@stigmer/server 3.38.3 → 3.39.0

package/src/store/sqlite/__tests__/migrations.test.ts

@@ -11,7 +11,11 @@
  * and leaves every other row's bytes as they were; a row it cannot decode
  * fails the step and leaves the database at v9. v11 adds the list index's
  * schema only, and a Go-written row of a declared kind is derived by the
- * store's reconciliation at open and read through the index.
+ * store's reconciliation at open and read through the index. v12 creates
+ * the organization-slug ledger and fills it: every live organization
+ * unretired, every organization a surviving scoped row names with none live
+ * retired, across keyset pages; a scoped row it cannot decode fails the
+ * step and leaves the database at v11 with no ledger.
  */
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -35,9 +39,11 @@ import { SqliteStore } from "../store.js";
 import {
   CURRENT_SCHEMA_VERSION,
   SCHEMA_VERSION_10,
+  SCHEMA_VERSION_12,
   getSchemaVersion,
   runMigrations,
 } from "../migrations.js";
+import { HISTORY_PAGE_SIZE } from "../../organization-slug-history.js";
 import { PUBLIC_ROW_KINDS_AT_RETIREMENT } from "../../public-visibility-retired.js";
 import { materializeGoFixture } from "./support.js";
 
@@ -85,6 +91,7 @@ describe("fresh database", () => {
       "signal_dedupe",
       "oauth_grant",
       "pending_oauth_state",
+      "organization_slugs",
     ]) {
       expect(tables, `table ${expected} should exist`).toContain(expected);
     }
@@ -100,7 +107,7 @@ describe("fresh database", () => {
       .prepare(`SELECT version FROM schema_version ORDER BY version`)
       .all() as Array<{ version: number }>;
     expect(rows.map((row) => row.version)).toEqual([
-      1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
+      1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12,
     ]);
   });
 
@@ -525,16 +532,15 @@ describe("v10: the retired public level leaves every row", () => {
   });
 
   it("a row of a kind outside the frozen table is never decoded", () => {
-    const { dbPath, db: setup } = v9Database();
+    const { db } = v9Database();
+    cleanups.push(() => db.close());
     // Bytes no schema decodes, under a kind the level never applied to.
-    insert(setup, "session", "ses_opaque", new Uint8Array([0xff, 0xff]));
-    setup.close();
+    // The chain stops at v10: v12 reads every organization-scoped row, so
+    // a later step would refuse these bytes for its own reason.
+    insert(db, "session", "ses_opaque", new Uint8Array([0xff, 0xff]));
 
-    const store = SqliteStore.open(dbPath);
-    cleanups.push(() => store.close());
-    const db = new DatabaseSync(dbPath);
-    cleanups.push(() => db.close());
-    expect(getSchemaVersion(db)).toBe(CURRENT_SCHEMA_VERSION);
+    runMigrations(db, SCHEMA_VERSION_10);
+    expect(getSchemaVersion(db)).toBe(SCHEMA_VERSION_10);
     expect(row(db, "session", "ses_opaque").data).toEqual(
       new Uint8Array([0xff, 0xff]),
     );
@@ -560,3 +566,126 @@ describe("v10: the retired public level leaves every row", () => {
     expect(row(db, "agent", "agt_public").data).toEqual(publicBytes);
   });
 });
