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

package/dist/esm/Cancellation.js

@@ -0,0 +1,116 @@
+/**
+ * Cancellation attribution as the control plane reads it back.
+ *
+ * A cancellation is durable but anonymous. `flows_runs.cancel_requested_at_ms`
+ * records that somebody asked, and nothing in the row records who, why, or
+ * whether the run was asked at all rather than swept up in an ancestor's
+ * cascade. Three journals hold the missing halves: the control plane's own
+ * `control.run.cancel-requested`, the engine's `flows.engine.interrupted`, and
+ * the ancestry the run store already keeps. This module folds them into one
+ * answer per run.
+ *
+ * The fold is pure and scope-independent: it reads whatever evidence it is
+ * handed and never issues a query, so the caller chooses how much to read.
+ * `SqlControlRuntime` uses two scopes. A listing folds the whole database,
+ * because every row is going to be answered for anyway. A single-run read
+ * folds only that run and its ancestor chain, which is the smallest scope that
+ * can still answer the question: cascade is a fact about a run's ancestors, so
+ * it cannot be decided one row at a time — a child's cancellation is
+ * attributed to whoever asked for its nearest cancelled ancestor's, however
+ * many rounds up that is.
+ *
+ * The two foreign event types are named as strings rather than imported,
+ * exactly as in {@link Lineage}: a control plane reads journals, not engines.
+ *
+ * @since 0.1.0
+ */
+/**
+ * The journal event type the control plane records an attributed cancel under.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const requestedEventType = "control.run.cancel-requested";
+/**
+ * The journal event type the engine records an interruption under.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const interruptedEventType = "flows.engine.interrupted";
+const cancelled = (evidence, requests) => evidence.cancelRequestedAt !== undefined || evidence.cancelledAt !== undefined ||
+    requests.has(evidence.runId);
+const requestedAtOf = (evidence, request) => {
+    /* v8 ignore next -- the trailing zero is unreachable: a run is attributed only once one of the three sources above exists, which is exactly what `cancelled` reads */
+    return request?.requestedAt ?? evidence.cancelRequestedAt ?? evidence.cancelledAt ?? 0;
+};
+const attributed = (source, requestedAt, request, cascadedFrom) => ({
+    requestedAt,
+    source,
+    ...(request?.principal === undefined ? {} : { principal: request.principal }),
+    ...(request?.reason === undefined ? {} : { reason: request.reason }),
+    ...(cascadedFrom === undefined ? {} : { cascadedFrom })
+});
+/**
+ * Attributes every cancelled run in one pass.
+ *
+ * Three sources, in the order a run's own evidence outranks its ancestors':
+ *
+ * 1. A `control.run.cancel-requested` entry names this run. Somebody asked for
+ *    this run by name, and the entry says who and why.
+ * 2. A cancelled ancestor exists. The run was swept up in that cancellation,
+ *    so it reports `cascade`, names the ancestor whose request started it, and
+ *    inherits that request's principal and reason — the honest answer to "who
+ *    cancelled this child" is the operator who cancelled its parent.
+ * 3. Neither. The engine cancelled the run on its own account: a lease
+ *    expiry, a budget, a supervisor. There is no principal to report, and
+ *    inventing one would be worse than saying nothing.
+ *
+ * The ancestor walk carries a visited set. A cyclic parent chain is not
+ * reachable through the engine's cycle detection, but a projection that hung
+ * on corrupt ancestry would take the control plane down with it.
+ *
+ * @param input the run evidence and the attributed requests
+ * @category projections
+ * @since 0.1.0
+ */
+export const attribute = (input) => {
+    const evidence = new Map(input.runs.map((run) => [run.runId, run]));
+    const result = new Map();
+    for (const run of input.runs) {
+        if (!cancelled(run, input.requests))
+            continue;
+        const own = input.requests.get(run.runId);
+        const requestedAt = requestedAtOf(run, own);
+        if (own !== undefined) {
+            result.set(run.runId, attributed("control", requestedAt, own));
+            continue;
+        }
+        const visited = new Set([run.runId]);
+        let ancestorId = run.parentRunId;
+        let cascadedFrom;
+        let origin;
+        while (ancestorId !== undefined && !visited.has(ancestorId)) {
+            visited.add(ancestorId);
+            const ancestor = evidence.get(ancestorId);
+            if (ancestor === undefined)
+                break;
+            if (cancelled(ancestor, input.requests)) {
+                // The nearest cancelled ancestor is the run this one was swept up
+                // with; the request that started it may be further up still, because
+                // a cascade cascades.
+                if (cascadedFrom === undefined)
+                    cascadedFrom = ancestorId;
+                origin = input.requests.get(ancestorId);
+                if (origin !== undefined)
+                    break;
+            }
+            ancestorId = ancestor.parentRunId;
+        }
+        result.set(run.runId, cascadedFrom === undefined
+            ? attributed("engine", requestedAt, undefined)
+            : attributed("cascade", requestedAt, origin, cascadedFrom));
+    }
+    return result;
+};
+//# sourceMappingURL=Cancellation.js.map

