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

package/dist/esm/Steering.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The steer lifecycle as the control plane reads it back.
+ *
+ * A steer has two durable moments and two different writers. The control plane
+ * records the first — `control.steer.enqueued`, written beside the admission
+ * it caused. The second belongs to `@smthrs/notifications`: a turn boundary
+ * promotes the notification and the queue journals the promotion. This module
+ * projects that promotion into the control vocabulary, so a watcher folds one
+ * stream instead of two, and so nothing writes "delivered" twice.
+ *
+ * Deriving rather than re-recording is what keeps the two halves honest. A
+ * control plane that emitted its own delivery record would be asserting a fact
+ * it did not observe: the boundary that delivered the steer runs in the agent
+ * process, not this one.
+ *
+ * @since 0.1.0
+ */
+import type { ControlEvent } from "./ControlSchema.ts";
+/**
+ * The journal event type the notification queue records a promotion under.
+ *
+ * Named as a string rather than imported so this projection reads a journal
+ * written by any queue implementation, exactly as `Lineage` reads engine
+ * decisions.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const promotedEventType = "flows/notifications/Promoted";
+/**
+ * The kind `watch` reports one delivered steer under.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const deliveredEventType = "control.steer.delivered";
+/**
+ * The kind `Control.steer` records an accepted steer under.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const enqueuedEventType = "control.steer.enqueued";
+/**
+ * Derives one delivery delta per message a promotion entry named.
+ *
+ * A boundary promotes a batch, so one entry can disclose several deliveries.
+ * Each delta carries the source sequence and the boundary that took it.
+ * `ControlLive.watch` adds an expansion cursor so a consumer can resume
+ * between deliveries in the same batch.
+ *
+ * A promotion that named nothing derives nothing: an idle boundary drains an
+ * empty queue on every turn, and reporting that as a delivery would bury the
+ * real ones.
+ *
+ * @param event the projected journal entry
+ * @category projections
+ * @since 0.1.0
+ */
+export declare const derive: (event: ControlEvent) => ReadonlyArray<ControlEvent>;
+/**
+ * Expands one projected entry into itself plus any deliveries it discloses.
+ *
+ * @param event the projected journal entry
+ * @category projections
+ * @since 0.1.0
+ */
+export declare const expand: (event: ControlEvent) => ReadonlyArray<ControlEvent>;
+//# sourceMappingURL=Steering.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Steering.d.ts","sourceRoot":"","sources":["../../src/Steering.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,iCAAiC,CAAA;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,4BAA4B,CAAA;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,2BAA2B,CAAA;AAUzD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,YAAY,KAAG,aAAa,CAAC,YAAY,CActE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,YAAY,KAAG,aAAa,CAAC,YAAY,CAA8B,CAAA"}

package/dist/esm/Steering.js

