@substrat-run/kernel 0.139.0 → 0.141.0

package/dist/derived-object.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derived-object.js","sourceRoot":"","sources":["../src/derived-object.ts"],"names":[],"mappings":""}

package/dist/derived-objects.d.ts

@@ -0,0 +1,108 @@
+/**
+ * What the kernel derived onto a module's tables, checked and put back (#2090).
+ *
+ * | Object | Is | When it is missing or not what the kernel emits |
+ * |---|---|---|
+ * | `_substrat_archived_at` / `_substrat_trashed_at` (#119) | state | fail closed: it cannot be invented again |
+ * | the `born` / `moved` archive/trash guard triggers (#119) | derived | put back |
+ * | the derived list indexes, partial per view on a stateful table (#811) | derived | put back |
+| the purge sweep's partial index on a trashable table with a horizon (#119) | derived | put back |
+ * | the search index and the three triggers keeping it in step (#827) | derived | rebuilt from the rows |
+ *
+ * The search triggers are a privacy fact, not only a freshness one: subject erasure rewrites a
+ * row's text and relies on the update and delete triggers to take the old text out of the index.
+ * Without them, erased text stays searchable.
+ *
+ * **An object is judged by its definition, not its name.** `sqlite_master` holds each one's
+ * CREATE statement as it was run, and the kernel knows the statement it emits
+ * (`DerivedObject`), so a same-named trigger that does nothing, an index on the wrong columns or
+ * with the wrong partial predicate, and an object filed under another table are all "not
+ * there". The text is compared exactly: nothing but the kernel writes these objects, and a
+ * normalisation that forgave whitespace would forgive it inside a string literal too — a guard
+ * keyed on a different entity type. An object an older kernel worded differently is re-created
+ * once.
+ *
+ * Four places ask, and all four come here, so "what a table is owed" is written once:
+ *
+ * - **runtime DDL** (`ctx.sql`'s after-DDL hook, #1811) repairs inside the operation's
+ *   transaction, whenever the scope has any derived plan. The text guard already refuses the DDL
+ *   known to move a stateful table's rows; a search-only or list-only table has no such guard,
+ *   and a module may rebuild it — this puts its triggers and indexes back before the operation
+ *   commits. A lost state column fails the operation, and the DDL with it.
+ * - **a migration** checks the state columns after its own SQL, inside its own transaction, so a
+ *   migration that drops one rolls back with nothing applied. The last migration of a pass then
+ *   repairs the derived objects, inside that same transaction: SQLite's ordinary
+ *   create-copy-rename rebuild of a table drops its triggers and indexes with it, and the
+ *   migrations that made them are journaled, so they never run again. Only after the last,
+ *   because a rebuild split over two migrations copies its rows in the second, and a guard put
+ *   back in between would refuse the archived ones — which also means such a split must ship
+ *   in ONE deploy: split over two, the guard is back before the copy runs.
+ * - **a wake with nothing pending** (and every `migrateScope`) repairs the same way, once per
+ *   instance. That is what reaches a scope stripped before this existed, whose migrations are
+ *   all journaled and will never run again.
+ * - **a restore** repairs after the rows, inside the load's transaction, which may legitimately
+ *   bring them archived or trashed.
+ *
+ * ## What the journal says a table is owed
+ *
+ * Every expectation comes from `_substrat_migrations`, not only from the declarations: a scope
+ * mid-upgrade has declared a trash its column migration has not added yet, and a restored dump
+ * carries the journal of the scope it came from. A column is owed once the migration that added
+ * it is journaled; a derived object once the migration that derived it, for the CURRENT
+ * declaration, is. An object from a withdrawn declaration is not this module's business.
+ */
+import { SubstratError } from '@substrat-run/contracts';
+import { type EntityStatePlan } from './entity-state.js';
+import { type ListIndexPlan } from './list-index.js';
+import type { ScopedSql } from './scope-host.js';
+import { type SearchIndexPlan } from './search-index.js';
+/** A scope's derivation inputs: every registered module's plans, entity type → plan. */
+export interface DerivedPlans {
+    readonly state: ReadonlyMap<string, EntityStatePlan>;
+    readonly lists: ReadonlyMap<string, ListIndexPlan>;
+    readonly search: ReadonlyMap<string, SearchIndexPlan>;
+}
+/**
+ * A table without a state column its journal says it has (`internal`). `migration` is the
+ * journaled `<module>@<version>` that added the column — what a scope failing closed on a wake,
+ * where no migration ran, records as its failure.
+ */
+export declare class StateColumnLost extends SubstratError {
+    readonly migration: string;
+    constructor(migration: string, message: string);
+}
+/**
+ * After runtime DDL, inside the operation's transaction: the same repair a migration pass makes.
+ * A lost state column throws `internal`, and the operation and its DDL roll back.
+ */
+export declare function afterRuntimeDdl(sql: ScopedSql, run: (ddl: string) => void, plans: DerivedPlans): void;
+/** Whether a scope has anything derived for `afterRuntimeDdl` to keep — the hook is installed only then. */
+export declare const derivesAnything: (plans: DerivedPlans) => boolean;
+/**
+ * A migration's half, after its own SQL and inside its own transaction: the state columns are
+ * still where the journal put them. A migration that dropped one throws here and rolls back —
+ * the rows keep their state, and the scope fails closed naming the migration.
+ */
+export declare function assertEntityStateColumns(sql: ScopedSql, plans: DerivedPlans, after: string): void;
+/**
+ * Check the state columns, then re-create every derived set the journal says a table is owed
+ * and the catalogue does not hold exactly as emitted. Run inside the caller's transaction, so a
+ * failure — a lost column, or DDL that will not apply — rolls the caller back whole.
+ *
+ * `run` executes a multi-statement script (a Durable Object splits it first). `after` names what
+ * left the schema this way, for the message. `absentTable: 'skip'` is a restore's: a table the
+ * dump did not carry is left absent, and owed nothing. Everywhere else an owed table that is
+ * gone has lost its state, and fails closed.
+ */
+export declare function repairDerivedObjects(sql: ScopedSql, run: (ddl: string) => void, plans: DerivedPlans, opts: {
+    readonly after: string;
+    readonly absentTable?: 'fail' | 'skip';
+}): void;
+/**
+ * Both adapters' migration pass, after one migration's SQL and inside its transaction: the
+ * column check, and — after the last migration of the pass — the derived objects repaired.
+ * `key` is `<module>@<version>`, which a failure names. A last entry the pass skips (journaled
+ * by a pass that ran first) needs nothing here: that pass repaired them after it.
+ */
+export declare function afterMigration(sql: ScopedSql, run: (ddl: string) => void, plans: DerivedPlans, key: string, last: boolean): void;
+//# sourceMappingURL=derived-objects.d.ts.map

