@smthrs/flow 0.0.0-stage → 1.0.0-rc.12

package/dist/esm/Sleep.js

@@ -0,0 +1,256 @@
+/**
+ * The system timer, as an ordinary declared action.
+ *
+ * `docs/concepts/flows-and-actions.md` names the timer primitive a
+ * gap and says how to close it: ship it over the existing `DurableClock`, so a
+ * wait is a visible, keyed plan node rather than a second execution mechanism.
+ * That is this module. {@link action} is a plain `Action.make` declaration —
+ * it appears in a catalog, `.call()` records a node, and `Graph.build` puts that
+ * node in the plan beside every other step — and {@link layer} is the
+ * implementation the hosts that can run a timer provide.
+ *
+ * The wait itself is `DurableClock`'s, not a new one. The implementation arms
+ * the durable clock and awaits its deferred, which is what parks the execution;
+ * the park is declared through the ordinary waiting vocabulary
+ * ({@link module:WaitingAnnotation.annotateWaiting}) under `timer`, with the
+ * deadline as `wakeAt`, so a durable driver records the same waiting row it
+ * records for a hand-written `DurableClock.sleep`. Replay is the deferred's:
+ * once the clock has fired, its result is persisted, so a re-driven round reads
+ * it and runs straight through instead of parking a second time.
+ *
+ * Which clock a wait arms is the dispatch's own, read from
+ * {@link module:Context.CurrentInvocationKey}: a keyed node already owns an
+ * identity that survives replay and separates two identical calls, so the timer
+ * inherits it rather than being addressed by the payload it was called with.
+ *
+ * @since 0.1.0
+ */
+import * as Clock from "effect/Clock";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Action from "./Action/index.js";
+import * as DurableClock from "./DurableClock.js";
+import { annotateWaiting } from "./FlowRuntime/WaitingAnnotation.js";
+/**
+ * A sleep whose payload does not name exactly one deadline.
+ *
+ * A payload carries a relative `millis` or an absolute `until`, and naming
+ * both, or neither, leaves no deadline to arm a clock with. It is a typed
+ * failure rather than a defect because the payload of a driven node is
+ * assembled from plan values, so an author's mistake is recoverable through
+ * `Node.catch` like any other declared failure.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class SleepRequestInvalid extends Schema.TaggedError()("@smthrs/flow/SleepRequestInvalid", {
+    code: Schema.Literals(["missing_deadline", "ambiguous_deadline", "invalid_deadline"]),
+    message: Schema.String
+}) {
+}
+/**
+ * The tag the sleep declaration is catalogued and resolved under.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const tag = "system/sleep";
+/**
+ * The declared sleep action: `millis` from now, or an absolute `until`.
+ *
+ * **When to use**
+ *
+ * Use it in a body wherever a round has to wait for time to pass —
+ * `Sleep.action.call({ millis: 60_000 })` — rather than reaching for
+ * `DurableClock.sleep`, which is only callable from a handler and leaves
+ * nothing in the plan. A sleep node is keyed, inspectable, and skippable by a
+ * branch exactly like an action that does work.
+ *
+ * Two waits of the same length are two waits: `sleep(1h)` followed by
+ * `sleep(1h)` sleeps for two hours, because each call is its own node with its
+ * own identity, exactly as two calls of any other declaration are.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const action = Action.makeSystem(tag, {
+    payload: {
+        millis: Schema.optional(Schema.Number),
+        until: Schema.optional(Schema.Number)
+    },
+    success: Schema.Void,
+    error: SleepRequestInvalid,
+    tier: "sealed"
+});
+/**
+ * The latest deadline a sleep can arm, in epoch milliseconds.
+ *
+ * A durable store records `wakeAt` and a clock's due time as a non-negative
+ * safe integer. A finite deadline past this one passed every other check and
+ * then failed the park write, so it is refused with the payload's other
+ * invalid deadlines instead.
+ *
+ * @private
+ */
+const latestDeadline = Number.MAX_SAFE_INTEGER;
+/**
+ * The refusal for a deadline later than {@link latestDeadline}.
+ *
+ * @private
+ */
+const tooLate = (stated) => new SleepRequestInvalid({
+    code: "invalid_deadline",
+    message: `${tag} was called with ${stated}, which ends after ${latestDeadline}, the latest epoch ` +
+        "millisecond a durable timer records."
+});
+/**
+ * The absolute deadline a payload names, in epoch milliseconds.
+ *
+ * DECIDED: a payload names EXACTLY one of `millis`
+ * and `until`, and both other shapes are refused rather than resolved by
+ * precedence. A precedence rule would silently ignore half of a payload an
+ * author believed in, and the two fields are the same fact stated two ways, so
+ * there is no shape where carrying both is meaningful.
+ *
+ * `Duration.millis` accepts every number, so an unchecked deadline changes the
+ * sleep instead of refusing it. `NaN` becomes zero, a negative relative delay
+ * has already passed, and `Infinity` never ends. The implementation rejects
+ * those values before it annotates the instance or arms a clock. A finite
+ * absolute `until` remains legal when it is in the past because that sleep can
+ * settle immediately.
+ *
+ * @private
+ */
+const deadlineOf = (payload, now) => {
+    if (payload.millis !== undefined && payload.until !== undefined) {
+        return Effect.fail(new SleepRequestInvalid({
+            code: "ambiguous_deadline",
+            message: `${tag} was called with both "millis" and "until". A sleep names one deadline: ` +
+                "a relative duration, or an absolute epoch time."
+        }));
+    }
+    if (payload.millis !== undefined) {
+        if (!Number.isFinite(payload.millis) || payload.millis < 0) {
+            return Effect.fail(new SleepRequestInvalid({
+                code: "invalid_deadline",
+                message: `${tag} was called with millis ${payload.millis}. A deadline is a finite number of ` +
+                    "milliseconds that is not negative; the sleep would be over before it started, or never over at all."
+            }));
+        }
+        const deadline = now + payload.millis;
+        if (!Number.isFinite(deadline)) {
+            return Effect.fail(new SleepRequestInvalid({
+                code: "invalid_deadline",
+                message: `${tag} was called with millis ${payload.millis} at current time ${now}, which produces ` +
+                    `${deadline}. A deadline is a finite epoch time in milliseconds.`
+            }));
+        }
+        return Math.ceil(deadline) > latestDeadline
+            ? Effect.fail(tooLate(`millis ${payload.millis} at current time ${now}`))
+            : Effect.succeed(deadline);
+    }
+    if (payload.until !== undefined) {
+        if (!Number.isFinite(payload.until)) {
+            return Effect.fail(new SleepRequestInvalid({
+                code: "invalid_deadline",
+                message: `${tag} was called with until ${payload.until}. A deadline is a finite epoch time in milliseconds; ` +
+                    "the sleep must end at a real point in time."
+            }));
+        }
+        return Math.ceil(payload.until) > latestDeadline
+            ? Effect.fail(tooLate(`until ${payload.until}`))
+            : Effect.succeed(payload.until);
+    }
+    return Effect.fail(new SleepRequestInvalid({
+        code: "missing_deadline",
+        message: `${tag} was called with neither "millis" nor "until", so there is no deadline to wait for.`
+    }));
+};
+/**
+ * The durable clock the dispatch currently executing arms.
+ *
+ * DECIDED: the name is derived from the ENGINE's
+ * per-dispatch identity — the invocation key it already allocated — rather than
+ * from the payload. A durable clock's deferred is addressed by (execution,
+ * name), so the name has to be stable across replays of one node and distinct
+ * between two identical nodes, and the invocation key is exactly that: it is
+ * allocated on every dispatch including a replayed one, because the driver
+ * addresses the recorded outcome by it. A payload-derived name has only the
+ * first property — `sleep(1h); work(); sleep(1h)` would address ONE wake and
+ * sleep once — and closing that with a discriminator in the payload would make
+ * an author carry identity that a keyed plan node already has.
+ *
+ * DECIDED: a runtime that supplies no dispatch
+ * identity is refused as a defect rather than falling back to the payload. The
+ * fallback is unobservable in the one-wait case and silently collapses two
+ * waits in every other, so it would trade a wiring error a host fixes once for
+ * a run that quietly sleeps for half as long as it declared.
+ *
+ * @private
+ */
+const clockName = Effect.gen(function* () {
+    const invocation = yield* Action.CurrentInvocationKey;
+    if (invocation === undefined) {
+        return yield* Effect.die(`${tag} ran under a runtime that supplies no Action.CurrentInvocationKey. ` +
+            "A durable timer is named by the dispatch that armed it, so a runtime that does not " +
+            "identify the dispatch cannot arm one.");
+    }
+    return `Sleep/${invocation}`;
+});
+/**
+ * The sleep implementation: arm the durable clock, park under `timer`, wake.
+ *
+ * Provide it beside the other action implementation layers a body calls, over
+ * the {@link module:Implementations.layerImplementations} table they file
+ * themselves in:
+ *
+ * ```ts
+ * Layer.mergeAll(Sleep.layer, Interpreter.layer(Pipeline)).pipe(
+ *   Layer.provideMerge(Action.layerImplementations)
+ * )
+ * ```
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = action.toLayer((payload) => Effect.gen(function* () {
+    // Whole milliseconds, both of them. A durable deadline lands in an INTEGER
+    // column whose CHECK constraint refuses anything else
+    // (`flows_runs.waiting_wake_at_ms`, `flows_clock_deadlines.due_at_ms`), and
+    // `Clock.currentTimeMillis` is not integral under every clock: a test clock
+    // advanced by a fractional-millisecond sleep reports a fractional now, and
+    // a fractional `millis` or `until` in the payload does the same. The
+    // unrounded deadline reached the park write as a raw SQL constraint
+    // failure, which killed the drive and left the run `running` with nothing
+    // left to wake it. `now` floors, and the deadline ceils so a rounded sleep
+    // never ends before the instant it was asked to wait for.
+    const now = Math.floor(yield* Clock.currentTimeMillis);
+    const wakeAt = Math.ceil(yield* deadlineOf(payload, now));
+    const remaining = wakeAt - now;
+    // DECIDED: a deadline that has already passed
+    // settles the node instead of parking it. A durable wait exists to survive
+    // the gap until a deadline, and a run that resumes after its own deadline
+    // has to make progress rather than park again on a timer that can only fire
+    // in the past.
+    if (remaining <= 0)
+        return;
+    const name = yield* clockName;
+    // DECIDED: the park is declared rather than
+    // left to a driver's derivation, so a host with no clock table still parks
+    // under `timer`. A `millis` deadline is recomputed from the current clock,
+    // so a round re-driven before its timer fires re-declares a `wakeAt` later
+    // than the armed one; the wake itself is unaffected, because the durable
+    // clock row is keyed by name and keeps the deadline it was first armed
+    // with, and `wakeAt` is a sweeper hint rather than the wake.
+    yield* annotateWaiting({ reason: "timer", wakeAt });
+    yield* DurableClock.sleep({
+        name,
+        duration: Duration.millis(remaining),
+        // The wait is the point: a sleep called as a plan node parks the
+        // execution rather than holding a fiber open, so the in-memory shortcut
+        // is disabled instead of being left at its 60-second default.
+        inMemoryThreshold: Duration.zero
+    });
+}));
+//# sourceMappingURL=Sleep.js.map

package/dist/esm/Sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sleep.js","sourceRoot":"","sources":["../../src/Sleep.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The system timer, as an ordinary declared action.\n *\n * `docs/concepts/flows-and-actions.md` names the timer primitive a\n * gap and says how to close it: ship it over the existing `DurableClock`, so a\n * wait is a visible, keyed plan node rather than a second execution mechanism.\n * That is this module. {@link action} is a plain `Action.make` declaration —\n * it appears in a catalog, `.call()` records a node, and `Graph.build` puts that\n * node in the plan beside every other step — and {@link layer} is the\n * implementation the hosts that can run a timer provide.\n *\n * The wait itself is `DurableClock`'s, not a new one. The implementation arms\n * the durable clock and awaits its deferred, which is what parks the execution;\n * the park is declared through the ordinary waiting vocabulary\n * ({@link module:WaitingAnnotation.annotateWaiting}) under `timer`, with the\n * deadline as `wakeAt`, so a durable driver records the same waiting row it\n * records for a hand-written `DurableClock.sleep`. Replay is the deferred's:\n * once the clock has fired, its result is persisted, so a re-driven round reads\n * it and runs straight through instead of parking a second time.\n *\n * Which clock a wait arms is the dispatch's own, read from\n * {@link module:Context.CurrentInvocationKey}: a keyed node already owns an\n * identity that survives replay and separates two identical calls, so the timer\n * inherits it rather than being addressed by the payload it was called with.\n *\n * @since 0.1.0\n */\n\nimport * as Clock from \"effect/Clock\"\nimport type * as Crypto from \"effect/Crypto\"\nimport * as Duration from \"effect/Duration\"\nimport * as Effect from \"effect/Effect\"\nimport type * as Layer from \"effect/Layer\"\nimport * as Schema from \"effect/Schema\"\nimport * as Action from \"./Action/index.ts\"\nimport * as DurableClock from \"./DurableClock.ts\"\nimport type { FlowRuntime } from \"./FlowRuntime/FlowRuntime.ts\"\nimport { annotateWaiting } from \"./FlowRuntime/WaitingAnnotation.ts\"\n\n/**\n * A sleep whose payload does not name exactly one deadline.\n *\n * A payload carries a relative `millis` or an absolute `until`, and naming\n * both, or neither, leaves no deadline to arm a clock with. It is a typed\n * failure rather than a defect because the payload of a driven node is\n * assembled from plan values, so an author's mistake is recoverable through\n * `Node.catch` like any other declared failure.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class SleepRequestInvalid extends Schema.TaggedError<SleepRequestInvalid>()(\n  \"@smthrs/flow/SleepRequestInvalid\",\n  {\n    code: Schema.Literals([\"missing_deadline\", \"ambiguous_deadline\", \"invalid_deadline\"]),\n    message: Schema.String\n  }\n) {}\n\n/**\n * The tag the sleep declaration is catalogued and resolved under.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const tag = \"system/sleep\"\n\n/**\n * The declared sleep action: `millis` from now, or an absolute `until`.\n *\n * **When to use**\n *\n * Use it in a body wherever a round has to wait for time to pass —\n * `Sleep.action.call({ millis: 60_000 })` — rather than reaching for\n * `DurableClock.sleep`, which is only callable from a handler and leaves\n * nothing in the plan. A sleep node is keyed, inspectable, and skippable by a\n * branch exactly like an action that does work.\n *\n * Two waits of the same length are two waits: `sleep(1h)` followed by\n * `sleep(1h)` sleeps for two hours, because each call is its own node with its\n * own identity, exactly as two calls of any other declaration are.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const action: Action.Declared<\n  typeof tag,\n  Schema.Struct<{\n    readonly millis: Schema.optional<Schema.Number>\n    readonly until: Schema.optional<Schema.Number>\n  }>,\n  typeof Schema.Void,\n  typeof SleepRequestInvalid,\n  never\n> = Action.makeSystem(tag, {\n  payload: {\n    millis: Schema.optional(Schema.Number),\n    until: Schema.optional(Schema.Number)\n  },\n  success: Schema.Void,\n  error: SleepRequestInvalid,\n  tier: \"sealed\"\n})\n\n/**\n * The latest deadline a sleep can arm, in epoch milliseconds.\n *\n * A durable store records `wakeAt` and a clock's due time as a non-negative\n * safe integer. A finite deadline past this one passed every other check and\n * then failed the park write, so it is refused with the payload's other\n * invalid deadlines instead.\n *\n * @private\n */\nconst latestDeadline = Number.MAX_SAFE_INTEGER\n\n/**\n * The refusal for a deadline later than {@link latestDeadline}.\n *\n * @private\n */\nconst tooLate = (stated: string): SleepRequestInvalid =>\n  new SleepRequestInvalid({\n    code: \"invalid_deadline\",\n    message: `${tag} was called with ${stated}, which ends after ${latestDeadline}, the latest epoch ` +\n      \"millisecond a durable timer records.\"\n  })\n\n/**\n * The absolute deadline a payload names, in epoch milliseconds.\n *\n * DECIDED: a payload names EXACTLY one of `millis`\n * and `until`, and both other shapes are refused rather than resolved by\n * precedence. A precedence rule would silently ignore half of a payload an\n * author believed in, and the two fields are the same fact stated two ways, so\n * there is no shape where carrying both is meaningful.\n *\n * `Duration.millis` accepts every number, so an unchecked deadline changes the\n * sleep instead of refusing it. `NaN` becomes zero, a negative relative delay\n * has already passed, and `Infinity` never ends. The implementation rejects\n * those values before it annotates the instance or arms a clock. A finite\n * absolute `until` remains legal when it is in the past because that sleep can\n * settle immediately.\n *\n * @private\n */\nconst deadlineOf = (\n  payload: { readonly millis?: number | undefined; readonly until?: number | undefined },\n  now: number\n): Effect.Effect<number, SleepRequestInvalid> => {\n  if (payload.millis !== undefined && payload.until !== undefined) {\n    return Effect.fail(\n      new SleepRequestInvalid({\n        code: \"ambiguous_deadline\",\n        message: `${tag} was called with both \"millis\" and \"until\". A sleep names one deadline: ` +\n          \"a relative duration, or an absolute epoch time.\"\n      })\n    )\n  }\n  if (payload.millis !== undefined) {\n    if (!Number.isFinite(payload.millis) || payload.millis < 0) {\n      return Effect.fail(\n        new SleepRequestInvalid({\n          code: \"invalid_deadline\",\n          message: `${tag} was called with millis ${payload.millis}. A deadline is a finite number of ` +\n            \"milliseconds that is not negative; the sleep would be over before it started, or never over at all.\"\n        })\n      )\n    }\n    const deadline = now + payload.millis\n    if (!Number.isFinite(deadline)) {\n      return Effect.fail(\n        new SleepRequestInvalid({\n          code: \"invalid_deadline\",\n          message: `${tag} was called with millis ${payload.millis} at current time ${now}, which produces ` +\n            `${deadline}. A deadline is a finite epoch time in milliseconds.`\n        })\n      )\n    }\n    return Math.ceil(deadline) > latestDeadline\n      ? Effect.fail(tooLate(`millis ${payload.millis} at current time ${now}`))\n      : Effect.succeed(deadline)\n  }\n  if (payload.until !== undefined) {\n    if (!Number.isFinite(payload.until)) {\n      return Effect.fail(\n        new SleepRequestInvalid({\n          code: \"invalid_deadline\",\n          message:\n            `${tag} was called with until ${payload.until}. A deadline is a finite epoch time in milliseconds; ` +\n            \"the sleep must end at a real point in time.\"\n        })\n      )\n    }\n    return Math.ceil(payload.until) > latestDeadline\n      ? Effect.fail(tooLate(`until ${payload.until}`))\n      : Effect.succeed(payload.until)\n  }\n  return Effect.fail(\n    new SleepRequestInvalid({\n      code: \"missing_deadline\",\n      message: `${tag} was called with neither \"millis\" nor \"until\", so there is no deadline to wait for.`\n    })\n  )\n}\n\n/**\n * The durable clock the dispatch currently executing arms.\n *\n * DECIDED: the name is derived from the ENGINE's\n * per-dispatch identity — the invocation key it already allocated — rather than\n * from the payload. A durable clock's deferred is addressed by (execution,\n * name), so the name has to be stable across replays of one node and distinct\n * between two identical nodes, and the invocation key is exactly that: it is\n * allocated on every dispatch including a replayed one, because the driver\n * addresses the recorded outcome by it. A payload-derived name has only the\n * first property — `sleep(1h); work(); sleep(1h)` would address ONE wake and\n * sleep once — and closing that with a discriminator in the payload would make\n * an author carry identity that a keyed plan node already has.\n *\n * DECIDED: a runtime that supplies no dispatch\n * identity is refused as a defect rather than falling back to the payload. The\n * fallback is unobservable in the one-wait case and silently collapses two\n * waits in every other, so it would trade a wiring error a host fixes once for\n * a run that quietly sleeps for half as long as it declared.\n *\n * @private\n */\nconst clockName: Effect.Effect<string> = Effect.gen(function*() {\n  const invocation = yield* Action.CurrentInvocationKey\n  if (invocation === undefined) {\n    return yield* Effect.die(\n      `${tag} ran under a runtime that supplies no Action.CurrentInvocationKey. ` +\n        \"A durable timer is named by the dispatch that armed it, so a runtime that does not \" +\n        \"identify the dispatch cannot arm one.\"\n    )\n  }\n  return `Sleep/${invocation}`\n})\n\n/**\n * The sleep implementation: arm the durable clock, park under `timer`, wake.\n *\n * Provide it beside the other action implementation layers a body calls, over\n * the {@link module:Implementations.layerImplementations} table they file\n * themselves in:\n *\n * ```ts\n * Layer.mergeAll(Sleep.layer, Interpreter.layer(Pipeline)).pipe(\n *   Layer.provideMerge(Action.layerImplementations)\n * )\n * ```\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer: Layer.Layer<never, never, Crypto.Crypto | FlowRuntime> = action.toLayer((payload) =>\n  Effect.gen(function*() {\n    // Whole milliseconds, both of them. A durable deadline lands in an INTEGER\n    // column whose CHECK constraint refuses anything else\n    // (`flows_runs.waiting_wake_at_ms`, `flows_clock_deadlines.due_at_ms`), and\n    // `Clock.currentTimeMillis` is not integral under every clock: a test clock\n    // advanced by a fractional-millisecond sleep reports a fractional now, and\n    // a fractional `millis` or `until` in the payload does the same. The\n    // unrounded deadline reached the park write as a raw SQL constraint\n    // failure, which killed the drive and left the run `running` with nothing\n    // left to wake it. `now` floors, and the deadline ceils so a rounded sleep\n    // never ends before the instant it was asked to wait for.\n    const now = Math.floor(yield* Clock.currentTimeMillis)\n    const wakeAt = Math.ceil(yield* deadlineOf(payload, now))\n    const remaining = wakeAt - now\n    // DECIDED: a deadline that has already passed\n    // settles the node instead of parking it. A durable wait exists to survive\n    // the gap until a deadline, and a run that resumes after its own deadline\n    // has to make progress rather than park again on a timer that can only fire\n    // in the past.\n    if (remaining <= 0) return\n    const name = yield* clockName\n    // DECIDED: the park is declared rather than\n    // left to a driver's derivation, so a host with no clock table still parks\n    // under `timer`. A `millis` deadline is recomputed from the current clock,\n    // so a round re-driven before its timer fires re-declares a `wakeAt` later\n    // than the armed one; the wake itself is unaffected, because the durable\n    // clock row is keyed by name and keeps the deadline it was first armed\n    // with, and `wakeAt` is a sweeper hint rather than the wake.\n    yield* annotateWaiting({ reason: \"timer\", wakeAt })\n    yield* DurableClock.sleep({\n      name,\n      duration: Duration.millis(remaining),\n      // The wait is the point: a sleep called as a plan node parks the\n      // execution rather than holding a fiber open, so the in-memory shortcut\n      // is disabled instead of being left at its 60-second default.\n      inMemoryThreshold: Duration.zero\n    })\n  })\n)\n"]}

