@substrat-run/kernel 0.139.0 → 0.140.0

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAExD,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GAEtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAsB,MAAM,iBAAiB,CAAC;AAEvG,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,kBAAkB,EAAwB,MAAM,mBAAmB,CAAC;AASjH;;;;GAIG;AACH,MAAM,OAAO,eAAgB,SAAQ,aAAa;IAErC,SAAS;IADpB,YACW,SAAiB,EAC1B,OAAe;QAEf,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;yBAHlB,SAAS;IAIpB,CAAC;CACF;AAsBD,+FAA+F;AAC/F,SAAS,WAAW,CAAC,GAAc;IACjC,OAAO,IAAI,GAAG,CACZ,GAAG;SACA,KAAK,CACJ,0DAA0D,CAC3D;SACA,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CACvF,CAAC;AACJ,CAAC;AAED,0FAA0F;AAC1F,MAAM,OAAO,GAAG,CAAC,SAAsC,EAAE,CAAU,EAA6B,EAAE,CAChG,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;IACnB,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IAClD,OAAO,CACL,KAAK,EAAE,IAAI,KAAK,CAAC,CAAC,IAAI;QACtB,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE;QACnD,KAAK,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CACpB,CAAC;AACJ,CAAC,CAAC,CAAC;AAEL,MAAM,SAAS,GAAG,CAAC,GAAc,EAAE,KAAa,EAAe,EAAE,CAC/D,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAmB,+CAA+C,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;AAElI,SAAS,YAAY,CAAC,GAAc,EAAE,KAAmB;IACvD,MAAM,OAAO,GAAG,IAAI,GAAG,CACrB,GAAG,CAAC,KAAK,CAAyC,qDAAqD,CAAC,CAAC,GAAG,CAC1G,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,OAAO,EAAE,CACrC,CACF,CAAC;IACF,MAAM,OAAO,GAAG,CAAC,QAAgB,EAAE,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,QAAQ,IAAI,OAAO,EAAE,CAAC,CAAC;IAC7F,MAAM,OAAO,GAAG,IAAI,GAAG,EAAwF,CAAC;IAChH,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,EAAE;QAC9B,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;QAChE,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC;IAC3B,CAAC,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QACxC,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC5B,MAAM,OAAO,GAAG,qBAAqB,CAAC,IAAI,CAAC;aACxC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;aAChD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;QAClF,IAAI,OAAO,CAAC,MAAM;YAAE,CAAC,CAAC,OAAO,GAAG,OAAO,CAAC;QACxC,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,uBAAuB,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YAC1D,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,yBAAyB,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjG,CAAC;QACD,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,KAAK,CAAC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YACpE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QACxC,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,gBAAgB,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YACrE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;IACD,+FAA+F;IAC/F,yDAAyD;IACzD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;QACzC,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,kBAAkB,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YACrD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,kBAAkB,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnG,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,KAAuB,EAAE,IAAY,EAAE,SAAiB,EAAS,EAAE;IAC9F,MAAM,IAAI,eAAe,CACvB,SAAS,EACT,GAAG,KAAK,UAAU,KAAK,CAAC,KAAK,aAAa,IAAI,mEAAmE,CAClH,CAAC;AACJ,CAAC,CAAC;AAEF;;;;GAIG;AACH,SAAS,aAAa,CACpB,GAAc,EACd,SAAsC,EACtC,KAAuB,EACvB,KAAa,EACb,WAAW,GAAoB,MAAM;IAErC,IAAI,CAAC,KAAK,CAAC,OAAO;QAAE,OAAO;IAC3B,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,EAAE,IAAI,KAAK,OAAO,EAAE,CAAC;QAC/D,IAAI,WAAW,KAAK,MAAM;YAAE,OAAO;QACnC,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,SAAS,CAAC,CAAC;IAC/D,CAAC;IACD,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IAC5C,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO;QAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;YAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;AACvG,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAc,EAAE,GAA0B,EAAE,KAAmB;IAC7F,oBAAoB,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,CAAC;AAClE,CAAC;AAED,4GAA4G;AAC5G,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAAmB,EAAW,EAAE,CAC9D,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC;AAExE;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAc,EAAE,KAAmB,EAAE,KAAa;IACzF,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,sDAAsD;IAC1F,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC;QAAE,aAAa,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAC5F,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAc,EACd,GAA0B,EAC1B,KAAmB,EACnB,IAAwE;IAExE,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC;QAC7C,aAAa,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACnE,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,EAAE,IAAI,KAAK,OAAO;YAAE,SAAS;QACzE,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO;YAAE,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;gBAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACvE,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAc,EACd,GAA0B,EAC1B,KAAmB,EACnB,GAAW,EACX,IAAa;IAEb,IAAI,IAAI;QAAE,oBAAoB,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,aAAa,GAAG,EAAE,EAAE,CAAC,CAAC;;QAC1E,wBAAwB,CAAC,GAAG,EAAE,KAAK,EAAE,aAAa,GAAG,EAAE,CAAC,CAAC;AAChE,CAAC"}

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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"}