package/dist/derived-objects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derived-objects.d.ts","sourceRoot":"","sources":["../src/derived-objects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAExD,OAAO,EAQL,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAoD,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACvG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAA0D,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEjH,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CACvD;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,aAAa;IAE9C,QAAQ,CAAC,SAAS,EAAE,MAAM;IAD5B,YACW,SAAS,EAAE,MAAM,EAC1B,OAAO,EAAE,MAAM,EAGhB;CACF;AAsHD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CAErG;AAED,4GAA4G;AAC5G,eAAO,MAAM,eAAe,UAAW,YAAY,KAAG,OACiB,CAAC;AAExE;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIjG;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,SAAS,EACd,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,EAC1B,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GACvE,IAAI,CAON;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,SAAS,EACd,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,EAC1B,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,OAAO,GACZ,IAAI,CAGN"}

package/dist/derived-objects.js

@@ -0,0 +1,199 @@
+/**
+ * What the kernel derived onto a module's tables, checked and put back (#2090).
+ *
+ * | Object | Is | When it is missing or not what the kernel emits |
+ * |---|---|---|
+ * | `_substrat_archived_at` / `_substrat_trashed_at` (#119) | state | fail closed: it cannot be invented again |
+ * | the `born` / `moved` archive/trash guard triggers (#119) | derived | put back |
+ * | the derived list indexes, partial per view on a stateful table (#811) | derived | put back |
+| the purge sweep's partial index on a trashable table with a horizon (#119) | derived | put back |
+ * | the search index and the three triggers keeping it in step (#827) | derived | rebuilt from the rows |
+ *
+ * The search triggers are a privacy fact, not only a freshness one: subject erasure rewrites a
+ * row's text and relies on the update and delete triggers to take the old text out of the index.
+ * Without them, erased text stays searchable.
+ *
+ * **An object is judged by its definition, not its name.** `sqlite_master` holds each one's
+ * CREATE statement as it was run, and the kernel knows the statement it emits
+ * (`DerivedObject`), so a same-named trigger that does nothing, an index on the wrong columns or
+ * with the wrong partial predicate, and an object filed under another table are all "not
+ * there". The text is compared exactly: nothing but the kernel writes these objects, and a
+ * normalisation that forgave whitespace would forgive it inside a string literal too — a guard
+ * keyed on a different entity type. An object an older kernel worded differently is re-created
+ * once.
+ *
+ * Four places ask, and all four come here, so "what a table is owed" is written once:
+ *
+ * - **runtime DDL** (`ctx.sql`'s after-DDL hook, #1811) repairs inside the operation's
+ *   transaction, whenever the scope has any derived plan. The text guard already refuses the DDL
+ *   known to move a stateful table's rows; a search-only or list-only table has no such guard,
+ *   and a module may rebuild it — this puts its triggers and indexes back before the operation
+ *   commits. A lost state column fails the operation, and the DDL with it.
+ * - **a migration** checks the state columns after its own SQL, inside its own transaction, so a
+ *   migration that drops one rolls back with nothing applied. The last migration of a pass then
+ *   repairs the derived objects, inside that same transaction: SQLite's ordinary
+ *   create-copy-rename rebuild of a table drops its triggers and indexes with it, and the
+ *   migrations that made them are journaled, so they never run again. Only after the last,
+ *   because a rebuild split over two migrations copies its rows in the second, and a guard put
+ *   back in between would refuse the archived ones — which also means such a split must ship
+ *   in ONE deploy: split over two, the guard is back before the copy runs.
+ * - **a wake with nothing pending** (and every `migrateScope`) repairs the same way, once per
+ *   instance. That is what reaches a scope stripped before this existed, whose migrations are
+ *   all journaled and will never run again.
+ * - **a restore** repairs after the rows, inside the load's transaction, which may legitimately
+ *   bring them archived or trashed.
+ *
+ * ## What the journal says a table is owed
+ *
+ * Every expectation comes from `_substrat_migrations`, not only from the declarations: a scope
+ * mid-upgrade has declared a trash its column migration has not added yet, and a restored dump
+ * carries the journal of the scope it came from. A column is owed once the migration that added
+ * it is journaled; a derived object once the migration that derived it, for the CURRENT
+ * declaration, is. An object from a withdrawn declaration is not this module's business.
+ */
+import { SubstratError } from '@substrat-run/contracts';
+import { entityStateGuardVersion, entityStateTriggerDdl, entityStateTriggerObjects, purgeIndexObjects, purgeIndexRepairDdl, purgeIndexVersion, stateColumnVersionsOf, } from './entity-state.js';
+import { listIndexDdl, listIndexObjects, listIndexVersion } from './list-index.js';
+import { searchIndexDdl, searchIndexObjects, searchIndexVersion } from './search-index.js';
+/**
+ * A table without a state column its journal says it has (`internal`). `migration` is the
+ * journaled `<module>@<version>` that added the column — what a scope failing closed on a wake,
+ * where no migration ran, records as its failure.
+ */
+export class StateColumnLost extends SubstratError {
+    migration;
+    constructor(migration, message) {
+        super('internal', message);
+        this.migration = migration;
+    }
+}
+/** `main`'s own catalogue by lowercased name — so a same-named temp object cannot stand in. */
+function catalogueOf(sql) {
+    return new Map(sql
+        .query(`SELECT type, name, tbl_name, sql FROM main.sqlite_master`)
+        .map((r) => [r.name.toLowerCase(), { type: r.type, table: r.tbl_name, sql: r.sql }]));
+}
+/** The first object of `d` the catalogue does not hold exactly as the kernel emits it. */
+const wrongIn = (catalogue, d) => d.objects.find((o) => {
+    const found = catalogue.get(o.name.toLowerCase());
+    return (found?.type !== o.type ||
+        found.table.toLowerCase() !== o.table.toLowerCase() ||
+        found.sql !== o.sql);
+});
+const columnsOn = (sql, table) => new Set(sql.query(`SELECT name FROM pragma_table_info(?, 'main')`, [table]).map((r) => r.name.toLowerCase()));
+function expectations(sql, plans) {
+    const journal = new Set(sql.query(`SELECT module_id, version FROM _substrat_migrations`).map((r) => `${r.module_id}@${r.version}`));
+    const applied = (moduleId, version) => journal.has(`${moduleId}@${version}`);
+    const byTable = new Map();
+    const entry = (table) => {
+        const key = table.toLowerCase();
+        if (!byTable.has(key))
+            byTable.set(key, { table, derived: [] });
+        return byTable.get(key);
+    };
+    for (const plan of plans.state.values()) {
+        const e = entry(plan.table);
+        const columns = stateColumnVersionsOf(plan)
+            .filter((c) => applied(plan.moduleId, c.version))
+            .map((c) => ({ column: c.column, migration: `${plan.moduleId}@${c.version}` }));
+        if (columns.length)
+            e.columns = columns;
+        if (applied(plan.moduleId, entityStateGuardVersion(plan))) {
+            e.derived.push({ objects: entityStateTriggerObjects(plan), ddl: entityStateTriggerDdl(plan) });
+        }
+        const purge = purgeIndexObjects(plan);
+        if (purge.length && applied(plan.moduleId, purgeIndexVersion(plan))) {
+            e.derived.push({ objects: purge, ddl: purgeIndexRepairDdl(plan) });
+        }
+    }
+    for (const plan of plans.lists.values()) {
+        const objects = listIndexObjects(plan);
+        if (objects.length && applied(plan.moduleId, listIndexVersion(plan))) {
+            entry(plan.table).derived.push({ objects, ddl: listIndexDdl(plan) });
+        }
+    }
+    // The DDL ends in a full `rebuild` from the content table, which is also what repairs an index
+    // that went stale while its triggers were gone or wrong.
+    for (const plan of plans.search.values()) {
+        if (applied(plan.moduleId, searchIndexVersion(plan))) {
+            entry(plan.table).derived.push({ objects: searchIndexObjects(plan), ddl: searchIndexDdl(plan) });
+        }
+    }
+    return [...byTable.values()];
+}
+const lost = (after, table, what, migration) => {
+    throw new StateColumnLost(migration, `${after} left '${table.table}' without ${what} — its archive/trash guarantees depend on it; nothing was changed`);
+};
+/**
+ * The state half: the table holds every column its journal added. Throws `StateColumnLost` on
+ * the first one gone. An absent table counts as losing them all, unless `absentTable` is
+ * `'skip'` — a restore's case, where a dump that did not carry a table is not made to invent one.
+ */
+function assertColumns(sql, catalogue, table, after, absentTable = 'fail') {
+    if (!table.columns)
+        return;
+    if (catalogue.get(table.table.toLowerCase())?.type !== 'table') {
+        if (absentTable === 'skip')
+            return;
+        lost(after, table, 'its table', table.columns[0].migration);
+    }
+    const present = columnsOn(sql, table.table);
+    for (const c of table.columns)
+        if (!present.has(c.column))
+            lost(after, table, c.column, c.migration);
+}
+/**
+ * After runtime DDL, inside the operation's transaction: the same repair a migration pass makes.
+ * A lost state column throws `internal`, and the operation and its DDL roll back.
+ */
+export function afterRuntimeDdl(sql, run, plans) {
+    repairDerivedObjects(sql, run, plans, { after: 'runtime DDL' });
+}
+/** Whether a scope has anything derived for `afterRuntimeDdl` to keep — the hook is installed only then. */
+export const derivesAnything = (plans) => plans.state.size > 0 || plans.lists.size > 0 || plans.search.size > 0;
+/**
+ * A migration's half, after its own SQL and inside its own transaction: the state columns are
+ * still where the journal put them. A migration that dropped one throws here and rolls back —
+ * the rows keep their state, and the scope fails closed naming the migration.
+ */
+export function assertEntityStateColumns(sql, plans, after) {
+    if (plans.state.size === 0)
+        return; // most scopes: nothing holds state, so no read at all
+    const catalogue = catalogueOf(sql);
+    for (const table of expectations(sql, plans))
+        assertColumns(sql, catalogue, table, after);
+}
+/**
+ * Check the state columns, then re-create every derived set the journal says a table is owed
+ * and the catalogue does not hold exactly as emitted. Run inside the caller's transaction, so a
+ * failure — a lost column, or DDL that will not apply — rolls the caller back whole.
+ *
+ * `run` executes a multi-statement script (a Durable Object splits it first). `after` names what
+ * left the schema this way, for the message. `absentTable: 'skip'` is a restore's: a table the
+ * dump did not carry is left absent, and owed nothing. Everywhere else an owed table that is
+ * gone has lost its state, and fails closed.
+ */
+export function repairDerivedObjects(sql, run, plans, opts) {
+    const catalogue = catalogueOf(sql);
+    for (const table of expectations(sql, plans)) {
+        assertColumns(sql, catalogue, table, opts.after, opts.absentTable);
+        if (catalogue.get(table.table.toLowerCase())?.type !== 'table')
+            continue;
+        for (const d of table.derived)
+            if (wrongIn(catalogue, d))
+                run(d.ddl);
+    }
+}
+/**
+ * Both adapters' migration pass, after one migration's SQL and inside its transaction: the
+ * column check, and — after the last migration of the pass — the derived objects repaired.
+ * `key` is `<module>@<version>`, which a failure names. A last entry the pass skips (journaled
+ * by a pass that ran first) needs nothing here: that pass repaired them after it.
+ */
+export function afterMigration(sql, run, plans, key, last) {
+    if (last)
+        repairDerivedObjects(sql, run, plans, { after: `migration ${key}` });
+    else
+        assertEntityStateColumns(sql, plans, `migration ${key}`);
+}
+//# sourceMappingURL=derived-objects.js.map

