@substrat-run/kernel 0.142.0 → 0.144.0

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

@@ -36,13 +36,25 @@ import type { SwitchSql } from './system-switch.js';
  *   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.
+ *   person's record is never marked. A shape with no `holder` gets no backfill. It is read in
+ *   windows like the walks (#2154): each pass reads at most its read budget of rows, in an index
+ *   order, marks at most its write budget, and hands back the last row it read as the cursor's
+ *   `row`, so the next pass seeks past it rather than re-reading from the start. A record tuple
+ *   (`shape:<type>`, `shape-backfilled`, `scope:<id>`) ends it once a read reaches the end of the
+ *   range, and never before. A table holder's read is keyed on `idColumn` and then the row's own
+ *   identity (its `rowid`, or a `WITHOUT ROWID` table's primary key), because nothing makes
+ *   `idColumn` unique or the principal non-NULL, and a key that ties lets a window's edge skip a row.
+ *
+ *   The cut-off is the cursor. Evidence that lands behind it while the backfill runs (a direct
+ *   grant of a shape key to the person on their own record, for `'self'` or a table holder) is not
+ *   marked, and once the record is written nothing is: the same accepted gap as a grant landing
+ *   after the record. There is deliberately no confirming walk, as a retirement has: it would
+ *   double every first backfill's reads to catch a grant that a shape grant should have made. For
+ *   `'grantee'` nothing can land at all, since the first pass records the grantee keys and the
+ *   tuple writer refuses them to every other grant from then on.
  * - `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
+ *   Each reconcile 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.
@@ -51,8 +63,36 @@ import type { SwitchSql } from './system-switch.js';
  * 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.
  */
+/**
+ * The index every marker walk reads (#2083): markers only, in `(object, subject)` order, so one
+ * shape's markers are one range (`<type>:` up to `<type>;`) and a pass's cursor is a seek into
+ * it. Without it a pass scanned the whole `_substrat_tuples` table, even when it had nothing to
+ * do. Partial, so it costs a row per marker and nothing for any other tuple. SQLite uses a
+ * partial index only where it can prove the index's WHERE from the query's, so the walks write the
+ * relation as this same literal: proved from the text alone, with no dependence on SQLite
+ * re-planning once a parameter is bound. In KERNEL_DDL on both adapters, which every wake re-runs,
+ * so an existing scope builds it on its next wake.
+ */
+export declare const SHAPE_MARKER_INDEX_DDL = "CREATE INDEX IF NOT EXISTS _substrat_tuples_shape_marker ON _substrat_tuples (object, subject) WHERE relation = 'bootstrap'";
 /** Holders topped up per pass — one transaction each, so a large scope never holds one long. */
 export declare const SHAPE_TOP_UP_BATCH = 500;
+/**
+ * Rows a pass may READ, per row of work it may write: markers on a walk, and the tuples or table
+ * rows the backfill reads for candidates (#2154). The budget bounds writes, but finding
+ * the holders who need one means reading past the ones who do not, and on a scope where nobody
+ * does (the common reconcile: nothing changed) that is every marker. Ten per row keeps a pass at
+ * 5000 index rows by default, short on any scope, while a rollout still spends most of each pass
+ * writing. A pass that reads its window without filling its budget hands back a cursor, and the
+ * next pass reads on from there.
+ */
+export declare const SHAPE_MARKER_READS_PER_ROW = 10;
+/**
+ * Confirming walks that may take keys, per shape per reconcile, before its retirement is left open
+ * for the next reconcile. Each one that takes keys starts another, so a steady stream of grants of
+ * a retired key landing ahead of the walk would otherwise keep a single reconcile walking forever.
+ * Left open, the retirement keeps no record, so the next reconcile simply runs it again.
+ */
+export declare const SHAPE_RETIRE_CONFIRMS_MAX = 3;
 /** 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. */
@@ -64,6 +104,54 @@ export declare function shapeTopUpBatch(batch?: number): number;
  * 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 stopped, so the next pass of the same reconcile starts there instead of at the
+ * first marker (#2083): the shape (its index in `shapes`), the step of it, and for a marker walk
+ * the last marker it read. Without it every pass re-read the holders earlier passes had already
+ * finished, and a rollout cost passes × markers.
+ *
+ * Skipping what lies behind it is safe because a walk leaves every marker it passes finished:
+ * topped up (each key now has a row) or with its retired keys tombstoned. A marker written behind
+ * it mid-run is complete when a shape grant writes it, and the backfill finishes before its
+ * shape's walks begin. The exception is a shape grant by an OLDER deployment, carrying the shape
+ * as it was, landing behind the cursor while the reconcile runs:
+ *
+ * - Missing a key the shape gained: the top-up keeps no record, so the next reconcile's top-up
+ *   reaches that holder.
+ * - Holding a key the shape retired: a retirement ends in a run-once record, so a holder it never
+ *   saw would never be reached. The first walk therefore never writes that record. Once it reaches
+ *   the last marker, a CONFIRMING walk starts again from the first (`confirm`), and the record is
+ *   written only when a confirming walk reaches the last marker having taken nothing; one that
+ *   took keys starts another, up to `SHAPE_RETIRE_CONFIRMS_MAX`; past that the retirement is left
+ *   open for the next reconcile. A grant landing behind the confirming walk itself is the gap
+ *   left, the same as one landing after the retirement finished.
+ */
+export interface ShapeCursor {
+    shape: number;
+    step: 'backfill' | 'retire' | 'topUp';
+    /** The last marker a walk read; `null` resumes the step from its start. */
+    marker: {
+        object: string;
+        subject: string;
+    } | null;
+    /**
+     * The backfill only (#2154): the sort key of the last row its read reached, `[object, relation,
+     * subject]` of a tuple for a `'self'` or `'grantee'` holder, `[id, rowid]` for a table holder
+     * (`[id, …primary key]` for a `WITHOUT ROWID` table). Absent
+     * or `null` reads the backfill from its start, which is always safe: a pair it already marked
+     * is no longer a candidate, so a cursor from before this field (or one a rollback ignores) only
+     * costs a re-read.
+     */
+    row?: readonly (string | number)[] | null;
+    /**
+     * A confirming retire walk only: whether it has taken nothing so far, and how many confirming
+     * walks before it, on this shape in this reconcile, took keys.
+     */
+    confirm?: {
+        clean: boolean;
+        count: number;
+    };
+}
 /** Where a pass runs and how its events are stamped — the facts only the adapter holds. */
 export interface ShapePass {
     tenantId: string;
@@ -73,22 +161,49 @@ export interface ShapePass {
     now: string;
     /** Rows of work at most: a backfill mark or a holder topped up each count one. */
     limit: number;
+    /** The previous pass's `next`; absent or `null` starts the reconcile from the beginning. */
+    after?: ShapeCursor | null;
     /** 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.
+ * One pass of the reconcile over one scope, at most `limit` rows of work and
+ * `limit × SHAPE_MARKER_READS_PER_ROW` rows read (markers, and the backfill's tuples or table
+ * rows): 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. `next` is `null` once the scope is done; otherwise the caller runs another pass with it
+ * as `after`. `retirementsLeftOpen` counts the shapes whose retirement this pass gave up on at
+ * `SHAPE_RETIRE_CONFIRMS_MAX`, for the next reconcile to run again. 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;
+    retirementsLeftOpen: number;
+    next: ShapeCursor | null;
 };
+/**
+ * A BINDING shape's record (#1686), on the scope's tuple spine beside the grantee keys: which
+ * table column names the record's person (`<table>.<idColumn>.<principalColumn>`), the key that
+ * lets someone bind or unbind them, and the shape's current keys — what a binding invite's claim
+ * gives. The claim and an unbind read these, never the vertical's code: the shape is the reviewed
+ * registry the platform last reconciled this scope with. Each identifier is a SQL identifier, so
+ * `.` cannot occur inside one.
+ */
+export declare const BIND_HOLDER_RELATION = "shape-bind-holder";
+export declare const BIND_PERMISSION_RELATION = "shape-bind-permission";
+export declare const BIND_KEY_RELATION = "shape-bind-key";
+/**
+ * `(shape:<type>, shape-bound, bound)`: this scope has declared a binding for `<type>` (#1686).
+ * Written by the first reconcile that records the binding (and by every claim, to the same effect)
+ * and STICKY — no reconcile removes it, whatever later
+ * versions declare — so an erasure keeps releasing that type's holders after a version drops the
+ * shape, drops its `bind` or moves its holder column. A spine tuple like the others here, so
+ * module code can never write one (`ctx.sql` refuses every `_substrat_*` write).
+ */
+export declare const BOUND_EVER_RELATION = "shape-bound";
 //# sourceMappingURL=entity-grant-shape.d.ts.map

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

@@ -1 +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"}
+{"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;AAMpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,gIAAsJ,CAAC;AAE1L,gGAAgG;AAChG,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAC7C;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAC3C,2GAA2G;AAC3G,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,KAAK,GAAE,MAA2B,GAAG,MAAM,CAS1E;AAuBD;;;;;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;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;IACtC,2EAA2E;IAC3E,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACnD;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC;IAC1C;;;OAGG;IACH,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;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,4FAA4F;IAC5F,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,sEAAsE;IACtE,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,sEAAsE;IACtE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,SAAS,EACb,IAAI,EAAE,SAAS,GACd;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CA+D9F;AAuZD;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AACxD,eAAO,MAAM,wBAAwB,0BAA0B,CAAC;AAChE,eAAO,MAAM,iBAAiB,mBAAmB,CAAC;AAClD;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,gBAAgB,CAAC"}