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

package/dist/cjs/Monitor.js

@@ -0,0 +1,283 @@
+"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 Monitor_exports = {};
+__export(Monitor_exports, {
+  Health: () => Health,
+  attemptFinishedEventType: () => attemptFinishedEventType,
+  attemptStartedEventType: () => attemptStartedEventType,
+  beatEventType: () => beatEventType,
+  classify: () => classify,
+  healedEventType: () => healedEventType,
+  isBookkeepingEvent: () => isBookkeepingEvent,
+  remedyFor: () => remedyFor,
+  run: () => run
+});
+module.exports = __toCommonJS(Monitor_exports);
+var import_journal = require("@smthrs/journal");
+var import_effect = require("effect");
+var import_Control = require("./Control.js");
+var import_ControlError = require("./ControlError.js");
+var SubjectHealth = __toESM(require("./Health.js"), 1);
+const attemptStartedEventType = "flows.engine.attempt-started";
+const attemptFinishedEventType = "flows.engine.attempt-finished";
+const beatEventType = "control.monitor.beat";
+const healedEventType = "control.monitor.healed";
+const Health = SubjectHealth.HealthState;
+const defaultRoundBound = 32;
+const foldAttempt = (state, event) => {
+  if (event.kind === attemptStartedEventType) state.open += 1;
+  if (event.kind === attemptFinishedEventType) {
+    state.open -= 1;
+    const payload = event.payload;
+    state.failed = typeof payload === "object" && payload !== null && !Array.isArray(payload) && payload["state"] === "failed";
+  }
+};
+const classify = (observation) => {
+  const attempts = { open: 0, failed: false };
+  for (const event of observation.events) foldAttempt(attempts, event);
+  return classifyState(observation, attempts);
+};
+const classifyState = (observation, attempts) => {
+  const summary = observation.summary;
+  if (summary === void 0) return "unknown";
+  if (summary.status === "failed") return "failing";
+  if (summary.status === "completed" || summary.status === "cancelled") return "healthy";
+  if (summary.status === "waiting-approval") return "awaiting-human";
+  if (summary.status === "parked" && (summary.waitingReason === "approval" || summary.waitingReason === void 0)) {
+    return "awaiting-human";
+  }
+  if (SubjectHealth.waitReason(summary.status, summary.waitingReason) !== void 0) return "healthy";
+  const bound = observation.roundBound ?? defaultRoundBound;
+  if (summary.roundOrdinal !== void 0 && summary.roundOrdinal >= bound) return "runaway-loop";
+  if (attempts.failed) return "failing";
+  if (!observation.semanticProgress && observation.beatsWithoutProgress >= observation.stallBeats) {
+    return attempts.open > 0 ? "wedged-node" : "stalled";
+  }
+  return "healthy";
+};
+const remedyFor = (health) => {
+  switch (health) {
+    case "stalled":
+    case "wedged-node":
+      return "resume";
+    case "failing":
+    case "runaway-loop":
+      return "cancel";
+    default:
+      return "none";
+  }
+};
+const summaryOf = (runId) => import_effect.Effect.flatMap(import_Control.Control, (control) => control.list({ _tag: "runs", filters: { runId } }).pipe(
+  import_effect.Effect.map((listed) => listed._tag === "runs" ? listed.items[0] : void 0)
+));
+const terminal = (summary) => summary !== void 0 && (summary.status === "completed" || summary.status === "failed" || summary.status === "cancelled");
+const run = (options) => import_effect.Effect.gen(function* () {
+  const control = yield* import_Control.Control;
+  const journal = yield* import_journal.Journal.Journal;
+  const intervalMs = options.intervalMs ?? options.healthCheck?.policy.intervalMs ?? 1e3;
+  let consecutiveProbeFailures = 0;
+  let lastPublished;
+  const maxChecks = options.maxChecks ?? 10;
+  const stallBeats = options.stallBeats ?? 3;
+  const autoHeal = options.autoHeal ?? [];
+  const monitorId = options.monitorId ?? "default";
+  const heal = options.heal ?? ((input) => input.remedy === "resume" ? control.resume({
+    runId: input.runId,
+    idempotencyKey: `monitor:${monitorId}:resume:${input.runId}:${input.beat}`
+  }) : control.cancel({
+    runId: input.runId,
+    reason: `monitor:${input.health}`,
+    idempotencyKey: `monitor:${monitorId}:cancel:${input.runId}:${input.beat}`
+  }));
+  const emit = (eventType, payload, operation) => {
+    const unrecorded = (cause) => new import_ControlError.PersistenceError({
+      operation: eventType,
+      message: `Failed to record ${operation} for ${options.runId}`,
+      cause
+    });
+    return import_effect.Effect.try({
+      try: () => new import_journal.JournalEvent.Input({
+        runId: import_journal.JournalEvent.RunId.make(options.runId),
+        sourceId: import_journal.JournalEvent.SourceId.make(`/control/monitor/${monitorId}`),
+        eventType,
+        payload: { runId: options.runId, monitorId, ...payload }
+      }),
+      catch: unrecorded
+    }).pipe(
+      import_effect.Effect.flatMap((input) => import_effect.Effect.mapError(journal.emitDurableUnfenced(input), unrecorded)),
+      import_effect.Effect.asVoid
+    );
+  };
+  const record = (beat, remedy) => emit(
+    beatEventType,
+    {
+      beat: beat.beat,
+      health: beat.health,
+      sequence: beat.sequence,
+      ...remedy === "none" ? {} : { remedy }
+    },
+    `monitor beat ${beat.beat}`
+  );
+  const recordHealed = (beat, remedy, receipt) => emit(
+    healedEventType,
+    { beat: beat.beat, health: beat.health, healed: remedy, receipt: receipt._tag },
+    `monitor heal ${beat.beat}`
+  );
+  const beats = [];
+  let beatsWithoutProgress = 0;
+  let lastSequence = -1;
+  let checkpoint = {};
+  const attempts = { open: 0, failed: false };
+  let sequence = -1;
+  for (let beat = 0; beat < maxChecks; beat += 1) {
+    if (beat > 0 && intervalMs > 0) {
+      yield* import_effect.Effect.sleep(import_effect.Duration.millis(
+        options.healthCheck === void 0 ? intervalMs : SubjectHealth.nextDelay(options.healthCheck.policy, consecutiveProbeFailures)
+      ));
+    }
+    const summary = yield* summaryOf(options.runId);
+    const newEvents = [];
+    const sinceCursor = Math.max(0, sequence);
+    yield* control.watch({ runId: options.runId, follow: false, ...checkpoint }).pipe(
+      import_effect.Stream.runForEach(
+        (event) => import_effect.Effect.sync(() => {
+          checkpoint = event.cursor === void 0 ? { afterSequence: event.sequence } : { afterCursor: event.cursor };
+          if (isBookkeepingEvent(event.kind)) return;
+          newEvents.push(event);
+          if (newEvents.length > 256) newEvents.shift();
+          sequence = event.sequence;
+          foldAttempt(attempts, event);
+        })
+      )
+    );
+    beatsWithoutProgress = sequence === lastSequence ? beatsWithoutProgress + 1 : 0;
+    lastSequence = sequence;
+    const health = classifyState({
+      ...summary === void 0 ? {} : { summary },
+      beatsWithoutProgress,
+      stallBeats,
+      ...options.roundBound === void 0 ? {} : { roundBound: options.roundBound }
+    }, attempts);
+    if (options.healthCheck !== void 0 && summary !== void 0) {
+      const check = options.healthCheck;
+      const subjectId = `run:${options.runId}`;
+      const incarnation = SubjectHealth.runIncarnation(summary);
+      const probe = SubjectHealth.evaluate(check, {
+        subjectId,
+        state: summary.status,
+        summary,
+        events: newEvents,
+        sinceCursor
+      }, { monitorId, incarnation, evidenceSeq: Math.max(0, sequence) });
+      let observation = yield* options.withProbePermit?.(probe) ?? probe;
+      const current = yield* summaryOf(options.runId);
+      if (current === void 0 || SubjectHealth.runIncarnation(current) !== incarnation) {
+        observation = { ...observation, outcome: "discarded", report: void 0, reason: "owner-changed" };
+      }
+      consecutiveProbeFailures = observation.outcome === "ok" ? 0 : consecutiveProbeFailures + 1;
+      const semanticProgress = observation.outcome === "ok" && observation.report?.activity === "working";
+      const baseHealth = classifyState({
+        summary,
+        beatsWithoutProgress,
+        stallBeats,
+        roundBound: options.roundBound,
+        semanticProgress
+      }, attempts);
+      observation = { ...observation, baseHealth };
+      const status = SubjectHealth.rollup({
+        subjectId,
+        state: summary.status,
+        incarnation,
+        waitingReason: summary.waitingReason,
+        baseHealth,
+        latest: { observation, sequence: 0 },
+        now: observation.observedAt,
+        updatedAt: summary.updatedAt
+      });
+      const changed = lastPublished === void 0 || lastPublished.incarnation !== observation.incarnation || lastPublished.outcome !== observation.outcome || lastPublished.baseHealth !== observation.baseHealth || lastPublished.evidenceSeq !== observation.evidenceSeq || JSON.stringify(lastPublished.report) !== JSON.stringify(observation.report) || lastPublished.reason !== observation.reason;
+      if (changed || observation.observedAt >= lastPublished.observedAt + check.policy.ttlMs / 2) {
+        yield* emit(SubjectHealth.statusObservedEventType, {
+          ...observation,
+          status: summary.status,
+          health: status.health,
+          activity: status.activity,
+          attention: status.attention,
+          freshness: status.freshness,
+          waitingReason: summary.waitingReason ?? ""
+        }, "health observation");
+        lastPublished = observation;
+      }
+    }
+    const remedy = autoHeal.includes(health) ? remedyFor(health) : "none";
+    const observed = { beat, health, sequence };
+    if (options.recordBeats !== false) yield* record(observed, remedy);
+    if (remedy === "none") {
+      beats.push(observed);
+    } else {
+      const receipt = yield* heal({ runId: options.runId, health, remedy, beat }).pipe(
+        // A remedy that fails must not abort the run of beats: the monitor
+        // is an unattended loop, and one failing heal leaves every other
+        // beat — and every other run it would have observed — unwatched.
+        // The failure is logged with the beat it failed on, and the beat is
+        // recorded without `healed` or `receipt`, exactly as a remedy the
+        // monitor never got to apply reports.
+        import_effect.Effect.catch(
+          (failure) => import_effect.Effect.annotateLogs(
+            import_effect.Effect.logWarning("A monitor remedy failed and was skipped"),
+            { runId: options.runId, beat, health, remedy, cause: String(failure) }
+          ).pipe(import_effect.Effect.as(void 0))
+        )
+      );
+      if (receipt === void 0) {
+        beats.push(observed);
+      } else {
+        const applied = receipt._tag === "Accepted" || receipt._tag === "AlreadyApplied";
+        if (applied) {
+          yield* recordHealed(observed, remedy, receipt);
+          beatsWithoutProgress = 0;
+        }
+        beats.push(applied ? { ...observed, healed: remedy, receipt } : { ...observed, receipt });
+        if (receipt._tag === "Terminal") break;
+      }
+    }
+    if (options.retainBeats !== void 0 && beats.length > options.retainBeats) {
+      beats.splice(0, beats.length - options.retainBeats);
+    }
+    if (terminal(summary)) {
+      break;
+    }
+  }
+  return {
+    runId: options.runId,
+    beats,
+    health: beats[beats.length - 1]?.health ?? "unknown"
+  };
+});
+const isBookkeepingEvent = (kind) => kind.startsWith("control.monitor.") || kind.startsWith("control.status.") || kind.startsWith("flows.alerts.") || kind.startsWith("flows.notifications.") || kind.startsWith("flows.notification.");
+//# sourceMappingURL=Monitor.js.map

