@open-everywhere/core 0.1.0

package/dist/agent/routines/jq-filter.js

@@ -0,0 +1,322 @@
+// The SUBSCRIPTION FILTER LANGUAGE (OPE-210) — **jq**, evaluated IN-PROCESS over the already
+// vendored `just-bash`.
+//
+// WHAT THIS REPLACES. The declared-key clause language (`{all: [{key, in: […]}], under: […]}`) that
+// `event-match.ts` used to evaluate structurally. That language was chosen for one property —
+// CREATE-TIME VALIDATION against a closed key vocabulary — and the property turned out not to be a
+// property of the SYNTAX at all. It comes from HAVING A SCHEMA, and given a schema jq paths validate
+// just as well. The code already conceded it: `EventNormalizer.matchKeysOpen` exists precisely
+// because for a category-(b) contract the key space belongs to the SENDER, so the membership check
+// never ran for the case that motivates flexible filtering in the first place.
+//
+// 🔴 DO NOT RE-PROPOSE ANY OF THESE. Each was considered and ruled out on measured evidence, not
+// taste: a jq-wasm build (a second wasm blob for something already in the tree), a bundled static
+// `jq` binary (a native artifact per platform, and lambda bundles), exec-to-host `jq` (a host
+// process, a host filesystem and the real process env — the three things the vendored one does not
+// have), a Vercel Sandbox round-trip (~seconds, for a 0.3ms predicate), and a bespoke path DSL
+// (which is how the language we are deleting came to exist).
+//
+// ── WHAT `just-bash` ACTUALLY GIVES US (measured 2026-07-28, node 24, this tree) ────────────────
+//
+// It is a pure JS/TS reimplementation of bash + coreutils — NOT a wrapper over host binaries — and
+// ships a jq reimplementation running over an IN-MEMORY filesystem. So:
+//
+//   • `$ENV.X` and `env.X` never see the real process env. `env` returns a synthesised
+//     `{HOME:"/",PATH:"/usr/bin:/bin",…}`; the host's variables are not reachable from inside.
+//   • `jq '.' /etc/passwd` reports "no such file" — the FS is the object we hand it and nothing else.
+//   • ~0.3–0.6 ms per evaluation on a fresh interpreter (200 fresh instances ≈ 115 ms; 200 on a
+//     shared instance ≈ 60 ms). A fresh instance per evaluation is therefore AFFORDABLE, and we take
+//     it, because a shared one would let one routine's filter observe another's writes.
+//
+// That is sandboxed BY CONSTRUCTION rather than by remembering to scrub, and the distinction is the
+// whole reason this is safe: a scrub-based defence is one refactor away from being wrong.
+//
+// ── THE THREE THINGS THAT WERE NOT KNOWN, AND WHAT PROBING FOUND ───────────────────────────────
+//
+// 1. FIDELITY. Spot-checked against real jq's semantics on everything this tree relies on and a
+//    good deal it does not: `IN`, `and`/`or`/`not`, `//`, `select`, `any`, `has`, `length`, `type`,
+//    `paths`, `..`, `walk`, `getpath`, `startswith`/`contains`/`ltrimstr`, `test`/`capture`/`gsub`,
+//    `split`, `ascii_downcase`, `tojson`/`fromjson`, string interpolation, `def`, `as` (pipe, array
+//    and object patterns), `reduce`, `foreach`, `try`/`catch`. All correct. Four real divergences,
+//    NONE of which can turn a non-match into a match — every one of them lands on a non-boolean or a
+//    non-zero exit, which {@link evaluateJqFilter} classifies as an ERROR and the caller skips:
+//      • `input`, `input_filename` and `halt_error` are NOT implemented (`Unknown function`, exit 3).
+//        Losing them is a feature — each is an input/output side effect a match predicate has no
+//        business having.
+//      • An UNDEFINED VARIABLE (`$x`) evaluates to `null` on exit 0, where real jq refuses to compile
+//        it. Worth knowing because it means a typo'd binding does not announce itself as a syntax
+//        error; it announces itself as "filter produced null", which is still a create-time refusal.
+//      • `$__loc__` returns something that is not an object.
+//      • A runtime type error real jq would RAISE can come back as a plain `false`
+//        (`null | test("x")` ⇒ `false`, exit 0, where real jq errors). It fails toward NO MATCH.
+//    ⚠️ ONE NON-FINDING WORTH RECORDING, because it cost an hour: `as $x | …` and `reduce … as $x`
+//    appeared broken and were not. They were being mangled by BASH, not by jq — the expression was
+//    reaching the shell inside double quotes, where `$x` expands to nothing. See {@link runJq} for
+//    why the expression now bypasses shell parsing entirely, which is also the injection fix.
+//
+// 2. ADVERSARIAL INPUT. The document jq sees is bounded BY CONSTRUCTION and not by a check here: it
+//    is built from a {@link NormalizedEvent}, whose `fields` is capped at `FIELDS_MAX_KEYS` scalars
+//    of `FIELD_VALUE_MAX` chars and whose `scope` is at most the five closed `SCOPE_KINDS`. There is
+//    no arbitrarily-nested attacker JSON for a filter to walk, because normalization already
+//    flattened it. A 16 × 200 document evaluates `[..] | length > 0` in ~1.4 ms.
+//
+// 3. THE RESOURCE BOUND — and this is the load-bearing correction to the plan.
+//
+//    🔴 `ExecOptions.signal` (AbortSignal) IS NOT A TIMEOUT AND MUST NOT BE USED AS ONE. Measured: a
+//    `repeat` bomb aborted at 20 ms ran for **5.3 seconds**, stopping only when the ITERATION limit
+//    hit. just-bash's cancellation is cooperative "at the next statement boundary" and one `jq`
+//    invocation is one statement, so the signal is only ever observed BEFORE the command starts (a
+//    pre-aborted signal does return 124 immediately). For the same reason a homegrown
+//    `Promise.race` timer is strictly worse than useless — jq's evaluation is synchronous and holds
+//    the event loop, so nothing else, timer included, can run while it burns.
+//
+//    ⭐ `executionLimits` ({@link JQ_LIMITS}) is the bound that actually works, and it is
+//    just-bash's own — preferred over anything homegrown exactly as the brief asked. `maxJqIterations`
+//    bounds every unbounded construct the language has (`repeat`, `while`, `until`) and was measured
+//    stopping all three. Together with `commands: ["jq"]` — which makes `cat`, `curl`, `sh`,
+//    `python3`, `js-exec` and even `echo` `command not found` — the reachable surface is one pure
+//    function over one in-memory file.
+//
+//    RESIDUAL, STATED HONESTLY: a terminating-but-slow expression is still possible (`[range(0;3000)]
+//    | map([range(0;3000)])` ≈ 214 ms) and no limit here catches it, because `maxArrayElements` and
+//    `maxStringLength` are not enforced on that path. Two things bound it and neither is a limit
+//    object: a filter is authored through `create_routine` and shown to a human on an approval card,
+//    and {@link probeFilter} REFUSES at create time any expression that exceeds
+//    {@link FILTER_PROBE_BUDGET_MS} against a canonical probe document. That create-time measurement
+//    genuinely predicts fire-time cost here, which it would not in general: the document's SHAPE is
+//    fixed and its SIZE is capped, so an expression's cost is very nearly input-independent.
+//
+// ── DEFENSE-IN-DEPTH IS DELIBERATELY OFF ───────────────────────────────────────────────────────
+//
+// just-bash offers `defenseInDepth`, which monkey-patches `Function`, `eval`, `setTimeout`,
+// `process` and friends FOR THE DURATION OF EXECUTION. Its own documentation calls it a SECONDARY
+// layer that must never be the primary mechanism. We decline it, and the reason is not cost: those
+// patches are PROCESS-GLOBAL, and this evaluator runs inside a request-handling lambda where
+// unrelated async work — an audit write, an in-flight fetch — can be resumed while they are in
+// place. Trading a real risk to unrelated code for a secondary defence against a language we never
+// enable (`javascript`/`python` are both off) is a bad trade. If it is ever wanted, it belongs
+// around a worker, not around a shared event loop.
+import { Bash } from "just-bash";
+import { FIELD_VALUE_MAX, FIELDS_MAX_KEYS, SCOPE_KINDS, scopeIdOf, } from "./event-model.js";
+import { webhookScheme } from "./scheme-name.js";
+/** Where the document is mounted in the in-memory FS. Never a host path — there is no host FS. */
+const DOC_PATH = "/event.json";
+/**
+ * Longest filter expression we will store or run. Not a security bound (there isn't one to buy at
+ * this layer) — it is the point past which a filter has stopped being a predicate a human can read
+ * off an approval card, and an unreadable predicate approved by a click is the failure this whole
+ * plane is built to avoid.
+ */
+export const FILTER_MAX_LENGTH = 1000;
+/** Create-time cost ceiling — see the header's RESIDUAL note for why this, and not a timeout. */
+const FILTER_PROBE_BUDGET_MS = 250;
+/**
+ * How many TIMED runs {@link probeFilter} takes, of which it keeps the FASTEST.
+ *
+ * 🔴 WHY MIN-OF-N AND NOT ONE RUN. This budget is a claim about the EXPRESSION, but a single
+ * wall-clock sample measures the expression AND the machine — a cold engine, a busy event loop, a
+ * co-tenant burning CPU. Those only ever ADD time, never subtract it, so the minimum of several
+ * runs is the honest estimator of the expression's own cost and the mean is not.
+ *
+ * This is not hypothetical. A filter that evaluates in well under a millisecond measured 1039ms —
+ * 4x the budget — on a loaded box, and the refusal it produced told the author to rewrite a
+ * predicate that was never the problem. A create-time gate that fails on machine weather is worse
+ * than no gate: it is unreproducible, it fires on the honest author rather than the expensive
+ * filter, and its message sends them to fix the wrong thing.
+ *
+ * The correctness probe stays a separate FIRST run whose timing is discarded, so one-time engine
+ * warm-up is never charged to the author.
+ */
+const PROBE_RUNS = 3;
+/**
+ * just-bash's OWN limits, used in preference to anything homegrown (and there is nothing homegrown
+ * here — see the header on why an AbortSignal cannot be a timeout).
+ *
+ * `maxJqIterations` is the one that matters: it is what stops `repeat`/`while`/`until`, the only
+ * genuinely unbounded constructs in the language. 1,000 is far above anything a predicate over a
+ * ≤16-field document needs and far below anything that takes measurable time. The rest are cheap
+ * belt: one command per evaluation, a shallow call stack, and output that cannot grow past a line.
+ */
+const JQ_LIMITS = {
+    maxJqIterations: 1_000,
+    maxCommandCount: 2,
+    maxCallDepth: 32,
+    maxLoopIterations: 1,
+    maxStringLength: 64 * 1024,
+    maxArrayElements: 4_096,
+    maxOutputSize: 64 * 1024,
+};
+/** Build the document. PURE and total — never throws, whatever a normalizer produced. */
+export function filterDocument(ev) {
+    const scope = {};
+    for (const kind of SCOPE_KINDS) {
+        const id = scopeIdOf(ev.scope, kind);
+        if (id !== undefined)
+            scope[kind] = id;
+    }
+    return {
+        source: ev.source,
+        scheme: webhookScheme(ev),
+        event: ev.event,
+        action: ev.action ?? null,
+        fields: ev.fields,
+        scope,
+        scopePath: ev.scope.map((s) => ({ kind: s.kind, id: s.id })),
+        deliveryId: ev.deliveryId ?? null,
+        occurredAt: ev.occurredAt ?? null,
+        redacted: ev.redacted === true,
+    };
+}
+/**
+ * A canonical document with the right SHAPE and the maximum legal SIZE, used by
+ * {@link probeFilterCost}. Full-size on purpose: a probe against an empty document would under-report
+ * the cost of anything that walks `fields`, and under-reporting is the only way this gate can be
+ * wrong in the dangerous direction.
+ */
+function probeDocument(source, matchKeys) {
+    const fields = {};
+    for (const k of matchKeys.slice(0, FIELDS_MAX_KEYS))
+        fields[k] = "x".repeat(FIELD_VALUE_MAX);
+    for (let i = Object.keys(fields).length; i < FIELDS_MAX_KEYS; i++)
+        fields[`probe_${i}`] = "x".repeat(FIELD_VALUE_MAX);
+    const scope = {};
+    for (const kind of SCOPE_KINDS)
+        scope[kind] = `probe-${kind}`;
+    return {
+        source,
+        scheme: source,
+        event: "probe",
+        action: "probe",
+        fields,
+        scope,
+        scopePath: SCOPE_KINDS.map((kind) => ({ kind, id: `probe-${kind}` })),
+        deliveryId: "probe",
+        occurredAt: new Date(0).toISOString(),
+        redacted: false,
+    };
+}
+/** Cap on the reason text carried into an audit row — jq's stderr is bounded, a stray value is not. */
+const REASON_MAX = 300;
+function reason(s) {
+    const one = s.replace(/\s+/g, " ").trim();
+    return one.length > REASON_MAX ? `${one.slice(0, REASON_MAX - 1)}…` : one;
+}
+/**
+ * Run one expression against one document.
+ *
+ * 🔴 THE EXPRESSION NEVER TOUCHES THE SHELL. It goes through `ExecOptions.args`, which just-bash
+ * appends to the command's argv AT THE INTERPRETER LEVEL — "values bypass shell parsing entirely, no
+ * escaping, splitting or globbing". Interpolating it into the command line instead is wrong twice
+ * over, and both were observed:
+ *   • CORRECTNESS — inside double quotes the shell expands `$x`, so `. as $x | $x == "y"` silently
+ *     became `. as | == "y"` and reported a parse error that made a working jq feature look missing.
+ *   • SAFETY — `$(…)` and backticks in a filter would be COMMAND SUBSTITUTION. `commands: ["jq"]`
+ *     already leaves nothing worth substituting, but relying on a command allow-list to contain an
+ *     injection is defence in the wrong place.
+ * Together these are why `args` is not an optimisation and must not be "simplified" back.
+ */
+async function runJq(expression, doc) {
+    const bash = new Bash({
+        files: { [DOC_PATH]: JSON.stringify(doc) },
+        // ONE command exists. Everything else — cat, curl, sh, python3, js-exec, echo — is "command not
+        // found", so even a hypothetical escape from the argv bypass reaches nothing.
+        commands: ["jq"],
+        env: {},
+        executionLimits: JQ_LIMITS,
+    });
+    const r = await bash.exec("jq -c", { args: [expression, DOC_PATH] });
+    return { code: r.exitCode, stdout: r.stdout, stderr: r.stderr };
+}
+/**
+ * EVALUATE. The whole match/no-match contract lives here and is FAIL-CLOSED at every arm:
+ *
+ *   stdout `true`  + exit 0  ⇒ MATCH.
+ *   stdout `false` + exit 0  ⇒ no match.
+ *   anything else            ⇒ `{error}` — the caller skips AND records why. Parse error, unknown
+ *                              function, an iteration limit, no output at all (`empty`), MORE than
+ *                              one output (`(true, false)`), or a non-boolean (`"opened"`, `null`,
+ *                              `1`).
+ *
+ * ⚠️ WE READ STDOUT, NOT `jq -e`'s EXIT CODE, and that is deliberate. `-e` returns 1 for both
+ * `false` and `null`, which collapses "the predicate said no" into "the predicate is broken" — and
+ * telling those two apart is the entire point of recording misses (§2.7: *"why didn't my routine
+ * fire"* is the most common webhook question). Reading the value keeps them distinct.
+ */
+export async function evaluateJqFilter(expression, doc) {
+    let r;
+    try {
+        r = await runJq(expression, doc);
+    }
+    catch (err) {
+        // The interpreter itself failed (an unsupported construct blowing the JS stack has been seen
+        // here). Never propagates: this runs inside a per-delivery fan-out where a throw would take out
+        // every OTHER routine's fire as collateral.
+        return { error: reason(`filter could not be evaluated: ${err instanceof Error ? err.message : String(err)}`) };
+    }
+    const out = r.stdout.trim();
+    if (r.code !== 0) {
+        const why = r.stderr.trim() || out || `jq exited ${r.code}`;
+        return { error: reason(why.replace(/^jq:\s*/, "")) };
+    }
+    if (out === "true")
+        return { match: true };
+    if (out === "false")
+        return { match: false };
+    if (out === "")
+        return { error: "filter produced no output — a subscription filter must evaluate to exactly true or false" };
+    if (out.includes("\n"))
+        return { error: `filter produced ${out.split("\n").length} results — a subscription filter must evaluate to exactly one boolean` };
+    return { error: reason(`filter produced ${out}, which is not true or false — a subscription filter must be a boolean predicate`) };
+}
+/**
+ * STATIC checks: everything knowable without running anything. THROWS, naming what is wrong — the
+ * house create-time refusal pattern (`entity-actions.ts`, `channel-read.ts`).
+ */
+export function assertFilterShape(expression) {
+    if (typeof expression !== "string" || expression.trim().length === 0) {
+        throw new Error("A subscription filter must be a non-empty jq expression, e.g. `.event == \"pull_request\"`.");
+    }
+    if (expression.length > FILTER_MAX_LENGTH) {
+        throw new Error(`A subscription filter is at most ${FILTER_MAX_LENGTH} characters (got ${expression.length}) — past that it stops being a predicate anyone can check on an approval card.`);
+    }
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u001f\u007f]/.test(expression)) {
+        throw new Error("A subscription filter must not contain control characters.");
+    }
+}
+/**
+ * CREATE-TIME COMPILE + COST PROBE. Runs the expression once against {@link probeDocument} and
+ * refuses anything that cannot be a working predicate, with jq's own message.
+ *
+ * WHY RUN IT RATHER THAN PARSE IT. There is no exposed parse-only entry point, and there does not
+ * need to be: running it is ~1 ms, and it catches strictly more — an unknown function
+ * (`input_filename`), an expression that is syntactically fine but yields a string, one that yields
+ * two values, one that blows an iteration limit. Every one of those would otherwise arm a routine
+ * that can never fire and never says so, which is the SILENT-NO-OP class this plane exists to kill.
+ *
+ * WHY A NON-BOOLEAN PROBE RESULT IS NOT REFUSED. `probeDocument` is synthetic, so a perfectly good
+ * predicate can legitimately return `false` — but one that returns a STRING on it is broken for
+ * every real delivery too, so that IS refused. `null` is refused for the same reason. What is
+ * accepted is exactly `true`/`false`.
+ */
+export async function probeFilter(expression, source, matchKeys) {
+    assertFilterShape(expression);
+    const doc = probeDocument(source, matchKeys);
+    // FIRST RUN IS THE CORRECTNESS RUN, and its timing is thrown away — see PROBE_RUNS.
+    const outcome = await evaluateJqFilter(expression, doc);
+    if ("error" in outcome) {
+        throw new Error(`That filter isn't a usable jq predicate on "${source}": ${outcome.error}. ` +
+            `A filter is a jq expression over the event that must evaluate to true or false, e.g. \`.event == "pull_request" and (.fields.action | IN("opened","reopened"))\`. ` +
+            `The event exposes .event, .action, .source, .fields.<name> and .scope.<${SCOPE_KINDS.join("|")}>.`);
+    }
+    let elapsed = Number.POSITIVE_INFINITY;
+    for (let i = 0; i < PROBE_RUNS; i++) {
+        const started = Date.now();
+        await evaluateJqFilter(expression, doc);
+        elapsed = Math.min(elapsed, Date.now() - started);
+    }
+    if (elapsed > FILTER_PROBE_BUDGET_MS) {
+        throw new Error(`That filter took ${elapsed}ms to evaluate, over the ${FILTER_PROBE_BUDGET_MS}ms limit — it would run on every delivery this source makes. Express it as a comparison over .fields / .scope rather than a search over the whole document.`);
+    }
+}
+//# sourceMappingURL=jq-filter.js.map