package/dist/entity-grant-shape.d.ts

@@ -0,0 +1,94 @@
+import { type EntityGrantShape, type EntityRef, type PrincipalId } from '@substrat-run/contracts';
+import type { SwitchSql } from './system-switch.js';
+/**
+ * A declared entity-grant SHAPE, reconciled (#2071).
+ *
+ * A vertical declares the keys a person is given on their own record (`ENTITY_GRANTS`:
+ * meridian's `EMPLOYEE_SELF` on `employee`, todo's owner grant on `owner`). They used to be
+ * minted key by key, once, when the person arrived, so a key added to the shape by a later
+ * release reached only the people who arrived after it, while `PERMISSIONS.md` said everyone
+ * held it.
+ *
+ * Three pieces, each one statement shared by both adapters:
+ *
+ * - {@link grantEntityShapeIn}: the grant. The shape's keys plus a MARKER tuple
+ *   (`ENTITY_SHAPE_MARKER_RELATION`) on the same entity. The marker is what makes a person a
+ *   holder of the shape, which no set of keys can: someone `ctx.grant`ed one of those keys
+ *   holds part of the shape and must never be topped up to all of it.
+ * - {@link topUpEntityGrantShapes}: one bounded pass of the reconcile, writing each top-up's
+ *   `entity.grants-topped-up` event beside it. Each live marker whose
+ *   entity lacks a key of the CURRENT shape gets that key. A key with any row at all is
+ *   skipped, and that includes a tombstone (K-21): a key someone took back from that person
+ *   stays taken back. A key merely dropped from the shape is left where it is, because silently
+ *   revoking authority on a deploy is the riskier mistake.
+ * - The retirement (#2082), in the same pass and budget, between the backfill and the top-up: a
+ *   key the shape declares `retired` is tombstoned for every live marker that still holds it
+ *   live, with one `entity.grants-retired` event per (person, entity). The tombstones are the
+ *   progress; a record tuple (`shape:<type>`, `shape-retired:<key>`, `scope:<id>`) ends it once
+ *   a batch comes back short, so a key granted to a holder again afterwards is left alone. A key
+ *   back in the shape's `permissions` tombstones that record, so a later release may retire it
+ *   again. One tuple is one authority: a direct grant of the key on the same entity to the same
+ *   person is that row, and goes with it.
+ * - The backfill, inside the same budget, until it is done once per (scope, entity type): how
+ *   people granted before markers existed become holders. For own-record holders it reads
+ *   provenance, never key sets alone.
+ *   The shape's declared `holder` says whose record each entity is (`'self'`: the entity id is
+ *   the principal; a table column naming the principal), and a person is marked only on their
+ *   own record, and only when they hold a row there (live or tombstoned) for some key of the
+ *   shape — evidence they were given it. Someone `ctx.grant`ed even the whole shape on another
+ *   person's record is never marked. A shape with no `holder` gets no backfill. Each batch marks
+ *   at most what the pass's budget allows; the markers are the progress, since a marked pair is
+ *   no longer a candidate, and a record tuple (`shape:<type>`, `shape-backfilled`, `scope:<id>`)
+ *   ends it once a batch comes back short.
+ * - `holder: 'grantee'` (#2083), for a record that names no principal (a portal customer, a
+ *   contact): whoever holds a live current or retired key of the shape on such an entity was given it.
+ *   Each pass records current and retired keys (`shape-grantee-key`), and the explicit tuple
+ *   writer makes non-shape grants refuse them on that entity type. A tuple from before the
+ *   first such pass cannot be told apart. A marker already written by a shape grant persists
+ *   through retirement, so its holder receives the new keys even if their old key was K alone.
+ *
+ * Only a shape declared `bootstrap: true` is reconciled: one a person is GIVEN on their own
+ * record. A sharing shape, which people reach through `ctx.grant` (todo's `list`), is skipped
+ * whole, backfill included, so a sharee is never marked a holder.
+ */
+/** Holders topped up per pass — one transaction each, so a large scope never holds one long. */
+export declare const SHAPE_TOP_UP_BATCH = 500;
+/** The largest batch a caller may ask for: past this a pass is the long transaction it exists to avoid. */
+export declare const SHAPE_TOP_UP_BATCH_MAX = 5000;
+/** `batch`, or `validation_failed`: a pass size is a positive integer no larger than the max. */
+export declare function shapeTopUpBatch(batch?: number): number;
+/**
+ * The shape's grant to one person on one entity: the marker and every key, each an explicit
+ * write, so a re-grant brings back what a revoke tombstoned — as `ctx.grant` does.
+ * `entityObjectRef` refuses a ref the walk could not read back (#1856). Run it in ONE
+ * transaction, so the marker and its keys land together or not at all.
+ */
+export declare function grantEntityShapeIn(db: SwitchSql, principal: PrincipalId, entity: EntityRef, permissions: readonly string[]): void;
+/** Where a pass runs and how its events are stamped — the facts only the adapter holds. */
+export interface ShapePass {
+    tenantId: string;
+    scopeId: string;
+    shapes: readonly EntityGrantShape[];
+    /** The pass's one instant: marker liveness and every event's `occurredAt`. */
+    now: string;
+    /** Rows of work at most: a backfill mark or a holder topped up each count one. */
+    limit: number;
+    /** The adapter's monotonic event-id mint, given the instant in ms. */
+    mintEventId: (ms: number) => string;
+    /** The deploy writing the events, for the outbox `version` column. */
+    version: string | null;
+}
+/**
+ * One pass of the reconcile over one scope, at most `limit` rows of work: backfill marks for any
+ * shape whose backfill is not done here, then holders whose retired keys are taken back, each
+ * with its `entity.grants-retired` event, then holders topped up, each with its
+ * `entity.grants-topped-up` event. `done` is false when the budget ran out, and the caller runs
+ * another pass. Run it inside ONE transaction, so the keys and their events commit together.
+ * Re-running a finished scope writes nothing.
+ */
+export declare function topUpEntityGrantShapes(db: SwitchSql, pass: ShapePass): {
+    toppedUp: number;
+    retired: number;
+    done: boolean;
+};
+//# sourceMappingURL=entity-grant-shape.d.ts.map

package/dist/entity-grant-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-grant-shape.d.ts","sourceRoot":"","sources":["../src/entity-grant-shape.ts"],"names":[],"mappings":"AAAA,OAAO,EAUL,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,WAAW,EACjB,MAAM,yBAAyB,CAAC;AAMjC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,gGAAgG;AAChG,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,2GAA2G;AAC3G,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,KAAK,GAAE,MAA2B,GAAG,MAAM,CAS1E;AAiBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CASjI;AAED,2FAA2F;AAC3F,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACpC,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,sEAAsE;IACtE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,SAAS,EACb,IAAI,EAAE,SAAS,GACd;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CA+EtD"}