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

package/dist/cjs/Cancellation.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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
+ */
+import type { Cancellation, Principal } from "./ControlSchema.ts";
+/**
+ * The journal event type the control plane records an attributed cancel under.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const requestedEventType = "control.run.cancel-requested";
+/**
+ * The journal event type the engine records an interruption under.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const interruptedEventType = "flows.engine.interrupted";
+/**
+ * One attributed cancel request, as the control plane journaled it.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Request {
+    readonly requestedAt: number;
+    readonly principal?: Principal | undefined;
+    readonly reason?: string | undefined;
+}
+/**
+ * What one run row discloses about its own cancellation.
+ *
+ * `cancelRequestedAt` is the run store's unfenced request column, and
+ * `cancelledAt` is the moment the engine journaled the interruption. Either
+ * one alone is evidence that this run was cancelled, and so is an attributed
+ * request naming the run: a control plane that cancels a run it owns
+ * interrupts the fiber rather than asking the column, and the journal entry it
+ * wrote is the whole record.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Evidence {
+    readonly runId: string;
+    readonly parentRunId?: string | undefined;
+    readonly cancelRequestedAt?: number | undefined;
+    readonly cancelledAt?: number | undefined;
+}
+/**
+ * Everything the fold reads.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Input {
+    readonly runs: ReadonlyArray<Evidence>;
+    /** Attributed requests the control plane journaled, by run id. */
+    readonly requests: ReadonlyMap<string, Request>;
+}
+/**
+ * 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 declare const attribute: (input: Input) => ReadonlyMap<string, Cancellation>;
+//# sourceMappingURL=Cancellation.d.ts.map

package/dist/cjs/Cancellation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cancellation.d.ts","sourceRoot":"","sources":["../../src/Cancellation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAEjE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,iCAAiC,CAAA;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,6BAA6B,CAAA;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACrC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1C;AAED;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAA;IACtC,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChD;AAwBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,KAAK,KAAG,WAAW,CAAC,MAAM,EAAE,YAAY,CAqCxE,CAAA"}

package/dist/cjs/Cancellation.js

@@ -0,0 +1,72 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Cancellation_exports = {};
+__export(Cancellation_exports, {
+  attribute: () => attribute,
+  interruptedEventType: () => interruptedEventType,
+  requestedEventType: () => requestedEventType
+});
+module.exports = __toCommonJS(Cancellation_exports);
+const requestedEventType = "control.run.cancel-requested";
+const interruptedEventType = "flows.engine.interrupted";
+const cancelled = (evidence, requests) => evidence.cancelRequestedAt !== void 0 || evidence.cancelledAt !== void 0 || requests.has(evidence.runId);
+const requestedAtOf = (evidence, request) => {
+  return request?.requestedAt ?? evidence.cancelRequestedAt ?? evidence.cancelledAt ?? 0;
+};
+const attributed = (source, requestedAt, request, cascadedFrom) => ({
+  requestedAt,
+  source,
+  ...request?.principal === void 0 ? {} : { principal: request.principal },
+  ...request?.reason === void 0 ? {} : { reason: request.reason },
+  ...cascadedFrom === void 0 ? {} : { cascadedFrom }
+});
+const attribute = (input) => {
+  const evidence = new Map(input.runs.map((run) => [run.runId, run]));
+  const result = /* @__PURE__ */ 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 !== void 0) {
+      result.set(run.runId, attributed("control", requestedAt, own));
+      continue;
+    }
+    const visited = /* @__PURE__ */ new Set([run.runId]);
+    let ancestorId = run.parentRunId;
+    let cascadedFrom;
+    let origin;
+    while (ancestorId !== void 0 && !visited.has(ancestorId)) {
+      visited.add(ancestorId);
+      const ancestor = evidence.get(ancestorId);
+      if (ancestor === void 0) break;
+      if (cancelled(ancestor, input.requests)) {
+        if (cascadedFrom === void 0) cascadedFrom = ancestorId;
+        origin = input.requests.get(ancestorId);
+        if (origin !== void 0) break;
+      }
+      ancestorId = ancestor.parentRunId;
+    }
+    result.set(
+      run.runId,
+      cascadedFrom === void 0 ? attributed("engine", requestedAt, void 0) : attributed("cascade", requestedAt, origin, cascadedFrom)
+    );
+  }
+  return result;
+};
+//# sourceMappingURL=Cancellation.js.map