package/dist/derived-objects.js.map

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

package/dist/email-intent.d.ts

@@ -0,0 +1,56 @@
+import { type PlatformOutcomeEvent, type PlatformRequestFailure, type PlatformRequestId, type PlatformRequestStatus, type ScopeId, type SendEmailRequest, type TenantId } from '@substrat-run/contracts';
+import type { OperationContext } from './scope-host.js';
+import type { SwitchSql } from './system-switch.js';
+/**
+ * Ask the platform to send one email, inside the operation (#2102).
+ *
+ * The send is a platform intent: a row written in this operation's transaction, so an
+ * operation that throws afterwards sends nothing, and one that commits is delivered by the
+ * platform's drain — retried while the provider defers it, and reported back as an
+ * `email.sent`, `email.refused` or `email.dead-lettered` event on `mail.about` (or on the
+ * intent, when the mail names no entity). The returned id is the `request` those events carry.
+ *
+ * Name the recipient's `subjectId` when they are a person in your data: the row holds their
+ * address and the message, and that id is how a subject erasure finds and cancels it.
+ *
+ * Parsed here rather than at drain time, so a malformed address fails the operation that wrote
+ * it, in front of the person who typed it, instead of a refusal event minutes later. Needs the
+ * vertical's `emailSender` grant, as the relay always has; without it the send is refused.
+ */
+export declare function requestEmail(ctx: Pick<OperationContext, 'requestPlatform'>, mail: Omit<SendEmailRequest, 'piiClass'>): PlatformRequestId;
+/** What the scope stamps on an outcome event it writes: the drain names the rest. */
+export interface OutcomeEventStamp {
+    tenantId: TenantId;
+    scopeId: ScopeId;
+    /** ISO 8601 — the settle's instant. */
+    now: string;
+    mintEventId(ms: number): string;
+    /** The deploy writing it, for the outbox's `version` column. */
+    version: string | null;
+}
+export interface PlatformRequestSettle {
+    status: PlatformRequestStatus;
+    result?: unknown;
+    lastError?: string | null;
+    failure?: PlatformRequestFailure | null;
+    /** #2102: the event this settle writes into the scope, when it moves the row out of `pending`. */
+    event?: PlatformOutcomeEvent | null;
+}
+/**
+ * Journal a platform-request outcome, and write its outcome event (#2102) — one step, so both
+ * adapters say the same thing and the event commits with the settle or not at all. Run it in a
+ * transaction.
+ *
+ * **Compare-and-set on `pending` (#1600 review).** The drain reads pending rows, runs a handler,
+ * then settles — and between the read and the settle a subject erasure can redact the row.
+ * Settling by `id` alone let that stale pass overwrite the redaction and write a provider's
+ * reply, which can quote the person, back into `last_error`. A settle that finds the row
+ * already terminal does nothing, deliberately silently — throwing would make the drain's
+ * blanket catch retry a row that is correctly over. The event follows the same rule: written
+ * only by the settle that actually moved the row, so a repeated settle never writes it twice.
+ *
+ * The event is refused (before anything is written) on a `pending` settle — an outcome event
+ * says the request is over — and when its `request` is not the row being settled.
+ */
+export declare function settlePlatformRequestIn(db: SwitchSql, id: PlatformRequestId, outcome: PlatformRequestSettle, stamp: OutcomeEventStamp): void;
+//# sourceMappingURL=email-intent.d.ts.map