+
+describe("v12: the organization-slug ledger records every slug taken before it", () => {
+  /** A v11 database: the chain replayed up to the step before v12. */
+  function v11Database(): { dbPath: string; db: DatabaseSync } {
+    const dbPath = tempDbPath();
+    const setup = new DatabaseSync(dbPath);
+    runMigrations(setup, SCHEMA_VERSION_12 - 1);
+    expect(getSchemaVersion(setup)).toBe(SCHEMA_VERSION_12 - 1);
+    return { dbPath, db: setup };
+  }
+
+  function agentNaming(id: string, org: string): Uint8Array {
+    return toBinary(
+      AgentSchema,
+      create(AgentSchema, {
+        metadata: { id, name: id, slug: id, org },
+        spec: { instructions: "a conformant instruction body" },
+      }),
+    );
+  }
+
+  function sessionNaming(id: string, org: string): Uint8Array {
+    return toBinary(
+      SessionSchema,
+      create(SessionSchema, { metadata: { id, name: id, slug: id, org } }),
+    );
+  }
+
+  function insert(
+    db: DatabaseSync,
+    kind: string,
+    id: string,
+    data: Uint8Array,
+  ): void {
+    db.prepare(`INSERT INTO resources (kind, id, data) VALUES (?, ?, ?)`).run(
+      kind,
+      id,
+      data,
+    );
+  }
+
+  function ledger(db: DatabaseSync): Array<{ slug: string; retired: number }> {
+    return db
+      .prepare(
+        `SELECT slug, retired_at IS NOT NULL AS retired FROM organization_slugs ORDER BY slug`,
+      )
+      .all() as Array<{ slug: string; retired: number }>;
+  }
+
+  it("records every live organization unretired and every organization a surviving row names with none live retired", () => {
+    const { dbPath, db: setup } = v11Database();
+    insert(setup, "organization", "acme", new Uint8Array([0x00]));
+    insert(setup, "agent", "agt_live", agentNaming("agt_live", "acme"));
+    insert(setup, "agent", "agt_gone", agentNaming("agt_gone", "deleted-one"));
+    insert(
+      setup,
+      "session",
+      "ses_gone",
+      sessionNaming("ses_gone", "deleted-two"),
+    );
+    insert(setup, "agent", "agt_orphan", agentNaming("agt_orphan", ""));
+    // A kind outside the table is never decoded, whatever it holds.
+    insert(
+      setup,
+      "identity_account",
+      "ida_opaque",
+      new Uint8Array([0xff, 0xff]),
+    );
+    setup.close();
+
+    const store = SqliteStore.open(dbPath);
+    cleanups.push(() => store.close());
+    const db = new DatabaseSync(dbPath);
+    cleanups.push(() => db.close());
+    expect(getSchemaVersion(db)).toBe(CURRENT_SCHEMA_VERSION);
+    expect(ledger(db)).toEqual([
+      { slug: "acme", retired: 0 },
+      { slug: "deleted-one", retired: 1 },
+      { slug: "deleted-two", retired: 1 },
+    ]);
+  });
+
+  it("reads a kind across keyset pages, missing no row past the first page", () => {
+    const { dbPath, db: setup } = v11Database();
+    const rows = HISTORY_PAGE_SIZE + 2;
+    for (let i = 0; i < rows; i++) {
+      const id = `agt_${String(i).padStart(4, "0")}`;
+      // The last row, past the first page, is the only one naming its
+      // organization.
+      insert(
+        setup,
+        "agent",
+        id,
+        agentNaming(id, i === rows - 1 ? "past-the-page" : "on-the-page"),
+      );
+    }
+    setup.close();
+
+    const store = SqliteStore.open(dbPath);
+    cleanups.push(() => store.close());
+    const db = new DatabaseSync(dbPath);
+    cleanups.push(() => db.close());
+    expect(ledger(db)).toEqual([
+      { slug: "on-the-page", retired: 1 },
+      { slug: "past-the-page", retired: 1 },
+    ]);
+  });
+
+  it("a scoped row that does not decode fails the step, names the row, and leaves the database at v11 with no ledger", () => {
+    const { dbPath, db: setup } = v11Database();
+    insert(setup, "agent", "agt_broken", new Uint8Array([0xff, 0xff, 0xff]));
+    setup.close();
+
+    expect(() => SqliteStore.open(dbPath)).toThrow(
+      /migrate to v12: .*agent 'agt_broken' cannot be read for the organization it names/,
+    );
+
+    const db = new DatabaseSync(dbPath);
+    cleanups.push(() => db.close());
+    expect(getSchemaVersion(db)).toBe(SCHEMA_VERSION_12 - 1);
+    expect(tableNames(db)).not.toContain("organization_slugs");
+  });
+});

package/src/store/sqlite/migrations.ts

@@ -33,6 +33,12 @@
  */
 import type { DatabaseSync } from "node:sqlite";
 
