@cat-factory/orchestration 0.229.0 → 0.231.0

package/dist/modules/execution/prReport.steps.js

@@ -1,4 +1,5 @@
 import { hostMarkdown } from '@cat-factory/kernel';
+import { selectEvidenceStep } from '@cat-factory/contracts';
 // ---------------------------------------------------------------------------
 // Step selection for the PR verification report: which step of a run a section reports on.
 //
@@ -16,14 +17,13 @@ import { hostMarkdown } from '@cat-factory/kernel';
  * `ci` gate after the coder and another after the tester, say), and the later run is the one
  * that describes the PR head as it stands now. Reporting the first would pin the section to a
  * verdict two steps of work out of date.
+ *
+ * The rule itself is `selectEvidenceStep` in `@cat-factory/contracts`, shared with the run
+ * outcome summary so the two documents cannot quote different sessions of the same run; this is
+ * the instance-shaped adapter every call site here already reads through.
  */
 export function findStep(instance, matches, hasEvidence) {
-    const matching = instance.steps.filter(matches);
-    for (let i = matching.length - 1; i >= 0; i--) {
-        if (hasEvidence(matching[i]))
-            return matching[i];
-    }
-    return matching[0];
+    return selectEvidenceStep(instance.steps, matches, hasEvidence);
 }
 /**
  * Render an ABSENT section's note: the ONE line every section emits in place of its evidence.

package/dist/modules/execution/prReport.steps.js.map

@@ -1 +1 @@
-{"version":3,"file":"prReport.steps.js","sourceRoot":"","sources":["../../../src/modules/execution/prReport.steps.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAElD,8EAA8E;AAC9E,2FAA2F;AAC3F,EAAE;AACF,6FAA6F;AAC7F,+FAA+F;AAC/F,gGAAgG;AAChG,oCAAoC;AACpC,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CACtB,QAA2B,EAC3B,OAAwC,EACxC,WAA4C;IAE5C,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IAC/C,KAAK,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,IAAI,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAE,CAAC;YAAE,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAA;IACnD,CAAC;IACD,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAA;AACpB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,IAA+B;IACxD,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,IAAI,IAAI,eAAe,CAAC,GAAG,CAAA;AAC3D,CAAC"}
+{"version":3,"file":"prReport.steps.js","sourceRoot":"","sources":["../../../src/modules/execution/prReport.steps.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAE3D,8EAA8E;AAC9E,2FAA2F;AAC3F,EAAE;AACF,6FAA6F;AAC7F,+FAA+F;AAC/F,gGAAgG;AAChG,oCAAoC;AACpC,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,QAAQ,CACtB,QAA2B,EAC3B,OAAwC,EACxC,WAA4C;IAE5C,OAAO,kBAAkB,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,CAAA;AACjE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,IAA+B;IACxD,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,IAAI,IAAI,eAAe,CAAC,GAAG,CAAA;AAC3D,CAAC"}

package/dist/modules/execution/runOutcome.boundary.d.ts

@@ -0,0 +1,11 @@
+import type { RunOutcome } from '@cat-factory/contracts';
+/**
+ * The outcome summary as a public response body: scrubbed, clamped, bounded, and honest about
+ * every drop.
+ *
+ * Rebuilt field by field rather than spread over the composed value, so a section added to
+ * {@link RunOutcome} fails THIS build until someone has decided what its boundary treatment is.
+ * A spread would have carried it out unscrubbed and compiled.
+ */
+export declare function boundOutcomeForApi(outcome: RunOutcome): RunOutcome;
+//# sourceMappingURL=runOutcome.boundary.d.ts.map

package/dist/modules/execution/runOutcome.boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runOutcome.boundary.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/runOutcome.boundary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAMV,UAAU,EACX,MAAM,wBAAwB,CAAA;AA2J/B;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,CAwBlE"}

package/dist/modules/execution/runOutcome.boundary.js