package/dist/cjs/Monitor.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Monitor.ts"],
+  "sourcesContent": ["/**\n * Run health over the control plane: what a run's state means, and what to do\n * about it.\n *\n * A control plane answers \"what is this run doing\". A monitor answers the\n * question after it \u2014 \"is that all right, and if not, what now\" \u2014 and the two\n * are deliberately separate modules. {@link classify} is a pure function of\n * one observation, so the vocabulary an operator reads on a dashboard is the\n * same one a heal loop branches on and the same one a test can enumerate.\n * {@link run} is the loop that beats over `Control` and journals what it saw.\n *\n * The classification is decided from durable evidence only: the run summary\n * the control plane projects, and the journal entries `watch` replays. Nothing\n * here reads an in-process fiber, which is what makes a monitor able to watch\n * a run in another process at all.\n *\n * @since 0.1.0\n */\n\nimport { Journal, JournalEvent } from \"@smthrs/journal\"\nimport { Duration, Effect, Stream } from \"effect\"\nimport { Control } from \"./Control.ts\"\nimport type { ControlError } from \"./ControlError.ts\"\nimport { PersistenceError } from \"./ControlError.ts\"\nimport type { ControlEvent, Receipt, RunId, RunSummary, WatchFilter } from \"./ControlSchema.ts\"\nimport * as SubjectHealth from \"./Health.ts\"\n\n/**\n * The journal event type the engine records when an action attempt starts.\n *\n * Named as a string rather than imported, exactly as in `Lineage`: a monitor\n * reads journals, not engines.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const attemptStartedEventType = \"flows.engine.attempt-started\"\n\n/**\n * The journal event type the engine records when an action attempt settles.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const attemptFinishedEventType = \"flows.engine.attempt-finished\"\n\n/**\n * The journal event type one monitor beat is recorded under.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const beatEventType = \"control.monitor.beat\"\n\n/**\n * The journal event type one applied remedy is recorded under.\n *\n * A beat and a heal are two records because they are two facts, and only one\n * of them is true before the remedy runs. A single record carrying `healed`\n * has to be written either before the remedy \u2014 leaving durable evidence of a\n * heal that a crash one instruction later never performed \u2014 or after it, which\n * loses the evidence of what a monitor decided when the remedy is what killed\n * it. Splitting them keeps both.\n *\n * @category constants\n * @since 0.1.0\n */\nexport const healedEventType = \"control.monitor.healed\"\n\n/**\n * What a run looks like to a monitor.\n *\n * `healthy` covers both \"moving\" and \"finished\": a completed run needs nothing\n * done to it, and neither does one that is making progress. The other six name\n * a specific thing that is wrong, because a heal that cannot tell them apart\n * would resume a run that is waiting for a human.\n *\n * @category models\n * @since 0.1.0\n */\nexport const Health = SubjectHealth.HealthState\n\n/**\n * What a run looks like to a monitor.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Health = typeof Health.Type\n\n/**\n * Everything one classification is decided from.\n *\n * `events` is the run's journal as `watch` projects it, oldest first.\n * `beatsWithoutProgress` counts consecutive beats that added no entry, and\n * `stallBeats` is how many of those make a stall. Splitting the count from the\n * threshold is what lets the same pure function serve a monitor that beats\n * every second and one that beats every hour.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Observation {\n  /** The run's projection, or nothing when the control plane has no such run. */\n  readonly summary?: RunSummary | undefined\n  readonly events: ReadonlyArray<ControlEvent>\n  readonly beatsWithoutProgress: number\n  readonly stallBeats: number\n  /**\n   * The trampoline round at which a lineage stops being a loop and starts\n   * being a runaway. A run past it is looping without converging.\n   */\n  readonly roundBound?: number | undefined\n  /** Fresh, explicitly reported semantic work; never inferred from bytes or monitor events. */\n  readonly semanticProgress?: boolean | undefined\n}\n\n/** How many rounds a trampoline may take before a monitor calls it runaway. */\nconst defaultRoundBound = 32\n\ninterface AttemptState {\n  open: number\n  failed: boolean\n}\n\nconst foldAttempt = (state: AttemptState, event: ControlEvent): void => {\n  if (event.kind === attemptStartedEventType) state.open += 1\n  if (event.kind === attemptFinishedEventType) {\n    state.open -= 1\n    const payload = event.payload\n    state.failed = typeof payload === \"object\" && payload !== null && !Array.isArray(payload) &&\n      (payload as { readonly state?: unknown })[\"state\"] === \"failed\"\n  }\n}\n\n/**\n * Decides what a run's state means.\n *\n * The order is the order an operator would read it in, and each rule earns its\n * place by naming a different response:\n *\n * | Condition | Health | Because |\n * | --- | --- | --- |\n * | No summary | `unknown` | Nothing to say, and nothing to do. |\n * | `failed` | `failing` | The run itself reported the failure. |\n * | `completed`, `cancelled` | `healthy` | A finished run needs nothing. |\n * | `waiting-approval`, or parked on `approval` | `awaiting-human` | A human owes it an answer; no machine can supply one. |\n * | Parked with no waiting reason | `awaiting-human` | Only an operator's own park writes no waiting reason, so a person stopped it and a person restarts it. |\n * | `roundOrdinal` at or past the bound | `runaway-loop` | The lineage is looping without converging. |\n * | The last settled attempt failed | `failing` | The run is still alive but its work is not landing. |\n * | No progress for `stallBeats`, an attempt open | `wedged-node` | One attempt started and never settled: the work is stuck, not the run. |\n * | No progress for `stallBeats` | `stalled` | Nothing is happening and nothing is in flight. |\n * | Anything else | `healthy` | Entries are still arriving. |\n *\n * `awaiting-human` deliberately outranks `failing`: a run parked for approval\n * after a failed attempt is waiting for a person, and resuming or cancelling\n * it would take the decision away from them.\n *\n * A park with no reason is the same case. The engine names every park it makes\n * \u2014 `event`, `approval`, `timer`, `quota`, `released` \u2014 so a parked run whose\n * `waitingReason` is absent was parked by an operator through\n * `ControlRuntime.writeStatus`. Calling that a stall and resuming it would undo\n * a deliberate act, which is the worst thing an unattended heal loop can do.\n *\n * @param observation what the beat saw\n * @category projections\n * @since 0.1.0\n */\nexport const classify = (observation: Observation): Health => {\n  const attempts: AttemptState = { open: 0, failed: false }\n  for (const event of observation.events) foldAttempt(attempts, event)\n  return classifyState(observation, attempts)\n}\n\nconst classifyState = (observation: Omit<Observation, \"events\">, attempts: AttemptState): Health => {\n  const summary = observation.summary\n  if (summary === undefined) return \"unknown\"\n  if (summary.status === \"failed\") return \"failing\"\n  if (summary.status === \"completed\" || summary.status === \"cancelled\") return \"healthy\"\n  if (summary.status === \"waiting-approval\") return \"awaiting-human\"\n  if (summary.status === \"parked\" && (summary.waitingReason === \"approval\" || summary.waitingReason === undefined)) {\n    return \"awaiting-human\"\n  }\n  if (SubjectHealth.waitReason(summary.status, summary.waitingReason) !== undefined) return \"healthy\"\n  const bound = observation.roundBound ?? defaultRoundBound\n  if (summary.roundOrdinal !== undefined && summary.roundOrdinal >= bound) return \"runaway-loop\"\n  if (attempts.failed) return \"failing\"\n  if (!observation.semanticProgress && observation.beatsWithoutProgress >= observation.stallBeats) {\n    return attempts.open > 0 ? \"wedged-node\" : \"stalled\"\n  }\n  return \"healthy\"\n}\n\n/**\n * What a monitor does about one unhealthy run.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Remedy = \"resume\" | \"cancel\" | \"none\"\n\n/**\n * The remedy a health warrants, before `autoHeal` decides whether to apply it.\n *\n * A stalled or wedged run is one nobody is driving, and a resume claims it. A\n * failing or runaway run is one that will not get better by being driven\n * harder. Everything else is left alone.\n *\n * @param health what the beat classified\n * @category projections\n * @since 0.1.0\n */\nexport const remedyFor = (health: Health): Remedy => {\n  switch (health) {\n    case \"stalled\":\n    case \"wedged-node\":\n      return \"resume\"\n    case \"failing\":\n    case \"runaway-loop\":\n      return \"cancel\"\n    default:\n      return \"none\"\n  }\n}\n\n/**\n * One beat of a monitor.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Beat {\n  /** Which beat this was, counting from zero. */\n  readonly beat: number\n  readonly health: Health\n  /** The newest journal sequence the run had, ignoring the monitor's own records. */\n  readonly sequence: number\n  /**\n   * The remedy that ran and returned, absent when none did.\n   *\n   * Present only after the heal succeeded, which is also when\n   * `control.monitor.healed` is journaled. A beat that decided on a remedy the\n   * monitor never got to apply reports nothing here.\n   */\n  readonly healed?: Remedy | undefined\n  /** The receipt the remedy returned, absent when none was applied. */\n  readonly receipt?: Receipt | undefined\n}\n\n/**\n * What a monitor found.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Report {\n  readonly runId: RunId\n  readonly beats: ReadonlyArray<Beat>\n  /** The last beat's health, or `unknown` when no beat ran. */\n  readonly health: Health\n}\n\n/**\n * How a monitor beats.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Options {\n  readonly runId: RunId\n  /** Optional configured observational checker; checker results never authorize a remedy. */\n  readonly healthCheck?: SubjectHealth.ResolvedCheck | undefined\n  /** Shared host admission limit around probes. */\n  readonly withProbePermit?: (<A>(effect: Effect.Effect<A>) => Effect.Effect<A>) | undefined\n  /** Bounded retained beat history for long-lived host monitoring. */\n  readonly retainBeats?: number | undefined\n  /** Hosts with structured status observations omit redundant legacy heartbeat records. */\n  readonly recordBeats?: boolean | undefined\n  /**\n   * Who is watching. Defaults to `default`.\n   *\n   * It reaches the journal twice: as the source of every record this monitor\n   * writes, and as `monitorId` in each payload. Two monitors pointed at one\n   * run both beat and both remedy \u2014 nothing on the control plane leases a run\n   * to one watcher \u2014 so the identity is what makes their evidence tellable\n   * apart, and what keeps their remedies on separate idempotency keys.\n   */\n  readonly monitorId?: string | undefined\n  /** How long to wait between beats. Defaults to one second. */\n  readonly intervalMs?: number | undefined\n  /** How many beats to take before reporting. Defaults to ten. */\n  readonly maxChecks?: number | undefined\n  /** How many beats without progress make a stall. Defaults to three. */\n  readonly stallBeats?: number | undefined\n  /** The round at which a trampoline is a runaway. Defaults to 32. */\n  readonly roundBound?: number | undefined\n  /** Which healths the monitor is allowed to act on. Defaults to none. */\n  readonly autoHeal?: ReadonlyArray<Health> | undefined\n  /**\n   * What to do about an unhealthy run. Defaults to `Control.resume` and\n   * `Control.cancel` per {@link remedyFor}.\n   *\n   * A heal that fails does not abort the monitor: the failure is logged, the\n   * beat is recorded without `healed` or `receipt`, and the loop moves to the\n   * next beat, where the stall evidence still stands and the remedy is\n   * retried under that beat's own idempotency key.\n   */\n  readonly heal?: (\n    input: { readonly runId: RunId; readonly health: Health; readonly remedy: Remedy; readonly beat: number }\n  ) => Effect.Effect<Receipt, ControlError>\n}\n\nconst summaryOf = (runId: RunId): Effect.Effect<RunSummary | undefined, ControlError, Control> =>\n  Effect.flatMap(Control, (control) =>\n    control.list({ _tag: \"runs\", filters: { runId } }).pipe(\n      Effect.map((listed) => listed._tag === \"runs\" ? listed.items[0] : undefined)\n    ))\n\nconst terminal = (summary: RunSummary | undefined): boolean =>\n  summary !== undefined &&\n  (summary.status === \"completed\" || summary.status === \"failed\" || summary.status === \"cancelled\")\n\n/**\n * Watches one run and, when told to, heals it.\n *\n * The loop stops early on a terminal run, because a finished run has nothing\n * left to observe and beating at it would fill its journal with heartbeats.\n * Otherwise it takes `maxChecks` beats and reports what it saw.\n *\n * Every beat is journaled as `control.monitor.beat` before any remedy is\n * applied, carrying the `remedy` it is about to attempt, so a monitor that\n * crashes mid-heal leaves the evidence of what it decided. The remedy itself\n * is journaled separately as `control.monitor.healed`, and only once the heal\n * returned a receipt: a heal that failed, or a process that died running one,\n * must not leave a durable record saying the run was healed.\n *\n * `autoHeal` is empty by default. A monitor that healed by default would be a\n * monitor that cancels a run the first time it looks at one, which is the\n * wrong default for a thing an operator points at production.\n *\n * Nothing here leases the run. Two monitors on one run both beat and both\n * remedy, so a remedy has to be idempotent on the control plane \u2014 which the\n * two defaults are, through `Control.resume` and `Control.cancel`\n * idempotency keys that name the monitor, the run, and the beat. A custom\n * `heal` owes the same property.\n *\n * @param options how to beat and what to heal\n * @category constructors\n * @since 0.1.0\n */\nexport const run = (\n  options: Options\n): Effect.Effect<Report, ControlError, Control | Journal.Journal> =>\n  Effect.gen(function*() {\n    const control = yield* Control\n    const journal = yield* Journal.Journal\n    const intervalMs = options.intervalMs ?? options.healthCheck?.policy.intervalMs ?? 1_000\n    let consecutiveProbeFailures = 0\n    let lastPublished: SubjectHealth.HealthObservation | undefined\n    const maxChecks = options.maxChecks ?? 10\n    const stallBeats = options.stallBeats ?? 3\n    const autoHeal = options.autoHeal ?? []\n    const monitorId = options.monitorId ?? \"default\"\n    const heal = options.heal ?? ((input) =>\n      input.remedy === \"resume\"\n        ? control.resume({\n          runId: input.runId,\n          idempotencyKey: `monitor:${monitorId}:resume:${input.runId}:${input.beat}`\n        })\n        : control.cancel({\n          runId: input.runId,\n          reason: `monitor:${input.health}`,\n          idempotencyKey: `monitor:${monitorId}:cancel:${input.runId}:${input.beat}`\n        }))\n\n    const emit = (\n      eventType: string,\n      payload: Record<string, unknown>,\n      operation: string\n    ): Effect.Effect<void, ControlError> => {\n      const unrecorded = (cause: unknown) =>\n        new PersistenceError({\n          operation: eventType,\n          message: `Failed to record ${operation} for ${options.runId}`,\n          cause\n        })\n      // The record is BUILT inside the failure channel, not before it.\n      // `JournalEvent.RunId`/`SourceId` refuse an identifier the store cannot\n      // tell apart from another one \u2014 a lone UTF-16 surrogate, an embedded NUL\n      // \u2014 by THROWING, and `monitorId` reaches here from an operator's flag. A\n      // thrown constructor is a defect, which the RPC boundary reports as an\n      // opaque `TransportError` and a caller cannot handle; a beat whose record\n      // cannot be built is the same event as a beat whose record cannot be\n      // appended, so both fail as `PersistenceError` naming the record.\n      return Effect.try({\n        try: () =>\n          new JournalEvent.Input({\n            runId: JournalEvent.RunId.make(options.runId),\n            sourceId: JournalEvent.SourceId.make(`/control/monitor/${monitorId}`),\n            eventType,\n            payload: { runId: options.runId, monitorId, ...payload }\n          }),\n        catch: unrecorded\n      }).pipe(\n        Effect.flatMap((input) => Effect.mapError(journal.emitDurableUnfenced(input), unrecorded)),\n        Effect.asVoid\n      )\n    }\n\n    /** What the beat saw, and what it is about to do about it. */\n    const record = (beat: Beat, remedy: Remedy): Effect.Effect<void, ControlError> =>\n      emit(\n        beatEventType,\n        {\n          beat: beat.beat,\n          health: beat.health,\n          sequence: beat.sequence,\n          ...(remedy === \"none\" ? {} : { remedy })\n        },\n        `monitor beat ${beat.beat}`\n      )\n\n    /** What the remedy did, once it returned. */\n    const recordHealed = (\n      beat: Beat,\n      remedy: Remedy,\n      receipt: Receipt\n    ): Effect.Effect<void, ControlError> =>\n      emit(\n        healedEventType,\n        { beat: beat.beat, health: beat.health, healed: remedy, receipt: receipt._tag },\n        `monitor heal ${beat.beat}`\n      )\n\n    const beats: Array<Beat> = []\n    let beatsWithoutProgress = 0\n    let lastSequence = -1\n    let checkpoint: Pick<WatchFilter, \"afterCursor\" | \"afterSequence\"> = {}\n    const attempts: AttemptState = { open: 0, failed: false }\n    let sequence = -1\n    for (let beat = 0; beat < maxChecks; beat += 1) {\n      if (beat > 0 && intervalMs > 0) {\n        yield* Effect.sleep(Duration.millis(\n          options.healthCheck === undefined\n            ? intervalMs\n            : SubjectHealth.nextDelay(options.healthCheck.policy, consecutiveProbeFailures)\n        ))\n      }\n      const summary = yield* summaryOf(options.runId)\n      const newEvents: Array<ControlEvent> = []\n      const sinceCursor = Math.max(0, sequence)\n      yield* control.watch({ runId: options.runId, follow: false, ...checkpoint }).pipe(\n        Stream.runForEach((event) =>\n          Effect.sync(() => {\n            // Advance over bookkeeping too, but never count it as run progress.\n            checkpoint = event.cursor === undefined\n              ? { afterSequence: event.sequence }\n              : { afterCursor: event.cursor }\n            if (isBookkeepingEvent(event.kind)) return\n            newEvents.push(event)\n            if (newEvents.length > 256) newEvents.shift()\n            sequence = event.sequence\n            foldAttempt(attempts, event)\n          })\n        )\n      )\n      beatsWithoutProgress = sequence === lastSequence ? beatsWithoutProgress + 1 : 0\n      lastSequence = sequence\n      const health = classifyState({\n        ...(summary === undefined ? {} : { summary }),\n        beatsWithoutProgress,\n        stallBeats,\n        ...(options.roundBound === undefined ? {} : { roundBound: options.roundBound })\n      }, attempts)\n      if (options.healthCheck !== undefined && summary !== undefined) {\n        const check = options.healthCheck\n        const subjectId = `run:${options.runId}`\n        const incarnation = SubjectHealth.runIncarnation(summary)\n        const probe = SubjectHealth.evaluate(check, {\n          subjectId,\n          state: summary.status,\n          summary,\n          events: newEvents,\n          sinceCursor\n        }, { monitorId, incarnation, evidenceSeq: Math.max(0, sequence) })\n        let observation = yield* (options.withProbePermit?.(probe) ?? probe)\n        const current = yield* summaryOf(options.runId)\n        if (current === undefined || SubjectHealth.runIncarnation(current) !== incarnation) {\n          observation = { ...observation, outcome: \"discarded\", report: undefined, reason: \"owner-changed\" }\n        }\n        consecutiveProbeFailures = observation.outcome === \"ok\" ? 0 : consecutiveProbeFailures + 1\n        const semanticProgress = observation.outcome === \"ok\" && observation.report?.activity === \"working\"\n        const baseHealth = classifyState({\n          summary,\n          beatsWithoutProgress,\n          stallBeats,\n          roundBound: options.roundBound,\n          semanticProgress\n        }, attempts)\n        observation = { ...observation, baseHealth }\n        const status = SubjectHealth.rollup({\n          subjectId,\n          state: summary.status,\n          incarnation,\n          waitingReason: summary.waitingReason,\n          baseHealth,\n          latest: { observation, sequence: 0 },\n          now: observation.observedAt,\n          updatedAt: summary.updatedAt\n        })\n        const changed = lastPublished === undefined || lastPublished.incarnation !== observation.incarnation ||\n          lastPublished.outcome !== observation.outcome || lastPublished.baseHealth !== observation.baseHealth ||\n          lastPublished.evidenceSeq !== observation.evidenceSeq ||\n          JSON.stringify(lastPublished.report) !== JSON.stringify(observation.report) ||\n          lastPublished.reason !== observation.reason\n        // Renew before expiry, but do not fill the journal with identical per-probe records.\n        if (changed || observation.observedAt >= lastPublished!.observedAt + check.policy.ttlMs / 2) {\n          yield* emit(SubjectHealth.statusObservedEventType, {\n            ...observation,\n            status: summary.status,\n            health: status.health,\n            activity: status.activity,\n            attention: status.attention,\n            freshness: status.freshness,\n            waitingReason: summary.waitingReason ?? \"\"\n          }, \"health observation\")\n          lastPublished = observation\n        }\n      }\n      // Checker output is observational and never participates in remedy authorization.\n      const remedy = autoHeal.includes(health) ? remedyFor(health) : \"none\"\n      const observed: Beat = { beat, health, sequence }\n      if (options.recordBeats !== false) yield* record(observed, remedy)\n      if (remedy === \"none\") {\n        beats.push(observed)\n      } else {\n        const receipt = yield* heal({ runId: options.runId, health, remedy, beat }).pipe(\n          // A remedy that fails must not abort the run of beats: the monitor\n          // is an unattended loop, and one failing heal leaves every other\n          // beat \u2014 and every other run it would have observed \u2014 unwatched.\n          // The failure is logged with the beat it failed on, and the beat is\n          // recorded without `healed` or `receipt`, exactly as a remedy the\n          // monitor never got to apply reports.\n          Effect.catch((failure) =>\n            Effect.annotateLogs(\n              Effect.logWarning(\"A monitor remedy failed and was skipped\"),\n              { runId: options.runId, beat, health, remedy, cause: String(failure) }\n            ).pipe(Effect.as(undefined))\n          )\n        )\n        if (receipt === undefined) {\n          // The stall evidence stands: nothing provably moved the run, so the\n          // next beat compares against the same progress mark and the remedy\n          // is retried with the beat's own idempotency key.\n          beats.push(observed)\n        } else {\n          // A remedy that returned is not a remedy that was applied. `Terminal`\n          // says the run had already settled, so nothing was healed; `Conflict`\n          // says the key belonged to another mutation, so this monitor's remedy\n          // never ran. Recording either as `healed` claimed something that did\n          // not happen, and resetting the stall count on either erased the\n          // evidence the next beat needs to notice the run is still stuck.\n          const applied = receipt._tag === \"Accepted\" || receipt._tag === \"AlreadyApplied\"\n          if (applied) {\n            // Journaled here and not a line earlier: `healed` is a claim about\n            // something that happened, and until the receipt came back it had not.\n            yield* recordHealed(observed, remedy, receipt)\n            // The heal moved the run, so the next beat compares against a run\n            // that has changed. Counting the beats before it as stall evidence\n            // again would heal a second time for the same stall.\n            beatsWithoutProgress = 0\n          }\n          beats.push(applied ? { ...observed, healed: remedy, receipt } : { ...observed, receipt })\n          // A remedy that answered `Terminal` observed the run settle. The loop\n          // ends on the same evidence a terminal summary ends it on, rather than\n          // beating against a run nothing can move.\n          if (receipt._tag === \"Terminal\") break\n        }\n      }\n      if (options.retainBeats !== undefined && beats.length > options.retainBeats) {\n        beats.splice(0, beats.length - options.retainBeats)\n      }\n      if (terminal(summary)) {\n        break\n      }\n    }\n    return {\n      runId: options.runId,\n      beats,\n      health: beats[beats.length - 1]?.health ?? \"unknown\"\n    }\n  })\n\n/** Observer and notification bookkeeping is never execution progress.\n * @category predicates\n * @since 1.0.0\n */\nexport const isBookkeepingEvent = (kind: string): boolean =>\n  kind.startsWith(\"control.monitor.\") || kind.startsWith(\"control.status.\") ||\n  kind.startsWith(\"flows.alerts.\") || kind.startsWith(\"flows.notifications.\") || kind.startsWith(\"flows.notification.\")\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAmBA,qBAAsC;AACtC,oBAAyC;AACzC,qBAAwB;AAExB,0BAAiC;AAEjC,oBAA+B;AAWxB,MAAM,0BAA0B;AAQhC,MAAM,2BAA2B;AAQjC,MAAM,gBAAgB;AAetB,MAAM,kBAAkB;AAaxB,MAAM,SAAS,cAAc;AAsCpC,MAAM,oBAAoB;AAO1B,MAAM,cAAc,CAAC,OAAqB,UAA8B;AACtE,MAAI,MAAM,SAAS,wBAAyB,OAAM,QAAQ;AAC1D,MAAI,MAAM,SAAS,0BAA0B;AAC3C,UAAM,QAAQ;AACd,UAAM,UAAU,MAAM;AACtB,UAAM,SAAS,OAAO,YAAY,YAAY,YAAY,QAAQ,CAAC,MAAM,QAAQ,OAAO,KACrF,QAAyC,OAAO,MAAM;AAAA,EAC3D;AACF;AAmCO,MAAM,WAAW,CAAC,gBAAqC;AAC5D,QAAM,WAAyB,EAAE,MAAM,GAAG,QAAQ,MAAM;AACxD,aAAW,SAAS,YAAY,OAAQ,aAAY,UAAU,KAAK;AACnE,SAAO,cAAc,aAAa,QAAQ;AAC5C;AAEA,MAAM,gBAAgB,CAAC,aAA0C,aAAmC;AAClG,QAAM,UAAU,YAAY;AAC5B,MAAI,YAAY,OAAW,QAAO;AAClC,MAAI,QAAQ,WAAW,SAAU,QAAO;AACxC,MAAI,QAAQ,WAAW,eAAe,QAAQ,WAAW,YAAa,QAAO;AAC7E,MAAI,QAAQ,WAAW,mBAAoB,QAAO;AAClD,MAAI,QAAQ,WAAW,aAAa,QAAQ,kBAAkB,cAAc,QAAQ,kBAAkB,SAAY;AAChH,WAAO;AAAA,EACT;AACA,MAAI,cAAc,WAAW,QAAQ,QAAQ,QAAQ,aAAa,MAAM,OAAW,QAAO;AAC1F,QAAM,QAAQ,YAAY,cAAc;AACxC,MAAI,QAAQ,iBAAiB,UAAa,QAAQ,gBAAgB,MAAO,QAAO;AAChF,MAAI,SAAS,OAAQ,QAAO;AAC5B,MAAI,CAAC,YAAY,oBAAoB,YAAY,wBAAwB,YAAY,YAAY;AAC/F,WAAO,SAAS,OAAO,IAAI,gBAAgB;AAAA,EAC7C;AACA,SAAO;AACT;AAqBO,MAAM,YAAY,CAAC,WAA2B;AACnD,UAAQ,QAAQ;AAAA,IACd,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AAAA,IACL,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EACX;AACF;AAyFA,MAAM,YAAY,CAAC,UACjB,qBAAO,QAAQ,wBAAS,CAAC,YACvB,QAAQ,KAAK,EAAE,MAAM,QAAQ,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE;AAAA,EACjD,qBAAO,IAAI,CAAC,WAAW,OAAO,SAAS,SAAS,OAAO,MAAM,CAAC,IAAI,MAAS;AAC7E,CAAC;AAEL,MAAM,WAAW,CAAC,YAChB,YAAY,WACX,QAAQ,WAAW,eAAe,QAAQ,WAAW,YAAY,QAAQ,WAAW;AA8BhF,MAAM,MAAM,CACjB,YAEA,qBAAO,IAAI,aAAY;AACrB,QAAM,UAAU,OAAO;AACvB,QAAM,UAAU,OAAO,uBAAQ;AAC/B,QAAM,aAAa,QAAQ,cAAc,QAAQ,aAAa,OAAO,cAAc;AACnF,MAAI,2BAA2B;AAC/B,MAAI;AACJ,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,WAAW,QAAQ,YAAY,CAAC;AACtC,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,OAAO,QAAQ,SAAS,CAAC,UAC7B,MAAM,WAAW,WACb,QAAQ,OAAO;AAAA,IACf,OAAO,MAAM;AAAA,IACb,gBAAgB,WAAW,SAAS,WAAW,MAAM,KAAK,IAAI,MAAM,IAAI;AAAA,EAC1E,CAAC,IACC,QAAQ,OAAO;AAAA,IACf,OAAO,MAAM;AAAA,IACb,QAAQ,WAAW,MAAM,MAAM;AAAA,IAC/B,gBAAgB,WAAW,SAAS,WAAW,MAAM,KAAK,IAAI,MAAM,IAAI;AAAA,EAC1E,CAAC;AAEL,QAAM,OAAO,CACX,WACA,SACA,cACsC;AACtC,UAAM,aAAa,CAAC,UAClB,IAAI,qCAAiB;AAAA,MACnB,WAAW;AAAA,MACX,SAAS,oBAAoB,SAAS,QAAQ,QAAQ,KAAK;AAAA,MAC3D;AAAA,IACF,CAAC;AASH,WAAO,qBAAO,IAAI;AAAA,MAChB,KAAK,MACH,IAAI,4BAAa,MAAM;AAAA,QACrB,OAAO,4BAAa,MAAM,KAAK,QAAQ,KAAK;AAAA,QAC5C,UAAU,4BAAa,SAAS,KAAK,oBAAoB,SAAS,EAAE;AAAA,QACpE;AAAA,QACA,SAAS,EAAE,OAAO,QAAQ,OAAO,WAAW,GAAG,QAAQ;AAAA,MACzD,CAAC;AAAA,MACH,OAAO;AAAA,IACT,CAAC,EAAE;AAAA,MACD,qBAAO,QAAQ,CAAC,UAAU,qBAAO,SAAS,QAAQ,oBAAoB,KAAK,GAAG,UAAU,CAAC;AAAA,MACzF,qBAAO;AAAA,IACT;AAAA,EACF;AAGA,QAAM,SAAS,CAAC,MAAY,WAC1B;AAAA,IACE;AAAA,IACA;AAAA,MACE,MAAM,KAAK;AAAA,MACX,QAAQ,KAAK;AAAA,MACb,UAAU,KAAK;AAAA,MACf,GAAI,WAAW,SAAS,CAAC,IAAI,EAAE,OAAO;AAAA,IACxC;AAAA,IACA,gBAAgB,KAAK,IAAI;AAAA,EAC3B;AAGF,QAAM,eAAe,CACnB,MACA,QACA,YAEA;AAAA,IACE;AAAA,IACA,EAAE,MAAM,KAAK,MAAM,QAAQ,KAAK,QAAQ,QAAQ,QAAQ,SAAS,QAAQ,KAAK;AAAA,IAC9E,gBAAgB,KAAK,IAAI;AAAA,EAC3B;AAEF,QAAM,QAAqB,CAAC;AAC5B,MAAI,uBAAuB;AAC3B,MAAI,eAAe;AACnB,MAAI,aAAiE,CAAC;AACtE,QAAM,WAAyB,EAAE,MAAM,GAAG,QAAQ,MAAM;AACxD,MAAI,WAAW;AACf,WAAS,OAAO,GAAG,OAAO,WAAW,QAAQ,GAAG;AAC9C,QAAI,OAAO,KAAK,aAAa,GAAG;AAC9B,aAAO,qBAAO,MAAM,uBAAS;AAAA,QAC3B,QAAQ,gBAAgB,SACpB,aACA,cAAc,UAAU,QAAQ,YAAY,QAAQ,wBAAwB;AAAA,MAClF,CAAC;AAAA,IACH;AACA,UAAM,UAAU,OAAO,UAAU,QAAQ,KAAK;AAC9C,UAAM,YAAiC,CAAC;AACxC,UAAM,cAAc,KAAK,IAAI,GAAG,QAAQ;AACxC,WAAO,QAAQ,MAAM,EAAE,OAAO,QAAQ,OAAO,QAAQ,OAAO,GAAG,WAAW,CAAC,EAAE;AAAA,MAC3E,qBAAO;AAAA,QAAW,CAAC,UACjB,qBAAO,KAAK,MAAM;AAEhB,uBAAa,MAAM,WAAW,SAC1B,EAAE,eAAe,MAAM,SAAS,IAChC,EAAE,aAAa,MAAM,OAAO;AAChC,cAAI,mBAAmB,MAAM,IAAI,EAAG;AACpC,oBAAU,KAAK,KAAK;AACpB,cAAI,UAAU,SAAS,IAAK,WAAU,MAAM;AAC5C,qBAAW,MAAM;AACjB,sBAAY,UAAU,KAAK;AAAA,QAC7B,CAAC;AAAA,MACH;AAAA,IACF;AACA,2BAAuB,aAAa,eAAe,uBAAuB,IAAI;AAC9E,mBAAe;AACf,UAAM,SAAS,cAAc;AAAA,MAC3B,GAAI,YAAY,SAAY,CAAC,IAAI,EAAE,QAAQ;AAAA,MAC3C;AAAA,MACA;AAAA,MACA,GAAI,QAAQ,eAAe,SAAY,CAAC,IAAI,EAAE,YAAY,QAAQ,WAAW;AAAA,IAC/E,GAAG,QAAQ;AACX,QAAI,QAAQ,gBAAgB,UAAa,YAAY,QAAW;AAC9D,YAAM,QAAQ,QAAQ;AACtB,YAAM,YAAY,OAAO,QAAQ,KAAK;AACtC,YAAM,cAAc,cAAc,eAAe,OAAO;AACxD,YAAM,QAAQ,cAAc,SAAS,OAAO;AAAA,QAC1C;AAAA,QACA,OAAO,QAAQ;AAAA,QACf;AAAA,QACA,QAAQ;AAAA,QACR;AAAA,MACF,GAAG,EAAE,WAAW,aAAa,aAAa,KAAK,IAAI,GAAG,QAAQ,EAAE,CAAC;AACjE,UAAI,cAAc,OAAQ,QAAQ,kBAAkB,KAAK,KAAK;AAC9D,YAAM,UAAU,OAAO,UAAU,QAAQ,KAAK;AAC9C,UAAI,YAAY,UAAa,cAAc,eAAe,OAAO,MAAM,aAAa;AAClF,sBAAc,EAAE,GAAG,aAAa,SAAS,aAAa,QAAQ,QAAW,QAAQ,gBAAgB;AAAA,MACnG;AACA,iCAA2B,YAAY,YAAY,OAAO,IAAI,2BAA2B;AACzF,YAAM,mBAAmB,YAAY,YAAY,QAAQ,YAAY,QAAQ,aAAa;AAC1F,YAAM,aAAa,cAAc;AAAA,QAC/B;AAAA,QACA;AAAA,QACA;AAAA,QACA,YAAY,QAAQ;AAAA,QACpB;AAAA,MACF,GAAG,QAAQ;AACX,oBAAc,EAAE,GAAG,aAAa,WAAW;AAC3C,YAAM,SAAS,cAAc,OAAO;AAAA,QAClC;AAAA,QACA,OAAO,QAAQ;AAAA,QACf;AAAA,QACA,eAAe,QAAQ;AAAA,QACvB;AAAA,QACA,QAAQ,EAAE,aAAa,UAAU,EAAE;AAAA,QACnC,KAAK,YAAY;AAAA,QACjB,WAAW,QAAQ;AAAA,MACrB,CAAC;AACD,YAAM,UAAU,kBAAkB,UAAa,cAAc,gBAAgB,YAAY,eACvF,cAAc,YAAY,YAAY,WAAW,cAAc,eAAe,YAAY,cAC1F,cAAc,gBAAgB,YAAY,eAC1C,KAAK,UAAU,cAAc,MAAM,MAAM,KAAK,UAAU,YAAY,MAAM,KAC1E,cAAc,WAAW,YAAY;AAEvC,UAAI,WAAW,YAAY,cAAc,cAAe,aAAa,MAAM,OAAO,QAAQ,GAAG;AAC3F,eAAO,KAAK,cAAc,yBAAyB;AAAA,UACjD,GAAG;AAAA,UACH,QAAQ,QAAQ;AAAA,UAChB,QAAQ,OAAO;AAAA,UACf,UAAU,OAAO;AAAA,UACjB,WAAW,OAAO;AAAA,UAClB,WAAW,OAAO;AAAA,UAClB,eAAe,QAAQ,iBAAiB;AAAA,QAC1C,GAAG,oBAAoB;AACvB,wBAAgB;AAAA,MAClB;AAAA,IACF;AAEA,UAAM,SAAS,SAAS,SAAS,MAAM,IAAI,UAAU,MAAM,IAAI;AAC/D,UAAM,WAAiB,EAAE,MAAM,QAAQ,SAAS;AAChD,QAAI,QAAQ,gBAAgB,MAAO,QAAO,OAAO,UAAU,MAAM;AACjE,QAAI,WAAW,QAAQ;AACrB,YAAM,KAAK,QAAQ;AAAA,IACrB,OAAO;AACL,YAAM,UAAU,OAAO,KAAK,EAAE,OAAO,QAAQ,OAAO,QAAQ,QAAQ,KAAK,CAAC,EAAE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAO1E,qBAAO;AAAA,UAAM,CAAC,YACZ,qBAAO;AAAA,YACL,qBAAO,WAAW,yCAAyC;AAAA,YAC3D,EAAE,OAAO,QAAQ,OAAO,MAAM,QAAQ,QAAQ,OAAO,OAAO,OAAO,EAAE;AAAA,UACvE,EAAE,KAAK,qBAAO,GAAG,MAAS,CAAC;AAAA,QAC7B;AAAA,MACF;AACA,UAAI,YAAY,QAAW;AAIzB,cAAM,KAAK,QAAQ;AAAA,MACrB,OAAO;AAOL,cAAM,UAAU,QAAQ,SAAS,cAAc,QAAQ,SAAS;AAChE,YAAI,SAAS;AAGX,iBAAO,aAAa,UAAU,QAAQ,OAAO;AAI7C,iCAAuB;AAAA,QACzB;AACA,cAAM,KAAK,UAAU,EAAE,GAAG,UAAU,QAAQ,QAAQ,QAAQ,IAAI,EAAE,GAAG,UAAU,QAAQ,CAAC;AAIxF,YAAI,QAAQ,SAAS,WAAY;AAAA,MACnC;AAAA,IACF;AACA,QAAI,QAAQ,gBAAgB,UAAa,MAAM,SAAS,QAAQ,aAAa;AAC3E,YAAM,OAAO,GAAG,MAAM,SAAS,QAAQ,WAAW;AAAA,IACpD;AACA,QAAI,SAAS,OAAO,GAAG;AACrB;AAAA,IACF;AAAA,EACF;AACA,SAAO;AAAA,IACL,OAAO,QAAQ;AAAA,IACf;AAAA,IACA,QAAQ,MAAM,MAAM,SAAS,CAAC,GAAG,UAAU;AAAA,EAC7C;AACF,CAAC;AAMI,MAAM,qBAAqB,CAAC,SACjC,KAAK,WAAW,kBAAkB,KAAK,KAAK,WAAW,iBAAiB,KACxE,KAAK,WAAW,eAAe,KAAK,KAAK,WAAW,sBAAsB,KAAK,KAAK,WAAW,qBAAqB;",
+  "names": []
+}

