@smthrs/control 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/ControlRuntime.js

@@ -0,0 +1,807 @@
+/**
+ * Browser-safe port between the control plane and the execution engine, with a
+ * deterministic in-memory implementation.
+ *
+ * `layerMemory` is the deterministic one: it models the production fence and
+ * approval ordering seams but keeps everything in a `Map`, so nothing it
+ * decides survives the process. The durable adapter is
+ * {@link SqlControlRuntime}, and both are held to one shared contract suite —
+ * see `test/ControlContract.ts`.
+ *
+ * @since 0.1.0
+ */
+import * as Fault from "@smthrs/flow/Fault";
+import { Context, Crypto, Effect, Fiber, Layer, Option, Schema } from "effect";
+import * as ApprovalAuthority from "./ApprovalAuthority.js";
+import { AlreadyResolved, ClaimLost, EnvelopeMismatch, FlowNotFound, InvalidInput, PersistenceError, PlanDenied, PlanDigestMismatch, PlanNotFound, RunNotFound } from "./ControlError.js";
+import { GrantScope as GrantScopeSchema, Principal as PrincipalSchema } from "./ControlSchema.js";
+import { canonicalIssue } from "./internal/issues.js";
+import { accepted, adoptedCode, alreadyApplied as replayReceipt, budgeted, canonical, codeDriftOf, emptyEnvelope, planCard, planFingerprint, sameEnvelope } from "./internal/planning.js";
+import { plannable } from "./SystemFlows.js";
+/**
+ * Whether `run` was launched by the principal `launcher` names: the same `id`,
+ * and the same `kind` when `launcher` gives one. A run with no recorded
+ * launcher never matches.
+ *
+ * @category predicates
+ * @since 1.0.0
+ */
+export const launchedByMatches = (run, launcher) => run.launchedBy !== undefined && run.launchedBy.id === launcher.id &&
+    (launcher.kind === undefined || run.launchedBy.kind === launcher.kind);
+/**
+ * The durable answer to an approval request. A decision is not inferred from
+ * the presence of a grant or from a boolean that also means denial.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const ApprovalDecision = Schema.Union([
+    Schema.Struct({ _tag: Schema.Literal("Pending") }),
+    Schema.Struct({
+        _tag: Schema.Literal("Approved"),
+        decisionPrincipal: PrincipalSchema,
+        decidedAt: Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0)),
+        scope: GrantScopeSchema
+    }),
+    Schema.Struct({
+        _tag: Schema.Literal("Denied"),
+        decisionPrincipal: PrincipalSchema,
+        decidedAt: Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0))
+    })
+]);
+/**
+ * A gate that still needs a decision.
+ * @category errors
+ * @since 1.0.0
+ */
+export class ApprovalPending extends Schema.TaggedError()("/control/ApprovalPending", {
+    tokenId: Schema.String
+}) {
+    get message() {
+        return "Approval is still pending. Wait for a decision before proceeding.";
+    }
+}
+/**
+ * A gate that was denied, not merely resolved.
+ * @category errors
+ * @since 1.0.0
+ */
+export class ApprovalDenied extends Schema.TaggedError()("/control/ApprovalDenied", {
+    tokenId: Schema.String,
+    decisionPrincipal: PrincipalSchema
+}) {
+    get message() {
+        return "Approval was denied. This request cannot authorize the gated work.";
+    }
+}
+/**
+ * Opens only an explicitly approved gate. Callers may park on ApprovalPending;
+ * ApprovalDenied is terminal. This reads a runtime-issued token, not an
+ * authentication credential, and does not itself install permissions.
+ * @category combinators
+ * @since 1.0.0
+ */
+export const requireApproved = (token) => token._tag === "Approved"
+    ? Effect.succeed(token)
+    : token._tag === "Pending"
+        ? Effect.fail(new ApprovalPending({ tokenId: token.tokenId }))
+        : Effect.fail(new ApprovalDenied({ tokenId: token.tokenId, decisionPrincipal: token.decisionPrincipal }));
+/**
+ * Service key for the execution-engine port.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class ControlRuntime extends Context.Service()("/control/ControlRuntime") {
+}
+/**
+ * Constructs a runtime service from an implementation record.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (implementation) => ControlRuntime.of(implementation);
+/**
+ * Refuses an id page size outside 1 through 500, the `queryRuns` bound.
+ *
+ * @category validation
+ * @since 1.0.0
+ */
+export const idPageLimit = (limit) => Number.isSafeInteger(limit) && limit >= 1 && limit <= 500
+    ? Effect.void
+    : Effect.fail(new InvalidInput({ issue: "limit: must be an integer between 1 and 500" }));
+/**
+ * One inventory page over dense insertion positions, where `idAt` resolves a
+ * position by direct lookup. Visits at most `limit` positions, so a page
+ * costs and holds one page however many entries exist.
+ */
+const pageByPosition = (request, newest, idAt) => {
+    const through = request.through ?? newest;
+    const ids = [];
+    let position = request.after ?? 0;
+    let visited = 0;
+    while (position < through && visited < request.limit) {
+        position += 1;
+        visited += 1;
+        const id = idAt(position);
+        if (id !== undefined)
+            ids.push(id);
+    }
+    return position < through ? { ids, next: position, through } : { ids, through };
+};
+// SQL persistence breaks caller reference identity through serialization. The
+// memory adapter must copy at the same boundaries or its test results diverge
+// from the durable implementation when a caller mutates an input or result.
+const snapshot = (value) => structuredClone(value);
+const asStored = (plan) => ({
+    card: snapshot(plan.card),
+    decodedInput: snapshot(plan.decodedInput),
+    decision: plan.decision
+});
+// JSON tuple encoding keeps caller-chosen ids in separate fields, so a node's
+// request id cannot alias another run's request or a plan id.
+const approvalKey = (target) => target._tag === "Plan"
+    ? JSON.stringify([target._tag, target.planId])
+    : JSON.stringify([target._tag, target.runId, target.requestId]);
+const sameApprovalIdentity = (left, right) => left._tag === "Plan"
+    ? right._tag === "Plan" && left.planId === right.planId
+    : right._tag === "Node" && left.runId === right.runId && left.requestId === right.requestId;
+const approvalToken = (token) => ({
+    tokenId: token.tokenId,
+    target: snapshot(token.target),
+    ...snapshot(token.decision)
+});
+/**
+ * Deterministic in-memory runtime. It models the production fence and approval
+ * ordering seams but intentionally does not claim durable process survival;
+ * see `control-runtime-engine-integration`.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerMemory = (options = {}) => Layer.effect(ControlRuntime, Effect.gen(function* () {
+    const crypto = yield* Crypto.Crypto;
+    const now = options.now ?? Date.now;
+    // The in-memory adapter stamps `memory`/`test` on a caller that names no
+    // principal, so its default policy delegates that identity as well as
+    // the local operator. Production policies never carry it.
+    const approvalAuthority = options.approvalAuthority ?? (yield* ApprovalAuthority.make([
+        {
+            principal: { id: "local", kind: "operator" },
+            scopes: ["once", "run", "remembered"],
+            targets: ["Plan", "Node"]
+        },
+        { principal: { id: "memory", kind: "test" }, scopes: ["once", "run", "remembered"], targets: ["Plan", "Node"] }
+    ]).pipe(Effect.orDie));
+    const authorizeApproval = approvalAuthority.authorize.bind(approvalAuthority);
+    const configuredFlows = options.flows ?? plannable.map((entry) => ({
+        flowId: entry.flowId,
+        description: `Reserved ${entry.verb} system flow`,
+        deployClass: entry.deployClass,
+        envelope: emptyEnvelope
+    }));
+    const flows = new Map(configuredFlows.map((flow) => [
+        flow.flowId,
+        { ...flow, envelope: snapshot(flow.envelope) }
+    ]));
+    const plans = new Map();
+    const planKeys = new Map();
+    const tokens = new Map();
+    const runs = new Map();
+    const mutations = new Map();
+    const runKeys = new Map();
+    const installedGrants = [];
+    const installedGrantKeys = new Set();
+    let planSequence = 0;
+    const signalCommands = new Map();
+    let pendingSignalOffset = 0;
+    let runSequence = 0;
+    let fenceSequence = 0;
+    let resumeSequence = 0;
+    const requireRun = (runId) => Effect.fromOption(Option.fromNullishOr(runs.get(runId)), () => new RunNotFound({ runId }));
+    const updateSummary = (run, fields) => {
+        run.summary = snapshot({ ...run.summary, ...fields, updatedAt: now() });
+        return snapshot(run.summary);
+    };
+    const checkFence = (runId, run, fence) => run.fence === undefined || run.fence !== fence
+        ? Effect.fail(new ClaimLost({ runId }))
+        : Effect.void;
+    /** `resume`, recording the identity `adopt` answers on the claimed run when given. */
+    const resumeRun = (runId, adopt) => Effect.gen(function* () {
+        const run = yield* requireRun(runId);
+        if (run.summary.status === "cancelled" ||
+            run.summary.status === "completed" ||
+            run.summary.status === "failed")
+            return snapshot(run.summary);
+        // Accepted claims are owned too; releasePending clears both fences.
+        if (run.fence !== undefined) {
+            /* v8 ignore next 3 -- one process holds this whole runtime, and it writes `fence` and `localFence` together; the peer this refuses exists only over a shared database, which is `SqlControlRuntime`'s fence */
+            if (run.localFence === undefined || run.fence !== run.localFence) {
+                return yield* new ClaimLost({ runId });
+            }
+            return snapshot(run.summary);
+        }
+        const adopted = adopt === undefined ? undefined : yield* adopt(run);
+        const fence = `fence-${++fenceSequence}`;
+        run.fence = fence;
+        run.localFence = fence;
+        // Claiming ends the park, so it ends the record of who wrote it.
+        return updateSummary(run, {
+            ...adopted,
+            status: "accepted",
+            ownerId: "memory-owner",
+            parkedBy: undefined
+        });
+    });
+    const service = make({
+        authorizeApproval,
+        plan: Effect.fn("ControlRuntime.plan")(function* (input) {
+            const flow = flows.get(input.flowId);
+            if (flow === undefined)
+                return yield* new FlowNotFound({ flowId: input.flowId });
+            const requestFingerprint = yield* Effect.try({
+                // Validate before cloning. Canonicalization reports a throwing
+                // getter at its stable path, while `structuredClone` would invoke
+                // the getter first and erase that safe diagnostic.
+                try: () => planFingerprint(input),
+                catch: (cause) => new InvalidInput({ issue: canonicalIssue(cause) })
+            });
+            const submitted = yield* Effect.try({
+                try: () => snapshot(input),
+                catch: (cause) => new InvalidInput({ issue: canonicalIssue(cause) })
+            });
+            if (submitted.idempotencyKey !== undefined) {
+                const prior = planKeys.get(submitted.idempotencyKey);
+                if (prior !== undefined) {
+                    if (prior.fingerprint !== requestFingerprint) {
+                        return yield* new InvalidInput({
+                            issue: `idempotency key ${submitted.idempotencyKey} was used for another plan`
+                        });
+                    }
+                    const stored = plans.get(prior.planId);
+                    /* v8 ignore next -- this map never loses a plan a key names; `SqlControlRuntime` covers the storage that can */
+                    if (stored !== undefined)
+                        return { card: snapshot(stored.card), created: false };
+                }
+            }
+            const decoded = yield* (flow.decode?.(submitted.input) ?? Effect.try({
+                try: () => {
+                    canonical(submitted.input);
+                    return submitted.input;
+                },
+                catch: (cause) => new InvalidInput({ issue: canonicalIssue(cause) })
+            }));
+            const planId = `plan-${++planSequence}`;
+            const handoff = flow.plan === undefined ? undefined : yield* flow.plan(decoded, planId);
+            const card = snapshot(yield* planCard({
+                planId,
+                flowId: submitted.flowId,
+                decodedInput: decoded,
+                envelope: budgeted(flow.envelope, submitted.budget),
+                deployClass: flow.deployClass,
+                executionDigest: flow.executionDigest,
+                handoff,
+                idempotencyKey: submitted.idempotencyKey
+            }).pipe(Effect.provideService(Crypto.Crypto, crypto)));
+            // Decoding, planning and hashing may yield to another keyed plan.
+            // Recheck immediately before publication, with no yield between a
+            // successful check and the three map writes below.
+            if (submitted.idempotencyKey !== undefined) {
+                const prior = planKeys.get(submitted.idempotencyKey);
+                if (prior !== undefined) {
+                    if (prior.fingerprint !== requestFingerprint) {
+                        return yield* new InvalidInput({
+                            issue: `idempotency key ${submitted.idempotencyKey} was used for another plan`
+                        });
+                    }
+                    const stored = plans.get(prior.planId);
+                    /* v8 ignore next -- this map never loses a plan a key names; `SqlControlRuntime` covers the storage that can */
+                    if (stored !== undefined)
+                        return { card: snapshot(stored.card), created: false };
+                }
+            }
+            plans.set(planId, { card, decodedInput: snapshot(decoded), decision: "pending" });
+            tokens.set(approvalKey(card.approval.target), {
+                tokenId: planId,
+                target: snapshot(card.approval.target),
+                decision: { _tag: "Pending" }
+            });
+            if (submitted.idempotencyKey !== undefined) {
+                planKeys.set(submitted.idempotencyKey, {
+                    fingerprint: requestFingerprint,
+                    planId
+                });
+            }
+            return { card: snapshot(card), created: true };
+        }),
+        getPlan: Effect.fn("ControlRuntime.getPlan")((planId) => Effect.fromOption(Option.fromNullishOr(plans.get(planId)), () => new PlanNotFound({ planId })).pipe(Effect.map(asStored))),
+        pagePlanIds: Effect.fn("ControlRuntime.pagePlanIds")(function* (request) {
+            yield* idPageLimit(request.limit);
+            return pageByPosition(request, planSequence, (position) => plans.has(`plan-${position}`) ? `plan-${position}` : undefined);
+        }),
+        queryPlans: Effect.fn("ControlRuntime.queryPlans")(function* (request) {
+            yield* idPageLimit(request.limit);
+            const matched = [];
+            let position = request.after ?? 0;
+            while (position < planSequence && matched.length < request.limit) {
+                position += 1;
+                const plan = plans.get(`plan-${position}`);
+                if (plan !== undefined &&
+                    (request.flowId === undefined || plan.card.flowId === request.flowId) &&
+                    (request.decision === undefined || plan.decision === request.decision))
+                    matched.push(asStored(plan));
+            }
+            return position < planSequence ? { plans: matched, next: position } : { plans: matched };
+        }),
+        lookupApproval: Effect.fn("ControlRuntime.lookupApproval")(function* (target) {
+            const requested = snapshot(target);
+            const tokenId = requested._tag === "Plan" ? requested.planId : requested.requestId;
+            const token = yield* Effect.fromOption(Option.fromNullishOr(tokens.get(approvalKey(requested))), () => requested._tag === "Node"
+                ? new RunNotFound({ runId: requested.runId })
+                : new PlanNotFound({ planId: requested.planId }));
+            // A stored target that disagrees with its composite key is corrupted;
+            // accepting only its digest and envelope would recreate the alias the
+            // composite identity closes. In memory the key is DERIVED from the
+            // identity, so only a caller reaching into the map can produce the
+            // disagreement; `SqlControlRuntime` stores the two apart and covers
+            // the same refusal against a rewritten row.
+            /* v8 ignore next 6 -- unreachable while the map key is derived from the identity it is compared against */
+            if (!sameApprovalIdentity(token.target, requested)) {
+                return yield* new PersistenceError({
+                    operation: "validate an approval token",
+                    message: "The stored approval target does not match its identity"
+                });
+            }
+            if (token.target.digest !== requested.digest) {
+                return yield* new PlanDigestMismatch({
+                    planId: tokenId,
+                    expected: token.target.digest,
+                    actual: requested.digest
+                });
+            }
+            if (!sameEnvelope(token.target.envelope, requested.envelope)) {
+                return yield* new EnvelopeMismatch({
+                    planId: tokenId,
+                    expected: canonical(token.target.envelope),
+                    actual: canonical(requested.envelope)
+                });
+            }
+            if (token.decision._tag !== "Pending")
+                return yield* new AlreadyResolved({ requestId: tokenId });
+            return approvalToken(token);
+        }),
+        registerApproval: Effect.fn("ControlRuntime.registerApproval")(function* (target) {
+            const requested = snapshot(target);
+            yield* requireRun(requested.runId);
+            const key = approvalKey(requested);
+            const existing = tokens.get(key);
+            if (existing === undefined) {
+                const stored = {
+                    tokenId: requested.requestId,
+                    target: requested,
+                    decision: { _tag: "Pending" }
+                };
+                tokens.set(key, stored);
+                return approvalToken(stored);
+            }
+            /* v8 ignore next 6 -- as in `lookupApproval`: the map key is derived from the identity, so a stored target can only disagree with it after a reach into the map */
+            if (!sameApprovalIdentity(existing.target, requested)) {
+                return yield* new PersistenceError({
+                    operation: "validate an approval token",
+                    message: "The stored approval target does not match its identity"
+                });
+            }
+            if (existing.target.digest !== requested.digest) {
+                return yield* new PlanDigestMismatch({
+                    planId: requested.requestId,
+                    expected: existing.target.digest,
+                    actual: requested.digest
+                });
+            }
+            if (!sameEnvelope(existing.target.envelope, requested.envelope)) {
+                return yield* new EnvelopeMismatch({
+                    planId: requested.requestId,
+                    expected: canonical(existing.target.envelope),
+                    actual: canonical(requested.envelope)
+                });
+            }
+            return approvalToken(existing);
+        }),
+        installBulkGrant: Effect.fn("ControlRuntime.installBulkGrant")((token, envelope, scope) => Effect.sync(() => {
+            const storedToken = snapshot(token);
+            const key = approvalKey(storedToken.target);
+            if (installedGrantKeys.has(key))
+                return;
+            installedGrantKeys.add(key);
+            installedGrants.push({
+                tokenId: storedToken.tokenId,
+                envelope: snapshot(envelope),
+                scope,
+                installedAt: now()
+            });
+        })),
+        resolveApproval: Effect.fn("ControlRuntime.resolveApproval")(function* (token, decision, principal, scope = "once") {
+            const requested = snapshot(token);
+            const requestedPrincipal = snapshot(principal);
+            const answer = yield* Schema.decodeUnknownEffect(ApprovalDecision)(decision === "approved"
+                ? { _tag: "Approved", decisionPrincipal: requestedPrincipal, decidedAt: now(), scope }
+                : { _tag: "Denied", decisionPrincipal: requestedPrincipal, decidedAt: now() }).pipe(Effect.mapError(() => new PersistenceError({
+                operation: "record an approval decision",
+                message: "The approval decision metadata is invalid"
+            })));
+            yield* authorizeApproval({ principal: requestedPrincipal, target: requested.target, decision, scope });
+            const mutable = tokens.get(approvalKey(requested.target));
+            if (mutable === undefined || mutable.decision._tag !== "Pending") {
+                return yield* new AlreadyResolved({ requestId: requested.tokenId });
+            }
+            mutable.decision = answer;
+            if (requested.target._tag === "Plan") {
+                const plan = plans.get(requested.target.planId);
+                /* v8 ignore next -- a plan token is only ever registered by `plan`, which stores the plan in the same call */
+                if (plan !== undefined)
+                    plan.decision = decision;
+            }
+        }),
+        launch: Effect.fn("ControlRuntime.launch")(function* (planId, requestedDigest, envelope, principal, reservedRunId) {
+            const plan = yield* Effect.fromOption(Option.fromNullishOr(plans.get(planId)), () => new PlanNotFound({ planId }));
+            if (plan.card.digest !== requestedDigest) {
+                return yield* new PlanDigestMismatch({
+                    planId,
+                    expected: plan.card.digest,
+                    actual: requestedDigest
+                });
+            }
+            if (!sameEnvelope(plan.card.envelope, envelope)) {
+                return yield* new EnvelopeMismatch({
+                    planId,
+                    expected: canonical(plan.card.envelope),
+                    actual: canonical(envelope)
+                });
+            }
+            if (plan.decision === "pending") {
+                return {
+                    _tag: "Parked",
+                    receipt: {
+                        _tag: "Parked",
+                        receiptId: `launch:${planId}`,
+                        planId,
+                        status: "waiting-approval"
+                    }
+                };
+            }
+            if (plan.decision !== "approved") {
+                return yield* new PlanDenied({ planId });
+            }
+            const sequence = ++runSequence;
+            const runId = reservedRunId ?? `run-${sequence}`;
+            if (runs.has(runId))
+                return yield* new PersistenceError({ operation: "reserve a run", message: "Run identity already exists" });
+            const fence = `fence-${++fenceSequence}`;
+            const timestamp = now();
+            const summary = {
+                runId,
+                flowId: plan.card.flowId,
+                status: "accepted",
+                planId,
+                planDigest: plan.card.digest,
+                ...(plan.card.executionDigest === undefined ? {} : { executionDigest: plan.card.executionDigest }),
+                ...(options.engineVersion === undefined ? {} : { engineVersion: options.engineVersion }),
+                ownerId: "memory-owner",
+                ...(principal === undefined ? {} : { launchedBy: { id: principal.id, kind: principal.kind } }),
+                ...(plan.card.envelope.budget.deadline === undefined
+                    ? {}
+                    : { deadlineAt: timestamp + plan.card.envelope.budget.deadline }),
+                createdAt: timestamp,
+                updatedAt: timestamp
+            };
+            runs.set(runId, {
+                summary: snapshot(summary),
+                fence,
+                localFence: fence,
+                sequence: runSequence,
+                signals: []
+            });
+            return {
+                _tag: "Started",
+                receipt: accepted(`launch:${planId}:${runId}`, runId),
+                run: snapshot(summary)
+            };
+        }),
+        getRun: Effect.fn("ControlRuntime.getRun")((runId) => Effect.map(requireRun(runId), (run) => snapshot(run.summary))),
+        pageRunIds: Effect.fn("ControlRuntime.pageRunIds")(function* (request) {
+            yield* idPageLimit(request.limit);
+            return pageByPosition(request, runSequence, (position) => runs.has(`run-${position}`) ? `run-${position}` : undefined);
+        }),
+        queryRuns: Effect.fn("ControlRuntime.queryRuns")(function* (request) {
+            if (!Number.isSafeInteger(request.limit) || request.limit < 1 || request.limit > 500) {
+                return yield* new InvalidInput({ issue: "limit: must be an integer between 1 and 500" });
+            }
+            const selected = [];
+            const filters = request.filters;
+            const newest = request.order === "newest";
+            const oldest = request.order === "oldest";
+            const candidates = newest
+                ? Array.from(runs.values()).sort((a, b) => b.summary.createdAt - a.summary.createdAt || b.sequence - a.sequence)
+                : oldest
+                    ? Array.from(runs.values()).sort((a, b) => a.summary.createdAt - b.summary.createdAt || a.sequence - b.sequence)
+                    : runs.values();
+            for (const run of candidates) {
+                const after = request.cursor;
+                if (after !== undefined && (after.source !== 0 || (newest
+                    ? run.summary.createdAt > after.createdAt ||
+                        (run.summary.createdAt === after.createdAt && run.sequence >= after.sequence)
+                    : oldest
+                        ? run.summary.createdAt < after.createdAt ||
+                            (run.summary.createdAt === after.createdAt && run.sequence <= after.sequence)
+                        : run.sequence <= after.sequence)))
+                    continue;
+                const summary = run.summary;
+                if (filters?.since !== undefined && summary.createdAt < filters.since)
+                    continue;
+                if (filters?.until !== undefined && summary.createdAt >= filters.until)
+                    continue;
+                if (filters?.runIds !== undefined && !filters.runIds.includes(summary.runId))
+                    continue;
+                if (filters?.flowId !== undefined && summary.flowId !== filters.flowId)
+                    continue;
+                if (filters?.status !== undefined && summary.status !== filters.status)
+                    continue;
+                if (filters?.terminal !== undefined &&
+                    ["completed", "failed", "cancelled"].includes(summary.status) !== filters.terminal)
+                    continue;
+                if (filters?.parentRunId !== undefined && summary.parentRunId !== filters.parentRunId)
+                    continue;
+                if (filters?.lineageId !== undefined && summary.lineageId !== filters.lineageId)
+                    continue;
+                if (filters?.launchedBy !== undefined && !launchedByMatches(summary, filters.launchedBy))
+                    continue;
+                selected.push(run);
+                if (selected.length > request.limit)
+                    break;
+            }
+            const page = selected.slice(0, request.limit);
+            const last = page.at(-1);
+            return {
+                items: page.map((run) => snapshot(run.summary)),
+                ...(selected.length <= request.limit || last === undefined ? {} : {
+                    nextCursor: {
+                        source: 0,
+                        sequence: last.sequence,
+                        createdAt: last.summary.createdAt,
+                        runId: last.summary.runId
+                    }
+                })
+            };
+        }),
+        listFlows: Effect.fn("ControlRuntime.listFlows")(() => Effect.sync(() => Array.from(flows.values(), (flow) => ({
+            flowId: flow.flowId,
+            description: flow.description
+        }))))(),
+        deliverSignal: Effect.fn("ControlRuntime.deliverSignal")((runId, signal) => Effect.tap(requireRun(runId), (run) => Effect.sync(() => void run.signals.push(snapshot(signal))))),
+        admitSignal: Effect.fn("ControlRuntime.admitSignal")(function* (commandId, runId, signal, principal) {
+            yield* requireRun(runId);
+            if (!signalCommands.has(commandId)) {
+                signalCommands.set(commandId, snapshot({
+                    commandId,
+                    runId,
+                    signal,
+                    token: null,
+                    state: "pending",
+                    ...(principal === undefined ? {} : { principal })
+                }));
+            }
+        }),
+        signalCommand: (commandId) => Effect.sync(() => snapshot(signalCommands.get(commandId))),
+        pendingSignals: Effect.sync(() => {
+            const pending = Array.from(signalCommands.values()).filter((command) => command.state === "pending");
+            if (pendingSignalOffset >= pending.length)
+                pendingSignalOffset = 0;
+            const page = pending.slice(pendingSignalOffset, pendingSignalOffset + 100);
+            pendingSignalOffset += page.length;
+            return snapshot(page);
+        }),
+        bindSignal: (commandId, token) => Effect.gen(function* () {
+            const command = signalCommands.get(commandId);
+            if (command === undefined) {
+                return yield* new PersistenceError({
+                    operation: "bind signal",
+                    message: `No pending signal command ${commandId}`
+                });
+            }
+            if (command.state !== "pending")
+                return command.token;
+            if (command.token === null &&
+                Array.from(signalCommands.values()).some((other) => other.commandId !== commandId && other.token === token))
+                return null;
+            const bound = command.token ?? token;
+            signalCommands.set(commandId, { ...command, token: bound });
+            return bound;
+        }),
+        settleSignal: (commandId, state) => Effect.sync(() => {
+            const command = signalCommands.get(commandId);
+            if (command !== undefined && command.state === "pending") {
+                signalCommands.set(commandId, { ...command, state });
+            }
+        }),
+        deliveredSignals: Effect.fn("ControlRuntime.deliveredSignals")((runId) => Effect.map(requireRun(runId), (run) => snapshot([
+            ...run.signals,
+            ...Array.from(signalCommands.values()).filter((command) => command.runId === runId && command.state !== "rejected").map((command) => command.signal)
+        ]))),
+        requestResume: Effect.fn("ControlRuntime.requestResume")(function* (runId, options) {
+            const run = yield* requireRun(runId);
+            if (run.summary.status === "cancelled" ||
+                run.summary.status === "completed" ||
+                run.summary.status === "failed") {
+                return yield* new InvalidInput({
+                    issue: `run ${runId} is ${run.summary.status} and cannot take a resume`
+                });
+            }
+            const sequence = ++resumeSequence;
+            run.pendingResume = sequence;
+            run.pendingResumeAtMs = now();
+            run.pendingConsent = options?.consent ?? run.pendingConsent;
+            updateSummary(run, { pendingResume: sequence });
+            return sequence;
+        }),
+        pendingResumes: Effect.sync(() => Array.from(runs.entries()).flatMap(([runId, run]) => run.pendingResume === undefined || run.pendingResumeAtMs === undefined ||
+            run.summary.status === "cancelled" ||
+            run.summary.status === "completed" || run.summary.status === "failed"
+            ? []
+            : [{
+                    runId,
+                    sequence: run.pendingResume,
+                    requestedAtMs: run.pendingResumeAtMs,
+                    ...(run.pendingConsent === undefined ? {} : { consent: run.pendingConsent })
+                }])),
+        clearResume: Effect.fn("ControlRuntime.clearResume")((runId, sequence) => Effect.sync(() => {
+            const run = runs.get(runId);
+            if (run === undefined || run.pendingResume !== sequence)
+                return;
+            run.pendingResume = undefined;
+            run.pendingResumeAtMs = undefined;
+            run.pendingConsent = undefined;
+            updateSummary(run, { pendingResume: undefined });
+        })),
+        registerFiber: Effect.fn("ControlRuntime.registerFiber")((runId, fiber) => Effect.tap(requireRun(runId), (run) => Effect.sync(() => {
+            run.fiber = fiber;
+            fiber.addObserver(() => {
+                if (run.fiber === fiber)
+                    run.fiber = undefined;
+            });
+        }))),
+        interrupt: Effect.fn("ControlRuntime.interrupt")(function* (runId, settle = (effect) => effect) {
+            const run = yield* requireRun(runId);
+            // Terminal first, as `resume` does: a settled run released its fence,
+            // and answering `ClaimLost` there would name the wrong problem.
+            if (run.summary.status === "cancelled" ||
+                run.summary.status === "completed" ||
+                run.summary.status === "failed")
+                return snapshot(run.summary);
+            if (run.localFence === undefined)
+                return yield* new ClaimLost({ runId });
+            const fence = run.localFence;
+            yield* checkFence(runId, run, fence);
+            if (run.fiber !== undefined)
+                yield* Fiber.interrupt(run.fiber);
+            return yield* settle(Effect.gen(function* () {
+                // Cleanup may settle the run or release and replace its owner.
+                if (run.summary.status === "cancelled" ||
+                    run.summary.status === "completed" ||
+                    run.summary.status === "failed")
+                    return snapshot(run.summary);
+                yield* checkFence(runId, run, fence);
+                run.fence = undefined;
+                run.localFence = undefined;
+                return updateSummary(run, { status: "cancelled", ownerId: undefined, parkedBy: undefined });
+            }));
+        }),
+        codeDrift: Effect.fn("ControlRuntime.codeDrift")(function* (runId) {
+            const run = yield* requireRun(runId);
+            return codeDriftOf(run.summary, flows.get(run.summary.flowId), options.engineVersion);
+        }),
+        recordedCode: Effect.fn("ControlRuntime.recordedCode")(function* (runId) {
+            const { executionDigest, engineVersion } = (yield* requireRun(runId)).summary;
+            return { executionDigest, engineVersion };
+        }),
+        resume: Effect.fn("ControlRuntime.resume")((runId) => resumeRun(runId)),
+        // `plan` refuses a flow this catalog does not hold, and the catalog is
+        // fixed at construction, so a run's flow is never gone here and there
+        // is always code to adopt. `SqlControlRuntime` reads a catalog that can
+        // lose a flow, and refuses that case before the claim.
+        resumeAdopting: Effect.fn("ControlRuntime.resumeAdopting")((runId) => resumeRun(runId, (run) => Effect.succeed(adoptedCode(run.summary, flows.get(run.summary.flowId), options.engineVersion)))),
+        claimFence: Effect.fn("ControlRuntime.claimFence")(function* (runId) {
+            const run = yield* requireRun(runId);
+            if (run.localFence === undefined)
+                return yield* new ClaimLost({ runId });
+            return run.localFence;
+        }),
+        releasePending: Effect.fn("ControlRuntime.releasePending")(function* (runId, fence) {
+            const run = yield* requireRun(runId);
+            yield* checkFence(runId, run, fence);
+            run.fence = undefined;
+            run.localFence = undefined;
+            return updateSummary(run, {
+                status: "accepted",
+                ownerId: undefined,
+                parkedBy: undefined
+            });
+        }),
+        writeStatus: Effect.fn("ControlRuntime.writeStatus")(function* (runId, fence, status) {
+            const run = yield* requireRun(runId);
+            yield* checkFence(runId, run, fence);
+            // Ownership is released by any status that is not being driven, so the
+            // fence that wrote a terminal or parked status is spent by writing it.
+            if (status === "accepted" || status === "running") {
+                return updateSummary(run, { status, parkedBy: undefined });
+            }
+            run.fence = undefined;
+            run.localFence = undefined;
+            // The spent fence is kept on a park, and only on a park: it is the
+            // only thing left on the row that says which host parked it.
+            return updateSummary(run, {
+                status,
+                ownerId: undefined,
+                parkedBy: status === "parked" || status === "waiting-approval" ? fence : undefined
+            });
+        }),
+        // Precedence matches `SqlControlRuntime`: the submitted identity is
+        // the one a server authenticated, and the configured one is this
+        // composition's fallback for a caller that named none.
+        stampPrincipal: Effect.fn("ControlRuntime.stampPrincipal")((submitted) => Effect.sync(() => ({
+            id: submitted?.id ?? options.principal?.id ?? "memory",
+            kind: submitted?.kind ?? options.principal?.kind ?? "test",
+            stampedAt: now()
+        }))),
+        lookupMutation: Effect.fn("ControlRuntime.lookupMutation")((key, fingerprint) => Effect.sync(() => {
+            const record = mutations.get(key);
+            if (record === undefined)
+                return undefined;
+            return record.fingerprint === fingerprint
+                ? replayReceipt(key, record.receipt)
+                : { _tag: "Conflict", message: `idempotency key ${key} was used for another mutation` };
+        })),
+        recordMutation: Effect.fn("ControlRuntime.recordMutation")((key, fingerprint, receipt) => Effect.gen(function* () {
+            const prior = mutations.get(key);
+            if (prior !== undefined &&
+                (prior.fingerprint !== fingerprint || canonical(prior.receipt) !== canonical(receipt))) {
+                return yield* Effect.fail(new PersistenceError({
+                    operation: "record a mutation",
+                    message: `Idempotency key ${key} was already settled by another mutation`
+                }));
+            }
+            mutations.set(key, { fingerprint, receipt: snapshot(receipt) });
+        })),
+        claimRunKey: Effect.fn("ControlRuntime.claimRunKey")(function* (key, fingerprint) {
+            const holder = runKeys.get(key);
+            if (holder !== undefined) {
+                if (holder.fingerprint !== fingerprint) {
+                    return yield* new InvalidInput({
+                        issue: `idempotency key ${key} was used for another run`
+                    });
+                }
+                const record = mutations.get(key);
+                if (record === undefined) {
+                    // One process owns this runtime, so reaching here takes a caller
+                    // that claimed and never recorded: the cross-process winner this
+                    // branch really models commits both in one transaction, which is
+                    // `SqlControlRuntime`'s seam.
+                    return yield* new PersistenceError({
+                        operation: "read a mutation",
+                        message: `run key ${key} was claimed by a mutation that recorded no receipt`
+                    });
+                }
+                return { _tag: "Raced", receipt: snapshot(record.receipt) };
+            }
+            runKeys.set(key, { fingerprint });
+            return { _tag: "Claimed" };
+        }),
+        releaseRunKey: Effect.fn("ControlRuntime.releaseRunKey")((key) => Effect.sync(() => {
+            runKeys.delete(key);
+        })),
+        grants: Effect.fn("ControlRuntime.grants")(() => Effect.sync(() => snapshot(installedGrants)))()
+    });
+    return service;
+}));
+Fault.register("/control/ApprovalPending", "wait");
+Fault.register("/control/ApprovalDenied", "user");
+//# sourceMappingURL=ControlRuntime.js.map