@@ -0,0 +1,163 @@
+import { redactSecrets } from '@cat-factory/kernel';
+// ---------------------------------------------------------------------------
+// The BOUNDARY treatment for the run outcome summary on its way out over
+// `GET /api/v1/runs/:runId/outcome`.
+//
+// `composeRunOutcome` lives in `@cat-factory/contracts` because the SPA composes the same
+// reduction live off its own store, and it is deliberately un-scrubbed and un-clamped for the
+// same reason `run-evidence.ts` says its join is: handing the SPA escaped entities and elided
+// prose would degrade the surface that renders into a DOM for a member who is already inside the
+// workspace. What crosses the wire to an API key is a different exposure, and it is the one the
+// verification report has always treated as such: the same tester summary, the same per-verdict
+// evidence and the same spec titles are scrubbed and clamped on their way onto a pull request
+// body and out of `GET /api/v1/runs/:runId/report`. Serving them verbatim beside that endpoint
+// would have made the weaker of the two the one an integration reads.
+//
+// Two things happen here, in this order, and the order is the point:
+//
+//  1. **Scrub, at COMPOSE time, before any truncation** (the repo-wide rule): a model routinely
+//     echoes a request URL or an auth header into its prose, and clamping first would leave half
+//     a token in the payload with nothing to say it had been cut.
+//  2. **BOUND what is unbounded**, recording every drop in `truncations`. A response whose size
+//     is set by how much a model chose to write is not a contract a consumer can hold; a
+//     response that says what it withheld is.
+//
+// Nothing here decides anything. Every count in the payload is computed over the WHOLE join
+// before this function sees it, so a bounded rendering still reports the true totals: the caps
+// touch what is SHOWN, never what is COUNTED.
+// ---------------------------------------------------------------------------
+/**
+ * How much of one free-text field survives. Sized for a field a person reads whole (a tester's
+ * observation against one requirement, its session summary), not for a transcript: a producer
+ * that wrote more than this has written a document, and the endpoint that serves documents is
+ * `/report`.
+ */
+const MAX_TEXT_CHARS = 2_000;
+/**
+ * How many requirement rows one response carries. Above any real service's `spec/` (the largest
+ * in this repo's own fixtures is two orders below it), so the cap is a ceiling on a pathological
+ * case rather than a routine truncation, and `truncations` names it on the runs that hit it.
+ */
+const MAX_REQUIREMENT_ENTRIES = 500;
+/** How many tester areas and concerns one response carries. Same reasoning as the rows. */
+const MAX_TESTER_LIST = 200;
+/** Scrub, then clamp. Null in, null out: an absent value is not an empty one. */
+function text(value) {
+    const scrubbed = redactSecrets(value) ?? null;
+    if (scrubbed == null)
+        return null;
+    return scrubbed.length <= MAX_TEXT_CHARS ? scrubbed : `${scrubbed.slice(0, MAX_TEXT_CHARS - 1)}…`;
+}
+/** The same treatment where the field is non-nullable. */
+function required(value) {
+    return text(value) ?? '';
+}
+/** The ONE shape a truncation note takes, matching the verification report's own vocabulary. */
+function note(label, kept, total, detail) {
+    return `${label}: showing ${kept} of ${total}${detail ? ` (${detail})` : ''}`;
+}
+/** Cap a list, recording what it dropped. */
+function cap(items, label, truncations, max, detail) {
+    if (items.length <= max)
+        return [...items];
+    truncations.push(note(label, max, items.length, detail));
+    return items.slice(0, max);
+}
+function boundRequirement(entry) {
+    return {
+        id: required(entry.id),
+        title: text(entry.title),
+        verdict: entry.verdict,
+        detail: text(entry.detail),
+        state: entry.state,
+        regression: entry.regression,
+    };
+}
+function boundRequirements(requirements, truncations) {
+    if (requirements.status === 'absent')
+        return requirements;
+    return {
+        status: 'reported',
+        spec: requirements.spec,
+        met: requirements.met,
+        notMet: requirements.notMet,
+        notCovered: requirements.notCovered,
+        regressions: requirements.regressions,
+        total: requirements.total,
+        unmatchedVerdicts: requirements.unmatchedVerdicts,
+        // The rows arrive ordered by SEVERITY, so a cap keeps the regressions and failures and drops
+        // the least severe tail. Said in the note, because a reader who assumed the spec's own order
+        // would conclude the missing requirements were never ruled on.
+        entries: cap(requirements.entries, 'requirements.entries', truncations, MAX_REQUIREMENT_ENTRIES, 'ordered by severity, so the rows dropped are the least severe').map(boundRequirement),
+    };
+}
+function boundConcern(concern) {
+    return { title: required(concern.title), severity: concern.severity };
+}
+function boundTests(tests, truncations) {
+    if (tests.status === 'absent')
+        return tests;
+    return {
+        status: 'reported',
+        verdict: tests.verdict,
+        summary: text(tests.summary),
+        abortReason: text(tests.abortReason),
+        areas: cap(tests.areas, 'tests.areas', truncations, MAX_TESTER_LIST).map(required),
+        passed: tests.passed,
+        failed: tests.failed,
+        skipped: tests.skipped,
+        concerns: cap(tests.concerns, 'tests.concerns', truncations, MAX_TESTER_LIST).map(boundConcern),
+        // The environment is a closed shape of platform-recorded identifiers, not model prose.
+        environment: tests.environment,
+    };
+}
+function boundVisuals(visuals) {
+    if (visuals.status === 'absent') {
+        return { status: 'absent', gap: visuals.gap, detail: text(visuals.detail) };
+    }
+    return {
+        status: 'reported',
+        source: visuals.source,
+        phase: visuals.phase,
+        // Bounded by the capture path, which caps how many views one run may store.
+        views: visuals.views.map((view) => ({
+            view: required(view.view),
+            artifactId: view.artifactId,
+            referenceArtifactId: view.referenceArtifactId,
+        })),
+    };
+}
+/**
+ * The outcome summary as a public response body: scrubbed, clamped, bounded, and honest about
+ * every drop.
+ *
+ * Rebuilt field by field rather than spread over the composed value, so a section added to
+ * {@link RunOutcome} fails THIS build until someone has decided what its boundary treatment is.
+ * A spread would have carried it out unscrubbed and compiled.
+ */
+export function boundOutcomeForApi(outcome) {
+    const truncations = [...outcome.truncations];
+    return {
+        version: outcome.version,
+        disposition: outcome.disposition,
+        title: required(outcome.title),
+        ask: text(outcome.ask),
+        pullRequests: outcome.pullRequests.map((pr) => ({
+            url: required(pr.url),
+            number: pr.number,
+            branch: text(pr.branch),
+            repo: text(pr.repo),
+        })),
+        requirements: boundRequirements(outcome.requirements, truncations),
+        tests: boundTests(outcome.tests, truncations),
+        visuals: boundVisuals(outcome.visuals),
+        // A closed vocabulary of enum members and one nullable enum: nothing here is authored text.
+        checks: outcome.checks.map((check) => ({
+            kind: check.kind,
+            state: check.state,
+            reproduction: check.reproduction,
+        })),
+        truncations,
+    };
+}
+//# sourceMappingURL=runOutcome.boundary.js.map

