@substrat-run/kernel 0.137.0 → 0.139.0

package/dist/membership-executor.js

@@ -0,0 +1,261 @@
+import { instant, orgId, principalId, z, } from '@substrat-run/contracts';
+import { isUnknownRoleError } from './permission-checker.js';
+import { refuseDelivery } from './delivery-refusal.js';
+import {} from './scope-host.js';
+/**
+ * The membership executor (K-22 §4.2, membership.md §4.2; #1184) — the out-of-band half of
+ * joining and leaving, written once so a host mounts it instead of hand-rolling the effect.
+ *
+ * Module code asks in its own transaction and this effects after commit, through `HostAdmin`:
+ * an invite engine's accept emits `member.add-requested`; a vertical's removal emits
+ * `member.remove-requested`. A rolled-back operation leaves no event and nothing to effect.
+ * Both are driven inline by the emitting call, with the outbox and `_substrat_deliveries` as
+ * the retry backstop, so the common case completes inside the request.
+ *
+ * **What it effects: a tenant-level role, and — opted into — the org.** An add assigns the
+ * invited role at the tenant node; a removal unassigns it. By default neither joins nor leaves
+ * the org both payloads name (the invites engine keys its invitations by org). A mount with
+ * `orgs: 'join'` (#2047) also joins it on an add and takes the person out of it on a removal, in
+ * the same directory unit as the role, bounded by MEMBERSHIP: the inviter or remover must be a
+ * live member of that org. A member holds everything the org confers, at every node — its
+ * grants in each scope's own store included — so that is the exact bound, and no scope store
+ * is read. A tenant admin who is not a member of the org cannot invite anyone into it, by
+ * design. A join's membership expires no later than the inviter's own: a temporary member
+ * cannot confer a permanent one.
+ *
+ * **Authority.** Every payload field is module-written, so none of them is authority.
+ *
+ * - An ADD is bounded by the inviter: the kernel-stamped `actor` of the invitation's own
+ *   `invites.sent` event, asked through the K-21 set comparison at the tenant node. Asked
+ *   twice: early, to refuse cheaply, and again inside the directory unit that writes the role
+ *   (`applyMembership`), so a demotion, a grant lost or a role widened in between is not
+ *   written past. The joiner is the request's own actor, who must have made the invitation's
+ *   first acceptance, and the request must be the first one naming that invitation: one
+ *   invitation, one join. The most a module can do is make the principal who actually invoked
+ *   it look like the sender — the same delegation bound `ctx.grant` has.
+ * - A REMOVE is bounded by the remover, the request's own actor (§5.1: removal takes the
+ *   same bound, or a junior admin could strip a role they could not have granted) — asked the
+ *   same two ways, so a remover demoted in between removes nobody.
+ *
+ * **Removal wins.** An add is refused when the joiner was removed after it was requested: by a
+ * later `member.remove-requested` on the same membership (ordered by outbox id), or by any
+ * tenant-level removal at all — staff's included, and a no-op one — which raises the person's
+ * removal fence in the directory unit that revokes. The add's own unit reads the fence, and a
+ * fence at or after `occurredAt - MEMBERSHIP_REMOVAL_SKEW_MS` refuses it.
+ *
+ * A refusal is terminal (`refuseDelivery`): journaled with its reason, never retried, listed
+ * by `executorDeadLetters`, and reported to the emitting call through `onExecutorOutcomes`.
+ *
+ * **The trail.** Admin rows are written by `actor`, the platform identity that executed them,
+ * `onBehalfOf` (#977) the person whose authority bounded them, and with `causedBy` = the event
+ * id: the correlation id that joins the scope's half of the trail to the directory's. A
+ * removal that took nothing writes no row (K-21), but still raises the fence.
+ *
+ * **Idempotent.** A delivered event never reaches its handler again. A crash between the
+ * effect and its journal row re-runs the handler, and every write it makes is idempotent.
+ */
+/** What the add path consumes, and the version it reads. */
+export const MEMBER_ADD_REQUESTED = 'member.add-requested';
+/** What the remove path consumes, and the version it reads. */
+export const MEMBER_REMOVE_REQUESTED = 'member.remove-requested';
+/** The delivery-journal id of the add path unless a mount names another (`executor:membership`). */
+export const MEMBERSHIP_EXECUTOR_ID = 'membership';
+/** The remove path's id, derived from the add path's: `<id>-remove`. */
+export const membershipRemoveExecutorId = (id = MEMBERSHIP_EXECUTOR_ID) => `${id}-remove`;
+/** The membership entity both requests are emitted on — what orders a removal after an add. */
+export const membershipEntity = (principal) => ({ entityType: 'membership', entityId: principal });
+/** The executor's own parse of an add (D-19: never the producer's types). */
+const memberAddRequested = z.object({
+    principal: principalId,
+    orgId,
+    tenantId: z.string(),
+    roleKey: z.string().min(1),
+    invitationId: z.string().min(1),
+});
+/**
+ * `member.remove-requested` v1 — what a vertical emits to take someone out: the role it
+ * holds them at, and the org its invitation named. Fat (D-19), like the add. The executor
+ * takes the role away; the org is the vertical's own vocabulary and is not touched.
+ */
+export const memberRemoveRequestedPayload = z.object({
+    principal: principalId,
+    orgId,
+    tenantId: z.string(),
+    roleKey: z.string().min(1),
+});
+/** What `invites.sent` and `invites.accepted` must agree with the request on. */
+const invitationFacts = z.object({ orgId: z.string(), roleKey: z.string() });
+const acceptedFacts = z.object({ principal: z.string() });
+/**
+ * How far before a request a removal still wins over it (#1184): 5 minutes. A removal's fence
+ * is stamped by the directory's clock; the request is a scope event stamped by the scope's.
+ * The two stores share no causal order, so a tie goes to the removal and so does anything
+ * within this skew. The cost, stated: someone removed less than this before they accept a NEW
+ * invite is refused — resend it. Removals through the seam are also ordered by outbox id.
+ */
+export const MEMBERSHIP_REMOVAL_SKEW_MS = 5 * 60_000;
+/** Mount the membership executor — both paths — on a host. One call, at host construction. */
+export function registerMembershipExecutor(host, options) {
+    if (options.level !== undefined && options.level !== 'tenant') {
+        throw new Error(`the membership executor is tenant-level only (got level '${String(options.level)}'): no single operation ` +
+            'spans the directory and a scope store. A scope role has assignScopeRoleBounded.');
+    }
+    const id = options.id ?? MEMBERSHIP_EXECUTOR_ID;
+    // The org a request names rides along only on a mount that joins orgs (#2047).
+    const orgOf = (request) => (options.orgs === 'join' ? { orgId: request.orgId } : {});
+    // Attributed (#977): the person whose authority bounded the write, beside the platform
+    // actor that executed it. `causedBy` is passed, never stamped by the host (#2055): a view of
+    // the host is not the `admin` the dispatch handed the handler, so the event goes with it.
+    // A host without `attributed` writes through that `admin`, which carries the event already.
+    const adminFor = (admin, who, event) => host.attributed?.({ principal: who, tenantId: event.tenantId }, { causedBy: event.id }).admin ?? admin;
+    host.registerExecutor(id, MEMBER_ADD_REQUESTED, async (admin, event, scope) => {
+        const decided = await authorizeAdd(event, scope);
+        if ('refused' in decided)
+            return decided.refused;
+        const { request, inviter } = decided;
+        // One directory unit: the fence, the bound asked again, the role and its audit row. A
+        // removal or a change of authority lands wholly before it or wholly after it.
+        const applied = await adminFor(admin, inviter, event).applyMembership(options.actor, {
+            op: 'add',
+            tenantId: event.tenantId,
+            principal: request.principal,
+            roleKey: request.roleKey,
+            boundedBy: inviter,
+            ...orgOf(request),
+            unlessRemovedSince: instant.parse(new Date(Date.parse(event.occurredAt) - MEMBERSHIP_REMOVAL_SKEW_MS).toISOString()),
+        });
+        return applied.applied ? undefined : refusalOf(applied, request, 'inviter', inviter);
+    }, options.retry);
+    host.registerExecutor(membershipRemoveExecutorId(id), MEMBER_REMOVE_REQUESTED, async (admin, event, scope) => {
+        const decided = await authorizeRemove(event, scope);
+        if ('refused' in decided)
+            return decided.refused;
+        const { request, remover } = decided;
+        // One directory unit: the remover's bound asked again, the revoke, its audit row if it
+        // took anything, and the fence — raised even with nothing held, so a pending add sees it.
+        const applied = await adminFor(admin, remover, event).applyMembership(options.actor, {
+            op: 'remove',
+            tenantId: event.tenantId,
+            principal: request.principal,
+            roleKey: request.roleKey,
+            boundedBy: remover,
+            ...orgOf(request),
+        });
+        return applied.applied ? undefined : refusalOf(applied, request, 'remover', remover);
+    }, options.retry);
+}
+/** Why a directory unit applied nothing, as the refusal the journal keeps. */
+function refusalOf(result, request, as, who) {
+    if ('removedAt' in result)
+        return refuseDelivery(`${request.principal} was removed after this request was made`);
+    if ('unknownRole' in result)
+        return refuseDelivery(`no such role in this tenant: ${result.unknownRole}`);
+    if ('unknownOrg' in result)
+        return refuseDelivery(`no such org in this tenant: ${result.unknownOrg}`);
+    if ('notMember' in result)
+        return refuseDelivery(`the ${as} ${who} is not a member of org ${result.notMember}`);
+    return refuseDelivery(`the ${as} ${who} no longer holds ${result.missing.join(', ')}, which '${request.roleKey}' confers`);
+}
+const refused = (reason) => ({ refused: refuseDelivery(reason) });
+/** Parse a request and hold it to its own envelope's tenant. Version 1 is the one read. */
+function requestOf(event, schema) {
+    if (event.schemaVersion !== 1)
+        return refused(`unsupported ${event.type} schemaVersion ${event.schemaVersion}`);
+    const parsed = schema.safeParse(event.payload);
+    if (!parsed.success)
+        return refused(`malformed ${event.type} payload`);
+    // The tenant on the envelope is kernel-stamped; the one in the payload is not.
+    if (parsed.data.tenantId !== event.tenantId)
+        return refused('the request names a tenant other than its own');
+    return { request: parsed.data };
+}
+/** §5.1's bound for `who` over `roleKey` at the tenant node, or the refusal saying what is missing. */
+async function bounded(scope, who, roleKey, as) {
+    // Read the way the unit's own answer is, so one `refusalOf` words both.
+    let refusal;
+    try {
+        const bound = await scope.covers(who, roleKey, 'tenant');
+        refusal = bound.covered ? null : { applied: false, missing: bound.missing };
+    }
+    catch (err) {
+        if (!isUnknownRoleError(err, roleKey))
+            throw err;
+        refusal = { applied: false, unknownRole: roleKey };
+    }
+    return refusal && { refused: refusalOf(refusal, { principal: who, roleKey }, as, who) };
+}
+/** Everything that decides whether an add may be effected. Reads only. */
+async function authorizeAdd(event, scope) {
+    const parsed = requestOf(event, memberAddRequested);
+    if ('refused' in parsed)
+        return parsed;
+    const { request } = parsed;
+    // The joiner is whoever invoked the accept — the envelope's actor, not a payload claim.
+    if (event.actor !== request.principal)
+        return refused('the request names a principal other than the one who accepted');
+    const history = await everything(scope, { entityType: 'invitation', entityId: request.invitationId });
+    const sent = history.filter((e) => e.type === 'invites.sent');
+    if (sent.length !== 1)
+        return refused(`invitation ${request.invitationId} has no single send to take authority from`);
+    const send = sent[0];
+    const sendFacts = invitationFacts.safeParse(send.payload);
+    if (!sendFacts.success || sendFacts.data.orgId !== request.orgId || sendFacts.data.roleKey !== request.roleKey) {
+        return refused(`the request does not match invitation ${request.invitationId} as it was sent`);
+    }
+    // Single use: the FIRST acceptance decides who joins. A later one — by anyone — joins
+    // nobody, and cannot unseat the first, whose delivery may still be retrying.
+    const first = history.find((e) => e.type === 'invites.accepted');
+    const acceptance = first ? acceptedFacts.safeParse(first.payload) : null;
+    if (!acceptance?.success || first.actor !== event.actor || acceptance.data.principal !== request.principal) {
+        return refused(`invitation ${request.invitationId} was not first accepted by ${request.principal}`);
+    }
+    const inviter = principalId.safeParse(send.actor);
+    if (!inviter.success)
+        return refused(`invitation ${request.invitationId} was not sent by a principal`);
+    // One invitation, one join. The request must follow the acceptance and be the FIRST
+    // request naming this invitation on the joiner's membership — outbox ids are kernel-minted
+    // and append-only, so the first request consumes the invitation for good, and a fresh one
+    // emitted later (after a removal, say) is refused however its payload reads.
+    if (first.id > event.id)
+        return refused(`the request precedes invitation ${request.invitationId}'s acceptance`);
+    const membership = await everything(scope, membershipEntity(request.principal));
+    const earlier = membership.find((e) => e.type === MEMBER_ADD_REQUESTED && e.id < event.id && invitationOf(e) === request.invitationId);
+    if (earlier)
+        return refused(`invitation ${request.invitationId} was already used, by request ${earlier.id}`);
+    // A removal through the seam, ordered after this request by outbox id. Every removal also
+    // raises the fence `applyMembership` reads inside the unit that writes.
+    if (membership.some((e) => e.type === MEMBER_REMOVE_REQUESTED && e.id > event.id)) {
+        return refused(`${request.principal} was removed after this request was made`);
+    }
+    // The early refusal; `applyMembership` asks the same bound again inside its unit.
+    const bound = await bounded(scope, inviter.data, request.roleKey, 'inviter');
+    return bound ?? { request, inviter: inviter.data };
+}
+/** Everything that decides whether a removal may be effected. Reads only. */
+async function authorizeRemove(event, scope) {
+    const parsed = requestOf(event, memberRemoveRequestedPayload);
+    if ('refused' in parsed)
+        return parsed;
+    const remover = principalId.safeParse(event.actor);
+    if (!remover.success)
+        return refused('the removal was not requested by a principal');
+    const bound = await bounded(scope, remover.data, parsed.request.roleKey, 'remover');
+    return bound ?? { request: parsed.request, remover: remover.data };
+}
+/** The invitation an add request names, read the way the executor reads a request. */
+function invitationOf(entry) {
+    const parsed = memberAddRequested.safeParse(entry.payload);
+    return parsed.success ? parsed.data.invitationId : undefined;
+}
+/** One entity's whole history, oldest first. Short by construction: a handful of events. */
+async function everything(scope, entity) {
+    const entries = [];
+    let cursor;
+    do {
+        const page = await scope.history(entity, { cursor });
+        entries.push(...page.entries);
+        cursor = page.nextCursor ?? undefined;
+    } while (cursor);
+    return entries;
+}
+//# sourceMappingURL=membership-executor.js.map