@@ -0,0 +1,89 @@
+/**
+ * The steer lifecycle as the control plane reads it back.
+ *
+ * A steer has two durable moments and two different writers. The control plane
+ * records the first — `control.steer.enqueued`, written beside the admission
+ * it caused. The second belongs to `@smthrs/notifications`: a turn boundary
+ * promotes the notification and the queue journals the promotion. This module
+ * projects that promotion into the control vocabulary, so a watcher folds one
+ * stream instead of two, and so nothing writes "delivered" twice.
+ *
+ * Deriving rather than re-recording is what keeps the two halves honest. A
+ * control plane that emitted its own delivery record would be asserting a fact
+ * it did not observe: the boundary that delivered the steer runs in the agent
+ * process, not this one.
+ *
+ * @since 0.1.0
+ */
+/**
+ * The journal event type the notification queue records a promotion under.
+ *
+ * Named as a string rather than imported so this projection reads a journal
+ * written by any queue implementation, exactly as `Lineage` reads engine
+ * decisions.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const promotedEventType = "flows/notifications/Promoted";
+/**
+ * The kind `watch` reports one delivered steer under.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const deliveredEventType = "control.steer.delivered";
+/**
+ * The kind `Control.steer` records an accepted steer under.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const enqueuedEventType = "control.steer.enqueued";
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value
+    : undefined;
+const strings = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+/**
+ * Derives one delivery delta per message a promotion entry named.
+ *
+ * A boundary promotes a batch, so one entry can disclose several deliveries.
+ * Each delta carries the source sequence and the boundary that took it.
+ * `ControlLive.watch` adds an expansion cursor so a consumer can resume
+ * between deliveries in the same batch.
+ *
+ * A promotion that named nothing derives nothing: an idle boundary drains an
+ * empty queue on every turn, and reporting that as a delivery would bury the
+ * real ones.
+ *
+ * @param event the projected journal entry
+ * @category projections
+ * @since 0.1.0
+ */
+export const derive = (event) => {
+    const runId = event.runId;
+    if (event.kind !== promotedEventType || runId === undefined)
+        return [];
+    const payload = record(event.payload);
+    if (payload === undefined)
+        return [];
+    const boundary = typeof payload["boundary"] === "string" ? payload["boundary"] : undefined;
+    if (boundary === undefined)
+        return [];
+    return strings(payload["ids"]).map((messageId) => ({
+        sequence: event.sequence,
+        kind: deliveredEventType,
+        runId,
+        occurredAt: event.occurredAt,
+        payload: { runId, messageId, boundary }
+    }));
+};
+/**
+ * Expands one projected entry into itself plus any deliveries it discloses.
+ *
+ * @param event the projected journal entry
+ * @category projections
+ * @since 0.1.0
+ */
+export const expand = (event) => [event, ...derive(event)];
+//# sourceMappingURL=Steering.js.map

package/dist/esm/Steering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Steering.js","sourceRoot":"","sources":["../../src/Steering.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,8BAA8B,CAAA;AAE/D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,yBAAyB,CAAA;AAE3D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,wBAAwB,CAAA;AAEzD,MAAM,MAAM,GAAG,CAAC,KAAc,EAAiD,EAAE,CAC/E,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;IAClE,CAAC,CAAC,KAA0C;IAC5C,CAAC,CAAC,SAAS,CAAA;AAEf,MAAM,OAAO,GAAG,CAAC,KAAc,EAAyB,EAAE,CACxD,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AAEjG;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,KAAmB,EAA+B,EAAE;IACzE,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAA;IACzB,IAAI,KAAK,CAAC,IAAI,KAAK,iBAAiB,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAA;IACtE,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IACrC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,CAAA;IACpC,MAAM,QAAQ,GAAG,OAAO,OAAO,CAAC,UAAU,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAC1F,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,EAAE,CAAA;IACrC,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAgB,EAAE,CAAC,CAAC;QAC/D,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,IAAI,EAAE,kBAAkB;QACxB,KAAK;QACL,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,OAAO,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE;KACxC,CAAC,CAAC,CAAA;AACL,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,KAAmB,EAA+B,EAAE,CAAC,CAAC,KAAK,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA","sourcesContent":["/**\n * The steer lifecycle as the control plane reads it back.\n *\n * A steer has two durable moments and two different writers. The control plane\n * records the first — `control.steer.enqueued`, written beside the admission\n * it caused. The second belongs to `@smthrs/notifications`: a turn boundary\n * promotes the notification and the queue journals the promotion. This module\n * projects that promotion into the control vocabulary, so a watcher folds one\n * stream instead of two, and so nothing writes \"delivered\" twice.\n *\n * Deriving rather than re-recording is what keeps the two halves honest. A\n * control plane that emitted its own delivery record would be asserting a fact\n * it did not observe: the boundary that delivered the steer runs in the agent\n * process, not this one.\n *\n * @since 0.1.0\n */\n\nimport type { ControlEvent } from \"./ControlSchema.ts\"\n\n/**\n * The journal event type the notification queue records a promotion under.\n *\n * Named as a string rather than imported so this projection reads a journal\n * written by any queue implementation, exactly as `Lineage` reads engine\n * decisions.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const promotedEventType = \"flows/notifications/Promoted\"\n\n/**\n * The kind `watch` reports one delivered steer under.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const deliveredEventType = \"control.steer.delivered\"\n\n/**\n * The kind `Control.steer` records an accepted steer under.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const enqueuedEventType = \"control.steer.enqueued\"\n\nconst record = (value: unknown): Readonly<Record<string, unknown>> | undefined =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value)\n    ? value as Readonly<Record<string, unknown>>\n    : undefined\n\nconst strings = (value: unknown): ReadonlyArray<string> =>\n  Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === \"string\") : []\n\n/**\n * Derives one delivery delta per message a promotion entry named.\n *\n * A boundary promotes a batch, so one entry can disclose several deliveries.\n * Each delta carries the source sequence and the boundary that took it.\n * `ControlLive.watch` adds an expansion cursor so a consumer can resume\n * between deliveries in the same batch.\n *\n * A promotion that named nothing derives nothing: an idle boundary drains an\n * empty queue on every turn, and reporting that as a delivery would bury the\n * real ones.\n *\n * @param event the projected journal entry\n * @category projections\n * @since 0.1.0\n */\nexport const derive = (event: ControlEvent): ReadonlyArray<ControlEvent> => {\n  const runId = event.runId\n  if (event.kind !== promotedEventType || runId === undefined) return []\n  const payload = record(event.payload)\n  if (payload === undefined) return []\n  const boundary = typeof payload[\"boundary\"] === \"string\" ? payload[\"boundary\"] : undefined\n  if (boundary === undefined) return []\n  return strings(payload[\"ids\"]).map((messageId): ControlEvent => ({\n    sequence: event.sequence,\n    kind: deliveredEventType,\n    runId,\n    occurredAt: event.occurredAt,\n    payload: { runId, messageId, boundary }\n  }))\n}\n\n/**\n * Expands one projected entry into itself plus any deliveries it discloses.\n *\n * @param event the projected journal entry\n * @category projections\n * @since 0.1.0\n */\nexport const expand = (event: ControlEvent): ReadonlyArray<ControlEvent> => [event, ...derive(event)]\n"]}

