agent-nuvira 3.3.3 → 3.3.4

package/dist/parity/scenarios.js

@@ -0,0 +1,175 @@
+/**
+ * WS0 (#22) — one scenario, every surface, one verdict.
+ *
+ * The registry (`surfaces.ts`) answers "which surfaces exist and what do they
+ * run through". This module answers the harder question: did they behave the
+ * same, and is the verdict trustworthy.
+ *
+ * THREE RULES, each closing a way a parity test lies:
+ *
+ *   1. STUB DEPTH MUST BE COMPARABLE. Every driver records where its stub sits.
+ *      `provider` (a stub provider object) and `transport` (a real provider
+ *      object talking to a stub SERVER — the forked subagent child) both run the
+ *      real turn code end to end, so they are ONE comparable class; folding them
+ *      together is what makes the child readable against the in-process
+ *      surfaces. `engine` replaces the very behaviour under test, so it never
+ *      compares with anything, itself included. A run that would have to compare
+ *      incomparable depths is refused rather than answered.
+ *
+ *   2. SKIPPED SURFACES ARE NAMED. A surface that cannot be driven appears in
+ *      `skipped` with the reason it is missing. Silence is how a harness ends up
+ *      "passing" for months while covering one surface.
+ *
+ *   3. TWO SURFACES IS THE MINIMUM. One available driver is not a parity run; it
+ *      is a smoke test wearing a parity label. That case reports
+ *      `insufficient`, never `at-par`.
+ *
+ *   4. THE TURN MUST HAVE REACHED A MODEL. The response cache is shared and
+ *      enabled on the `answerOnce` path, so the second surface of a run can be
+ *      served from the first one's entry — same answer, no model call, no tool
+ *      lifecycle, and a flawless "agreement" between two replays that proves
+ *      nothing. Measured, not hypothetical: before this rule existed, the second
+ *      surface of every two-driver run was a cache hit (the drivers now isolate
+ *      the cache per turn as well — belt and braces, because either guard alone
+ *      would be one edit away from being removed).
+ *      A zero is refused as `unreached-model` rather than compared.
+ *
+ * Pure by construction: no `fs`, no `vi`, no process env — which is what lets
+ * both the test suite and `nuvira parity run` import it. The drivers that
+ * actually drive a turn live in `./drivers.ts` (transport depth, a loopback stub
+ * server), so the CLI and CI run the SAME mechanism instead of two copies that
+ * could disagree.
+ */
+import { compare } from './observation.js';
+/**
+ * Drive one scenario through every available driver and compare the results.
+ *
+ * Order matters only for the report: the first available driver is the baseline.
+ * Driver order is the caller's, so a scenario can pin a baseline deliberately.
+ */
+export async function runParityScenario(scenario, drivers) {
+    const skipped = drivers
+        .filter((d) => !d.available)
+        .map((d) => ({ surface: d.surface, reason: d.blockedBy ?? 'no reason recorded' }));
+    const available = drivers.filter((d) => d.available);
+    if (available.length < 2) {
+        return {
+            scenario: scenario.id,
+            depth: null,
+            observations: [],
+            differences: [],
+            skipped,
+            verdict: 'not-run',
+            refusal: {
+                kind: 'insufficient-coverage',
+                available: available.map((d) => d.surface),
+                message: `only ${available.length} surface(s) can be driven for "${scenario.id}"` +
+                    (skipped.length > 0 ? `; skipped: ${skipped.map((s) => `${s.surface} (${s.reason})`).join('; ')}` : '') +
+                    '. A parity verdict needs at least two.',
+            },
+        };
+    }
+    const depths = [...new Set(available.map((d) => d.depth))];
+    // R2 — `provider` and `transport` are one comparable class (see rule 1 in the
+    // header). `engine` never compares, whether or not it is paired with anything.
+    if (depths.includes('engine')) {
+        return {
+            scenario: scenario.id,
+            depth: null,
+            observations: [],
+            differences: [],
+            skipped,
+            verdict: 'not-run',
+            refusal: {
+                kind: 'depth-mismatch',
+                depths: available.map((d) => ({ surface: d.surface, depth: d.depth })),
+                message: `a stub sits at the ENGINE depth (${depths.join(', ')}), so a verdict would be meaningless: ` +
+                    'that surface has had the behaviour under test replaced, and it can never be compared — ' +
+                    'not with a provider stub, and not with another engine stub. ' +
+                    'Re-drive it at provider or transport depth, or declare the gap.',
+            },
+        };
+    }
+    /** No single depth to report when comparable depths were mixed. */
+    const reportedDepth = depths.length === 1 ? depths[0] : null;
+    const observations = [];
+    for (const driver of available)
+        observations.push(await driver.run(scenario));
+    // Rule 4. Checked BEFORE comparing, because a zero would otherwise surface as
+    // a "divergence" in modelCalls — the right refusal with the wrong name.
+    const unreached = observations.filter((observation) => observation.modelCalls === 0);
+    if (unreached.length > 0) {
+        return {
+            scenario: scenario.id,
+            depth: reportedDepth,
+            observations,
+            differences: [],
+            skipped,
+            verdict: 'not-run',
+            refusal: {
+                kind: 'unreached-model',
+                surfaces: unreached.map((observation) => observation.surface),
+                message: `no model call on: ${unreached.map((o) => o.surface).join(', ')}. ` +
+                    'A turn served without reaching a model — a response-cache replay, or a ' +
+                    'surface answering from a shortcut — did no routing and no tool work, so ' +
+                    'comparing it says nothing. Isolate the cache (or use a distinct message) ' +
+                    'and re-run before reading any verdict from this scenario.',
+            },
+        };
+    }
+    const [baseline, ...rest] = observations;
+    // WS6 (#28) — a scenario that DECLARES a fault is compared on the FAULT-HONESTY
+    // projection instead of the full one, and the reason is measured rather than
+    // aesthetic: under a fatal dependency failure the surfaces legitimately differ in
+    // every other field. The CLI, the GUI, a messaging bridge and a forked child
+    // have different user-facing copy, different error taxonomies, different
+    // last-attempt attributions and different retry counts — comparing those would
+    // report four correct surfaces as divergent and bury the one fact the row is
+    // about. What must NOT differ is whether the failure was reported as a failure.
+    const differences = scenario.fault
+        ? rest.flatMap((observation) => compareFaultHonesty(baseline, observation))
+        : rest.flatMap((observation) => compare(baseline, observation));
+    return {
+        scenario: scenario.id,
+        depth: reportedDepth,
+        observations,
+        differences,
+        skipped,
+        verdict: differences.length === 0 ? 'at-par' : 'divergent',
+    };
+}
+/**
+ * WS6 (#28) — the fields a FAULT row is compared on: what the turn was given, and
+ * whether it reported the consequence.
+ *
+ * `status` and the fault's own `asked`/`site`/`kind` say both surfaces were told
+ * the same thing and ended the same way; `took` is the load-bearing one, because a
+ * surface that SWALLOWED the fault — completed a turn the backend never served, or
+ * reported an injected tool failure as a success — reads `took: false` against
+ * every other surface's `true`. A swallowed fault leaves no other trace, which is
+ * why it is a compared field and not something a test reads off one surface.
+ *
+ * Deliberately absent: `answer`, `errorCode`, `provider`/`transport`/`model`,
+ * `debugLog`, `otel`, `modelCalls` and `toolCalls`. Each of those legitimately
+ * differs under a fatal fault (a messaging surface has no bubble to fill; a child
+ * announces its transport before it fails; the last attempt a debug header names
+ * is the fallback, not the provider that errored). They are still recorded on the
+ * observation for the failure report — only the comparison excludes them.
+ */
+export function compareFaultHonesty(a, b) {
+    const differences = [];
+    const who = `${a.surface} vs ${b.surface}`;
+    if (a.status !== b.status) {
+        differences.push(`${who}: status differs — ${a.status} vs ${b.status}`);
+    }
+    const fields = ['asked', 'site', 'kind', 'took'];
+    for (const field of fields) {
+        const l = a.fault[field];
+        const r = b.fault[field];
+        if (l !== r) {
+            differences.push(`${who}: fault.${field} differs — ${String(l)} vs ${String(r)}`);
+        }
+    }
+    return differences;
+}
+//# sourceMappingURL=scenarios.js.map

