test(metadata-protocol,cli): seed the sequences fixtures with the key the platform actually stores

CI caught the #12394 handoff writing a SECOND counter row for one logical
sequence, on live MySQL and on SQLite alike. Root cause is the fixtures, not
the repair: both hand-seeded `key_hash` as an invented string (`'h1'`/`'h2'`
and `'h_global'`/`'h_org'`), which was inert for as long as the repair
addressed counter rows by `(object, field, tenant_id)`. #12394 addresses the
destination row by `key_hash` — the table's only key — so an invented hash
describes a table no install can hold: the org row reads ABSENT and a second
row is inserted beside it.

Measured: the driver stores `key_hash = sha256(object US tenant US field US
scope)` for every row it writes, and `ensureSequencesKeyHashShape` recomputes
the same hash for every legacy row it migrates.

- cli: take the hash from the driver's own `sequenceKeyHash`, so the fixture is
  the same bytes the only production writer would have written and cannot drift.
- metadata-protocol live-MySQL: spell the derivation independently (this package
  does not depend on driver-sql), making it a third spelling and therefore a pin
  on it; give `key_hash` its real PRIMARY KEY.
- metadata-protocol unit: new #12394 suite over a KEYED store that answers the
  probe by its parameter and enforces the primary key. The INSERT-vs-UPDATE
  decision had no unit coverage keyed by a real hash — every existing fake
  matched on statement shape and handed back its one row for any key.

`sequenceKeyHash` is exported from the module for that suite; it is NOT
re-exported from the package index, so the published surface is unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W6HFzyH98W1YaQXhJUJt6o

Author: claude

packages/cli/src/utils/platform-migrations-arming.integration.test.ts

@@ -149,9 +149,24 @@ async function writeDamagedInstall(): Promise<void> {
     t.bigInteger('last_value').notNullable().defaultTo(0);
     t.timestamp('updated_at');
   });
+  // [#12394] `key_hash` is DERIVED, never invented. It used to be seeded here as
+  // the placeholders `'h1'`/`'h2'`, which was harmless only for as long as the
+  // repair addressed counter rows by `(object, field, tenant_id)`: nothing read
+  // the column, so any string did. #12394's handoff addresses the destination
+  // row by `key_hash` — the key the table is actually keyed on — so a fixture
+  // carrying an invented hash describes a table the platform cannot produce, and
+  // the repair correctly reads the org row as ABSENT and inserts a SECOND one.
+  //
+  // Taking the hash from the driver's own `sequenceKeyHash` rather than
+  // re-spelling it here is the point: this fixture is now the same bytes the
+  // only production writer of this table would have written, and it cannot drift
+  // from it. `ensureSequencesKeyHashShape` recomputes the same hash for every
+  // legacy row it migrates, so this is the shape of every real install.
+  const keyHash = (object: string, tenantId: string, field: string, scope = ''): string =>
+    (seed as any).sequenceKeyHash(object, tenantId, field, scope);
   await k(SEQUENCES_TABLE).insert([
-    { key_hash: 'h1', object: 'crm_case', tenant_id: GLOBAL_TENANT, field: 'case_number', scope: '', last_value: SEEDED_LAST_VALUE },
-    { key_hash: 'h2', object: 'crm_case', tenant_id: ORG_ID, field: 'case_number', scope: '', last_value: 1 },
+    { key_hash: keyHash('crm_case', GLOBAL_TENANT, 'case_number'), object: 'crm_case', tenant_id: GLOBAL_TENANT, field: 'case_number', scope: '', last_value: SEEDED_LAST_VALUE },
+    { key_hash: keyHash('crm_case', ORG_ID, 'case_number'), object: 'crm_case', tenant_id: ORG_ID, field: 'case_number', scope: '', last_value: 1 },
   ]);
   await seed.disconnect();
 }

packages/metadata-protocol/src/migrations/seed-tenancy-backfill.live-mysql.test.ts

