@opensip-cli/contracts 0.1.0

package/dist/recipe-default.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { BUILTIN_DEFAULT_RECIPE, resolveToolRecipeName } from './recipe-default.js';
+describe('resolveToolRecipeName (ADR-0022 precedence + tolerance)', () => {
+    it('explicit --recipe wins over every config source and is strict', () => {
+        expect(resolveToolRecipeName({
+            explicit: 'backend',
+            toolRecipe: 'graph-core',
+        })).toEqual({ name: 'backend', source: 'flag', tolerant: false });
+    });
+    it('falls to <tool>.recipe when no flag, and is tolerant', () => {
+        expect(resolveToolRecipeName({ toolRecipe: 'graph-core' })).toEqual({
+            name: 'graph-core',
+            source: 'tool-config',
+            tolerant: true,
+        });
+    });
+    it('returns the builtin default when nothing is configured', () => {
+        expect(resolveToolRecipeName({})).toEqual({
+            name: BUILTIN_DEFAULT_RECIPE,
+            source: 'builtin',
+            tolerant: true,
+        });
+    });
+    it('treats empty-string config values as unset (precedence skips them)', () => {
+        expect(resolveToolRecipeName({ explicit: '', toolRecipe: '' })).toEqual({
+            name: BUILTIN_DEFAULT_RECIPE,
+            source: 'builtin',
+            tolerant: true,
+        });
+    });
+});
+//# sourceMappingURL=recipe-default.test.js.map

package/dist/recipe-default.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipe-default.test.js","sourceRoot":"","sources":["../src/recipe-default.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEpF,QAAQ,CAAC,yDAAyD,EAAE,GAAG,EAAE;IACvE,EAAE,CAAC,+DAA+D,EAAE,GAAG,EAAE;QACvE,MAAM,CACJ,qBAAqB,CAAC;YACpB,QAAQ,EAAE,SAAS;YACnB,UAAU,EAAE,YAAY;SACzB,CAAC,CACH,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,CAAC,qBAAqB,CAAC,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;YAClE,IAAI,EAAE,YAAY;YAClB,MAAM,EAAE,aAAa;YACrB,QAAQ,EAAE,IAAI;SACf,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wDAAwD,EAAE,GAAG,EAAE;QAChE,MAAM,CAAC,qBAAqB,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;YACxC,IAAI,EAAE,sBAAsB;YAC5B,MAAM,EAAE,SAAS;YACjB,QAAQ,EAAE,IAAI;SACf,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oEAAoE,EAAE,GAAG,EAAE;QAC5E,MAAM,CAAC,qBAAqB,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;YACtE,IAAI,EAAE,sBAAsB;YAC5B,MAAM,EAAE,SAAS;YACjB,QAAQ,EAAE,IAAI;SACf,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/score.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Canonical pass rate for a run.
+ *
+ * `score` is a shared field on the run verdict (`SignalEnvelope.verdict`)
+ * and `StoredSession` that the dashboard renders as the "PASS RATE" column.
+ * It has ONE meaning across every tool: the percentage of units that passed.
+ *
+ * A unit passes when it has no error-severity signals — warnings alone
+ * do not fail a unit. So a warnings-only run
+ * scores 100, consistent with the WARN-but-passing status the dashboard
+ * shows for it. An empty run (no checks) also scores 100, matching the
+ * fitness gate-baseline convention so `--gate-compare` does not report a
+ * phantom regression on an empty recipe.
+ *
+ * This lives in contracts — the layer below every tool — because the
+ * formula must be identical everywhere `score` is produced. Each tool
+ * previously rolled its own: fitness used passed/total, but graph used a
+ * findings-count penalty (`100 - findings`), which disagreed with its own
+ * passed/total summary and rendered 0% for warnings-only runs. Route all
+ * score computation through here so they cannot drift again.
+ */
+export declare function passRate(summary: {
+    readonly total: number;
+    readonly passed: number;
+}): number;
+//# sourceMappingURL=score.d.ts.map

package/dist/score.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score.d.ts","sourceRoot":"","sources":["../src/score.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAE7F"}

package/dist/score.js

