@substrat-run/contract-tests 0.142.0 → 0.144.0

package/dist/shape-backfill-ties.d.ts

@@ -0,0 +1,29 @@
+import { type SwitchSql } from '@substrat-run/kernel';
+interface TieCase {
+    name: string;
+    /** The pairs the backfill marked, and the ones it should have. */
+    marked: string[];
+    expected: string[];
+    /** Whether the run-once record was written once the reconcile finished. */
+    recorded: boolean;
+}
+/**
+ * Three cases, each its own table and entity type, each reconciled at `limit` 1 (one mark, a window
+ * of ten rows) until the reconcile finishes:
+ *
+ * - `duplicate id`: `(e1, A)`, `(e1, B)`, `(e2, C)` on an index of the id alone. The write budget
+ *   ends the first pass on A, mid-id.
+ * - `null principal at the edge`: nine rows with no principal, then `(e1, NULL)` closing the first
+ *   window, then `(e1, A)`. A principal-keyed seek past `(e1, NULL)` compares NULL for every e1 row.
+ * - `without rowid`: `(e1, A)`, `(e1, B)`, `(e2, C)` in a `WITHOUT ROWID` table keyed on another
+ *   column, with an index on the id. Then the same table declared `WITHOUT ROWID, STRICT`, and
+ *   `WITHOUT ROWID` followed by a comment: DDL text that does not end in the clause.
+ * - `a column named rowid`: the duplicate-id case in a table whose own `rowid` column, the same on
+ *   every row, would stand where the row's identity should.
+ */
+export declare function shapeBackfillTies(raw: SwitchSql, ids: {
+    tenantId: string;
+    scopeId: string;
+}): TieCase[];
+export {};
+//# sourceMappingURL=shape-backfill-ties.d.ts.map

package/dist/shape-backfill-ties.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape-backfill-ties.d.ts","sourceRoot":"","sources":["../src/shape-backfill-ties.ts"],"names":[],"mappings":"AAWA,OAAO,EAAkD,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtG,UAAU,OAAO;IACf,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,2EAA2E;IAC3E,QAAQ,EAAE,OAAO,CAAC;CACnB;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,EAAE,CA+EvG"}

package/dist/shape-backfill-ties.js

