@hecer/yoke 1.20.0 → 1.22.0

package/dist/smoke/command.js

@@ -1,7 +1,10 @@
-import { mkdirSync, rmSync, renameSync } from 'node:fs';
+import { lstatSync, mkdirSync, rmSync, renameSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
+import { createHash } from 'node:crypto';
 import { loadConfig } from '../retrofit/config.js';
+import { workspaceFingerprint } from '../workspace/fingerprint.js';
+import { statePath } from '../workspace/state.js';
 const CONFIG_GUIDANCE = [
     'No smoke flows configured. Add a smoke section to .yoke/config.yaml, e.g.:',
     '',
@@ -24,7 +27,7 @@ export async function launchPlaywright(targetDir) {
         const chromium = pw.chromium ?? pw.default?.chromium;
         if (!chromium)
             return null;
-        return await chromium.launch({ headless: true });
+        return await chromium.launch({ headless: true, timeout: 30_000 });
     }
     catch {
         return null;
@@ -32,7 +35,7 @@ export async function launchPlaywright(targetDir) {
 }
 // Flow names come from user config and become filenames — keep them safe.
 function safeName(name) {
-    return name.replace(/[^\w.-]+/g, '-');
+    return name.replace(/[^\w.-]+/g, '-').slice(0, 120) || 'flow';
 }
 // The label names a directory that gets rmSync'd recursively — it must never
 // carry path semantics ('..', separators). Dots are stripped entirely so a
@@ -41,6 +44,204 @@ export function safeLabel(label) {
     const cleaned = label.replace(/[^\w-]+/g, '-').replace(/^-+|-+$/g, '');
     return cleaned || 'latest';
 }
+class SmokeFailure extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+function failureCode(error, fallback) {
+    if (error instanceof SmokeFailure)
+        return error.code;
+    return error?.name === 'TimeoutError' ? 'timeout' : fallback;
+}
+async function bounded(operation, timeout) {
+    if (timeout <= 0)
+        throw new SmokeFailure('timeout');
+    const deadline = Date.now() + timeout;
+    let timer;
+    try {
+        const result = await Promise.race([
+            Promise.resolve().then(operation),
+            new Promise((_, reject) => { timer = setTimeout(() => reject(new SmokeFailure('timeout')), timeout); }),
+        ]);
+        if (Date.now() >= deadline)
+            throw new SmokeFailure('timeout');
+        return result;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function measured(stage, operation, fallback) {
+    const started = Date.now();
+    try {
+        await operation();
+        stage.status = 'passed';
+    }
+    catch (error) {
+        stage.status = 'failed';
+        stage.failure = failureCode(error, fallback);
+        throw new SmokeFailure(stage.failure);
+    }
+    finally {
+        stage.durationMs = Date.now() - started;
+    }
+}
+async function executeStep(page, step, baseUrl, timeout, fillValue) {
+    switch (step.action) {
+        case 'click':
+            if (!page.click)
+                throw new SmokeFailure('unsupported-action');
+            await page.click(step.selector, { timeout });
+            return;
+        case 'fill':
+            if (fillValue === undefined || fillValue.length > 8192)
+                throw new SmokeFailure('fill-value-unavailable');
+            if (!page.fill)
+                throw new SmokeFailure('unsupported-action');
+            await page.fill(step.selector, fillValue, { timeout });
+            return;
+        case 'press':
+            if (!page.press)
+                throw new SmokeFailure('unsupported-action');
+            await page.press(step.selector, step.key, { timeout });
+            return;
+        case 'expect-visible':
+            await page.waitForSelector(step.selector, { state: 'visible', timeout });
+            return;
+        case 'expect-text': {
+            if (!page.textContent)
+                throw new SmokeFailure('unsupported-action');
+            const deadline = Date.now() + timeout;
+            await page.waitForSelector(step.selector, { state: 'visible', timeout });
+            const normalize = (value) => value.replace(/\s+/gu, ' ').trim();
+            const expected = normalize(step.text);
+            // Both a fixed attempt bound and the enclosing deadline apply. No unbounded
+            // polling, even when a test adapter ignores Playwright's own timeout option.
+            for (let attempt = 0; attempt <= Math.ceil(timeout / 100); attempt++) {
+                const remaining = deadline - Date.now();
+                if (remaining <= 0)
+                    break;
+                const actual = normalize(await page.textContent(step.selector, { timeout: remaining }) ?? '');
+                if (Date.now() < deadline && (step.exact ? actual === expected : actual.includes(expected)))
+                    return;
+                await new Promise(resolveValue => setTimeout(resolveValue, Math.max(0, Math.min(100, deadline - Date.now()))));
+            }
+            throw new SmokeFailure('timeout');
+        }
+        case 'expect-url': {
+            if (!page.waitForURL)
+                throw new SmokeFailure('unsupported-action');
+            const expected = new URL(step.url, baseUrl).href;
+            await page.waitForURL(url => url.href === expected, { waitUntil: 'load', timeout });
+            return;
+        }
+        case 'reload': {
+            if (!page.reload)
+                throw new SmokeFailure('unsupported-action');
+            const response = await page.reload({ waitUntil: 'load', timeout });
+            if (response && !response.ok())
+                throw new SmokeFailure('http-error');
+            return;
+        }
+        default: {
+            const unexpected = step;
+            void unexpected;
+            throw new SmokeFailure('unsupported-action');
+        }
+    }
+}
+async function runFlow(browser, flow, baseUrl, proofDir, fileStem, fillValues, name) {
+    const started = Date.now(), deadline = started + (flow.timeoutMs ?? 60_000);
+    const report = {
+        name, status: 'failed', durationMs: 0, navigation: { status: 'skipped', durationMs: 0 },
+        ...(flow.landmark ? { landmark: { status: 'skipped', durationMs: 0 } } : {}),
+        steps: (flow.steps ?? []).map((step, index) => ({ index: index + 1, action: step.action, status: 'skipped', durationMs: 0 })),
+    };
+    let context, page, consoleErrors = 0;
+    let video = null;
+    const remaining = (limit) => Math.min(limit, deadline - Date.now());
+    const assertNoConsoleErrors = () => { if (consoleErrors > 0)
+        throw new SmokeFailure('console-errors'); };
+    try {
+        context = await bounded(() => browser.newContext({ recordVideo: { dir: join(proofDir, '.video-tmp') }, viewport: { width: 1280, height: 720 } }), remaining(30_000));
+        page = await bounded(() => context.newPage(), remaining(30_000));
+        const activePage = page;
+        // Browser diagnostics can echo input values. Count them; never persist their
+        // text, call logs, selectors or parameters in the machine-readable report.
+        page.on('console', msg => { if (msg?.type?.() === 'error')
+            consoleErrors++; });
+        page.on('pageerror', () => { consoleErrors++; });
+        await measured(report.navigation, async () => {
+            const timeout = remaining(30_000);
+            const response = await bounded(() => activePage.goto(baseUrl + flow.path, { waitUntil: 'load', timeout }), timeout);
+            if (response && !response.ok())
+                throw new SmokeFailure('http-error');
+            assertNoConsoleErrors();
+        }, 'navigation-failed');
+        if (flow.landmark && report.landmark) {
+            await measured(report.landmark, async () => {
+                const timeout = remaining(10_000);
+                await bounded(() => activePage.waitForSelector(flow.landmark, { state: 'visible', timeout }), timeout);
+                assertNoConsoleErrors();
+            }, 'landmark-missing');
+        }
+        for (const [index, step] of (flow.steps ?? []).entries()) {
+            await measured(report.steps[index], async () => {
+                const timeout = remaining(step.timeoutMs ?? 10_000);
+                await bounded(() => executeStep(activePage, step, baseUrl, timeout, fillValues.get(step)), timeout);
+                assertNoConsoleErrors();
+            }, 'step-failed');
+        }
+    }
+    catch (error) {
+        report.failure = failureCode(error, 'context-failed');
+    }
+    finally {
+        if (page) {
+            try {
+                await bounded(() => page.screenshot({ path: join(proofDir, `${fileStem}.png`), fullPage: true, timeout: 5000 }), 5000);
+                const saved = lstatSync(join(proofDir, `${fileStem}.png`));
+                if (!saved.isFile() || saved.size === 0)
+                    throw new SmokeFailure('screenshot-failed');
+                report.screenshot = `${fileStem}.png`;
+            }
+            catch {
+                report.failure ??= 'screenshot-failed';
+            }
+            try {
+                video = page.video();
+            }
+            catch { /* Video is best-effort evidence. */ }
+        }
+        if (context) {
+            try {
+                await bounded(() => context.close(), 5000);
+            }
+            catch {
+                report.failure ??= 'context-cleanup-failed';
+            }
+        }
+        if (video) {
+            try {
+                const path = await bounded(() => video.path(), 5000);
+                if (report.failure) {
+                    renameSync(path, join(proofDir, `${fileStem}.webm`));
+                    report.failureVideo = `${fileStem}.webm`;
+                }
+                else
+                    rmSync(path, { force: true });
+            }
+            catch { /* Preserve the original failure if video is unavailable. */ }
+        }
+    }
+    report.status = report.failure ? 'failed' : 'passed';
+    report.durationMs = Date.now() - started;
+    return report;
+}
 export async function runFlowSmoke(targetDir, opts = {}) {
     const config = loadConfig(targetDir);
     const smoke = config?.smoke;
@@ -51,91 +252,118 @@ export async function runFlowSmoke(targetDir, opts = {}) {
     const baseUrl = opts.url ?? smoke.baseUrl;
     const label = safeLabel(opts.label ?? process.env.YOKE_STORY ?? 'latest');
     const proofRel = join('.yoke', 'proof', label);
-    const proofDir = join(targetDir, proofRel);
+    let proofDir, sourceFingerprint;
+    try {
+        proofDir = statePath(targetDir, 'proof', label);
+        sourceFingerprint = workspaceFingerprint(targetDir);
+    }
+    catch {
+        console.error('Smoke evidence path or source fingerprint could not be verified; previous evidence was preserved.');
+        return 2;
+    }
+    const started = Date.now();
+    const fillValues = new Map();
+    for (const flow of smoke.flows)
+        for (const step of flow.steps ?? []) {
+            if (step.action === 'fill')
+                fillValues.set(step, step.value ?? (step.valueEnv ? process.env[step.valueEnv] : undefined));
+        }
+    const configDigest = createHash('sha256').update(JSON.stringify({ smoke, baseUrl, resolvedFillValues: [...fillValues.values()] })).digest('hex');
+    const redact = (text) => [...fillValues.values()].filter((value) => !!value).sort((a, b) => b.length - a.length).reduce((current, value) => current.split(value).join('[redacted]'), text);
     const launch = opts.launch ?? launchPlaywright;
-    const browser = await launch(targetDir);
+    let browser;
+    try {
+        browser = await bounded(() => launch(targetDir), 30_000);
+    }
+    catch {
+        console.error('Smoke browser could not start; previous evidence was preserved.');
+        return 2;
+    }
     if (!browser) {
         console.error(`Playwright not found in ${targetDir}. Install it: npm i -D playwright && npx playwright install chromium`);
         return 2;
     }
     // Wipe only once the run is actually going to happen — an exit-2 run must
     // not destroy the previous run's evidence.
-    rmSync(proofDir, { recursive: true, force: true }); // fresh evidence per run
-    mkdirSync(proofDir, { recursive: true });
+    try {
+        statePath(targetDir, 'proof', label);
+        rmSync(proofDir, { recursive: true, force: true }); // fresh evidence per run
+        mkdirSync(proofDir, { recursive: true });
+    }
+    catch {
+        try {
+            await bounded(() => browser.close(), 5000);
+        }
+        catch { /* Report setup failed. */ }
+        console.error('Smoke evidence directory could not be prepared.');
+        return 2;
+    }
     const videoTmp = join(proofDir, '.video-tmp');
-    let green = 0;
+    let baseOrigin = 'unavailable', browserVersion;
     try {
-        for (const flow of smoke.flows) {
-            const context = await browser.newContext({ recordVideo: { dir: videoTmp } });
-            const page = await context.newPage();
-            const errors = [];
-            page.on('console', (msg) => {
-                const m = msg;
-                if (m.type?.() === 'error')
-                    errors.push(String(m.text?.() ?? msg));
-            });
-            page.on('pageerror', (err) => {
-                errors.push(String(err?.message ?? err));
-            });
-            let reason;
-            try {
-                const resp = await page.goto(baseUrl + flow.path, { waitUntil: 'load', timeout: 30_000 });
-                if (resp && !resp.ok())
-                    reason = `HTTP ${resp.status()}`;
-                if (!reason && flow.landmark) {
-                    try {
-                        await page.waitForSelector(flow.landmark, { timeout: 10_000 });
-                    }
-                    catch {
-                        reason = `landmark "${flow.landmark}" not found`;
-                    }
-                }
-                if (!reason && errors.length > 0) {
-                    reason = `${errors.length} console error(s): ${errors[0].slice(0, 200)}`;
-                }
-            }
-            catch (e) {
-                reason = e.message.split('\n')[0];
-            }
-            // The screenshot IS the evidence — taken on success AND failure; a crashed
-            // page must not mask the original failure.
-            const shotName = `${safeName(flow.name)}.png`;
-            let shotOk = false;
-            try {
-                await page.screenshot({ path: join(proofDir, shotName), fullPage: true });
-                shotOk = true;
-            }
-            catch { /* keep the original reason */ }
-            const video = page.video();
-            await context.close();
-            let videoKept = false;
-            if (video) {
-                try {
-                    const vpath = await video.path();
-                    if (reason) {
-                        renameSync(vpath, join(proofDir, `${safeName(flow.name)}.webm`));
-                        videoKept = true;
-                    }
-                    else {
-                        rmSync(vpath, { force: true });
-                    }
-                }
-                catch { /* video is best-effort evidence */ }
-            }
-            if (reason) {
-                const saved = [shotOk ? 'screenshot' : null, videoKept ? 'video' : null].filter(Boolean).join(' + ');
-                console.log(`✘ ${flow.name} — ${reason}${saved ? ` (${saved} saved under ${proofRel})` : ''}`);
-            }
-            else {
-                green++;
-                console.log(`✔ ${flow.name} (screenshot: ${join(proofRel, shotName)})`);
+        baseOrigin = new URL(baseUrl).origin;
+    }
+    catch { /* Navigation reports the invalid address. */ }
+    try {
+        const version = browser.version?.();
+        if (version)
+            browserVersion = redact(version.slice(0, 120));
+    }
+    catch { /* Optional runtime metadata. */ }
+    const report = {
+        version: 1, startedAt: new Date(started).toISOString(), generatedAt: '', durationMs: 0, status: 'failed',
+        sourceFingerprint, afterSourceFingerprint: null, sourceStable: false, configDigest,
+        environment: { platform: process.platform, architecture: process.arch, nodeVersion: process.version, driver: opts.launch ? 'injected' : 'playwright-chromium', ...(browserVersion ? { browserVersion } : {}), baseOrigin: redact(baseOrigin), viewport: { width: 1280, height: 720 } },
+        flows: [],
+    };
+    const filenames = new Set();
+    try {
+        for (const [index, flow] of smoke.flows.entries()) {
+            const baseName = safeName(redact(flow.name));
+            let fileStem = baseName, suffix = index + 1;
+            while (filenames.has(fileStem.toLowerCase()))
+                fileStem = `${baseName}-${suffix++}`;
+            filenames.add(fileStem.toLowerCase());
+            const result = await runFlow(browser, flow, baseUrl, proofDir, fileStem, fillValues, redact(flow.name));
+            report.flows.push(result);
+            if (result.status === 'failed') {
+                const saved = [result.screenshot ? 'screenshot' : null, result.failureVideo ? 'video' : null].filter(Boolean).join(' + ');
+                const failedStep = result.steps.find(step => step.status === 'failed');
+                console.log(`✘ ${result.name} — ${failedStep ? `step ${failedStep.index} (${failedStep.action}): ` : ''}${result.failure}${saved ? ` (${saved} saved under ${proofRel})` : ''}`);
             }
+            else
+                console.log(`✔ ${result.name} (screenshot: ${join(proofRel, result.screenshot)})`);
         }
     }
     finally {
-        await browser.close();
+        try {
+            await bounded(() => browser.close(), 5000);
+        }
+        catch {
+            report.failure = 'browser-cleanup-failed';
+        }
         rmSync(videoTmp, { recursive: true, force: true });
     }
+    try {
+        report.afterSourceFingerprint = workspaceFingerprint(targetDir);
+    }
+    catch { /* Missing identity prevents a pass. */ }
+    report.sourceStable = report.sourceFingerprint === report.afterSourceFingerprint;
+    if (!report.sourceStable)
+        report.failure ??= 'source-changed-or-unavailable';
+    const green = report.flows.filter(flow => flow.status === 'passed').length;
+    report.status = !report.failure && green === smoke.flows.length ? 'passed' : 'failed';
+    report.generatedAt = new Date().toISOString();
+    report.durationMs = Date.now() - started;
+    try {
+        writeFileSync(statePath(targetDir, 'proof', label, 'report.json'), JSON.stringify(report, null, 2), { mode: 0o600 });
+    }
+    catch {
+        console.error('Smoke report could not be saved.');
+        return 2;
+    }
+    if (report.failure)
+        console.log(`✘ Flow-smoke evidence: ${report.failure}`);
     console.log(`Flow-smoke: ${green}/${smoke.flows.length} flows green — proof: ${proofRel}`);
-    return green === smoke.flows.length ? 0 : 1;
+    return report.status === 'passed' ? 0 : 1;
 }

package/docs/BENCHMARK-MANIFEST.md

@@ -0,0 +1,131 @@
+# Benchmark comparison manifests
+
+Yoke 1.22.0 adds a versioned provenance and comparability contract to the direct
+Codex comparison tools. This changes the tooling, not the historical results.
+No authenticated development run or new savings measurement is implied.
+
+## What a new result records
+
+The result document has schemaVersion 2 and a manifest with schemaVersion 1.
+The manifest declares a unique comparison identity, its purpose (workflow or
+controlled), the expected arms, the planned paired repeat count, and every
+condition that is intentionally allowed to differ between arms. Each declared
+difference needs a field name and a reason.
+
+Each run contains its own context:
+
+| Section | Recorded conditions |
+| --- | --- |
+| Source | Package version, Git commit, dirty state, SHA-256 build digest and whether source/build inputs stayed stable during the run |
+| Fixture | Fixture identity and SHA-256 digests of the seed, original acceptance files and shared requirements |
+| Execution | Provider, requested model, provider-reported model identities, effort, routing, native delegation, native goals, worker count and workflow |
+| Prompt | Digest and scope of the submitted input: direct provider prompt or Yoke PRD/configuration bundle |
+| Startup | Permissions, bare mode, ignore-rules, commit policy, isolation, timeout policy and user-state policy |
+| Environment | Platform, architecture, Node version, provider CLI version, hashed host identity, background-load policy and whether skills/plugins were audited |
+
+The build digest hashes the actual runtime files, canon, adapters/hooks, package
+metadata, dependency lockfile and comparison tooling. It is recorded even for a
+clean checkout, because an ignored dist directory can be stale. Dirty work is
+therefore identified by both its base commit and runtime digest. Changes during a
+run invalidate the stable-source condition. Missing Git or CLI provenance remains
+unknown; it is never filled from a version written into an older report.
+
+These digests identify recorded inputs. They are not signatures and do not prove
+that a provider served a particular model. Reported model identity comes from
+provider telemetry, never from the requested alias as a fallback.
+
+## Submitted inputs and effective prompts
+
+The direct arm records a digest of the prompt sent to the provider. The Yoke arm
+records a digest of the PRD and generated configuration submitted to the workflow.
+Those inputs are expanded into story prompts by the separately hashed runtime.
+The manifest labels these different scopes explicitly.
+
+The tool does not claim to capture every dynamically expanded prompt, retry
+message, provider system instruction, discovered skill or native context.
+The seed and requirement digests still have to agree across all arms. A prompt
+digest difference is permitted only when the manifest declares it.
+
+## Current workflow comparison
+
+The comparison still measures one direct Codex session against Yoke's normal
+story execution. Yoke can add worktrees, per-story provider starts, verification
+and commits. These are deliberate workflow differences, not isolated measurements
+of a scheduler or model-call overhead.
+
+The existing direct-arm ignore-rules flag is retained and explicitly declared as
+a startup-policy difference. Yoke retains its normal project rule handling.
+Both arms request bare mode and disable native multi-agent delegation. The tool
+does not silently modify global provider configuration or user rules.
+
+Model and effort must match across arms unless a different experiment explicitly
+declares those fields as variables. The same applies to actual model identities:
+matching aliases alone do not establish a same-model comparison. An allowed
+difference never makes a missing value valid. Fixture, requirement and acceptance
+differences cannot be waived.
+
+Conditions must stay stable within repeated runs of the same arm. A changing
+adaptive model mix therefore needs a separately designed comparison contract;
+this fixed-arm workflow tool does not silently pool such runs.
+
+## Analysis and output states
+
+Run the analyzer on already recorded result files:
+
+    node bench/analyze-codex-comparison.mjs path/to/results.json
+
+Files may contribute different arms of the same declared comparison. They must
+agree on the manifest and supply every planned arm/repeat exactly once.
+Different comparison identities are never pooled merely because their fixture
+and arm labels match.
+
+| State | Meaning |
+| --- | --- |
+| verified | All declared paired runs exist, recorded conditions match the contract, immutable acceptance passes, and input/cache/output telemetry is present |
+| incompatible | Undeclared differences, changing within-arm conditions, conflicting manifests or duplicate measurements |
+| incomplete | Some planned arms or repeats are missing |
+| acceptance-failed | An arm did not pass immutable acceptance; its short failure time cannot count as a speedup |
+| unverified | Missing/unknown provenance or telemetry, an unsupported schema, invalid context or an invalid variable declaration |
+| legacy/unverified | The input predates manifests; its reported provenance and measurements remain readable but are not promoted to a verified comparison |
+
+Only verified comparisons produce entries in the top-level groups array.
+Other measurements remain in runs and explicitly labeled diagnostic summaries.
+Missing or partial token measurements remain null. The analyzer does not invent
+USD costs, CPU/memory measurements or savings percentages.
+
+A successfully parsed diagnostic report can exit 0 while containing no verified
+comparison. Consumers must inspect comparison status and groups. Malformed JSON,
+impossible cache accounting, invalid timing and empty measurement inputs fail
+the command.
+
+## Historical records
+
+The analyzer reads both older results arrays and the runs arrays in dated
+aggregate reports. It preserves their reported version and commit under
+legacyReports, marks them legacy/unverified and leaves performance groups empty.
+It no longer hardcodes Yoke 1.19.0 or the September audit commit.
+
+The September 29 comparison and September 30 corrected smoke remain historical
+evidence with their original sample sizes and limitations. The latter has no
+contemporaneous baseline and must not be combined with the former to claim a
+new relative speedup.
+
+## Measurement limits and authorized execution
+
+Manifest verification establishes recorded comparability, not statistical
+confidence, complete environment isolation or general product quality.
+Current fixtures have visible tests and are small. Host load is uncontrolled,
+skills/plugins are not exhaustively audited, and the dependency lockfile does
+not certify every installed dependency or provider-internal setting.
+
+Wall time starts after fixture preparation and ends when the runner exits.
+Independent acceptance duration is separate; summaries also report elapsed time
+through that acceptance. Source/environment hashing and fixture setup are
+outside that timed interval.
+
+The comparison launcher makes real authenticated provider calls. Run it only
+under the user's authorized experiment scope. It accepts explicit arms, repeats,
+model and effort; its default result root is a short OS-temporary directory
+whose logs are retained. Tooling tests use synthetic records and do not launch
+providers. An existing authorization for exactly two Curiuma development runs
+is not permission for an additional fixture matrix or model-routing study.

package/docs/CODE-INTELLIGENCE.md

@@ -28,9 +28,51 @@ Install and pin these tools in the project or developer environment before enabl
 
 - Every request is tied to a workspace and a content-addressed snapshot of committed and uncommitted, non-sensitive files.
 - Paths are workspace-relative; traversal, symlinks, `.env`/key material and policy-excluded paths are rejected.
-- Read calls are bounded by timeout and output budgets. Results carry backend, version, source path, content hash, resolution and freshness.
+- Read calls share a request deadline and a complete-response output budget. Results distinguish backend identity, source location, semantic resolution and unverified index freshness. See the limits and evidence contracts below.
 - Edits run in a disposable Yoke sandbox. Preview writes a durable plan and diff but requires an approval record created by the Yoke control layer.
 - Apply rechecks the snapshot, plan expiry, plan hash, an exclusive transaction lock and idempotency. It produces a managed worktree and does not commit or merge; the existing Yoke loop and gates remain authoritative for integration.
 - Network access is not needed by the facade. Backend installation and any backend-specific network behavior remain an explicit environment concern.
 
 For a host that has no native MCP support (currently Pi), use the normal Yoke loop and bounded CLI/skill adapter. Yoke does not invent a second MCP transport for that host.
+
+## Evidence and trace contracts
+
+`code_trace` treats Serena's incoming reference list as references to the requested symbol. Each validated referencing symbol has an edge **to the requested target**. Two adjacent results never imply an edge between those results. Incoming implementation lists similarly use the `implements` relation. A bare symbol name is resolved to a unique path-bound Serena identity before requesting these relations; ambiguous targets remain unresolved.
+
+The pinned Graft trace interface returns text. Until an explicit edge format is validated, its output is retained as structural candidates, without invented call edges. Incoming references cannot establish outgoing calls, imports or inheritance: unsupported direction/relation combinations return partial results and explain the missing contract. `require_resolved` excludes unresolved structural candidates; it does not turn an unsupported query into a resolved graph. Semantic trace results currently cover one hop. Requests for greater depth are marked unverified instead of pretending traversal was completed.
+
+`frontier_remaining` counts known entries omitted by result limits, and `traversal_complete` is false when exhaustive traversal is unverified. Zero known omissions does not prove that no other references exist. Node limits preserve graph endpoints: returned edges never point at removed nodes.
+
+The workspace snapshot is content-addressed and an explicitly supplied snapshot is checked against the current workspace before processing. This check does **not** prove that Graft's index, Graphify's graph or the language server has processed those exact file contents. The supported wire contracts do not provide an independently validated index-to-snapshot binding. Consequently backend evidence uses `freshness: "unknown"` and `content_hash: null`; an untrusted backend field claiming `current` is not accepted as proof. The facade no longer stamps a current workspace file hash onto potentially older evidence.
+
+Recognized, path-bound Serena symbol records can have `resolution: "resolved"` while freshness remains unknown. Unrecognized records remain unresolved and cannot create symbols or edges. Read responses use `status: "partial"` and partial coverage for available backends because index freshness and exhaustive coverage are not established. A successful process call alone does not imply complete coverage. Missing backends remain separately identified in `backends_missing`.
+
+Each retained evidence link has a matching `provenance.evidence_id`. This additive field allows callers to resolve evidence IDs and lets output reduction remove unused provenance without breaking retained links. No response cache is used; no stale evidence is reused under a new snapshot or query.
+
+## Output and time limits
+
+The facade forwards all four configured limits:
+
+```yaml
+codeIntelligence:
+  mode: shadow
+  limits:
+    tokenBudget: 2400
+    timeoutMs: 10000
+    maxBytes: 2000000
+    maxBackends: 3
+```
+
+The effective output cap is the smaller of `maxBytes` and the effective token budget. A request's `token_budget`, where supported, can lower the configured cap, but cannot raise it. The default configured token budget is 2400. The budget covers the entire serialized JSON response in MCP `structuredContent`: result data, provenance, warnings, identifiers, coverage, errors and the metrics themselves. The outer JSON-RPC framing and the short MCP text summary are outside that response.
+
+**Token accounting is deliberately conservative:** one UTF-8 byte consumes one budget unit. `metrics.result_tokens` is therefore an estimate with `token_count_kind: "estimated"` and `token_count_method: "utf8_bytes_conservative"`. It is not provider-measured usage, a tokenizer-specific exact count or a billing estimate. `metrics.returned_bytes` is the actual UTF-8 size of the serialized structured response, including the metrics. This replaces the earlier four-bytes-per-token approximation and makes the same numeric budget stricter; increase the configured budget explicitly if a workflow requires larger context, rather than treating the old number as an exact token allowance.
+
+When an answer does not fit, text is shortened at Unicode-safe boundaries and lower-ranked entries are removed. Arrays and operation receipt fields keep their schema, retained graph edges have valid endpoints, and unused provenance is removed. The answer reports `partial`, adds a truncation warning and never claims complete coverage. Narrow the query or raise the configured budget to obtain omitted content; `next_cursor: null` does not imply a complete search.
+
+A budget can be smaller than the mandatory response envelope. For example, 128 budget units cannot encode all required identifiers and error fields. Such requests fail with `BUDGET_EXCEEDED` **before a backend is invoked**. The small, fixed-shape error envelope is the only output-cap exception; its size is reported accurately, and it contains no backend payload or unbounded error text. Apply additionally reserves space for its entire concrete receipt, including all changed paths and a possible deadline warning, before starting a transaction. An insufficient receipt budget rejects the apply without mutating. A completed apply keeps its transaction receipt even if synchronous work crossed the deadline.
+
+The effective deadline is the smaller of configured `timeoutMs` (10000 ms by default) and the request's `timeout_ms`/tool default. All backend calls, semantic target resolution and preview operations consume the same remaining time. MCP initialization and its subsequent tool call also share that allowance. A backend which ignores its timeout is closed, late results are discarded, and no subsequent backend starts after expiry. Backend shutdown has a separate bounded cleanup grace; synchronous filesystem snapshot/transaction operations cannot be preempted mid-operation, so the deadline is not an exact end-to-end wall-clock promise. A final deadline check after normalization and output reduction marks delayed results partial and keeps any completed operation's receipt. A preview needing the former 120000 ms tool default must also have a configured timeout of at least that size.
+
+## Validation scope
+
+The regression suite uses model-free adapters and local synthetic MCP processes. It verifies reference direction and endpoints, unknown payload handling, honest freshness and coverage, aggregate output limits, Unicode boundaries, evidence link preservation, tiny-budget failures, limit propagation, and shared deadlines including initialization. It does not assert a successful run against installed authenticated backends or an exact provider-token saving.

package/docs/CODEX-COMPARISON-2026-09-29.md

@@ -25,3 +25,18 @@ See the [Goals/resource audit](GOALS-RESOURCE-AUDIT-2026-09-29.md) for implement
 Reproduce with `bench/compare-codex.mjs`, then `bench/analyze-codex-comparison.mjs`. Use fresh, short output roots on Windows. The new summary tests verify median arithmetic, cache subtraction, unknown usage, incompatible policies and invalid measurements.
 
 Provenance: this report is disclosed as AI-assisted. Read-only text scans cannot establish human authorship or verify proprietary keyed watermarks; cryptographic verification and signer trust remain unknown without the corresponding verifier and trust policy.
+
+## Later tooling update — 1.22.0
+
+The measurements above remain the historical 1.19.0 results. The current analyzer
+reads their aggregate JSON as legacy/unverified because those runs did not record
+the new complete comparison manifest. It preserves the reported values and does
+not manufacture missing provenance or reinterpret them as 1.22.0 measurements.
+
+New runs record source/build, fixture, acceptance and submitted-input digests,
+requested and reported model identities, and explicit startup conditions.
+The historical direct-arm ignore-rules difference is now an expressly declared
+workflow variable. Undeclared cross-arm differences, missing provenance and
+failed acceptance do not produce performance comparison groups.
+See [benchmark manifests](BENCHMARK-MANIFEST.md) for the contract and limitations.
+This is a tooling change; no new authenticated comparison was performed for it.