package/dist/agent/routines/jq-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jq-filter.js","sourceRoot":"","sources":["../../../agent/routines/jq-filter.ts"],"names":[],"mappings":"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"}

package/dist/agent/routines/lifecycle.d.ts

@@ -0,0 +1,101 @@
+import { type Routine, type RunOutcome } from "./routine.js";
+/** Default consecutive-failure threshold before a routine self-disables. */
+export declare const MAX_CONSECUTIVE_FAILURES = 3;
+/**
+ * OPE-506 — Tag's policy, adopted verbatim: 3 consecutive failures is not enough on its own. The
+ * streak must also SPAN at least this long, so a fast cadence failing 3 times in a couple of
+ * minutes does not disable on a blip the way a routine failing 3 times across 3 hours should. One
+ * hour, matching a design note §S2 ("after three consecutive
+ * failed runs spanning at least an hour"). A `once` trigger is exempt — see {@link applyOutcome}'s
+ * once-branch, which disables on its FIRST failure and needs no span at all.
+ */
+export declare const MIN_CONSECUTIVE_FAILURE_SPAN_MS: number;
+/**
+ * Fold a run outcome into a routine's state and apply self-disable. Returns a
+ * NEW routine (the store round-trips whole objects). `nextRunAt` is set by the
+ * caller (it owns the clock); this only touches outcome/failure/disable state.
+ *
+ * - ok       -> resets the failure counter.
+ * - skipped  -> records it, does NOT count as a failure (e.g. a ✅-reaction skip
+ *               or a watch that saw no change). Proactivity shouldn't punish a
+ *               correct "nothing to do".
+ * - failed   -> increments; at the threshold AND once the streak has spanned
+ *               {@link MIN_CONSECUTIVE_FAILURE_SPAN_MS}, the routine disables itself so a broken
+ *               routine can't spam a channel forever (OPE-506).
+ *
+ * A `once` TRIGGER IS TERMINAL AFTER ITS ONE FIRE, REGARDLESS OF OUTCOME (OPE-506) — a one-shot
+ * never gets a second scheduled instant (`computeNextRun` always returns null for it), so leaving
+ * it `active` would read as a stuck routine. Unlike the pre-OPE-506 shape (which the dispatcher
+ * disabled BEFORE the outcome was known, with a generic "fired" reason that a failure could never
+ * overwrite) this now happens HERE, after the real outcome has settled, so a failed one-shot's
+ * `disabledReason` says so — "disables on its first failure with the reason recorded", verbatim.
+ */
+export declare function applyOutcome(routine: Routine, outcome: RunOutcome, ranAt: Date, maxFailures?: number): Routine;
+/** The verdict {@link completeJob} returns — either the retired routine, or a structured reason it
+ *  couldn't complete (so the tool maps each to an instructive error / idempotent success). */
+export type JobCompletion = {
+    readonly kind: "completed";
+    readonly routine: Routine;
+} | {
+    readonly kind: "already-done";
+    readonly routine: Routine;
+} | {
+    readonly kind: "not-a-job";
+};
+/**
+ * Retire a DURABLE JOB (OPE-55): flip it to the terminal `done` status, stamp completedAt/Reason,
+ * and null its next run so the dispatcher never fires it again. PURE + IDEMPOTENT — completing an
+ * already-`done` job is a no-op success (returns the unchanged row), and completing a NON-job
+ * routine is a structured `not-a-job` error (a stateless routine has no job to complete; use
+ * cancel_routine). The row is KEPT (never deleted) for audit/list visibility, like a `once` fire.
+ */
+export declare function completeJob(routine: Routine, reason: string, at: Date): JobCompletion;
+/**
+ * Settle a session-end outcome against what the run itself recorded. The outcome
+ * hook only sees ok/failed (session lifecycle events), but a run can record its own
+ * verdict mid-turn and a clean completion must not overwrite it:
+ *
+ *   - `skipped` — a watch run that saw no change, via `record_watch_state`. A clean
+ *     completion keeps the skip rather than claiming "ok".
+ *   - `failed` — a DECLARED SEMANTIC failure (OPE-177), via `report_run_failed`. This is
+ *     the arm that closes "the routine that reports 'I couldn't reach the API' every run and
+ *     completes cleanly forever": from the session's point of view that turn SUCCEEDED, so
+ *     `sessionOutcome` is "ok" and only the declaration can say otherwise. It WINS over a
+ *     clean completion — a run that declared failure and then tidied up is still a failed run.
+ *
+ * Safe because the dispatcher clears `lastOutcome` (and `lastFailureReason`) on every fire: a
+ * recorded outcome present at session end was written during THIS run, never a stale one. A
+ * session-level failure always wins too (a run that broke after recording its observation still
+ * counts as failed), so the only ordering that matters is declaration-beats-clean-completion.
+ */
+export declare function settleOutcome(sessionOutcome: "ok" | "failed", recorded: RunOutcome | undefined): RunOutcome;
+/**
+ * Fold one DECLARED failure (OPE-177) into a routine. Pure: normalisation here, persistence in the
+ * `report_run_failed` tool — the same split as applyWatchObservation / applyJobStateObservation.
+ *
+ * TRUNCATES rather than rejects. `record_job_state` rejects an oversize ledger because a truncated
+ * ledger is a CORRUPTED one; a truncated one-line reason is still a usable reason, and refusing the
+ * declaration would leave the run recorded as a success — which is the whole defect. Whitespace is
+ * collapsed for the same reason disable-notice.ts collapses a prompt: this lands in an audit row
+ * next to a routine id, not in a document.
+ *
+ * The patch deliberately writes BOTH fields: `lastOutcome: "failed"` is what {@link settleOutcome}
+ * reads at session end, and the reason is what rides onto the forensic rows. Writing one without the
+ * other would be the half-mechanism this ticket exists to avoid.
+ */
+export declare function declareRunFailed(reason: string): {
+    readonly reason: string;
+    readonly patch: Partial<Routine>;
+};
+/**
+ * A `watch` routine should post only when the watched state changed. Given the
+ * previously stored hash and the new one, should it act? (First observation —
+ * no prior hash — counts as a change so the baseline is reported once.)
+ */
+export declare function shouldPostOnDiff(prevHash: string | undefined, newHash: string): boolean;
+/**
+ * Tiny deterministic, dependency-free string hash (djb2/33) as hex. Used to
+ * fingerprint a watch's observed state for cheap diffing. Not cryptographic.
+ */
+export declare function hashState(s: string): string;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/agent/routines/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../agent/routines/lifecycle.ts"],"names":[],"mappings":"AAYA,OAAO,EAAgC,KAAK,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAE3F,4EAA4E;AAC5E,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,QAAc,CAAC;AAwC3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE,IAAI,EACX,WAAW,SAA2B,GACrC,OAAO,CA2CT;AAED;8FAC8F;AAC9F,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC;AAEnC;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,GAAG,aAAa,CAerF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,cAAc,EAAE,IAAI,GAAG,QAAQ,EAAE,QAAQ,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,CAG3G;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,CAO9G;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvF;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI3C"}