package/dist/email-intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-intent.d.ts","sourceRoot":"","sources":["../src/email-intent.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,OAAO,EACZ,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACd,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,IAAI,CAAC,gBAAgB,EAAE,iBAAiB,CAAC,EAC9C,IAAI,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC,GACvC,iBAAiB,CAKnB;AAED,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,gEAAgE;IAChE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACxC,kGAAkG;IAClG,KAAK,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,SAAS,EACb,EAAE,EAAE,iBAAiB,EACrB,OAAO,EAAE,qBAAqB,EAC9B,KAAK,EAAE,iBAAiB,GACvB,IAAI,CAsCN"}

package/dist/email-intent.js

@@ -0,0 +1,71 @@
+import { SEND_EMAIL_KIND, domainEvent, eventId, platformOutcomeEvent, sendEmailRequest, } from '@substrat-run/contracts';
+import { KERNEL_ACTOR, kernelOutboxInsertSql } from './kernel-outbox.js';
+/**
+ * Ask the platform to send one email, inside the operation (#2102).
+ *
+ * The send is a platform intent: a row written in this operation's transaction, so an
+ * operation that throws afterwards sends nothing, and one that commits is delivered by the
+ * platform's drain — retried while the provider defers it, and reported back as an
+ * `email.sent`, `email.refused` or `email.dead-lettered` event on `mail.about` (or on the
+ * intent, when the mail names no entity). The returned id is the `request` those events carry.
+ *
+ * Name the recipient's `subjectId` when they are a person in your data: the row holds their
+ * address and the message, and that id is how a subject erasure finds and cancels it.
+ *
+ * Parsed here rather than at drain time, so a malformed address fails the operation that wrote
+ * it, in front of the person who typed it, instead of a refusal event minutes later. Needs the
+ * vertical's `emailSender` grant, as the relay always has; without it the send is refused.
+ */
+export function requestEmail(ctx, mail) {
+    const parsed = sendEmailRequest.parse(mail);
+    // Classified like an event naming the same person, so a subject erasure reaches the row.
+    const payload = parsed.subjectId ? { ...parsed, piiClass: 'direct' } : parsed;
+    return ctx.requestPlatform({ kind: SEND_EMAIL_KIND, payload });
+}
+/**
+ * Journal a platform-request outcome, and write its outcome event (#2102) — one step, so both
+ * adapters say the same thing and the event commits with the settle or not at all. Run it in a
+ * transaction.
+ *
+ * **Compare-and-set on `pending` (#1600 review).** The drain reads pending rows, runs a handler,
+ * then settles — and between the read and the settle a subject erasure can redact the row.
+ * Settling by `id` alone let that stale pass overwrite the redaction and write a provider's
+ * reply, which can quote the person, back into `last_error`. A settle that finds the row
+ * already terminal does nothing, deliberately silently — throwing would make the drain's
+ * blanket catch retry a row that is correctly over. The event follows the same rule: written
+ * only by the settle that actually moved the row, so a repeated settle never writes it twice.
+ *
+ * The event is refused (before anything is written) on a `pending` settle — an outcome event
+ * says the request is over — and when its `request` is not the row being settled.
+ */
+export function settlePlatformRequestIn(db, id, outcome, stamp) {
+    const event = outcome.event == null ? null : platformOutcomeEvent.parse(outcome.event);
+    if (event && outcome.status === 'pending') {
+        throw new Error(`settle of platform request ${id}: an outcome event needs a terminal status, not 'pending'`);
+    }
+    if (event && event.payload.request !== id) {
+        throw new Error(`settle of platform request ${id}: the outcome event names request ${event.payload.request}`);
+    }
+    const was = db.all('SELECT status FROM _substrat_platform_requests WHERE id = ?', id)[0]?.status;
+    db.run(`UPDATE _substrat_platform_requests
+       SET status = ?, result = COALESCE(?, result), last_error = ?, last_failure = ?,
+           attempts = attempts + 1, settled_at = ?
+     WHERE id = ? AND status = 'pending'`, outcome.status, outcome.result === undefined ? null : JSON.stringify(outcome.result), outcome.lastError ?? null, outcome.failure == null ? null : JSON.stringify(outcome.failure), outcome.status === 'pending' ? null : stamp.now, id);
+    if (!event || was !== 'pending')
+        return;
+    const full = domainEvent.parse({
+        id: eventId.parse(stamp.mintEventId(Date.parse(stamp.now))),
+        type: event.type,
+        schemaVersion: 1,
+        occurredAt: stamp.now,
+        tenantId: stamp.tenantId,
+        scopeId: stamp.scopeId,
+        actor: KERNEL_ACTOR,
+        entity: event.entity,
+        piiClass: 'none',
+        payload: event.payload,
+    });
+    const st = kernelOutboxInsertSql(full, stamp.version);
+    db.run(st.sql, ...st.params);
+}
+//# sourceMappingURL=email-intent.js.map