package/dist/modules/execution/runOutcome.boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runOutcome.boundary.js","sourceRoot":"","sources":["../../../src/modules/execution/runOutcome.boundary.ts"],"names":[],"mappings":"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"}

package/dist/modules/observability/retentionPass.d.ts

@@ -45,73 +45,6 @@ export declare function createRetentionPass(logger?: Logger): RetentionPass;
  * history. Shared by both facades so the two cannot drift on how much they heal.
  */
 export declare const RUN_DAY_ROLLUP_LOOKBACK_MS: number;
-/** How far back a steady-state spend-rollup pass recomputes, for the reason above. */
-export declare const SPEND_DAY_ROLLUP_LOOKBACK_MS: number;
-/**
- * The most a SINGLE spend-rollup pass will aggregate. The catch-up walk below can ask for an
- * arbitrarily wide window (a deployment that has never rolled up, a sweep down for a week),
- * and one unbounded `GROUP BY` over a busy deployment's whole ledger is how a cron pass turns
- * into a row-limit error on D1 or a long-running query on Postgres, which would then fail on
- * every subsequent pass too, since the window only widens.
- */
-export declare const SPEND_DAY_ROLLUP_MAX_SPAN_MS: number;
-/**
- * How far back the FIRST pass on a deployment reaches. The rollup serves the 90-day report
- * window, so a rollup that started at "today" would under-report that window for a quarter
- * while looking complete: the ledger holds the data, and the reader has no way to see that
- * the newer store simply had not been asked yet. Older history than this is deliberately not
- * backfilled: `rolledUpThrough` states where the durable record begins.
- *
- * It also serves as the FLOOR under a resumed pass when the ledger has no retention window of
- * its own to derive one from. See {@link spendRollupWindow}.
- */
-export declare const SPEND_DAY_ROLLUP_BACKFILL_MS: number;
-/** One spend-rollup pass's window, plus whatever it had to give up on to produce it. */
-export interface SpendRollupWindow {
-    from: number;
-    to: number;
-    /**
-     * The span the catch-up horizon dropped, or null when the walk covers everything the last
-     * pass left. NON-NULL IS A PERMANENT DATA GAP, not a deferral: nothing re-offers these days
-     * to a later pass, and the watermark advances past them. Whoever calls this must SAY so:
-     * `through_day` is a high-water mark and cannot represent a hole, so the log line is the
-     * only place the hole is ever named.
-     */
-    skipped: {
-        from: number;
-        to: number;
-    } | null;
-}
-/**
- * The window one spend-rollup pass should materialise, given what the last pass covered and
- * how long the LEDGER it folds is retained.
- *
- * Unlike the run rollup, which recomputes a fixed trailing lookback, this one walks FORWARD
- * from the sweep's own watermark. The difference is that a gap here is permanent: nothing
- * else retains the attribution the rollup is folding, so a day the sweep skipped while it was
- * down is a day whose TCO history is simply missing, forever. Resuming from the watermark
- * turns "the sweep was down for a week" into a few catch-up passes instead.
- *
- * Which is why the catch-up horizon is derived from `ledgerRetentionMs` rather than reusing
- * the backfill constant. The two answer different questions and only look alike. The backfill
- * bounds a FIRST pass, where the choice is how much history to adopt and 90 days is a
- * judgement call. A resumed pass has no such choice: every day between the watermark and now
- * is a day this deployment has already committed to recording, and the ledger still HOLDS it
- * (the prune runs in this same sweep, so a sweep that was down pruned nothing either). A
- * horizon shorter than the ledger's own retention would step over those days while they were
- * still readable, which is losing data that was there for the asking. Past the ledger's
- * retention there is genuinely nothing left to fold, so that is where the walk stops, and the
- * pathological watermark the horizon exists to contain (hand-edited, restored from a backup,
- * epoch-zero) is still contained.
- *
- * Pure so both facades share it (and so the walk is unit-testable without a database): the
- * caller reads the watermark, calls this, materialises `[from, to)`, and reports `skipped`.
- *
- * @param ledgerRetentionMs how long `token_usage` is kept; 0 or less means the ledger is
- *   never pruned, in which case there is no retention edge to derive a horizon from and the
- *   backfill constant is the floor.
- */
-export declare function spendRollupWindow(throughDay: number | null, now: number, ledgerRetentionMs: number): SpendRollupWindow;
 /**
  * One sweep's spend-rollup step, shared by both facades: read the watermark, walk the window,
  * materialise it, and NAME any span the catch-up horizon had to give up on.

package/dist/modules/observability/retentionPass.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retentionPass.d.ts","sourceRoot":"","sources":["../../../src/modules/observability/retentionPass.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,qBAAqB,EAAiB,MAAM,qBAAqB,CAAA;AAiB5F,0FAA0F;AAC1F,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,KAAK,CACH,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GACvC,OAAO,CAAC,MAAM,CAAC,CAAA;IAClB;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAClE;;;;;;;;;OASG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACzE;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAC1B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAyBlE;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,QAAuB,CAAA;AAE9D,sFAAsF;AACtF,eAAO,MAAM,4BAA4B,QAAuB,CAAA;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,QAAwB,CAAA;AAEjE;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B,QAAwB,CAAA;AAEjE,wFAAwF;AACxF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV;;;;;;OAMG;IACH,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,GAAG,EAAE,MAAM,EACX,iBAAiB,EAAE,MAAM,GACxB,iBAAiB,CAmBnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,aAAa,EACnB,UAAU,EAAE,IAAI,CAAC,qBAAqB,EAAE,iBAAiB,GAAG,sBAAsB,CAAC,EACnF,GAAG,EAAE,MAAM,EACX,iBAAiB,EAAE,MAAM,EACzB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAwBjB"}
+{"version":3,"file":"retentionPass.d.ts","sourceRoot":"","sources":["../../../src/modules/observability/retentionPass.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EACX,KAAK,qBAAqB,EAG3B,MAAM,qBAAqB,CAAA;AAiB5B,0FAA0F;AAC1F,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,KAAK,CACH,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GACvC,OAAO,CAAC,MAAM,CAAC,CAAA;IAClB;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAClE;;;;;;;;;OASG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACzE;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAC1B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAyBlE;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,QAAuB,CAAA;AAE9D;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,aAAa,EACnB,UAAU,EAAE,IAAI,CAAC,qBAAqB,EAAE,iBAAiB,GAAG,sBAAsB,CAAC,EACnF,GAAG,EAAE,MAAM,EACX,iBAAiB,EAAE,MAAM,EACzB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAwBjB"}

package/dist/modules/observability/retentionPass.js

@@ -1,4 +1,4 @@
-import { describeError } from '@cat-factory/kernel';
+import { describeError, spendRollupWindow, } from '@cat-factory/kernel';
 /**
  * Start one isolated retention pass. Create a new one per sweep (the {@link RetentionPass.failed}
  * list is per-pass state), then read `failed` after the last table.
@@ -40,75 +40,6 @@ export function createRetentionPass(logger) {
  * history. Shared by both facades so the two cannot drift on how much they heal.
  */
 export const RUN_DAY_ROLLUP_LOOKBACK_MS = 3 * 24 * 60 * 60_000;