@@ -0,0 +1,25 @@
+/**
+ * Canonical pass rate for a run.
+ *
+ * `score` is a shared field on the run verdict (`SignalEnvelope.verdict`)
+ * and `StoredSession` that the dashboard renders as the "PASS RATE" column.
+ * It has ONE meaning across every tool: the percentage of units that passed.
+ *
+ * A unit passes when it has no error-severity signals — warnings alone
+ * do not fail a unit. So a warnings-only run
+ * scores 100, consistent with the WARN-but-passing status the dashboard
+ * shows for it. An empty run (no checks) also scores 100, matching the
+ * fitness gate-baseline convention so `--gate-compare` does not report a
+ * phantom regression on an empty recipe.
+ *
+ * This lives in contracts — the layer below every tool — because the
+ * formula must be identical everywhere `score` is produced. Each tool
+ * previously rolled its own: fitness used passed/total, but graph used a
+ * findings-count penalty (`100 - findings`), which disagreed with its own
+ * passed/total summary and rendered 0% for warnings-only runs. Route all
+ * score computation through here so they cannot drift again.
+ */
+export function passRate(summary) {
+    return summary.total > 0 ? Math.round((summary.passed / summary.total) * 100) : 100;
+}
+//# sourceMappingURL=score.js.map

package/dist/score.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"score.js","sourceRoot":"","sources":["../src/score.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,QAAQ,CAAC,OAA4D;IACnF,OAAO,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AACtF,CAAC"}

package/dist/score.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=score.test.d.ts.map

package/dist/score.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score.test.d.ts","sourceRoot":"","sources":["../src/score.test.ts"],"names":[],"mappings":""}

package/dist/score.test.js

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { passRate } from './score.js';
+describe('passRate', () => {
+    it('is the rounded passed/total percentage', () => {
+        expect(passRate({ total: 4, passed: 4 })).toBe(100);
+        expect(passRate({ total: 4, passed: 1 })).toBe(25);
+        expect(passRate({ total: 2, passed: 1 })).toBe(50);
+    });
+    it('rounds to the nearest integer', () => {
+        expect(passRate({ total: 3, passed: 1 })).toBe(33);
+        expect(passRate({ total: 3, passed: 2 })).toBe(67);
+    });
+    it('is 100 for an empty run (no checks) — matches the gate-baseline convention', () => {
+        expect(passRate({ total: 0, passed: 0 })).toBe(100);
+    });
+    it('does not penalize warnings: all-passed scores 100 regardless of finding volume', () => {
+        // The graph regression: every check passed (warnings only), so the
+        // pass rate is 100 even though the run had many findings.
+        expect(passRate({ total: 1, passed: 1 })).toBe(100);
+    });
+});
+//# sourceMappingURL=score.test.js.map