package/dist/esm/Stall.d.ts

@@ -0,0 +1,173 @@
+/**
+ * The stall breaker: end a round loop that has stopped making progress.
+ *
+ * A round bound is only a budget. A loop whose rounds change nothing spends
+ * the whole budget anyway: an agent that rewrites the same tree, a check that
+ * fails the same way after every repair, a reviser that hands back the same
+ * draft. This module counts consecutive rounds whose signal did not move and
+ * reports a {@link Stalled} verdict once one signal has held for
+ * `rounds` rounds in a row.
+ *
+ * Three signals are read, each optional per round:
+ *
+ * - `tree`: a fingerprint of the files the round left behind, such as a JJ
+ *   tree id or a `TreeFingerprint` checksum.
+ * - `checks`: the ids of the checks that failed. Order does not matter, and
+ *   an empty list is not compared.
+ * - `output`: the round's value, compared by the SHA-256 of its RFC 8785
+ *   canonical JSON. A value with no canonical form is not compared.
+ *
+ * Everything here is data. The {@link State} a round carries forward is a
+ * plain record, so a durable trampoline keeps it in its payload and a replay
+ * reads the same verdict. The loop decides what `on` means: `stop` settles
+ * with the stalled value, `park` settles the same way tagged for a caller
+ * that hands it to a person (the coding correction reports it `blocked`),
+ * and `escalate` fails.
+ *
+ * @since 1.0.0
+ */
+import * as Schema from "effect/Schema";
+/**
+ * What a loop does once it has stalled.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const On: Schema.Literals<readonly ["stop", "park", "escalate"]>;
+/**
+ * The `on` values as a type.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type On = typeof On.Type;
+/**
+ * The signal that held still.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const Signal: Schema.Literals<readonly ["tree", "checks", "output"]>;
+/**
+ * The signal names as a type.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Signal = typeof Signal.Type;
+/**
+ * A resolved stall policy: `rounds` identical rounds in a row, at least two,
+ * trigger `on`.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const Policy: Schema.Struct<{
+    readonly rounds: Schema.Int;
+    readonly on: Schema.Literals<readonly ["stop", "park", "escalate"]>;
+}>;
+/**
+ * A resolved policy as a type.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Policy = typeof Policy.Type;
+/**
+ * The authoring form of a {@link Policy}; `on` defaults to `"stop"`.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Options {
+    readonly rounds: number;
+    readonly on?: On | undefined;
+}
+/**
+ * What one round reports. An absent signal is not compared and resets its
+ * streak.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Observation {
+    readonly tree?: string | undefined;
+    readonly checks?: ReadonlyArray<string> | undefined;
+    readonly output?: unknown;
+}
+/**
+ * The streak of every signal, carried from one round to the next.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const State: Schema.Struct<{
+    readonly tree: Schema.NullOr<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly rounds: Schema.Int;
+    }>>;
+    readonly checks: Schema.NullOr<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly rounds: Schema.Int;
+    }>>;
+    readonly output: Schema.NullOr<Schema.Struct<{
+        readonly key: Schema.String;
+        readonly rounds: Schema.Int;
+    }>>;
+}>;
+/**
+ * The carried streaks as a type.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type State = typeof State.Type;
+/**
+ * The state before the first round.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const initial: State;
+/**
+ * The typed verdict: which signal held, for how many rounds, and what the
+ * policy says to do.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const Stalled: Schema.Struct<{
+    readonly _tag: Schema.Literal<"Stalled">;
+    readonly signal: Schema.Literals<readonly ["tree", "checks", "output"]>;
+    readonly rounds: Schema.Int;
+    readonly on: Schema.Literals<readonly ["stop", "park", "escalate"]>;
+}>;
+/**
+ * The verdict as a type.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Stalled = typeof Stalled.Type;
+/**
+ * Validates authoring options into a {@link Policy}. Throws a `RangeError`
+ * for fewer than two rounds, since one round cannot repeat anything.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const policy: (options: Options) => Policy;
+/**
+ * Folds one round into the state and reports whether the loop has stalled.
+ *
+ * Signals are judged in the order `tree`, `checks`, `output`; the first that
+ * reached `policy.rounds` names the verdict.
+ *
+ * @category combinators
+ * @since 1.0.0
+ */
+export declare const observe: (policy: Policy, state: State, observation: Observation) => {
+    readonly state: State;
+    readonly stalled: Stalled | undefined;
+};
+//# sourceMappingURL=Stall.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Stall.d.ts","sourceRoot":"","sources":["../../src/Stall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,EAAE,wDAAgD,CAAA;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC,IAAI,CAAA;AAE/B;;;;;GAKG;AACH,eAAO,MAAM,MAAM,wDAAgD,CAAA;AAEnE;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,MAAM;;;EAGjB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,SAAS,CAAA;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAC1B;AAID;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;EAAkE,CAAA;AAEpF;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,EAAE,KAAkD,CAAA;AAExE;;;;;;GAMG;AACH,eAAO,MAAM,OAAO;;;;;EAKlB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAA;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,GAAI,SAAS,OAAO,KAAG,MAKzC,CAAA;AAsBD;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAClB,QAAQ,MAAM,EACd,OAAO,KAAK,EACZ,aAAa,WAAW,KACvB;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAAA;CAYhE,CAAA"}

