@miller-tech/uap 2.16.6 → 2.19.5

package/dist/delivery/merge-gate.js

@@ -0,0 +1,309 @@
+/**
+ * Stub markers in ADDED code. Applied to non-test, non-docs files: test
+ * suites legitimately stub seams (the house style injects stubs everywhere),
+ * and docs/ADRs legitimately quote the markers they describe. A `todo!()`
+ * left in production code is exactly the half-delivery this check exists to
+ * catch.
+ */
+export const STUB_PATTERNS = [
+    { label: 'todo macro', re: /todo!\s*\(/ },
+    { label: 'NotImplementedError', re: /\bNotImplementedError\b/ },
+    { label: 'unimplemented', re: /\bunimplemented\b|\bnot implemented\b/i },
+    // Bounded gap (was `.*`): an adversarial multi-megabyte single line made
+    // this pattern quadratic; 120 chars is far more than any real
+    // placeholder sentence needs (security review P2).
+    { label: 'placeholder implementation', re: /\bplaceholder\b.{0,120}\b(implementation|for now)\b|\bstub(?:bed)? (?:body|implementation|for now)\b/i },
+    { label: 'TODO marker', re: /\bTODO\b/ },
+    { label: 'FIXME marker', re: /\bFIXME\b/ },
+];
+/** Apology / escape phrasing — the "sorry delta". Scanned in added lines of
+ *  every changed file and in the run's declared summaries. */
+export const SORRY_PATTERNS = [
+    { label: 'apology', re: /\bsorry\b|\bi apolog(i|y)/i },
+    { label: 'gave up', re: /\bi couldn'?t\b|\bi was unable\b|\bdidn'?t manage to\b|\bnot able to (?:complete|finish|fulfill)\b/i },
+    { label: 'refusal', re: /\bcannot (?:complete|fulfill)\b|\bunable to (?:complete|fulfill|finish)\b/i },
+];
+/**
+ * Paths that ARE the gate system. A diff touching any of these without
+ * `allowGateInfra` fails axiom-honesty — including the merge gate, its
+ * evidence gatherer, and the ledger functions the provenance and
+ * green-recompute checks consume: a PR may not weaken (or rewrite) the checks
+ * that judge it.
+ *
+ * Deliberately hard-coded in source, not a config file: an externalized list
+ * could be edited by the very PR it judges, and any edit to THIS list trips
+ * axiom-honesty against the gate itself (the list protects itself by being
+ * the gate — architect review F6).
+ */
+export const GATE_INFRA_PREFIXES = [
+    '.codex/hooks/',
+    '.github/workflows/',
+    'src/policies/enforcers/',
+    'src/delivery/merge-gate.ts',
+    'src/delivery/gate-evidence.ts',
+    'src/cli/merge-gate.ts',
+    'src/cli/merge-queue.ts',
+    'src/mission/ledger.ts',
+    'src/mission/database.ts',
+    'scripts/version-bump.sh',
+    '.uap/quality-baseline.json',
+    'config/capacity-policy.json',
+];
+/** Test paths are exempt from stub-marker scanning (seams are stubbed by
+ *  design in this codebase); docs paths are exempt because they quote the
+ *  markers they describe. */
+function isTestPath(path) {
+    return /(^|\/)test\//.test(path) || /\.(test|spec)\.[cm]?[jt]s$/.test(path);
+}
+function isDocsPath(path) {
+    return /\.(md|html|txt)$/.test(path);
+}
+/** Adversarial long lines (minified blobs, lockfiles) make multi-token
+ *  patterns expensive; cap per-line scanning (security review P2). */
+const SCAN_LINE_MAX = 8192;
+/** First matching pattern label, or null. Long lines are skipped — a real
+ *  stub marker sits on a human-scale line. */
+function firstMatch(text, patterns) {
+    for (const line of text.split('\n')) {
+        if (line.length > SCAN_LINE_MAX)
+            continue;
+        for (const p of patterns) {
+            if (p.re.test(line))
+                return p.label;
+        }
+    }
+    return null;
+}
+/**
+ * PURE decision core. Every check runs and reports (a full finding list, not
+ * first-fail) so an operator sees every reason at once; `pass` is the AND of
+ * all findings.
+ */
+export function evaluateMergeGate(inputs) {
+    const findings = [];
+    // ── 1. provenance / statement immutability ──
+    const markerOk = inputs.ledgerIntact && inputs.markerHash8 !== undefined && inputs.markerHash8 === inputs.acceptanceHash8;
+    findings.push({
+        check: 'provenance',
+        ok: markerOk,
+        detail: !inputs.ledgerIntact
+            ? 'ledger tampered: stored acceptance text no longer hashes to the stored hash'
+            : inputs.markerHash8 === undefined
+                ? `no [mission:#${inputs.missionId}:hash8] marker ties this work to frozen acceptance`
+                : inputs.markerHash8 === inputs.acceptanceHash8
+                    ? `marker hash ${inputs.markerHash8} matches frozen acceptance`
+                    : `marker hash ${inputs.markerHash8} is superseded (current: ${inputs.acceptanceHash8}) — the work was built under replanned-away criteria`,
+    });
+    // ── 2. green recompute ──
+    let greenOk = true;
+    const greenDetails = [];
+    // Tier 1 — the evidence artifact deliver records on success. Production
+    // delivered runs persist WITHOUT a checkpoint (deliver clears it), so the
+    // artifact is the seam that survives a real delivery; a present-but-invalid
+    // artifact (red gate, hatch, sha drift) is a hard failure.
+    if (inputs.evidence !== null) {
+        if (!inputs.evidence.present) {
+            greenDetails.push(`no gate-evidence artifact for ${inputs.evidence.expectedSha.slice(0, 12)}… (.uap/evidence/)`);
+        }
+        else if (!inputs.evidence.shaMatches) {
+            greenOk = false;
+            greenDetails.push('evidence artifact is bound to a different candidate sha');
+        }
+        else if (!inputs.evidence.hatchesEmpty) {
+            greenOk = false;
+            greenDetails.push('evidence artifact records gate-affecting environment hatches');
+        }
+        else if (!inputs.evidence.gatesAllZero) {
+            greenOk = false;
+            greenDetails.push('evidence artifact records a non-zero gate exit');
+        }
+    }
+    // Tier 2 — run-state history (present on interrupted/resumed shapes and
+    // hand-crafted fixtures; absent on the production delivered shape).
+    if (inputs.runState === null) {
+        greenOk = false;
+        greenDetails.push('no linked run (or run-state unreadable)');
+    }
+    else {
+        if (inputs.runState.status !== 'delivered') {
+            greenOk = false;
+            greenDetails.push(`run state is '${sanitize(inputs.runState.status)}', not 'delivered'`);
+        }
+        if (inputs.pidCorroborated === false) {
+            greenOk = false;
+            greenDetails.push('run pid does not match the pid the orchestrator spawned');
+        }
+        const history = inputs.runState.history ?? [];
+        if (history.length > 0) {
+            const last = history[history.length - 1];
+            if (!last.passed) {
+                greenOk = false;
+                greenDetails.push(`last recorded iteration failed its gates`);
+            }
+            else if (last.acceptanceMet !== undefined && last.acceptanceMet < 1) {
+                greenOk = false;
+                greenDetails.push(`final acceptance judge met only ${Math.round(last.acceptanceMet * 100)}% of criteria`);
+            }
+        }
+        else if (inputs.evidence !== null && inputs.evidence.present) {
+            // artifact-backed: status + artifact is sufficient.
+        }
+        else if (inputs.evidence === null) {
+            // caller did not check the artifact; history is the only evidence.
+        }
+        else {
+            // No artifact AND no history: the "delivered" status string alone is
+            // testimony, not evidence — refuse it (code review P1).
+            greenOk = false;
+            greenDetails.push('no recorded evidence beyond the delivered status string (deliver clears checkpoints on success; expected .uap/evidence/<sha>.json)');
+        }
+    }
+    if (inputs.openSalvageCount > 0) {
+        greenOk = false;
+        greenDetails.push(`${inputs.openSalvageCount} salvage proposal(s) await a ruling (approval-gated — landing would bypass the ruling)`);
+    }
+    const artifactNote = inputs.evidence !== null && inputs.evidence.present && inputs.evidence.gatesAllZero && inputs.evidence.hatchesEmpty && inputs.evidence.shaMatches
+        ? ' + evidence artifact green'
+        : '';
+    findings.push({
+        check: 'green-recompute',
+        ok: greenOk,
+        detail: greenOk
+            ? `fresh run-state: delivered${artifactNote}, no open salvage`
+            : greenDetails.join('; '),
+    });
+    // ── 3. sorry-delta ──
+    const stubHits = [];
+    const sorryHits = [];
+    for (const f of inputs.changedFiles) {
+        if (f.addedText.length === 0)
+            continue;
+        if (!isTestPath(f.path) && !isDocsPath(f.path)) {
+            const stub = firstMatch(f.addedText, STUB_PATTERNS);
+            if (stub)
+                stubHits.push(`${f.path} (${stub})`);
+        }
+        const sorry = firstMatch(f.addedText, SORRY_PATTERNS);
+        if (sorry)
+            sorryHits.push(`${f.path} (${sorry})`);
+    }
+    const summaries = (inputs.runState?.phaseSummaries ?? []).join('\n');
+    if (summaries.length > 0) {
+        const sorry = firstMatch(summaries, SORRY_PATTERNS);
+        if (sorry)
+            sorryHits.push(`run summaries (${sorry})`);
+    }
+    const sorryOk = stubHits.length === 0 && sorryHits.length === 0;
+    findings.push({
+        check: 'sorry-delta',
+        ok: sorryOk,
+        detail: sorryOk
+            ? `no stub or apology markers in ${inputs.changedFiles.length} changed file(s)`
+            : `stub markers: ${stubHits.length ? stubHits.join(', ') : 'none'}; apology markers: ${sorryHits.length ? sorryHits.join(', ') : 'none'}`,
+    });
+    // ── 4. axiom-honesty (gate-infra tampering) ──
+    const infraHits = inputs.changedFiles
+        .map((f) => f.path)
+        .filter((p) => GATE_INFRA_PREFIXES.some((prefix) => p === prefix || p.startsWith(prefix)));
+    const infraOk = infraHits.length === 0 || inputs.allowGateInfra === true;
+    findings.push({
+        check: 'axiom-honesty',
+        ok: infraOk,
+        detail: infraHits.length === 0
+            ? 'diff does not touch gate infrastructure'
+            : infraOk
+                ? `gate-infra changes explicitly acknowledged: ${infraHits.join(', ')}`
+                : `diff touches gate infrastructure without acknowledgment (${infraHits.join(', ')}) — pass --allow-gate-infra (or label the PR gate-infra) only if this is deliberate`,
+    });
+    return { missionId: inputs.missionId, pass: findings.every((f) => f.ok), findings };
+}
+/**
+ * Strip terminal escapes before echoing untrusted strings (run-state status
+ * comes from an agent-writable state.json — CWE-117, security review P3).
+ */
+function sanitize(text) {
+    // eslint-disable-next-line no-control-regex
+    return String(text).replace(/[\u001b\u009b]/g, '');
+}
+/**
+ * Extract the mission provenance marker from free text (a PR title or body).
+ * Prefix-pinned like the poll-executor's parser: the bracketed form must match
+ * exactly, so argv injection and partial collisions cannot forge linkage.
+ */
+export function missionMarkerOf(text) {
+    const m = /\[mission:#(\d+):([0-9a-f]{8})\]/.exec(text ?? '');
+    return m ? { missionId: Number(m[1]), hash8: m[2] } : null;
+}
+/**
+ * Parse a unified diff into changed files with their ADDED lines. Accepts the
+ * output of `git diff --unified=0 <base>...HEAD` and `gh pr diff`. Pure — the
+ * command execution lives in the callers, tests exercise only this parser.
+ *
+ * Path coverage is the security property: DELETED files (`+++ /dev/null`),
+ * RENAMED files (no `+++` line at all), and BINARY files (no headers) must all
+ * reach the axiom-honesty prefix match — `git rm .codex/hooks/x.sh` is the
+ * purest form of weakening a gate, so the deleted path is captured from the
+ * `diff --git` / `--- a/` lines (security review P1, architect F1).
+ *
+ * An ADDED content line that itself starts with `+++` is not misread as a
+ * header: `+++` only opens a file when the previous line was its `---` pair.
+ */
+export function parseUnifiedDiff(diff) {
+    const byPath = new Map();
+    const fileFor = (path) => {
+        let f = byPath.get(path);
+        if (!f) {
+            f = { path, addedText: '' };
+            byPath.set(path, f);
+        }
+        return f;
+    };
+    let current = null;
+    let inHunk = false; // true after a file's first @@ line
+    let prevWasHeaderPair = false; // previous line was a `--- ` file header
+    for (const line of diff.split('\n')) {
+        if (line.startsWith('diff --git ')) {
+            // `diff --git a/<path> b/<path>` — authoritative for renames (no +++
+            // line follows) and binaries. Register both sides; the b-side becomes
+            // the add target if a +++ header never appears.
+            const m = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
+            if (m) {
+                fileFor(m[1]); // old path (deletions, rename source)
+                current = fileFor(m[2]);
+            }
+            inHunk = false;
+            prevWasHeaderPair = false;
+            continue;
+        }
+        if (!inHunk && line.startsWith('--- ')) {
+            const old = line.slice(4);
+            // `--- a/<path>`: register the path (deletion evidence) but do not
+            // retarget added lines — only the `+++` header does that.
+            if (old.startsWith('a/') && old !== 'a/')
+                fileFor(old.slice(2));
+            prevWasHeaderPair = true;
+            continue;
+        }
+        if (!inHunk && line.startsWith('+++ ') && prevWasHeaderPair) {
+            const target = line.slice(4);
+            current =
+                target === '/dev/null'
+                    ? null // pure deletion: added lines cannot follow
+                    : fileFor(target.startsWith('b/') ? target.slice(2) : target);
+            prevWasHeaderPair = false;
+            continue;
+        }
+        prevWasHeaderPair = false;
+        if (line.startsWith('@@')) {
+            inHunk = true;
+            continue;
+        }
+        if (line.startsWith('+') && current) {
+            // Inside a hunk every `+`-leading line is content — including one that
+            // merely LOOKS like a header (`++ b/x` renders as `+++ b/x`).
+            current.addedText += line.slice(1) + '\n';
+        }
+    }
+    return [...byPath.values()];
+}
+//# sourceMappingURL=merge-gate.js.map

package/dist/delivery/merge-gate.js.map

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

package/dist/inference/analysis.d.ts

@@ -32,6 +32,29 @@ export interface PrefillSample {
     /** Reported throughput for that prefill. */
     tokensPerSecond: number;
 }
+/** The shape `analyzeTrend` needs: a throughput reading with the workload
+ * quantity that determines how comparable it is (prompt size for prefill,
+ * prompt DEPTH for decode). Structural supertype of PrefillSample, so
+ * existing callers pass unchanged; strata decode samples reuse it with
+ * `tokens` = depth, which is what makes decode buckets compare like-with-like. */
+export interface TrendSample {
+    at: number;
+    /** The quantity whose size determines the bucket — NOT always "tokens
+     * transferred" (see the decode case above). */
+    tokens: number;
+    tokensPerSecond: number;
+}
+/** A turn's prefix-cache reuse accounting. Used by the strata backend, which
+ * reports reuse as a FACT (tokens served from cache), not a counterfactual.
+ * `at` is the strata sample clock: line index for log samples, epoch ms for
+ * ring samples — comparable within one source, never across sources. */
+export interface ReuseSample {
+    at: number;
+    /** Prompt tokens the client sent. */
+    incoming: number;
+    /** Tokens served from the cache. */
+    reused: number;
+}
 /** A turn's cache/checkpoint divergence accounting. */
 export interface CheckpointSample {
     /** Prompt tokens the client sent. */
@@ -44,7 +67,7 @@ export interface CheckpointSample {
 export interface InferenceSnapshot {
     /** Seconds the server process has been running, when known. */
     uptimeSeconds?: number;
-    /** Parallel rails (`-np`). */
+    /** Parallel rails (`-np`), or /slots length on strata. */
     rails?: number;
     /** Shared KV pool size in cells (`-c`). Under --kv-unified this is TOTAL. */
     poolCells?: number;
@@ -61,6 +84,20 @@ export interface InferenceSnapshot {
     generationTimeouts?: number;
     /** Distinct server PIDs seen in the window. >1 means it spans a restart. */
     processCount?: number;
+    /**
+     * Strata-backend fields. All optional so the llama.cpp path constructs the
+     * snapshot exactly as before.
+     */
+    /** Which backend produced this snapshot — the report says so out loud. */
+    backend?: 'llamacpp' | 'strata';
+    /** Model id the backend advertises (strata /metrics engine.model). */
+    engineModel?: string;
+    /** Decode throughput per request, bucketed by prompt DEPTH. */
+    decode?: TrendSample[];
+    /** Per-request prefix-cache reuse (strata reports reuse as a fact). */
+    reuse?: ReuseSample[];
+    /** Backend-reported free VRAM in MiB (strata engine.vram_free_mib). */
+    vramFreeMiB?: number;
 }
 export interface Thresholds {
     /** Ratio of recent to early prefill below which we call it degraded. */
@@ -74,6 +111,15 @@ export interface Thresholds {
     kvFloorSlack: number;
     /** Any timeout in the window is at least a WARN. */
     timeoutsWarn: number;
+    /** Mean prefix-cache reuse fraction below which the cache is failing. */
+    reuseWarn: number;
+    /** Backend-reported free VRAM below which we warn (OOM territory). */
+    vramHeadroomWarnMiB: number;
+    /** How many recent reuse samples the cache-miss check looks at. The cache
+     * question is "is it tracking NOW", not "did every conversation since the
+     * process start reuse well" — a 23h log legitimately contains dozens of
+     * cold-start turns. */
+    reuseTailSamples: number;
 }
 export declare const DEFAULT_THRESHOLDS: Thresholds;
 /** Prompt-size buckets. Prefill tok/s is strongly size-dependent, so an
@@ -102,14 +148,18 @@ export interface TrendResult {
     note?: string;
 }
 /**
- * Compare early-life against recent prefill throughput WITHIN a size bucket.
+ * Compare early-life against recent throughput WITHIN a size bucket.
  *
  * Splitting the samples in half and averaging each side would be wrong: if
  * the workload's prompt sizes drift (and they do — conversations grow), the
  * mean moves for reasons that have nothing to do with the server. So pick the
  * bucket that has enough samples on BOTH sides and compare only within it.
+ *
+ * Generic over TrendSample: prefill samples carry prompt size in `tokens`,
+ * strata decode samples carry prompt DEPTH — the quantity that determines
+ * comparability is whatever the caller puts there.
  */
-export declare function analyzeTrend(samples: PrefillSample[], thresholds?: Thresholds): TrendResult;
+export declare function analyzeTrend(samples: TrendSample[], thresholds?: Thresholds): TrendResult;
 export interface CheckpointResult {
     /** Mean fraction of reusable tokens actually recovered. */
     recovery?: number;
@@ -119,6 +169,17 @@ export interface CheckpointResult {
 }
 /** How much of the reusable prefix the checkpoints actually deliver. */
 export declare function analyzeCheckpoints(samples: CheckpointSample[]): CheckpointResult;
+export interface ReuseResult {
+    /** Mean fraction of the sent prompt served from cache. */
+    fraction?: number;
+    /** Mean tokens re-read per turn that a healthy cache would have supplied. */
+    wastedTokens?: number;
+    samples: number;
+}
+/** Mean prefix-cache reuse over the strata samples. Strata reports reuse as a
+ * fact, so there is no reusable-vs-restored split — the health question is
+ * simply "is the cache tracking the conversation". */
+export declare function analyzeReuse(samples: ReuseSample[]): ReuseResult;
 export interface Finding {
     health: Exclude<InferenceHealth, 'UNKNOWN'>;
     /** Stable id so monitors can match on it without parsing prose. */
@@ -132,6 +193,11 @@ export interface InferenceReport {
     findings: Finding[];
     trend: TrendResult;
     checkpoints: CheckpointResult;
+    /** Strata-backend additions; undefined for the llama.cpp path so existing
+     * monitors keep their parsed shape working. */
+    backend?: 'llamacpp' | 'strata';
+    decodeTrend?: TrendResult;
+    reuse?: ReuseResult;
 }
 /** Roll a snapshot up into a verdict. Pure; no I/O, no clock. */
 export declare function assessInference(snap: InferenceSnapshot, thresholds?: Thresholds): InferenceReport;

package/dist/inference/analysis.d.ts.map

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

package/dist/inference/analysis.js

@@ -33,6 +33,22 @@ export const DEFAULT_THRESHOLDS = {
     checkpointRecoveryWarn: 0.5,
     kvFloorSlack: 0.15,
     timeoutsWarn: 1,
+    // Strata's own healthy conversations reuse 90%+ of the prefix
+    // (observed 2026-10-04: 38270/38659 = 99%). Under half means most turns
+    // re-read the whole prompt — the compaction/checkpoint starvation analog.
+    reuseWarn: 0.5,
+    // The strata reserve-aware floor. NOTE this is NOT the capacity policy's
+    // gpuMinFreeMiB (200 for the strata entry): that one is HOST-wide free
+    // VRAM from nvidia-smi; this one is strata's own /metrics reading, which
+    // already respects its --vram-reserve-mib 1200. Both floors being 600 in
+    // the first draft was a coincidence, not a coupling — tune them
+    // independently.
+    vramHeadroomWarnMiB: 600,
+    // Observed live 2026-10-04: a whole-process mean (39% over 4400 requests)
+    // fired a WARN that was really dozens of legitimate cold-start turns from
+    // OTHER sessions; the active session's recent turns reuse 95-99%. The tail
+    // is the signal.
+    reuseTailSamples: 50,
 };
 /** Prompt-size buckets. Prefill tok/s is strongly size-dependent, so an
  * average across mixed sizes is not comparable over time. */
@@ -46,16 +62,20 @@ export function sizeBucket(tokens) {
     return '>30k';
 }
 /**
- * Compare early-life against recent prefill throughput WITHIN a size bucket.
+ * Compare early-life against recent throughput WITHIN a size bucket.
  *
  * Splitting the samples in half and averaging each side would be wrong: if
  * the workload's prompt sizes drift (and they do — conversations grow), the
  * mean moves for reasons that have nothing to do with the server. So pick the
  * bucket that has enough samples on BOTH sides and compare only within it.
+ *
+ * Generic over TrendSample: prefill samples carry prompt size in `tokens`,
+ * strata decode samples carry prompt DEPTH — the quantity that determines
+ * comparability is whatever the caller puts there.
  */
 export function analyzeTrend(samples, thresholds = DEFAULT_THRESHOLDS) {
     if (samples.length < thresholds.minSamplesPerEra * 2) {
-        return { earlyCount: 0, recentCount: 0, note: 'not enough prefill samples for a trend' };
+        return { earlyCount: 0, recentCount: 0, note: 'not enough samples for a trend' };
     }
     // Bucket FIRST, then split each bucket at its OWN median time.
     //
@@ -133,6 +153,19 @@ export function analyzeCheckpoints(samples) {
         samples: usable.length,
     };
 }
+/** Mean prefix-cache reuse over the strata samples. Strata reports reuse as a
+ * fact, so there is no reusable-vs-restored split — the health question is
+ * simply "is the cache tracking the conversation". */
+export function analyzeReuse(samples) {
+    const real = samples.filter((s) => s.incoming > 0);
+    if (real.length === 0)
+        return { samples: 0 };
+    return {
+        fraction: real.reduce((a, s) => a + s.reused / s.incoming, 0) / real.length,
+        wastedTokens: real.reduce((a, s) => a + Math.max(0, s.incoming - s.reused), 0) / real.length,
+        samples: real.length,
+    };
+}
 /** Name the other slowed buckets, so a single headline number does not read
  *  as though only one prompt size is affected. */
 function alsoAffected(trend) {
@@ -226,18 +259,101 @@ export function assessInference(snap, thresholds = DEFAULT_THRESHOLDS) {
                 `(${Math.floor(snap.poolCells / snap.rails).toLocaleString()} each if evenly divided)`,
         });
     }
-    const worst = findings.reduce((acc, f) => (rank[f.health] > rank[acc] ? f.health : acc), findings.length > 0 ? 'GREEN' : 'UNKNOWN');
+    // 7. Decode decay (strata): the same bucketed early/recent comparison over
+    //    decode samples, with depth as the bucketing quantity. This is the
+    //    signal llama.cpp journals cannot give — they never log decode rate.
+    //    "Sampled window" rather than "process's life": the sample set may be
+    //    the whole serve log (a process lifetime) or the bounded /metrics
+    //    ring (a dozen recent requests), and the message must not claim more
+    //    coverage than the samples carry.
+    const decodeTrend = snap.decode !== undefined ? analyzeTrend(snap.decode, thresholds) : undefined;
+    if (decodeTrend?.ratio !== undefined) {
+        const pct = Math.round((1 - decodeTrend.ratio) * 100);
+        if (decodeTrend.ratio < thresholds.degradeRatioRed) {
+            findings.push({
+                health: 'RED',
+                code: 'decode-decay',
+                message: `decode in the ${decodeTrend.bucket}-depth bucket fell ${pct}% across the sampled window ` +
+                    `(${Math.round(decodeTrend.earlyMean)} -> ${Math.round(decodeTrend.recentMean)} tok/s)` +
+                    alsoAffected(decodeTrend),
+                remedy: 'restart the strata serve layer; if it returns within days, check the expert cache and KV residency',
+            });
+        }
+        else if (decodeTrend.ratio < thresholds.degradeRatioWarn) {
+            findings.push({
+                health: 'WARN',
+                code: 'decode-decay',
+                message: `decode in the ${decodeTrend.bucket}-depth bucket is down ${pct}% ` +
+                    `(${Math.round(decodeTrend.earlyMean)} -> ${Math.round(decodeTrend.recentMean)} tok/s)` +
+                    alsoAffected(decodeTrend),
+                remedy: 'watch it; a restart restores throughput if the decay continues',
+            });
+        }
+    }
+    // 8. Prefix-cache failure (strata): recent turns re-reading most of the
+    //    prompt. Only the TAIL counts: the question is whether the cache is
+    //    tracking the conversation NOW, and a whole-process mean mixes in
+    //    every legitimate cold start since the process began — measured on the
+    //    live 2026-10-04 log, that mean (39%) fired on a stack whose active
+    //    session was reusing 99%. A single 0% turn right after a client
+    //    compaction must not fire this on its own, hence the mean over the tail.
+    //    Samples are SORTED by `at` first: the log source is oldest-first, but
+    //    the /metrics ring is NEWEST-first, and slicing an unsorted array takes
+    //    the first N by position — the OLDEST half of a ring, inverting exactly
+    //    the current-vs-cold-start signal the tail exists for.
+    const reuse = snap.reuse !== undefined
+        ? analyzeReuse([...snap.reuse]
+            .sort((a, b) => a.at - b.at)
+            .slice(Math.max(0, snap.reuse.length - thresholds.reuseTailSamples)))
+        : undefined;
+    if (reuse?.fraction !== undefined && reuse.fraction < thresholds.reuseWarn) {
+        findings.push({
+            health: reuse.wastedTokens > 20_000 ? 'RED' : 'WARN',
+            code: 'cache-miss',
+            message: `the prefix cache is re-reading ${Math.round((1 - reuse.fraction) * 100)}% of prompts ` +
+                `(~${Math.round(reuse.wastedTokens).toLocaleString()} tokens re-read per turn)`,
+            remedy: 'a fresh or just-compacted conversation legitimately re-reads; sustained misses mean the ' +
+                'conversation cache is not tracking — check conversation_cache slots and restart if it persists',
+        });
+    }
+    // 9. VRAM headroom (strata's own reserve-aware reading). The capacity
+    //    doctor checks the HOST-wide number; this one catches another process
+    //    eating the card from under strata.
+    if (snap.vramFreeMiB !== undefined && snap.vramFreeMiB < thresholds.vramHeadroomWarnMiB) {
+        findings.push({
+            health: 'WARN',
+            code: 'vram-headroom',
+            message: `strata reports only ${snap.vramFreeMiB} MiB free (reserve-aware) — below the ` +
+                `${thresholds.vramHeadroomWarnMiB} MiB headroom floor`,
+            remedy: 'something is eating the card (another model process, a vision request); free it or lower --max-context',
+        });
+    }
+    const worst = findings.reduce((acc, f) => (rank[f.health] > rank[acc] ? f.health : acc), 'GREEN');
     // No evidence at all is UNKNOWN, never a fabricated GREEN — the same
     // fail-open posture the capacity doctor uses.
     //
-    // But "no evidence" is about the SAMPLED signals (trend, checkpoints, KV).
+    // But "no evidence" is about the SAMPLED signals (trend, checkpoints, KV,
+    // decode, reuse, VRAM). When they ARE present and nothing crossed a
+    // threshold, GREEN is the honest verdict: the 2026-10-03 draft left a
+    // healthy single-rail stack at UNKNOWN (GREEN previously required a
+    // finding to exist, and only multi-rail llama.cpp emitted one — the
+    // shared-pool info), which made a working strata backend indistinguishable
+    // from a blind probe for every monitor parsing --json.
+    //
     // A finding that fired is itself evidence, so an actionable one must never
     // be masked by an UNKNOWN rollup: generation timeouts are counted from the
     // proxy journal and can fire with none of the sampled signals present,
     // which let a RED finding pass --strict with exit 0.
     const actionable = findings.some((f) => f.health !== 'GREEN');
-    const noSampledEvidence = trend.ratio === undefined && checkpoints.samples === 0 && snap.kvBitsPerValue === undefined;
-    const health = actionable || !noSampledEvidence ? worst : 'UNKNOWN';
-    return { health, findings, trend, checkpoints };
+    const noSampledEvidence = trend.ratio === undefined &&
+        checkpoints.samples === 0 &&
+        snap.kvBitsPerValue === undefined &&
+        (snap.decode?.length ?? 0) === 0 &&
+        (snap.reuse?.length ?? 0) === 0 &&
+        snap.vramFreeMiB === undefined;
+    const health = noSampledEvidence && !actionable ? 'UNKNOWN' : worst;
+    return snap.backend !== undefined
+        ? { health, findings, trend, checkpoints, backend: snap.backend, decodeTrend, reuse }
+        : { health, findings, trend, checkpoints };
 }
 //# sourceMappingURL=analysis.js.map