package/dist/parity/scenarios.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenarios.js","sourceRoot":"","sources":["../../src/parity/scenarios.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAE,OAAO,EAAwB,MAAM,kBAAkB,CAAC;AAsKjE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAwB,EACxB,OAAgC;IAEhC,MAAM,OAAO,GAAqB,OAAO;SACtC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;SAC3B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,IAAI,oBAAoB,EAAE,CAAC,CAAC,CAAC;IAErF,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAErD,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,QAAQ,EAAE,QAAQ,CAAC,EAAE;YACrB,KAAK,EAAE,IAAI;YACX,YAAY,EAAE,EAAE;YAChB,WAAW,EAAE,EAAE;YACf,OAAO;YACP,OAAO,EAAE,SAAS;YAClB,OAAO,EAAE;gBACP,IAAI,EAAE,uBAAuB;gBAC7B,SAAS,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;gBAC1C,OAAO,EACL,QAAQ,SAAS,CAAC,MAAM,kCAAkC,QAAQ,CAAC,EAAE,GAAG;oBACxE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACvG,wCAAwC;aAC3C;SACF,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3D,8EAA8E;IAC9E,+EAA+E;IAC/E,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9B,OAAO;YACL,QAAQ,EAAE,QAAQ,CAAC,EAAE;YACrB,KAAK,EAAE,IAAI;YACX,YAAY,EAAE,EAAE;YAChB,WAAW,EAAE,EAAE;YACf,OAAO;YACP,OAAO,EAAE,SAAS;YAClB,OAAO,EAAE;gBACP,IAAI,EAAE,gBAAgB;gBACtB,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;gBACtE,OAAO,EACL,oCAAoC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,wCAAwC;oBAC7F,yFAAyF;oBACzF,8DAA8D;oBAC9D,iEAAiE;aACpE;SACF,CAAC;IACJ,CAAC;IACD,mEAAmE;IACnE,MAAM,aAAa,GAAqB,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAE/E,MAAM,YAAY,GAAsB,EAAE,CAAC;IAC3C,KAAK,MAAM,MAAM,IAAI,SAAS;QAAE,YAAY,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE9E,8EAA8E;IAC9E,wEAAwE;IACxE,MAAM,SAAS,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,UAAU,KAAK,CAAC,CAAC,CAAC;IACrF,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,QAAQ,EAAE,QAAQ,CAAC,EAAE;YACrB,KAAK,EAAE,aAAa;YACpB,YAAY;YACZ,WAAW,EAAE,EAAE;YACf,OAAO;YACP,OAAO,EAAE,SAAS;YAClB,OAAO,EAAE;gBACP,IAAI,EAAE,iBAAiB;gBACvB,QAAQ,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC;gBAC7D,OAAO,EACL,qBAAqB,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;oBACnE,yEAAyE;oBACzE,0EAA0E;oBAC1E,2EAA2E;oBAC3E,2DAA2D;aAC9D;SACF,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,GAAG,YAAY,CAAC;IACzC,gFAAgF;IAChF,6EAA6E;IAC7E,kFAAkF;IAClF,6EAA6E;IAC7E,yEAAyE;IACzE,+EAA+E;IAC/E,6EAA6E;IAC7E,gFAAgF;IAChF,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK;QAChC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,mBAAmB,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QAC3E,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC;IAElE,OAAO;QACL,QAAQ,EAAE,QAAQ,CAAC,EAAE;QACrB,KAAK,EAAE,aAAa;QACpB,YAAY;QACZ,WAAW;QACX,OAAO;QACP,OAAO,EAAE,WAAW,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW;KAC3D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAkB,EAAE,CAAkB;IACxE,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;IAC3C,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,WAAW,CAAC,IAAI,CAAC,GAAG,GAAG,sBAAsB,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAU,CAAC;IAC1D,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACzB,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACZ,WAAW,CAAC,IAAI,CAAC,GAAG,GAAG,WAAW,KAAK,cAAc,MAAM,CAAC,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACpF,CAAC;IACH,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/parity/surfaces.d.ts