@@ -46,6 +46,7 @@
  */
 
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { createHash } from 'node:crypto';
 import mysql from 'mysql2/promise';
 import {
   backfillSeedTenancy,
@@ -68,6 +69,32 @@ const DB = currentLiveMysqlDatabase();
 const OBJECT = 'os9381_case';
 const FIELD = 'case_number';
 
+/**
+ * The row key of `_objectstack_sequences`, spelled the way its only production
+ * writer spells it (#12394).
+ *
+ * This fixture used to seed `key_hash` as the placeholders `'h_global'` and
+ * `'h_org'`. That was invisible for as long as the repair addressed counter rows
+ * by `(object, field, tenant_id)` — nothing read the column, so any string did.
+ * #12394's handoff addresses the destination row by `key_hash`, which is the key
+ * the table is actually keyed on, so an invented hash describes a table no
+ * install can hold: the repair reads the organization row as ABSENT and inserts
+ * a SECOND counter for one logical sequence.
+ *
+ * Spelled here rather than imported because `metadata-protocol` does not depend
+ * on `driver-sql` — which makes this a THIRD independent spelling of the same
+ * derivation, and therefore a pin on it: a separator or field-order change in
+ * `seed-tenancy-backfill.ts` stops matching these rows and this suite goes red.
+ * The separator is the ASCII unit separator, written as the escape \u001f and
+ * never as a raw control byte — the same discipline the module and the driver
+ * both keep.
+ */
+function sequenceKeyHash(object: string, tenantId: string, field: string, scope: string): string {
+  return createHash('sha256')
+    .update(`${object}\u001f${tenantId}\u001f${field}\u001f${scope}`)
+    .digest('hex');
+}
+
 if (!MYSQL_URL && EXPECT_LIVE) {
   describe('#9381 live MySQL', () => {
     it('OS_TEST_MYSQL_URL must be set — this runner declared it provisioned a server', () => {
@@ -113,9 +140,18 @@ describe.skipIf(!MYSQL_URL)('#9381 seed-tenancy backfill on a LIVE MySQL', () =>
     // Column names spelled the way the driver's own `createSequencesTable`
     // spells them; `last_value` is quoted here for the same reason the migration
     // has to quote it (see the reserved-word assertion below).
+    //
+    // [#12394] `key_hash` carries its real PRIMARY KEY. The driver declares it
+    // `.notNullable().primary()`, and it is the ONLY key this table has — no
+    // unique index stands behind `(object, tenant_id, field, scope)`. Seeding it
+    // as a plain column let a repair that wrote a SECOND row for one logical
+    // counter land quietly as an extra row instead of an `ER_DUP_ENTRY`; with
+    // the real key here, that defect can only ever be an error on the two
+    // dialects that enforce it.
     await conn.query(
       `CREATE TABLE \`${SEQUENCES_TABLE}\` (` +
-        '`key_hash` VARCHAR(64), `object` VARCHAR(64), `tenant_id` VARCHAR(64), ' +
+        '`key_hash` VARCHAR(64) NOT NULL PRIMARY KEY, `object` VARCHAR(64), ' +
+        '`tenant_id` VARCHAR(64), ' +
         '`field` VARCHAR(64), `scope` VARCHAR(255) NOT NULL DEFAULT \'\', ' +
         '`last_value` INT, `updated_at` DATETIME(3))',
     );
@@ -127,8 +163,12 @@ describe.skipIf(!MYSQL_URL)('#9381 seed-tenancy backfill on a LIVE MySQL', () =>
     await conn.query("INSERT INTO `sys_organization` (`id`) VALUES ('org_live')");
     await conn.query(
       `INSERT INTO \`${SEQUENCES_TABLE}\` (\`key_hash\`, \`object\`, \`tenant_id\`, \`field\`, \`last_value\`) ` +
-        `VALUES ('h_global', '${OBJECT}', '${GLOBAL_TENANT}', '${FIELD}', 38), ` +
-        `('h_org', '${OBJECT}', 'org_live', '${FIELD}', 4)`,
+        `VALUES (?, '${OBJECT}', '${GLOBAL_TENANT}', '${FIELD}', 38), ` +
+        `(?, '${OBJECT}', 'org_live', '${FIELD}', 4)`,
+      [
+        sequenceKeyHash(OBJECT, GLOBAL_TENANT, FIELD, ''),
+        sequenceKeyHash(OBJECT, 'org_live', FIELD, ''),
+      ],
     );
     // The card's own repro: seeded rows carry NULL, API rows carry the org, and
     // CASE-00001/2 were minted on BOTH sides.

packages/metadata-protocol/src/migrations/seed-tenancy-backfill.test.ts

@@ -43,6 +43,7 @@ import {
   buildCounterInsertSql,
   buildGlobalCounterDeleteByKeyHashSql,
   buildSequencesPresenceSql,
+  sequenceKeyHash,
   SEQUENCES_TABLE,
   GLOBAL_TENANT,
   ORGANIZATION_FIELD,
@@ -361,6 +362,157 @@ describe('#9381 dialect-aware statement text', () => {
   });
 });
 
+/**
+ * #12394 — the counter handoff, against a store that is KEYED.
+ *
+ * ## The hole this closes
+ *
+ * Every other fake seam in this file answers by STATEMENT SHAPE: it matches on
+ * `sql.includes('"key_hash" = ?')` and hands back the one row it is holding,
+ * without ever reading the parameter. A fake like that models a database in
+ * which every key addresses the same row — so the one decision this handoff
+ * makes, INSERT-vs-UPDATE keyed by `key_hash`, is answered correctly no matter
+ * what key the migration asks with. The branch cannot fail here, which is the
+ * same thing as saying it is not covered.
+ *
+ * It was not covered anywhere else at unit speed either: the UPDATE branch (an
+ * organization-scoped row that ALREADY exists) reached CI only through two
+ * integration fixtures, and both of them seeded `key_hash` as an invented string
+ * — `'h1'`/`'h2'` and `'h_global'`/`'h_org'`. Those were inert for as long as the
+ * repair addressed counter rows by `(object, field, tenant_id)`. The moment it
+ * began addressing them by `key_hash`, both fixtures described a table no
+ * install can hold, the destination row read as ABSENT, and the repair inserted
+ * a SECOND counter for one logical sequence — on SQLite and on MySQL alike, so
+ * this was never a dialect gap.
+ *
+ * ## What makes this fixture able to fail
+ *
+ * It is a real keyed store: rows live in a `Map` under their own `key_hash`, the
+ * probe answers by the parameter it was given, and the INSERT REFUSES a key that
+ * is already present — because `key_hash` is the table's PRIMARY KEY and its
+ * only key (no unique index stands behind `(object, tenant_id, field, scope)`).
+ * A fake looser than the producer is how a dead write path ships green; this one
+ * is exactly as strict. A repair that wrote its mark under a key other than the
+ * one it probed now ends with two rows or a refused write, and both are red.
+ */
+describe('#12394 the counter handoff writes the row the driver will read', () => {
+  const OBJECT = 'crm_case';
+  const FIELD = 'case_number';
+  const ORG = 'org_a';
+
+  /** A `_objectstack_sequences` that is keyed the way the real table is keyed. */
+  function keyedSequences(seed: Array<Record<string, unknown>>) {
+    const rows = new Map<string, Record<string, unknown>>();
+    for (const row of seed) rows.set(String(row.key_hash), { ...row });
+    const exec = async (sql: string, params: unknown[] = []): Promise<unknown> => {
+      if (sql.includes('WHERE 1 = 0')) return []; // presence + key-shape probes
+      if (sql.includes('LEFT JOIN')) {
+        return [
+          { object: OBJECT, field: FIELD, global_last_value: 38, organization_last_value: 1 },
+        ];
+      }
+      if (sql.includes(ORGANIZATION_TABLE)) return [{ id: ORG }];
+      if (sql.includes('rows_holding')) return [];
+      if (sql.startsWith('INSERT') && sql.includes(SEQUENCES_TABLE)) {
+        const key = String(params[0]);
+        // The PRIMARY KEY, enforced. Without this the fixture would absorb the
+        // very defect it exists to catch.
+        if (rows.has(key)) throw new Error(`duplicate key value violates the primary key: ${key}`);
+        rows.set(key, {
+          key_hash: key,
+          object: String(params[1]),
+          tenant_id: String(params[2]),
+          field: String(params[3]),
+          scope: String(params[4]),
+          last_value: Number(params[5]),
+        });
+        return [];
+      }
+      if (sql.startsWith('UPDATE') && sql.includes(SEQUENCES_TABLE)) {
+        const row = rows.get(String(params[1]));
+        if (row) row.last_value = Number(params[0]);
+        return [];
+      }
+      if (sql.startsWith('DELETE') && sql.includes(SEQUENCES_TABLE)) {
+        rows.delete(String(params[0]));
+        return [];
+      }
+      if (sql.startsWith('UPDATE') || sql.startsWith('DELETE')) return []; // the stamp
+      // The org-scoped row, addressed by the key the caller actually asked with.
+      if (sql.includes('"key_hash" = ?')) {
+        const row = rows.get(String(params[0]));
+        return row ? [{ last_value: row.last_value }] : [];
+      }
+      // The `__global__` rows for one object/field — one per scope.
+      if (sql.includes('tenant_id')) {
+        return [...rows.values()].filter((r) => r.tenant_id === GLOBAL_TENANT);
+      }
+      return [];
+    };
+    return { rows, seam: { exec } as never };
+  }
+
+  const globalRow = {
+    key_hash: sequenceKeyHash(OBJECT, GLOBAL_TENANT, FIELD, ''),
+    object: OBJECT,
+    tenant_id: GLOBAL_TENANT,
+    field: FIELD,
+    scope: '',
+    last_value: 38,
+  };
+
+  it('[first boot] creates the organization row at the merged mark, then retires __global__', async () => {
+    const { rows, seam } = keyedSequences([globalRow]);
+    const result = await backfillSeedTenancy(seam);
+
+    expect(result.status).toBe('applied');
+    // One row, under the key the DRIVER will compute — not under any key.
+    expect([...rows.keys()]).toEqual([sequenceKeyHash(OBJECT, ORG, FIELD, '')]);
+    expect([...rows.values()][0]!.last_value).toBe(38);
+  });
+
+  it('[the CI regression] an existing organization row is RAISED, never duplicated', async () => {
+    // The shape both integration fixtures were really in, spelled with the key
+    // the platform actually stores. A repair that probes with one key and writes
+    // under another leaves two rows here, which is what CI caught.
+    const { rows, seam } = keyedSequences([
+      globalRow,
+      {
+        key_hash: sequenceKeyHash(OBJECT, ORG, FIELD, ''),
+        object: OBJECT,
+        tenant_id: ORG,
+        field: FIELD,
+        scope: '',
+        last_value: 1,
+      },
+    ]);
+    const result = await backfillSeedTenancy(seam);
+
+    expect(result.status).toBe('applied');
+    expect(rows.size).toBe(1);
+    expect([...rows.values()][0]).toMatchObject({ tenant_id: ORG, last_value: 38 });
+  });
+
+  it('[never lowered] an organization row already ahead of __global__ keeps its own mark', async () => {
+    const { rows, seam } = keyedSequences([
+      globalRow,
+      {
+        key_hash: sequenceKeyHash(OBJECT, ORG, FIELD, ''),
+        object: OBJECT,
+        tenant_id: ORG,
+        field: FIELD,
+        scope: '',
+        last_value: 91,
+      },
+    ]);
+    await backfillSeedTenancy(seam);
+
+    expect(rows.size).toBe(1);
+    // The merge rule is the greater of the two COUNTERS, never the data max.
+    expect([...rows.values()][0]!.last_value).toBe(91);
+  });
+});
+
 /**
  * #9451 — the durable receipt.
  *

packages/metadata-protocol/src/migrations/seed-tenancy-backfill.ts

@@ -709,7 +709,12 @@ export function buildGlobalCounterDeleteSql(client?: string): string {
  *
  * The separator is the ASCII unit separator, spelled as the escape \u001f and never as a raw control byte — the driver spells it the same way.
  */
-function sequenceKeyHash(object: string, tenantId: string, field: string, scope: string): string {
+export function sequenceKeyHash(
+  object: string,
+  tenantId: string,
+  field: string,
+  scope: string,
+): string {
   return createHash('sha256')
     .update(`${object}\u001f${tenantId}\u001f${field}\u001f${scope}`)
     .digest('hex');