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

package/dist/esm/ControlExecutor.d.ts

@@ -0,0 +1,372 @@
+/**
+ * Acceptance port from the control plane into a real run executor.
+ *
+ * Governing contract: `docs/pages/control/index.md`.
+ *
+ * @since 0.1.0
+ */
+import type { ExecutionFact } from "@smthrs/journal";
+import { Context, Effect, Layer } from "effect";
+import type { LaunchFailed, PersistenceError } from "./ControlError.ts";
+import type { StoredPlan } from "./ControlRuntime.ts";
+import type { ApprovalTarget, ExecutionBatch, PendingWait, Principal, Receipt, RunId, RunSummary, SignalPayload } from "./ControlSchema.ts";
+/**
+ * One stored plan and the run summary it is being started as.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Launch {
+    readonly plan: StoredPlan;
+    readonly run: RunSummary;
+}
+/**
+ * Whether the executor took the launch now or queued it.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Acceptance = "accepted" | "pending";
+/**
+ * One run whose cancellation has to become durable on the engine row.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface CancelRequest {
+    readonly runId: RunId;
+}
+/**
+ * The engine row a cancel request arrived too late for.
+ *
+ * It carries the ENGINE's status rather than a bare marker because the control
+ * plane cannot read that row: in the shipped CLI the two `flows_runs` tables
+ * live in two files (`.flows/control.db` and `.flows/engine.db`), so the port
+ * is the only place the plane learns what actually became of the run.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface CancelTerminal {
+    readonly _tag: "Terminal";
+    readonly status: "completed" | "failed" | "cancelled";
+}
+/**
+ * What the executor did with a cancel request.
+ *
+ * `recorded` means THIS call set `cancel_requested_at_ms` on the engine row, so
+ * the owning process stops the run at its next cancel poll whichever process
+ * asked. `already-requested` means the column was already set when this call
+ * arrived: the request is just as durable, and the cancellation it belongs to
+ * was somebody else's. `Control.cancel` keys its attribution event on that
+ * difference — the write is first-writer-wins and every repeat re-runs the
+ * whole mutation, so answering `recorded` to all of them left one journaled
+ * `control.run.cancel-requested` per ask for a single cancellation (release validation
+ * smoke: three `cancel` calls and one `down` against one parked run left four).
+ * `unknown` means this executor's engine has no row for the run at all, which
+ * is the honest answer for a run another composition launched into a database
+ * this one does not share. A {@link CancelTerminal} means the engine row has
+ * already settled, so there is nothing left to stop: recording intent on it
+ * would be a request no process can ever act on, and answering `recorded` let
+ * `Control.cancel` write a terminal control status the engine row does not have
+ * (triage B-11).
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type CancelRecord = "recorded" | "already-requested" | "unknown" | CancelTerminal;
+/**
+ * One parked run that has been told to resume.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface ResumeRequest {
+    readonly runId: RunId;
+}
+/**
+ * What the executor did with a resume request.
+ *
+ * `resuming` means this executor hosts the run's execution, has taken the
+ * control row's fence, and is re-driving it: the caller can stop, and the run
+ * moves on its own. `unknown` means this executor drives no execution for the
+ * run, which is the answer an operator's CLI, a gateway, or any second process
+ * gives, and it is why the control plane records the delegation durably
+ * instead of treating its own journal entry as the delivery (triage B-15).
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ResumeUptake = "resuming" | "unknown";
+/**
+ * One signal to deliver to a run's open wait point.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Signal {
+    /** Actor-scoped durable admission identity, present on control-plane delivery. */
+    readonly commandId?: string;
+    /** An existing immutable binding survives a crash before acknowledgment. */
+    readonly token?: string | null;
+    readonly runId: RunId;
+    readonly signal: SignalPayload;
+    /**
+     * Who admitted the signal. A human wait ({@link humanWaitReason}) completes
+     * only when `ApprovalAuthority` authorizes this principal to approve the
+     * wait's `Node` target; without one the signal is `refused`.
+     */
+    readonly principal?: Principal | undefined;
+}
+/**
+ * What the executor did with a signal.
+ *
+ * `delivered` means the `WaitFor` deferred the run is parked on was completed
+ * with the signal's payload and the run was woken. `no-match` means the run IS
+ * parked and is waiting for something else, which `Control.signal` refuses
+ * rather than recording a delivery nothing consumes. `unknown` means this
+ * executor is driving no execution for the run at all — another process may
+ * be, or none is yet — so the recorded message is the whole delivery and the
+ * executor that eventually drives the run replays it at its next start.
+ * `refused` means the signal named an open human wait and `ApprovalAuthority`
+ * did not authorize its principal to answer it: the wait stays open, and
+ * `Control.signal` fails `Unauthorized`.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type SignalDelivery = "delivered" | "no-match" | "refused" | "unknown";
+/**
+ * Current engine observation. Missing execution is distinct from a running one.
+ * @category models
+ * @since 1.0.0
+ */
+export type ExecutionObservation = {
+    readonly _tag: "Missing";
+} | {
+    readonly _tag: "Observed";
+    readonly executionView?: ExecutionFact.View | undefined;
+    readonly status: "accepted" | "running" | "parked" | "waiting-approval" | "completed" | "failed" | "cancelled";
+    readonly waitingReason?: string | undefined;
+    readonly parentRunId?: string | undefined;
+    readonly lineageId?: string | undefined;
+    readonly roundOrdinal?: number | undefined;
+    /**
+     * Open human waits anywhere in this execution's tree.
+     *
+     * The control plane cannot compute these. It keeps its own coordination
+     * copy of `flows_runs`, and the executions a flow spawns — where a nested
+     * `HumanTask` actually parks — exist only in the executor's database, with
+     * the edges that link them. `readExecution` is the one place that reads
+     * both, so it is where a run tree's open questions become visible to
+     * anything else.
+     *
+     * Absent when nothing in the tree is waiting on a person. `status` rolls
+     * up with them: an execution parked while a descendant holds a human wait
+     * is observed as `waiting-approval`.
+     */
+    readonly pendingWaits?: ReadonlyArray<PendingWait> | undefined;
+};
+/**
+ * The waiting reason a human wait parks under.
+ *
+ * `HumanTask` and the agent's own `ask` both declare it
+ * (`@smthrs/flow` `FlowRuntime.annotateWaiting({ reason: "approval" })`), so
+ * it is the one value that separates "somebody has to answer this" from every
+ * other park.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const humanWaitReason = "approval";
+/**
+ * One parked execution as a {@link PendingWait}, or nothing when it is not a
+ * wait a person or a named control signal can end.
+ *
+ * Shared by the two readers that produce these rows — the control plane's own
+ * SQL runtime, when it shares a database with the engine, and the executor's
+ * observation port, when it does not — so a wait reads the same either way.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const pendingWaitOf: (row: {
+    readonly runId: string;
+    readonly flowId?: string | undefined;
+    readonly reason: string;
+    readonly token: string | null | undefined;
+    readonly request?: unknown;
+    readonly createdAt: number;
+}) => PendingWait | undefined;
+/**
+ * The wait a `Node` approval target addresses, when it addresses one.
+ *
+ * Most gates are a capability the run wants allowed: the target's `digest` is
+ * the request's own digest, a decision grants or refuses it, and the control
+ * plane holds a registered token for it. A `HumanTask` gate has no such token
+ * — nothing registers one, because the run parked itself on a durable wait
+ * rather than asking the control plane for permission — and `lookupApproval`
+ * answers a target with no token by reporting the RUN as missing. That is what
+ * an operator saw when the app submitted an answer as an ordinary approval:
+ * `/control/RunNotFound` naming a run that was listed, rendered, and waiting
+ * (workspace 4bb93306, run-1).
+ *
+ * So a decision has to be able to tell the two apart from the payload alone.
+ * The approvals projection publishes a human wait with the durable wait token
+ * as the `digest` and the wait point's own name as the `requestId`, and a
+ * durable deferred token is self-describing: it decodes to a flow, an
+ * execution, and a deferred name under `WaitFor/`. Nothing else produces one,
+ * so a target carrying one is a question, and the name it answers is right
+ * there.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const answerableWait: (target: ApprovalTarget) => {
+    readonly name: string;
+    readonly token: string;
+} | undefined;
+/**
+ * The executor port: the control plane hands work over to a real run executor
+ * and learns only what the executor did with it.
+ *
+ * `launch` is acceptance. `requestCancel`, `deliverSignal`, and `resumeRun`
+ * are the three requests that have to reach the engine to mean anything: a
+ * cancel is durable on the engine row so that whichever process owns the run
+ * stops it, a signal completes the wait point a parked run is actually waiting
+ * on, and a resume re-drives the execution an approval decision unblocked.
+ * Without them the control plane records facts nobody reads — a cancel that
+ * answers `ClaimLost` to every process but the owner, a signal a parked run
+ * never sees, and a resume event published into an in-process hub no other
+ * process subscribes to (the release policy; triage B-10, B-13, B-15).
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export interface Service {
+    /** Read from the executor's database, never the control coordination copy. */
+    readonly readExecution?: (runId: RunId) => Effect.Effect<ExecutionObservation, PersistenceError>;
+    /** Exact observations scoped to the authorized control root; unrelated native rows are never exposed. */
+    readonly readExecutions?: (input: {
+        readonly runId: RunId;
+        readonly executionIds: ReadonlyArray<string>;
+    }) => Effect.Effect<ExecutionBatch, PersistenceError>;
+    readonly launch: (input: Launch) => Effect.Effect<Acceptance, LaunchFailed>;
+    /**
+     * Host-only close of a retained run, after its last native module completed.
+     * @since 1.0.0
+     */
+    readonly requestComplete?: ((input: {
+        readonly runId: RunId;
+        readonly receiptId: string;
+    }) => Effect.Effect<Receipt, PersistenceError>) | undefined;
+    /**
+     * Records a cancellation on the engine row, durably, regardless of which
+     * process owns the run.
+     */
+    readonly requestCancel: (input: CancelRequest) => Effect.Effect<CancelRecord, PersistenceError>;
+    /**
+     * Completes the run's open `WaitFor` wait point with the signal's payload.
+     */
+    readonly deliverSignal: (input: Signal) => Effect.Effect<SignalDelivery, PersistenceError>;
+    /**
+     * Takes up a resume: claims the control row and re-drives the execution,
+     * when this executor is the one hosting it.
+     */
+    readonly resumeRun: (input: ResumeRequest) => Effect.Effect<ResumeUptake, PersistenceError>;
+    /**
+     * Finishes a PARKED execution whose cancellation is already durable.
+     *
+     * A park has no owner — that is what makes it resumable — so nothing is
+     * driving the run and nothing reads the request {@link requestCancel} wrote.
+     * The engine's parked-run sweep does, once per heartbeat, but a `smithers
+     * cancel` process writes the request at the very end of its life and exits
+     * before that tick: the release validation watched an engine row stay
+     * `suspended` with `cancel_requested_at_ms` set through six more commands
+     * and fifteen seconds, so `gc` collected the run in `control.db` and
+     * skipped it in `engine.db`.
+     *
+     * Called AFTER the cancel mutation commits, never inside it: driving a run
+     * re-enters the engine, whose writes would wait on the writer the
+     * mutation's transaction holds. An executor that does not host the run, or
+     * one whose run is not parked, does nothing and leaves the durable request
+     * standing for the host that does.
+     */
+    readonly settleCancelledPark: (input: CancelRequest) => Effect.Effect<void, PersistenceError>;
+}
+declare const ControlExecutor_base: Context.ServiceClass<ControlExecutor, "/control/ControlExecutor", Service>;
+/**
+ * The {@link Service} tag.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class ControlExecutor extends ControlExecutor_base {
+}
+/**
+ * Builds a {@link Service} from an implementation of its methods.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: (implementation: Service) => Service;
+/**
+ * A {@link Service} that accepts every launch as `pending` and starts
+ * nothing. Overrides replace individual methods.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const makeNoop: (overrides?: Partial<Service>) => Service;
+/**
+ * Provides {@link ControlExecutor} from an implementation.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: (implementation: Service) => Layer.Layer<ControlExecutor>;
+/**
+ * The same executor with methods that drive a run refused.
+ *
+ * A host composed to observe runs rather than drive them has no completion
+ * judge, so it must not be able to start or resume one: without this a verb
+ * misclassified as a read would admit a run and lose it at its first
+ * completion, which is the outcome the boot-time judge requirement exists to
+ * prevent. Reaching either method is a composition defect, not an operator
+ * error, so it dies rather than failing.
+ *
+ * Observation, cancellation and signal delivery stay live. A cancel and a
+ * signal record a durable request that the process driving the run picks up,
+ * so none of them reaches a completion, and refusing them would stop an
+ * operator ending a run on a host with no gateway key, which is the whole
+ * reason a read host exists.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const makeObserving: (service: Service) => Service;
+/**
+ * An executor that only reads the engine: every method that drives or
+ * changes a run dies.
+ *
+ * A host composed over read-only stores carries it. Unlike
+ * {@link makeObserving}, it records no cancel and delivers no signal, because
+ * such a host can write neither. Without `readExecution` a listing answers
+ * from the control plane's coordination copy alone.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const makeReadOnly: ({ readExecution, readExecutions }?: {
+    readonly readExecution?: Service["readExecution"];
+    readonly readExecutions?: Service["readExecutions"];
+}) => Service;
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layerNoop: (overrides?: Partial<Service>) => Layer.Layer<ControlExecutor>;
+export {};
+//# sourceMappingURL=ControlExecutor.d.ts.map

package/dist/esm/ControlExecutor.d.ts.map

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

package/dist/esm/ControlExecutor.js

@@ -0,0 +1,212 @@
+/**
+ * Acceptance port from the control plane into a real run executor.
+ *
+ * Governing contract: `docs/pages/control/index.md`.
+ *
+ * @since 0.1.0
+ */
+import * as Sha256 from "@smthrs/crypto/Sha256";
+import * as DurableDeferred from "@smthrs/flow/DurableDeferred";
+import { Context, Effect, Layer, Option, Schema } from "effect";
+/**
+ * The waiting reason a human wait parks under.
+ *
+ * `HumanTask` and the agent's own `ask` both declare it
+ * (`@smthrs/flow` `FlowRuntime.annotateWaiting({ reason: "approval" })`), so
+ * it is the one value that separates "somebody has to answer this" from every
+ * other park.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export const humanWaitReason = "approval";
+/**
+ * The wait point a durable token addresses, as a person reads it.
+ *
+ * A `HumanTask` attempt is its own wait point named `WaitFor/<task>#<attempt>`
+ * (`@smthrs/flow` `HumanTask`), and a plain `WaitFor` gate is `WaitFor/<name>`.
+ * Splitting the two out of the token is what lets a client address an answer by
+ * the name a person was asked under rather than by a base64 blob, and lets an
+ * inbox say which of three attempts is open.
+ *
+ * A token this plane cannot parse names nothing extra; the token itself still
+ * travels, so the wait stays answerable.
+ */
+/** The engine's own decoder: tokens are UTF-8 JSON in base64url, which `atob` misreads. */
+const decodeToken = Schema.decodeUnknownOption(DurableDeferred.TokenParsed.FromString);
+const waitPointOf = (token) => {
+    const decoded = decodeToken(token);
+    if (Option.isNone(decoded))
+        return {};
+    const deferredName = decoded.value.deferredName;
+    if (!deferredName.startsWith("WaitFor/"))
+        return {};
+    const point = deferredName.slice("WaitFor/".length);
+    const marker = point.lastIndexOf("#");
+    if (marker < 0)
+        return { name: point };
+    const attempt = Number(point.slice(marker + 1));
+    return Number.isSafeInteger(attempt) && attempt > 0
+        ? { name: point.slice(0, marker), attempt }
+        : { name: point };
+};
+/**
+ * One parked execution as a {@link PendingWait}, or nothing when it is not a
+ * wait a person or a named control signal can end.
+ *
+ * Shared by the two readers that produce these rows — the control plane's own
+ * SQL runtime, when it shares a database with the engine, and the executor's
+ * observation port, when it does not — so a wait reads the same either way.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const pendingWaitOf = (row) => {
+    if (row.token === null || row.token === undefined)
+        return undefined;
+    const point = waitPointOf(row.token);
+    if (row.reason !== humanWaitReason && !(row.reason === "event" && point.name !== undefined))
+        return undefined;
+    return {
+        runId: row.runId,
+        reason: row.reason,
+        token: row.token,
+        tokenDigest: Sha256.digestSync(row.token),
+        createdAt: row.createdAt,
+        ...(row.flowId === undefined ? {} : { flowId: row.flowId }),
+        ...point,
+        ...(row.request === undefined ? {} : { request: row.request })
+    };
+};
+/**
+ * The wait a `Node` approval target addresses, when it addresses one.
+ *
+ * Most gates are a capability the run wants allowed: the target's `digest` is
+ * the request's own digest, a decision grants or refuses it, and the control
+ * plane holds a registered token for it. A `HumanTask` gate has no such token
+ * — nothing registers one, because the run parked itself on a durable wait
+ * rather than asking the control plane for permission — and `lookupApproval`
+ * answers a target with no token by reporting the RUN as missing. That is what
+ * an operator saw when the app submitted an answer as an ordinary approval:
+ * `/control/RunNotFound` naming a run that was listed, rendered, and waiting
+ * (workspace 4bb93306, run-1).
+ *
+ * So a decision has to be able to tell the two apart from the payload alone.
+ * The approvals projection publishes a human wait with the durable wait token
+ * as the `digest` and the wait point's own name as the `requestId`, and a
+ * durable deferred token is self-describing: it decodes to a flow, an
+ * execution, and a deferred name under `WaitFor/`. Nothing else produces one,
+ * so a target carrying one is a question, and the name it answers is right
+ * there.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const answerableWait = (target) => {
+    if (target._tag !== "Node")
+        return undefined;
+    const point = waitPointOf(target.digest);
+    return point.name === undefined ? undefined : { name: target.requestId, token: target.digest };
+};
+/**
+ * The {@link Service} tag.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export class ControlExecutor extends Context.Service()("/control/ControlExecutor") {
+}
+/**
+ * Builds a {@link Service} from an implementation of its methods.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = (implementation) => ControlExecutor.of(implementation);
+/**
+ * A {@link Service} that accepts every launch as `pending` and starts
+ * nothing. Overrides replace individual methods.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeNoop = (overrides = {}) => make({
+    launch: Effect.fn("ControlExecutor.launch")(() => Effect.succeed("pending")),
+    // An executor that starts nothing owns no engine row and no wait point, so
+    // it records no cancel and matches no signal. `Control.cancel` still writes
+    // its journal entry and interrupts a local fiber, and `Control.signal`
+    // still records the message: both are what the port's absence already did.
+    requestCancel: Effect.fn("ControlExecutor.requestCancel")(() => Effect.succeed("unknown")),
+    deliverSignal: Effect.fn("ControlExecutor.deliverSignal")(() => Effect.succeed("unknown")),
+    resumeRun: Effect.fn("ControlExecutor.resumeRun")(() => Effect.succeed("unknown")),
+    settleCancelledPark: Effect.fn("ControlExecutor.settleCancelledPark")(() => Effect.void),
+    ...overrides
+});
+/**
+ * Provides {@link ControlExecutor} from an implementation.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = (implementation) => Layer.succeed(ControlExecutor)(make(implementation));
+/**
+ * The same executor with methods that drive a run refused.
+ *
+ * A host composed to observe runs rather than drive them has no completion
+ * judge, so it must not be able to start or resume one: without this a verb
+ * misclassified as a read would admit a run and lose it at its first
+ * completion, which is the outcome the boot-time judge requirement exists to
+ * prevent. Reaching either method is a composition defect, not an operator
+ * error, so it dies rather than failing.
+ *
+ * Observation, cancellation and signal delivery stay live. A cancel and a
+ * signal record a durable request that the process driving the run picks up,
+ * so none of them reaches a completion, and refusing them would stop an
+ * operator ending a run on a host with no gateway key, which is the whole
+ * reason a read host exists.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const makeObserving = (service) => {
+    const refuse = (method) => Effect.die(new Error(`This host observes runs and drives none, so ControlExecutor.${method} is unreachable on it. ` +
+        "Compose it with startsRuns to start or resume a run."));
+    return make({
+        ...service,
+        requestComplete: undefined,
+        launch: Effect.fn("ControlExecutor.launch")(() => refuse("launch")),
+        resumeRun: Effect.fn("ControlExecutor.resumeRun")(() => refuse("resumeRun"))
+    });
+};
+/**
+ * An executor that only reads the engine: every method that drives or
+ * changes a run dies.
+ *
+ * A host composed over read-only stores carries it. Unlike
+ * {@link makeObserving}, it records no cancel and delivers no signal, because
+ * such a host can write neither. Without `readExecution` a listing answers
+ * from the control plane's coordination copy alone.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const makeReadOnly = ({ readExecution, readExecutions } = {}) => {
+    const refuse = (method) => Effect.die(new Error(`This host only observes runs, so ControlExecutor.${method} is unreachable on it.`));
+    return make({
+        ...(readExecution === undefined ? {} : { readExecution }),
+        ...(readExecutions === undefined ? {} : { readExecutions }),
+        launch: Effect.fn("ControlExecutor.launch")(() => refuse("launch")),
+        requestCancel: Effect.fn("ControlExecutor.requestCancel")(() => refuse("requestCancel")),
+        deliverSignal: Effect.fn("ControlExecutor.deliverSignal")(() => refuse("deliverSignal")),
+        resumeRun: Effect.fn("ControlExecutor.resumeRun")(() => refuse("resumeRun")),
+        settleCancelledPark: Effect.fn("ControlExecutor.settleCancelledPark")(() => refuse("settleCancelledPark"))
+    });
+};
+/**
+ * Provides {@link makeNoop}.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layerNoop = (overrides = {}) => Layer.succeed(ControlExecutor)(makeNoop(overrides));
+//# sourceMappingURL=ControlExecutor.js.map

package/dist/esm/ControlExecutor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ControlExecutor.js","sourceRoot":"","sources":["../../src/ControlExecutor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Acceptance port from the control plane into a real run executor.\n *\n * Governing contract: `docs/pages/control/index.md`.\n *\n * @since 0.1.0\n */\n\nimport * as Sha256 from \"@smthrs/crypto/Sha256\"\nimport * as DurableDeferred from \"@smthrs/flow/DurableDeferred\"\nimport type { ExecutionFact } from \"@smthrs/journal\"\nimport { Context, Effect, Layer, Option, Schema } from \"effect\"\nimport type { LaunchFailed, PersistenceError } from \"./ControlError.ts\"\nimport type { StoredPlan } from \"./ControlRuntime.ts\"\nimport type {\n  ApprovalTarget,\n  ExecutionBatch,\n  PendingWait,\n  Principal,\n  Receipt,\n  RunId,\n  RunSummary,\n  SignalPayload\n} from \"./ControlSchema.ts\"\n\n/**\n * One stored plan and the run summary it is being started as.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Launch {\n  readonly plan: StoredPlan\n  readonly run: RunSummary\n}\n\n/**\n * Whether the executor took the launch now or queued it.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Acceptance = \"accepted\" | \"pending\"\n\n/**\n * One run whose cancellation has to become durable on the engine row.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface CancelRequest {\n  readonly runId: RunId\n}\n\n/**\n * The engine row a cancel request arrived too late for.\n *\n * It carries the ENGINE's status rather than a bare marker because the control\n * plane cannot read that row: in the shipped CLI the two `flows_runs` tables\n * live in two files (`.flows/control.db` and `.flows/engine.db`), so the port\n * is the only place the plane learns what actually became of the run.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface CancelTerminal {\n  readonly _tag: \"Terminal\"\n  readonly status: \"completed\" | \"failed\" | \"cancelled\"\n}\n\n/**\n * What the executor did with a cancel request.\n *\n * `recorded` means THIS call set `cancel_requested_at_ms` on the engine row, so\n * the owning process stops the run at its next cancel poll whichever process\n * asked. `already-requested` means the column was already set when this call\n * arrived: the request is just as durable, and the cancellation it belongs to\n * was somebody else's. `Control.cancel` keys its attribution event on that\n * difference — the write is first-writer-wins and every repeat re-runs the\n * whole mutation, so answering `recorded` to all of them left one journaled\n * `control.run.cancel-requested` per ask for a single cancellation (release validation\n * smoke: three `cancel` calls and one `down` against one parked run left four).\n * `unknown` means this executor's engine has no row for the run at all, which\n * is the honest answer for a run another composition launched into a database\n * this one does not share. A {@link CancelTerminal} means the engine row has\n * already settled, so there is nothing left to stop: recording intent on it\n * would be a request no process can ever act on, and answering `recorded` let\n * `Control.cancel` write a terminal control status the engine row does not have\n * (triage B-11).\n *\n * @category models\n * @since 0.1.0\n */\nexport type CancelRecord = \"recorded\" | \"already-requested\" | \"unknown\" | CancelTerminal\n\n/**\n * One parked run that has been told to resume.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface ResumeRequest {\n  readonly runId: RunId\n}\n\n/**\n * What the executor did with a resume request.\n *\n * `resuming` means this executor hosts the run's execution, has taken the\n * control row's fence, and is re-driving it: the caller can stop, and the run\n * moves on its own. `unknown` means this executor drives no execution for the\n * run, which is the answer an operator's CLI, a gateway, or any second process\n * gives, and it is why the control plane records the delegation durably\n * instead of treating its own journal entry as the delivery (triage B-15).\n *\n * @category models\n * @since 0.1.0\n */\nexport type ResumeUptake = \"resuming\" | \"unknown\"\n\n/**\n * One signal to deliver to a run's open wait point.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Signal {\n  /** Actor-scoped durable admission identity, present on control-plane delivery. */\n  readonly commandId?: string\n  /** An existing immutable binding survives a crash before acknowledgment. */\n  readonly token?: string | null\n  readonly runId: RunId\n  readonly signal: SignalPayload\n  /**\n   * Who admitted the signal. A human wait ({@link humanWaitReason}) completes\n   * only when `ApprovalAuthority` authorizes this principal to approve the\n   * wait's `Node` target; without one the signal is `refused`.\n   */\n  readonly principal?: Principal | undefined\n}\n\n/**\n * What the executor did with a signal.\n *\n * `delivered` means the `WaitFor` deferred the run is parked on was completed\n * with the signal's payload and the run was woken. `no-match` means the run IS\n * parked and is waiting for something else, which `Control.signal` refuses\n * rather than recording a delivery nothing consumes. `unknown` means this\n * executor is driving no execution for the run at all — another process may\n * be, or none is yet — so the recorded message is the whole delivery and the\n * executor that eventually drives the run replays it at its next start.\n * `refused` means the signal named an open human wait and `ApprovalAuthority`\n * did not authorize its principal to answer it: the wait stays open, and\n * `Control.signal` fails `Unauthorized`.\n *\n * @category models\n * @since 0.1.0\n */\nexport type SignalDelivery = \"delivered\" | \"no-match\" | \"refused\" | \"unknown\"\n\n/**\n * Current engine observation. Missing execution is distinct from a running one.\n * @category models\n * @since 1.0.0\n */\nexport type ExecutionObservation =\n  | { readonly _tag: \"Missing\" }\n  | {\n    readonly _tag: \"Observed\"\n    readonly executionView?: ExecutionFact.View | undefined\n    readonly status: \"accepted\" | \"running\" | \"parked\" | \"waiting-approval\" | \"completed\" | \"failed\" | \"cancelled\"\n    readonly waitingReason?: string | undefined\n    readonly parentRunId?: string | undefined\n    readonly lineageId?: string | undefined\n    readonly roundOrdinal?: number | undefined\n    /**\n     * Open human waits anywhere in this execution's tree.\n     *\n     * The control plane cannot compute these. It keeps its own coordination\n     * copy of `flows_runs`, and the executions a flow spawns — where a nested\n     * `HumanTask` actually parks — exist only in the executor's database, with\n     * the edges that link them. `readExecution` is the one place that reads\n     * both, so it is where a run tree's open questions become visible to\n     * anything else.\n     *\n     * Absent when nothing in the tree is waiting on a person. `status` rolls\n     * up with them: an execution parked while a descendant holds a human wait\n     * is observed as `waiting-approval`.\n     */\n    readonly pendingWaits?: ReadonlyArray<PendingWait> | undefined\n  }\n\n/**\n * The waiting reason a human wait parks under.\n *\n * `HumanTask` and the agent's own `ask` both declare it\n * (`@smthrs/flow` `FlowRuntime.annotateWaiting({ reason: \"approval\" })`), so\n * it is the one value that separates \"somebody has to answer this\" from every\n * other park.\n *\n * @category models\n * @since 1.0.0\n */\nexport const humanWaitReason = \"approval\"\n\n/**\n * The wait point a durable token addresses, as a person reads it.\n *\n * A `HumanTask` attempt is its own wait point named `WaitFor/<task>#<attempt>`\n * (`@smthrs/flow` `HumanTask`), and a plain `WaitFor` gate is `WaitFor/<name>`.\n * Splitting the two out of the token is what lets a client address an answer by\n * the name a person was asked under rather than by a base64 blob, and lets an\n * inbox say which of three attempts is open.\n *\n * A token this plane cannot parse names nothing extra; the token itself still\n * travels, so the wait stays answerable.\n */\n/** The engine's own decoder: tokens are UTF-8 JSON in base64url, which `atob` misreads. */\nconst decodeToken = Schema.decodeUnknownOption(DurableDeferred.TokenParsed.FromString)\n\nconst waitPointOf = (token: string): { readonly name?: string; readonly attempt?: number } => {\n  const decoded = decodeToken(token)\n  if (Option.isNone(decoded)) return {}\n  const deferredName = decoded.value.deferredName\n  if (!deferredName.startsWith(\"WaitFor/\")) return {}\n  const point = deferredName.slice(\"WaitFor/\".length)\n  const marker = point.lastIndexOf(\"#\")\n  if (marker < 0) return { name: point }\n  const attempt = Number(point.slice(marker + 1))\n  return Number.isSafeInteger(attempt) && attempt > 0\n    ? { name: point.slice(0, marker), attempt }\n    : { name: point }\n}\n\n/**\n * One parked execution as a {@link PendingWait}, or nothing when it is not a\n * wait a person or a named control signal can end.\n *\n * Shared by the two readers that produce these rows — the control plane's own\n * SQL runtime, when it shares a database with the engine, and the executor's\n * observation port, when it does not — so a wait reads the same either way.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const pendingWaitOf = (row: {\n  readonly runId: string\n  readonly flowId?: string | undefined\n  readonly reason: string\n  readonly token: string | null | undefined\n  readonly request?: unknown\n  readonly createdAt: number\n}): PendingWait | undefined => {\n  if (row.token === null || row.token === undefined) return undefined\n  const point = waitPointOf(row.token)\n  if (row.reason !== humanWaitReason && !(row.reason === \"event\" && point.name !== undefined)) return undefined\n  return {\n    runId: row.runId,\n    reason: row.reason,\n    token: row.token,\n    tokenDigest: Sha256.digestSync(row.token),\n    createdAt: row.createdAt,\n    ...(row.flowId === undefined ? {} : { flowId: row.flowId }),\n    ...point,\n    ...(row.request === undefined ? {} : { request: row.request as PendingWait[\"request\"] })\n  }\n}\n\n/**\n * The wait a `Node` approval target addresses, when it addresses one.\n *\n * Most gates are a capability the run wants allowed: the target's `digest` is\n * the request's own digest, a decision grants or refuses it, and the control\n * plane holds a registered token for it. A `HumanTask` gate has no such token\n * — nothing registers one, because the run parked itself on a durable wait\n * rather than asking the control plane for permission — and `lookupApproval`\n * answers a target with no token by reporting the RUN as missing. That is what\n * an operator saw when the app submitted an answer as an ordinary approval:\n * `/control/RunNotFound` naming a run that was listed, rendered, and waiting\n * (workspace 4bb93306, run-1).\n *\n * So a decision has to be able to tell the two apart from the payload alone.\n * The approvals projection publishes a human wait with the durable wait token\n * as the `digest` and the wait point's own name as the `requestId`, and a\n * durable deferred token is self-describing: it decodes to a flow, an\n * execution, and a deferred name under `WaitFor/`. Nothing else produces one,\n * so a target carrying one is a question, and the name it answers is right\n * there.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const answerableWait = (\n  target: ApprovalTarget\n): { readonly name: string; readonly token: string } | undefined => {\n  if (target._tag !== \"Node\") return undefined\n  const point = waitPointOf(target.digest)\n  return point.name === undefined ? undefined : { name: target.requestId, token: target.digest }\n}\n\n/**\n * The executor port: the control plane hands work over to a real run executor\n * and learns only what the executor did with it.\n *\n * `launch` is acceptance. `requestCancel`, `deliverSignal`, and `resumeRun`\n * are the three requests that have to reach the engine to mean anything: a\n * cancel is durable on the engine row so that whichever process owns the run\n * stops it, a signal completes the wait point a parked run is actually waiting\n * on, and a resume re-drives the execution an approval decision unblocked.\n * Without them the control plane records facts nobody reads — a cancel that\n * answers `ClaimLost` to every process but the owner, a signal a parked run\n * never sees, and a resume event published into an in-process hub no other\n * process subscribes to (the release policy; triage B-10, B-13, B-15).\n *\n * @category services\n * @since 0.1.0\n */\nexport interface Service {\n  /** Read from the executor's database, never the control coordination copy. */\n  readonly readExecution?: (runId: RunId) => Effect.Effect<ExecutionObservation, PersistenceError>\n  /** Exact observations scoped to the authorized control root; unrelated native rows are never exposed. */\n  readonly readExecutions?: (input: {\n    readonly runId: RunId\n    readonly executionIds: ReadonlyArray<string>\n  }) => Effect.Effect<ExecutionBatch, PersistenceError>\n  readonly launch: (input: Launch) => Effect.Effect<Acceptance, LaunchFailed>\n  /**\n   * Host-only close of a retained run, after its last native module completed.\n   * @since 1.0.0\n   */\n  readonly requestComplete?:\n    | ((input: { readonly runId: RunId; readonly receiptId: string }) => Effect.Effect<Receipt, PersistenceError>)\n    | undefined\n  /**\n   * Records a cancellation on the engine row, durably, regardless of which\n   * process owns the run.\n   */\n  readonly requestCancel: (input: CancelRequest) => Effect.Effect<CancelRecord, PersistenceError>\n  /**\n   * Completes the run's open `WaitFor` wait point with the signal's payload.\n   */\n  readonly deliverSignal: (input: Signal) => Effect.Effect<SignalDelivery, PersistenceError>\n  /**\n   * Takes up a resume: claims the control row and re-drives the execution,\n   * when this executor is the one hosting it.\n   */\n  readonly resumeRun: (input: ResumeRequest) => Effect.Effect<ResumeUptake, PersistenceError>\n  /**\n   * Finishes a PARKED execution whose cancellation is already durable.\n   *\n   * A park has no owner — that is what makes it resumable — so nothing is\n   * driving the run and nothing reads the request {@link requestCancel} wrote.\n   * The engine's parked-run sweep does, once per heartbeat, but a `smithers\n   * cancel` process writes the request at the very end of its life and exits\n   * before that tick: the release validation watched an engine row stay\n   * `suspended` with `cancel_requested_at_ms` set through six more commands\n   * and fifteen seconds, so `gc` collected the run in `control.db` and\n   * skipped it in `engine.db`.\n   *\n   * Called AFTER the cancel mutation commits, never inside it: driving a run\n   * re-enters the engine, whose writes would wait on the writer the\n   * mutation's transaction holds. An executor that does not host the run, or\n   * one whose run is not parked, does nothing and leaves the durable request\n   * standing for the host that does.\n   */\n  readonly settleCancelledPark: (input: CancelRequest) => Effect.Effect<void, PersistenceError>\n}\n\n/**\n * The {@link Service} tag.\n *\n * @category services\n * @since 0.1.0\n */\nexport class ControlExecutor extends Context.Service<ControlExecutor, Service>()(\n  \"/control/ControlExecutor\"\n) {}\n\n/**\n * Builds a {@link Service} from an implementation of its methods.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = (implementation: Service): Service => ControlExecutor.of(implementation)\n\n/**\n * A {@link Service} that accepts every launch as `pending` and starts\n * nothing. Overrides replace individual methods.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const makeNoop = (overrides: Partial<Service> = {}): Service =>\n  make({\n    launch: Effect.fn(\"ControlExecutor.launch\")(() => Effect.succeed(\"pending\" as const)),\n    // An executor that starts nothing owns no engine row and no wait point, so\n    // it records no cancel and matches no signal. `Control.cancel` still writes\n    // its journal entry and interrupts a local fiber, and `Control.signal`\n    // still records the message: both are what the port's absence already did.\n    requestCancel: Effect.fn(\"ControlExecutor.requestCancel\")(() => Effect.succeed(\"unknown\" as const)),\n    deliverSignal: Effect.fn(\"ControlExecutor.deliverSignal\")(() => Effect.succeed(\"unknown\" as const)),\n    resumeRun: Effect.fn(\"ControlExecutor.resumeRun\")(() => Effect.succeed(\"unknown\" as const)),\n    settleCancelledPark: Effect.fn(\"ControlExecutor.settleCancelledPark\")(() => Effect.void),\n    ...overrides\n  })\n\n/**\n * Provides {@link ControlExecutor} from an implementation.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer = (implementation: Service): Layer.Layer<ControlExecutor> =>\n  Layer.succeed(ControlExecutor)(make(implementation))\n\n/**\n * The same executor with methods that drive a run refused.\n *\n * A host composed to observe runs rather than drive them has no completion\n * judge, so it must not be able to start or resume one: without this a verb\n * misclassified as a read would admit a run and lose it at its first\n * completion, which is the outcome the boot-time judge requirement exists to\n * prevent. Reaching either method is a composition defect, not an operator\n * error, so it dies rather than failing.\n *\n * Observation, cancellation and signal delivery stay live. A cancel and a\n * signal record a durable request that the process driving the run picks up,\n * so none of them reaches a completion, and refusing them would stop an\n * operator ending a run on a host with no gateway key, which is the whole\n * reason a read host exists.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const makeObserving = (service: Service): Service => {\n  const refuse = (method: string) =>\n    Effect.die(\n      new Error(\n        `This host observes runs and drives none, so ControlExecutor.${method} is unreachable on it. ` +\n          \"Compose it with startsRuns to start or resume a run.\"\n      )\n    )\n  return make({\n    ...service,\n    requestComplete: undefined,\n    launch: Effect.fn(\"ControlExecutor.launch\")(() => refuse(\"launch\")),\n    resumeRun: Effect.fn(\"ControlExecutor.resumeRun\")(() => refuse(\"resumeRun\"))\n  })\n}\n\n/**\n * An executor that only reads the engine: every method that drives or\n * changes a run dies.\n *\n * A host composed over read-only stores carries it. Unlike\n * {@link makeObserving}, it records no cancel and delivers no signal, because\n * such a host can write neither. Without `readExecution` a listing answers\n * from the control plane's coordination copy alone.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const makeReadOnly = (\n  { readExecution, readExecutions }: {\n    readonly readExecution?: Service[\"readExecution\"]\n    readonly readExecutions?: Service[\"readExecutions\"]\n  } = {}\n): Service => {\n  const refuse = (method: string) =>\n    Effect.die(new Error(`This host only observes runs, so ControlExecutor.${method} is unreachable on it.`))\n  return make({\n    ...(readExecution === undefined ? {} : { readExecution }),\n    ...(readExecutions === undefined ? {} : { readExecutions }),\n    launch: Effect.fn(\"ControlExecutor.launch\")(() => refuse(\"launch\")),\n    requestCancel: Effect.fn(\"ControlExecutor.requestCancel\")(() => refuse(\"requestCancel\")),\n    deliverSignal: Effect.fn(\"ControlExecutor.deliverSignal\")(() => refuse(\"deliverSignal\")),\n    resumeRun: Effect.fn(\"ControlExecutor.resumeRun\")(() => refuse(\"resumeRun\")),\n    settleCancelledPark: Effect.fn(\"ControlExecutor.settleCancelledPark\")(() => refuse(\"settleCancelledPark\"))\n  })\n}\n\n/**\n * Provides {@link makeNoop}.\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layerNoop = (overrides: Partial<Service> = {}): Layer.Layer<ControlExecutor> =>\n  Layer.succeed(ControlExecutor)(makeNoop(overrides))\n"]}