@@ -0,0 +1,122 @@
+/**
+ * WS0 (#22) — the surface registry.
+ *
+ * WHY THIS FILE EXISTS. Before a capability can be promised on "every surface"
+ * (WS1-WS7), the set of surfaces has to be DECLARED. Inferred from whatever
+ * happens to import what, it is invisible: nothing fails when a new
+ * implementation appears beside the shared one, and nothing fails when a
+ * capability lands on one surface and quietly misses three.
+ *
+ * MEASURED, and the reason this is not paranoia — four ways to run an agent turn
+ * already exist over three engine labels:
+ *
+ *   - `src/cli/chat.ts` runs a turn through its own `answerOnce`
+ *     (`cli/chat.ts:502`), which the dashboard drives too
+ *     (`web-dashboard/chat-console.ts:391` lazily imports ChatCommand, `:618`
+ *     awaits `engine.answerOnce`), and which the gateway chat engine also calls
+ *     (`cli/chat.ts:625` — "the chat console and the gateway chat engine both
+ *     call answerOnce"). This one IS shared, and it is the model for the rest.
+ *   - `src/cli/loop-executor.ts:196` `runLoopExecutor` — the loop engine.
+ *   - `src/tools/pipeline-tool.ts:76` `runPipelineTool` — the pipeline engine,
+ *     which is the ONLY way the gateway runs a non-chat turn.
+ *   - `src/cli/execute.ts` picks between them itself (`:1655` direct, `:1725`
+ *     loop, `:2009` pipeline) and reaches the provider factory directly, so its
+ *     engine choice and provider construction live in the surface.
+ *
+ * Also measured: `src/web-dashboard/server.ts` does not import any turn entry —
+ * it reaches `answerOnce` indirectly through `chat-console.ts`, which is why
+ * `turnEntries` below records what a surface ends up using rather than what it
+ * imports literally. `surfacesReaching` (see `parity/graph.ts`) does the
+ * transitive check.
+ *
+ * This module is DATA plus pure lookups on purpose: it is what the parity test
+ * and the capability matrix read, so it must be cheap to import from a test and
+ * free of side effects.
+ */
+import type { EngineMode } from '../learning/engine-router.js';
+/** The surfaces a person can talk to agent-nuvira through. */
+export type SurfaceId = 'cli-chat' | 'cli-execute' | 'dashboard-chat' | 'gateway-chat' | 'subagent';
+/**
+ * The shared turn entries. A surface runs a turn through one of these, or it is
+ * a silo — which is exactly what the architecture test in
+ * `tests/parity/cross-surface.test.ts` fails on.
+ */
+export type TurnEntryId = 'chat-once' | 'loop-executor' | 'pipeline-tool' | 'orchestrator' | 'child-runtime';
+export interface TurnEntry {
+    id: TurnEntryId;
+    /** Repo-relative module that exports the entry. */
+    module: string;
+    /** The exported symbol a surface calls. */
+    symbol: string;
+    /** Engines this entry can serve. */
+    engines: readonly EngineMode[];
+    note: string;
+}
+export interface SurfaceDescriptor {
+    id: SurfaceId;
+    label: string;
+    /**
+     * Repo-relative modules that OWN the surface (the thing a person addresses).
+     * Paths, not globs: the registry is meant to be read.
+     */
+    modules: readonly string[];
+    /** Shared turn entries this surface uses, transitively. */
+    turnEntries: readonly TurnEntryId[];
+    /**
+     * Engine labels observable through this surface. More than one entry means
+     * the surface chooses, and a parity test must exercise each.
+     */
+    engines: readonly EngineMode[];
+    /**
+     * True when the surface runs in its own process. Such a surface legitimately
+     * builds its own provider and loop (that IS the isolation), so the
+     * in-process rules below do not apply to it — but its observable behaviour
+     * still must match, which is what the normalised observation checks.
+     */
+    separateProcess?: boolean;
+    /** How a parity test drives this surface headlessly. */
+    headless: string;
+}
+/**
+ * The shared entries. `engines` is what the entry can serve, not what every
+ * caller uses: the gateway only ever asks `pipeline-tool` for pipeline work.
+ */
+export declare const TURN_ENTRIES: Record<TurnEntryId, TurnEntry>;
+/**
+ * Known surface-level debt, keyed by what is wrong and why it is still here.
+ *
+ * This is a RATCHET, not an allowlist of convenience: the architecture test
+ * asserts the observed violations EQUAL this list, so adding a new bypass fails,
+ * and removing one without deleting its entry fails too (a stale entry would
+ * otherwise hide the next one). Every entry is somebody's workstream.
+ *
+ * BOTH ARE EMPTY NOW. `src/cli/execute.ts` was the whole list: it built its own
+ * provider and drove the pipeline engine through a private `Orchestrator`. It
+ * now resolves through the shared `resolveProvider` and runs pipeline turns
+ * through `runPipelineTool`. The keys stay declared with empty arrays on
+ * purpose — deleting a key would stop the rule from being measured at all, and
+ * the next bypass would then be invisible instead of a one-line diff here.
+ */
+export declare const SURFACE_DEBT: Record<string, readonly string[]>;
+/**
+ * Every surface, with the evidence that it exists. Order is display order only.
+ */
+export declare const SURFACES: readonly SurfaceDescriptor[];
+/** A surface by id, or undefined. */
+export declare function surfaceById(id: SurfaceId): SurfaceDescriptor | undefined;
+/** Every surface that runs a turn through `entry`, directly or transitively. */
+export declare function surfacesReaching(entry: TurnEntryId): SurfaceDescriptor[];
+/**
+ * Every (surface, engine) pair a parity test must exercise. A surface that can
+ * select between engines contributes one pair per engine, so a capability that
+ * works under `loop` and fails under `pipeline` cannot pass unnoticed.
+ */
+export declare function parityMatrix(): Array<{
+    surface: SurfaceId;
+    engine: EngineMode;
+}>;
+/** Repo-relative paths of the surface-owned modules. */
+export declare function surfaceModulePaths(): string[];
+/** Repo-relative paths of the shared turn entries. */
+export declare function turnEntryModulePaths(): string[];
+//# sourceMappingURL=surfaces.d.ts.map