package/dist/esm/Cancellation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cancellation.js","sourceRoot":"","sources":["../../src/Cancellation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Cancellation attribution as the control plane reads it back.\n *\n * A cancellation is durable but anonymous. `flows_runs.cancel_requested_at_ms`\n * records that somebody asked, and nothing in the row records who, why, or\n * whether the run was asked at all rather than swept up in an ancestor's\n * cascade. Three journals hold the missing halves: the control plane's own\n * `control.run.cancel-requested`, the engine's `flows.engine.interrupted`, and\n * the ancestry the run store already keeps. This module folds them into one\n * answer per run.\n *\n * The fold is pure and scope-independent: it reads whatever evidence it is\n * handed and never issues a query, so the caller chooses how much to read.\n * `SqlControlRuntime` uses two scopes. A listing folds the whole database,\n * because every row is going to be answered for anyway. A single-run read\n * folds only that run and its ancestor chain, which is the smallest scope that\n * can still answer the question: cascade is a fact about a run's ancestors, so\n * it cannot be decided one row at a time — a child's cancellation is\n * attributed to whoever asked for its nearest cancelled ancestor's, however\n * many rounds up that is.\n *\n * The two foreign event types are named as strings rather than imported,\n * exactly as in {@link Lineage}: a control plane reads journals, not engines.\n *\n * @since 0.1.0\n */\n\nimport type { Cancellation, Principal } from \"./ControlSchema.ts\"\n\n/**\n * The journal event type the control plane records an attributed cancel under.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const requestedEventType = \"control.run.cancel-requested\"\n\n/**\n * The journal event type the engine records an interruption under.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const interruptedEventType = \"flows.engine.interrupted\"\n\n/**\n * One attributed cancel request, as the control plane journaled it.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Request {\n  readonly requestedAt: number\n  readonly principal?: Principal | undefined\n  readonly reason?: string | undefined\n}\n\n/**\n * What one run row discloses about its own cancellation.\n *\n * `cancelRequestedAt` is the run store's unfenced request column, and\n * `cancelledAt` is the moment the engine journaled the interruption. Either\n * one alone is evidence that this run was cancelled, and so is an attributed\n * request naming the run: a control plane that cancels a run it owns\n * interrupts the fiber rather than asking the column, and the journal entry it\n * wrote is the whole record.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Evidence {\n  readonly runId: string\n  readonly parentRunId?: string | undefined\n  readonly cancelRequestedAt?: number | undefined\n  readonly cancelledAt?: number | undefined\n}\n\n/**\n * Everything the fold reads.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Input {\n  readonly runs: ReadonlyArray<Evidence>\n  /** Attributed requests the control plane journaled, by run id. */\n  readonly requests: ReadonlyMap<string, Request>\n}\n\nconst cancelled = (evidence: Evidence, requests: Input[\"requests\"]): boolean =>\n  evidence.cancelRequestedAt !== undefined || evidence.cancelledAt !== undefined ||\n  requests.has(evidence.runId)\n\nconst requestedAtOf = (evidence: Evidence, request: Request | undefined): number => {\n  /* v8 ignore next -- the trailing zero is unreachable: a run is attributed only once one of the three sources above exists, which is exactly what `cancelled` reads */\n  return request?.requestedAt ?? evidence.cancelRequestedAt ?? evidence.cancelledAt ?? 0\n}\n\nconst attributed = (\n  source: Cancellation[\"source\"],\n  requestedAt: number,\n  request: Request | undefined,\n  cascadedFrom?: string\n): Cancellation => ({\n  requestedAt,\n  source,\n  ...(request?.principal === undefined ? {} : { principal: request.principal }),\n  ...(request?.reason === undefined ? {} : { reason: request.reason }),\n  ...(cascadedFrom === undefined ? {} : { cascadedFrom })\n})\n\n/**\n * Attributes every cancelled run in one pass.\n *\n * Three sources, in the order a run's own evidence outranks its ancestors':\n *\n * 1. A `control.run.cancel-requested` entry names this run. Somebody asked for\n *    this run by name, and the entry says who and why.\n * 2. A cancelled ancestor exists. The run was swept up in that cancellation,\n *    so it reports `cascade`, names the ancestor whose request started it, and\n *    inherits that request's principal and reason — the honest answer to \"who\n *    cancelled this child\" is the operator who cancelled its parent.\n * 3. Neither. The engine cancelled the run on its own account: a lease\n *    expiry, a budget, a supervisor. There is no principal to report, and\n *    inventing one would be worse than saying nothing.\n *\n * The ancestor walk carries a visited set. A cyclic parent chain is not\n * reachable through the engine's cycle detection, but a projection that hung\n * on corrupt ancestry would take the control plane down with it.\n *\n * @param input the run evidence and the attributed requests\n * @category projections\n * @since 0.1.0\n */\nexport const attribute = (input: Input): ReadonlyMap<string, Cancellation> => {\n  const evidence = new Map(input.runs.map((run) => [run.runId, run]))\n  const result = new Map<string, Cancellation>()\n  for (const run of input.runs) {\n    if (!cancelled(run, input.requests)) continue\n    const own = input.requests.get(run.runId)\n    const requestedAt = requestedAtOf(run, own)\n    if (own !== undefined) {\n      result.set(run.runId, attributed(\"control\", requestedAt, own))\n      continue\n    }\n    const visited = new Set<string>([run.runId])\n    let ancestorId = run.parentRunId\n    let cascadedFrom: string | undefined\n    let origin: Request | undefined\n    while (ancestorId !== undefined && !visited.has(ancestorId)) {\n      visited.add(ancestorId)\n      const ancestor = evidence.get(ancestorId)\n      if (ancestor === undefined) break\n      if (cancelled(ancestor, input.requests)) {\n        // The nearest cancelled ancestor is the run this one was swept up\n        // with; the request that started it may be further up still, because\n        // a cascade cascades.\n        if (cascadedFrom === undefined) cascadedFrom = ancestorId\n        origin = input.requests.get(ancestorId)\n        if (origin !== undefined) break\n      }\n      ancestorId = ancestor.parentRunId\n    }\n    result.set(\n      run.runId,\n      cascadedFrom === undefined\n        ? attributed(\"engine\", requestedAt, undefined)\n        : attributed(\"cascade\", requestedAt, origin, cascadedFrom)\n    )\n  }\n  return result\n}\n"]}