@@ -0,0 +1,113 @@
+/**
+ * A table holder's rows that share an `idColumn` are all read, whichever row a window ends on
+ * (#2154, #2159 review). Nothing makes `idColumn` unique or the principal non-NULL, so a read keyed
+ * on the id alone, or on the id and the principal, skipped the rest of an id's rows at a window's
+ * edge, and the run-once record then closed the backfill over them for good. Pure, with no runner:
+ * each adapter hands it its scope's own SQLite as the kernel's `SwitchSql`, so the cases run on the
+ * engine it actually ships, and asserts every case marked what it expected.
+ *
+ * Harness code: it writes `_substrat_*` rows directly, which is exactly what `ctx.sql` refuses.
+ */
+import { entityGrantShape } from '@substrat-run/contracts';
+import { topUpEntityGrantShapes, ulid } from '@substrat-run/kernel';
+const KEY = 'shape-tie:use';
+/**
+ * Three cases, each its own table and entity type, each reconciled at `limit` 1 (one mark, a window
+ * of ten rows) until the reconcile finishes:
+ *
+ * - `duplicate id`: `(e1, A)`, `(e1, B)`, `(e2, C)` on an index of the id alone. The write budget
+ *   ends the first pass on A, mid-id.
+ * - `null principal at the edge`: nine rows with no principal, then `(e1, NULL)` closing the first
+ *   window, then `(e1, A)`. A principal-keyed seek past `(e1, NULL)` compares NULL for every e1 row.
+ * - `without rowid`: `(e1, A)`, `(e1, B)`, `(e2, C)` in a `WITHOUT ROWID` table keyed on another
+ *   column, with an index on the id. Then the same table declared `WITHOUT ROWID, STRICT`, and
+ *   `WITHOUT ROWID` followed by a comment: DDL text that does not end in the clause.
+ * - `a column named rowid`: the duplicate-id case in a table whose own `rowid` column, the same on
+ *   every row, would stand where the row's identity should.
+ */
+export function shapeBackfillTies(raw, ids) {
+    const cases = [
+        {
+            name: 'duplicate id',
+            type: 'tieseat',
+            ddl: ['CREATE TABLE shape_tie_seat (entity_id TEXT, holder TEXT)', 'CREATE INDEX shape_tie_seat_id ON shape_tie_seat (entity_id)'],
+            rows: [['e1', 'A'], ['e1', 'B'], ['e2', 'C']],
+        },
+        {
+            name: 'null principal at the edge',
+            type: 'tiedesk',
+            ddl: ['CREATE TABLE shape_tie_desk (entity_id TEXT, holder TEXT)', 'CREATE INDEX shape_tie_desk_id ON shape_tie_desk (entity_id)'],
+            rows: [...Array.from({ length: 9 }, (_, i) => [`a${i}`, null]), ['e1', null], ['e1', 'A']],
+        },
+        {
+            name: 'without rowid',
+            type: 'tiebadge',
+            ddl: [
+                'CREATE TABLE shape_tie_badge (k TEXT PRIMARY KEY, entity_id TEXT, holder TEXT) WITHOUT ROWID',
+                'CREATE INDEX shape_tie_badge_id ON shape_tie_badge (entity_id)',
+            ],
+            rows: [['e1', 'A'], ['e1', 'B'], ['e2', 'C']],
+        },
+        {
+            name: 'without rowid, strict',
+            type: 'tiestrict',
+            ddl: [
+                'CREATE TABLE shape_tie_strict (k TEXT PRIMARY KEY, entity_id TEXT, holder TEXT) WITHOUT ROWID, STRICT',
+                'CREATE INDEX shape_tie_strict_id ON shape_tie_strict (entity_id)',
+            ],
+            rows: [['e1', 'A'], ['e1', 'B'], ['e2', 'C']],
+        },
+        {
+            name: 'without rowid, then a comment',
+            type: 'tienote',
+            ddl: [
+                'CREATE TABLE shape_tie_note (k TEXT PRIMARY KEY, entity_id TEXT, holder TEXT) WITHOUT ROWID -- keyed on k',
+                'CREATE INDEX shape_tie_note_id ON shape_tie_note (entity_id)',
+            ],
+            rows: [['e1', 'A'], ['e1', 'B'], ['e2', 'C']],
+        },
+        {
+            name: 'a column named rowid',
+            type: 'tieshadow',
+            ddl: [
+                "CREATE TABLE shape_tie_shadow (rowid TEXT DEFAULT 'same', entity_id TEXT, holder TEXT)",
+                'CREATE INDEX shape_tie_shadow_id ON shape_tie_shadow (entity_id)',
+            ],
+            rows: [['e1', 'A'], ['e1', 'B'], ['e2', 'C']],
+        },
+    ];
+    return cases.map(({ name, type, ddl, rows }) => {
+        const table = ddl[0].split(' ')[2];
+        for (const st of ddl)
+            raw.run(st);
+        const expected = [];
+        const keyed = ddl[0].includes('WITHOUT ROWID'); // its own key column, `k`
+        rows.forEach(([id, who], i) => {
+            const holder = who && `${who}-${ulid()}`;
+            if (keyed)
+                raw.run(`INSERT INTO ${table} (k, entity_id, holder) VALUES (?, ?, ?)`, `k${i}`, id, holder);
+            else
+                raw.run(`INSERT INTO ${table} (entity_id, holder) VALUES (?, ?)`, id, holder);
+            if (!holder)
+                return;
+            raw.run('INSERT INTO _substrat_tuples (subject, relation, object) VALUES (?, ?, ?)', `principal:${holder}`, `granted:${KEY}`, `${type}:${id}`);
+            expected.push(`principal:${holder} ${type}:${id}`);
+        });
+        const shapes = [entityGrantShape.parse({ entityType: type, permissions: [KEY], bootstrap: true, holder: { table, idColumn: 'entity_id', principalColumn: 'holder' } })];
+        let after = null;
+        let passes = 0;
+        do {
+            after = topUpEntityGrantShapes(raw, { ...ids, shapes, now: new Date().toISOString(), limit: 1, after, mintEventId: () => ulid(), version: null }).next;
+            passes++;
+        } while (after && passes < 100);
+        // A cursor that never ends is a failure of its own, whatever happened to be marked by the cap.
+        if (after)
+            throw new Error(`${name}: the reconcile did not finish in ${passes} passes`);
+        const marked = raw
+            .all("SELECT subject || ' ' || object AS pair FROM _substrat_tuples WHERE relation = 'bootstrap' AND object >= ? AND object < ? ORDER BY 1", `${type}:`, `${type};`)
+            .map((r) => String(r['pair']));
+        const recorded = raw.all("SELECT 1 FROM _substrat_tuples WHERE subject = ? AND relation = 'shape-backfilled'", `shape:${type}`).length === 1;
+        return { name, marked, expected: expected.sort(), recorded };
+    });
+}
+//# sourceMappingURL=shape-backfill-ties.js.map

