fix(objectql): align SysMetadataRepository with existing sys_metadata schema (ADR-0008 PR-10d.2)

Discovery from the PR-10d.2 audit: the production sys_metadata table
(packages/platform-objects/src/metadata/sys-metadata.object.ts) already
has a `checksum: text(64)` column — exactly the right shape for sha256
hex — and a `version: number` column for monotonic increments. The
draft SysMetadataRepository was writing a non-existent `_hash` column,
which would silently drop or error against real drivers.

Changes:
- SysMetadataRepository now reads/writes `checksum` instead of `_hash`
- documented schema mapping in the file header:
  body → metadata · hash → checksum · version int → version
- updated the in-memory test fakes (both sys-metadata-repository.test.ts
  and layered-overlay-integration.test.ts) to mirror the new column name
- extended the dry-run probe (PR-10d.1) with two new checks:
  * checksum_missing — warning, eligible for lazy backfill
  * checksum_drift   — error, stored checksum disagrees with hashSpec(body)
- 3 new probe tests + report fields (needsBackfill, checksumDrift)

Result: zero DDL needed for PR-10d.3 cutover. Legacy rows with NULL
checksum will be backfilled on first put(). Objectql suite: 325/325 green.

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

Author: os-zhuang

.changeset/pr10d2-schema-alignment.md

@@ -0,0 +1,15 @@
+---
+"@objectstack/objectql": patch
+---
+
+fix(objectql): SysMetadataRepository reuses the existing `checksum` column
+instead of writing a non-existent `_hash` column (ADR-0008 PR-10d.2). The
+production `sys_metadata` schema (`packages/platform-objects`) already
+ships with `checksum: text(64)` — perfect for sha256 hex — and `version:
+number` for the monotonic counter. No DDL migration is required for
+PR-10d.3 cutover; legacy rows with NULL checksum will be lazily
+backfilled on first put().
+
+Also extends the PR-10d.1 dry-run probe with two new checks
+(`checksum_missing` warning, `checksum_drift` error) and three additional
+tests, taking objectql to 325/325 green.

packages/objectql/scripts/dry-run-hash-compat.ts

@@ -38,6 +38,11 @@ export interface LegacyMetadataRow {
     metadata?: string | null;
     state?: string;
     version?: number | null;
+    /**
+     * Legacy `checksum` column (sha256 hex). PR-10d.2 reuses this column
+     * as the optimistic-locking token; pre-PR-10d rows have `null`.
+     */
+    checksum?: string | null;
     [k: string]: unknown;
 }
 
@@ -49,7 +54,9 @@ export interface RowFinding {
         | 'non_object_body'
         | 'unstable_hash'
         | 'missing_metadata'
-        | 'duplicate_overlay_key';
+        | 'duplicate_overlay_key'
+        | 'checksum_drift'
+        | 'checksum_missing';
     detail: string;
 }
 
@@ -59,6 +66,10 @@ export interface DryRunReport {
     findings: RowFinding[];
     typeDistribution: Record<string, number>;
     duplicateKeys: string[];
+    /** Rows where `checksum` is NULL — eligible for lazy backfill on first write. */
+    needsBackfill: number;
+    /** Rows where stored `checksum` disagrees with recomputed `hashSpec(body)`. */
+    checksumDrift: number;
     compatible: boolean;
 }
 