-/** How far back a steady-state spend-rollup pass recomputes, for the reason above. */
-export const SPEND_DAY_ROLLUP_LOOKBACK_MS = 3 * 24 * 60 * 60_000;
-/**
- * The most a SINGLE spend-rollup pass will aggregate. The catch-up walk below can ask for an
- * arbitrarily wide window (a deployment that has never rolled up, a sweep down for a week),
- * and one unbounded `GROUP BY` over a busy deployment's whole ledger is how a cron pass turns
- * into a row-limit error on D1 or a long-running query on Postgres, which would then fail on
- * every subsequent pass too, since the window only widens.
- */
-export const SPEND_DAY_ROLLUP_MAX_SPAN_MS = 30 * 24 * 60 * 60_000;
-/**
- * How far back the FIRST pass on a deployment reaches. The rollup serves the 90-day report
- * window, so a rollup that started at "today" would under-report that window for a quarter
- * while looking complete: the ledger holds the data, and the reader has no way to see that
- * the newer store simply had not been asked yet. Older history than this is deliberately not
- * backfilled: `rolledUpThrough` states where the durable record begins.
- *
- * It also serves as the FLOOR under a resumed pass when the ledger has no retention window of
- * its own to derive one from. See {@link spendRollupWindow}.
- */
-export const SPEND_DAY_ROLLUP_BACKFILL_MS = 90 * 24 * 60 * 60_000;
-/**
- * The window one spend-rollup pass should materialise, given what the last pass covered and
- * how long the LEDGER it folds is retained.
- *
- * Unlike the run rollup, which recomputes a fixed trailing lookback, this one walks FORWARD
- * from the sweep's own watermark. The difference is that a gap here is permanent: nothing
- * else retains the attribution the rollup is folding, so a day the sweep skipped while it was
- * down is a day whose TCO history is simply missing, forever. Resuming from the watermark
- * turns "the sweep was down for a week" into a few catch-up passes instead.
- *
- * Which is why the catch-up horizon is derived from `ledgerRetentionMs` rather than reusing
- * the backfill constant. The two answer different questions and only look alike. The backfill
- * bounds a FIRST pass, where the choice is how much history to adopt and 90 days is a
- * judgement call. A resumed pass has no such choice: every day between the watermark and now
- * is a day this deployment has already committed to recording, and the ledger still HOLDS it
- * (the prune runs in this same sweep, so a sweep that was down pruned nothing either). A
- * horizon shorter than the ledger's own retention would step over those days while they were
- * still readable, which is losing data that was there for the asking. Past the ledger's
- * retention there is genuinely nothing left to fold, so that is where the walk stops, and the
- * pathological watermark the horizon exists to contain (hand-edited, restored from a backup,
- * epoch-zero) is still contained.
- *
- * Pure so both facades share it (and so the walk is unit-testable without a database): the
- * caller reads the watermark, calls this, materialises `[from, to)`, and reports `skipped`.
- *
- * @param ledgerRetentionMs how long `token_usage` is kept; 0 or less means the ledger is
- *   never pruned, in which case there is no retention edge to derive a horizon from and the
- *   backfill constant is the floor.
- */
-export function spendRollupWindow(throughDay, now, ledgerRetentionMs) {
-    // A `null` watermark is "no pass has ever completed", not "start from now": see the
-    // backfill constant. Once there IS one, the steady-state lookback still applies on top of
-    // it, so a day that was still accruing when it was covered gets recomputed rather than
-    // frozen half-counted.
-    const resume = throughDay == null
-        ? now - SPEND_DAY_ROLLUP_BACKFILL_MS
-        : Math.min(throughDay, now - SPEND_DAY_ROLLUP_LOOKBACK_MS);
-    const horizon = now - Math.max(ledgerRetentionMs, SPEND_DAY_ROLLUP_BACKFILL_MS);
-    // Never walk back past the horizon, and never aggregate more than one pass's worth in one
-    // query. A first pass is bounded by its own backfill choice, so only a RESUMED one can be
-    // cut here, and only that one has days it was already committed to.
-    const from = Math.max(resume, horizon);
-    return {
-        from,
-        to: Math.min(now, from + SPEND_DAY_ROLLUP_MAX_SPAN_MS),
-        skipped: throughDay != null && resume < horizon ? { from: resume, to: horizon } : null,
-    };
-}
 /**
  * One sweep's spend-rollup step, shared by both facades: read the watermark, walk the window,
  * materialise it, and NAME any span the catch-up horizon had to give up on.

package/dist/modules/observability/retentionPass.js.map

@@ -1 +1 @@
-{"version":3,"file":"retentionPass.js","sourceRoot":"","sources":["../../../src/modules/observability/retentionPass.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"retentionPass.js","sourceRoot":"","sources":["../../../src/modules/observability/retentionPass.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,aAAa,EACb,iBAAiB,GAClB,MAAM,qBAAqB,CAAA;AAqD5B;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAe;IACjD,MAAM,MAAM,GAAa,EAAE,CAAA;IAC3B,MAAM,OAAO,GAAG,KAAK,EAAE,KAAa,EAAE,GAA0B,EAAmB,EAAE;QACnF,IAAI,CAAC;YACH,OAAO,MAAM,GAAG,EAAE,CAAA;QACpB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YAClB,yFAAyF;YACzF,uFAAuF;YACvF,6DAA6D;YAC7D,MAAM,EAAE,IAAI,CAAC,0DAA0D,EAAE;gBACvE,KAAK,EAAE,WAAW;gBAClB,KAAK;gBACL,GAAG,aAAa,CAAC,KAAK,CAAC;aACxB,CAAC,CAAA;YACF,OAAO,CAAC,CAAA;QACV,CAAC;IACH,CAAC,CAAA;IACD,OAAO;QACL,KAAK,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,CACnC,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,GAAG,QAAQ,CAAC,CAAC;QAChF,MAAM,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;QAC3C,WAAW,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;QACpD,MAAM;KACP,CAAA;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,MAAM,CAAA;AAE9D;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,IAAmB,EACnB,UAAmF,EACnF,GAAW,EACX,iBAAyB,EACzB,MAAe;IAEf,OAAO,MAAM,IAAI,CAAC,WAAW,CAAC,YAAY,EAAE,KAAK,IAAI,EAAE;QACrD,MAAM,SAAS,GAAG,MAAM,UAAU,CAAC,oBAAoB,EAAE,CAAA;QACzD,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,iBAAiB,CAAC,SAAS,EAAE,GAAG,EAAE,iBAAiB,CAAC,CAAA;QAClF,IAAI,OAAO,EAAE,CAAC;YACZ,wFAAwF;YACxF,qFAAqF;YACrF,wFAAwF;YACxF,oDAAoD;YACpD,MAAM,EAAE,IAAI,CACV,0EAA0E;gBACxE,wCAAwC,EAC1C;gBACE,KAAK,EAAE,WAAW;gBAClB,KAAK,EAAE,YAAY;gBACnB,WAAW,EAAE,OAAO,CAAC,IAAI;gBACzB,SAAS,EAAE,OAAO,CAAC,EAAE;gBACrB,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC,CAAC;gBACzE,SAAS;aACV,CACF,CAAA;QACH,CAAC;QACD,OAAO,MAAM,UAAU,CAAC,eAAe,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IACnD,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/validation/validateRegistrations.d.ts

@@ -1,5 +1,5 @@
 import type { AgentKindRegistry } from '@cat-factory/agents';
-import type { BinaryGeneratorRegistry, FoundationalServiceRegistry, GateRegistry, InitiativePresetRegistry, PipelineRegistry, PromptFragmentRegistry, PromptFragmentSource, TaskTypeRegistry } from '@cat-factory/kernel';
+import type { BinaryGeneratorRegistry, DeploymentDocumentResolver, FoundationalServiceRegistry, GateRegistry, InitiativePresetRegistry, PipelineRegistry, PromptFragmentRegistry, PromptFragmentSource, TaskTypeRegistry } from '@cat-factory/kernel';
 /** A single problem found during validation. `error` aborts boot; `warn` is logged only. */
 export interface RegistrationProblem {
     severity: 'error' | 'warn';
@@ -87,6 +87,15 @@ export interface ValidatedRegistries {
      * never arrives.
      */
     promptFragments?: PromptFragmentSource;
+    /**
+     * How this deployment reads its OWN documents, or absent when it configured none.
+     *
+     * What turns the `documentRef` check below from a blanket refusal into a real one: a
+     * code-registered fragment may name a living document exactly when the deployment can resolve
+     * it, and only this can say whether it can. Named as the CONTAINER names it, like every other
+     * member here.
+     */
+    deploymentDocumentResolver?: DeploymentDocumentResolver;
 }
 /** Options for {@link collectRegistrationProblems} / {@link validateRegistrations}. */
 export interface ValidateRegistrationsOptions {
@@ -109,6 +118,30 @@ export interface ValidateRegistrationsOptions {
      * (errors still throw).
      */
     onWarn?: (problem: RegistrationProblem) => void;
+    /**
+     * Raise a `warn` to an ERROR: return `true` and the problem joins the aggregated boot failure
+     * instead of the log.
+     *
+     * The severities here are set by ONE bar: boot ERRORS on what is fully knowable from a
+     * registration and WARNS only where it structurally cannot see the answer (ADR 0040). That bar is
+     * about what the PLATFORM can know, and for one warn in particular the DEPLOYMENT knows more.
+     * `task_type_unknown_fragment` fires for two causes it cannot separate: a typo in a code-owned id,
+     * and an account/workspace-tier id that merges per workspace at run time and is invisible at boot.
+     * A deployment whose operations reference only fragments it registers itself knows the second
+     * cause cannot apply to it, and for that deployment the warn names a real defect: part of an
+     * operation's standing guidance silently never enters a run, and for a `conditionalFragmentIds`
+     * entry it goes missing only for the cases matching the condition.
+     *
+     * So the SEVERITY is platform judgement and the DISPOSITION is deployment policy, which is the
+     * split this hook exists to express. It takes the whole problem rather than a list of codes on
+     * purpose: a deployment can escalate one code, a prefix, or everything, and a warn added later is
+     * covered by a predicate that never mentioned it.
+     *
+     * Escalated problems are collected and thrown TOGETHER with the genuine errors, so a boot failure
+     * still names every problem at once. A predicate that throws is a bug in the predicate and
+     * propagates unchanged, rather than being swallowed into a warn about warnings.
+     */
+    escalateWarning?: (problem: RegistrationProblem) => boolean;
 }
 /**
  * Collect every registration problem (does not throw). Useful for tests and for callers that
@@ -119,6 +152,10 @@ export declare function collectRegistrationProblems(opts: ValidateRegistrationsO
  * Validate the registered extensions, throwing an aggregated error on any `error`-severity
  * problem and logging `warn`-severity ones. Call once at facade boot, after every `register*`
  * import side effect + provider wiring, before serving requests.
+ *
+ * A deployment may raise selected warnings to errors with
+ * {@link ValidateRegistrationsOptions.escalateWarning}; an escalated problem is thrown with the
+ * errors and is NOT also logged, so one problem produces one report.
  */
 export declare function validateRegistrations(opts: ValidateRegistrationsOptions): void;
 /** Run {@link validateRegistrations} at most once per process. Safe to call from a per-request build. */

package/dist/validation/validateRegistrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validateRegistrations.d.ts","sourceRoot":"","sources":["../../src/validation/validateRegistrations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,OAAO,KAAK,EAEV,uBAAuB,EACvB,2BAA2B,EAC3B,YAAY,EACZ,wBAAwB,EAGxB,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,qBAAqB,CAAA;AA+D5B,4FAA4F;AAC5F,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAA;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,iBAAiB,EAAE,iBAAiB,CAAA;IACpC;;;;OAIG;IACH,YAAY,EAAE,YAAY,CAAA;IAC1B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IACnC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IACnC;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,wBAAwB,CAAA;IACnD;;;;;;OAMG;IACH,2BAA2B,CAAC,EAAE,2BAA2B,CAAA;IACzD;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,uBAAuB,CAAA;IACjD;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,sBAAsB,CAAA;IAC/C;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,oBAAoB,CAAA;CACvC;AAED,uFAAuF;AACvF,MAAM,WAAW,4BAA4B;IAC3C,+EAA+E;IAC/E,UAAU,EAAE,mBAAmB,CAAA;IAC/B,qGAAqG;IACrG,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACxC,qGAAqG;IACrG,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACxC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACrC;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,IAAI,CAAA;CAChD;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,4BAA4B,GACjC,mBAAmB,EAAE,CA4FvB;AA6jCD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,4BAA4B,GAAG,IAAI,CAY9E;AAOD,yGAAyG;AACzG,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,4BAA4B,GAAG,IAAI,CASlF;AAED,uFAAuF;AACvF,wBAAgB,gCAAgC,IAAI,IAAI,CAEvD"}
+{"version":3,"file":"validateRegistrations.d.ts","sourceRoot":"","sources":["../../src/validation/validateRegistrations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,OAAO,KAAK,EAEV,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,EAC3B,YAAY,EACZ,wBAAwB,EAGxB,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,qBAAqB,CAAA;AAgE5B,4FAA4F;AAC5F,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAA;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,iBAAiB,EAAE,iBAAiB,CAAA;IACpC;;;;OAIG;IACH,YAAY,EAAE,YAAY,CAAA;IAC1B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IACnC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IACnC;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,wBAAwB,CAAA;IACnD;;;;;;OAMG;IACH,2BAA2B,CAAC,EAAE,2BAA2B,CAAA;IACzD;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,uBAAuB,CAAA;IACjD;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,sBAAsB,CAAA;IAC/C;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,oBAAoB,CAAA;IACtC;;;;;;;OAOG;IACH,0BAA0B,CAAC,EAAE,0BAA0B,CAAA;CACxD;AAED,uFAAuF;AACvF,MAAM,WAAW,4BAA4B;IAC3C,+EAA+E;IAC/E,UAAU,EAAE,mBAAmB,CAAA;IAC/B,qGAAqG;IACrG,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACxC,qGAAqG;IACrG,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACxC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IACrC;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,IAAI,CAAA;IAC/C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAA;CAC5D;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,4BAA4B,GACjC,mBAAmB,EAAE,CA4FvB;AA+kCD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,4BAA4B,GAAG,IAAI,CAuB9E;AAOD,yGAAyG;AACzG,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,4BAA4B,GAAG,IAAI,CASlF;AAED,uFAAuF;AACvF,wBAAgB,gCAAgC,IAAI,IAAI,CAEvD"}