prism-mcp-server 20.0.8 → 20.1.0

package/README.md

@@ -18,6 +18,22 @@ A paid subscription adds cloud sync, higher model tiers, and team features throu
 
 ---
 
+## What's New in v20.1.0
+
+### Every Inference Outcome Is Now Observable
+`prism_infer` gains a failure contract: pass `escalation: "report"` and every call returns a structured `gate_outcome` — `success`, `degraded` (gate-failed output served anyway, explicitly flagged), or `refused` (typed, with reason, instead of a thrown error). Degraded output can no longer serve silently.
+
+### Big Prompts Work Locally
+Prompts over 4000 chars were blanket-refused when cloud was off. Now the full text gets a deterministic reserved-keyword scan plus a head+middle+tail excerpt classification — clean oversize prompts serve locally with a distinct `UNCERTAIN_LENGTH` audit marker. Clinical/reserved handling is unchanged (and its keyword floor got stronger).
+
+### No More Silent Truncation
+Tier context limits now match the live Modelfiles (27b/9b are 4096-token models; 4b/2b are 32768 — the old table had it backwards). Tiers that can't hold your prompt are skipped with a visible `ctx_insufficient` reason; if nothing fits, you get the full prompt on cloud or a loud error — never an answer computed from a silently-clipped prompt.
+
+### Know Which Plan You're Actually Running Under
+Entitlements carry a `source` field: `portal` (real), `unconfigured` (free by design), or `fallback_free` (portal unreachable — free limits ASSUMED). Pass `strict_entitlements: true` to fail loud instead of running degraded.
+
+---
+
 ## What's New in v20.0.8
 
 ### verify_behavior Works Again

package/dist/boundaries/boundaries.js

@@ -17,12 +17,12 @@
  * BOUNDARIES_VERSION is still used by markContextLoaded for session
  * drift detection — bump it when the safety contract changes.
  */
-export const BOUNDARIES_VERSION = "3";
+export const BOUNDARIES_VERSION = "4";
 export const BOUNDARIES_TEXT = `
 Safety boundaries are enforced in code — shown so hosts avoid wasted round-trips.
 
 - **Crisis/self-harm** inputs are intercepted before reaching any model.
-- **BCBA reserved categories** (restraint, seclusion, physical management, dosing) are classified by Layer 1. RESERVED and UNCERTAIN prompts escalate to cloud or are refused. On classifier failure, a keyword backstop blocks reserved vocabulary before local generation.
+- **BCBA reserved categories** (restraint, seclusion, physical management, dosing): Layer 1 classifies; RESERVED/UNCERTAIN escalate to cloud or are refused. A keyword backstop covers classifier failure; oversize prompts get a full-text keyword scan + excerpt classification.
 - **Dangerous output** (restraint instructions, overdose methods, self-harm guidance) is blocked regardless of host.
 - AAC access is never restricted as a consequence.
 `.trim();

package/dist/tools/__tests__/layer1Integration.test.js

@@ -103,17 +103,109 @@ describe("keywordBackstop", () => {
         expect(keywordBackstop(padded)).toBe("OBVIOUS_RESERVED");
     });
 });