package/dist/score.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"score.test.js","sourceRoot":"","sources":["../src/score.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE;IACxB,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAChD,MAAM,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpD,MAAM,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnD,MAAM,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnD,MAAM,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4EAA4E,EAAE,GAAG,EAAE;QACpF,MAAM,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gFAAgF,EAAE,GAAG,EAAE;QACxF,mEAAmE;QACnE,0DAA0D;QAC1D,MAAM,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/session-types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Session persistence contract type.
+ *
+ * `StoredSession` is the cross-tool shape every tool's session row shares.
+ * The runtime (SessionRepo, schema, id/filename helpers) lives in
+ * @opensip-cli/session-store; this type stays in contracts as the shared
+ * surface tools and the dashboard agree on (audit 2026-05-29, contracts
+ * split).
+ */
+import type { SignalEnvelope } from './signal-envelope.js';
+import type { ToolShortId } from '@opensip-cli/core';
+/**
+ * A persisted tool-run session.
+ *
+ * Holds only **generic** columns every tool shares — score, pass/fail,
+ * lifecycle timing, host metrics, provenance. Per-session detail is
+ * tool-specific and lives in the opaque {@link StoredSession.payload}:
+ * `contracts` holds ZERO tool vocabulary. Each tool owns the shape of its own
+ * payload; the dashboard, as the presentation owner, reads the payload and
+ * renders it — the same producer/consumer split used for `GraphCatalog`.
+ *
+ * ## Host-owned run lifecycle timing (host-owned-run-timing)
+ *
+ * - `startedAt` is the wall-clock start of the user-initiated tool run,
+ *   captured by the host run-lifecycle plane *after* the per-run `RunScope`
+ *   exists and *before* any tool-owned setup / handler / live-renderer work.
+ * - `completedAt` is the wall-clock instant the tool handler / live renderer
+ *   returned its completion data to the host, *before* host persistence,
+ *   render, egress, or report side effects.
+ * - `durationMs` is the canonical tool-invocation duration (monotonic
+ *   elapsed between the two boundaries), **not** TTY-busy time.
+ *
+ * All three are stamped exclusively by the host run-lifecycle plane from a
+ * single `RunLifecycle`. Tools never capture `new Date()` / `Date.now()` /
+ * `performance.now()` for these fields and never supply them — they return a
+ * `ToolSessionContribution` (verdict/score/recipe/payload) and the host owns
+ * the timing. See the clock taxonomy in the spec / session docs.
+ *
+ * `hostMetrics` (when present) explains *host-side* overhead — TTY occupancy,
+ * render, persist, egress, total command time — separately from the canonical
+ * `durationMs`. It is a hydrated projection of the sibling host-metrics record
+ * keyed by session id, not necessarily a column on the `sessions` table.
+ */
+export interface StoredSession {
+    readonly id: string;
+    readonly tool: ToolShortId;
+    /** Wall-clock start of the tool run (host run-lifecycle plane). */
+    readonly startedAt: string;
+    /** Wall-clock completion of the tool run (when the tool returned to the host). */
+    readonly completedAt: string;
+    readonly cwd: string;
+    readonly recipe?: string;
+    readonly score: number;
+    readonly passed: boolean;
+    /** Canonical tool-invocation duration (monotonic), not TTY-busy time. */
+    readonly durationMs: number;
+    /**
+     * Host-side overhead metrics for this run, hydrated from the sibling
+     * host-metrics record. Absent when no metrics were captured. These are NOT
+     * a replacement for `durationMs` — they answer "where did host-side cost
+     * accumulate", not "how long did the tool take".
+     */
+    readonly hostMetrics?: StoredSessionHostMetrics;
+    /**
+     * Tool-owned opaque per-session detail. `contracts` treats this as
+     * `unknown` and never inspects it; the producing tool owns and validates
+     * its shape. Absent for tools that persist no detail.
+     *
+     * ## Inner payload versioning convention
+     *
+     * All tools (first-party and third-party) MUST stamp new payloads they
+     * persist with a top-level numeric `"__version": N` (double-underscore
+     * prefix signals infrastructure, not user data). Start at `1` for the
+     * current shape.
+     *
+     * The host (contracts / session-store / datastore) stays ignorant of tool
+     * shapes — only the producing tool owns the semantics of its version.
+     * The structural decoder tolerates legacy payloads (missing `__version`
+     * treated as v1 / legacy with `fidelity: 'projection'`).
+     *
+     * Example of a versioned tool payload (illustrative v1):
+     * ```json
+     * {
+     *   "__version": 1,
+     *   "summary": { "total": 42, "passed": 40, "failed": 2, "errors": 1, "warnings": 1 },
+     *   "checks": [ ... ]
+     * }
+     * ```
+     *
+     * - Additive / optional fields: safe, no version bump required.
+     * - Breaking (remove/rename/ reinterpret required field, change shapes
+     *   that replay code depends on): bump `__version` + follow documented
+     *   deprecation window (see extending guide and ADR-0050).
+     */
+    readonly payload?: unknown;
+}
+/**
+ * Host-side overhead metrics for a single tool run, captured on separate
+ * clocks from the canonical `durationMs` (host-owned-run-timing §5.3/§5.4).
+ *
+ * Stored in a sibling host-metrics record keyed by session id (so render /
+ * egress metrics — known only *after* the initial session write — can be
+ * upserted without rewriting the session row) and hydrated back onto
+ * {@link StoredSession.hostMetrics} for readers. Every field is optional: a
+ * given run only populates the metrics observable for its path (e.g.
+ * `ttyBusyMs` only for live/TTY runs).
+ */
+export interface StoredSessionHostMetrics {
+    /** Time the interactive TTY was occupied by the live view. */
+    readonly ttyBusyMs?: number;
+    /** Time spent rendering the final static/live completion output. */
+    readonly renderMs?: number;
+    /** Time spent writing the session row + payload. */
+    readonly persistMs?: number;
+    /** Time spent in host-owned post-run signal/report delivery. */
+    readonly egressMs?: number;
+    /** Elapsed time for the full command action, including host pre/post work. */
+    readonly totalCommandMs?: number;
+}
+/** A tool-owned replay of a stored session projection. */
+export interface ToolSessionReplay<R = unknown> {
+    /** Human-renderable result for the shared CLI render seam. */
+    readonly result: R;
+    /** Machine-readable reconstructed envelope emitted by `sessions show --json`. */
+    readonly envelope: SignalEnvelope;
+    /**
+     * Stored sessions currently persist dashboard/detail projections, not the full
+     * live run envelope. This marker makes that explicit for machine consumers.
+     */
+    readonly fidelity: 'projection';
+}
+//# sourceMappingURL=session-types.d.ts.map

package/dist/session-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-types.d.ts","sourceRoot":"","sources":["../src/session-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,wBAAwB,CAAC;IAChD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,wBAAwB;IACvC,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,0DAA0D;AAC1D,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,OAAO;IAC5C,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;CACjC"}

package/dist/session-types.js

@@ -0,0 +1,11 @@
+/**
+ * Session persistence contract type.
+ *
+ * `StoredSession` is the cross-tool shape every tool's session row shares.
+ * The runtime (SessionRepo, schema, id/filename helpers) lives in
+ * @opensip-cli/session-store; this type stays in contracts as the shared
+ * surface tools and the dashboard agree on (audit 2026-05-29, contracts
+ * split).
+ */
+export {};
+//# sourceMappingURL=session-types.js.map

package/dist/session-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-types.js","sourceRoot":"","sources":["../src/session-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/signal-envelope.d.ts

@@ -0,0 +1,118 @@
+import type { FingerprintStrategy, Signal, ToolShortId, VerdictPolicy } from '@opensip-cli/core';
+/**
+ * Run-level verdict header. `passed` ⇔ "no `critical`/`high` signals";
+ * `score` is the canonical {@link passRate} over `summary`.
+ */
+export interface RunVerdict {
+    readonly score: number;
+    readonly passed: boolean;
+    readonly summary: {
+        readonly total: number;
+        readonly passed: number;
+        readonly failed: number;
+        readonly errors: number;
+        readonly warnings: number;
+    };
+}
+/**
+ * Per-unit fact sidecar. A "unit" is the neutral umbrella over a fit check, a
+ * graph rule, and a sim scenario (ADR-0011). Carries ONLY what a flat
+ * `Signal[]` cannot express: that a unit ran, whether it errored, and timing.
+ * `passed` ⇔ "that unit emitted no `critical`/`high` signals".
+ */
+export interface UnitResult {
+    readonly slug: string;
+    readonly passed: boolean;
+    readonly violationCount?: number;
+    readonly durationMs: number;
+    readonly error?: string;
+    /**
+     * Files the unit validated/scanned this run (fitness's "Validated" column).
+     * A per-unit fact a flat `Signal[]` cannot express — a check that scanned
+     * 450 files and emitted 0 signals still has `filesValidated: 450`. Optional:
+     * graph rules / sim scenarios do not scan files and omit it (the terminal
+     * table renders the column blank for those tools). `itemType` names the
+     * scanned noun (`files` / `packages` / …) for the column label.
+     */
+    readonly filesValidated?: number;
+    readonly itemType?: string;
+    /**
+     * Findings suppressed by an inline `@fitness-ignore` directive this run
+     * (fitness's "Ignores" column). Like {@link filesValidated}, a per-unit fact
+     * not recoverable from the (post-suppression) signal list; optional and
+     * omitted by tools without a suppression mechanism.
+     */
+    readonly ignoredCount?: number;
+}
+/** The one tool-run output envelope. The `CommandResult` payload every tool returns. */
+export interface SignalEnvelope {
+    readonly schemaVersion: 2;
+    readonly tool: ToolShortId;
+    readonly recipe?: string;
+    readonly runId: string;
+    readonly createdAt: string;
+    readonly verdict: RunVerdict;
+    readonly units: readonly UnitResult[];
+    readonly signals: readonly Signal[];
+    /** Graph-only edge-fidelity marker, carried over from CliOutput.resolutionMode. */
+    readonly resolutionMode?: 'exact' | 'fast';
+}
+/**
+ * Input to {@link buildSignalEnvelope}. `signals` are already the wire
+ * currency; `units` carry the per-unit ran/errored/timing facts. `runId` and
+ * `createdAt` are supplied by the caller (formatter-purity contract: no
+ * `Date.now()`/`randomUUID` in this layer, so tests stay deterministic).
+ */
+export interface BuildEnvelopeInput {
+    readonly tool: ToolShortId;
+    readonly recipe?: string;
+    readonly runId: string;
+    readonly createdAt: string;
+    readonly units: readonly UnitResult[];
+    readonly signals: readonly Signal[];
+    readonly resolutionMode?: 'exact' | 'fast';
+    /**
+     * The tool's resolved findings policy (ADR-0035). `verdict.passed` is computed
+     * from `(errors, warnings)` against this — replacing the old `errors === 0`.
+     */
+    readonly policy: VerdictPolicy;
+    /**
+     * `true` when the run faulted OUTSIDE its units — e.g. fit's plugin-load
+     * errors, which occur before any unit exists. Unit-level faults are derived
+     * from `UnitResult.error` and need not be passed here. A faulted run always
+     * FAILs, independent of the findings policy (a crash ≠ "0 errors found").
+     */
+    readonly runFaulted: boolean;
+    /**
+     * The tool's baseline-identity strategy (ADR-0036). {@link buildSignalEnvelope}
+     * stamps `Signal.fingerprint` with it at construction, so every envelope
+     * reaches the host seams (gate save/compare, cloud, SARIF) already stamped —
+     * the "tool forgot to stamp" failure class cannot occur for an envelope built
+     * here. Omitted ⇒ {@link defaultFingerprintStrategy} (`ruleId|filePath|line|col`),
+     * which is exactly the documented inheritance for a tool that declares no
+     * `Tool.fingerprintStrategy`. Stamping is idempotent: a signal that already
+     * carries a non-empty `fingerprint` is preserved byte-for-byte, so a tool may
+     * still stamp earlier (e.g. at `createSignal`) without double-hashing.
+     */
+    readonly fingerprintStrategy?: FingerprintStrategy;
+}
+/**
+ * Assemble a {@link SignalEnvelope} from a run's units + signals.
+ *
+ * Centralises the verdict/summary computation so all three tools agree on
+ * "`passed` ⇔ no critical/high" and the score definition. Pure: no IO, no
+ * clock, no id generation — `runId`/`createdAt` arrive on the input.
+ *
+ * - `summary.total/passed/failed` come from `units` (units are what "ran").
+ * - `summary.errors/warnings` come from `signals` (critical|high → error,
+ *   else warning).
+ * - `score = passRate(summary)`.
+ * - `verdict.passed` (ADR-0035) ⇔ the run did not fault, no unit errored, AND
+ *   the error/warning counts pass the tool's findings `policy`. This is the
+ *   single verdict that drives both the exit code and the headline.
+ * - Every signal is fingerprint-stamped (ADR-0036) with
+ *   `input.fingerprintStrategy` (host default when omitted; idempotent for
+ *   pre-stamped signals), so the built envelope is gate-ready by construction.
+ */
+export declare function buildSignalEnvelope(input: BuildEnvelopeInput): SignalEnvelope;
+//# sourceMappingURL=signal-envelope.d.ts.map

package/dist/signal-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-envelope.d.ts","sourceRoot":"","sources":["../src/signal-envelope.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEjG;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,mFAAmF;IACnF,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC5C;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CACpD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,cAAc,CA+C7E"}

package/dist/signal-envelope.js

@@ -0,0 +1,84 @@
+/**
+ * SignalEnvelope — the universal tool-run output currency (ADR-0011).
+ *
+ * Every tool run yields one envelope: the flat `Signal[]` a run produced
+ * (the same currency the cloud egresses via {@link SignalBatch}, ADR-0008)
+ * plus run identity (`tool`, `recipe`, `runId`, `createdAt`), a `verdict`
+ * header, and a `units[]` sidecar (so "ran, errored, 0 signals" is expressible
+ * — a flat signal list cannot carry per-unit ran/errored/timing facts). On the
+ * CLI wire this envelope rides under `.envelope` of a `CommandOutcome`
+ * (ADR-0024), so a `--json` consumer reads `jq '.envelope.verdict.passed'` /
+ * `.envelope.verdict.score`.
+ *
+ * This is intentionally close to {@link SignalBatch} (the cloud egress shape):
+ * the cloud sink ships the signals as-is, adding `repo` identity and dropping
+ * `verdict`/`units`. It lives in `contracts` — the tool↔runner contract layer —
+ * because it is the `CommandResult` payload every tool returns and the
+ * composition root consumes.
+ *
+ * `schemaVersion` is the output-contract version, independent of any package
+ * version. It is `2`, succeeding the implicit `CliOutput` "1.0" husk this
+ * envelope replaces.
+ */
+import { defaultFingerprintStrategy, policyPasses, SeverityPolicy, stampFingerprints, } from '@opensip-cli/core';
+import { passRate } from './score.js';
+/**
+ * Assemble a {@link SignalEnvelope} from a run's units + signals.
+ *
+ * Centralises the verdict/summary computation so all three tools agree on
+ * "`passed` ⇔ no critical/high" and the score definition. Pure: no IO, no
+ * clock, no id generation — `runId`/`createdAt` arrive on the input.
+ *
+ * - `summary.total/passed/failed` come from `units` (units are what "ran").
+ * - `summary.errors/warnings` come from `signals` (critical|high → error,
+ *   else warning).
+ * - `score = passRate(summary)`.
+ * - `verdict.passed` (ADR-0035) ⇔ the run did not fault, no unit errored, AND
+ *   the error/warning counts pass the tool's findings `policy`. This is the
+ *   single verdict that drives both the exit code and the headline.
+ * - Every signal is fingerprint-stamped (ADR-0036) with
+ *   `input.fingerprintStrategy` (host default when omitted; idempotent for
+ *   pre-stamped signals), so the built envelope is gate-ready by construction.
+ */
+export function buildSignalEnvelope(input) {
+    const total = input.units.length;
+    const passed = input.units.filter((u) => u.passed).length;
+    const failed = total - passed;
+    // ADR-0036: fingerprints are an envelope-construction concern. Stamping here
+    // (tool strategy, host default when none) guarantees every built envelope is
+    // gate-ready, instead of trusting each tool to remember a post-hoc stamp that
+    // would otherwise only fail at the first `--gate-save`.
+    const signals = stampFingerprints(input.signals, input.fingerprintStrategy ?? defaultFingerprintStrategy);
+    let errors = 0;
+    let warnings = 0;
+    for (const signal of signals) {
+        // The gate's error/warning split is the central policy predicate (§5.9), one
+        // source of truth shared with the verdict / terminal table / SARIF level.
+        if (SeverityPolicy.isError(signal.severity))
+            errors += 1;
+        else
+            warnings += 1;
+    }
+    const summary = { total, passed, failed, errors, warnings };
+    // A unit that errored (a check that threw / timed out) is a fault, not a
+    // finding — it FAILs the run regardless of the findings policy. Pre-unit
+    // faults (e.g. fit plugin-load) arrive on `runFaulted` since no unit exists.
+    const unitFaulted = input.units.some((u) => u.error !== undefined);
+    const verdict = {
+        score: passRate(summary),
+        passed: !input.runFaulted && !unitFaulted && policyPasses({ errors, warnings }, input.policy),
+        summary,
+    };
+    return {
+        schemaVersion: 2,
+        tool: input.tool,
+        recipe: input.recipe,
+        runId: input.runId,
+        createdAt: input.createdAt,
+        verdict,
+        units: input.units,
+        signals,
+        resolutionMode: input.resolutionMode,
+    };
+}
+//# sourceMappingURL=signal-envelope.js.map

package/dist/signal-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-envelope.js","sourceRoot":"","sources":["../src/signal-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EACL,0BAA0B,EAC1B,YAAY,EACZ,cAAc,EACd,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAyGtC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAyB;IAC3D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC;IACjC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;IAC1D,MAAM,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;IAE9B,6EAA6E;IAC7E,6EAA6E;IAC7E,8EAA8E;IAC9E,wDAAwD;IACxD,MAAM,OAAO,GAAG,iBAAiB,CAC/B,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,mBAAmB,IAAI,0BAA0B,CACxD,CAAC;IAEF,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,6EAA6E;QAC7E,0EAA0E;QAC1E,IAAI,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC;YAAE,MAAM,IAAI,CAAC,CAAC;;YACpD,QAAQ,IAAI,CAAC,CAAC;IACrB,CAAC;IAED,MAAM,OAAO,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAE5D,yEAAyE;IACzE,yEAAyE;IACzE,6EAA6E;IAC7E,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC;IAEnE,MAAM,OAAO,GAAe;QAC1B,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC;QACxB,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,WAAW,IAAI,YAAY,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,KAAK,CAAC,MAAM,CAAC;QAC7F,OAAO;KACR,CAAC;IAEF,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,OAAO;QACP,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,OAAO;QACP,cAAc,EAAE,KAAK,CAAC,cAAc;KACrC,CAAC;AACJ,CAAC"}

package/dist/signal-envelope.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=signal-envelope.test.d.ts.map

package/dist/signal-envelope.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-envelope.test.d.ts","sourceRoot":"","sources":["../src/signal-envelope.test.ts"],"names":[],"mappings":""}