package/dist/esm/SystemFlows.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Reserved system-flow identifiers projected by the command-line interface.
+ *
+ * @since 0.1.0
+ */
+/**
+ * The projection metadata for one reserved system flow.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface SystemFlowEntry {
+    readonly verb: string;
+    readonly flowId: `system/${string}`;
+    readonly projection: "procedure" | "systemFlow";
+    readonly deployClass: boolean;
+    readonly planBearing: boolean;
+    /**
+     * Whether a control plane may plan and run this reserved id.
+     *
+     * `false` means the row is command-line metadata and nothing else: the verb
+     * is named here so the binary can refuse it by name, and no runtime may
+     * offer it as a flow. `replay` was removed by the frozen rc.0 contract yet
+     * every runtime turned the whole catalog into plannable flows, so
+     * `plan({flowId: "system/replay"})` returned a real approval card and only a
+     * later `run` failed. A removed feature that half works is exactly what the
+     * contract forbids.
+     */
+    readonly plannable: boolean;
+}
+/**
+ * The authoritative command-line verb to reserved-flow map.
+ *
+ * `gc` is the retention verb: it resolves `@smthrs/engine-store`'s `retain`
+ * operation, which deletes aged terminal runs with their attempts, clock
+ * deadlines, deferred completions, journal entries, and time-travel archive
+ * rows. It is a procedure rather than a deploy-class system flow because it
+ * takes no plan and bears no approval envelope; the deletion is gated by the
+ * operator invoking it, and automatic retention stays opt-in.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export declare const catalog: readonly [{
+    readonly verb: "plan";
+    readonly flowId: "system/plan";
+    readonly projection: "procedure";
+    readonly deployClass: false;
+    readonly planBearing: false;
+    readonly plannable: true;
+}, {
+    readonly verb: "run";
+    readonly flowId: "system/run";
+    readonly projection: "procedure";
+    readonly deployClass: false;
+    readonly planBearing: false;
+    readonly plannable: true;
+}, {
+    readonly verb: "release";
+    readonly flowId: "system/release";
+    readonly projection: "systemFlow";
+    readonly deployClass: true;
+    readonly planBearing: true;
+    readonly plannable: true;
+}, {
+    readonly verb: "serve";
+    readonly flowId: "system/serve";
+    readonly projection: "systemFlow";
+    readonly deployClass: true;
+    readonly planBearing: true;
+    readonly plannable: true;
+}, {
+    readonly verb: "up";
+    readonly flowId: "system/up";
+    readonly projection: "systemFlow";
+    readonly deployClass: true;
+    readonly planBearing: true;
+    readonly plannable: true;
+}, {
+    readonly verb: "ls";
+    readonly flowId: "system/ls";
+    readonly projection: "procedure";
+    readonly deployClass: false;
+    readonly planBearing: false;
+    readonly plannable: true;
+}, {
+    readonly verb: "ps";
+    readonly flowId: "system/ps";
+    readonly projection: "procedure";
+    readonly deployClass: false;
+    readonly planBearing: false;
+    readonly plannable: true;
+}, {
+    readonly verb: "logs";
+    readonly flowId: "system/logs";
+    readonly projection: "procedure";
+    readonly deployClass: false;
+    readonly planBearing: false;
+    readonly plannable: true;
+}, {
+    readonly verb: "status";
+    readonly flowId: "system/status";
+    readonly projection: "procedure";
+    readonly deployClass: false;
+    readonly planBearing: false;
+    readonly plannable: true;
+}, {
+    readonly verb: "cancel";
+    readonly flowId: "system/cancel";
+    readonly projection: "procedure";
+    readonly deployClass: false;
+    readonly planBearing: false;
+    readonly plannable: true;
+}, {
+    readonly verb: "approve";
+    readonly flowId: "system/approve";
+    readonly projection: "procedure";
+    readonly deployClass: false;
+    readonly planBearing: false;
+    readonly plannable: true;
+}, {
+    readonly verb: "deny";
+    readonly flowId: "system/deny";
+    readonly projection: "procedure";
+    readonly deployClass: false;
+    readonly planBearing: false;
+    readonly plannable: true;
+}, {
+    readonly verb: "signal";
+    readonly flowId: "system/signal";
+    readonly projection: "procedure";
+    readonly deployClass: false;
+    readonly planBearing: false;
+    readonly plannable: true;
+}, {
+    readonly verb: "gc";
+    readonly flowId: "system/gc";
+    readonly projection: "procedure";
+    readonly deployClass: false;
+    readonly planBearing: false;
+    readonly plannable: true;
+}, {
+    readonly verb: "replay";
+    readonly flowId: "system/replay";
+    readonly projection: "systemFlow";
+    readonly deployClass: false;
+    readonly planBearing: false;
+    readonly plannable: false;
+}, {
+    readonly verb: "add";
+    readonly flowId: "system/add";
+    readonly projection: "systemFlow";
+    readonly deployClass: false;
+    readonly planBearing: true;
+    readonly plannable: true;
+}, {
+    readonly verb: "remove";
+    readonly flowId: "system/remove";
+    readonly projection: "systemFlow";
+    readonly deployClass: false;
+    readonly planBearing: true;
+    readonly plannable: true;
+}, {
+    readonly verb: "eject";
+    readonly flowId: "system/eject";
+    readonly projection: "systemFlow";
+    readonly deployClass: false;
+    readonly planBearing: true;
+    readonly plannable: true;
+}, {
+    readonly verb: "test";
+    readonly flowId: "system/test";
+    readonly projection: "systemFlow";
+    readonly deployClass: false;
+    readonly planBearing: false;
+    readonly plannable: true;
+}, {
+    readonly verb: "init";
+    readonly flowId: "system/init";
+    readonly projection: "systemFlow";
+    readonly deployClass: false;
+    readonly planBearing: true;
+    readonly plannable: true;
+}, {
+    readonly verb: "doctor";
+    readonly flowId: "system/doctor";
+    readonly projection: "systemFlow";
+    readonly deployClass: false;
+    readonly planBearing: false;
+    readonly plannable: true;
+}, {
+    readonly verb: "migrate";
+    readonly flowId: "system/migrate";
+    readonly projection: "systemFlow";
+    readonly deployClass: false;
+    readonly planBearing: true;
+    readonly plannable: true;
+}, {
+    readonly verb: "target";
+    readonly flowId: "system/target";
+    readonly projection: "systemFlow";
+    readonly deployClass: true;
+    readonly planBearing: true;
+    readonly plannable: true;
+}, {
+    readonly verb: "docs";
+    readonly flowId: "system/docs";
+    readonly projection: "systemFlow";
+    readonly deployClass: false;
+    readonly planBearing: false;
+    readonly plannable: true;
+}];
+/**
+ * The catalog entries a control runtime may offer as flows.
+ *
+ * One list, so a composition that builds its own flow map (the CLI does) and
+ * the runtimes' own defaults cannot disagree about which reserved ids exist.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export declare const plannable: ReadonlyArray<SystemFlowEntry>;
+//# sourceMappingURL=SystemFlows.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SystemFlows.d.ts","sourceRoot":"","sources":["../../src/SystemFlows.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,UAAU,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,UAAU,EAAE,WAAW,GAAG,YAAY,CAAA;IAC/C,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwK+B,CAAA;AAEnD;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,EAAE,aAAa,CAAC,eAAe,CAA8C,CAAA"}

package/dist/esm/SystemFlows.js

@@ -0,0 +1,198 @@
+/**
+ * Reserved system-flow identifiers projected by the command-line interface.
+ *
+ * @since 0.1.0
+ */
+/**
+ * The authoritative command-line verb to reserved-flow map.
+ *
+ * `gc` is the retention verb: it resolves `@smthrs/engine-store`'s `retain`
+ * operation, which deletes aged terminal runs with their attempts, clock
+ * deadlines, deferred completions, journal entries, and time-travel archive
+ * rows. It is a procedure rather than a deploy-class system flow because it
+ * takes no plan and bears no approval envelope; the deletion is gated by the
+ * operator invoking it, and automatic retention stays opt-in.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export const catalog = [
+    {
+        verb: "plan",
+        flowId: "system/plan",
+        projection: "procedure",
+        deployClass: false,
+        planBearing: false,
+        plannable: true
+    },
+    {
+        verb: "run",
+        flowId: "system/run",
+        projection: "procedure",
+        deployClass: false,
+        planBearing: false,
+        plannable: true
+    },
+    {
+        verb: "release",
+        flowId: "system/release",
+        projection: "systemFlow",
+        deployClass: true,
+        planBearing: true,
+        plannable: true
+    },
+    {
+        verb: "serve",
+        flowId: "system/serve",
+        projection: "systemFlow",
+        deployClass: true,
+        planBearing: true,
+        plannable: true
+    },
+    { verb: "up", flowId: "system/up", projection: "systemFlow", deployClass: true, planBearing: true, plannable: true },
+    { verb: "ls", flowId: "system/ls", projection: "procedure", deployClass: false, planBearing: false, plannable: true },
+    { verb: "ps", flowId: "system/ps", projection: "procedure", deployClass: false, planBearing: false, plannable: true },
+    {
+        verb: "logs",
+        flowId: "system/logs",
+        projection: "procedure",
+        deployClass: false,
+        planBearing: false,
+        plannable: true
+    },
+    {
+        verb: "status",
+        flowId: "system/status",
+        projection: "procedure",
+        deployClass: false,
+        planBearing: false,
+        plannable: true
+    },
+    {
+        verb: "cancel",
+        flowId: "system/cancel",
+        projection: "procedure",
+        deployClass: false,
+        planBearing: false,
+        plannable: true
+    },
+    {
+        verb: "approve",
+        flowId: "system/approve",
+        projection: "procedure",
+        deployClass: false,
+        planBearing: false,
+        plannable: true
+    },
+    {
+        verb: "deny",
+        flowId: "system/deny",
+        projection: "procedure",
+        deployClass: false,
+        planBearing: false,
+        plannable: true
+    },
+    {
+        verb: "signal",
+        flowId: "system/signal",
+        projection: "procedure",
+        deployClass: false,
+        planBearing: false,
+        plannable: true
+    },
+    { verb: "gc", flowId: "system/gc", projection: "procedure", deployClass: false, planBearing: false, plannable: true },
+    {
+        verb: "replay",
+        flowId: "system/replay",
+        projection: "systemFlow",
+        deployClass: false,
+        planBearing: false,
+        plannable: false
+    },
+    {
+        verb: "add",
+        flowId: "system/add",
+        projection: "systemFlow",
+        deployClass: false,
+        planBearing: true,
+        plannable: true
+    },
+    {
+        verb: "remove",
+        flowId: "system/remove",
+        projection: "systemFlow",
+        deployClass: false,
+        planBearing: true,
+        plannable: true
+    },
+    {
+        verb: "eject",
+        flowId: "system/eject",
+        projection: "systemFlow",
+        deployClass: false,
+        planBearing: true,
+        plannable: true
+    },
+    {
+        verb: "test",
+        flowId: "system/test",
+        projection: "systemFlow",
+        deployClass: false,
+        planBearing: false,
+        plannable: true
+    },
+    {
+        verb: "init",
+        flowId: "system/init",
+        projection: "systemFlow",
+        deployClass: false,
+        planBearing: true,
+        plannable: true
+    },
+    {
+        verb: "doctor",
+        flowId: "system/doctor",
+        projection: "systemFlow",
+        deployClass: false,
+        planBearing: false,
+        plannable: true
+    },
+    {
+        verb: "migrate",
+        flowId: "system/migrate",
+        projection: "systemFlow",
+        deployClass: false,
+        planBearing: true,
+        plannable: true
+    },
+    {
+        // A build target declaring `approval: "required"`: its plan input is the
+        // target's label and revision digest, and the build planner runs it only
+        // once that plan is approved. The build executes it, never a control run.
+        verb: "target",
+        flowId: "system/target",
+        projection: "systemFlow",
+        deployClass: true,
+        planBearing: true,
+        plannable: true
+    },
+    {
+        verb: "docs",
+        flowId: "system/docs",
+        projection: "systemFlow",
+        deployClass: false,
+        planBearing: false,
+        plannable: true
+    }
+];
+/**
+ * The catalog entries a control runtime may offer as flows.
+ *
+ * One list, so a composition that builds its own flow map (the CLI does) and
+ * the runtimes' own defaults cannot disagree about which reserved ids exist.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export const plannable = catalog.filter((entry) => entry.plannable);
+//# sourceMappingURL=SystemFlows.js.map

package/dist/esm/SystemFlows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SystemFlows.js","sourceRoot":"","sources":["../../src/SystemFlows.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Reserved system-flow identifiers projected by the command-line interface.\n *\n * @since 0.1.0\n */\n\n/**\n * The projection metadata for one reserved system flow.\n *\n * @since 0.1.0\n * @category models\n */\nexport interface SystemFlowEntry {\n  readonly verb: string\n  readonly flowId: `system/${string}`\n  readonly projection: \"procedure\" | \"systemFlow\"\n  readonly deployClass: boolean\n  readonly planBearing: boolean\n  /**\n   * Whether a control plane may plan and run this reserved id.\n   *\n   * `false` means the row is command-line metadata and nothing else: the verb\n   * is named here so the binary can refuse it by name, and no runtime may\n   * offer it as a flow. `replay` was removed by the frozen rc.0 contract yet\n   * every runtime turned the whole catalog into plannable flows, so\n   * `plan({flowId: \"system/replay\"})` returned a real approval card and only a\n   * later `run` failed. A removed feature that half works is exactly what the\n   * contract forbids.\n   */\n  readonly plannable: boolean\n}\n\n/**\n * The authoritative command-line verb to reserved-flow map.\n *\n * `gc` is the retention verb: it resolves `@smthrs/engine-store`'s `retain`\n * operation, which deletes aged terminal runs with their attempts, clock\n * deadlines, deferred completions, journal entries, and time-travel archive\n * rows. It is a procedure rather than a deploy-class system flow because it\n * takes no plan and bears no approval envelope; the deletion is gated by the\n * operator invoking it, and automatic retention stays opt-in.\n *\n * @since 0.1.0\n * @category models\n */\nexport const catalog = [\n  {\n    verb: \"plan\",\n    flowId: \"system/plan\",\n    projection: \"procedure\",\n    deployClass: false,\n    planBearing: false,\n    plannable: true\n  },\n  {\n    verb: \"run\",\n    flowId: \"system/run\",\n    projection: \"procedure\",\n    deployClass: false,\n    planBearing: false,\n    plannable: true\n  },\n  {\n    verb: \"release\",\n    flowId: \"system/release\",\n    projection: \"systemFlow\",\n    deployClass: true,\n    planBearing: true,\n    plannable: true\n  },\n  {\n    verb: \"serve\",\n    flowId: \"system/serve\",\n    projection: \"systemFlow\",\n    deployClass: true,\n    planBearing: true,\n    plannable: true\n  },\n  { verb: \"up\", flowId: \"system/up\", projection: \"systemFlow\", deployClass: true, planBearing: true, plannable: true },\n  { verb: \"ls\", flowId: \"system/ls\", projection: \"procedure\", deployClass: false, planBearing: false, plannable: true },\n  { verb: \"ps\", flowId: \"system/ps\", projection: \"procedure\", deployClass: false, planBearing: false, plannable: true },\n  {\n    verb: \"logs\",\n    flowId: \"system/logs\",\n    projection: \"procedure\",\n    deployClass: false,\n    planBearing: false,\n    plannable: true\n  },\n  {\n    verb: \"status\",\n    flowId: \"system/status\",\n    projection: \"procedure\",\n    deployClass: false,\n    planBearing: false,\n    plannable: true\n  },\n  {\n    verb: \"cancel\",\n    flowId: \"system/cancel\",\n    projection: \"procedure\",\n    deployClass: false,\n    planBearing: false,\n    plannable: true\n  },\n  {\n    verb: \"approve\",\n    flowId: \"system/approve\",\n    projection: \"procedure\",\n    deployClass: false,\n    planBearing: false,\n    plannable: true\n  },\n  {\n    verb: \"deny\",\n    flowId: \"system/deny\",\n    projection: \"procedure\",\n    deployClass: false,\n    planBearing: false,\n    plannable: true\n  },\n  {\n    verb: \"signal\",\n    flowId: \"system/signal\",\n    projection: \"procedure\",\n    deployClass: false,\n    planBearing: false,\n    plannable: true\n  },\n  { verb: \"gc\", flowId: \"system/gc\", projection: \"procedure\", deployClass: false, planBearing: false, plannable: true },\n  {\n    verb: \"replay\",\n    flowId: \"system/replay\",\n    projection: \"systemFlow\",\n    deployClass: false,\n    planBearing: false,\n    plannable: false\n  },\n  {\n    verb: \"add\",\n    flowId: \"system/add\",\n    projection: \"systemFlow\",\n    deployClass: false,\n    planBearing: true,\n    plannable: true\n  },\n  {\n    verb: \"remove\",\n    flowId: \"system/remove\",\n    projection: \"systemFlow\",\n    deployClass: false,\n    planBearing: true,\n    plannable: true\n  },\n  {\n    verb: \"eject\",\n    flowId: \"system/eject\",\n    projection: \"systemFlow\",\n    deployClass: false,\n    planBearing: true,\n    plannable: true\n  },\n  {\n    verb: \"test\",\n    flowId: \"system/test\",\n    projection: \"systemFlow\",\n    deployClass: false,\n    planBearing: false,\n    plannable: true\n  },\n  {\n    verb: \"init\",\n    flowId: \"system/init\",\n    projection: \"systemFlow\",\n    deployClass: false,\n    planBearing: true,\n    plannable: true\n  },\n  {\n    verb: \"doctor\",\n    flowId: \"system/doctor\",\n    projection: \"systemFlow\",\n    deployClass: false,\n    planBearing: false,\n    plannable: true\n  },\n  {\n    verb: \"migrate\",\n    flowId: \"system/migrate\",\n    projection: \"systemFlow\",\n    deployClass: false,\n    planBearing: true,\n    plannable: true\n  },\n  {\n    // A build target declaring `approval: \"required\"`: its plan input is the\n    // target's label and revision digest, and the build planner runs it only\n    // once that plan is approved. The build executes it, never a control run.\n    verb: \"target\",\n    flowId: \"system/target\",\n    projection: \"systemFlow\",\n    deployClass: true,\n    planBearing: true,\n    plannable: true\n  },\n  {\n    verb: \"docs\",\n    flowId: \"system/docs\",\n    projection: \"systemFlow\",\n    deployClass: false,\n    planBearing: false,\n    plannable: true\n  }\n] as const satisfies ReadonlyArray<SystemFlowEntry>\n\n/**\n * The catalog entries a control runtime may offer as flows.\n *\n * One list, so a composition that builds its own flow map (the CLI does) and\n * the runtimes' own defaults cannot disagree about which reserved ids exist.\n *\n * @since 0.1.0\n * @category models\n */\nexport const plannable: ReadonlyArray<SystemFlowEntry> = catalog.filter((entry) => entry.plannable)\n"]}