package/dist/shape-backfill-ties.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape-backfill-ties.js","sourceRoot":"","sources":["../src/shape-backfill-ties.ts"],"names":[],"mappings":"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"}

package/dist/shape-reconcile-plan.d.ts

@@ -0,0 +1,37 @@
+import { type SwitchSql } from '@substrat-run/kernel';
+type HolderKind = 'self' | 'grantee' | 'table';
+interface ShapeReconcilePlanReport {
+    /** The plan of each marker walk the passes sent (one per retire and top-up walk). */
+    walks: string[];
+    /** The plan of each backfill read, by the holder kind it read for. */
+    backfills: Record<HolderKind, string[]>;
+    /** Every planned table scan of `_substrat_tuples`, with the statement that planned it. */
+    scans: string[];
+    /** Passes the reconcile took, and whether every holder ended up with the whole shape. */
+    passes: number;
+    complete: boolean;
+    /** Markers the backfill wrote, and how many legacy holders there were to mark. */
+    marks: number;
+    holders: number;
+    /** The most rows any one pass's backfill reads fetched, and the read budget of a pass. */
+    maxFetched: number;
+    window: number;
+    /** The most rows the engine read in one pass, every statement included: given `rowsRead` only. */
+    maxRowsRead: number | null;
+}
+/**
+ * Seed three shapes' worlds on `raw` — holders of the old shape, legacy holders with no marker for
+ * each holder kind, a retired key, and another type's markers beside them — then reconcile them in
+ * small passes, each resuming from the last, planning every statement. `legacy` legacy holders per
+ * kind (default 5); `rowsRead`, when the engine counts them, the running total of rows it has read.
+ * Run it on a scope nothing else is writing.
+ */
+export declare function shapeReconcilePlans(raw: SwitchSql, ids: {
+    tenantId: string;
+    scopeId: string;
+}, opts?: {
+    legacy?: number;
+    rowsRead?: () => number;
+}): ShapeReconcilePlanReport;
+export {};
+//# sourceMappingURL=shape-reconcile-plan.d.ts.map

package/dist/shape-reconcile-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape-reconcile-plan.d.ts","sourceRoot":"","sources":["../src/shape-reconcile-plan.ts"],"names":[],"mappings":"AAsBA,OAAO,EAA8E,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAIlI,KAAK,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAE/C,UAAU,wBAAwB;IAChC,qFAAqF;IACrF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;IACxC,0FAA0F;IAC1F,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,kGAAkG;IAClG,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAQD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,SAAS,EACd,GAAG,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAC1C,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAA;CAAO,GACtD,wBAAwB,CA0G1B"}

package/dist/shape-reconcile-plan.js