package/dist/cjs/Cancellation.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Cancellation.ts"],
+  "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 \u2014 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 \u2014 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"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAmCO,MAAM,qBAAqB;AAQ3B,MAAM,uBAAuB;AA8CpC,MAAM,YAAY,CAAC,UAAoB,aACrC,SAAS,sBAAsB,UAAa,SAAS,gBAAgB,UACrE,SAAS,IAAI,SAAS,KAAK;AAE7B,MAAM,gBAAgB,CAAC,UAAoB,YAAyC;AAElF,SAAO,SAAS,eAAe,SAAS,qBAAqB,SAAS,eAAe;AACvF;AAEA,MAAM,aAAa,CACjB,QACA,aACA,SACA,kBACkB;AAAA,EAClB;AAAA,EACA;AAAA,EACA,GAAI,SAAS,cAAc,SAAY,CAAC,IAAI,EAAE,WAAW,QAAQ,UAAU;AAAA,EAC3E,GAAI,SAAS,WAAW,SAAY,CAAC,IAAI,EAAE,QAAQ,QAAQ,OAAO;AAAA,EAClE,GAAI,iBAAiB,SAAY,CAAC,IAAI,EAAE,aAAa;AACvD;AAyBO,MAAM,YAAY,CAAC,UAAoD;AAC5E,QAAM,WAAW,IAAI,IAAI,MAAM,KAAK,IAAI,CAAC,QAAQ,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC;AAClE,QAAM,SAAS,oBAAI,IAA0B;AAC7C,aAAW,OAAO,MAAM,MAAM;AAC5B,QAAI,CAAC,UAAU,KAAK,MAAM,QAAQ,EAAG;AACrC,UAAM,MAAM,MAAM,SAAS,IAAI,IAAI,KAAK;AACxC,UAAM,cAAc,cAAc,KAAK,GAAG;AAC1C,QAAI,QAAQ,QAAW;AACrB,aAAO,IAAI,IAAI,OAAO,WAAW,WAAW,aAAa,GAAG,CAAC;AAC7D;AAAA,IACF;AACA,UAAM,UAAU,oBAAI,IAAY,CAAC,IAAI,KAAK,CAAC;AAC3C,QAAI,aAAa,IAAI;AACrB,QAAI;AACJ,QAAI;AACJ,WAAO,eAAe,UAAa,CAAC,QAAQ,IAAI,UAAU,GAAG;AAC3D,cAAQ,IAAI,UAAU;AACtB,YAAM,WAAW,SAAS,IAAI,UAAU;AACxC,UAAI,aAAa,OAAW;AAC5B,UAAI,UAAU,UAAU,MAAM,QAAQ,GAAG;AAIvC,YAAI,iBAAiB,OAAW,gBAAe;AAC/C,iBAAS,MAAM,SAAS,IAAI,UAAU;AACtC,YAAI,WAAW,OAAW;AAAA,MAC5B;AACA,mBAAa,SAAS;AAAA,IACxB;AACA,WAAO;AAAA,MACL,IAAI;AAAA,MACJ,iBAAiB,SACb,WAAW,UAAU,aAAa,MAAS,IAC3C,WAAW,WAAW,aAAa,QAAQ,YAAY;AAAA,IAC7D;AAAA,EACF;AACA,SAAO;AACT;",
+  "names": []
+}

package/dist/cjs/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/cjs/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/cjs/Channels.js