package/dist/parity/surfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaces.d.ts","sourceRoot":"","sources":["../../src/parity/surfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE/D,8DAA8D;AAC9D,MAAM,MAAM,SAAS,GACjB,UAAU,GACV,aAAa,GACb,gBAAgB,GAChB,cAAc,GACd,UAAU,CAAC;AAEf;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB,WAAW,GACX,eAAe,GACf,eAAe,GACf,cAAc,GACd,eAAe,CAAC;AAEpB,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,WAAW,CAAC;IAChB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,SAAS,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,2DAA2D;IAC3D,WAAW,EAAE,SAAS,WAAW,EAAE,CAAC;IACpC;;;OAGG;IACH,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,WAAW,EAAE,SAAS,CAoCvD,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAK1D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,SAAS,iBAAiB,EA2DhD,CAAC;AAEF,qCAAqC;AACrC,wBAAgB,WAAW,CAAC,EAAE,EAAE,SAAS,GAAG,iBAAiB,GAAG,SAAS,CAExE;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,iBAAiB,EAAE,CAExE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,KAAK,CAAC;IAAE,OAAO,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC,CAMhF;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAE7C;AAED,sDAAsD;AACtD,wBAAgB,oBAAoB,IAAI,MAAM,EAAE,CAE/C"}

package/dist/parity/surfaces.js