package/dist/esm/Channels.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Channel contracts and the in-memory channel coordinator.
+ *
+ * A channel verifies opaque transport data before it decodes or maps it. The
+ * resulting request is then dispatched through the Control service; channels
+ * do not acquire an execution path of their own.
+ *
+ * @since 0.1.0
+ */
+import { Context, Effect, Layer, type Schema } from "effect";
+import { Control } from "./Control.ts";
+import { type ControlError, InvalidInput, type Unauthorized, Unavailable } from "./ControlError.ts";
+import { ControlRuntime } from "./ControlRuntime.ts";
+import type { FlowId, IdempotencyKey, Receipt, RunId, RunSummary, SignalPayload } from "./ControlSchema.ts";
+/**
+ * Opaque request data passed to a channel before decoding.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface RawInbound {
+    readonly body: Uint8Array;
+    readonly headers: Readonly<Record<string, string | undefined>>;
+    readonly idempotencyKey: IdempotencyKey;
+}
+/**
+ * The channel mapping after a verified payload has been decoded.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type InboundResult = {
+    readonly _tag: "Start";
+    readonly flowId: FlowId;
+    readonly input: unknown;
+} | {
+    readonly _tag: "Signal";
+    readonly runId: RunId;
+    readonly signal: SignalPayload;
+};
+/**
+ * A process-local per-channel delivery record. `messageId` identifies an existing
+ * platform message, so a reconnect can update it instead of posting again.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Delivery {
+    readonly cursor: string;
+    readonly messageId?: string | undefined;
+}
+/**
+ * A side-effect-free outbound projection. Network delivery belongs to the
+ * transport adapter, which consumes this value after it is journaled.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface DeliveryProjection {
+    readonly cursor: string;
+    readonly messageId?: string | undefined;
+    readonly operation: "post" | "edit" | "noop";
+    readonly message: unknown;
+}
+/**
+ * A bidirectional platform adapter.
+ *
+ * `verify` must only inspect opaque bytes and headers. It always precedes
+ * `decode`, preventing untrusted public requests from reaching planning.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export interface Channel<A = unknown> {
+    readonly name: string;
+    readonly schema: Schema.Schema<A>;
+    /**
+     * Non-secret HTTP header names whose values change the decoded command.
+     * Names are matched case-insensitively and folded into durable idempotency;
+     * signature, authorization, and credential headers must not be declared.
+     */
+    readonly fingerprintHeaders?: ReadonlyArray<string> | undefined;
+    readonly verify: (raw: RawInbound) => Effect.Effect<void, Unauthorized>;
+    /** Deterministic, side-effect-free decoding; retries may evaluate it again. */
+    readonly decode: (raw: RawInbound) => Effect.Effect<A, InvalidInput>;
+    /** Deterministic, side-effect-free mapping; retries may evaluate it again. */
+    readonly map: (payload: A) => Effect.Effect<InboundResult, InvalidInput>;
+    readonly project: (run: RunSummary, delivery: Delivery | undefined) => DeliveryProjection;
+}
+/**
+ * A registered channel with its payload type hidden. Decoding and mapping stay
+ * paired, so lookup never exposes a mapper accepting arbitrary unknown data.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface RegisteredChannel extends Omit<Channel, "decode" | "map"> {
+    readonly decodeAndMap: (raw: RawInbound) => Effect.Effect<InboundResult, InvalidInput>;
+}
+/**
+ * Arguments for ingesting one authenticated channel request.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface IngestRequest {
+    readonly channel: string;
+    readonly raw: RawInbound;
+}
+/**
+ * Arguments for projecting one run onto a channel.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface ProjectRequest {
+    readonly channel: string;
+    readonly run: RunSummary;
+}
+/**
+ * The channel coordinator.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export interface Channels {
+    readonly register: <A>(channel: Channel<A>) => Effect.Effect<void>;
+    readonly lookup: (name: string) => Effect.Effect<RegisteredChannel, Unavailable>;
+    readonly ingest: (request: IngestRequest) => Effect.Effect<Receipt, ControlError>;
+    readonly project: (request: ProjectRequest) => Effect.Effect<DeliveryProjection, Unavailable>;
+}
+/**
+ * Service tag for channel registration, ingestion, and pure projection.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare const Channels: Context.Service<Channels, Channels>;
+/**
+ * Builds the coordinator over Control's durable mutation store.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const make: Effect.Effect<Channels, never, Control | ControlRuntime>;
+/**
+ * Builds a process-local coordinator for adapter unit tests.
+ *
+ * Production hosts use {@link layer}; this constructor deliberately makes no
+ * restart guarantee.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const makeMemory: Effect.Effect<Channels, never, Control>;
+/**
+ * Channel layer with durable inbound receipts supplied by `ControlRuntime`.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: Layer.Layer<Channels, never, Control | ControlRuntime>;
+/**
+ * Process-local channel layer for adapter unit tests only.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export declare const layerMemory: Layer.Layer<Channels, never, Control>;
+//# sourceMappingURL=Channels.d.ts.map

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

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

package/dist/esm/Channels.js

@@ -0,0 +1,312 @@
+/**
+ * Channel contracts and the in-memory channel coordinator.
+ *
+ * A channel verifies opaque transport data before it decodes or maps it. The
+ * resulting request is then dispatched through the Control service; channels
+ * do not acquire an execution path of their own.
+ *
+ * @since 0.1.0
+ */
+import * as Sha256 from "@smthrs/crypto/Sha256";
+import { Clock, Context, Effect, Layer, Ref, Semaphore } from "effect";
+import { Control } from "./Control.js";
+import { InvalidInput, Unavailable } from "./ControlError.js";
+import { ControlRuntime } from "./ControlRuntime.js";
+import { alreadyApplied } from "./internal/planning.js";
+const eraseChannel = (channel) => ({
+    name: channel.name,
+    schema: channel.schema,
+    fingerprintHeaders: channel.fingerprintHeaders,
+    verify: (raw) => channel.verify(raw),
+    decodeAndMap: (raw) => Effect.flatMap(channel.decode(raw), (payload) => channel.map(payload)),
+    project: (run, delivery) => channel.project(run, delivery)
+});
+/**
+ * Service tag for channel registration, ingestion, and pure projection.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export const Channels = Context.Service("/control/Channels");
+const unavailable = (feature) => new Unavailable({
+    feature,
+    ticket: "control-channel-registry"
+});
+const deliveryKey = (channel, run) => `${channel.length}:${channel}:${run.runId}`;
+/** Collision-free control-plane key for one channel-owned external key. */
+const scopedKey = (channel, key) => `channel:${channel.length}:${channel}:${key}`;
+const mutationKey = (channel, key) => `channel.ingest:${scopedKey(channel, key)}`;
+const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+const typedArrayBuffer = Object.getOwnPropertyDescriptor(typedArrayPrototype, "buffer")?.get;
+const typedArrayByteOffset = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteOffset")?.get;
+const typedArrayByteLength = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteLength")?.get;
+class InboundBoundaryError extends TypeError {
+    issue;
+    constructor(issue) {
+        super(issue);
+        this.issue = issue;
+    }
+}
+const boundary = (issue) => {
+    throw new InboundBoundaryError(issue);
+};
+const plainRecord = (input, path) => {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        return boundary(`${path}: must be a plain record`);
+    }
+    const prototype = Object.getPrototypeOf(input);
+    if (prototype !== Object.prototype && prototype !== null) {
+        return boundary(`${path}: must have a plain prototype`);
+    }
+    return input;
+};
+const ownData = (input, key, path) => {
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    if (descriptor === undefined || !("value" in descriptor))
+        return boundary(`${path}: must be an own data property`);
+    return descriptor.value;
+};
+const copyBody = (input) => {
+    /* v8 ignore next 4 -- every host that has `Uint8Array` has its prototype accessors; the refusal exists so a host without them fails closed rather than reading a caller-owned buffer */
+    if (typedArrayBuffer === undefined || typedArrayByteOffset === undefined ||
+        typedArrayByteLength === undefined)
+        return boundary("raw.body: this host cannot inspect typed arrays");
+    try {
+        const buffer = Reflect.apply(typedArrayBuffer, input, []);
+        const byteOffset = Reflect.apply(typedArrayByteOffset, input, []);
+        const byteLength = Reflect.apply(typedArrayByteLength, input, []);
+        const source = new Uint8Array(buffer, byteOffset, byteLength);
+        const snapshot = new Uint8Array(byteLength);
+        snapshot.set(source);
+        return snapshot;
+    }
+    catch {
+        return boundary("raw.body: must be a Uint8Array");
+    }
+};
+const snapshotHeaders = (input) => {
+    const record = plainRecord(input, "raw.headers");
+    const snapshot = Object.create(null);
+    for (const key of Reflect.ownKeys(record)) {
+        if (typeof key !== "string")
+            return boundary("raw.headers: symbol keys are not supported");
+        const descriptor = Object.getOwnPropertyDescriptor(record, key);
+        if (descriptor === undefined || !("value" in descriptor) || !descriptor.enumerable) {
+            return boundary(`raw.headers.${key}: must be an enumerable data property`);
+        }
+        if (descriptor.value !== undefined && typeof descriptor.value !== "string") {
+            return boundary(`raw.headers.${key}: must be a string or undefined`);
+        }
+        const normalized = key.toLowerCase();
+        if (Object.hasOwn(snapshot, normalized)) {
+            return boundary(`raw.headers.${normalized}: duplicate case-insensitive name`);
+        }
+        snapshot[normalized] = descriptor.value;
+    }
+    return Object.freeze(snapshot);
+};
+const snapshotRequest = (input) => Effect.try({
+    try: () => {
+        const request = plainRecord(input, "request");
+        const channel = ownData(request, "channel", "request.channel");
+        const candidate = plainRecord(ownData(request, "raw", "request.raw"), "request.raw");
+        const idempotencyKey = ownData(candidate, "idempotencyKey", "raw.idempotencyKey");
+        if (typeof channel !== "string" || channel.length === 0)
+            return boundary("request.channel: must be non-empty");
+        if (typeof idempotencyKey !== "string" || idempotencyKey.length === 0) {
+            return boundary("raw.idempotencyKey: must be non-empty");
+        }
+        return Object.freeze({
+            channel,
+            raw: Object.freeze({
+                body: copyBody(ownData(candidate, "body", "raw.body")),
+                headers: snapshotHeaders(ownData(candidate, "headers", "raw.headers")),
+                idempotencyKey
+            })
+        });
+    },
+    catch: (cause) => new InvalidInput({
+        issue: cause instanceof InboundBoundaryError ? cause.issue : "channel request could not be inspected safely"
+    })
+});
+const normalizedFingerprintHeaders = (channel) => Array.from(new Set((channel.fingerprintHeaders ?? []).map((name) => name.toLowerCase()))).sort();
+/** Digests the body plus only the adapter-declared, non-secret semantic headers. */
+const fingerprint = (body, headers, names) => {
+    const document = JSON.stringify([
+        Sha256.digestSync(body),
+        names.map((name) => [name, headers[name] ?? null])
+    ]);
+    return `channel-ingress:v2:${Sha256.digestSync(new TextEncoder().encode(document))}`;
+};
+const externalReceipt = (receipt, key) => {
+    switch (receipt._tag) {
+        case "Accepted":
+        case "AlreadyApplied":
+        case "Parked":
+            return { ...receipt, receiptId: key };
+        default:
+            return receipt;
+    }
+};
+/**
+ * Builds an in-memory channel registry and delivery map over Control's durable
+ * mutation store. Inbound idempotency therefore survives coordinator restarts;
+ * only registration and outbound projection cursors are process-local.
+ */
+const makeWith = (runtime) => Effect.gen(function* () {
+    const channels = yield* Ref.make(new Map());
+    const deliveries = new Map();
+    // Live identities are never evicted. Terminal identities have a FIFO window
+    // for reconnects; retaining one per historical run would grow without bound.
+    const terminalDeliveries = new Set();
+    const maximumTerminalDeliveries = 1024;
+    const ingestion = yield* Semaphore.make(1);
+    const control = yield* Control;
+    const lookup = Effect.fn("Channels.lookup")(function* (name) {
+        return yield* Effect.flatMap(Ref.get(channels), (registered) => {
+            const channel = registered.get(name);
+            return channel === undefined
+                ? Effect.fail(unavailable(`channel "${name}" is not registered`))
+                : Effect.succeed(channel);
+        });
+    });
+    return Channels.of({
+        register: Effect.fn("Channels.register")((channel) => Ref.update(channels, (registered) => {
+            const next = new Map(registered);
+            next.set(channel.name, eraseChannel(channel));
+            return next;
+        })),
+        lookup,
+        ingest: Effect.fn("Channels.ingest")((request) => Effect.flatMap(snapshotRequest(request), (snapshot) => ingestion.withPermits(1)(Effect.gen(function* () {
+            const channel = yield* lookup(snapshot.channel);
+            const fingerprintHeaders = normalizedFingerprintHeaders(channel);
+            const bodyFingerprint = fingerprint(snapshot.raw.body, snapshot.raw.headers, fingerprintHeaders);
+            // This ordering is intentional: signature verification is the
+            // amplification guard and must happen before decode or Control access.
+            // The verifier receives its own body copy, so even a verifier that
+            // edits bytes cannot change what the decoder sees after approval.
+            yield* channel.verify({ ...snapshot.raw, body: copyBody(snapshot.raw.body) });
+            const externalKey = snapshot.raw.idempotencyKey;
+            const durableKey = mutationKey(snapshot.channel, externalKey);
+            const prior = yield* runtime.lookupMutation(durableKey, bodyFingerprint);
+            if (prior !== undefined)
+                return externalReceipt(prior, externalKey);
+            const mapped = yield* channel.decodeAndMap(snapshot.raw);
+            const key = scopedKey(snapshot.channel, externalKey);
+            let receipt;
+            if (mapped._tag === "Signal") {
+                // The channel is the caller, not the local operator: a webhook
+                // body names the run and wait, so a signal it maps to answers a
+                // human wait only if the host delegates approval to this channel.
+                receipt = yield* control.signal({
+                    runId: mapped.runId,
+                    signal: mapped.signal,
+                    idempotencyKey: key,
+                    principal: { id: snapshot.channel, kind: "channel", stampedAt: yield* Clock.currentTimeMillis }
+                });
+            }
+            else {
+                const plan = yield* control.plan({
+                    flowId: mapped.flowId,
+                    input: mapped.input,
+                    idempotencyKey: key
+                });
+                receipt = yield* control.run({
+                    _tag: "Plan",
+                    planId: plan.planId,
+                    digest: plan.digest,
+                    envelope: plan.envelope,
+                    idempotencyKey: key
+                });
+            }
+            // A parked start has not launched. Leave ingress unsettled so a
+            // redelivery can retry the same Control key after plan approval.
+            if (receipt._tag !== "Conflict" && receipt._tag !== "Parked") {
+                yield* runtime.recordMutation(durableKey, bodyFingerprint, receipt);
+            }
+            return externalReceipt(receipt, externalKey);
+        })))),
+        project: Effect.fn("Channels.project")(function* (request) {
+            const channel = yield* lookup(request.channel);
+            const key = deliveryKey(request.channel, request.run);
+            // Keep the read, projection and update synchronous so concurrent fibers
+            // cannot project from the same stale delivery identity.
+            return yield* Effect.sync(() => {
+                const prior = deliveries.get(key);
+                const projection = channel.project(request.run, prior);
+                if (projection.operation !== "noop" &&
+                    (prior === undefined || prior.cursor !== projection.cursor || prior.messageId !== projection.messageId)) {
+                    deliveries.set(key, { cursor: projection.cursor, messageId: projection.messageId });
+                }
+                if (deliveries.has(key)) {
+                    const status = request.run.status;
+                    if (status === "completed" || status === "failed" || status === "cancelled") {
+                        terminalDeliveries.add(key);
+                        if (terminalDeliveries.size > maximumTerminalDeliveries) {
+                            // The set is nonempty because it just exceeded the limit.
+                            const oldest = terminalDeliveries.values().next().value;
+                            terminalDeliveries.delete(oldest);
+                            deliveries.delete(oldest);
+                        }
+                    }
+                    else {
+                        terminalDeliveries.delete(key);
+                    }
+                }
+                return projection;
+            });
+        })
+    });
+});
+/**
+ * Builds the coordinator over Control's durable mutation store.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const make = Effect.gen(function* () {
+    const runtime = yield* ControlRuntime;
+    return yield* makeWith(runtime);
+});
+/**
+ * Builds a process-local coordinator for adapter unit tests.
+ *
+ * Production hosts use {@link layer}; this constructor deliberately makes no
+ * restart guarantee.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const makeMemory = Effect.gen(function* () {
+    const records = yield* Ref.make(new Map());
+    return yield* makeWith({
+        lookupMutation: (key, candidate) => Ref.get(records).pipe(Effect.map((stored) => {
+            const prior = stored.get(key);
+            if (prior === undefined)
+                return undefined;
+            return prior.fingerprint === candidate
+                ? alreadyApplied(key, prior.receipt)
+                : { _tag: "Conflict", message: `idempotency key ${key} was used for another mutation` };
+        })),
+        recordMutation: (key, candidate, receipt) => Ref.update(records, (stored) => {
+            const next = new Map(stored);
+            next.set(key, { fingerprint: candidate, receipt });
+            return next;
+        })
+    });
+});
+/**
+ * Channel layer with durable inbound receipts supplied by `ControlRuntime`.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = Layer.effect(Channels, make);
+/**
+ * Process-local channel layer for adapter unit tests only.
+ *
+ * @category layers
+ * @since 1.0.0
+ */
+export const layerMemory = Layer.effect(Channels, makeMemory);
+//# sourceMappingURL=Channels.js.map