@@ -0,0 +1,143 @@
+/**
+ * The shape reconcile's reads, planned by the SQLite each adapter actually runs (#2083, #2154).
+ *
+ * A pass walks a shape's markers on `_substrat_tuples_shape_marker`, a partial index SQLite uses
+ * only where it can prove the index's `relation = 'bootstrap'` from the query. A relation term it
+ * cannot prove that from, or an object prefix written as `substr`, plans a scan of the whole tuple
+ * table, which no functional test notices, because a test scope has a dozen rows. So the probe here drives the kernel's own
+ * pass over a scope's real schema and asks the engine to plan every statement the pass sends,
+ * exactly as sent. Pure, with no runner: each adapter hands it its scope's own SQLite as the
+ * kernel's `SwitchSql` (over a `better-sqlite3` file, a Durable Object's `storage.sql`) and
+ * asserts on the report.
+ *
+ * The backfill reads in windows too (#2154), for each holder kind: the probe seeds legacy holders
+ * of a `'self'`, a `'grantee'` and a table-holder shape, and reports each kind's read plans, how
+ * many rows each pass fetched, and how many markers the backfill wrote, so an adapter can assert
+ * every holder was marked exactly once. Given the engine's own count of rows read (a Durable
+ * Object's `cursor.rowsRead`), it reports the most any one pass read, every statement included,
+ * which is the bound a scope actually pays.
+ *
+ * Harness code: it writes `_substrat_*` rows directly, which is exactly what `ctx.sql` refuses.
+ */
+import { entityGrantShape } from '@substrat-run/contracts';
+import { SHAPE_MARKER_READS_PER_ROW, topUpEntityGrantShapes, ulid } from '@substrat-run/kernel';
+const MARKERS = 30;
+const LIMIT = 4;
+const KEYS = ['shape-plan:read', 'shape-plan:use'];
+const RETIRED = 'shape-plan:old';
+const BADGES = 'shape_plan_badge';
+/**
+ * Seed three shapes' worlds on `raw` — holders of the old shape, legacy holders with no marker for
+ * each holder kind, a retired key, and another type's markers beside them — then reconcile them in
+ * small passes, each resuming from the last, planning every statement. `legacy` legacy holders per
+ * kind (default 5); `rowsRead`, when the engine counts them, the running total of rows it has read.
+ * Run it on a scope nothing else is writing.
+ */
+export function shapeReconcilePlans(raw, ids, opts = {}) {
+    const legacy = opts.legacy ?? 5;
+    const tuple = (subject, relation, object) => raw.run('INSERT OR REPLACE INTO _substrat_tuples (subject, relation, object) VALUES (?, ?, ?)', subject, relation, object);
+    const pad = (i) => String(i).padStart(5, '0');
+    for (let i = 0; i < MARKERS; i++) {
+        const [who, desk] = [`principal:${ulid()}`, `desk:d${pad(i)}`];
+        tuple(who, 'bootstrap', desk);
+        tuple(who, `granted:${KEYS[0]}`, desk);
+        if (i % 3 === 0)
+            tuple(who, `granted:${RETIRED}`, desk);
+        tuple(who, 'bootstrap', `room:d${pad(i)}`); // another type's marker: never read by this shape
+    }
+    raw.run(`CREATE TABLE IF NOT EXISTS ${BADGES} (id TEXT PRIMARY KEY, holder TEXT)`);
+    for (let i = 0; i < legacy; i++) {
+        const [grantee, owner, badged] = [ulid(), ulid(), ulid()];
+        tuple(`principal:${grantee}`, `granted:${KEYS[0]}`, `desk:l${pad(i)}`);
+        tuple(`principal:${owner}`, `granted:${KEYS[0]}`, `seat:${owner}`);
+        tuple(`principal:${ulid()}`, `granted:${KEYS[0]}`, `seat:${owner}`); // a sharee on it: never marked
+        raw.run(`INSERT INTO ${BADGES} (id, holder) VALUES (?, ?)`, `b${pad(i)}`, badged);
+        tuple(`principal:${badged}`, `granted:${KEYS[0]}`, `badge:b${pad(i)}`);
+    }
+    const walks = [];
+    const backfills = { self: [], grantee: [], table: [] };
+    const scans = [];
+    let [marks, fetched] = [0, 0];
+    /** Which holder kind a statement is the backfill read of, if it is one. */
+    const backfillOf = (sql, params) => sql.includes(`FROM "${BADGES}" e`) ? 'table' : sql.includes('(t.object, t.relation, t.subject) > (?, ?, ?)') ? (params.includes('seat;') ? 'self' : 'grantee') : null;
+    const plan = (sql, params) => {
+        if (!/^\s*(SELECT|UPDATE|DELETE)/i.test(sql))
+            return;
+        const detail = raw.all(`EXPLAIN QUERY PLAN ${sql}`, ...params).map((r) => String(r['detail']));
+        const joined = detail.join(' | ');
+        if (sql.includes('(m.object, m.subject) > (?, ?)'))
+            walks.push(joined);
+        const kind = backfillOf(sql, params);
+        if (kind)
+            backfills[kind].push(joined);
+        // A virtual table (`json_each`, `pragma_table_list`) is scanned by design; a scan of the tuple
+        // table, or of the holder's table, never is.
+        for (const d of detail)
+            if (/^SCAN /.test(d) && !/VIRTUAL TABLE/.test(d))
+                scans.push(`${d} — ${sql.replace(/\s+/g, ' ').slice(0, 160)}`);
+    };
+    const sql = {
+        all: (q, ...p) => {
+            if (q.startsWith('EXPLAIN'))
+                return raw.all(q, ...p); // the kernel's own plan check: not a read of rows
+            plan(q, p);
+            const rows = raw.all(q, ...p);
+            if (backfillOf(q, p))
+                fetched += rows.length;
+            return rows;
+        },
+        run: (q, ...p) => {
+            plan(q, p);
+            if (q.startsWith('INSERT OR IGNORE') && p[1] === 'bootstrap')
+                marks++;
+            raw.run(q, ...p);
+        },
+    };
+    const shapes = [
+        entityGrantShape.parse({ entityType: 'desk', permissions: KEYS, retired: [RETIRED], bootstrap: true, holder: 'grantee' }),
+        entityGrantShape.parse({ entityType: 'seat', permissions: KEYS, bootstrap: true, holder: 'self' }),
+        entityGrantShape.parse({ entityType: 'badge', permissions: KEYS, bootstrap: true, holder: { table: BADGES, idColumn: 'id', principalColumn: 'holder' } }),
+    ];
+    let after = null;
+    let passes = 0;
+    let maxFetched = 0;
+    let maxRowsRead = 0;
+    do {
+        fetched = 0;
+        const before = opts.rowsRead?.() ?? 0;
+        after = topUpEntityGrantShapes(sql, {
+            ...ids,
+            shapes,
+            now: new Date().toISOString(),
+            limit: LIMIT,
+            after,
+            mintEventId: () => ulid(),
+            version: null,
+        }).next;
+        maxFetched = Math.max(maxFetched, fetched);
+        // `EXPLAIN QUERY PLAN` executes nothing, so the probe's own planning adds no rows read.
+        maxRowsRead = Math.max(maxRowsRead, (opts.rowsRead?.() ?? 0) - before);
+        passes++;
+    } while (after && passes < 100_000);
+    const short = raw.all(`SELECT count(*) AS n FROM _substrat_tuples m
+      WHERE m.relation = 'bootstrap' AND ((m.object >= 'desk:' AND m.object < 'desk;') OR (m.object >= 'seat:' AND m.object < 'seat;')
+                                          OR (m.object >= 'badge:' AND m.object < 'badge;'))
+        AND NOT EXISTS (SELECT 1 FROM _substrat_tuples t WHERE t.subject = m.subject AND t.object = m.object
+                         AND t.relation = 'granted:${KEYS[1]}' AND t.revoked_at IS NULL)`)[0]['n'];
+    const markers = raw.all(`SELECT count(*) AS n FROM _substrat_tuples WHERE relation = 'bootstrap'
+        AND ((object >= 'desk:l' AND object < 'desk:m') OR (object >= 'seat:' AND object < 'seat;') OR (object >= 'badge:' AND object < 'badge;'))`)[0]['n'];
+    const holders = legacy * 3;
+    return {
+        walks,
+        backfills,
+        scans,
+        passes,
+        complete: after === null && Number(short) === 0 && Number(markers) === holders,
+        marks,
+        holders,
+        maxFetched,
+        window: LIMIT * SHAPE_MARKER_READS_PER_ROW,
+        maxRowsRead: opts.rowsRead ? maxRowsRead : null,
+    };
+}
+//# sourceMappingURL=shape-reconcile-plan.js.map

