@substrat-run/kernel 0.139.0 → 0.141.0

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

package/dist/entity-grant-shape.js

@@ -0,0 +1,329 @@
+import { ENTITY_GRANTS_RETIRED, ENTITY_GRANTS_TOPPED_UP, ENTITY_SHAPE_MARKER_RELATION, domainEvent, entityGrantsRetiredPayload, entityGrantsToppedUpPayload, entityObjectRef, eventId, } from '@substrat-run/contracts';
+import { assertKernelAuthoredType, substratError } from '@substrat-run/contracts';
+import { KERNEL_ACTOR, kernelOutboxInsertSql } from './kernel-outbox.js';
+import { GRANTEE_KEY_RELATION, explicitTupleSql } from './entity-grant.js';
+import { liveTupleSql } from './permission-eval.js';
+import { assertSqlIdentifier } from './sql-identifier.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 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 const SHAPE_TOP_UP_BATCH_MAX = 5000;
+/** `batch`, or `validation_failed`: a pass size is a positive integer no larger than the max. */
+export function shapeTopUpBatch(batch = SHAPE_TOP_UP_BATCH) {
+    if (!Number.isInteger(batch) || batch < 1 || batch > SHAPE_TOP_UP_BATCH_MAX) {
+        throw substratError('validation_failed', `reconcileEntityGrantShapes: batch must be an integer from 1 to ${SHAPE_TOP_UP_BATCH_MAX}, not ${batch}`, { errors: [{ path: 'batch', message: `an integer from 1 to ${SHAPE_TOP_UP_BATCH_MAX}` }] });
+    }
+    return batch;
+}
+/** The backfill's run-once record: `(shape:<type>, backfilled, scope:<id>)`. */
+const BACKFILLED_RELATION = 'shape-backfilled';
+/** A retirement's run-once record, per key: `(shape:<type>, shape-retired:<key>, scope:<id>)`. */
+const RETIRED_RELATION = 'shape-retired:';
+/** The subject and object of a shape's run-once records on one scope. */
+const recordRefs = (entityType, scopeId) => [`shape:${entityType}`, `scope:${scopeId}`];
+/** The writer of the top-up events: the kernel, as no module or person acted. */
+const PRINCIPAL = 'principal:';
+const keysOf = (permissions) => [...new Set(permissions)].sort();
+/**
+ * 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 function grantEntityShapeIn(db, principal, entity, permissions) {
+    const object = entityObjectRef(entity, 'grantEntityShape');
+    const subject = `${PRINCIPAL}${principal}`;
+    for (const st of [
+        explicitTupleSql(subject, ENTITY_SHAPE_MARKER_RELATION, object),
+        ...keysOf(permissions).map((p) => explicitTupleSql(subject, `granted:${p}`, object)),
+    ]) {
+        db.run(st.sql, ...st.params);
+    }
+}
+/**
+ * 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 function topUpEntityGrantShapes(db, pass) {
+    // Here as well as at each entry point: a pass with no budget never reports done, so a caller
+    // looping until it does would never stop.
+    let budget = shapeTopUpBatch(pass.limit);
+    recordGranteeKeys(db, pass.shapes);
+    let toppedUp = 0;
+    let retired = 0;
+    for (const shape of pass.shapes) {
+        // A sharing shape is never reconciled — not topped up, not backfilled, nothing retired.
+        if (!shape.bootstrap)
+            continue;
+        const keys = keysOf(shape.permissions);
+        // A key the shape grants is never taken back, whatever the declaration says.
+        const gone = keysOf(shape.retired ?? []).filter((k) => !keys.includes(k));
+        if (keys.length === 0 && gone.length === 0)
+            continue;
+        const prefix = `${shape.entityType}:`;
+        const json = JSON.stringify(keys);
+        // A live retired key still identifies a legacy holder so this pass can retire it.
+        // The grantee query excludes tombstoned tuples.
+        budget -= backfill(db, pass, shape, prefix, JSON.stringify([...keys, ...gone]), budget);
+        if (budget === 0)
+            return { toppedUp, retired, done: false };
+        reopenRetirements(db, pass, shape.entityType, keys);
+        const took = retire(db, pass, shape.entityType, prefix, gone, budget);
+        budget -= took;
+        retired += took;
+        if (budget === 0)
+            return { toppedUp, retired, done: false };
+        if (keys.length === 0)
+            continue;
+        const holders = db.all(`SELECT m.subject, m.object FROM _substrat_tuples m
+        WHERE m.relation = ? AND ${liveTupleSql('m')}
+          AND substr(m.subject, 1, ${PRINCIPAL.length}) = '${PRINCIPAL}'
+          AND substr(m.object, 1, ?) = ?
+          AND EXISTS (SELECT 1 FROM json_each(?) k
+                       WHERE NOT EXISTS (SELECT 1 FROM _substrat_tuples t
+                                          WHERE t.subject = m.subject AND t.object = m.object
+                                            AND t.relation = 'granted:' || k.value))
+        ORDER BY m.subject, m.object
+        LIMIT ?`, ENTITY_SHAPE_MARKER_RELATION, pass.now, prefix.length, prefix, json, budget);
+        for (const h of holders) {
+            const added = db.all(`SELECT k.value AS key FROM json_each(?) k
+            WHERE NOT EXISTS (SELECT 1 FROM _substrat_tuples t
+                               WHERE t.subject = ? AND t.object = ? AND t.relation = 'granted:' || k.value)
+            ORDER BY k.value`, json, h.subject, h.object).map((m) => m.key);
+            for (const key of added) {
+                db.run(`INSERT OR IGNORE INTO _substrat_tuples (subject, relation, object) VALUES (?, ?, ?)`, h.subject, `granted:${key}`, h.object);
+            }
+            const st = kernelOutboxInsertSql(shapeEvent(pass, ENTITY_GRANTS_TOPPED_UP, entityGrantsToppedUpPayload, {
+                principal: h.subject.slice(PRINCIPAL.length),
+                entity: { entityType: shape.entityType, entityId: h.object.slice(prefix.length) },
+                added,
+            }), pass.version);
+            db.run(st.sql, ...st.params);
+        }
+        budget -= holders.length;
+        toppedUp += holders.length;
+        if (budget === 0)
+            return { toppedUp, retired, done: false };
+    }
+    return { toppedUp, retired, done: true };
+}
+/**
+ * One bounded batch of a shape's retirement: at most `budget` (person, entity) pairs, each a
+ * live marker still holding a retired key live there, whose retired keys are tombstoned with one
+ * event. Keys whose retirement already finished on this scope are skipped, and a short batch
+ * records the rest finished. Returns how many pairs it took keys from.
+ */
+function retire(db, pass, entityType, prefix, gone, budget) {
+    if (gone.length === 0)
+        return 0;
+    const [shapeRef, scopeRef] = recordRefs(entityType, pass.scopeId);
+    const finished = new Set(db.all(`SELECT substr(relation, ${RETIRED_RELATION.length + 1}) AS key FROM _substrat_tuples
+          WHERE subject = ? AND object = ? AND revoked_at IS NULL
+            AND relation IN (SELECT '${RETIRED_RELATION}' || value FROM json_each(?))`, shapeRef, scopeRef, JSON.stringify(gone)).map((r) => r.key));
+    const open = gone.filter((k) => !finished.has(k));
+    if (open.length === 0)
+        return 0;
+    const json = JSON.stringify(open);
+    const holders = db.all(`SELECT m.subject, m.object FROM _substrat_tuples m
+      WHERE m.relation = ? AND ${liveTupleSql('m')}
+        AND substr(m.subject, 1, ${PRINCIPAL.length}) = '${PRINCIPAL}'
+        AND substr(m.object, 1, ?) = ?
+        AND EXISTS (SELECT 1 FROM _substrat_tuples t
+                     WHERE t.subject = m.subject AND t.object = m.object AND t.revoked_at IS NULL
+                       AND t.relation IN (SELECT 'granted:' || value FROM json_each(?)))
+      ORDER BY m.subject, m.object
+      LIMIT ?`, ENTITY_SHAPE_MARKER_RELATION, pass.now, prefix.length, prefix, json, budget);
+    for (const h of holders) {
+        // Tombstoned and read back in one statement: the keys this holder lost are what it touched.
+        const removed = keysOf(db.all(`UPDATE _substrat_tuples SET revoked_at = ?
+            WHERE subject = ? AND object = ? AND revoked_at IS NULL
+              AND relation IN (SELECT 'granted:' || value FROM json_each(?))
+            RETURNING substr(relation, 9) AS key`, pass.now, h.subject, h.object, json).map((r) => r.key));
+        const st = kernelOutboxInsertSql(shapeEvent(pass, ENTITY_GRANTS_RETIRED, entityGrantsRetiredPayload, {
+            principal: h.subject.slice(PRINCIPAL.length),
+            entity: { entityType, entityId: h.object.slice(prefix.length) },
+            removed,
+        }), pass.version);
+        db.run(st.sql, ...st.params);
+    }
+    if (holders.length < budget) {
+        for (const k of open) {
+            db.run('INSERT OR REPLACE INTO _substrat_tuples (subject, relation, object) VALUES (?, ?, ?)', shapeRef, `${RETIRED_RELATION}${k}`, scopeRef);
+        }
+    }
+    return holders.length;
+}
+/**
+ * A key back in the shape ends its retirement's record (tombstoned, like any tuple), so a later
+ * release that drops and retires it again runs the retirement again.
+ */
+function reopenRetirements(db, pass, entityType, keys) {
+    if (keys.length === 0)
+        return;
+    db.run(`UPDATE _substrat_tuples SET revoked_at = ?
+      WHERE subject = ? AND object = ? AND revoked_at IS NULL
+        AND relation IN (SELECT '${RETIRED_RELATION}' || value FROM json_each(?))`, pass.now, ...recordRefs(entityType, pass.scopeId), JSON.stringify(keys));
+}
+/**
+ * One bounded batch of the backfill for one shape — at most `budget` marks — and the run-once
+ * record when the batch comes back short. Returns how many it marked. See the module comment:
+ * provenance only, from the shape's declared `holder`.
+ */
+function backfill(db, pass, shape, prefix, json, budget) {
+    if (!shape.holder || budget === 0)
+        return 0;
+    const [shapeRef, scopeRef] = recordRefs(shape.entityType, pass.scopeId);
+    const record = [shapeRef, BACKFILLED_RELATION, scopeRef];
+    if (db.all('SELECT 1 FROM _substrat_tuples WHERE subject = ? AND relation = ? AND object = ?', ...record).length > 0) {
+        return 0;
+    }
+    // Not yet a holder in any state: a tombstoned marker is a revoke of the holding, kept.
+    const unmarked = (subject, object) => `NOT EXISTS (SELECT 1 FROM _substrat_tuples m WHERE m.subject = ${subject} AND m.relation = '${ENTITY_SHAPE_MARKER_RELATION}' AND m.object = ${object})`;
+    const heldThere = (subject, object) => `EXISTS (SELECT 1 FROM _substrat_tuples g WHERE g.subject = ${subject} AND g.object = ${object}
+               AND g.relation IN (SELECT 'granted:' || value FROM json_each(?)))`;
+    let candidates;
+    if (shape.holder === 'self') {
+        // The entity id IS the principal: `owner:<p>` belongs to `principal:<p>` and nobody else.
+        candidates = db.all(`SELECT DISTINCT t.subject, t.object FROM _substrat_tuples t
+        WHERE substr(t.object, 1, ?) = ?
+          AND t.subject = '${PRINCIPAL}' || substr(t.object, ?)
+          AND t.relation IN (SELECT 'granted:' || value FROM json_each(?))
+          AND ${unmarked('t.subject', 't.object')}
+        ORDER BY t.subject, t.object
+        LIMIT ?`, prefix.length, prefix, prefix.length + 1, json, budget);
+    }
+    else if (shape.holder === 'grantee') {
+        // Whoever holds a LIVE key of the shape on an entity of this type. Live, unlike the other two
+        // holders: with no record naming the person, a key taken back from them is no evidence they
+        // still belong there, and marking them would hand a revoked portal the next key it gains.
+        candidates = db.all(`SELECT DISTINCT t.subject, t.object FROM _substrat_tuples t
+        WHERE substr(t.object, 1, ?) = ?
+          AND substr(t.subject, 1, ${PRINCIPAL.length}) = '${PRINCIPAL}'
+          AND t.relation IN (SELECT 'granted:' || value FROM json_each(?))
+          AND ${liveTupleSql('t')}
+          AND ${unmarked('t.subject', 't.object')}
+        ORDER BY t.subject, t.object
+        LIMIT ?`, prefix.length, prefix, json, pass.now, budget);
+    }
+    else {
+        const { table, idColumn, principalColumn } = shape.holder;
+        const where = `entityGrants holder of '${shape.entityType}'`;
+        for (const [kind, name] of [['a table', table], ['a column', idColumn], ['a column', principalColumn]]) {
+            assertSqlIdentifier('reconcileEntityGrantShapes', kind, name, where);
+        }
+        // The vertical's table may not exist yet on this scope (a module not migrated): nothing to
+        // mark, and the backfill stays open for the next reconcile rather than being recorded done.
+        if (db.all(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?`, table).length === 0)
+            return 0;
+        const subject = `'${PRINCIPAL}' || e."${principalColumn}"`;
+        const object = `? || e."${idColumn}"`;
+        candidates = db.all(`SELECT ${subject} AS subject, ${object} AS object FROM "${table}" e
+        WHERE e."${principalColumn}" IS NOT NULL
+          AND ${heldThere(subject, object)}
+          AND ${unmarked(subject, object)}
+        ORDER BY 1, 2
+        LIMIT ?`, prefix, prefix, json, prefix, budget);
+    }
+    for (const c of candidates) {
+        db.run('INSERT OR IGNORE INTO _substrat_tuples (subject, relation, object) VALUES (?, ?, ?)', c.subject, ENTITY_SHAPE_MARKER_RELATION, c.object);
+    }
+    if (candidates.length < budget) {
+        db.run('INSERT OR IGNORE INTO _substrat_tuples (subject, relation, object) VALUES (?, ?, ?)', ...record);
+    }
+    return candidates.length;
+}
+/**
+ * The current and retired keys of every `holder: 'grantee'` bootstrap shape, recorded so the
+ * explicit tuple writer can refuse them to every non-shape grant. A reconcile carries the
+ * reached version's whole reviewed registry,
+ * so the records are made to match it exactly: a declaration a later version drops stops
+ * refusing. Bounded by the declared keys, so it runs in every pass without a budget.
+ */
+function recordGranteeKeys(db, shapes) {
+    const rows = shapes
+        .filter((s) => s.bootstrap && s.holder === 'grantee')
+        .flatMap((s) => keysOf([...s.permissions, ...(s.retired ?? [])]).map((k) => [`shape:${s.entityType}`, `granted:${k}`]));
+    db.run(
+    // The subject range keeps it on the primary key: `shape:` rows only, never the whole table.
+    `DELETE FROM _substrat_tuples WHERE subject >= 'shape:' AND subject < 'shape;' AND relation = ?
+        AND NOT EXISTS (SELECT 1 FROM json_each(?) r
+                         WHERE json_extract(r.value, '$[0]') = _substrat_tuples.subject
+                           AND json_extract(r.value, '$[1]') = _substrat_tuples.object)`, GRANTEE_KEY_RELATION, JSON.stringify(rows));
+    for (const [subject, object] of rows) {
+        db.run('INSERT OR IGNORE INTO _substrat_tuples (subject, relation, object) VALUES (?, ?, ?)', subject, GRANTEE_KEY_RELATION, object);
+    }
+}
+/**
+ * The kernel's event for one (person, entity) a pass changed — a top-up or a retirement — the
+ * audit record, on the entity's own history.
+ */
+function shapeEvent(pass, type, schema, payload) {
+    return domainEvent.parse({
+        id: eventId.parse(pass.mintEventId(Date.parse(pass.now))),
+        type,
+        schemaVersion: 1,
+        occurredAt: pass.now,
+        tenantId: pass.tenantId,
+        scopeId: pass.scopeId,
+        actor: KERNEL_ACTOR,
+        entity: payload.entity,
+        piiClass: 'none',
+        payload: schema.parse(payload),
+    });
+}
+//# sourceMappingURL=entity-grant-shape.js.map

package/dist/entity-grant-shape.js.map

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

package/dist/entity-grant.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `ctx.grant` / `ctx.revoke`'s writes to `_substrat_tuples`, as one statement each for both
+ * adapters (#2071).
+ *
+ * A revoke TOMBSTONES (K-21): the row stays with `revoked_at` set, the checker's walk skips it,
+ * and it stays readable as evidence that the key was taken back. It used to be a `DELETE`,
+ * which left "revoked" and "never held" as the same absent row. That is the one distinction a
+ * declared entity-grant shape's top-up needs (`entity-grant-shape.ts`): a key someone took back
+ * from a person must not come back with the next release.
+ *
+ * A grant is the EXPLICIT write, so it clears a tombstone: a re-grant grants, as
+ * `assignScopeRole` and `HostAdmin.grant` already do. A live row is left exactly as it is,
+ * expiry included, because `ctx.grant` has never shortened or lengthened a grant it found.
+ */
+import type { SwitchSql } from './system-switch.js';
+type Params = [string, string, string];
+/** A reconciled grantee shape's protected key, stored on the scope's tuple spine. */
+export declare const GRANTEE_KEY_RELATION = "shape-grantee-key";
+/** The explicit scope-tuple write for admin/local grants and ctx.grant, behind one shape guard. */
+export declare function writeExplicitTupleIn(db: SwitchSql, subject: string, relation: string, object: string, mode: {
+    kind: 'replace';
+    expiresAt: string | null;
+} | {
+    kind: 'delegated';
+}): void;
+/**
+ * The explicit tuple write: insert it, or bring a tombstoned one back with no expiry. A live
+ * row is untouched. `ctx.grant` and a declared shape's grant (`entity-grant-shape.ts`) share it.
+ */
+export declare function explicitTupleSql(subject: string, relation: string, object: string): {
+    sql: string;
+    params: Params;
+};
+/** `ctx.grant`'s write — {@link explicitTupleSql} on a `granted:` relation. */
+export declare function delegatedGrantSql(principal: string, permission: string, object: string): {
+    sql: string;
+    params: Params;
+};
+/** Tombstone a live grant. A repeat revoke, or a revoke of a grant never made, changes nothing. */
+export declare function delegatedRevokeSql(principal: string, permission: string, object: string, at: string): {
+    sql: string;
+    params: [string, ...Params];
+};
+export {};
+//# sourceMappingURL=entity-grant.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entity-grant.d.ts","sourceRoot":"","sources":["../src/entity-grant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,KAAK,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAEvC,qFAAqF;AACrF,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAgBxD,mGAAmG;AACnG,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,SAAS,EACb,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GAC1E,IAAI,CAcN;AAQD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAOnH;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAExH;AAED,mGAAmG;AACnG,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,GACT;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,CAAA;CAAE,CAM9C"}

package/dist/entity-grant.js

@@ -0,0 +1,71 @@
+/**
+ * `ctx.grant` / `ctx.revoke`'s writes to `_substrat_tuples`, as one statement each for both
+ * adapters (#2071).
+ *
+ * A revoke TOMBSTONES (K-21): the row stays with `revoked_at` set, the checker's walk skips it,
+ * and it stays readable as evidence that the key was taken back. It used to be a `DELETE`,
+ * which left "revoked" and "never held" as the same absent row. That is the one distinction a
+ * declared entity-grant shape's top-up needs (`entity-grant-shape.ts`): a key someone took back
+ * from a person must not come back with the next release.
+ *
+ * A grant is the EXPLICIT write, so it clears a tombstone: a re-grant grants, as
+ * `assignScopeRole` and `HostAdmin.grant` already do. A live row is left exactly as it is,
+ * expiry included, because `ctx.grant` has never shortened or lengthened a grant it found.
+ */
+import { PermissionDenied } from './permission-checker.js';
+/** A reconciled grantee shape's protected key, stored on the scope's tuple spine. */
+export const GRANTEE_KEY_RELATION = 'shape-grantee-key';
+/** Every explicit non-shape scope tuple write uses this guard, including administrative writes. */
+function assertDelegableTuple(db, relation, object) {
+    if (!relation.startsWith('granted:'))
+        return;
+    const colon = object.indexOf(':');
+    if (colon < 0)
+        return;
+    const entityType = object.slice(0, colon);
+    if (db.all('SELECT 1 FROM _substrat_tuples WHERE subject = ? AND relation = ? AND object = ?', `shape:${entityType}`, GRANTEE_KEY_RELATION, relation).length > 0) {
+        throw new PermissionDenied(`cannot grant '${relation.slice('granted:'.length)}' on ${object} — ` +
+            `it is a key of the declared '${entityType}' shape, given only by the shape grant`);
+    }
+}
+/** The explicit scope-tuple write for admin/local grants and ctx.grant, behind one shape guard. */
+export function writeExplicitTupleIn(db, subject, relation, object, mode) {
+    assertDelegableTuple(db, relation, object);
+    if (mode.kind === 'replace') {
+        db.run('INSERT OR REPLACE INTO _substrat_tuples (subject, relation, object, expires_at) VALUES (?, ?, ?, ?)', subject, relation, object, mode.expiresAt);
+    }
+    else {
+        const grant = explicitTupleSql(subject, relation, object);
+        db.run(grant.sql, ...grant.params);
+    }
+}
+const refs = (principal, permission, object) => [
+    `principal:${principal}`,
+    `granted:${permission}`,
+    object,
+];
+/**
+ * The explicit tuple write: insert it, or bring a tombstoned one back with no expiry. A live
+ * row is untouched. `ctx.grant` and a declared shape's grant (`entity-grant-shape.ts`) share it.
+ */
+export function explicitTupleSql(subject, relation, object) {
+    return {
+        sql: `INSERT INTO _substrat_tuples (subject, relation, object) VALUES (?, ?, ?)
+          ON CONFLICT (subject, relation, object) DO UPDATE SET revoked_at = NULL, expires_at = NULL
+          WHERE _substrat_tuples.revoked_at IS NOT NULL`,
+        params: [subject, relation, object],
+    };
+}
+/** `ctx.grant`'s write — {@link explicitTupleSql} on a `granted:` relation. */
+export function delegatedGrantSql(principal, permission, object) {
+    return explicitTupleSql(...refs(principal, permission, object));
+}
+/** Tombstone a live grant. A repeat revoke, or a revoke of a grant never made, changes nothing. */
+export function delegatedRevokeSql(principal, permission, object, at) {
+    return {
+        sql: `UPDATE _substrat_tuples SET revoked_at = ?
+           WHERE subject = ? AND relation = ? AND object = ? AND revoked_at IS NULL`,
+        params: [at, ...refs(principal, permission, object)],
+    };
+}
+//# sourceMappingURL=entity-grant.js.map

package/dist/entity-grant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-grant.js","sourceRoot":"","sources":["../src/entity-grant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAK3D,qFAAqF;AACrF,MAAM,CAAC,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AAExD,mGAAmG;AACnG,SAAS,oBAAoB,CAAC,EAAa,EAAE,QAAgB,EAAE,MAAc;IAC3E,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO;IAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO;IACtB,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAC1C,IAAI,EAAE,CAAC,GAAG,CAAC,kFAAkF,EAAE,SAAS,UAAU,EAAE,EAAE,oBAAoB,EAAE,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjK,MAAM,IAAI,gBAAgB,CACxB,iBAAiB,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,MAAM,KAAK;YACnE,gCAAgC,UAAU,wCAAwC,CACrF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,oBAAoB,CAClC,EAAa,EACb,OAAe,EACf,QAAgB,EAChB,MAAc,EACd,IAA2E;IAE3E,oBAAoB,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC3C,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,EAAE,CAAC,GAAG,CACJ,qGAAqG,EACrG,OAAO,EACP,QAAQ,EACR,MAAM,EACN,IAAI,CAAC,SAAS,CACf,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC1D,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;AACH,CAAC;AAED,MAAM,IAAI,GAAG,CAAC,SAAiB,EAAE,UAAkB,EAAE,MAAc,EAAU,EAAE,CAAC;IAC9E,aAAa,SAAS,EAAE;IACxB,WAAW,UAAU,EAAE;IACvB,MAAM;CACP,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,QAAgB,EAAE,MAAc;IAChF,OAAO;QACL,GAAG,EAAE;;wDAE+C;QACpD,MAAM,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC;KACpC,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,iBAAiB,CAAC,SAAiB,EAAE,UAAkB,EAAE,MAAc;IACrF,OAAO,gBAAgB,CAAC,GAAG,IAAI,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,kBAAkB,CAChC,SAAiB,EACjB,UAAkB,EAClB,MAAc,EACd,EAAU;IAEV,OAAO;QACL,GAAG,EAAE;oFAC2E;QAChF,MAAM,EAAE,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;KACrD,CAAC;AACJ,CAAC"}

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

@@ -8,7 +8,7 @@
 import { type EntityStateName } from '@substrat-run/contracts';
 import { type EntityStatePlan, type StateCheck } from './entity-state.js';
 import { type ListIndexPlan } from './list-index.js';
-import type { OperationContext } from './scope-host.js';
+import type { OperationContext, PageParams } from './scope-host.js';
 import { type SearchIndexPlan } from './search-index.js';
 /**
  * Refuse the bin on the UNCHECKED readers. `ctx.page` and `ctx.search` check no permission, so
@@ -29,14 +29,11 @@ export interface TrashedReadDeps {
     searchPlans: ReadonlyMap<string, SearchIndexPlan>;
     statePlans: ReadonlyMap<string, EntityStatePlan>;
     check: StateCheck;
-    /** Rows one trashed page may read looking for visible ones — `TRASH_SCAN_BUDGET` unless a test narrows it. */
+    /** Test override; a sealed production walk chooses a private budget up to `TRASH_SCAN_BUDGET`. */
     scanBudget?: number;
+    continuation?: (entityType: string, params: PageParams) => ReturnType<OperationContext['pageContinuation']>;
 }
-/**
- * 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.
- */
+/** Maximum number of binned rows one `ctx.pageTrashed` call reads. */
 export declare const TRASH_SCAN_BUDGET = 2000;
 export type TrashedReads = Pick<OperationContext, 'pageTrashed' | 'searchTrashed'>;
 export declare function createTrashedReads(deps: TrashedReadDeps): TrashedReads;

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

@@ -1 +1 @@
-{"version":3,"file":"entity-state-reads.d.ts","sourceRoot":"","sources":["../src/entity-state-reads.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAgD,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACxH,OAAO,EAAoC,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAQrH;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,EAChD,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,eAAe,GAAG,SAAS,GAChC,MAAM,GAAG,SAAS,CAGpB;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAC9E,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC9C,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAClD,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACjD,KAAK,EAAE,UAAU,CAAC;IAClB,8GAA8G;IAC9G,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,OAAQ,CAAC;AAEvC,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,gBAAgB,EAAE,aAAa,GAAG,eAAe,CAAC,CAAC;AAyBnF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,YAAY,CAsFtE"}
+{"version":3,"file":"entity-state-reads.d.ts","sourceRoot":"","sources":["../src/entity-state-reads.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAOL,KAAK,eAAe,EAErB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAgD,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACxH,OAAO,EAAoC,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAQrH;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,EAChD,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,eAAe,GAAG,SAAS,GAChC,MAAM,GAAG,SAAS,CAGpB;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,OAAO,EAAE,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAC9E,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC9C,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAClD,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACjD,KAAK,EAAE,UAAU,CAAC;IAClB,kGAAkG;IAClG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,UAAU,CAAC,gBAAgB,CAAC,kBAAkB,CAAC,CAAC,CAAC;CAC7G;AAED,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,OAAsB,CAAC;AAErD,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,gBAAgB,EAAE,aAAa,GAAG,eAAe,CAAC,CAAC;AAyBnF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,YAAY,CA2DtE"}