@substrat-run/kernel 0.138.0 → 0.140.0

package/dist/entity-state.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Entity archive and trash (#119): the kernel half, written once — both adapters hand
+ * `createEntityStateVerbs` the same things, the way `createEntityEdgeVerbs` is shared.
+ *
+ * ## What the kernel owns, and what it leaves to the vertical
+ *
+ * | Kernel | Vertical |
+ * |---|---|
+ * | The two columns on the entity's table, added by a derived migration | Which entities declare `archive` / `trash`, and the keys |
+ * | The transitions, their refusals, and the event each one emits | The operations that call the verbs, and their routes |
+ * | The declared key, re-checked on the entity by every verb and every trashed read | What an archived row looks like on a screen |
+ * | `ctx.page` / `ctx.search` leaving archived and trashed rows out by default | Its own hand-written `SELECT`s — see the gap below |
+ *
+ * ## The state is two columns
+ *
+ * `_substrat_archived_at` and `_substrat_trashed_at`, each an ISO instant or NULL. Apart, not
+ * one enum, so a trash never forgets an archive: `restore` clears the trash and leaves the
+ * archive, and an archived row that went to the bin comes back archived. The visible state is
+ * derived (contracts `entity-state.ts`): trashed, else archived, else active.
+ *
+ * Module code cannot write either column: `ctx.sql` refuses a write naming a `_substrat_*`
+ * column (`spine-guard.ts`), so the only way into or out of the trash is a verb that checks
+ * the key and emits the event. It can READ them, which is how a vertical's own `SELECT` keeps
+ * archived rows out of a screen `ctx.page` does not compose.
+ *
+ * ## The gap, stated
+ *
+ * The kernel filters the reads it composes — `ctx.page` and `ctx.search` — and nothing else.
+ * A handler's own `SELECT … FROM todo_lists WHERE id = ?` sees an archived or trashed row
+ * exactly as before. That is the honest limit of a kernel that does not parse module SQL:
+ * a get-by-id asks `ctx.entityState(ref)` and decides, and a hand-written list adds the
+ * predicate itself (`entityStateWhere`).
+ *
+ * ## Trash is not erasure, and not tenant deletion
+ *
+ * Trash keeps the row and every event about it. Subject erasure (#37) reaches a trashed row
+ * exactly as it reaches any other, because the row never moved tables; a tenant's deletion
+ * (#36) removes it with everything else. Nothing here extends a retention or shortens one.
+ */
+import { type DomainEventInput, type EntityStateDeclaration, type EntityStateName, type Instant, type PermissionKey } from '@substrat-run/contracts';
+import type { OperationContext, ScopedSql, SqlMigration } from './scope-host.js';
+import type { DerivedObject } from './derived-object.js';
+/** A resolved declaration: everything the DDL, the reads and the verbs need. */
+export interface EntityStatePlan {
+    readonly moduleId: string;
+    readonly entityType: string;
+    readonly table: string;
+    readonly idColumn: string;
+    /** Present when the entity can be archived. */
+    readonly archivePermission?: PermissionKey;
+    /** Present when the entity can be trashed. */
+    readonly trashPermission?: PermissionKey;
+    /** Present when a trashed entity is purged after this many days (`entity-trash.ts`). */
+    readonly purgeAfterDays?: number;
+}
+/** The operation's own check — a pass is recorded as one of its authorizations (K-34). */
+export type StateCheck = OperationContext['check'];
+/**
+ * Resolve one module's declarations. Refuses rather than skips, for `searchIndexPlans`'s
+ * reason: a declaration the author believes is live that silently is not leaves a trashed
+ * row in every list with no error anywhere.
+ */
+export declare function entityStatePlans(moduleId: string, declarations: readonly EntityStateDeclaration[] | undefined): EntityStatePlan[];
+/**
+ * The migrations that add the columns — one per column, so declaring `trash` on an entity
+ * that already declared `archive` adds one column and re-runs nothing.
+ *
+ * **The version is the declaration**, as for search and list indexes. Unlike theirs, this DDL
+ * is not drop-then-create: a column holds the state, and dropping it would un-trash every row.
+ * So it runs once per column, ever. Withdrawing a declaration leaves the column where it is,
+ * holding what it held; re-declaring it finds the migration already applied.
+ *
+ * Applied after the module's own migrations (the table must exist) and before its list
+ * indexes (their partial `WHERE` names these columns) — `moduleMigrations` writes that order.
+ */
+export declare function entityStateMigrations(moduleId: string, declarations: readonly EntityStateDeclaration[] | undefined): SqlMigration[];
+/** The column migrations' versions, and the column each adds — what the journal says a table holds. */
+export declare const stateColumnVersionsOf: (plan: EntityStatePlan) => {
+    version: string;
+    column: string;
+}[];
+/** The purge index's migration version (#119) — present only on a plan with a purge horizon. */
+export declare const purgeIndexVersion: (plan: EntityStatePlan) => string;
+/**
+ * The partial index the purge sweep walks (#119): trashed rows only, oldest trash first, so a
+ * sweep reads the due rows and nothing else. Its name is kernel-prefixed, so the reserved
+ * namespace. Empty for a plan without a purge horizon.
+ */
+export declare function purgeIndexObjects(plan: EntityStatePlan): DerivedObject[];
+/**
+ * The purge index's DDL. `IF NOT EXISTS` because a dump load runs it again after the rows are
+ * in; a repair that finds it wrong drops it first (`purgeIndexRepairDdl`).
+ */
+export declare function purgeIndexDdl(plan: EntityStatePlan): string;
+/** Drop-then-create, for a purge index the catalogue holds under its name but not as emitted. */
+export declare function purgeIndexRepairDdl(plan: EntityStatePlan): string;
+/**
+ * The guard triggers' version. By which columns they guard, so declaring a trash on an
+ * archivable entity rebuilds them to guard both.
+ */
+export declare const entityStateGuardVersion: (plan: EntityStatePlan) => string;
+/** The prefix of every trigger this module derives — kernel-owned, so the reserved one. */
+export declare const ENTITY_STATE_TRIGGER_PREFIX = "_substrat_state_";
+/**
+ * The kernel's authorization for ONE move (#119, Codex r2): the row `ctx.archive` & co. write
+ * just before their `UPDATE` and delete just after it, in the same transaction. The update
+ * trigger below refuses any change to the columns that has no such row — so the only writer the
+ * columns admit is the one that can write a `_substrat_*` TABLE, which `ctx.sql` refuses by name
+ * (a far simpler reading than finding an assignment target in an expression).
+ *
+ * Never holds a row between operations: written and removed inside one move, and a move that
+ * throws rolls back with its operation. Shared by both adapters' `KERNEL_DDL`, like the other
+ * kernel-owned spine tables, so the two cannot part company.
+ */
+export declare const ENTITY_STATE_MOVES_TABLE = "_substrat_state_moves";
+export declare const ENTITY_STATE_MOVES_DDL = "\n  CREATE TABLE IF NOT EXISTS _substrat_state_moves (\n    entity_type TEXT NOT NULL,\n    entity_id TEXT NOT NULL,\n    PRIMARY KEY (entity_type, entity_id)\n  );\n";
+/**
+ * The invariant below the column guard, as two triggers on the entity's table.
+ *
+ * `ctx.sql` refuses the writes that would set the columns (`assertNoReservedColumnWrite`), but
+ * that is a reading of SQL text, and a reading can miss a form — it did, twice. These hold
+ * whatever the text says:
+ *
+ * - **born** — `BEFORE INSERT`: a row is never inserted archived or trashed. Every row enters
+ *   active.
+ * - **moved** — `BEFORE UPDATE OF` the columns: a change to either aborts unless the kernel's
+ *   authorization row for this entity exists (`ENTITY_STATE_MOVES_TABLE`), which only a move
+ *   writes. An `UPDATE` that does not name the columns does not fire it.
+ *
+ * Drop-then-create, like the search triggers, and re-run after a dump load: a load drops the
+ * table and with it the triggers, then inserts the rows first — a restored binned row is
+ * legitimately born trashed, so the triggers are put back only after them.
+ */
+export declare function entityStateTriggerDdl(plan: EntityStatePlan): string;
+/** The two guard triggers `entityStateTriggerDdl` creates, each with its CREATE statement. */
+export declare function entityStateTriggerObjects(plan: EntityStatePlan): DerivedObject[];
+/**
+ * Add one module's plans to a scope's registry, refusing a second declaration of a type — the
+ * table is one module's, and two answers to "who may trash it" is no answer — and a key the
+ * module does not declare. The entity is the module's, so its keys are too: a key nobody
+ * declared reaches no role, no grant shape and no `PERMISSIONS.md`, and would make the verb
+ * look gated while nobody could ever pass it.
+ */
+export declare function addStatePlans(byType: Map<string, EntityStatePlan>, moduleId: string, declarations: readonly EntityStateDeclaration[] | undefined, declaredKeys: readonly {
+    readonly key: string;
+}[]): void;
+/** The tables whose rows carry the columns, lowercased as SQLite resolves a name — `guardSpine`'s input. */
+export declare const statefulTablesOf: (plans: ReadonlyMap<string, EntityStatePlan>) => ReadonlySet<string>;
+/** The columns a plan has, for code that only needs to know which views exist. */
+export interface StateColumns {
+    readonly archive: boolean;
+    readonly trash: boolean;
+}
+export declare const stateColumnsOf: (plan: EntityStatePlan) => StateColumns;
+/** The views an entity with these columns has — `active` always, then one per column. */
+export declare function viewsOf(columns: StateColumns): EntityStateName[];
+/**
+ * The predicate selecting one view's rows, over bare column names or `alias.`-qualified ones.
+ *
+ * **Spelled one way, everywhere.** A partial index is used only when the query's `WHERE`
+ * contains the index's own terms, so the list index DDL and the list query both come from
+ * here — a reworded copy would plan a scan in production and pass every test.
+ *
+ * `columns` absent is an entity that declares no state: every row is active, so there is no
+ * predicate. A view the entity does not have is refused rather than answered empty — asking
+ * an entity with no trash for its trashed rows is a wiring mistake, and an empty page would
+ * read as an empty bin.
+ */
+export declare function entityStateWhere(entityType: string, columns: StateColumns, view: EntityStateName, alias?: string): string;
+export declare function entityStateWhere(entityType: string, columns: StateColumns | undefined, view: EntityStateName | undefined, alias?: string): string | undefined;
+/** The two columns as one row holds them. */
+export interface StateRow {
+    readonly archived_at: string | null;
+    readonly trashed_at: string | null;
+}
+/** One row's two columns, or `undefined` when the row does not exist. */
+export declare function readStateRow(sql: ScopedSql, plan: EntityStatePlan, entityId: string): StateRow | undefined;
+/**
+ * The plan for `entityType`, and the key one of its states is gated on — or `validation_failed`
+ * naming what the entity does not declare. Shared by the verbs and the trashed readers, so
+ * "declares no trash" is one sentence.
+ */
+export declare function stateKeyOf(plans: ReadonlyMap<string, EntityStatePlan>, verb: string, entityType: string, which: 'archive' | 'trash'): {
+    plan: EntityStatePlan;
+    key: PermissionKey;
+};
+/** What the verbs need from the adapter. */
+export interface EntityStateDeps {
+    /** RAW access inside the operation's own transaction — the guarded `ctx.sql` refuses these columns. */
+    sql: ScopedSql;
+    /** entity type → its plan, for every registered module. */
+    plans: ReadonlyMap<string, EntityStatePlan>;
+    /** The operation's instant — what each column is stamped with. */
+    now: Instant;
+    check: StateCheck;
+    /** `ctx.emit`'s kernel writer — stamps the actor, the authorization chain and the operation. */
+    emit: (event: DomainEventInput) => void;
+    /** K-42's read-only refusal, for the effecting verbs. */
+    assertWrites: (verb: string) => void;
+}
+/** The verbs, as `OperationContext` carries them. */
+export type EntityStateVerbs = Pick<OperationContext, 'archive' | 'unarchive' | 'trash' | 'restore' | 'entityState'>;
+export declare function createEntityStateVerbs(deps: EntityStateDeps): EntityStateVerbs;
+//# sourceMappingURL=entity-state.d.ts.map

package/dist/entity-state.d.ts.map

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

package/dist/entity-state.js

@@ -0,0 +1,356 @@
+/**
+ * Entity archive and trash (#119): the kernel half, written once — both adapters hand
+ * `createEntityStateVerbs` the same things, the way `createEntityEdgeVerbs` is shared.
+ *
+ * ## What the kernel owns, and what it leaves to the vertical
+ *
+ * | Kernel | Vertical |
+ * |---|---|
+ * | The two columns on the entity's table, added by a derived migration | Which entities declare `archive` / `trash`, and the keys |
+ * | The transitions, their refusals, and the event each one emits | The operations that call the verbs, and their routes |
+ * | The declared key, re-checked on the entity by every verb and every trashed read | What an archived row looks like on a screen |
+ * | `ctx.page` / `ctx.search` leaving archived and trashed rows out by default | Its own hand-written `SELECT`s — see the gap below |
+ *
+ * ## The state is two columns
+ *
+ * `_substrat_archived_at` and `_substrat_trashed_at`, each an ISO instant or NULL. Apart, not
+ * one enum, so a trash never forgets an archive: `restore` clears the trash and leaves the
+ * archive, and an archived row that went to the bin comes back archived. The visible state is
+ * derived (contracts `entity-state.ts`): trashed, else archived, else active.
+ *
+ * Module code cannot write either column: `ctx.sql` refuses a write naming a `_substrat_*`
+ * column (`spine-guard.ts`), so the only way into or out of the trash is a verb that checks
+ * the key and emits the event. It can READ them, which is how a vertical's own `SELECT` keeps
+ * archived rows out of a screen `ctx.page` does not compose.
+ *
+ * ## The gap, stated
+ *
+ * The kernel filters the reads it composes — `ctx.page` and `ctx.search` — and nothing else.
+ * A handler's own `SELECT … FROM todo_lists WHERE id = ?` sees an archived or trashed row
+ * exactly as before. That is the honest limit of a kernel that does not parse module SQL:
+ * a get-by-id asks `ctx.entityState(ref)` and decides, and a hand-written list adds the
+ * predicate itself (`entityStateWhere`).
+ *
+ * ## Trash is not erasure, and not tenant deletion
+ *
+ * Trash keeps the row and every event about it. Subject erasure (#37) reaches a trashed row
+ * exactly as it reaches any other, because the row never moved tables; a tenant's deletion
+ * (#36) removes it with everything else. Nothing here extends a retention or shortens one.
+ */
+import { ARCHIVED_AT_COLUMN, ENTITY_ARCHIVED, ENTITY_RESTORED, ENTITY_TRASHED, ENTITY_UNARCHIVED, TRASHED_AT_COLUMN, entityStateChangedPayload, substratError, } from '@substrat-run/contracts';
+import { assertAllowed } from './permission-checker.js';
+import { assertSqlIdentifier } from './sql-identifier.js';
+/**
+ * Resolve one module's declarations. Refuses rather than skips, for `searchIndexPlans`'s
+ * reason: a declaration the author believes is live that silently is not leaves a trashed
+ * row in every list with no error anywhere.
+ */
+export function entityStatePlans(moduleId, declarations) {
+    if (!declarations?.length)
+        return [];
+    const plans = [];
+    const seen = new Set();
+    for (const decl of declarations) {
+        const where = `${moduleId} entityStates['${decl.entityType}']`;
+        if (seen.has(decl.entityType))
+            throw new Error(`entity state: ${where} is declared twice`);
+        seen.add(decl.entityType);
+        if (!decl.table) {
+            throw new Error(`entity state: ${where} carries no table — declare \`archive\`/\`trash\` on the entity and ` +
+                'spread `manifestEntities()`, so the entity registry supplies it');
+        }
+        if (!decl.archivePermission && !decl.trashPermission) {
+            throw new Error(`entity state: ${where} declares neither an archive nor a trash permission`);
+        }
+        if (decl.purgeAfterDays !== undefined && !decl.trashPermission) {
+            throw new Error(`entity state: ${where} declares a purge horizon and no trash — only a trashed entity is purged`);
+        }
+        plans.push({
+            moduleId,
+            entityType: decl.entityType,
+            table: assertSqlIdentifier('entity state', 'a table', decl.table, where),
+            idColumn: assertSqlIdentifier('entity state', 'an id column', decl.idColumn ?? 'id', where),
+            ...(decl.archivePermission ? { archivePermission: decl.archivePermission } : {}),
+            ...(decl.trashPermission ? { trashPermission: decl.trashPermission } : {}),
+            ...(decl.purgeAfterDays !== undefined ? { purgeAfterDays: decl.purgeAfterDays } : {}),
+        });
+    }
+    return plans;
+}
+/**
+ * The migrations that add the columns — one per column, so declaring `trash` on an entity
+ * that already declared `archive` adds one column and re-runs nothing.
+ *
+ * **The version is the declaration**, as for search and list indexes. Unlike theirs, this DDL
+ * is not drop-then-create: a column holds the state, and dropping it would un-trash every row.
+ * So it runs once per column, ever. Withdrawing a declaration leaves the column where it is,
+ * holding what it held; re-declaring it finds the migration already applied.
+ *
+ * Applied after the module's own migrations (the table must exist) and before its list
+ * indexes (their partial `WHERE` names these columns) — `moduleMigrations` writes that order.
+ */
+export function entityStateMigrations(moduleId, declarations) {
+    const out = [];
+    for (const plan of entityStatePlans(moduleId, declarations)) {
+        for (const { version, column } of stateColumnVersionsOf(plan)) {
+            out.push({ version, sql: `ALTER TABLE ${plan.table} ADD COLUMN ${column} TEXT;` });
+        }
+        // After the columns they name.
+        out.push({ version: entityStateGuardVersion(plan), sql: entityStateTriggerDdl(plan) });
+        // The purge sweep's walk (#119): the oldest trashed rows first, without reading the rest of
+        // the bin. Its own version, so declaring a horizon later adds it and re-runs nothing.
+        if (plan.purgeAfterDays !== undefined)
+            out.push({ version: purgeIndexVersion(plan), sql: purgeIndexDdl(plan) });
+    }
+    return out;
+}
+/** The column migrations' versions, and the column each adds — what the journal says a table holds. */
+export const stateColumnVersionsOf = (plan) => [
+    ...(plan.archivePermission ? [{ version: `state/${plan.entityType}:archive`, column: ARCHIVED_AT_COLUMN }] : []),
+    ...(plan.trashPermission ? [{ version: `state/${plan.entityType}:trash`, column: TRASHED_AT_COLUMN }] : []),
+];
+/** The purge index's migration version (#119) — present only on a plan with a purge horizon. */
+export const purgeIndexVersion = (plan) => `state/${plan.entityType}:purge`;
+/**
+ * The partial index the purge sweep walks (#119): trashed rows only, oldest trash first, so a
+ * sweep reads the due rows and nothing else. Its name is kernel-prefixed, so the reserved
+ * namespace. Empty for a plan without a purge horizon.
+ */
+export function purgeIndexObjects(plan) {
+    if (plan.purgeAfterDays === undefined)
+        return [];
+    const name = `_substrat_purge_${plan.table}`;
+    return [
+        {
+            name,
+            type: 'index',
+            table: plan.table,
+            sql: `CREATE INDEX ${name} ON ${plan.table} (${TRASHED_AT_COLUMN}, ${plan.idColumn}) WHERE ${TRASHED_AT_COLUMN} IS NOT NULL`,
+        },
+    ];
+}
+/**
+ * The purge index's DDL. `IF NOT EXISTS` because a dump load runs it again after the rows are
+ * in; a repair that finds it wrong drops it first (`purgeIndexRepairDdl`).
+ */
+export function purgeIndexDdl(plan) {
+    return purgeIndexObjects(plan)
+        .map((idx) => `${idx.sql.replace(/^CREATE INDEX /, 'CREATE INDEX IF NOT EXISTS ')};`)
+        .join('\n');
+}
+/** Drop-then-create, for a purge index the catalogue holds under its name but not as emitted. */
+export function purgeIndexRepairDdl(plan) {
+    return purgeIndexObjects(plan)
+        .flatMap((idx) => [`DROP INDEX IF EXISTS ${idx.name};`, `${idx.sql};`])
+        .join('\n');
+}
+/**
+ * The guard triggers' version. By which columns they guard, so declaring a trash on an
+ * archivable entity rebuilds them to guard both.
+ */
+export const entityStateGuardVersion = (plan) => {
+    const { archive, trash } = stateColumnsOf(plan);
+    return `state/${plan.entityType}:guard:${[...(archive ? ['archive'] : []), ...(trash ? ['trash'] : [])].join('+')}`;
+};
+/** The prefix of every trigger this module derives — kernel-owned, so the reserved one. */
+export const ENTITY_STATE_TRIGGER_PREFIX = '_substrat_state_';
+/**
+ * The kernel's authorization for ONE move (#119, Codex r2): the row `ctx.archive` & co. write
+ * just before their `UPDATE` and delete just after it, in the same transaction. The update
+ * trigger below refuses any change to the columns that has no such row — so the only writer the
+ * columns admit is the one that can write a `_substrat_*` TABLE, which `ctx.sql` refuses by name
+ * (a far simpler reading than finding an assignment target in an expression).
+ *
+ * Never holds a row between operations: written and removed inside one move, and a move that
+ * throws rolls back with its operation. Shared by both adapters' `KERNEL_DDL`, like the other
+ * kernel-owned spine tables, so the two cannot part company.
+ */
+export const ENTITY_STATE_MOVES_TABLE = '_substrat_state_moves';
+export const ENTITY_STATE_MOVES_DDL = `
+  CREATE TABLE IF NOT EXISTS _substrat_state_moves (
+    entity_type TEXT NOT NULL,
+    entity_id TEXT NOT NULL,
+    PRIMARY KEY (entity_type, entity_id)
+  );
+`;
+/** A string literal for SQL text: the entity type is a declaration, still quoted rather than trusted. */
+const literal = (value) => `'${value.replace(/'/g, "''")}'`;
+/**
+ * The invariant below the column guard, as two triggers on the entity's table.
+ *
+ * `ctx.sql` refuses the writes that would set the columns (`assertNoReservedColumnWrite`), but
+ * that is a reading of SQL text, and a reading can miss a form — it did, twice. These hold
+ * whatever the text says:
+ *
+ * - **born** — `BEFORE INSERT`: a row is never inserted archived or trashed. Every row enters
+ *   active.
+ * - **moved** — `BEFORE UPDATE OF` the columns: a change to either aborts unless the kernel's
+ *   authorization row for this entity exists (`ENTITY_STATE_MOVES_TABLE`), which only a move
+ *   writes. An `UPDATE` that does not name the columns does not fire it.
+ *
+ * Drop-then-create, like the search triggers, and re-run after a dump load: a load drops the
+ * table and with it the triggers, then inserts the rows first — a restored binned row is
+ * legitimately born trashed, so the triggers are put back only after them.
+ */
+export function entityStateTriggerDdl(plan) {
+    return entityStateTriggerObjects(plan)
+        .flatMap((t) => [`DROP TRIGGER IF EXISTS ${t.name};`, `${t.sql};`])
+        .join('\n');
+}
+/** The two guard triggers `entityStateTriggerDdl` creates, each with its CREATE statement. */
+export function entityStateTriggerObjects(plan) {
+    const born = `${ENTITY_STATE_TRIGGER_PREFIX}${plan.table}_born`;
+    const moved = `${ENTITY_STATE_TRIGGER_PREFIX}${plan.table}_moved`;
+    const columns = stateColumnVersionsOf(plan).map((c) => c.column);
+    const trigger = (name, lines) => ({ name, type: 'trigger', table: plan.table, sql: lines.join('\n') });
+    return [
+        trigger(born, [
+            `CREATE TRIGGER ${born} BEFORE INSERT ON ${plan.table} WHEN ${columns.map((c) => `NEW.${c} IS NOT NULL`).join(' OR ')} BEGIN`,
+            `  SELECT RAISE(ABORT, 'a row is never inserted archived or trashed - ctx.archive and ctx.trash move it (#119)');`,
+            `END`,
+        ]),
+        trigger(moved, [
+            `CREATE TRIGGER ${moved} BEFORE UPDATE OF ${columns.join(', ')} ON ${plan.table}`,
+            `WHEN NOT EXISTS (SELECT 1 FROM ${ENTITY_STATE_MOVES_TABLE} WHERE entity_type = ${literal(plan.entityType)} AND entity_id = OLD.${plan.idColumn}) BEGIN`,
+            `  SELECT RAISE(ABORT, 'archive and trash state moves only through ctx.archive, ctx.trash and ctx.restore (#119)');`,
+            `END`,
+        ]),
+    ];
+}
+/**
+ * Add one module's plans to a scope's registry, refusing a second declaration of a type — the
+ * table is one module's, and two answers to "who may trash it" is no answer — and a key the
+ * module does not declare. The entity is the module's, so its keys are too: a key nobody
+ * declared reaches no role, no grant shape and no `PERMISSIONS.md`, and would make the verb
+ * look gated while nobody could ever pass it.
+ */
+export function addStatePlans(byType, moduleId, declarations, declaredKeys) {
+    for (const plan of entityStatePlans(moduleId, declarations)) {
+        for (const key of [plan.archivePermission, plan.trashPermission]) {
+            if (key && !declaredKeys.some((p) => p.key === key)) {
+                throw new Error(`entity state: ${moduleId} gates '${plan.entityType}' on '${key}', which it does not declare in \`permissions\``);
+            }
+        }
+        const existing = byType.get(plan.entityType);
+        if (existing) {
+            throw new Error(`entity state: '${plan.entityType}' is declared archivable/trashable by both ` +
+                `'${existing.moduleId}' and '${plan.moduleId}' — one entity type, one owner`);
+        }
+        byType.set(plan.entityType, plan);
+    }
+}
+/** The tables whose rows carry the columns, lowercased as SQLite resolves a name — `guardSpine`'s input. */
+export const statefulTablesOf = (plans) => new Set([...plans.values()].map((p) => p.table.toLowerCase()));
+export const stateColumnsOf = (plan) => ({
+    archive: plan.archivePermission !== undefined,
+    trash: plan.trashPermission !== undefined,
+});
+/** The views an entity with these columns has — `active` always, then one per column. */
+export function viewsOf(columns) {
+    return ['active', ...(columns.archive ? ['archived'] : []), ...(columns.trash ? ['trashed'] : [])];
+}
+export function entityStateWhere(entityType, columns, view, alias) {
+    const asked = view ?? 'active';
+    if ((asked === 'archived' && !columns?.archive) || (asked === 'trashed' && !columns?.trash)) {
+        throw substratError('validation_failed', `'${entityType}' has no ${asked} view — it declares no ${asked === 'archived' ? 'archive' : 'trash'}`, { errors: [{ path: 'view', message: `not declared for '${entityType}'` }] });
+    }
+    if (!columns)
+        return undefined;
+    const col = (name) => (alias ? `${alias}.${name}` : name);
+    if (asked === 'trashed')
+        return `${col(TRASHED_AT_COLUMN)} IS NOT NULL`;
+    const terms = [];
+    if (columns.archive)
+        terms.push(`${col(ARCHIVED_AT_COLUMN)} IS ${asked === 'archived' ? 'NOT ' : ''}NULL`);
+    if (columns.trash)
+        terms.push(`${col(TRASHED_AT_COLUMN)} IS NULL`);
+    return terms.join(' AND ');
+}
+const stateOf = (row) => row.trashed_at !== null ? 'trashed' : row.archived_at !== null ? 'archived' : 'active';
+/** One row's two columns, or `undefined` when the row does not exist. */
+export function readStateRow(sql, plan, entityId) {
+    const columns = stateColumnsOf(plan);
+    return sql.query(`SELECT ${columns.archive ? ARCHIVED_AT_COLUMN : 'NULL'} AS archived_at, ` +
+        `${columns.trash ? TRASHED_AT_COLUMN : 'NULL'} AS trashed_at ` +
+        `FROM ${plan.table} WHERE ${plan.idColumn} = ?`, [entityId])[0];
+}
+/**
+ * The plan for `entityType`, and the key one of its states is gated on — or `validation_failed`
+ * naming what the entity does not declare. Shared by the verbs and the trashed readers, so
+ * "declares no trash" is one sentence.
+ */
+export function stateKeyOf(plans, verb, entityType, which) {
+    const plan = plans.get(entityType);
+    const key = which === 'archive' ? plan?.archivePermission : plan?.trashPermission;
+    if (!plan || !key) {
+        throw substratError('validation_failed', `${verb}: '${entityType}' declares no ${which}`, {
+            errors: [{ path: 'entityType', message: `'${entityType}' declares no ${which}` }],
+        });
+    }
+    return { plan, key };
+}
+const COLUMN = { archived_at: ARCHIVED_AT_COLUMN, trashed_at: TRASHED_AT_COLUMN };
+const MOVES = {
+    archive: { verb: 'ctx.archive', which: 'archive', from: ['active'], column: 'archived_at', set: true, type: ENTITY_ARCHIVED },
+    unarchive: { verb: 'ctx.unarchive', which: 'archive', from: ['archived'], column: 'archived_at', set: false, type: ENTITY_UNARCHIVED },
+    // Archived rows may be trashed: "delete this old thing" is the commonest reason to open an
+    // archive at all. The archive survives the trip, which is what `restore` relies on.
+    trash: { verb: 'ctx.trash', which: 'trash', from: ['active', 'archived'], column: 'trashed_at', set: true, type: ENTITY_TRASHED },
+    restore: { verb: 'ctx.restore', which: 'trash', from: ['trashed'], column: 'trashed_at', set: false, type: ENTITY_RESTORED },
+};
+export function createEntityStateVerbs(deps) {
+    const move = async (m, entity) => {
+        deps.assertWrites(m.verb);
+        const { plan, key } = stateKeyOf(deps.plans, m.verb, entity.entityType, m.which);
+        // The DECLARED key, on THIS entity, before anything about the row is read: whether it
+        // exists is not something a caller without the key gets to learn.
+        assertAllowed(await deps.check(key, entity));
+        const row = readStateRow(deps.sql, plan, entity.entityId);
+        if (!row) {
+            throw substratError('not_found', `${m.verb}: ${entity.entityType}:${entity.entityId} does not exist`);
+        }
+        const from = stateOf(row);
+        if (!m.from.includes(from)) {
+            throw substratError('conflict', `${m.verb}: ${entity.entityType}:${entity.entityId} is ${from} — ` +
+                `only ${m.from.join(' or ')} can be moved this way`, { reason: 'invalid_transition' });
+        }
+        const at = m.set ? deps.now : null;
+        // The authorization the update trigger asks for, held for exactly this one statement.
+        const authorize = [entity.entityType, entity.entityId];
+        deps.sql.exec(`INSERT OR IGNORE INTO ${ENTITY_STATE_MOVES_TABLE} (entity_type, entity_id) VALUES (?, ?)`, authorize);
+        try {
+            const { changes } = deps.sql.exec(`UPDATE ${plan.table} SET ${COLUMN[m.column]} = ? WHERE ${plan.idColumn} = ?`, [
+                at,
+                entity.entityId,
+            ]);
+            // The row exists (read above), so an UPDATE that changed nothing was swallowed — a trigger's
+            // RAISE(IGNORE), say. Recording a move that did not happen is the one thing this must not do.
+            // `0`, not `!== 1`: a Durable Object's count includes the index rows the move rewrote.
+            if (changes === 0) {
+                throw substratError('internal', `${m.verb}: the update of ${entity.entityType}:${entity.entityId} changed no row — nothing was recorded`);
+            }
+        }
+        finally {
+            deps.sql.exec(`DELETE FROM ${ENTITY_STATE_MOVES_TABLE} WHERE entity_type = ? AND entity_id = ?`, authorize);
+        }
+        const to = stateOf({ ...row, [m.column]: at });
+        const payload = entityStateChangedPayload.parse({ entity, from, to }); // strips extra keys
+        deps.emit({ type: m.type, schemaVersion: 1, entity: payload.entity, piiClass: 'none', payload });
+        return to;
+    };
+    return {
+        archive: (entity) => move(MOVES.archive, entity),
+        unarchive: (entity) => move(MOVES.unarchive, entity),
+        trash: (entity) => move(MOVES.trash, entity),
+        restore: (entity) => move(MOVES.restore, entity),
+        entityState: (entity) => {
+            const plan = deps.plans.get(entity.entityType);
+            if (!plan) {
+                throw substratError('validation_failed', `ctx.entityState: '${entity.entityType}' declares no archive or trash — declare one on the entity`);
+            }
+            const row = readStateRow(deps.sql, plan, entity.entityId);
+            return row ? stateOf(row) : null;
+        },
+    };
+}
+//# sourceMappingURL=entity-state.js.map

package/dist/entity-state.js.map

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