@@ -0,0 +1,190 @@
+/**
+ * WS0 (#22) — the surface registry.
+ *
+ * WHY THIS FILE EXISTS. Before a capability can be promised on "every surface"
+ * (WS1-WS7), the set of surfaces has to be DECLARED. Inferred from whatever
+ * happens to import what, it is invisible: nothing fails when a new
+ * implementation appears beside the shared one, and nothing fails when a
+ * capability lands on one surface and quietly misses three.
+ *
+ * MEASURED, and the reason this is not paranoia — four ways to run an agent turn
+ * already exist over three engine labels:
+ *
+ *   - `src/cli/chat.ts` runs a turn through its own `answerOnce`
+ *     (`cli/chat.ts:502`), which the dashboard drives too
+ *     (`web-dashboard/chat-console.ts:391` lazily imports ChatCommand, `:618`
+ *     awaits `engine.answerOnce`), and which the gateway chat engine also calls
+ *     (`cli/chat.ts:625` — "the chat console and the gateway chat engine both
+ *     call answerOnce"). This one IS shared, and it is the model for the rest.
+ *   - `src/cli/loop-executor.ts:196` `runLoopExecutor` — the loop engine.
+ *   - `src/tools/pipeline-tool.ts:76` `runPipelineTool` — the pipeline engine,
+ *     which is the ONLY way the gateway runs a non-chat turn.
+ *   - `src/cli/execute.ts` picks between them itself (`:1655` direct, `:1725`
+ *     loop, `:2009` pipeline) and reaches the provider factory directly, so its
+ *     engine choice and provider construction live in the surface.
+ *
+ * Also measured: `src/web-dashboard/server.ts` does not import any turn entry —
+ * it reaches `answerOnce` indirectly through `chat-console.ts`, which is why
+ * `turnEntries` below records what a surface ends up using rather than what it
+ * imports literally. `surfacesReaching` (see `parity/graph.ts`) does the
+ * transitive check.
+ *
+ * This module is DATA plus pure lookups on purpose: it is what the parity test
+ * and the capability matrix read, so it must be cheap to import from a test and
+ * free of side effects.
+ */
+/**
+ * The shared entries. `engines` is what the entry can serve, not what every
+ * caller uses: the gateway only ever asks `pipeline-tool` for pipeline work.
+ */
+export const TURN_ENTRIES = {
+    'chat-once': {
+        id: 'chat-once',
+        module: 'src/cli/chat.ts',
+        symbol: 'ChatCommand.answerOnce',
+        engines: ['loop'],
+        note: 'The interactive engine. Shared by the CLI chat, the dashboard console and the gateway chat path — the only entry that is genuinely cross-surface today, and therefore the template for the others.',
+    },
+    'loop-executor': {
+        id: 'loop-executor',
+        module: 'src/cli/loop-executor.ts',
+        symbol: 'runLoopExecutor',
+        engines: ['loop'],
+        note: 'The loop engine as a library. Written to give `nuvira execute` the exposure the chat path already had, so it is the intended replacement for the surface-level branch in execute.ts.',
+    },
+    'pipeline-tool': {
+        id: 'pipeline-tool',
+        module: 'src/tools/pipeline-tool.ts',
+        symbol: 'runPipelineTool',
+        engines: ['pipeline'],
+        note: 'The pipeline engine, reached through the orchestrator. The gateway runs every non-chat turn through this, which is why the gateway is pipeline-only.',
+    },
+    orchestrator: {
+        id: 'orchestrator',
+        module: 'src/agents/orchestrator.ts',
+        symbol: 'Orchestrator',
+        engines: ['pipeline'],
+        note: 'The pipeline engine core, owned by the `pipeline-tool` wrapper. A surface that reaches it DIRECTLY is driving pipeline turns itself — legitimate, but it bypasses the wrapper`s provider resolution, understand-card and checkpoint default, which is what SURFACE_DEBT used to record for `cli/execute.ts`. No surface does today; the entry stays declared because the wrapper itself is one, and the rule needs something to measure against.',
+    },
+    'child-runtime': {
+        id: 'child-runtime',
+        module: 'src/tools/child-agent-runtime.ts',
+        symbol: 'runSubagent',
+        engines: ['loop'],
+        note: 'The subagent child process. It builds its own provider and loop on purpose: it is the isolation boundary, and it reports the provider/model/transport it actually used so the parent can attribute the run.',
+    },
+};
+/**
+ * Known surface-level debt, keyed by what is wrong and why it is still here.
+ *
+ * This is a RATCHET, not an allowlist of convenience: the architecture test
+ * asserts the observed violations EQUAL this list, so adding a new bypass fails,
+ * and removing one without deleting its entry fails too (a stale entry would
+ * otherwise hide the next one). Every entry is somebody's workstream.
+ *
+ * BOTH ARE EMPTY NOW. `src/cli/execute.ts` was the whole list: it built its own
+ * provider and drove the pipeline engine through a private `Orchestrator`. It
+ * now resolves through the shared `resolveProvider` and runs pipeline turns
+ * through `runPipelineTool`. The keys stay declared with empty arrays on
+ * purpose — deleting a key would stop the rule from being measured at all, and
+ * the next bypass would then be invisible instead of a one-line diff here.
+ */
+export const SURFACE_DEBT = {
+    /** Surface modules that construct their own provider instead of going through a shared entry. */
+    'provider-factory': [],
+    /** Surface modules that drive the pipeline engine without the `pipeline-tool` wrapper. */
+    'pipeline-wrapper-bypass': [],
+};
+/**
+ * Every surface, with the evidence that it exists. Order is display order only.
+ */
+export const SURFACES = [
+    {
+        id: 'cli-chat',
+        label: 'CLI chat',
+        modules: ['src/cli/chat.ts', 'src/cli/cli-program.ts'],
+        // Two entries, not one: measured, `chat.ts:87` imports `runPipelineTool` and
+        // calls it at `:702`, so the chat surface can also run a pipeline turn. The
+        // engine is chosen by the user's explicit command (`:298` checks
+        // `action.run === 'pipeline'`), NOT by the router — which is why this
+        // surface declares both engines and the parity matrix exercises both.
+        turnEntries: ['chat-once', 'pipeline-tool'],
+        engines: ['loop', 'pipeline'],
+        headless: 'Drive ChatCommand.answerOnce with a stub provider and an in-memory askUser responder (the shape chat-console.ts already uses); drive the pipeline path through the same runPipelineTool wrapper.',
+    },
+    {
+        id: 'cli-execute',
+        label: 'CLI execute / one-shot',
+        modules: ['src/cli/execute.ts', 'src/cli/run.ts'],
+        // `pipeline-tool` IS here now: measured, `execute.ts` drives its pipeline
+        // runs through the wrapper. It used to import the Orchestrator directly and
+        // never reach the wrapper — exactly the drift this registry exists to
+        // surface, and the reason it was the sole entry on
+        // `SURFACE_DEBT['pipeline-wrapper-bypass']`.
+        // `chat-once` is here for the same measured reason as ever: execute.ts
+        // reaches the chat engine through `import('./chat.js')`, which is also how
+        // its interactive mode works.
+        turnEntries: ['chat-once', 'loop-executor', 'pipeline-tool'],
+        engines: ['loop', 'pipeline'],
+        headless: 'Drive the command`s own single-goal path (`runSingleGoal`) with the provider stubbed at the shared factory and the engine pinned to loop, and read the turn AND its attribution (provider/model/transport) and its per-call tool outcomes off what the command returns. Both of the command`s arms report now — the loop engine through `runLoopExecutor` and the direct chat answer through the engine`s `onToolCall`.',
+    },
+    {
+        id: 'dashboard-chat',
+        label: 'Dashboard chat',
+        modules: ['src/web-dashboard/server.ts', 'src/web-dashboard/chat-console.ts'],
+        turnEntries: ['chat-once'],
+        engines: ['loop'],
+        headless: 'Call the turn through chat-console with a stub provider and no HTTP transport; the console is the seam, not the server.',
+    },
+    {
+        id: 'gateway-chat',
+        label: 'Gateway (Slack / Discord / Telegram / …)',
+        modules: [
+            'src/gateway/registry.ts',
+            'src/gateway/adapters.ts',
+            'src/gateway/realtime.ts',
+        ],
+        turnEntries: ['chat-once', 'pipeline-tool'],
+        engines: ['loop', 'pipeline'],
+        headless: 'Invoke the registry handler with a synthetic inbound message and a stub adapter; no live transport, no credentials.',
+    },
+    {
+        id: 'subagent',
+        label: 'Subagent child process',
+        modules: ['src/tools/child-agent-runtime.ts', 'src/tools/child-agent-entry.ts'],
+        turnEntries: ['child-runtime'],
+        engines: ['loop'],
+        separateProcess: true,
+        headless: 'Spawn the child entry with a stub provider over its IPC frames, as tests/tools/subagent-end-to-end.test.ts does.',
+    },
+];
+/** A surface by id, or undefined. */
+export function surfaceById(id) {
+    return SURFACES.find((s) => s.id === id);
+}
+/** Every surface that runs a turn through `entry`, directly or transitively. */
+export function surfacesReaching(entry) {
+    return SURFACES.filter((s) => s.turnEntries.includes(entry));
+}
+/**
+ * Every (surface, engine) pair a parity test must exercise. A surface that can
+ * select between engines contributes one pair per engine, so a capability that
+ * works under `loop` and fails under `pipeline` cannot pass unnoticed.
+ */
+export function parityMatrix() {
+    const pairs = [];
+    for (const surface of SURFACES) {
+        for (const engine of surface.engines)
+            pairs.push({ surface: surface.id, engine });
+    }
+    return pairs;
+}
+/** Repo-relative paths of the surface-owned modules. */
+export function surfaceModulePaths() {
+    return [...new Set(SURFACES.flatMap((s) => s.modules))].sort();
+}
+/** Repo-relative paths of the shared turn entries. */
+export function turnEntryModulePaths() {
+    return Object.values(TURN_ENTRIES).map((e) => e.module).sort();
+}
+//# sourceMappingURL=surfaces.js.map

package/dist/parity/surfaces.js.map

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