package/dist/esm/Stall.js

@@ -0,0 +1,138 @@
+/**
+ * The stall breaker: end a round loop that has stopped making progress.
+ *
+ * A round bound is only a budget. A loop whose rounds change nothing spends
+ * the whole budget anyway: an agent that rewrites the same tree, a check that
+ * fails the same way after every repair, a reviser that hands back the same
+ * draft. This module counts consecutive rounds whose signal did not move and
+ * reports a {@link Stalled} verdict once one signal has held for
+ * `rounds` rounds in a row.
+ *
+ * Three signals are read, each optional per round:
+ *
+ * - `tree`: a fingerprint of the files the round left behind, such as a JJ
+ *   tree id or a `TreeFingerprint` checksum.
+ * - `checks`: the ids of the checks that failed. Order does not matter, and
+ *   an empty list is not compared.
+ * - `output`: the round's value, compared by the SHA-256 of its RFC 8785
+ *   canonical JSON. A value with no canonical form is not compared.
+ *
+ * Everything here is data. The {@link State} a round carries forward is a
+ * plain record, so a durable trampoline keeps it in its payload and a replay
+ * reads the same verdict. The loop decides what `on` means: `stop` settles
+ * with the stalled value, `park` settles the same way tagged for a caller
+ * that hands it to a person (the coding correction reports it `blocked`),
+ * and `escalate` fails.
+ *
+ * @since 1.0.0
+ */
+import { canonicalize } from "@smthrs/canonical";
+import { digestSync } from "@smthrs/crypto";
+import * as Schema from "effect/Schema";
+/**
+ * What a loop does once it has stalled.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export const On = Schema.Literals(["stop", "park", "escalate"]);
+/**
+ * The signal that held still.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export const Signal = Schema.Literals(["tree", "checks", "output"]);
+/**
+ * A resolved stall policy: `rounds` identical rounds in a row, at least two,
+ * trigger `on`.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export const Policy = Schema.Struct({
+    rounds: Schema.Int.check(Schema.isGreaterThanOrEqualTo(2)),
+    on: On
+});
+const Streak = Schema.NullOr(Schema.Struct({ key: Schema.String, rounds: Schema.Int }));
+/**
+ * The streak of every signal, carried from one round to the next.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export const State = Schema.Struct({ tree: Streak, checks: Streak, output: Streak });
+/**
+ * The state before the first round.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const initial = { tree: null, checks: null, output: null };
+/**
+ * The typed verdict: which signal held, for how many rounds, and what the
+ * policy says to do.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export const Stalled = Schema.Struct({
+    _tag: Schema.Literal("Stalled"),
+    signal: Signal,
+    rounds: Schema.Int,
+    on: On
+});
+/**
+ * Validates authoring options into a {@link Policy}. Throws a `RangeError`
+ * for fewer than two rounds, since one round cannot repeat anything.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const policy = (options) => {
+    if (!Number.isSafeInteger(options.rounds) || options.rounds < 2) {
+        throw new RangeError("Stall rounds must be a safe integer of at least 2");
+    }
+    return { rounds: options.rounds, on: options.on ?? "stop" };
+};
+// A value with no canonical form (an `Error`, a `bigint`) is not compared.
+const hash = (value) => {
+    try {
+        return digestSync(canonicalize(value ?? null));
+    }
+    catch {
+        return undefined;
+    }
+};
+const keys = (observation) => ({
+    tree: observation.tree,
+    // No failing check is not a repeated failure.
+    checks: observation.checks === undefined || observation.checks.length === 0
+        ? undefined
+        : JSON.stringify([...new Set(observation.checks)].sort()),
+    output: "output" in observation ? hash(observation.output) : undefined
+});
+const signals = ["tree", "checks", "output"];
+/**
+ * Folds one round into the state and reports whether the loop has stalled.
+ *
+ * Signals are judged in the order `tree`, `checks`, `output`; the first that
+ * reached `policy.rounds` names the verdict.
+ *
+ * @category combinators
+ * @since 1.0.0
+ */
+export const observe = (policy, state, observation) => {
+    const current = keys(observation);
+    const next = Object.fromEntries(signals.map((signal) => {
+        const key = current[signal];
+        const prior = state[signal];
+        return [signal, key === undefined ? null : { key, rounds: prior?.key === key ? prior.rounds + 1 : 1 }];
+    }));
+    const signal = signals.find((signal) => (next[signal]?.rounds ?? 0) >= policy.rounds);
+    return {
+        state: next,
+        stalled: signal === undefined ? undefined : { _tag: "Stalled", signal, rounds: next[signal].rounds, on: policy.on }
+    };
+};
+//# sourceMappingURL=Stall.js.map