package/dist/email-intent.js.map

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

package/dist/entity-edges.d.ts

@@ -1,4 +1,4 @@
-import { type DomainEventInput, type Instant } from '@substrat-run/contracts';
+import { type DomainEventInput, type EntityRef, type Instant } from '@substrat-run/contracts';
 import type { OperationContext, ScopedSql } from './scope-host.js';
 /**
  * `ctx.link` and `ctx.relink` (K-16, #1864), written once — both adapters hand the same
@@ -29,6 +29,11 @@ export interface EntityEdgeDeps {
     emit: (event: DomainEventInput) => void;
     /** K-42's read-only refusal, for the effecting verbs. */
     assertWrites: (verb: string) => void;
+    /**
+     * Is this entity out of reach as a parent (#119) — its type declares trash, and it is binned or
+     * missing (`isUnreachableParent`)? Refused by `link` and as `relink`'s `to`, one answer for both.
+     */
+    isUnreachableParent: (entity: EntityRef) => boolean;
 }
 export type EntityEdgeVerbs = Pick<OperationContext, 'link' | 'relink'>;
 export declare function createEntityEdgeVerbs(deps: EntityEdgeDeps): EntityEdgeVerbs;

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

@@ -1 +1 @@
-{"version":3,"file":"entity-edges.d.ts","sourceRoot":"","sources":["../src/entity-edges.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,gBAAgB,EAErB,KAAK,OAAO,EACb,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEnE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,2FAA2F;IAC3F,GAAG,EAAE,SAAS,CAAC;IACf,mFAAmF;IACnF,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IACpD,kEAAkE;IAClE,GAAG,EAAE,OAAO,CAAC;IACb,2EAA2E;IAC3E,IAAI,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACxC,yDAAyD;IACzD,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC;AAExE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,GAAG,eAAe,CA8I3E"}
+{"version":3,"file":"entity-edges.d.ts","sourceRoot":"","sources":["../src/entity-edges.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,OAAO,EACb,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEnE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,cAAc;IAC7B,2FAA2F;IAC3F,GAAG,EAAE,SAAS,CAAC;IACf,mFAAmF;IACnF,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IACpD,kEAAkE;IAClE,GAAG,EAAE,OAAO,CAAC;IACb,2EAA2E;IAC3E,IAAI,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACxC,yDAAyD;IACzD,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;;;OAGG;IACH,mBAAmB,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC;CACrD;AAED,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC;AAExE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,GAAG,eAAe,CA4J3E"}

package/dist/entity-edges.js

@@ -7,6 +7,17 @@ export function createEntityEdgeVerbs(deps) {
                 `(declare it in a module manifest's entityRelations)`);
         }
     };