package/dist/shape-reconcile-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape-reconcile-plan.js","sourceRoot":"","sources":["../src/shape-reconcile-plan.ts"],"names":[],"mappings":"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"}

package/dist/test-operations.d.ts

@@ -0,0 +1,25 @@
+import { type BoundOperations, type HandlerMap } from '@substrat-run/kernel';
+/** The maps a registration derives from a declaration, as a fixture may hand them over raw. */
+export interface RawDerivedMaps {
+    inputs?: BoundOperations['inputs'];
+    concurrency?: BoundOperations['concurrency'];
+    idempotencyOptOuts?: BoundOperations['idempotencyOptOuts'];
+}
+/**
+ * A fixture's operations, registered without binding them to a declaration (#1835) — the TEST
+ * SEAM around `operationsFor`, and the only one.
+ *
+ * The suites drive the host with modules built for one assertion each, so most have no declared
+ * surface: `testOperations(handlers)` is `undeclaredOperations` with the reason stated once.
+ *
+ * A few prove what the HOST refuses when the derived maps are wrong — a schema or a precondition
+ * naming an unbound operation, an `inputs` map that is not the one `operationInputsOf`
+ * returned, a forged trash surface — or need maps over handlers whose types they erase on
+ * purpose. Those pass `derived`, and get a `BoundOperations` no binder made, through the kernel's
+ * `./testing` subpath — the value a module cannot build, and boundary-lint R2 refuses that import,
+ * and this package's, from module code.
+ */
+export declare function testOperations(handlers: HandlerMap, derived?: RawDerivedMaps): {
+    operations: BoundOperations;
+};
+//# sourceMappingURL=test-operations.d.ts.map