package/dist/esm/WebCryptoCipher.d.ts

@@ -0,0 +1,49 @@
+/**
+ * AES-256-GCM credential encryption over the Web Crypto API.
+ *
+ * One adapter serves both hosts the project supports: `globalThis.crypto.subtle`
+ * is the browser's own API and has been Node's since v19, so this module
+ * imports nothing from `node:*` and still runs unmodified on the server. A host
+ * without Web Crypto, such as an old runtime or a locked-down worker, fails
+ * with the typed `Unavailable`, never a defect. A key that is not 32
+ * base64-encoded bytes fails with `InvalidInput`. A record that does not open
+ * fails with `PersistenceError` on operation `credential.open`, which names
+ * whether the stored nonce was malformed or the ciphertext failed
+ * authentication (a different key, changed metadata, or tampered bytes).
+ *
+ * The key is host-managed and supplied at layer construction. It is held as a
+ * non-extractable `CryptoKey`, so it cannot be read back out of the cipher, and
+ * it never reaches `CredentialStore`.
+ *
+ * @since 0.1.0
+ */
+import { Effect, Layer, Redacted } from "effect";
+import { InvalidInput, type Unavailable } from "./ControlError.ts";
+import * as CredentialCipher from "./CredentialCipher.ts";
+/**
+ * Host-managed key material for the cipher.
+ *
+ * `key` is 32 raw bytes, base64-encoded, held redacted so it cannot be printed
+ * or serialized by accident.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options {
+    readonly key: Redacted.Redacted<string>;
+}
+/**
+ * Imports the host key and constructs the cipher.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: (options: Options) => Effect.Effect<CredentialCipher.Service, Unavailable | InvalidInput>;
+/**
+ * Provides AES-256-GCM credential encryption under a host-managed key.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: (options: Options) => Layer.Layer<CredentialCipher.CredentialCipher, Unavailable | InvalidInput>;
+//# sourceMappingURL=WebCryptoCipher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WebCryptoCipher.d.ts","sourceRoot":"","sources":["../../src/WebCryptoCipher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAChD,OAAO,EAAE,YAAY,EAAoB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACpF,OAAO,KAAK,gBAAgB,MAAM,uBAAuB,CAAA;AA+DzD;;;;;;;;GAQG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;CACxC;AAED;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS,OAAO,KAAG,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,YAAY,CAoDtG,CAAA;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAChB,SAAS,OAAO,KACf,KAAK,CAAC,KAAK,CAAC,gBAAgB,CAAC,gBAAgB,EAAE,WAAW,GAAG,YAAY,CACZ,CAAA"}