package/dist/esm/Stall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Stall.js","sourceRoot":"","sources":["../../src/Stall.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The stall breaker: end a round loop that has stopped making progress.\n *\n * A round bound is only a budget. A loop whose rounds change nothing spends\n * the whole budget anyway: an agent that rewrites the same tree, a check that\n * fails the same way after every repair, a reviser that hands back the same\n * draft. This module counts consecutive rounds whose signal did not move and\n * reports a {@link Stalled} verdict once one signal has held for\n * `rounds` rounds in a row.\n *\n * Three signals are read, each optional per round:\n *\n * - `tree`: a fingerprint of the files the round left behind, such as a JJ\n *   tree id or a `TreeFingerprint` checksum.\n * - `checks`: the ids of the checks that failed. Order does not matter, and\n *   an empty list is not compared.\n * - `output`: the round's value, compared by the SHA-256 of its RFC 8785\n *   canonical JSON. A value with no canonical form is not compared.\n *\n * Everything here is data. The {@link State} a round carries forward is a\n * plain record, so a durable trampoline keeps it in its payload and a replay\n * reads the same verdict. The loop decides what `on` means: `stop` settles\n * with the stalled value, `park` settles the same way tagged for a caller\n * that hands it to a person (the coding correction reports it `blocked`),\n * and `escalate` fails.\n *\n * @since 1.0.0\n */\n\nimport { canonicalize } from \"@smthrs/canonical\"\nimport { digestSync } from \"@smthrs/crypto\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * What a loop does once it has stalled.\n *\n * @category models\n * @since 1.0.0\n */\nexport const On = Schema.Literals([\"stop\", \"park\", \"escalate\"])\n\n/**\n * The `on` values as a type.\n *\n * @category models\n * @since 1.0.0\n */\nexport type On = typeof On.Type\n\n/**\n * The signal that held still.\n *\n * @category models\n * @since 1.0.0\n */\nexport const Signal = Schema.Literals([\"tree\", \"checks\", \"output\"])\n\n/**\n * The signal names as a type.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Signal = typeof Signal.Type\n\n/**\n * A resolved stall policy: `rounds` identical rounds in a row, at least two,\n * trigger `on`.\n *\n * @category models\n * @since 1.0.0\n */\nexport const Policy = Schema.Struct({\n  rounds: Schema.Int.check(Schema.isGreaterThanOrEqualTo(2)),\n  on: On\n})\n\n/**\n * A resolved policy as a type.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Policy = typeof Policy.Type\n\n/**\n * The authoring form of a {@link Policy}; `on` defaults to `\"stop\"`.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Options {\n  readonly rounds: number\n  readonly on?: On | undefined\n}\n\n/**\n * What one round reports. An absent signal is not compared and resets its\n * streak.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface Observation {\n  readonly tree?: string | undefined\n  readonly checks?: ReadonlyArray<string> | undefined\n  readonly output?: unknown\n}\n\nconst Streak = Schema.NullOr(Schema.Struct({ key: Schema.String, rounds: Schema.Int }))\n\n/**\n * The streak of every signal, carried from one round to the next.\n *\n * @category models\n * @since 1.0.0\n */\nexport const State = Schema.Struct({ tree: Streak, checks: Streak, output: Streak })\n\n/**\n * The carried streaks as a type.\n *\n * @category models\n * @since 1.0.0\n */\nexport type State = typeof State.Type\n\n/**\n * The state before the first round.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const initial: State = { tree: null, checks: null, output: null }\n\n/**\n * The typed verdict: which signal held, for how many rounds, and what the\n * policy says to do.\n *\n * @category models\n * @since 1.0.0\n */\nexport const Stalled = Schema.Struct({\n  _tag: Schema.Literal(\"Stalled\"),\n  signal: Signal,\n  rounds: Schema.Int,\n  on: On\n})\n\n/**\n * The verdict as a type.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Stalled = typeof Stalled.Type\n\n/**\n * Validates authoring options into a {@link Policy}. Throws a `RangeError`\n * for fewer than two rounds, since one round cannot repeat anything.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const policy = (options: Options): Policy => {\n  if (!Number.isSafeInteger(options.rounds) || options.rounds < 2) {\n    throw new RangeError(\"Stall rounds must be a safe integer of at least 2\")\n  }\n  return { rounds: options.rounds, on: options.on ?? \"stop\" }\n}\n\n// A value with no canonical form (an `Error`, a `bigint`) is not compared.\nconst hash = (value: unknown): string | undefined => {\n  try {\n    return digestSync(canonicalize(value ?? null))\n  } catch {\n    return undefined\n  }\n}\n\nconst keys = (observation: Observation): Record<Signal, string | undefined> => ({\n  tree: observation.tree,\n  // No failing check is not a repeated failure.\n  checks: observation.checks === undefined || observation.checks.length === 0\n    ? undefined\n    : JSON.stringify([...new Set(observation.checks)].sort()),\n  output: \"output\" in observation ? hash(observation.output) : undefined\n})\n\nconst signals: ReadonlyArray<Signal> = [\"tree\", \"checks\", \"output\"]\n\n/**\n * Folds one round into the state and reports whether the loop has stalled.\n *\n * Signals are judged in the order `tree`, `checks`, `output`; the first that\n * reached `policy.rounds` names the verdict.\n *\n * @category combinators\n * @since 1.0.0\n */\nexport const observe = (\n  policy: Policy,\n  state: State,\n  observation: Observation\n): { readonly state: State; readonly stalled: Stalled | undefined } => {\n  const current = keys(observation)\n  const next = Object.fromEntries(signals.map((signal) => {\n    const key = current[signal]\n    const prior = state[signal]\n    return [signal, key === undefined ? null : { key, rounds: prior?.key === key ? prior.rounds + 1 : 1 }]\n  })) as unknown as State\n  const signal = signals.find((signal) => (next[signal]?.rounds ?? 0) >= policy.rounds)\n  return {\n    state: next,\n    stalled: signal === undefined ? undefined : { _tag: \"Stalled\", signal, rounds: next[signal]!.rounds, on: policy.on }\n  }\n}\n"]}