package/dist/cjs/ScopedToken.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Scoped, expiring gateway tokens.
+ *
+ * A gateway's configured bearer credential grants everything the gateway
+ * serves, for as long as it is configured. A scoped token is a grant the
+ * holder of that credential mints for someone else: a closed list of
+ * procedures, optionally confined to one run or one flow, and an expiry. It
+ * is signed with HMAC-SHA256 under the bearer credential, so a gateway
+ * verifies it with the key it already holds and stores nothing; rotating the
+ * bearer credential revokes every token minted under it.
+ *
+ * The wire form is `smt1.<claims>.<signature>`, both parts unpadded base64url,
+ * the claims a canonical JSON document. A token names procedures rather than
+ * scope words so that what it authorizes is readable off the token itself and
+ * does not change when a scope grows.
+ *
+ * Web Crypto does the signing, so the same module runs on Node, Bun, and in a
+ * browser that holds a token.
+ *
+ * @since 1.0.0
+ */
+import { Effect, Schema } from "effect";
+import { Unauthorized } from "./ControlError.ts";
+import { type Authenticator, type Call } from "./ControlRpcs.ts";
+import type { Principal } from "./ControlSchema.ts";
+/**
+ * The version prefix every scoped token starts with.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const prefix = "smt1";
+/**
+ * The scopes `smthrs token mint --scope` accepts, and the procedures each
+ * one names.
+ *
+ * `read:runs` covers every read the control plane and the gateway serve.
+ * `write:runs` covers the mutations that start, steer, signal, cancel, and
+ * resume a run, and the gateway's `Run.Fork` and `Run.Verify`, which branch a
+ * run or drive the project's flow code over a copy of it. `approve:runs` covers the approval decisions on both mounts.
+ * A token holding `approve:runs` still needs the host's `ApprovalAuthority`
+ * to delegate to its principal, exactly as the bearer does.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const scopes: {
+    readonly "read:runs": readonly ["List", "Watch", "Projection.Snapshot", "Projection.Subscribe"];
+    readonly "write:runs": readonly ["Plan", "Run", "Steer", "Signal", "Cancel", "Resume", "Run.Fork", "Run.Verify"];
+    readonly "approve:runs": readonly ["Approve", "Deny", "Approval.Submit"];
+};
+/**
+ * One scope name.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Scope = keyof typeof scopes;
+/**
+ * Every scope name, in the order {@link scopes} declares them.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const scopeNames: ReadonlyArray<Scope>;
+/**
+ * What a token grants, as signed.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const Claims: Schema.Struct<{
+    readonly v: Schema.Literal<1>;
+    /** A random identifier, so two tokens with the same grant differ. */
+    readonly id: Schema.String;
+    readonly procedures: Schema.$Array<Schema.String>;
+    readonly runId: Schema.optional<Schema.String>;
+    readonly flowId: Schema.optional<Schema.String>;
+    /** Minted at, milliseconds since the epoch. */
+    readonly iat: Schema.Number;
+    /** Expires at, milliseconds since the epoch; refused once `now >= exp`. */
+    readonly exp: Schema.Number;
+}>;
+/**
+ * What a token grants, as signed.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Claims = typeof Claims.Type;
+/**
+ * What `mint` needs.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface MintOptions {
+    /** The signing key: the gateway's configured bearer credential. */
+    readonly key: string;
+    readonly scopes: ReadonlyArray<Scope>;
+    /** How long the token lives, in milliseconds; must be positive. */
+    readonly ttlMillis: number;
+    /** Confine every call to this run. */
+    readonly runId?: string | undefined;
+    /** Confine every call to this flow. */
+    readonly flowId?: string | undefined;
+    readonly now?: (() => number) | undefined;
+}
+/**
+ * A minted token beside the claims it carries.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Minted {
+    readonly token: string;
+    readonly claims: Claims;
+}
+/**
+ * Whether a bearer credential is spelled as a scoped token.
+ *
+ * @category predicates
+ * @since 1.0.0
+ */
+export declare const isScopedToken: (credential: string) => boolean;
+/**
+ * The procedures a list of scopes names, each once, in scope order.
+ *
+ * @category getters
+ * @since 1.0.0
+ */
+export declare const procedures: (names: ReadonlyArray<Scope>) => ReadonlyArray<string>;
+/**
+ * Mints one token under the key.
+ *
+ * An empty key, no scopes, or a non-positive lifetime is a caller defect: it
+ * cannot produce a token anyone should hold, so it dies rather than signs.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const mint: (options: MintOptions) => Effect.Effect<Minted>;
+/**
+ * Verifies a token's signature and expiry under the key and returns its
+ * claims. Every malformation, a wrong key, and an expired token all fail with
+ * the same `Unauthorized`, so the token is not a parsing oracle.
+ *
+ * @param now the moment to judge `exp` against, in milliseconds
+ * @category verification
+ * @since 1.0.0
+ */
+export declare const verify: (key: string, token: string, now: number) => Effect.Effect<Claims, Unauthorized>;
+/**
+ * Whether verified claims authorize one call.
+ *
+ * The procedure must be named. A token confined to a run authorizes only a
+ * call that names that run, and one confined to a flow only a call that names
+ * that flow: a call that names neither, such as an unfiltered `List`, is
+ * refused rather than widened.
+ *
+ * @category verification
+ * @since 1.0.0
+ */
+export declare const authorizes: (claims: Claims, call: Call) => boolean;
+/**
+ * What the scoped-token authenticator needs.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface AuthenticatorOptions {
+    /** The verifying key: the gateway's configured bearer credential. */
+    readonly key: string;
+    /** The principal every valid scoped token is stamped as. */
+    readonly principal: Omit<Principal, "stampedAt">;
+    readonly now?: (() => number) | undefined;
+}
+/**
+ * Authenticates a bearer credential spelled as a scoped token: the signature
+ * and expiry always, and the procedure plus run or flow confinement whenever
+ * the boundary knows which call it is guarding. An edge that authenticates an
+ * upgrade knows no call, so it admits the socket and leaves each frame to the
+ * in-band check.
+ *
+ * A credential that is not a scoped token is refused here; compose with
+ * `ControlRpcs.bearerAuthenticator` through `ControlRpcs.anyAuthenticator`
+ * to accept both.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const authenticator: (options: AuthenticatorOptions) => Authenticator;
+//# sourceMappingURL=ScopedToken.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ScopedToken.d.ts","sourceRoot":"","sources":["../../src/ScopedToken.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,MAAM,EAAoB,MAAM,EAAE,MAAM,QAAQ,CAAA;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,KAAK,aAAa,EAAoB,KAAK,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAClF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,MAAM,SAAS,CAAA;AAE5B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,MAAM;;;;CAIuC,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,OAAO,MAAM,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,aAAa,CAAC,KAAK,CAAuC,CAAA;AAEnF;;;;;GAKG;AACH,eAAO,MAAM,MAAM;;IAEjB,qEAAqE;;;;;IAKrE,+CAA+C;;IAE/C,2EAA2E;;EAE3E,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;IACrC,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,uCAAuC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAA;CAC1C;AAED;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAeD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,YAAY,MAAM,KAAG,OAA8C,CAAA;AAEjG;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GACrB,OAAO,aAAa,CAAC,KAAK,CAAC,KAC1B,aAAa,CAAC,MAAM,CAAwD,CAAA;AAE/E;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS,WAAW,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAwB5D,CAAA;AAIJ;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,GAAI,KAAK,MAAM,EAAE,OAAO,MAAM,EAAE,KAAK,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CA4B/F,CAAA;AAeJ;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,EAAE,MAAM,IAAI,KAAG,OAGoB,CAAA;AAE5E;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,CAAA;IAChD,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAA;CAC1C;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,oBAAoB,KAAG,aAa5D,CAAA"}