+import {
+  HISTORY_PAGE_SIZE,
+  ORGANIZATION_SCOPED_KINDS_AT_LEDGER,
+  organizationNamedBy,
+  undecodableRowError,
+} from "../organization-slug-history.js";
 import {
   PUBLIC_ROW_KINDS_AT_RETIREMENT,
   movePublicRowToOrg,
@@ -54,9 +60,11 @@ export const SCHEMA_VERSION_9 = 9;
 export const SCHEMA_VERSION_10 = 10;
 /** v11: the list index's columns, key table and indexes (DDL only). */
 export const SCHEMA_VERSION_11 = 11;
+/** v12: the organization-slug ledger, filled with every slug taken before it. */
+export const SCHEMA_VERSION_12 = 12;
 
 /** Target version for new databases. */
-export const CURRENT_SCHEMA_VERSION = SCHEMA_VERSION_11;
+export const CURRENT_SCHEMA_VERSION = SCHEMA_VERSION_12;
 
 /**
  * Applies every pending migration up to `targetVersion` in order — all of
@@ -87,6 +95,7 @@ export function runMigrations(
     [SCHEMA_VERSION_9, migrateToV9],
     [SCHEMA_VERSION_10, migrateToV10],
     [SCHEMA_VERSION_11, migrateToV11],
+    [SCHEMA_VERSION_12, migrateToV12],
   ];
 
   for (const [version, migrate] of chain) {
@@ -474,3 +483,62 @@ function migrateToV11(db: DatabaseSync): void {
       ON resource_list_keys (kind, key, value, created_at, id);
   `);
 }
+
+/**
+ * v12: the organization-slug ledger, the Postgres driver's v7 in this
+ * engine's terms (postgres/migrations.ts gives the reasons for the table's
+ * shape and the fill's order; organization-slug-history.ts what the fill
+ * records and why an undecodable row fails the step). Runs inside
+ * applyInTransaction's BEGIN, so a throw rolls the whole step back and the
+ * boot stops on the row it names. INSERT OR IGNORE keeps a live
+ * organization's entry unretired whatever its rows say.
+ */
+function migrateToV12(db: DatabaseSync): void {
+  db.exec(`
+    CREATE TABLE organization_slugs (
+      slug TEXT PRIMARY KEY,
+      claimed_at TEXT NOT NULL,
+      retired_at TEXT
+    ) WITHOUT ROWID;
+  `);
+  const recordedAt = new Date().toISOString();
+  db.prepare(
+    `INSERT OR IGNORE INTO organization_slugs (slug, claimed_at)
+     SELECT id, ? FROM resources WHERE kind = 'organization'`,
+  ).run(recordedAt);
+
+  const page = db.prepare(
+    `SELECT id, data FROM resources WHERE kind = ? AND id > ? ORDER BY id LIMIT ?`,
+  );
+  const named = new Set<string>();
+  for (const entry of ORGANIZATION_SCOPED_KINDS_AT_LEDGER) {
+    let after = "";
+    for (;;) {
+      const rows = page.all(entry.kind, after, HISTORY_PAGE_SIZE) as Array<{
+        id: string;
+        data: Uint8Array;
+      }>;
+      for (const row of rows) {
+        let org: string;
+        try {
+          org = organizationNamedBy(entry, row.data);
+        } catch (error) {
+          throw undecodableRowError(entry, row.id, error);
+        }
+        if (org !== "") {
+          named.add(org);
+        }
+      }
+      if (rows.length < HISTORY_PAGE_SIZE) {
+        break;
+      }
+      after = rows[rows.length - 1]!.id;
+    }
+  }
+  const retire = db.prepare(
+    `INSERT OR IGNORE INTO organization_slugs (slug, claimed_at, retired_at) VALUES (?, ?, ?)`,
+  );
+  for (const slug of named) {
+    retire.run(slug, recordedAt, recordedAt);
+  }
+}

package/src/store/sqlite/store.ts

@@ -47,6 +47,9 @@ import type {
   ClaimResult,
   OAuthGrant,
   OAuthGrantStore,
+  OrganizationSlugClaim,
+  OrganizationSlugEntry,
+  OrganizationSlugStore,
   PendingOAuthState,
   PendingOAuthStateStore,
   RawResourceDocument,
@@ -156,6 +159,7 @@ const RECONCILE_BATCH = 500;
 export class SqliteStore implements Store {
   readonly bootstrapState: BootstrapStateStore;
   readonly signalDedupe: SignalDedupeStore;
+  readonly organizationSlugs: OrganizationSlugStore;
   readonly oauthGrants: OAuthGrantStore;
   readonly pendingOAuthStates: PendingOAuthStateStore;
 
@@ -176,6 +180,7 @@ export class SqliteStore implements Store {
     this.listIndexes = listIndexes;
     this.bootstrapState = new SqliteBootstrapStateStore(() => this.open());
     this.signalDedupe = new SqliteSignalDedupeStore(() => this.open(), logger);
+    this.organizationSlugs = new SqliteOrganizationSlugStore(() => this.open());
     this.oauthGrants = new SqliteOAuthGrantStore(() => this.open());
     this.pendingOAuthStates = new SqlitePendingOAuthStateStore(() =>
       this.open(),
@@ -1596,6 +1601,85 @@ function isUniqueConstraintError(error: unknown): boolean {
   );
 }
 
+// =============================================================================
+// Organization slugs
+// =============================================================================
+
+/** A ledger row as the driver reads it (`retired_at` NULL while held). */
+interface OrganizationSlugRow {
+  slug: string;
+  claimed_at: string;
+  retired_at: string | null;
+}
+
+function organizationSlugEntryOf(
+  row: OrganizationSlugRow,
+): OrganizationSlugEntry {
+  return {
+    slug: row.slug,
+    claimedAt: row.claimed_at,
+    retiredAt: row.retired_at ?? "",
+  };
+}
+
+class SqliteOrganizationSlugStore implements OrganizationSlugStore {
+  constructor(private readonly open: () => DatabaseSync) {}
+
+  async claim(slug: string): Promise<OrganizationSlugClaim> {
+    const db = this.open();
+    const claimedAt = new Date().toISOString();
+    // INSERT OR IGNORE on the primary key: the one connection serialises
+    // writers, and `changes` says whether this claim is the one that won.
+    const inserted = db
+      .prepare(
+        `INSERT OR IGNORE INTO organization_slugs (slug, claimed_at) VALUES (?, ?)`,
+      )
+      .run(slug, claimedAt);
+    if (Number(inserted.changes) === 1) {
+      return { claimed: true, entry: { slug, claimedAt, retiredAt: "" } };
+    }
+    const holder = await this.find(slug);
+    if (holder === undefined) {
+      // A holder only disappears through its own create's release, so a
+      // lost claim with no holder is a claim that raced that release:
+      // surfaced as a fault rather than fabricating an entry.
+      throw new Error(
+        `organization slug '${slug}': its holder disappeared during the claim`,
+      );
+    }
+    return { claimed: false, entry: holder };
+  }
+
+  async retire(slug: string): Promise<void> {
+    const retiredAt = new Date().toISOString();
+    this.open()
+      .prepare(
+        `INSERT INTO organization_slugs (slug, claimed_at, retired_at) VALUES (?, ?, ?)
+         ON CONFLICT (slug) DO UPDATE SET retired_at = excluded.retired_at
+         WHERE organization_slugs.retired_at IS NULL`,
+      )
+      .run(slug, retiredAt, retiredAt);
+  }
+
+  async release(entry: OrganizationSlugEntry): Promise<void> {
+    this.open()
+      .prepare(
+        `DELETE FROM organization_slugs
+         WHERE slug = ? AND claimed_at = ? AND retired_at IS NULL`,
+      )
+      .run(entry.slug, entry.claimedAt);
+  }
+
+  async find(slug: string): Promise<OrganizationSlugEntry | undefined> {
+    const row = this.open()
+      .prepare(
+        `SELECT slug, claimed_at, retired_at FROM organization_slugs WHERE slug = ?`,
+      )
+      .get(slug) as OrganizationSlugRow | undefined;
+    return row === undefined ? undefined : organizationSlugEntryOf(row);
+  }
+}
+
 // =============================================================================
 // MCP OAuth grants (Go pkg/domain/mcpserver/oauth/grant_store.go)
 // =============================================================================