package/dist/test-operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-operations.d.ts","sourceRoot":"","sources":["../src/test-operations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGnG,+FAA+F;AAC/F,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,eAAe,CAAC,aAAa,CAAC,CAAC;IAC7C,kBAAkB,CAAC,EAAE,eAAe,CAAC,oBAAoB,CAAC,CAAC;CAC5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG;IAAE,UAAU,EAAE,eAAe,CAAA;CAAE,CAG9G"}

package/dist/test-operations.js

@@ -0,0 +1,22 @@
+import { undeclaredOperations } from '@substrat-run/kernel';
+import { forgeBoundOperationsForTest } from '@substrat-run/kernel/testing';
+/**
+ * A fixture's operations, registered without binding them to a declaration (#1835) — the TEST
+ * SEAM around `operationsFor`, and the only one.
+ *
+ * The suites drive the host with modules built for one assertion each, so most have no declared
+ * surface: `testOperations(handlers)` is `undeclaredOperations` with the reason stated once.
+ *
+ * A few prove what the HOST refuses when the derived maps are wrong — a schema or a precondition
+ * naming an unbound operation, an `inputs` map that is not the one `operationInputsOf`
+ * returned, a forged trash surface — or need maps over handlers whose types they erase on
+ * purpose. Those pass `derived`, and get a `BoundOperations` no binder made, through the kernel's
+ * `./testing` subpath — the value a module cannot build, and boundary-lint R2 refuses that import,
+ * and this package's, from module code.
+ */
+export function testOperations(handlers, derived) {
+    if (!derived)
+        return undeclaredOperations('a contract-test fixture, built to drive the host rather than declared', handlers);
+    return { operations: forgeBoundOperationsForTest(handlers, derived) };
+}
+//# sourceMappingURL=test-operations.js.map

package/dist/test-operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-operations.js","sourceRoot":"","sources":["../src/test-operations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAyC,MAAM,sBAAsB,CAAC;AACnG,OAAO,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AAS3E;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,QAAoB,EAAE,OAAwB;IAC3E,IAAI,CAAC,OAAO;QAAE,OAAO,oBAAoB,CAAC,uEAAuE,EAAE,QAAQ,CAAC,CAAC;IAC7H,OAAO,EAAE,UAAU,EAAE,2BAA2B,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC;AACxE,CAAC"}

package/dist/vertical-events-suite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vertical-events-suite.d.ts","sourceRoot":"","sources":["../src/vertical-events-suite.ts"],"names":[],"mappings":"AACA,OAAO,EASL,CAAC,EAED,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EAGtB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACd,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAML,KAAK,kBAAkB,EAEvB,KAAK,kBAAkB,EAGvB,KAAK,SAAS,EAEf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAA4D,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAcvH,eAAO,MAAM,YAAY,aAAa,CAAC;AACvC,eAAO,MAAM,cAAc,eAAe,CAAC;AAI3C,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiC/B,CAAC;AAiFH,eAAO,MAAM,YAAY,EAAE,kBAuC1B,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BjC,CAAC;AAkCH,eAAO,MAAM,cAAc,EAAE,kBAgD5B,CAAC;AAIF;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,SAAS,CAAC;IACpB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,YAAY,CAAC,CAAC;IACnD;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,gBAAgB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACrG;;;OAGG;IACH,IAAI,CAAC,EAAE,CACL,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,OAAO,KACb,OAAO,CAAC,SAAS;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,EAAE,CAAC,CAAC;IACtG;;;;OAIG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CACpD;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,GAChD,IAAI,CA+1CN"}
+{"version":3,"file":"vertical-events-suite.d.ts","sourceRoot":"","sources":["../src/vertical-events-suite.ts"],"names":[],"mappings":"AACA,OAAO,EASL,CAAC,EAED,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EAGtB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACd,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAOL,KAAK,kBAAkB,EAEvB,KAAK,kBAAkB,EAGvB,KAAK,SAAS,EAEf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAA4D,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAevH,eAAO,MAAM,YAAY,aAAa,CAAC;AACvC,eAAO,MAAM,cAAc,eAAe,CAAC;AAI3C,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiC/B,CAAC;AAiFH,eAAO,MAAM,YAAY,EAAE,kBAuC1B,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BjC,CAAC;AAgDH,eAAO,MAAM,cAAc,EAAE,kBA0D5B,CAAC;AAIF;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,SAAS,CAAC;IACpB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,YAAY,CAAC,CAAC;IACnD;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,gBAAgB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACrG;;;OAGG;IACH,IAAI,CAAC,EAAE,CACL,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,OAAO,KACb,OAAO,CAAC,SAAS;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,EAAE,CAAC,CAAC;IACtG;;;;OAIG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;CACpD;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,GAChD,IAAI,CA24CN"}