+    /**
+     * A binned entity is gone from everyone's view until it is restored (#119), so nothing new
+     * hangs off it. The refusal is the one a MISSING parent of the same type gets, word for word:
+     * `link` checks no permission, so a refusal that named the trash would tell a caller who may not
+     * see the parent that it exists. An ARCHIVED parent passes: archived is filed away and readable.
+     */
+    const assertParentReachable = (verb, parent) => {
+        if (deps.isUnreachableParent(parent)) {
+            throw substratError('not_found', `${verb}: ${parent.entityType}:${parent.entityId} not found`);
+        }
+    };
     /**
      * Refuse when `ancestorCandidate` is `child` itself, or already lies beneath `child` in the
      * live parent graph — shared by `link` (candidate = the new `parent`) and `relink` (candidate
@@ -54,6 +65,7 @@ export function createEntityEdgeVerbs(deps) {
             const c = entityObjectRef(child, 'ctx.link'); // #1856: an edge the walk can read back
             const p = entityObjectRef(parent, 'ctx.link');
             assertDeclared('ctx.link', child, parent);
+            assertParentReachable('ctx.link', parent);
             // Refuse a parent that is the child itself or already beneath it (#1875) — same question
             // `relink` asks of `to`, same walk.
             assertNoCycle('ctx.link', 'link', c, p);
@@ -80,6 +92,7 @@ export function createEntityEdgeVerbs(deps) {
             // whether or not its relation is still declared, so an edge that grants must stay
             // movable. What `from` must be is an edge that exists.
             assertDeclared('ctx.relink', child, to);
+            assertParentReachable('ctx.relink', to);
             // The walk's own `live` predicate, so "is a parent" means what a check means by it.
             const live = deps.sql.query(`SELECT 1 AS live FROM _substrat_tuples
          WHERE subject = ? AND relation = 'parent' AND object = ? AND ${liveTupleSql()}`, [c, f, deps.now]);

package/dist/entity-edges.js.map

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