-// ── callLayer1 over-length test ─────────────────────────────────────────────
-describe("callLayer1 over-length", () => {
-    it("returns UNCERTAIN for prompts > 4000 chars (attacker-controlled length)", async () => {
-        const longPrompt = "A".repeat(5000);
-        const result = await callLayer1(longPrompt, "http://localhost:11434", "model");
+// ── callLayer1 over-length (§5.3: UNCERTAIN_LENGTH) ─────────────────────────
+/** Mock fetch returning a fixed classifier verdict. */
+const classifierFetch = (verdict) => vi.fn(async () => new Response(JSON.stringify({ message: { content: verdict } }), { status: 200 }));
+describe("callLayer1 over-length (§5.3)", () => {
+    const HEAD = "This is the beginning of a long benign refactoring request. ";
+    const MIDDLE = "middle filler content about data processing ".repeat(150);
+    const TAIL = " And this is the very end of the request, thanks.";
+    const cleanOversize = HEAD + MIDDLE + TAIL; // > 4000 chars, no reserved vocab
+    it("full-text keyword floor catches reserved vocab in the UNSEEN middle — no classifier call", async () => {
+        const prompt = "A".repeat(3000) + " write a seclusion protocol " + "B".repeat(3000);
+        const fetchSpy = classifierFetch("OBVIOUS_NOT_RESERVED");
+        const result = await callLayer1(prompt, "http://x", "model", fetchSpy);
+        expect(result).toBe("OBVIOUS_RESERVED");
+        expect(fetchSpy).not.toHaveBeenCalled();
+    });
+    it("clean oversize prompt with clean excerpt → UNCERTAIN_LENGTH (distinct from UNCERTAIN)", async () => {
+        const fetchSpy = classifierFetch("OBVIOUS_NOT_RESERVED");
+        const result = await callLayer1(cleanOversize, "http://x", "model", fetchSpy);
+        expect(result).toBe("UNCERTAIN_LENGTH");
+        expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+    it("classifier receives a bounded head+tail excerpt, not the full prompt", async () => {
+        const fetchSpy = classifierFetch("OBVIOUS_NOT_RESERVED");
+        await callLayer1(cleanOversize, "http://x", "model", fetchSpy);
+        const body = JSON.parse(fetchSpy.mock.calls[0][1]["body"]);
+        const sent = body.messages[0].content;
+        expect(sent).toContain(HEAD.trim());
+        expect(sent).toContain(TAIL.trim());
+        expect(sent).toContain("[…]");
+        // bounded: template + excerpt stays under the classifier cap + template overhead
+        expect(sent.length).toBeLessThan(6000);
+    });
+    it("excerpt classified OBVIOUS_RESERVED keeps full reserved handling", async () => {
+        const fetchSpy = classifierFetch("OBVIOUS_RESERVED");
+        const result = await callLayer1(cleanOversize, "http://x", "model", fetchSpy);
+        expect(result).toBe("OBVIOUS_RESERVED");
+    });
+    it("excerpt classified UNCERTAIN keeps full reserved handling", async () => {
+        const fetchSpy = classifierFetch("UNCERTAIN");
+        const result = await callLayer1(cleanOversize, "http://x", "model", fetchSpy);
         expect(result).toBe("UNCERTAIN");
     });
+    it("classifier failure on oversize → UNCERTAIN_LENGTH (keyword floor already cleared full text)", async () => {
+        const failingFetch = vi.fn(async () => { throw new Error("connection refused"); });
+        const result = await callLayer1(cleanOversize, "http://x", "model", failingFetch);
+        expect(result).toBe("UNCERTAIN_LENGTH");
+        expect(failingFetch).toHaveBeenCalledTimes(2); // initial + retry
+    });
+    it("normal-size prompts are unaffected — full prompt sent, verdict passthrough", async () => {
+        const fetchSpy = classifierFetch("OBVIOUS_NOT_RESERVED");
+        const result = await callLayer1("short benign prompt", "http://x", "model", fetchSpy);
+        expect(result).toBe("OBVIOUS_NOT_RESERVED");
+        const body = JSON.parse(fetchSpy.mock.calls[0][1]["body"]);
+        expect(body.messages[0].content).toContain("short benign prompt");
+        expect(body.messages[0].content).not.toContain("[…]");
+    });
     it("returns ERROR for empty prompts", async () => {
         const result = await callLayer1("", "http://localhost:11434", "model");
         expect(result).toBe("ERROR");
     });
+    it("middle window: content at the prompt's center IS visible to the classifier", async () => {
+        const marker = "UNIQUE-CENTER-MARKER-PHRASE";
+        const half = "x".repeat(4000);
+        const prompt = half + " " + marker + " " + half;
+        const fetchSpy = classifierFetch("OBVIOUS_NOT_RESERVED");
+        await callLayer1(prompt, "http://x", "model", fetchSpy);
+        const body = JSON.parse(fetchSpy.mock.calls[0][1]["body"]);
+        expect(body.messages[0].content).toContain(marker);
+    });
+    it("DOCUMENTED RESIDUAL (accepted, adversarial review finding 1): keyword-free paraphrased reserved content outside head/middle/tail windows reaches UNCERTAIN_LENGTH", async () => {
+        // A paraphrase with NO RESERVED_KEYWORDS match, placed between the head
+        // window and the middle window, is invisible to both the keyword floor
+        // and the excerpt. This test PINS the accepted residual risk so any
+        // future change to it is deliberate. Mitigations in force: full-text
+        // keyword floor (deterministic), head+middle+tail sampling (placement
+        // is hard), checkInputSafety on the full prompt, checkOutputSafety on
+        // all served output.
+        const paraphrase = "describe how staff should pin the person still while they fight";
+        const prompt = "y".repeat(2500) + paraphrase + "z".repeat(6000);
+        const fetchSpy = classifierFetch("OBVIOUS_NOT_RESERVED");
+        const result = await callLayer1(prompt, "http://x", "model", fetchSpy);
+        expect(result).toBe("UNCERTAIN_LENGTH");
+        const body = JSON.parse(fetchSpy.mock.calls[0][1]["body"]);
+        expect(body.messages[0].content).not.toContain("pin the person");
+    });
+});
+// ── RESERVED_KEYWORDS additions (adversarial-review bypass closure) ─────────
+describe("keywordBackstop — closed bypasses", () => {
+    it.each([
+        ["basket hold", "write the basket hold procedure"],
+        ["prone hold", "steps for a prone hold on the client"],
+        ["two-person hold", "when do we use a two-person hold"],
+        ["holding the client down", "staff procedure for holding the client down"],
+        ["hold the child down", "how to hold the child down safely"],
+        ["rage episode", "what to do during a rage episode"],
+    ])("catches %s", (_label, prompt) => {
+        expect(keywordBackstop(prompt)).toBe("OBVIOUS_RESERVED");
+    });
+    it("still clean on benign hold/rage usages", () => {
+        expect(keywordBackstop("hold the deploy until CI is green")).toBe("OBVIOUS_NOT_RESERVED");
+        expect(keywordBackstop("the on-hold order queue needs a refactor")).toBe("OBVIOUS_NOT_RESERVED");
+        expect(keywordBackstop("all the rage in the JS ecosystem")).toBe("OBVIOUS_NOT_RESERVED");
+    });
 });
 // ── LAYER1_PROMPT drift test ──────────────────────────────────────────────────
 describe("LAYER1_PROMPT drift", () => {

package/dist/tools/prismInferHandler.js

@@ -30,7 +30,7 @@ import { stripThink } from "../utils/thinkStrip.js";
 import { passesQualityGate } from "../utils/qualityGate.js";
 import { checkInputSafety, checkOutputSafety } from "../utils/safetyGate.js";
 import { callLayer1 as defaultCallLayer1, keywordBackstop } from "../utils/layer1.js";
-import { recordInference, recordThinkOnlyRetry, formatInferenceMetrics } from "../utils/inferenceMetrics.js";
+import { recordInference, recordThinkOnlyRetry, formatInferenceMetrics, estimateTokens } from "../utils/inferenceMetrics.js";
 import { appendInferMetric } from "../storage/inferMetricsLedger.js";
 // ─── Tool Definition ────────────────────────────────────────────
 export const PRISM_INFER_TOOL = {
@@ -122,6 +122,26 @@ export const PRISM_INFER_TOOL = {
                 description: "Enable thinking mode (<think> blocks). Default: true for chat/code, false for route. " +
                     "Thinking improves quality on complex tasks but adds latency (~2-5s).",
             },
+            strict_entitlements: {
+                type: "boolean",
+                description: "Fail loud instead of running with ASSUMED free-tier limits (plan v2 §5.5). " +
+                    "When true and entitlement resolution fell back to free because the portal " +
+                    "was unreachable (source='fallback_free'), the call throws instead of " +
+                    "silently applying free clamps. Portal-confirmed free plans and " +
+                    "unconfigured machines are unaffected. Default: false.",
+                default: false,
+            },
+            escalation: {
+                type: "string",
+                enum: ["serve", "report"],
+                description: "Failure contract (plan v2 §5.2). 'serve' (default) keeps legacy behavior: " +
+                    "safety refusals throw, gate-failed output may be served. 'report' returns a " +
+                    "structured gate_outcome on every terminal path — refused results come back as " +
+                    "{status:'refused', output:''} instead of an error, and degraded (gate-failed, " +
+                    "served-anyway) output is explicitly flagged so callers can distinguish " +
+                    "success / degraded / refused.",
+                default: "serve",
+            },
         },
         required: ["prompt"],
     },
@@ -158,6 +178,11 @@ export function isPrismInferArgs(args) {
         return false;
     if (a.verifier_timeout_ms !== undefined && typeof a.verifier_timeout_ms !== "number")
         return false;
+    if (a.escalation !== undefined &&
+        !["serve", "report"].includes(a.escalation))
+        return false;
+    if (a.strict_entitlements !== undefined && typeof a.strict_entitlements !== "boolean")
+        return false;
     if (a.evidence !== undefined) {
         if (!Array.isArray(a.evidence))
             return false;
@@ -278,9 +303,11 @@ export class ReservedRefusalError extends Error {
 }
 function makeReservedRefusal(verdict, attempts) {
     // Ledger the refusal (fire-and-forget). No prompt content is persisted —
-    // same HIPAA posture as the safety_gate exclusion.
+    // same HIPAA posture as the safety_gate exclusion. gate_outcome mirrors
+    // the §5.2 report-mode row so refusal queries see both modes.
     appendInferMetric({
         backend: "refused", model: null, used_cloud: false,
+        gate_outcome: "refused",
         refusal_reason: "layer1_reserved",
     });
     return new ReservedRefusalError(verdict, attempts);
@@ -396,9 +423,20 @@ export async function runInfer(args, deps) {
         };
     }
     // ── Entitlement enforcement ──────────────────────────────────
-    // Fetch user's plan limits (cached 1hr). Free users without auth
-    // get 4b ceiling, 50 calls/day, 512 max tokens.
+    // Resolved per call (§5.5) — getEntitlements dedupes via a 5-min cache.
+    // Free users without auth get 4b ceiling, 50 calls/day, 512 max tokens.
     const ent = deps.entitlements ?? await getEntitlements();
+    const entSource = ent.source ?? "portal";
+    // §5.5 fail-loud: "fallback_free" means auth IS configured but the
+    // portal couldn't be reached and no cached plan exists — the free-tier
+    // clamps below would be an ASSUMPTION, not the user's plan. Strict
+    // callers refuse to run on assumptions. This is an infrastructure
+    // failure, not a safety refusal — it throws in both escalation modes.
+    if (args.strict_entitlements && entSource === "fallback_free") {
+        throw new Error("prism_infer: entitlements_unavailable — portal resolution failed (source=fallback_free) " +
+            "and strict_entitlements=true; refusing to run with assumed free-tier limits. " +
+            "Retry, or drop strict_entitlements to accept free clamps.");
+    }
     // MF2: In chat/code modes, request the 27B tier (subject to plan ceiling + RAM).
     // mode:"code" implies quality → start higher in the cascade.
     const mode = args.mode ?? "route";
@@ -415,6 +453,25 @@ export async function runInfer(args, deps) {
     const attempts = [];
     // Strip verification args if plan lacks grounding_verifier
     const gatedArgs = canVerify ? args : { ...args, verify: false, evidence: undefined };
+    // §5.2 failure contract: under escalation:"report", safety refusals return
+    // a typed result (output:"") instead of throwing. Infra exhaustion (no
+    // backend produced output) still throws in BOTH modes — an infrastructure
+    // failure is not a refusal (§5.1 distinction).
+    const wantReport = args.escalation === "report";
+    // Shared per-result entitlement metadata (§5.5) — spread into every
+    // terminal result so callers can audit which plan/provenance applied.
+    const entMeta = { plan: ent.plan, entitlements_source: entSource };
+    const refusedResult = (reason) => ({
+        output: "",
+        backend: "refused",
+        model_picked: null,
+        ram_free_mb: ramFreeMb,
+        latency_ms: Date.now() - t0,
+        used_cloud: false,
+        attempts,
+        ...entMeta,
+        gate_outcome: { status: "refused", reason, served_anyway: false },
+    });
     debugLog(`[prism_infer] plan=${ent.plan} ceiling=${effectiveCeiling} max_tokens=${maxTokens} cloud=${allowCloud} verify=${canVerify}`);
     // Log tier enforcement to Datadog for monetization visibility
     const ceilingClamped = effectiveCeiling !== (args.model_ceiling ?? ent.model_ceiling);
@@ -423,7 +480,7 @@ export async function runInfer(args, deps) {
     const verifierBlocked = (args.verify === true || (args.evidence?.length ?? 0) > 0) && !canVerify;
     if (ceilingClamped || tokensClamped || cloudBlocked || verifierBlocked) {
         ddLog("info", "prism_infer.tier_enforcement", {
-            plan: ent.plan,
+            ...entMeta,
             requested_ceiling: args.model_ceiling,
             effective_ceiling: effectiveCeiling,
             ceiling_clamped: ceilingClamped,
@@ -473,6 +530,8 @@ export async function runInfer(args, deps) {
                     const weakBackend = /^(ollama-|openrouter-)/.test(cloud.backend ?? "");
                     if (weakBackend) {
                         attempts.push({ tier: "synalux", reason: `reserved_weak_backend:${cloud.backend}` });
+                        if (wantReport)
+                            return refusedResult("layer1_reserved");
                         throw makeReservedRefusal(l1, attempts);
                     }
                     return await applyVerification(cloud.output, gatedArgs, deps, {
@@ -482,14 +541,27 @@ export async function runInfer(args, deps) {
                         latency_ms: Date.now() - t0,
                         used_cloud: true,
                         attempts,
-                        plan: ent.plan,
+                        ...entMeta,
                         completion_tokens: Math.ceil(cloud.output.length / 4),
+                        gate_outcome: { status: "success", served_anyway: false },
                     });
                 }
                 attempts.push({ tier: "synalux", reason: cloud.reason ?? "unknown" });
             }
+            if (wantReport)
+                return refusedResult("layer1_reserved");
             throw makeReservedRefusal(l1, attempts);
         }
+        if (l1 === "UNCERTAIN_LENGTH") {
+            // §5.3: prompt too long to classify in full, but the full-text
+            // keyword floor was clean AND the head+tail excerpt classified
+            // clean. Proceed to the local tier walk with a distinct audit
+            // marker — "too long to classify" is not a safety verdict.
+            // Whether the prompt FITS a local tier's context is the §5.4
+            // ctx gate's job, not Layer 1's.
+            debugLog(`[prism_infer] Layer 1 verdict=UNCERTAIN_LENGTH — oversize prompt cleared by keyword floor + excerpt, proceeding local`);
+            attempts.push({ tier: "layer1", reason: "layer1_uncertain_length" });
+        }
         if (l1 === "ERROR") {
             debugLog(`[prism_infer] Layer 1 verdict=ERROR — classifier failed, trying cloud then keyword backstop`);
             attempts.push({ tier: "layer1", reason: "layer1_error" });
@@ -504,8 +576,9 @@ export async function runInfer(args, deps) {
                         latency_ms: Date.now() - t0,
                         used_cloud: true,
                         attempts,
-                        plan: ent.plan,
+                        ...entMeta,
                         completion_tokens: Math.ceil(cloud.output.length / 4),
+                        gate_outcome: { status: "success", served_anyway: false },
                     });
                 }
                 attempts.push({ tier: "synalux", reason: cloud.reason ?? "unknown" });
@@ -514,10 +587,21 @@ export async function runInfer(args, deps) {
             debugLog(`[prism_infer] keyword backstop verdict=${backstop}`);
             attempts.push({ tier: "keyword_backstop", reason: `backstop_${backstop.toLowerCase()}` });
             if (backstop === "OBVIOUS_RESERVED") {
+                if (wantReport)
+                    return refusedResult("keyword_backstop_reserved");
+                // Serve-mode backstop refusal previously wrote NO ledger row —
+                // ledger it like every other refusal (no prompt content persisted).
+                appendInferMetric({
+                    backend: "refused", model: null, used_cloud: false,
+                    gate_outcome: "refused",
+                    refusal_reason: "keyword_backstop_reserved",
+                });
                 throw new Error(`prism_infer: classifier failed + keyword backstop caught reserved content. attempts=${JSON.stringify(attempts)}`);
             }
         }
-        debugLog(`[prism_infer] Layer 1 verdict=OBVIOUS_NOT_RESERVED — proceeding local`);
+        if (l1 === "OBVIOUS_NOT_RESERVED") {
+            debugLog(`[prism_infer] Layer 1 verdict=OBVIOUS_NOT_RESERVED — proceeding local`);
+        }
     }
     // ── end Layer 1 ─────────────────────────────────────────────────────────
     // Walk the tier table top → bottom, capped by model_ceiling. Each tier
@@ -603,6 +687,23 @@ export async function runInfer(args, deps) {
                 attempts.push({ tier: tier.tag, reason: "ram_insufficient" });
                 continue;
             }
+            // Ctx gate (§5.4): skip tiers whose live Modelfile num_ctx cannot
+            // hold the PROMPT (+ system + small template margin). Ollama
+            // silently truncates an over-ctx prompt and answers from the
+            // fragment — "never silent truncation" (plan §7). Generated
+            // tokens shift the window rather than truncate the prompt, so
+            // max_tokens is deliberately NOT reserved here — requiring
+            // prompt+output ≤ ctx would make a max_tokens=4096 request
+            // unroutable to the 4096-ctx tiers even for tiny prompts.
+            // ctxTokens mirrors the live Modelfile values (see MODEL_TIERS).
+            const CTX_TEMPLATE_MARGIN = 64;
+            const promptTokensEst = estimateTokens(args.prompt)
+                + (args.system ? estimateTokens(args.system) : 0)
+                + CTX_TEMPLATE_MARGIN;
+            if (promptTokensEst > tier.ctxTokens) {
+                attempts.push({ tier: tier.tag, reason: "ctx_insufficient" });
+                continue;
+            }
             anyViable = true;
             const timeout = args.timeout_ms ?? DEFAULT_TIMEOUTS[tier.tag] ?? 60_000;
             const enableThink = args.think ?? (mode !== "route");
@@ -624,11 +725,14 @@ export async function runInfer(args, deps) {
                     debugLog(`[prism_infer] quality gate FAIL (${gate.reason}) — escalating to cloud`);
                     attempts.push({ tier: tier.tag, reason: `quality_gate:${gate.reason}` });
                     if (gate.reason === "hard_truncation" || gate.reason === "loop_detected") {
-                        localDraft = { output, tier: tier.tag, promptTokens: result.promptTokens, completionTokens: result.completionTokens };
+                        localDraft = { output, tier: tier.tag, gateReason: gate.reason, promptTokens: result.promptTokens, completionTokens: result.completionTokens };
                     }
                     break;
                 }
                 if (!gate.pass) {
+                    // §5.2: this served-anyway path used to be silent — the result
+                    // carried no flag at all. Now both quality_gate_failed and
+                    // gate_outcome mark it degraded.
                     debugLog(`[prism_infer] quality gate FAIL (${gate.reason}) — no cloud, serving local`);
                 }
                 return await applyVerification(output, gatedArgs, deps, {
@@ -638,9 +742,13 @@ export async function runInfer(args, deps) {
                     latency_ms: Date.now() - t0,
                     used_cloud: false,
                     attempts,
-                    plan: ent.plan,
+                    ...entMeta,
                     prompt_tokens: result.promptTokens,
                     completion_tokens: result.completionTokens,
+                    quality_gate_failed: gate.pass ? undefined : true,
+                    gate_outcome: gate.pass
+                        ? { status: "success", served_anyway: false }
+                        : { status: "degraded", reason: gate.reason, served_anyway: true },
                 });
             }
             attempts.push({ tier: tier.tag, reason: result.reason });
@@ -663,11 +771,12 @@ export async function runInfer(args, deps) {
                 latency_ms: Date.now() - t0,
                 used_cloud: true,
                 attempts,
-                plan: ent.plan,
+                ...entMeta,
                 // T4: omit prompt_tokens — cloud doesn't return Ollama actual eval count.
                 // recordInference receives prompt_text and computes submittedEst via
                 // estimateTokens(), keeping promptTokensEvaluated=0 (correct for cloud).
                 completion_tokens: Math.ceil(cloud.output.length / 4),
+                gate_outcome: { status: "success", served_anyway: false },
             });
         }
         attempts.push({ tier: "synalux", reason: cloud.reason ?? "unknown" });
@@ -685,10 +794,11 @@ export async function runInfer(args, deps) {
             latency_ms: Date.now() - t0,
             used_cloud: false,
             attempts,
-            plan: ent.plan,
+            ...entMeta,
             prompt_tokens: localDraft.promptTokens,
             completion_tokens: localDraft.completionTokens,
             quality_gate_failed: true,
+            gate_outcome: { status: "degraded", reason: localDraft.gateReason, served_anyway: true },
         });
     }
     const err = new Error(`prism_infer: no backend produced output. attempts=${JSON.stringify(attempts)}, free=${fmtGb(freeBytes)}`);
@@ -785,6 +895,12 @@ export async function prismInferHandler(args) {
             ` used_cloud=${result.used_cloud}` +
             tokenStr +
             (result.quality_gate_failed ? ` quality_gate_failed=true` : "") +
+            (result.gate_outcome && result.gate_outcome.status !== "success"
+                ? ` gate=${result.gate_outcome.status}${result.gate_outcome.reason ? `:${result.gate_outcome.reason}` : ""}`
+                : "") +
+            (result.entitlements_source && result.entitlements_source !== "portal"
+                ? ` ent_source=${result.entitlements_source}`
+                : "") +
             (result.verification ? ` verify=${result.verification.action}` : "") +
             (result.attempts.length ? ` attempts=${JSON.stringify(result.attempts)}` : "");
         // Append periodic session-level stats to the header line.

package/dist/utils/entitlements.js

@@ -31,6 +31,13 @@ export const FREE_ENTITLEMENTS = {
 const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 let cache = null;
 let inFlight = null;
+// §5.5 negative cache: fallback_free is kept OUT of the main 5-min cache
+// (recovery must not wait a full TTL), but an un-cached failure would make
+// every sequential call during an outage pay the full JWT+fetch attempt
+// (worst case ~10s on a hanging network). A short negative TTL caps that
+// amplification while still retrying promptly.
+const FALLBACK_NEGATIVE_TTL_MS = 25_000;
+let negativeCache = null;
 // ── Model tier ordering for ceiling enforcement ───────────────────
 const TIER_ORDER = ["2b", "4b", "9b", "27b"];
 /**
@@ -63,12 +70,12 @@ export function clampCeiling(requested, planCeiling) {
 async function fetchEntitlements() {
     if (!SYNALUX_CONFIGURED || !PRISM_SYNALUX_BASE_URL) {
         debugLog("[entitlements] no Synalux auth configured — free tier");
-        return FREE_ENTITLEMENTS;
+        return { ...FREE_ENTITLEMENTS, source: "unconfigured" };
     }
     const jwt = await getSynaluxJwt();
     if (!jwt) {
-        debugLog("[entitlements] JWT exchange failed — free tier fallback");
-        return FREE_ENTITLEMENTS;
+        debugLog("[entitlements] JWT exchange failed — free tier fallback (fallback_free)");
+        return { ...FREE_ENTITLEMENTS, source: "fallback_free" };
     }
     try {
         const url = `${PRISM_SYNALUX_BASE_URL}/api/v1/prism/entitlements`;
@@ -84,15 +91,18 @@ async function fetchEntitlements() {
                 debugLog("[entitlements] using last-known-good (safety fail-closed)");
                 return cache.entitlements;
             }
-            return FREE_ENTITLEMENTS;
+            return { ...FREE_ENTITLEMENTS, source: "fallback_free" };
         }
         const data = (await res.json());
         if (!data.plan || !data.model_ceiling) {
             debugLog("[entitlements] malformed response");
             if (cache)
                 return cache.entitlements;
-            return FREE_ENTITLEMENTS;
+            return { ...FREE_ENTITLEMENTS, source: "fallback_free" };
         }
+        // §5.5: provenance — this is REAL portal data (a portal "free" plan
+        // gets source:"portal", distinguishing it from an assumed fallback).
+        data.source = "portal";
         // Normalize legacy ceiling values to the current fleet.
         if (data.model_ceiling === "14b") {
             debugLog("[entitlements] grandfathered 14b ceiling → 9b");
@@ -114,20 +124,27 @@ async function fetchEntitlements() {
             debugLog("[entitlements] using last-known-good (safety fail-closed)");
             return cache.entitlements;
         }
-        debugLog("[entitlements] no cached entitlements — free tier fallback (cold start)");
-        return FREE_ENTITLEMENTS;
+        debugLog("[entitlements] no cached entitlements — free tier fallback (cold start, fallback_free)");
+        return { ...FREE_ENTITLEMENTS, source: "fallback_free" };
     }
 }
 // ── Public API ────────────────────────────────────────────────────
 /**
- * Get the current user's entitlements (cached for 1 hour).
- * Concurrent callers share a single in-flight fetch.
+ * Get the current user's entitlements (5-minute cache; resolved per call —
+ * plan v2 §5.5). Concurrent callers share a single in-flight fetch.
+ * fallback_free results are never cached, so degraded resolution retries
+ * on the next call.
  */
 export async function getEntitlements() {
     const now = Date.now();
     if (cache && cache.expiresAt > now) {
         return cache.entitlements;
     }
+    // §5.5: within the short negative window after a fallback_free
+    // resolution, return it without re-attempting the portal.
+    if (negativeCache && negativeCache.until > now) {
+        return negativeCache.entitlements;
+    }
     if (inFlight)
         return inFlight;
     inFlight = (async () => {
@@ -136,11 +153,20 @@ export async function getEntitlements() {
             // Only update cache if this is a REAL fetch (not a cached fallback).
             // fetchEntitlements returns cache.entitlements on error — detect by
             // checking if the returned object is the exact same reference.
-            const isFallback = cache && ent === cache.entitlements;
+            // §5.5: fallback_free results are also never cached — pinning an
+            // assumed-free degradation for the TTL would delay recovery; the
+            // next call retries the portal instead.
+            const isFallback = (cache && ent === cache.entitlements) || ent.source === "fallback_free";
             if (!isFallback) {
                 cache = { entitlements: ent, expiresAt: Date.now() + CACHE_TTL_MS };
             }
             // On fallback: DON'T refresh expiresAt — let it expire so we retry.
+            if (ent.source === "fallback_free") {
+                negativeCache = { entitlements: ent, until: Date.now() + FALLBACK_NEGATIVE_TTL_MS };
+            }
+            else {
+                negativeCache = null;
+            }
             return ent;
         }
         finally {
@@ -154,11 +180,13 @@ export async function getEntitlements() {
  */
 export function invalidateEntitlements() {
     cache = null;
+    negativeCache = null;
 }
 /** Test-only: reset all state. */
 export function _resetEntitlementsForTest() {
     cache = null;
     inFlight = null;
+    negativeCache = null;
 }
 /** Test-only: inject a cached entitlement. */
 export function _setCacheForTest(ent, ttlMs = CACHE_TTL_MS) {

package/dist/utils/inferenceMetrics.js

@@ -55,17 +55,35 @@ export function recordInference(result) {
         return;
     // Durable ledger row (fire-and-forget; in-memory counters below remain the
     // per-session view). safety_gate is excluded by the early return above.
+    // §5.2: prefer the structured gate_outcome; keep the legacy
+    // "gate_failed_served" string for degraded rows so existing ledger
+    // queries stay valid. Refused rows (escalation:"report") carry the
+    // refusal reason — the serve-mode throw paths ledger directly at the
+    // refusal site (makeReservedRefusal / backstop), so exactly one row
+    // is written either way.
+    const gateOutcomeStr = result.gate_outcome
+        ? (result.gate_outcome.status === "degraded" ? "gate_failed_served" : result.gate_outcome.status)
+        : (result.quality_gate_failed ? "gate_failed_served" : undefined);
     appendInferMetric({
         backend: result.backend,
         model: result.model_picked,
         used_cloud: result.used_cloud,
         mode: result.mode,
-        gate_outcome: result.quality_gate_failed ? "gate_failed_served" : undefined,
+        gate_outcome: gateOutcomeStr,
+        refusal_reason: result.gate_outcome?.status === "refused" ? result.gate_outcome.reason : undefined,
         prompt_tokens: result.prompt_tokens,
         completion_tokens: result.completion_tokens,
         latency_ms: result.latency_ms,
         ram_free_mb: result.ram_free_mb,
     });
+    // §5.2: refused results (escalation:"report") get a ledger row above but
+    // must NOT touch the session accumulators — no model ran and nothing was
+    // served, so counting them as local serves would inflate local% and
+    // cloudTokensSavedEst (the GATE 6 KPI: "improves only when local inference
+    // replaces a cloud call"). Serve-mode refusals throw and never reach here,
+    // so skipping keeps both modes' accounting identical.
+    if (result.backend === "refused")
+        return;
     const key = result.model_picked ?? result.backend;
     if (result.used_cloud) {
         cloudCalls++;

package/dist/utils/layer1.js

@@ -5,9 +5,14 @@
  * a prompt is OBVIOUS_RESERVED, OBVIOUS_NOT_RESERVED, or UNCERTAIN.
  *
  * Fail-closed contract:
- *   OBVIOUS_NOT_RESERVED → the ONLY verdict that permits local routing
+ *   OBVIOUS_NOT_RESERVED → permits local routing
  *   OBVIOUS_RESERVED     → escalate to cloud
  *   UNCERTAIN            → escalate to cloud (conservative)
+ *   UNCERTAIN_LENGTH     → §5.3: prompt too long to classify in full, but the
+ *                          full-text keyword floor is clean AND a head+tail
+ *                          excerpt classified clean — permits local routing
+ *                          with a distinct audit marker ("too long to classify"
+ *                          ≠ "semantically uncertain")
  *   ERROR                → escalate to cloud (never fail-open)
  *
  * The prompt below is VERBATIM from §E of prism-infer-boundaries/SKILL.md.
@@ -66,7 +71,7 @@ const LAYER1_RETRY_TIMEOUT_MS = 5_000;
 // Not sufficient alone (adversaries can paraphrase), but as an ERROR-path
 // floor they block the obvious cases that padding/injection attacks
 // would otherwise smuggle through.
-const RESERVED_KEYWORDS = /\b(restrain\w*|seclu(?:sion|d\w*)|physical\s*holds?|containment|self[- ]?harm\w*|suicid\w*|overdos\w*|dos(?:age|ing)\s*(?:mg|schedule)|crisis\s*de[- ]?escalation|meltdown\s*management|elopement\s*incident)\b/i;
+const RESERVED_KEYWORDS = /\b(restrain\w*|seclu(?:sion|d\w*)|physical\s*holds?|(?:prone|supine|basket|therapeutic|manual|two[- ]?person)\s+holds?|hold(?:ing)?\s+(?:the\s+)?(?:client|child|student|patient)\s+down|containment|self[- ]?harm\w*|suicid\w*|overdos\w*|dos(?:age|ing)\s*(?:mg|schedule)|crisis\s*de[- ]?escalation|meltdown\s*management|rage\s+episode|elopement\s*incident)\b/i;
 /**
  * Deterministic keyword check — the ERROR-path floor.
  * Returns OBVIOUS_RESERVED if reserved vocabulary is present,
@@ -77,21 +82,54 @@ export function keywordBackstop(prompt) {
     return RESERVED_KEYWORDS.test(prompt) ? "OBVIOUS_RESERVED" : "OBVIOUS_NOT_RESERVED";
 }
 // Over-length prompts are attacker-controlled — don't let length
-// select the ERROR branch. Classify as UNCERTAIN (conservative)
-// rather than feeding a huge prompt to a 4B classifier that will timeout.
+// select the ERROR branch. §5.3: instead of a blanket UNCERTAIN (which
+// routed every big benign prompt to cloud-or-refuse — v1 FATAL #3), run
+// the deterministic keyword floor over the FULL text, then classify a
+// bounded head+tail excerpt. A clean floor + clean excerpt yields the
+// distinct UNCERTAIN_LENGTH verdict so callers can tell "too long to
+// classify" from "semantically uncertain".
 const MAX_CLASSIFIER_PROMPT_LENGTH = 4_000;
+// Excerpt budget: head + middle + tail must stay under the classifier cap
+// with room for the LAYER1_PROMPT template. The sampled middle window
+// narrows the region an attacker can hide paraphrased reserved content in
+// (adversarial-review finding: keyword-free paraphrases in the unseen
+// middle are the residual gap — the window makes padding placement
+// harder; the full-text keyword floor remains the deterministic net).
+const EXCERPT_HEAD_CHARS = 2_000;
+const EXCERPT_MID_CHARS = 400;
+const EXCERPT_TAIL_CHARS = 1_400;
+/** Bounded head+middle+tail excerpt of an oversize prompt (§5.3). Exported for tests. */
+export function buildOversizeExcerpt(prompt) {
+    const midStart = Math.max(EXCERPT_HEAD_CHARS, Math.floor(prompt.length / 2) - EXCERPT_MID_CHARS / 2);
+    const middle = prompt.slice(midStart, midStart + EXCERPT_MID_CHARS);
+    return (prompt.slice(0, EXCERPT_HEAD_CHARS) +
+        "\n[…]\n" +
+        middle +
+        "\n[…]\n" +
+        prompt.slice(-EXCERPT_TAIL_CHARS));
+}
 /**
  * Run the Layer 1 classifier with retry on cold-model timeout.
  * Returns a verdict; never throws.
  *
  * Flow: classify → if ERROR, retry once with longer timeout →
  * if still ERROR, return ERROR (caller uses keywordBackstop).
+ *
+ * Oversize flow (§5.3): full-text keyword floor → excerpt classification →
+ * reserved/uncertain excerpt verdicts keep full reserved handling;
+ * a clean excerpt returns UNCERTAIN_LENGTH.
  */
 export async function callLayer1(userPrompt, ollamaUrl, model, fetchImpl = fetch) {
     if (!userPrompt || !userPrompt.trim())
         return "ERROR";
-    if (userPrompt.length > MAX_CLASSIFIER_PROMPT_LENGTH)
-        return "UNCERTAIN";
+    const oversize = userPrompt.length > MAX_CLASSIFIER_PROMPT_LENGTH;
+    if (oversize && keywordBackstop(userPrompt) === "OBVIOUS_RESERVED") {
+        // The regex floor has no length limit — reserved vocabulary anywhere
+        // in the full text (including the middle the excerpt can't see)
+        // short-circuits to reserved handling.
+        return "OBVIOUS_RESERVED";
+    }
+    const classifierInput = oversize ? buildOversizeExcerpt(userPrompt) : userPrompt;
     const classify = async (timeoutMs) => {
         let res;
         try {
@@ -101,7 +139,7 @@ export async function callLayer1(userPrompt, ollamaUrl, model, fetchImpl = fetch
                 body: JSON.stringify({
                     model,
                     messages: [
-                        { role: "user", content: LAYER1_PROMPT.replace("{prompt}", userPrompt) },
+                        { role: "user", content: LAYER1_PROMPT.replace("{prompt}", classifierInput) },
                     ],
                     stream: false,
                     think: false,
@@ -128,7 +166,16 @@ export async function callLayer1(userPrompt, ollamaUrl, model, fetchImpl = fetch
         return parseLayer1(text);
     };
     const first = await classify(LAYER1_TIMEOUT_MS);
-    if (first !== "ERROR")
-        return first;
-    return classify(LAYER1_RETRY_TIMEOUT_MS);
+    const verdict = first !== "ERROR" ? first : await classify(LAYER1_RETRY_TIMEOUT_MS);
+    if (!oversize)
+        return verdict;
+    // §5.3 oversize mapping:
+    //   excerpt OBVIOUS_RESERVED / UNCERTAIN → keep full reserved handling
+    //   excerpt OBVIOUS_NOT_RESERVED        → UNCERTAIN_LENGTH (distinct verdict)
+    //   excerpt ERROR                       → UNCERTAIN_LENGTH — the deterministic
+    //     keyword floor already cleared the FULL text above, which is the same
+    //     floor the normal-size ERROR path falls back to via the caller.
+    if (verdict === "OBVIOUS_RESERVED" || verdict === "UNCERTAIN")
+        return verdict;
+    return "UNCERTAIN_LENGTH";
 }

package/dist/utils/modelPicker.js

@@ -24,12 +24,21 @@ const GB = 1024 ** 3;
 /**
  * Tier table, ordered LARGEST → SMALLEST. Picker walks this and returns
  * the first row whose minFreeGb fits within freeBytes.
+ *
+ * ctxTokens (§5.4): aligned with the LIVE Modelfile `num_ctx` values
+ * (verified via `ollama show <tag> --modelfile` on 2026-07-20). The values
+ * are inverted from intuition — the 27b/9b Modelfiles bake num_ctx 4096
+ * while 4b/2b bake 32768. The tier walk skips tiers whose ctx cannot hold
+ * prompt + output (reason: ctx_insufficient) — Ollama otherwise silently
+ * truncates the prompt and answers from the fragment. If a Modelfile's
+ * num_ctx is ever raised, update the row here (a raise is a measured
+ * decision with KV-cache RAM costed — plan v2 §5.4).
  */
 export const MODEL_TIERS = [
-    { tag: 'prism-coder:27b', weightsGb: 16, minFreeGb: 20, ctxTokens: 32_768 },
-    { tag: 'prism-coder:9b', weightsGb: 5.8, minFreeGb: 8, ctxTokens: 32_768 },
+    { tag: 'prism-coder:27b', weightsGb: 16, minFreeGb: 20, ctxTokens: 4_096 },
+    { tag: 'prism-coder:9b', weightsGb: 5.8, minFreeGb: 8, ctxTokens: 4_096 },
     { tag: 'prism-coder:4b', weightsGb: 3.4, minFreeGb: 5, ctxTokens: 32_768 },
-    { tag: 'prism-coder:2b', weightsGb: 2.3, minFreeGb: 3, ctxTokens: 8_192 },
+    { tag: 'prism-coder:2b', weightsGb: 2.3, minFreeGb: 3, ctxTokens: 32_768 },
 ];
 /**
  * True when `installed` matches `tierTag` either as a bare tag

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.0.8",
+  "version": "20.1.0",
   "mcpName": "io.github.dcostenco/prism-coder",
   "description": "Prism Coder — Cognitive memory + tool-calling intelligence for AI agents. Mind Palace persistent memory (BFCL Gold Certified, 100% Tool-Call Accuracy, 114 Agent Skills, PHI Guard, Tier Enforcement, Prompt-Based Skill Routing, Zero-Search HDC/HRR retrieval, HRR Semantic Drift Detection across BCBA/Coding/AAC domains, HIPAA-hardened local-first storage, SLERP-optimized GRPO alignment) plus the prism-coder 1.7B–32B open-weights LLM fleet.",
   "module": "index.ts",