@@ -71,6 +82,8 @@ export function runDryRun(rows: LegacyMetadataRow[]): DryRunReport {
     const seen = new Map<string, LegacyMetadataRow>();
     const duplicateKeys = new Set<string>();
     let okRows = 0;
+    let needsBackfill = 0;
+    let checksumDrift = 0;
 
     for (const row of rows) {
         const tag = {
@@ -146,7 +159,31 @@ export function runDryRun(rows: LegacyMetadataRow[]): DryRunReport {
             continue;
         }
 
-        // 5. Duplicate (type, name, organization_id) — would break the unique
+        // 5. Checksum reconciliation (PR-10d.2). The repository uses the
+        //    `checksum` column as the optimistic-lock token. Pre-PR-10d
+        //    rows have `null`. Eligible for lazy backfill on next write.
+        //    If non-null, it MUST equal hashSpec(body) — otherwise legacy
+        //    code wrote a checksum we can't reproduce.
+        if (row.checksum == null) {
+            needsBackfill += 1;
+            findings.push({
+                row: tag,
+                severity: 'warning',
+                code: 'checksum_missing',
+                detail: 'legacy row with NULL checksum — will be backfilled on first put()',
+            });
+        } else if (row.checksum !== h1) {
+            checksumDrift += 1;
+            findings.push({
+                row: tag,
+                severity: 'error',
+                code: 'checksum_drift',
+                detail: `stored checksum ${row.checksum} != recomputed ${h1}`,
+            });
+            continue;
+        }
+
+        // 6. Duplicate (type, name, organization_id) — would break the unique
         //    overlay invariant. Only count active rows.
         if (row.state === 'active' && row.type && row.name) {
             const key = `${row.type}|${row.name}|${row.organization_id ?? '__env__'}`;
@@ -164,7 +201,7 @@ export function runDryRun(rows: LegacyMetadataRow[]): DryRunReport {
             seen.set(key, row);
         }
 
-        // 6. Distribution.
+        // 7. Distribution.
         if (row.type) {
             typeDistribution[row.type] = (typeDistribution[row.type] ?? 0) + 1;
         }
@@ -177,6 +214,8 @@ export function runDryRun(rows: LegacyMetadataRow[]): DryRunReport {
         findings,
         typeDistribution,
         duplicateKeys: Array.from(duplicateKeys),
+        needsBackfill,
+        checksumDrift,
         compatible: findings.every((f) => f.severity !== 'error'),
     };
 }
@@ -191,6 +230,8 @@ export function formatReport(report: DryRunReport): string {
     lines.push(`Total rows:        ${report.totalRows}`);
     lines.push(`OK rows:           ${report.okRows}`);
     lines.push(`Findings:          ${report.findings.length}`);
+    lines.push(`Needs backfill:    ${report.needsBackfill} (NULL checksum)`);
+    lines.push(`Checksum drift:    ${report.checksumDrift}`);
     lines.push(`Compatible:        ${report.compatible ? 'YES ✅' : 'NO ❌'}`);
     lines.push('');
     lines.push('## Type distribution');

packages/objectql/src/dry-run-hash-compat.test.ts

@@ -1,6 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, expect, it } from 'vitest';
+import { hashSpec } from '@objectstack/metadata-core';
 import { runDryRun, type LegacyMetadataRow } from '../scripts/dry-run-hash-compat';
 
 /**
@@ -13,13 +14,8 @@ import { runDryRun, type LegacyMetadataRow } from '../scripts/dry-run-hash-compa
  * or dashboard body. Shapes vary in nesting, key order, locale strings, etc.
  */
 
-const validView = (overrides: Record<string, unknown> = {}) => ({
-    id: 'r1',
-    type: 'view',
-    name: 'case_grid',
-    organization_id: 'org_alpha',
-    state: 'active',
-    metadata: JSON.stringify({
+const validView = (overrides: Record<string, unknown> = {}): LegacyMetadataRow => {
+    const body = {
         name: 'case_grid',
         type: 'grid',
         label: 'Cases',
@@ -28,8 +24,17 @@ const validView = (overrides: Record<string, unknown> = {}) => ({
             { field: 'title', width: 240 },
         ],
         ...overrides,
-    }),
-});
+    };
+    return {
+        id: 'r1',
+        type: 'view',
+        name: 'case_grid',
+        organization_id: 'org_alpha',
+        state: 'active',
+        metadata: JSON.stringify(body),
+        checksum: hashSpec(body),
+    };
+};
 
 describe('runDryRun — happy path', () => {
     it('returns compatible:true for a clean snapshot', () => {
@@ -57,21 +62,25 @@ describe('runDryRun — happy path', () => {
         // Production code does `JSON.stringify(item)` which preserves insertion
         // order. Different writers produce different orderings. canonicalize()
         // must absorb this.
+        const bodyA = { z: 1, a: 2, m: { y: 9, b: 8 } };
+        const bodyB = { a: 2, m: { b: 8, y: 9 }, z: 1 };
         const a: LegacyMetadataRow = {
             id: 'r1',
             type: 'view',
             name: 'case_grid',
             organization_id: 'org_alpha',
             state: 'active',
-            metadata: JSON.stringify({ z: 1, a: 2, m: { y: 9, b: 8 } }),
+            metadata: JSON.stringify(bodyA),
+            checksum: hashSpec(bodyA),
         };
         const b: LegacyMetadataRow = {
             id: 'r2',
             type: 'view',
             name: 'case_kanban',
             organization_id: 'org_alpha',
             state: 'active',
-            metadata: JSON.stringify({ a: 2, m: { b: 8, y: 9 }, z: 1 }),
+            metadata: JSON.stringify(bodyB),
+            checksum: hashSpec(bodyB),
         };
         const report = runDryRun([a, b]);
         expect(report.compatible).toBe(true);
@@ -189,12 +198,55 @@ describe('runDryRun — error classification', () => {
     });
 });
 
+describe('runDryRun — checksum reconciliation (PR-10d.2)', () => {
+    it('warns (does not fail) when legacy row has NULL checksum', () => {
+        const report = runDryRun([
+            { ...validView(), checksum: null },
+        ]);
+        expect(report.compatible).toBe(true);    // warning, not error
+        expect(report.needsBackfill).toBe(1);
+        expect(report.findings).toHaveLength(1);
+        expect(report.findings[0].code).toBe('checksum_missing');
+        expect(report.findings[0].severity).toBe('warning');
+    });
+
+    it('accepts row whose stored checksum matches recomputed hashSpec(body)', () => {
+        const body = { name: 'case_grid', type: 'grid', label: 'Cases' };
+        const report = runDryRun([
+            {
+                id: 'r1',
+                type: 'view',
+                name: 'case_grid',
+                organization_id: 'org_alpha',
+                state: 'active',
+                metadata: JSON.stringify(body),
+                checksum: hashSpec(body),
+            },
+        ]);
+        expect(report.compatible).toBe(true);
+        expect(report.needsBackfill).toBe(0);
+        expect(report.checksumDrift).toBe(0);
+        expect(report.findings).toHaveLength(0);
+    });
+
+    it('flags drift when stored checksum disagrees with recomputed hash', () => {
+        const report = runDryRun([
+            { ...validView(), checksum: 'sha256:deadbeef' },
+        ]);
+        expect(report.compatible).toBe(false);
+        expect(report.checksumDrift).toBe(1);
+        expect(report.findings[0].code).toBe('checksum_drift');
+    });
+});
+
 describe('runDryRun — boundary conditions', () => {
     it('handles empty snapshot', () => {
         const report = runDryRun([]);
         expect(report.compatible).toBe(true);
         expect(report.totalRows).toBe(0);
         expect(report.okRows).toBe(0);
+        expect(report.needsBackfill).toBe(0);
+        expect(report.checksumDrift).toBe(0);
     });
 
     it('handles row with deeply nested body', () => {

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

@@ -26,7 +26,7 @@ interface Row {
     name: string;
     organization_id: string | null;
     metadata: string;
-    _hash: string;
+    checksum: string;
     state: string;
     version: number;
 }

packages/objectql/src/sys-metadata-repository.test.ts

@@ -18,7 +18,7 @@ interface Row {
     name: string;
     organization_id: string | null;
     metadata: string;
-    _hash: string;
+    checksum: string;
     state: string;
     version: number;
     created_at: string;

packages/objectql/src/sys-metadata-repository.ts

@@ -23,7 +23,16 @@
  *     table yet; LISTEN/NOTIFY plumbing comes with PostgresRepository)
  *   - history() — emits empty AsyncIterable
  *   - branch ops (fork/merge)
- *   - hashSpec backfill for legacy rows missing `_hash`
+ *   - hashSpec backfill for legacy rows missing `checksum`
+ *
+ * Schema mapping (ADR-0008 PR-10d.2):
+ *   Repository concept      sys_metadata column
+ *   ─────────────────────── ───────────────────
+ *   body                  → metadata           (JSON string)
+ *   hash (sha256)         → checksum           (text(64))
+ *   monotonic version int → version            (number)
+ *   org isolation         → organization_id    (lookup)
+ *   actor                 → updated_by         (lookup, optional)
  *
  * Composition: PR-10c will compose
  *   `LayeredRepository([FileSystemRepository, SysMetadataRepository])`
@@ -150,7 +159,7 @@ export class SysMetadataRepository implements MetadataRepository {
     const existing = await this.engine.findOne('sys_metadata', {
       where: this.whereFor(ref),
     });
-    const existingHash: string | null = existing?._hash ?? null;
+    const existingHash: string | null = existing?.checksum ?? null;
     if (opts.parentVersion !== existingHash) {
       throw new ConflictError(this.fullRef(ref), opts.parentVersion, existingHash);
     }
@@ -170,7 +179,7 @@ export class SysMetadataRepository implements MetadataRepository {
       name: ref.name,
       organization_id: this.organizationId,
       metadata: JSON.stringify(body),
-      _hash: version,
+      checksum: version,
       state: 'active',
       version: (existing?.version ?? 0) + 1,
       updated_at: now,
@@ -223,7 +232,7 @@ export class SysMetadataRepository implements MetadataRepository {
       // (actual HEAD is null but caller supplied a non-null parentVersion).
       throw new ConflictError(this.fullRef(ref), opts.parentVersion, null);
     }
-    const existingHash: string | null = existing._hash ?? null;
+    const existingHash: string | null = existing.checksum ?? null;
     if (opts.parentVersion !== existingHash) {
       throw new ConflictError(this.fullRef(ref), opts.parentVersion, existingHash);
     }
@@ -396,7 +405,7 @@ export class SysMetadataRepository implements MetadataRepository {
   private rowToItem(ref: Pick<MetaRef, 'type' | 'name'>, row: any): MetadataItem {
     const body: Record<string, unknown> =
       typeof row.metadata === 'string' ? JSON.parse(row.metadata) : (row.metadata ?? {});
-    const hash: string = row._hash ?? hashSpec(body);
+    const hash: string = row.checksum ?? hashSpec(body);
     return {
       ref: this.fullRef(ref),
       body,