package/dist/membership-executor.js.map

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

package/dist/membership-fence.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The removal fence (#1184): one row per (tenant, principal), stamped with the latest moment
+ * that person was removed at the tenant level. The membership executor's add reads it inside
+ * the directory unit that assigns the role, and applies nothing when it stands at or after
+ * the request's `occurredAt - MEMBERSHIP_REMOVAL_SKEW_MS`.
+ *
+ * A table of its own rather than a read of the admin log, because K-21's audit contract
+ * writes no row for a removal that took nothing — and a removal of someone whose add is still
+ * on its way takes nothing, yet must still win. Every tenant-level `unassignRole` and every
+ * `removeMember` raises it in the SAME unit as its revoke, staff's and the executor's alike,
+ * a no-op included. Never lowered: a later removal moves it forward, an earlier one does not.
+ *
+ * The admin log is still the history. This is only the latest position.
+ */
+/**
+ * The table. Interpolated into both adapters' directory DDL, so `lint:spine-ddl` sees the one
+ * spelling on each side, and a directory dump carries it like every other directory table.
+ */
+export declare const MEMBERSHIP_FENCES_DDL = "\n  CREATE TABLE IF NOT EXISTS _substrat_membership_fences (\n    tenant_id  TEXT NOT NULL,\n    principal  TEXT NOT NULL,\n    removed_at TEXT NOT NULL,\n    PRIMARY KEY (tenant_id, principal)\n  );\n";
+/** Raise `principal`'s fence to `removed_at`, never lower it. Binds tenant, principal, at. */
+export declare const RAISE_MEMBERSHIP_FENCE_SQL = "\n  INSERT INTO _substrat_membership_fences (tenant_id, principal, removed_at) VALUES (?, ?, ?)\n  ON CONFLICT (tenant_id, principal) DO UPDATE SET removed_at = MAX(removed_at, excluded.removed_at)\n";
+/** The fence, if it stands at or after an instant. Binds tenant, principal, since. */
+export declare const MEMBERSHIP_FENCE_SINCE_SQL = "\n  SELECT removed_at FROM _substrat_membership_fences\n  WHERE tenant_id = ? AND principal = ? AND removed_at >= ?\n";
+/** The fence's table name, as the DDL above spells it. */
+export declare const MEMBERSHIP_FENCES_TABLE = "_substrat_membership_fences";
+/**
+ * The one-time backfill from the admin log: everyone removed at the tenant level before the
+ * fence existed. Without it, an add requested back then and never effected — the backlog a host
+ * that mounts the executor for the first time drains — would re-admit someone removed by hand
+ * since, because the fence would have nothing to say about them.
+ *
+ * It reads who those removals named: an `unassignRole` row at the tenant node (`scope_id` NULL)
+ * carries the assignment as `before.principalId`, a `removeMember` row the membership as
+ * `before.principal`. A no-op removal wrote no row and is not recovered — nothing before the
+ * fence recorded one.
+ *
+ * **Every backfilled fence stands at `at`, the adapter's clock at the moment it runs — never the
+ * audit row's own time** (Codex round 4). Those rows were stamped by the wall clock, while a
+ * request still queued from back then was stamped by the host's clock, which need not agree: a
+ * host clock running ahead would put the copied time below the request's cutoff and the backlog
+ * would re-admit the person. Stamping at backfill time is conservative instead: every request
+ * emitted before it, for anyone ever removed, is refused. That takes nothing legitimate away —
+ * anyone re-added before the executor existed got their role inline, by hand, and holds it
+ * still — and an invite accepted more than `MEMBERSHIP_REMOVAL_SKEW_MS` after it is unaffected.
+ *
+ * `INSERT OR IGNORE`, so a fence the live path raised is never lowered by history. The adapters
+ * run it on the construction that creates the table, and a directory restore runs it when the
+ * dump did not carry the table, so it runs once per directory that never had it.
+ */
+export declare function membershipFencesBackfillSql(at: string): string;
+/** "Does the fence table exist yet?" — asked BEFORE the DDL, so the backfill runs once. */
+export declare function membershipFencesTableExists(db: {
+    all(sql: string, ...params: string[]): unknown[];
+}): boolean;
+/** Does a dump carry the fence table? Compared without case, as SQLite resolves a name. */
+export declare function dumpCarriesMembershipFences(names: readonly string[]): boolean;
+//# sourceMappingURL=membership-fence.d.ts.map

package/dist/membership-fence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"membership-fence.d.ts","sourceRoot":"","sources":["../src/membership-fence.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,eAAO,MAAM,qBAAqB,8MAOjC,CAAC;AAEF,8FAA8F;AAC9F,eAAO,MAAM,0BAA0B,4MAGtC,CAAC;AAEF,sFAAsF;AACtF,eAAO,MAAM,0BAA0B,0HAGtC,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,uBAAuB,gCAAgC,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAiB9D;AAED,2FAA2F;AAC3F,wBAAgB,2BAA2B,CAAC,EAAE,EAAE;IAAE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAAA;CAAE,GAAG,OAAO,CAE7G;AAED,2FAA2F;AAC3F,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAE7E"}

package/dist/membership-fence.js

@@ -0,0 +1,90 @@
+import { instant } from '@substrat-run/contracts';
+/**
+ * The removal fence (#1184): one row per (tenant, principal), stamped with the latest moment
+ * that person was removed at the tenant level. The membership executor's add reads it inside
+ * the directory unit that assigns the role, and applies nothing when it stands at or after
+ * the request's `occurredAt - MEMBERSHIP_REMOVAL_SKEW_MS`.
+ *
+ * A table of its own rather than a read of the admin log, because K-21's audit contract
+ * writes no row for a removal that took nothing — and a removal of someone whose add is still
+ * on its way takes nothing, yet must still win. Every tenant-level `unassignRole` and every
+ * `removeMember` raises it in the SAME unit as its revoke, staff's and the executor's alike,
+ * a no-op included. Never lowered: a later removal moves it forward, an earlier one does not.
+ *
+ * The admin log is still the history. This is only the latest position.
+ */
+/**
+ * The table. Interpolated into both adapters' directory DDL, so `lint:spine-ddl` sees the one
+ * spelling on each side, and a directory dump carries it like every other directory table.
+ */
+export const MEMBERSHIP_FENCES_DDL = `
+  CREATE TABLE IF NOT EXISTS _substrat_membership_fences (
+    tenant_id  TEXT NOT NULL,
+    principal  TEXT NOT NULL,
+    removed_at TEXT NOT NULL,
+    PRIMARY KEY (tenant_id, principal)
+  );
+`;
+/** Raise `principal`'s fence to `removed_at`, never lower it. Binds tenant, principal, at. */
+export const RAISE_MEMBERSHIP_FENCE_SQL = `
+  INSERT INTO _substrat_membership_fences (tenant_id, principal, removed_at) VALUES (?, ?, ?)
+  ON CONFLICT (tenant_id, principal) DO UPDATE SET removed_at = MAX(removed_at, excluded.removed_at)
+`;
+/** The fence, if it stands at or after an instant. Binds tenant, principal, since. */
+export const MEMBERSHIP_FENCE_SINCE_SQL = `
+  SELECT removed_at FROM _substrat_membership_fences
+  WHERE tenant_id = ? AND principal = ? AND removed_at >= ?
+`;
+/** The fence's table name, as the DDL above spells it. */
+export const MEMBERSHIP_FENCES_TABLE = '_substrat_membership_fences';
+/**
+ * The one-time backfill from the admin log: everyone removed at the tenant level before the
+ * fence existed. Without it, an add requested back then and never effected — the backlog a host
+ * that mounts the executor for the first time drains — would re-admit someone removed by hand
+ * since, because the fence would have nothing to say about them.
+ *
+ * It reads who those removals named: an `unassignRole` row at the tenant node (`scope_id` NULL)
+ * carries the assignment as `before.principalId`, a `removeMember` row the membership as
+ * `before.principal`. A no-op removal wrote no row and is not recovered — nothing before the
+ * fence recorded one.
+ *
+ * **Every backfilled fence stands at `at`, the adapter's clock at the moment it runs — never the
+ * audit row's own time** (Codex round 4). Those rows were stamped by the wall clock, while a
+ * request still queued from back then was stamped by the host's clock, which need not agree: a
+ * host clock running ahead would put the copied time below the request's cutoff and the backlog
+ * would re-admit the person. Stamping at backfill time is conservative instead: every request
+ * emitted before it, for anyone ever removed, is refused. That takes nothing legitimate away —
+ * anyone re-added before the executor existed got their role inline, by hand, and holds it
+ * still — and an invite accepted more than `MEMBERSHIP_REMOVAL_SKEW_MS` after it is unaffected.
+ *
+ * `INSERT OR IGNORE`, so a fence the live path raised is never lowered by history. The adapters
+ * run it on the construction that creates the table, and a directory restore runs it when the
+ * dump did not carry the table, so it runs once per directory that never had it.
+ */
+export function membershipFencesBackfillSql(at) {
+    // Interpolated, not bound: the adapters run it through `exec`. `instant` holds it to an
+    // ISO-8601 UTC timestamp, which carries no quote, or throws.
+    return `
+  INSERT OR IGNORE INTO _substrat_membership_fences (tenant_id, principal, removed_at)
+  SELECT DISTINCT tenant_id, principal, '${instant.parse(at)}'
+    FROM (
+      SELECT tenant_id, json_extract(before, '$.principalId') AS principal
+        FROM _substrat_admin_log
+       WHERE action = 'unassignRole' AND tenant_id IS NOT NULL AND scope_id IS NULL
+      UNION ALL
+      SELECT tenant_id, json_extract(before, '$.principal') AS principal
+        FROM _substrat_admin_log
+       WHERE action = 'removeMember' AND tenant_id IS NOT NULL
+    )
+   WHERE principal IS NOT NULL
+`;
+}
+/** "Does the fence table exist yet?" — asked BEFORE the DDL, so the backfill runs once. */
+export function membershipFencesTableExists(db) {
+    return db.all(`SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = ?`, MEMBERSHIP_FENCES_TABLE).length > 0;
+}
+/** Does a dump carry the fence table? Compared without case, as SQLite resolves a name. */
+export function dumpCarriesMembershipFences(names) {
+    return names.some((n) => n.toLowerCase() === MEMBERSHIP_FENCES_TABLE);
+}
+//# sourceMappingURL=membership-fence.js.map

package/dist/membership-fence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"membership-fence.js","sourceRoot":"","sources":["../src/membership-fence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAElD;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;CAOpC,CAAC;AAEF,8FAA8F;AAC9F,MAAM,CAAC,MAAM,0BAA0B,GAAG;;;CAGzC,CAAC;AAEF,sFAAsF;AACtF,MAAM,CAAC,MAAM,0BAA0B,GAAG;;;CAGzC,CAAC;AAEF,0DAA0D;AAC1D,MAAM,CAAC,MAAM,uBAAuB,GAAG,6BAA6B,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,2BAA2B,CAAC,EAAU;IACpD,wFAAwF;IACxF,6DAA6D;IAC7D,OAAO;;2CAEkC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;;;;;;;;;;;CAW3D,CAAC;AACF,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,2BAA2B,CAAC,EAAwD;IAClG,OAAO,EAAE,CAAC,GAAG,CAAC,0EAA0E,EAAE,uBAAuB,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AAChI,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,2BAA2B,CAAC,KAAwB;IAClE,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,uBAAuB,CAAC,CAAC;AACxE,CAAC"}

package/dist/module-migrations.d.ts

@@ -1,11 +1,13 @@
+import type { EntityStateDeclaration } from '@substrat-run/contracts';
 import { type ListDeclaration } from './list-index.js';
 import { type SearchableDeclaration } from './search-index.js';
 import type { SqlMigration } from './scope-host.js';
 /**
  * Every migration a module's scope applies, in the order the host applies them: the module's
- * own `migrations`, then the search indexes its `searchables` declare (#827), then the list
- * indexes its `lists` declare (#811). The two derived sets come after the authored ones because
- * their DDL names the tables those create.
+ * own `migrations`, then the search indexes its `searchables` declare (#827), then the archive and
+ * trash columns its `entityStates` declare (#119), then the list indexes its `lists` declare
+ * (#811). The derived sets come after the authored ones because their DDL names the tables those
+ * create, and the columns come before the list indexes because a partial index names them.
  *
  * The one place that order is written. Both hosts store what this returns as a module's
  * migrations, and `substrat push` calls it (from the vertical's own kernel) to carry the SQL a
@@ -20,6 +22,7 @@ export declare function moduleMigrations(registration: {
         readonly id: string;
         readonly searchables?: readonly SearchableDeclaration[];
         readonly lists?: readonly ListDeclaration[];
+        readonly entityStates?: readonly EntityStateDeclaration[];
     };
     readonly migrations?: readonly SqlMigration[];
 }): SqlMigration[];

package/dist/module-migrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module-migrations.d.ts","sourceRoot":"","sources":["../src/module-migrations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAyB,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACtF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE;IAC7C,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;QACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;KAC7C,CAAC;IACF,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC/C,GAAG,YAAY,EAAE,CAGjB"}
+{"version":3,"file":"module-migrations.d.ts","sourceRoot":"","sources":["../src/module-migrations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAEtE,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAyB,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACtF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE;IAC7C,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;QACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;QAC5C,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;KAC3D,CAAC;IACF,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC/C,GAAG,YAAY,EAAE,CAQjB"}

package/dist/module-migrations.js

@@ -1,10 +1,12 @@
+import { entityStateMigrations } from './entity-state.js';
 import { listIndexMigrations } from './list-index.js';
 import { searchIndexMigrations } from './search-index.js';
 /**
  * Every migration a module's scope applies, in the order the host applies them: the module's
- * own `migrations`, then the search indexes its `searchables` declare (#827), then the list
- * indexes its `lists` declare (#811). The two derived sets come after the authored ones because
- * their DDL names the tables those create.
+ * own `migrations`, then the search indexes its `searchables` declare (#827), then the archive and
+ * trash columns its `entityStates` declare (#119), then the list indexes its `lists` declare
+ * (#811). The derived sets come after the authored ones because their DDL names the tables those
+ * create, and the columns come before the list indexes because a partial index names them.
  *
  * The one place that order is written. Both hosts store what this returns as a module's
  * migrations, and `substrat push` calls it (from the vertical's own kernel) to carry the SQL a
@@ -15,7 +17,12 @@ import { searchIndexMigrations } from './search-index.js';
  * Structural, so a `ModuleRegistration` fits and so does a module read back as data.
  */
 export function moduleMigrations(registration) {
-    const { id, searchables, lists } = registration.manifest;
-    return [...(registration.migrations ?? []), ...searchIndexMigrations(id, searchables), ...listIndexMigrations(id, lists)];
+    const { id, searchables, lists, entityStates } = registration.manifest;
+    return [
+        ...(registration.migrations ?? []),
+        ...searchIndexMigrations(id, searchables),
+        ...entityStateMigrations(id, entityStates),
+        ...listIndexMigrations(id, lists, entityStates),
+    ];
 }
 //# sourceMappingURL=module-migrations.js.map

package/dist/module-migrations.js.map

@@ -1 +1 @@
-{"version":3,"file":"module-migrations.js","sourceRoot":"","sources":["../src/module-migrations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAwB,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAA8B,MAAM,mBAAmB,CAAC;AAGtF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAAC,YAOhC;IACC,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,YAAY,CAAC,QAAQ,CAAC;IACzD,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,GAAG,qBAAqB,CAAC,EAAE,EAAE,WAAW,CAAC,EAAE,GAAG,mBAAmB,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;AAC5H,CAAC"}
+{"version":3,"file":"module-migrations.js","sourceRoot":"","sources":["../src/module-migrations.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAwB,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAA8B,MAAM,mBAAmB,CAAC;AAGtF;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAAC,YAQhC;IACC,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,YAAY,CAAC,QAAQ,CAAC;IACvE,OAAO;QACL,GAAG,CAAC,YAAY,CAAC,UAAU,IAAI,EAAE,CAAC;QAClC,GAAG,qBAAqB,CAAC,EAAE,EAAE,WAAW,CAAC;QACzC,GAAG,qBAAqB,CAAC,EAAE,EAAE,YAAY,CAAC;QAC1C,GAAG,mBAAmB,CAAC,EAAE,EAAE,KAAK,EAAE,YAAY,CAAC;KAChD,CAAC;AACJ,CAAC"}

package/dist/operation-series.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Business volumes on a clock (#1750): calls per `(entityType, operation)` per time bucket,
+ * counted over a scope's outbox. Which pairs are worth counting is the caller's, derived
+ * from the model by the dashboard's `lifecycleMovesOf` (see `@substrat-run/contracts`'s
+ * `operation-series.ts` for why those counts are exact).
+ *
+ * ## Bounded, and index-backed with no new index
+ *
+ * The window is capped at seven days and the answer at `OPERATION_SERIES_MAX_BUCKETS` per
+ * pair, and it is ONE aggregate statement: no row leaves SQLite, so there is no per-row
+ * work on this side of it. The rows it scans are a CLOSED range of the primary key, so the
+ * work is the window's rows whatever lies after it — a window years ago visits only its own.
+ * An event id is minted from the instant the operation ran (#956) by a mint whose floor only
+ * rises, so an id never carries a time BEFORE its own `occurred_at`: every event at or after
+ * `since` has an id at or above `ulidFloor(since)`. The key range ends at
+ * `ulidFloor(until + OPERATION_SERIES_ID_SLACK_MS)`, a fixed sliver past the window.
+ * `occurred_at` stays the exact filter on both ends; the key range only bounds the scan.
+ *
+ * The slack is for ids that run AHEAD of their instants. `createUlid` (ulid.ts) holds a
+ * clock that is at or behind its floor at `lastTime` — and bumps a millisecond on the
+ * (astronomically rare) random overflow — and `seedFrom` raises that floor to the outbox's
+ * `MAX(id)` when a writer wakes. So an event in the window's last moments can carry an id
+ * past `until`, by as much as the clock stepped back. The mint itself sets no bound on
+ * that; the wall clock does: the Durable Object host reads the platform's NTP-disciplined
+ * clock, whose corrections are sub-second. `OPERATION_SERIES_ID_SLACK_MS` covers that with
+ * two orders of margin, at the cost of scanning one more minute of rows. `occurred_at`
+ * stays the exact filter, so the slack admits rows to the scan, never to the count.
+ *
+ * Past the slack, stated: a step back larger than a minute (a pure host's injected clock
+ * rewound by hand, a floor seeded from an id planted in the future) leaves an id beyond
+ * the range, and that event is not counted by a window ending before its id.
+ *
+ * The bucket arithmetic casts its parameters: a driver may bind a JS number as REAL, and
+ * then the division would place an event at its own instant instead of its bucket's start.
+ *
+ * The pairs go in as ONE bound JSON array, matched with `json_each`, rather than a
+ * placeholder each: 64 pairs as two `IN` lists is 128 parameters, past the Durable
+ * Object's 100.
+ *
+ * Same permission posture as every read in `timeline.ts`: the caller checks, this does not.
+ */
+import type { OperationSeriesInput, OperationSeriesResult } from '@substrat-run/contracts';
+import type { TimelineReader } from './timeline.js';
+/**
+ * How far past `until` the key range reaches, for an id held at the mint's floor while its
+ * instant was inside the window (see the header for where the size comes from).
+ */
+export declare const OPERATION_SERIES_ID_SLACK_MS = 60000;
+/**
+ * The read's one statement and its parameters — exported so each adapter's suite can ask
+ * its own SQLite for the plan of exactly what runs, not a copy of it.
+ */
+export declare function operationSeriesQuery(input: OperationSeriesInput): {
+    sql: string;
+    params: Array<string | number>;
+};
+export declare function readOperationSeries(ctx: TimelineReader, input: OperationSeriesInput): OperationSeriesResult;
+//# sourceMappingURL=operation-series.d.ts.map

package/dist/operation-series.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-series.d.ts","sourceRoot":"","sources":["../src/operation-series.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAC3F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGpD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAKnD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,oBAAoB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAA;CAAE,CA2BjH;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,oBAAoB,GAAG,qBAAqB,CAqB3G"}

package/dist/operation-series.js

@@ -0,0 +1,63 @@
+import { ulidFloor } from './ulid.js';
+/**
+ * How far past `until` the key range reaches, for an id held at the mint's floor while its
+ * instant was inside the window (see the header for where the size comes from).
+ */
+export const OPERATION_SERIES_ID_SLACK_MS = 60_000;
+/** Joins a pair into one key — a control character no entity or operation name carries. */
+const SEP = '\u001f';
+/**
+ * The read's one statement and its parameters — exported so each adapter's suite can ask
+ * its own SQLite for the plan of exactly what runs, not a copy of it.
+ */
+export function operationSeriesQuery(input) {
+    const sinceMs = Date.parse(input.since);
+    const untilMs = Date.parse(input.until);
+    const keys = [...new Set(input.moves.map((m) => `${m.entityType}${SEP}${m.operation}`))];
+    // A distinct (entity, call) is one move: a call that emitted three events about one
+    // record moved it once. A row from before invocation ids falls back to its own id.
+    return {
+        sql: `SELECT entity_type, operation,
+            (CAST(strftime('%s', occurred_at) AS INTEGER) - CAST(? AS INTEGER)) / CAST(? AS INTEGER) AS b,
+            COUNT(DISTINCT entity_id || char(31) || COALESCE(invocation_id, id)) AS n
+       FROM _substrat_outbox
+      WHERE id >= ? AND id < ? AND occurred_at >= ? AND occurred_at < ?
+        AND entity_type || char(31) || operation IN (SELECT value FROM json_each(?))
+      GROUP BY entity_type, operation, b
+      ORDER BY b`,
+        params: [
+            sinceMs / 1000,
+            input.bucketMinutes * 60,
+            ulidFloor(sinceMs),
+            // `until` is at most the end of 9999 (the input schema's bound), so a minute past it is
+            // far inside what a ULID encodes: `ulidFloor` cannot throw here.
+            ulidFloor(untilMs + OPERATION_SERIES_ID_SLACK_MS),
+            new Date(sinceMs).toISOString(),
+            new Date(untilMs).toISOString(),
+            JSON.stringify(keys),
+        ],
+    };
+}
+export function readOperationSeries(ctx, input) {
+    const sinceMs = Date.parse(input.since);
+    const step = input.bucketMinutes * 60;
+    const q = operationSeriesQuery(input);
+    const rows = ctx.sql.query(q.sql, q.params);
+    const counted = new Map();
+    for (const r of rows) {
+        const key = `${r.entity_type}${SEP}${r.operation}`;
+        const list = counted.get(key) ?? [];
+        list.push({ start: new Date(sinceMs + r.b * step * 1000).toISOString(), count: r.n });
+        counted.set(key, list);
+    }
+    return {
+        since: input.since,
+        until: input.until,
+        bucketMinutes: input.bucketMinutes,
+        series: input.moves.map((m) => {
+            const buckets = counted.get(`${m.entityType}${SEP}${m.operation}`) ?? [];
+            return { entityType: m.entityType, operation: m.operation, total: buckets.reduce((n, b) => n + b.count, 0), buckets };
+        }),
+    };
+}
+//# sourceMappingURL=operation-series.js.map