@substrat-run/kernel 0.138.0 → 0.139.0

package/dist/entity-state-reads.js

@@ -0,0 +1,135 @@
+/**
+ * The kernel-composed reads over archivable and trashable entities (#119), written once for
+ * both adapters: the view predicate `ctx.page`/`ctx.search` add, and the two trashed readers.
+ *
+ * Kept apart from `entity-state.ts` because these need the list and search composers, and those
+ * need the view predicate from there — one direction of import, not a cycle.
+ */
+import { listLimitOf, substratError, } from '@substrat-run/contracts';
+import { entityStateWhere, stateColumnsOf, stateKeyOf } from './entity-state.js';
+import { cursorOf, listQuery, NotListable } from './list-index.js';
+import { NotSearchable, searchLimit, searchMatchExpression, searchQuery, } from './search-index.js';
+/**
+ * Refuse the bin on the UNCHECKED readers. `ctx.page` and `ctx.search` check no permission, so
+ * the trashed view is not theirs to serve — it reaches them as a string from the wire as easily
+ * as from code, and must be refused there rather than answered.
+ */
+export function uncheckedView(verb, entityType, view) {
+    if (view !== 'trashed')
+        return view;
+    throw substratError('validation_failed', `${verb}: the trash of '${entityType}' is read with ${verb === 'ctx.page' ? 'ctx.pageTrashed' : 'ctx.searchTrashed'}, ` +
+        'which checks the declared trash key on every row', { errors: [{ path: 'view', message: 'trashed is not a view of this read' }] });
+}
+/**
+ * The `src`-aliased predicate a search over `entityType` adds for `view`, or `undefined` when
+ * the entity declares no state (every row is active).
+ */
+export function searchStateWhere(statePlans, entityType, view) {
+    const plan = statePlans.get(entityType);
+    return entityStateWhere(entityType, plan && stateColumnsOf(plan), uncheckedView('ctx.search', entityType, view), 'src');
+}
+/**
+ * How many binned rows one `ctx.pageTrashed` call reads, at most, looking for rows the caller
+ * may see. Each costs a permission check, and a Durable Object has a CPU budget per request, so
+ * a bin full of other people's rows cannot be walked without bound inside one call.
+ */
+export const TRASH_SCAN_BUDGET = 2_000;
+/**
+ * Keep the rows of a trashed read the caller may see in the bin.
+ *
+ * The declared trash key is checked per row, inside the kernel, so a handler cannot forget it:
+ * a member who holds the key on their own lists sees their own bin and nobody else's. Per row
+ * because the key is usually entity-narrowed; a scope-wide holder passes every row and pays one
+ * cheap check each.
+ */
+async function keepVisible(check, key, entityType, rows, idOf) {
+    const kept = [];
+    for (const row of rows) {
+        const entity = { entityType, entityId: idOf(row) };
+        if ((await check(key, entity)).allowed)
+            kept.push(row);
+    }
+    return kept;
+}
+export function createTrashedReads(deps) {
+    return {
+        /**
+         * The bin, walked so that **no position of a row the caller may not see ever leaves the
+         * kernel.** A cursor is a row's sort value and id, so minting one from a refused row would
+         * hand the caller that row's id and timestamp — the very thing the per-row check withholds.
+         *
+         * So the walk runs internally past refused rows until it has `limit` visible ones or reaches
+         * the end, and the cursor is minted from the last VISIBLE row of a FULL page. Past
+         * `TRASH_SCAN_BUDGET` rows it stops, and a page that stops short of `limit` — at the end or
+         * at the budget — answers the same way either way: the visible rows it found, and no cursor.
+         * A cursor on a short page would say "the budget ran out", which is the bin's size again.
+         *
+         * That answer can be wrong: a page that stops at the budget truncates the walk silently, and
+         * a caller whose rows sit more than the budget past the previous one's never sees them. It is chosen over the alternatives on purpose. A cursor
+         * would carry a hidden row's position (the leak above), and a refusal — or a count in a
+         * message — tells the caller the bin holds more than the budget of rows they cannot see,
+         * which is its own disclosure. Only a sealed (authenticated, opaque) continuation can carry
+         * the walk on without saying where it is, and a hosted scope holds no key to seal one with
+         * (K-45). Until then the walk ends early, silently, and K-45 says so.
+         */
+        async pageTrashed(entityType, params) {
+            const { key } = stateKeyOf(deps.statePlans, 'ctx.pageTrashed', entityType, 'trash');
+            const plan = deps.listPlans.get(entityType);
+            if (!plan)
+                throw new NotListable(entityType);
+            if (params.total) {
+                throw substratError('validation_failed', 'ctx.pageTrashed: a trashed page carries no total — a count over rows the caller may not see would disclose them');
+            }
+            const limit = listLimitOf(params.limit);
+            const budget = deps.scanBudget ?? TRASH_SCAN_BUDGET;
+            const kept = [];
+            let cursor = params.cursor;
+            let scanned = 0;
+            let sortColumn = '';
+            let order = 'asc';
+            for (;;) {
+                const batch = Math.min(limit, budget - scanned);
+                const q = listQuery(plan, {
+                    limit: batch,
+                    sort: params.sort,
+                    order: params.order,
+                    cursor,
+                    filters: params.filters,
+                    view: 'trashed',
+                });
+                ({ sortColumn, order } = q);
+                const rows = deps.query(q.sql, q.params);
+                for (const row of rows) {
+                    scanned += 1;
+                    const entity = { entityType, entityId: String(row[plan.idColumn]) };
+                    if (!(await deps.check(key, entity)).allowed)
+                        continue;
+                    kept.push(row);
+                    if (kept.length === limit) {
+                        return { entries: kept, nextCursor: cursorOf(row, sortColumn, plan.idColumn, order, 'trashed') };
+                    }
+                }
+                // A short batch is the end of the bin: nothing after it, so no cursor at all.
+                if (rows.length < batch)
+                    return { entries: kept, nextCursor: null };
+                // Internal only — never returned while it points at a refused row.
+                cursor = cursorOf(rows[rows.length - 1], sortColumn, plan.idColumn, order, 'trashed');
+                if (scanned >= budget)
+                    break;
+            }
+            // Fewer than `limit` visible rows, and the budget spent: answered exactly as the end of the
+            // bin is — whatever was found, and no cursor — deliberately; see above.
+            return { entries: kept, nextCursor: null };
+        },
+        async searchTrashed(entityType, term, options) {
+            const { plan: state, key } = stateKeyOf(deps.statePlans, 'ctx.searchTrashed', entityType, 'trash');
+            const plan = deps.searchPlans.get(entityType);
+            if (!plan)
+                throw new NotSearchable(entityType);
+            const q = searchQuery(plan, searchMatchExpression(term, plan.tokenizer), searchLimit(options?.limit), entityStateWhere(entityType, stateColumnsOf(state), 'trashed', 'src'));
+            const hits = deps.query(q.sql, q.params).map((row) => ({ entityType, id: row.id, rank: row.rank }));
+            return keepVisible(deps.check, key, entityType, hits, (hit) => hit.id);
+        },
+    };
+}
+//# sourceMappingURL=entity-state-reads.js.map

package/dist/entity-state-reads.js.map

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

package/dist/entity-state.d.ts

@@ -0,0 +1,177 @@
+/**
+ * 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';
+/** 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;
+}
+/** 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 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;
+/**
+ * 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 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;
+/**
+ * After runtime DDL (#119, Codex r3): does every stateful table still carry what the kernel
+ * derived for it? The guard refuses the DDL known to take it away; this is the check that does not
+ * depend on having known. Read from `main`'s own catalogue, so a same-named temp object cannot
+ * stand in for the real table. Throws — the operation and its DDL roll back — rather than
+ * re-deriving: a schema the kernel did not expect is not one to repair silently.
+ *
+ * `indexes` names the derived list indexes each stateful table must keep, by table.
+ */
+export declare function assertEntityStateIntact(sql: ScopedSql, plans: ReadonlyMap<string, EntityStatePlan>, indexes?: ReadonlyMap<string, readonly string[]>): void;
+//# 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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"}