package/dist/vertical-events-suite.js

@@ -1,7 +1,8 @@
 import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
 import { dataSubjectId, eventId, moduleManifest, permissionKey, platformActorId, principalId, scopeId, tenantId, z, } from '@substrat-run/contracts';
-import { assertAllowed, crossVerticalHealth, INERT_SCOPE_REASON, runPlatformSweep, ulid, } from '@substrat-run/kernel';
+import { assertAllowed, crossVerticalHealth, INERT_SCOPE_REASON, REDACTED_DELIVERY_NOTE, runPlatformSweep, ulid, } from '@substrat-run/kernel';
 import { expectAnswered, expectSettledUnknown, withRefusedOutcome } from './switch-audit-fault.js';
+import { testOperations } from './test-operations.js';
 // -- the two fixture verticals ------------------------------------------------
 //
 // Named as the verticals of one tenant would be: a CRM that owns customers, and a board-room
@@ -127,13 +128,13 @@ const crmFlag = async (ctx, input) => {
 export const crmExportMod = {
     manifest: crmExportModManifest,
     migrations: [{ version: '0001-init', sql: 'CREATE TABLE crm_customers (id TEXT PRIMARY KEY, name TEXT NOT NULL)' }],
-    operations: {
+    ...testOperations({
         'crm/create': crmCreate,
         'crm/note': crmNote,
         'crm/touch': crmTouch,
         'crm/create-then-fail': crmCreateThenFail,
         'crm/flag': crmFlag,
-    },
+    }),
     consumers: {
         // In the invoke's post-commit tail: an exported type committed by a consumer, not the operation.
         'crm.customer-flagged': async (ctx, event) => {
@@ -176,8 +177,11 @@ export const boardImportModManifest = moduleManifest.parse({
         emits: [
             { type: 'board.association-created', schemaVersion: 1 },
             { type: 'board.association-linked', schemaVersion: 1 },
+            // #1757: board's OWN classified event, whose local consumer fails quoting the subject.
+            { type: 'board.member-noted', schemaVersion: 1 },
         ],
         consumes: [
+            { type: 'board.member-noted', schemaVersion: 1 },
             { from: CRM_VERTICAL, type: 'crm.customer-created', schemaVersion: 1 },
             // crm emits this and does not export it. Declaring it must not be enough to receive it.
             { from: CRM_VERTICAL, type: 'crm.customer-noted', schemaVersion: 1 },
@@ -202,9 +206,22 @@ const boardRead = async (ctx) => {
         imports: ctx.sql.query('SELECT event_id, source_vertical, source_scope_id, type, hops, withheld FROM _substrat_imports ORDER BY event_id'),
         deliveries: ctx.sql.query('SELECT event_id, consumer_module, error FROM _substrat_deliveries ORDER BY event_id, consumer_module'),
         outbox: ctx.sql.query('SELECT id, type, caused_by, actor FROM _substrat_outbox ORDER BY id'),
-        replays: ctx.sql.query('SELECT replay_id, kind, event_id, consumer_module FROM _substrat_import_replays ORDER BY kind, event_id'),
+        replays: ctx.sql.query(`SELECT replay_id, kind, event_id, consumer_module, json_extract(row, '$.error') AS error
+         FROM _substrat_import_replays ORDER BY kind, event_id`),
     };
 };
+/** #1757: emits board's own classified event about one subject. */
+const boardNoteMember = async (ctx, input) => {
+    assertAllowed(await ctx.check(key('association:read')));
+    ctx.emit({
+        type: 'board.member-noted',
+        schemaVersion: 1,
+        entity: { entityType: 'member', entityId: input.subjectId },
+        piiClass: 'direct',
+        subjectId: dataSubjectId.parse(input.subjectId),
+        payload: { subjectId: input.subjectId },
+    });
+};
 export const boardImportMod = {
     manifest: boardImportModManifest,
     migrations: [
@@ -216,14 +233,24 @@ export const boardImportMod = {
       `,
         },
     ],
-    operations: { 'board/read': boardRead },
+    ...testOperations({
+        'board/read': boardRead,
+        'board/note-member': boardNoteMember,
+    }),
+    consumers: {
+        // #1757: fails quoting the subject, so its delivery row holds the subject's id as text.
+        'board.member-noted': async (_ctx, event) => {
+            throw new Error(`board cannot note member ${event.subjectId}`);
+        },
+    },
     imports: {
         [CRM_VERTICAL]: {
             'crm.customer-created': async (ctx, event) => {
                 assertAllowed(await ctx.check(key('association:sync')));
                 const c = customerCreated.parse(event.payload);
-                if (c.name === 'poison')
-                    throw new Error('board refuses the poison customer');
+                // The name is quoted, so a handler's own sentence can carry a subject's id (#1757).
+                if (c.name.startsWith('poison'))
+                    throw new Error(`board refuses the poison customer ${c.name}`);
                 ctx.sql.exec(`INSERT INTO board_associations (crm_id, name) VALUES (?, ?)
            ON CONFLICT (crm_id) DO UPDATE SET name = excluded.name`, [c.id, c.name]);
                 ctx.emit({
@@ -742,6 +769,44 @@ export function verticalEventsContractSuite(adapterName, makeFixture) {
             expect(createdFor(first.event_id)).toBe(1);
             expect(createdFor(second.event_id)).toBe(2);
         });
+        // #1757: a replay keeps an import's delivery row in `_substrat_import_replays`, `error`
+        // included. On a released import that text is a handler's own sentence and can name a
+        // subject, but no erasure reaches it, live or moved aside: a released event is piiClass
+        // 'none', so no subject link names its delivery. (A withheld one, a classified one included,
+        // gets a dead letter whose error is the platform's own note, which names no one.) The control is
+        // the scope's OWN classified event, whose failed delivery the same erasure does rewrite.
+        // What is held is that the two copies of an import's delivery agree after an erasure, so a
+        // later erasure that reaches the live row cannot leave the replayed one behind.
+        it('an erasure treats an import\'s moved-aside delivery exactly as its live one (#1757)', async () => {
+            const t = await newTenant();
+            const p = await install(t, CRM_VERTICAL);
+            const c = await install(t, BOARD_VERTICAL);
+            const subject = dataSubjectId.parse(ulid());
+            await create(t, p, `poison ${subject}`);
+            await sweep();
+            await lever(t, c, replay(null));
+            // The redelivery fails again, so the live table and the replay history each hold the text.
+            await sweep();
+            await (await fx.consumer.getScope(reader, t, c)).invoke('board/note-member', { subjectId: subject });
+            const receipt = await fx.consumer.admin.shredSubject(staff, t, c, subject);
+            expect(receipt).toMatchObject({ subjectId: subject, eventsRedacted: 1 });
+            const view = await board(t, c);
+            const [own] = view.outbox.filter((o) => o.type === 'board.member-noted');
+            expect(view.deliveries.find((d) => d.event_id === own.id)?.error).toBe(REDACTED_DELIVERY_NOTE);
+            const [imported] = view.imports;
+            const live = view.deliveries.find((d) => d.event_id === imported.event_id)?.error;
+            const archived = view.replays.find((r) => r.kind === 'delivery' && r.event_id === imported.event_id)?.error;
+            // Both copies exist, so the comparison below cannot pass on two absences.
+            expect(typeof live).toBe('string');
+            expect(typeof archived).toBe('string');
+            expect(archived, '#1757: an erasure changed an imported delivery\'s live error but not its copy in ' +
+                '_substrat_import_replays (or the reverse). Whatever reaches _substrat_deliveries.error for an ' +
+                'imported event must rewrite json_extract(row, \'$.error\') of its kind=\'delivery\' rows too, in ' +
+                'the same transaction, or the replay history keeps what the live table gave up.').toBe(live);
+            // Today no erasure reaches either copy. When one does, this line changes, and the one above
+            // is what holds the replay history to it.
+            expect(live).toContain(subject);
+        });
         it('skip to now: nothing before the skip is delivered, what comes after is, and a replay reaches back', async () => {
             const t = await newTenant();
             const p = await install(t, CRM_VERTICAL);