@@ -0,0 +1,278 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Channels_exports = {};
+__export(Channels_exports, {
+  Channels: () => Channels,
+  layer: () => layer,
+  layerMemory: () => layerMemory,
+  make: () => make,
+  makeMemory: () => makeMemory
+});
+module.exports = __toCommonJS(Channels_exports);
+var Sha256 = __toESM(require("@smthrs/crypto/Sha256"), 1);
+var import_effect = require("effect");
+var import_Control = require("./Control.js");
+var import_ControlError = require("./ControlError.js");
+var import_ControlRuntime = require("./ControlRuntime.js");
+var import_planning = require("./internal/planning.js");
+const eraseChannel = (channel) => ({
+  name: channel.name,
+  schema: channel.schema,
+  fingerprintHeaders: channel.fingerprintHeaders,
+  verify: (raw) => channel.verify(raw),
+  decodeAndMap: (raw) => import_effect.Effect.flatMap(channel.decode(raw), (payload) => channel.map(payload)),
+  project: (run, delivery) => channel.project(run, delivery)
+});
+const Channels = import_effect.Context.Service("/control/Channels");
+const unavailable = (feature) => new import_ControlError.Unavailable({
+  feature,
+  ticket: "control-channel-registry"
+});
+const deliveryKey = (channel, run) => `${channel.length}:${channel}:${run.runId}`;
+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 === void 0 || !("value" in descriptor)) return boundary(`${path}: must be an own data property`);
+  return descriptor.value;
+};
+const copyBody = (input) => {
+  if (typedArrayBuffer === void 0 || typedArrayByteOffset === void 0 || typedArrayByteLength === void 0) 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 = /* @__PURE__ */ 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 === void 0 || !("value" in descriptor) || !descriptor.enumerable) {
+      return boundary(`raw.headers.${key}: must be an enumerable data property`);
+    }
+    if (descriptor.value !== void 0 && 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) => import_effect.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 import_ControlError.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();
+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;
+  }
+};
+const makeWith = (runtime) => import_effect.Effect.gen(function* () {
+  const channels = yield* import_effect.Ref.make(/* @__PURE__ */ new Map());
+  const deliveries = /* @__PURE__ */ new Map();
+  const terminalDeliveries = /* @__PURE__ */ new Set();
+  const maximumTerminalDeliveries = 1024;
+  const ingestion = yield* import_effect.Semaphore.make(1);
+  const control = yield* import_Control.Control;
+  const lookup = import_effect.Effect.fn("Channels.lookup")(
+    function* (name) {
+      return yield* import_effect.Effect.flatMap(import_effect.Ref.get(channels), (registered) => {
+        const channel = registered.get(name);
+        return channel === void 0 ? import_effect.Effect.fail(unavailable(`channel "${name}" is not registered`)) : import_effect.Effect.succeed(channel);
+      });
+    }
+  );
+  return Channels.of({
+    register: import_effect.Effect.fn("Channels.register")(
+      (channel) => import_effect.Ref.update(channels, (registered) => {
+        const next = new Map(registered);
+        next.set(channel.name, eraseChannel(channel));
+        return next;
+      })
+    ),
+    lookup,
+    ingest: import_effect.Effect.fn("Channels.ingest")(
+      (request) => import_effect.Effect.flatMap(snapshotRequest(request), (snapshot) => ingestion.withPermits(1)(import_effect.Effect.gen(function* () {
+        const channel = yield* lookup(snapshot.channel);
+        const fingerprintHeaders = normalizedFingerprintHeaders(channel);
+        const bodyFingerprint = fingerprint(snapshot.raw.body, snapshot.raw.headers, fingerprintHeaders);
+        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 !== void 0) return externalReceipt(prior, externalKey);
+        const mapped = yield* channel.decodeAndMap(snapshot.raw);
+        const key = scopedKey(snapshot.channel, externalKey);
+        let receipt;
+        if (mapped._tag === "Signal") {
+          receipt = yield* control.signal({
+            runId: mapped.runId,
+            signal: mapped.signal,
+            idempotencyKey: key,
+            principal: { id: snapshot.channel, kind: "channel", stampedAt: yield* import_effect.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
+          });
+        }
+        if (receipt._tag !== "Conflict" && receipt._tag !== "Parked") {
+          yield* runtime.recordMutation(durableKey, bodyFingerprint, receipt);
+        }
+        return externalReceipt(receipt, externalKey);
+      })))
+    ),
+    project: import_effect.Effect.fn("Channels.project")(function* (request) {
+      const channel = yield* lookup(request.channel);
+      const key = deliveryKey(request.channel, request.run);
+      return yield* import_effect.Effect.sync(() => {
+        const prior = deliveries.get(key);
+        const projection = channel.project(request.run, prior);
+        if (projection.operation !== "noop" && (prior === void 0 || 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) {
+              const oldest = terminalDeliveries.values().next().value;
+              terminalDeliveries.delete(oldest);
+              deliveries.delete(oldest);
+            }
+          } else {
+            terminalDeliveries.delete(key);
+          }
+        }
+        return projection;
+      });
+    })
+  });
+});
+const make = import_effect.Effect.gen(function* () {
+  const runtime = yield* import_ControlRuntime.ControlRuntime;
+  return yield* makeWith(runtime);
+});
+const makeMemory = import_effect.Effect.gen(function* () {
+  const records = yield* import_effect.Ref.make(
+    /* @__PURE__ */ new Map()
+  );
+  return yield* makeWith({
+    lookupMutation: (key, candidate) => import_effect.Ref.get(records).pipe(import_effect.Effect.map((stored) => {
+      const prior = stored.get(key);
+      if (prior === void 0) return void 0;
+      return prior.fingerprint === candidate ? (0, import_planning.alreadyApplied)(key, prior.receipt) : { _tag: "Conflict", message: `idempotency key ${key} was used for another mutation` };
+    })),
+    recordMutation: (key, candidate, receipt) => import_effect.Ref.update(records, (stored) => {
+      const next = new Map(stored);
+      next.set(key, { fingerprint: candidate, receipt });
+      return next;
+    })
+  });
+});
+const layer = import_effect.Layer.effect(Channels, make);
+const layerMemory = import_effect.Layer.effect(Channels, makeMemory);
+//# sourceMappingURL=Channels.js.map