feat(objectql): PR-10d.3 — feature flag for repository write path

Introduces an opt-in path in ObjectStackProtocolImplementation.saveMetaItem
that writes overlay metadata through SysMetadataRepository.put instead of
the raw engine, so writes append to the change-log and emit HMR seq events.

Behavioural changes (all behind options.useRepositoryWritePath /
OBJECTSTACK_USE_REPOSITORY_WRITE_PATH=1):
- saveMetaItem request gained optional parentVersion (If-Match) and
  actor fields. ConflictError -> 409 metadata_conflict.
- Plural type aliases (views, dashboards, ...) normalized to singular
  before the repo's overlay-allowlist gate (rubber-duck #5).
- Object-registry mutation moved AFTER successful put() so a conflict
  does not leave the in-memory registry stale (rubber-duck #3 invariant
  test added).

Repo/test-fake fixes uncovered by rubber-duck review:
- SysMetadataRepository.put/delete now update/delete by row id because
  the engine's strict .update requires id or multi:true (rubber-duck #1).
- sys_metadata.checksum column widened from 64 -> 71 chars to hold the
  sha256: prefix produced by hashSpec() (rubber-duck #2).
- Three test fake engines extended to support both overlay-tuple and
  id-based where lookups.

333/333 objectql tests pass.

Deferred to PR-10d.4: REST plumbing for parentVersion/actor
(rubber-duck #6), race-window retry for omitted parentVersion
(rubber-duck #4), default flag flip + legacy path removal.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: os-zhuang

.changeset/pr10d3-feature-flag-repo-path.md

@@ -0,0 +1,20 @@
+---
+"@objectstack/objectql": minor
+"@objectstack/platform-objects": patch
+---
+
+PR-10d.3 — feature flag for `SysMetadataRepository.put` write path in `saveMetaItem`.
+
+- `ObjectStackProtocolImplementation` now accepts an `options.useRepositoryWritePath` flag
+  (also honored via `OBJECTSTACK_USE_REPOSITORY_WRITE_PATH=1`) that routes overlay writes
+  through `SysMetadataRepository.put`, appending to the change-log and emitting HMR `seq`.
+- `saveMetaItem` request grew optional `parentVersion` (If-Match) and `actor` fields.
+  `ConflictError` is mapped to a 409 `metadata_conflict` API error.
+- Plural metadata type aliases (`views`, `dashboards`, ...) are normalized to singular
+  before the repo's overlay-allowlist gate.
+- `SysMetadataRepository.put`/`delete` now update/delete by row `id` (the engine's
+  strict `.update` semantics require an id or `multi:true`).
+- `sys_metadata.checksum` column widened from 64 → 71 chars to hold the `"sha256:"`
+  prefix produced by `hashSpec()`.
+- Default behaviour unchanged: legacy raw-engine path remains until PR-10d.4 flips the
+  flag and removes it.

packages/objectql/src/layered-overlay-integration.test.ts

@@ -35,6 +35,15 @@ function makeFakeEngine() {
     const rows = new Map<string, Row>();
     const keyOf = (w: Record<string, unknown>) =>
         `${w.type}|${w.name}|${String(w.organization_id ?? 'null')}`;
+    const findRow = (w: Record<string, unknown>): { key: string; row: Row } | null => {
+        if (w.id !== undefined) {
+            for (const [k, r] of rows) if (r.id === w.id) return { key: k, row: r };
+            return null;
+        }
+        const k = keyOf(w);
+        const r = rows.get(k);
+        return r ? { key: k, row: r } : null;
+    };
     return {
         rows,
         async find(_t: string, opts: { where: Record<string, unknown> }) {
@@ -46,21 +55,24 @@ function makeFakeEngine() {
             );
         },
         async findOne(_t: string, opts: { where: Record<string, unknown> }) {
-            return rows.get(keyOf(opts.where)) ?? null;
+            return findRow(opts.where)?.row ?? null;
         },
         async insert(_t: string, data: Record<string, unknown>) {
             const row: Row = { id: `r_${rows.size + 1}`, ...(data as any) };
             rows.set(keyOf(data), row);
             return { id: row.id };
         },
         async update(_t: string, data: Record<string, unknown>, opts: { where: Record<string, unknown> }) {
-            const k = keyOf(opts.where);
-            const cur = rows.get(k)!;
-            rows.set(k, { ...cur, ...(data as any) });
-            return { id: cur.id };
+            const found = findRow(opts.where);
+            if (!found) return { id: null };
+            rows.set(found.key, { ...found.row, ...(data as any) });
+            return { id: found.row.id };
         },
         async delete(_t: string, opts: { where: Record<string, unknown> }) {
-            return { deleted: rows.delete(keyOf(opts.where)) ? 1 : 0 };
+            const found = findRow(opts.where);
+            if (!found) return { deleted: 0 };
+            rows.delete(found.key);
+            return { deleted: 1 };
         },
     };
 }

packages/objectql/src/protocol-save-meta-repo-path.test.ts

@@ -0,0 +1,255 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, expect, it } from 'vitest';
+import { hashSpec } from '@objectstack/metadata-core';
+import { ObjectStackProtocolImplementation } from './protocol';
+
+/**
+ * PR-10d.3 — repository write path behind a feature flag.
+ *
+ * These tests verify the new branch in `saveMetaItem` that routes through
+ * `SysMetadataRepository.put` when `useRepositoryWritePath` is on. We
+ * stub the engine surface that both the protocol and the repository touch:
+ * findOne / find / insert / update / delete on `sys_metadata`, plus a
+ * minimal registry (only consulted for `type === 'object'`).
+ */
+
+interface Row {
+    id: string;
+    type: string;
+    name: string;
+    organization_id: string | null;
+    state: string;
+    metadata: string;
+    checksum?: string;
+    version?: number;
+    updated_at?: string;
+    created_at?: string;
+}
+
+function keyOf(w: Record<string, unknown>) {
+    return `${w.type}|${w.name}|${w.organization_id ?? '__env__'}`;
+}
+
+function makeStubEngine() {
+    const rows = new Map<string, Row>();
+    let nextId = 0;
+    const findRow = (w: Record<string, unknown>): { key: string; row: Row } | null => {
+        if (w.id !== undefined) {
+            for (const [k, r] of rows) if (r.id === w.id) return { key: k, row: r };
+            return null;
+        }
+        const k = keyOf(w);
+        const r = rows.get(k);
+        return r ? { key: k, row: r } : null;
+    };
+    const engine: any = {
+        async findOne(_t: string, opts: { where: Record<string, unknown> }) {
+            return findRow(opts.where)?.row ?? null;
+        },
+        async find(_t: string, opts: { where: Record<string, unknown> }) {
+            return Array.from(rows.values()).filter((r) => {
+                if (opts.where.type && r.type !== opts.where.type) return false;
+                if (opts.where.organization_id !== undefined
+                    && r.organization_id !== opts.where.organization_id) return false;
+                if (opts.where.state && r.state !== opts.where.state) return false;
+                return true;
+            });
+        },
+        async insert(_t: string, data: Record<string, unknown>) {
+            nextId += 1;
+            const row = { id: `r_${nextId}`, ...(data as any) } as Row;
+            rows.set(keyOf(data), row);
+            return { id: row.id };
+        },
+        async update(_t: string, data: Record<string, unknown>, opts: { where: Record<string, unknown> }) {
+            const found = findRow(opts.where);
+            if (!found) return { id: null };
+            rows.set(found.key, { ...found.row, ...(data as any) });
+            return { id: found.row.id };
+        },
+        async delete(_t: string, opts: { where: Record<string, unknown> }) {
+            const found = findRow(opts.where);
+            if (!found) return { deleted: 0 };
+            rows.delete(found.key);
+            return { deleted: 1 };
+        },
+        registry: {
+            registerItem: () => {},
+            registerObject: () => {},
+        },
+    };
+    return { engine, rows };
+}
+
+describe('saveMetaItem — repository write path (PR-10d.3)', () => {
+    it('legacy path remains the default when no flag is passed', async () => {
+        const { engine, rows } = makeStubEngine();
+        const protocol = new ObjectStackProtocolImplementation(engine);
+        const result = await protocol.saveMetaItem({
+            type: 'view',
+            name: 'case_grid',
+            organizationId: 'org_alpha',
+            item: { name: 'case_grid', type: 'grid', label: 'Cases', columns: ['id', 'title'] },
+        });
+        expect(result.success).toBe(true);
+        // Legacy path does NOT set checksum / does NOT emit a seq.
+        expect((result as any).seq).toBeUndefined();
+        const row = Array.from(rows.values())[0];
+        expect(row.checksum).toBeUndefined();
+    });
+
+    it('repository path writes the checksum and surfaces seq', async () => {
+        const { engine, rows } = makeStubEngine();
+        const protocol = new ObjectStackProtocolImplementation(
+            engine, undefined, undefined, undefined,
+            { useRepositoryWritePath: true },
+        );
+        const body = { name: 'case_grid', type: 'grid', label: 'Cases', columns: ['id', 'title'] };
+        const result = await protocol.saveMetaItem({
+            type: 'view',
+            name: 'case_grid',
+            organizationId: 'org_alpha',
+            item: body,
+        });
+        expect(result.success).toBe(true);
+        expect((result as any).seq).toBe(1);
+        const row = Array.from(rows.values())[0];
+        expect(row.checksum).toBe(hashSpec(body));
+    });
+
+    it('repository path increments seq across writes and updates the body', async () => {
+        const { engine, rows } = makeStubEngine();
+        const protocol = new ObjectStackProtocolImplementation(
+            engine, undefined, undefined, undefined,
+            { useRepositoryWritePath: true },
+        );
+        const r1 = await protocol.saveMetaItem({
+            type: 'view', name: 'v', organizationId: 'org',
+            item: { name: 'view_one', type: 'grid', label: 'A', columns: ['id'] },
+        });
+        const r2 = await protocol.saveMetaItem({
+            type: 'view', name: 'v', organizationId: 'org',
+            item: { name: 'view_one', type: 'grid', label: 'B', columns: ['id'] },
+        });
+        expect((r1 as any).seq).toBe(1);
+        expect((r2 as any).seq).toBe(2);
+        const row = Array.from(rows.values())[0];
+        expect(JSON.parse(row.metadata).label).toBe('B');
+    });
+
+    it('repository path returns 409 on parentVersion mismatch', async () => {
+        const { engine } = makeStubEngine();
+        const protocol = new ObjectStackProtocolImplementation(
+            engine, undefined, undefined, undefined,
+            { useRepositoryWritePath: true },
+        );
+        // First write establishes a HEAD.
+        await protocol.saveMetaItem({
+            type: 'view', name: 'v', organizationId: 'org',
+            item: { name: 'view_one', type: 'grid', label: 'A', columns: ['id'] },
+        });
+        // Second write with an explicit stale parentVersion → conflict.
+        await expect(
+            protocol.saveMetaItem({
+                type: 'view', name: 'v', organizationId: 'org',
+                item: { name: 'view_one', type: 'grid', label: 'B', columns: ['id'] },
+                parentVersion: 'sha256:notTheCurrentHead',
+            }),
+        ).rejects.toMatchObject({
+            code: 'metadata_conflict',
+            status: 409,
+        });
+    });
+
+    it('repository path no-ops when body is identical (idempotent put)', async () => {
+        const { engine, rows } = makeStubEngine();
+        const protocol = new ObjectStackProtocolImplementation(
+            engine, undefined, undefined, undefined,
+            { useRepositoryWritePath: true },
+        );
+        const body = { name: 'view_one', type: 'grid', label: 'A', columns: ['id'] };
+        const r1 = await protocol.saveMetaItem({
+            type: 'view', name: 'v', organizationId: 'org', item: body,
+        });
+        const r2 = await protocol.saveMetaItem({
+            type: 'view', name: 'v', organizationId: 'org', item: body,
+        });
+        // No new seq allocated for an identical body.
+        expect((r1 as any).seq).toBe(1);
+        expect((r2 as any).seq).toBe(1);
+        // Still only one row in the store.
+        expect(rows.size).toBe(1);
+    });
+
+    it('env-wide overlays (organizationId omitted) use a separate repo bucket', async () => {
+        const { engine, rows } = makeStubEngine();
+        const protocol = new ObjectStackProtocolImplementation(
+            engine, undefined, undefined, undefined,
+            { useRepositoryWritePath: true },
+        );
+        await protocol.saveMetaItem({
+            type: 'view', name: 'v',
+            item: { name: 'view_one', type: 'grid', label: 'env-wide', columns: ['id'] },
+        });
+        await protocol.saveMetaItem({
+            type: 'view', name: 'v', organizationId: 'org_alpha',
+            item: { name: 'view_one', type: 'grid', label: 'org_alpha', columns: ['id'] },
+        });
+        // Two rows: one with organization_id=null, one with org_alpha.
+        expect(rows.size).toBe(2);
+        const orgs = Array.from(rows.values()).map((r) => r.organization_id).sort();
+        expect(orgs).toEqual([null, 'org_alpha']);
+    });
+
+    it('plural type (e.g. "views") is normalized to singular before the repo gate (rubber-duck #5)', async () => {
+        const { engine, rows } = makeStubEngine();
+        const protocol = new ObjectStackProtocolImplementation(
+            engine, undefined, undefined, undefined,
+            { useRepositoryWritePath: true },
+        );
+        // 'views' must succeed — the repo only knows the singular form, so
+        // without normalization this would throw 403 not_overridable.
+        const result = await protocol.saveMetaItem({
+            type: 'views',
+            name: 'case_grid',
+            organizationId: 'org',
+            item: { name: 'case_grid', type: 'grid', label: 'OK', columns: ['id'] },
+        });
+        expect(result.success).toBe(true);
+        const row = Array.from(rows.values())[0];
+        // The stored row keeps the SINGULAR type since the repo writes it.
+        expect(row.type).toBe('view');
+    });
+
+    it('on ConflictError the overlay row body is unchanged (rubber-duck #3 invariant)', async () => {
+        const { engine, rows } = makeStubEngine();
+        const protocol = new ObjectStackProtocolImplementation(
+            engine, undefined, undefined, undefined,
+            { useRepositoryWritePath: true },
+        );
+
+        // Establish a HEAD overlay.
+        await protocol.saveMetaItem({
+            type: 'view',
+            name: 'cases',
+            organizationId: 'org_x',
+            item: { name: 'cases', type: 'grid', label: 'Original', columns: ['id'] },
+        });
+        const beforeBody = (Array.from(rows.values())[0] as any).metadata;
+
+        // Stale parentVersion → 409. The stored body must not change.
+        await expect(
+            protocol.saveMetaItem({
+                type: 'view',
+                name: 'cases',
+                organizationId: 'org_x',
+                item: { name: 'cases', type: 'grid', label: 'Mutated (should not land)', columns: ['id'] },
+                parentVersion: 'sha256:stale',
+            }),
+        ).rejects.toMatchObject({ code: 'metadata_conflict', status: 409 });
+
+        const afterBody = (Array.from(rows.values())[0] as any).metadata;
+        expect(afterBody).toBe(beforeBody);
+    });
+});