open-multi-agent-kit 0.99.0 → 1.2.0

package/dist/observation/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../src/observation/view.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAA6B,eAAe,EAAuB,cAAc,EAAE,MAAM,YAAY,CAAC;AAOlH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,6EAA6E;AAC7E,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AASD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,EAAE,CAyB7F;AAwDD;;;;GAIG;AACH,wBAAgB,SAAS,CACxB,WAAW,EAAE,cAAc,EAC3B,eAAe,GAAE,SAAS,MAAM,EAAO,GACrC,SAAS,eAAe,EAAE,CAkC5B;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACzB,KAAK,EAAE,SAAS,eAAe,EAAE,EACjC,YAAY,EAAE,MAAM,EACpB,eAAe,GAAE,SAAS,MAAM,EAAO,GACrC,eAAe,GAAG,IAAI,CAqBxB","sourcesContent":["/**\n * Deterministic observation views with a coverage gate — U1/U3.\n *\n * A view is a projection of a stored raw observation, never a rewrite of it.\n * `chooseView` refuses any candidate that drops a required fact atom: a cheap\n * representation is admissible only if it preserves the decision-relevant\n * facts the current obligations need. `coverageStatus` is `unknown` when the\n * input carries no required fact set — never silently \"covered\".\n */\n\nimport { ensure, integer, text } from \"../metacognition/validation.ts\";\nimport { viewDigestOf } from \"./identity.ts\";\nimport type { ObservationCoverageStatus, ObservationView, ObservationViewKind, RawObservation } from \"./types.ts\";\n\nconst CHARS_PER_TOKEN = 4;\n/** Per-atom-class occurrence cap. Four classes stay well under any global bound. */\nconst MAX_FACTS_PER_ID = 32;\nconst MAX_VIEW_TEXT = 32_768;\n\nexport function estimateViewTokens(text: string): number {\n\treturn Math.max(1, Math.ceil(text.length / CHARS_PER_TOKEN));\n}\n\n/** A host-verifiable fact atom extracted from raw bytes, e.g. exitCode=1. */\nexport interface FactAtom {\n\treadonly id: string;\n\t/** The verbatim text that must appear in a view for the atom to count as covered. */\n\treadonly evidence: string;\n\treadonly byteOffset: number;\n\treadonly byteLength: number;\n}\n\nconst FACT_PATTERNS: readonly { readonly id: string; readonly re: RegExp }[] = [\n\t{ id: \"exit-code\", re: /exit code[:\\s]+(-?\\d+)|exitCode\\s*[=:]\\s*(-?\\d+)/i },\n\t{ id: \"test-failure\", re: /FAIL[:\\s]+([A-Za-z0-9_.\\-/]+)|✗\\s*([A-Za-z0-9_.\\-/]+)/ },\n\t{ id: \"permission-denied\", re: /permission[ _-]?denied|EACCES/i },\n\t{ id: \"error-marker\", re: /(?:error|errno|exception|traceback)[:\\s]/i },\n];\n\n/**\n * Extract host-verifiable fact atoms from raw bytes. `requiredFactIds` limits\n * extraction to the caller's obligation set; when omitted, all recognized\n * atoms are returned so a view can advertise what it preserves.\n */\nexport function extractFacts(raw: Uint8Array, requiredFactIds?: readonly string[]): FactAtom[] {\n\tconst decoded = new TextDecoder(\"utf-8\", { fatal: false }).decode(raw);\n\tconst encoder = new TextEncoder();\n\tconst wanted = requiredFactIds === undefined ? undefined : new Set(requiredFactIds);\n\tconst facts: FactAtom[] = [];\n\tfor (const { id, re } of FACT_PATTERNS) {\n\t\tif (wanted !== undefined && !wanted.has(id)) continue;\n\t\t// Per-id cap, not a shared running total: a log that repeats one atom\n\t\t// thousands of times must not starve a later pattern out of extraction\n\t\t// entirely, or a required atom silently disappears from every view.\n\t\tlet perId = 0;\n\t\tfor (const match of decoded.matchAll(new RegExp(re.source, re.flags.includes(\"g\") ? re.flags : `${re.flags}g`))) {\n\t\t\tif (perId >= MAX_FACTS_PER_ID) break;\n\t\t\tconst evidence = match[0];\n\t\t\tconst byteOffset = encoder.encode(decoded.slice(0, match.index ?? 0)).length;\n\t\t\tfacts.push({\n\t\t\t\tid,\n\t\t\t\tevidence,\n\t\t\t\tbyteOffset,\n\t\t\t\tbyteLength: encoder.encode(evidence).length,\n\t\t\t});\n\t\t\tperId += 1;\n\t\t}\n\t}\n\treturn facts;\n}\n\n/**\n * Collapse repeated identical atoms into one line that keeps the occurrence\n * count. Without this the evidence view of a log that repeats one failure is\n * larger than the raw text it was supposed to shrink, and the selector\n * correctly but uselessly falls back to full text.\n */\nfunction dedupeFacts(facts: readonly FactAtom[]): readonly { readonly fact: FactAtom; readonly count: number }[] {\n\tconst byKey = new Map<string, { fact: FactAtom; count: number }>();\n\tfor (const fact of facts) {\n\t\tconst key = `${fact.id}\\u0000${fact.evidence}`;\n\t\tconst existing = byKey.get(key);\n\t\tif (existing === undefined) byKey.set(key, { fact, count: 1 });\n\t\telse existing.count += 1;\n\t}\n\treturn [...byKey.values()];\n}\n\nfunction viewText(raw: Uint8Array, facts: readonly FactAtom[], kind: ObservationViewKind): string {\n\tconst decoded = new TextDecoder(\"utf-8\", { fatal: false }).decode(raw);\n\tswitch (kind) {\n\t\tcase \"full\":\n\t\t\treturn decoded;\n\t\tcase \"excerpt\": {\n\t\t\tif (decoded.length <= MAX_VIEW_TEXT) return decoded;\n\t\t\tconst head = decoded.slice(0, Math.floor(MAX_VIEW_TEXT / 2));\n\t\t\tconst tail = decoded.slice(-Math.floor(MAX_VIEW_TEXT / 2));\n\t\t\treturn `${head}\\n…[omitted ${decoded.length - MAX_VIEW_TEXT} chars]…\\n${tail}`;\n\t\t}\n\t\tcase \"evidence\":\n\t\t\treturn facts.length === 0\n\t\t\t\t? \"\"\n\t\t\t\t: dedupeFacts(facts)\n\t\t\t\t\t\t.map(({ fact, count }) =>\n\t\t\t\t\t\t\tcount === 1\n\t\t\t\t\t\t\t\t? `${fact.id} @${fact.byteOffset}: ${fact.evidence}`\n\t\t\t\t\t\t\t\t: `${fact.id} @${fact.byteOffset} \\u00d7${count}: ${fact.evidence}`,\n\t\t\t\t\t\t)\n\t\t\t\t\t\t.join(\"\\n\")\n\t\t\t\t\t\t.slice(0, MAX_VIEW_TEXT);\n\t\tcase \"pointer\":\n\t\t\treturn `[observation ${raw.length} bytes; digest-bound; read via handle]`;\n\t}\n}\n\nfunction coverageFor(\n\tcovered: readonly string[],\n\trequired: readonly string[],\n): { status: ObservationCoverageStatus; missing: readonly string[] } {\n\tif (required.length === 0) return { status: \"unknown\", missing: [] };\n\tconst coveredSet = new Set(covered);\n\tconst missing = required.filter((id) => !coveredSet.has(id));\n\treturn { status: missing.length === 0 ? \"complete\" : \"partial\", missing };\n}\n\n/**\n * Build the candidate views for one observation. Every view records which\n * fact atoms it preserves and which required atoms it would drop, so the\n * selector can gate on coverage rather than token density alone.\n */\nexport function makeViews(\n\tobservation: RawObservation,\n\trequiredFactIds: readonly string[] = [],\n): readonly ObservationView[] {\n\ttext(observation.observationId, \"observationId\", 128);\n\tfor (const id of requiredFactIds) text(id, \"requiredFactId\", 256);\n\tconst facts = extractFacts(observation.bytes);\n\tconst coveredByKind: Record<ObservationViewKind, readonly string[]> = {\n\t\tfull: facts.map((f) => f.id),\n\t\texcerpt: facts.map((f) => f.id), // excerpt keeps head+tail; see note\n\t\tevidence: facts.map((f) => f.id),\n\t\tpointer: [],\n\t};\n\tconst kinds: readonly ObservationViewKind[] = [\"full\", \"excerpt\", \"evidence\", \"pointer\"];\n\treturn kinds.map((kind) => {\n\t\tconst body = viewText(observation.bytes, facts, kind);\n\t\tconst covered = coveredByKind[kind].filter(\n\t\t\t(id) => body.includes(id) || kind !== \"evidence\" || facts.some((f) => f.id === id),\n\t\t);\n\t\tconst { status, missing } = coverageFor(covered, requiredFactIds);\n\t\treturn Object.freeze({\n\t\t\tviewKind: kind,\n\t\t\tobservationId: observation.observationId,\n\t\t\tparentDigest: observation.rawDigest,\n\t\t\ttransformationDigest: viewDigestOf({\n\t\t\t\tobservationId: observation.observationId,\n\t\t\t\tviewKind: kind,\n\t\t\t\tparams: `req:${[...requiredFactIds].sort().join(\",\")}`,\n\t\t\t}),\n\t\t\ttext: body,\n\t\t\testimatedTokens: estimateViewTokens(body),\n\t\t\tcoveredFactIds: covered,\n\t\t\tmissingRequiredFactIds: missing,\n\t\t\tcoverageStatus: status,\n\t\t\ttaskVerdict: \"not-assessed\" as const,\n\t\t});\n\t});\n}\n\n/**\n * Coverage-gated deterministic selection: the smallest view that preserves\n * every required fact within budget. Returns null (infeasible) rather than\n * silently dropping a required atom — the caller must widen the budget or keep\n * the raw observation.\n */\nexport function chooseView(\n\tviews: readonly ObservationView[],\n\tbudgetTokens: number,\n\trequiredFactIds: readonly string[] = [],\n): ObservationView | null {\n\tinteger(budgetTokens, \"budgetTokens\");\n\tensure(views.length > 0, \"views must be nonempty\");\n\tfor (const id of requiredFactIds) text(id, \"requiredFactId\", 256);\n\tconst admissible = views.filter(\n\t\t(v) => v.estimatedTokens <= budgetTokens && requiredFactIds.every((id) => v.coveredFactIds.includes(id)),\n\t);\n\tif (admissible.length === 0) return null;\n\t// Smallest tokens wins; break ties toward the higher-fidelity kind.\n\tconst rank: Record<ObservationViewKind, number> = { full: 0, excerpt: 1, evidence: 2, pointer: 3 };\n\tlet best: ObservationView | undefined;\n\tfor (const view of admissible) {\n\t\tif (\n\t\t\tbest === undefined ||\n\t\t\tview.estimatedTokens < best.estimatedTokens ||\n\t\t\t(view.estimatedTokens === best.estimatedTokens && rank[view.viewKind] < rank[best.viewKind])\n\t\t) {\n\t\t\tbest = view;\n\t\t}\n\t}\n\treturn best ?? null;\n}\n"]}

package/dist/observation/view.js

@@ -0,0 +1,173 @@
+/**
+ * Deterministic observation views with a coverage gate — U1/U3.
+ *
+ * A view is a projection of a stored raw observation, never a rewrite of it.
+ * `chooseView` refuses any candidate that drops a required fact atom: a cheap
+ * representation is admissible only if it preserves the decision-relevant
+ * facts the current obligations need. `coverageStatus` is `unknown` when the
+ * input carries no required fact set — never silently "covered".
+ */
+import { ensure, integer, text } from "../metacognition/validation.js";
+import { viewDigestOf } from "./identity.js";
+const CHARS_PER_TOKEN = 4;
+/** Per-atom-class occurrence cap. Four classes stay well under any global bound. */
+const MAX_FACTS_PER_ID = 32;
+const MAX_VIEW_TEXT = 32_768;
+export function estimateViewTokens(text) {
+    return Math.max(1, Math.ceil(text.length / CHARS_PER_TOKEN));
+}
+const FACT_PATTERNS = [
+    { id: "exit-code", re: /exit code[:\s]+(-?\d+)|exitCode\s*[=:]\s*(-?\d+)/i },
+    { id: "test-failure", re: /FAIL[:\s]+([A-Za-z0-9_.\-/]+)|✗\s*([A-Za-z0-9_.\-/]+)/ },
+    { id: "permission-denied", re: /permission[ _-]?denied|EACCES/i },
+    { id: "error-marker", re: /(?:error|errno|exception|traceback)[:\s]/i },
+];
+/**
+ * Extract host-verifiable fact atoms from raw bytes. `requiredFactIds` limits
+ * extraction to the caller's obligation set; when omitted, all recognized
+ * atoms are returned so a view can advertise what it preserves.
+ */
+export function extractFacts(raw, requiredFactIds) {
+    const decoded = new TextDecoder("utf-8", { fatal: false }).decode(raw);
+    const encoder = new TextEncoder();
+    const wanted = requiredFactIds === undefined ? undefined : new Set(requiredFactIds);
+    const facts = [];
+    for (const { id, re } of FACT_PATTERNS) {
+        if (wanted !== undefined && !wanted.has(id))
+            continue;
+        // Per-id cap, not a shared running total: a log that repeats one atom
+        // thousands of times must not starve a later pattern out of extraction
+        // entirely, or a required atom silently disappears from every view.
+        let perId = 0;
+        for (const match of decoded.matchAll(new RegExp(re.source, re.flags.includes("g") ? re.flags : `${re.flags}g`))) {
+            if (perId >= MAX_FACTS_PER_ID)
+                break;
+            const evidence = match[0];
+            const byteOffset = encoder.encode(decoded.slice(0, match.index ?? 0)).length;
+            facts.push({
+                id,
+                evidence,
+                byteOffset,
+                byteLength: encoder.encode(evidence).length,
+            });
+            perId += 1;
+        }
+    }
+    return facts;
+}
+/**
+ * Collapse repeated identical atoms into one line that keeps the occurrence
+ * count. Without this the evidence view of a log that repeats one failure is
+ * larger than the raw text it was supposed to shrink, and the selector
+ * correctly but uselessly falls back to full text.
+ */
+function dedupeFacts(facts) {
+    const byKey = new Map();
+    for (const fact of facts) {
+        const key = `${fact.id}\u0000${fact.evidence}`;
+        const existing = byKey.get(key);
+        if (existing === undefined)
+            byKey.set(key, { fact, count: 1 });
+        else
+            existing.count += 1;
+    }
+    return [...byKey.values()];
+}
+function viewText(raw, facts, kind) {
+    const decoded = new TextDecoder("utf-8", { fatal: false }).decode(raw);
+    switch (kind) {
+        case "full":
+            return decoded;
+        case "excerpt": {
+            if (decoded.length <= MAX_VIEW_TEXT)
+                return decoded;
+            const head = decoded.slice(0, Math.floor(MAX_VIEW_TEXT / 2));
+            const tail = decoded.slice(-Math.floor(MAX_VIEW_TEXT / 2));
+            return `${head}\n…[omitted ${decoded.length - MAX_VIEW_TEXT} chars]…\n${tail}`;
+        }
+        case "evidence":
+            return facts.length === 0
+                ? ""
+                : dedupeFacts(facts)
+                    .map(({ fact, count }) => count === 1
+                    ? `${fact.id} @${fact.byteOffset}: ${fact.evidence}`
+                    : `${fact.id} @${fact.byteOffset} \u00d7${count}: ${fact.evidence}`)
+                    .join("\n")
+                    .slice(0, MAX_VIEW_TEXT);
+        case "pointer":
+            return `[observation ${raw.length} bytes; digest-bound; read via handle]`;
+    }
+}
+function coverageFor(covered, required) {
+    if (required.length === 0)
+        return { status: "unknown", missing: [] };
+    const coveredSet = new Set(covered);
+    const missing = required.filter((id) => !coveredSet.has(id));
+    return { status: missing.length === 0 ? "complete" : "partial", missing };
+}
+/**
+ * Build the candidate views for one observation. Every view records which
+ * fact atoms it preserves and which required atoms it would drop, so the
+ * selector can gate on coverage rather than token density alone.
+ */
+export function makeViews(observation, requiredFactIds = []) {
+    text(observation.observationId, "observationId", 128);
+    for (const id of requiredFactIds)
+        text(id, "requiredFactId", 256);
+    const facts = extractFacts(observation.bytes);
+    const coveredByKind = {
+        full: facts.map((f) => f.id),
+        excerpt: facts.map((f) => f.id), // excerpt keeps head+tail; see note
+        evidence: facts.map((f) => f.id),
+        pointer: [],
+    };
+    const kinds = ["full", "excerpt", "evidence", "pointer"];
+    return kinds.map((kind) => {
+        const body = viewText(observation.bytes, facts, kind);
+        const covered = coveredByKind[kind].filter((id) => body.includes(id) || kind !== "evidence" || facts.some((f) => f.id === id));
+        const { status, missing } = coverageFor(covered, requiredFactIds);
+        return Object.freeze({
+            viewKind: kind,
+            observationId: observation.observationId,
+            parentDigest: observation.rawDigest,
+            transformationDigest: viewDigestOf({
+                observationId: observation.observationId,
+                viewKind: kind,
+                params: `req:${[...requiredFactIds].sort().join(",")}`,
+            }),
+            text: body,
+            estimatedTokens: estimateViewTokens(body),
+            coveredFactIds: covered,
+            missingRequiredFactIds: missing,
+            coverageStatus: status,
+            taskVerdict: "not-assessed",
+        });
+    });
+}
+/**
+ * Coverage-gated deterministic selection: the smallest view that preserves
+ * every required fact within budget. Returns null (infeasible) rather than
+ * silently dropping a required atom — the caller must widen the budget or keep
+ * the raw observation.
+ */
+export function chooseView(views, budgetTokens, requiredFactIds = []) {
+    integer(budgetTokens, "budgetTokens");
+    ensure(views.length > 0, "views must be nonempty");
+    for (const id of requiredFactIds)
+        text(id, "requiredFactId", 256);
+    const admissible = views.filter((v) => v.estimatedTokens <= budgetTokens && requiredFactIds.every((id) => v.coveredFactIds.includes(id)));
+    if (admissible.length === 0)
+        return null;
+    // Smallest tokens wins; break ties toward the higher-fidelity kind.
+    const rank = { full: 0, excerpt: 1, evidence: 2, pointer: 3 };
+    let best;
+    for (const view of admissible) {
+        if (best === undefined ||
+            view.estimatedTokens < best.estimatedTokens ||
+            (view.estimatedTokens === best.estimatedTokens && rank[view.viewKind] < rank[best.viewKind])) {
+            best = view;
+        }
+    }
+    return best ?? null;
+}
+//# sourceMappingURL=view.js.map

package/dist/observation/view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../../src/observation/view.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Deterministic observation views with a coverage gate — U1/U3.\n *\n * A view is a projection of a stored raw observation, never a rewrite of it.\n * `chooseView` refuses any candidate that drops a required fact atom: a cheap\n * representation is admissible only if it preserves the decision-relevant\n * facts the current obligations need. `coverageStatus` is `unknown` when the\n * input carries no required fact set — never silently \"covered\".\n */\n\nimport { ensure, integer, text } from \"../metacognition/validation.ts\";\nimport { viewDigestOf } from \"./identity.ts\";\nimport type { ObservationCoverageStatus, ObservationView, ObservationViewKind, RawObservation } from \"./types.ts\";\n\nconst CHARS_PER_TOKEN = 4;\n/** Per-atom-class occurrence cap. Four classes stay well under any global bound. */\nconst MAX_FACTS_PER_ID = 32;\nconst MAX_VIEW_TEXT = 32_768;\n\nexport function estimateViewTokens(text: string): number {\n\treturn Math.max(1, Math.ceil(text.length / CHARS_PER_TOKEN));\n}\n\n/** A host-verifiable fact atom extracted from raw bytes, e.g. exitCode=1. */\nexport interface FactAtom {\n\treadonly id: string;\n\t/** The verbatim text that must appear in a view for the atom to count as covered. */\n\treadonly evidence: string;\n\treadonly byteOffset: number;\n\treadonly byteLength: number;\n}\n\nconst FACT_PATTERNS: readonly { readonly id: string; readonly re: RegExp }[] = [\n\t{ id: \"exit-code\", re: /exit code[:\\s]+(-?\\d+)|exitCode\\s*[=:]\\s*(-?\\d+)/i },\n\t{ id: \"test-failure\", re: /FAIL[:\\s]+([A-Za-z0-9_.\\-/]+)|✗\\s*([A-Za-z0-9_.\\-/]+)/ },\n\t{ id: \"permission-denied\", re: /permission[ _-]?denied|EACCES/i },\n\t{ id: \"error-marker\", re: /(?:error|errno|exception|traceback)[:\\s]/i },\n];\n\n/**\n * Extract host-verifiable fact atoms from raw bytes. `requiredFactIds` limits\n * extraction to the caller's obligation set; when omitted, all recognized\n * atoms are returned so a view can advertise what it preserves.\n */\nexport function extractFacts(raw: Uint8Array, requiredFactIds?: readonly string[]): FactAtom[] {\n\tconst decoded = new TextDecoder(\"utf-8\", { fatal: false }).decode(raw);\n\tconst encoder = new TextEncoder();\n\tconst wanted = requiredFactIds === undefined ? undefined : new Set(requiredFactIds);\n\tconst facts: FactAtom[] = [];\n\tfor (const { id, re } of FACT_PATTERNS) {\n\t\tif (wanted !== undefined && !wanted.has(id)) continue;\n\t\t// Per-id cap, not a shared running total: a log that repeats one atom\n\t\t// thousands of times must not starve a later pattern out of extraction\n\t\t// entirely, or a required atom silently disappears from every view.\n\t\tlet perId = 0;\n\t\tfor (const match of decoded.matchAll(new RegExp(re.source, re.flags.includes(\"g\") ? re.flags : `${re.flags}g`))) {\n\t\t\tif (perId >= MAX_FACTS_PER_ID) break;\n\t\t\tconst evidence = match[0];\n\t\t\tconst byteOffset = encoder.encode(decoded.slice(0, match.index ?? 0)).length;\n\t\t\tfacts.push({\n\t\t\t\tid,\n\t\t\t\tevidence,\n\t\t\t\tbyteOffset,\n\t\t\t\tbyteLength: encoder.encode(evidence).length,\n\t\t\t});\n\t\t\tperId += 1;\n\t\t}\n\t}\n\treturn facts;\n}\n\n/**\n * Collapse repeated identical atoms into one line that keeps the occurrence\n * count. Without this the evidence view of a log that repeats one failure is\n * larger than the raw text it was supposed to shrink, and the selector\n * correctly but uselessly falls back to full text.\n */\nfunction dedupeFacts(facts: readonly FactAtom[]): readonly { readonly fact: FactAtom; readonly count: number }[] {\n\tconst byKey = new Map<string, { fact: FactAtom; count: number }>();\n\tfor (const fact of facts) {\n\t\tconst key = `${fact.id}\\u0000${fact.evidence}`;\n\t\tconst existing = byKey.get(key);\n\t\tif (existing === undefined) byKey.set(key, { fact, count: 1 });\n\t\telse existing.count += 1;\n\t}\n\treturn [...byKey.values()];\n}\n\nfunction viewText(raw: Uint8Array, facts: readonly FactAtom[], kind: ObservationViewKind): string {\n\tconst decoded = new TextDecoder(\"utf-8\", { fatal: false }).decode(raw);\n\tswitch (kind) {\n\t\tcase \"full\":\n\t\t\treturn decoded;\n\t\tcase \"excerpt\": {\n\t\t\tif (decoded.length <= MAX_VIEW_TEXT) return decoded;\n\t\t\tconst head = decoded.slice(0, Math.floor(MAX_VIEW_TEXT / 2));\n\t\t\tconst tail = decoded.slice(-Math.floor(MAX_VIEW_TEXT / 2));\n\t\t\treturn `${head}\\n…[omitted ${decoded.length - MAX_VIEW_TEXT} chars]…\\n${tail}`;\n\t\t}\n\t\tcase \"evidence\":\n\t\t\treturn facts.length === 0\n\t\t\t\t? \"\"\n\t\t\t\t: dedupeFacts(facts)\n\t\t\t\t\t\t.map(({ fact, count }) =>\n\t\t\t\t\t\t\tcount === 1\n\t\t\t\t\t\t\t\t? `${fact.id} @${fact.byteOffset}: ${fact.evidence}`\n\t\t\t\t\t\t\t\t: `${fact.id} @${fact.byteOffset} \\u00d7${count}: ${fact.evidence}`,\n\t\t\t\t\t\t)\n\t\t\t\t\t\t.join(\"\\n\")\n\t\t\t\t\t\t.slice(0, MAX_VIEW_TEXT);\n\t\tcase \"pointer\":\n\t\t\treturn `[observation ${raw.length} bytes; digest-bound; read via handle]`;\n\t}\n}\n\nfunction coverageFor(\n\tcovered: readonly string[],\n\trequired: readonly string[],\n): { status: ObservationCoverageStatus; missing: readonly string[] } {\n\tif (required.length === 0) return { status: \"unknown\", missing: [] };\n\tconst coveredSet = new Set(covered);\n\tconst missing = required.filter((id) => !coveredSet.has(id));\n\treturn { status: missing.length === 0 ? \"complete\" : \"partial\", missing };\n}\n\n/**\n * Build the candidate views for one observation. Every view records which\n * fact atoms it preserves and which required atoms it would drop, so the\n * selector can gate on coverage rather than token density alone.\n */\nexport function makeViews(\n\tobservation: RawObservation,\n\trequiredFactIds: readonly string[] = [],\n): readonly ObservationView[] {\n\ttext(observation.observationId, \"observationId\", 128);\n\tfor (const id of requiredFactIds) text(id, \"requiredFactId\", 256);\n\tconst facts = extractFacts(observation.bytes);\n\tconst coveredByKind: Record<ObservationViewKind, readonly string[]> = {\n\t\tfull: facts.map((f) => f.id),\n\t\texcerpt: facts.map((f) => f.id), // excerpt keeps head+tail; see note\n\t\tevidence: facts.map((f) => f.id),\n\t\tpointer: [],\n\t};\n\tconst kinds: readonly ObservationViewKind[] = [\"full\", \"excerpt\", \"evidence\", \"pointer\"];\n\treturn kinds.map((kind) => {\n\t\tconst body = viewText(observation.bytes, facts, kind);\n\t\tconst covered = coveredByKind[kind].filter(\n\t\t\t(id) => body.includes(id) || kind !== \"evidence\" || facts.some((f) => f.id === id),\n\t\t);\n\t\tconst { status, missing } = coverageFor(covered, requiredFactIds);\n\t\treturn Object.freeze({\n\t\t\tviewKind: kind,\n\t\t\tobservationId: observation.observationId,\n\t\t\tparentDigest: observation.rawDigest,\n\t\t\ttransformationDigest: viewDigestOf({\n\t\t\t\tobservationId: observation.observationId,\n\t\t\t\tviewKind: kind,\n\t\t\t\tparams: `req:${[...requiredFactIds].sort().join(\",\")}`,\n\t\t\t}),\n\t\t\ttext: body,\n\t\t\testimatedTokens: estimateViewTokens(body),\n\t\t\tcoveredFactIds: covered,\n\t\t\tmissingRequiredFactIds: missing,\n\t\t\tcoverageStatus: status,\n\t\t\ttaskVerdict: \"not-assessed\" as const,\n\t\t});\n\t});\n}\n\n/**\n * Coverage-gated deterministic selection: the smallest view that preserves\n * every required fact within budget. Returns null (infeasible) rather than\n * silently dropping a required atom — the caller must widen the budget or keep\n * the raw observation.\n */\nexport function chooseView(\n\tviews: readonly ObservationView[],\n\tbudgetTokens: number,\n\trequiredFactIds: readonly string[] = [],\n): ObservationView | null {\n\tinteger(budgetTokens, \"budgetTokens\");\n\tensure(views.length > 0, \"views must be nonempty\");\n\tfor (const id of requiredFactIds) text(id, \"requiredFactId\", 256);\n\tconst admissible = views.filter(\n\t\t(v) => v.estimatedTokens <= budgetTokens && requiredFactIds.every((id) => v.coveredFactIds.includes(id)),\n\t);\n\tif (admissible.length === 0) return null;\n\t// Smallest tokens wins; break ties toward the higher-fidelity kind.\n\tconst rank: Record<ObservationViewKind, number> = { full: 0, excerpt: 1, evidence: 2, pointer: 3 };\n\tlet best: ObservationView | undefined;\n\tfor (const view of admissible) {\n\t\tif (\n\t\t\tbest === undefined ||\n\t\t\tview.estimatedTokens < best.estimatedTokens ||\n\t\t\t(view.estimatedTokens === best.estimatedTokens && rank[view.viewKind] < rank[best.viewKind])\n\t\t) {\n\t\t\tbest = view;\n\t\t}\n\t}\n\treturn best ?? null;\n}\n"]}

package/docs/audit-revalidation-2026-09-17.md

@@ -0,0 +1,77 @@
+# Audit revalidation — 2026-09-17
+
+Baseline: `1e58611d0c28775c8a066b6e913ea6710ccea396`, with unrelated local
+provider/model changes present. This is a scoped local revalidation, not a release
+approval, full security audit, or competitor benchmark.
+
+## Inputs and scope
+
+The local September 14 reproduction ZIP targets
+`69e0637d8fddd26eb40a7ec3f8ebfb65b500de5b`. All 25 entries listed in its
+SHA256SUMS matched. Its recorded six expected failures describe that historical
+snapshot, not the current checkout. The archived runner was not executed or
+substituted for current repository tests.
+
+The September 15 strategy report combines historical findings with proposed
+resource-aware scheduling, recovery, and comparative evaluation. These proposals
+are not measured product benefits. The September 16 GitHub audit targets
+`739bc6f3b6fe1c89bfe058aad7ec17ad252fb10e`; its missing DAG contract is no longer
+present in this baseline. The documents were used to select the checks below;
+not every proposed acceptance criterion was executed.
+
+## Executed regression groups
+
+Commands use `node ../../node_modules/vitest/dist/cli.js --run` from the named
+workspace. No external provider requests were needed.
+
+| Workspace | Test files | Result |
+| --- | --- | --- |
+| agent | `test/tool-dag-*.test.ts` | 83 passed, including 10,000 seeded bounded schedules |
+| coding-agent | `test/mcp/{protocol,protocol-required,manager-lifecycle,manager-health,client,tools}.test.ts` | 61 passed; client tests include a local stdio fixture |
+| protocol | `test/{protocol,evaluation-candidate-binding,validation,run-dag-contract,run-dag-properties}.test.ts` | 44 passed |
+| coding-agent | `test/{context-budget-v2-validation-cache,context-budget-cache,context-budget-cache-policy,context-budget-v2-tier-floor,context-budget-v2-eligibility,context-budget-v2-nonfinite-tokens,context-budget-governor-v2}.test.ts` | 46 passed after the fix below |
+
+These are 234 distinct passing test cases, not 234 independent production tasks.
+An initial command included nonexistent `test/mcp/manager.test.ts`; Vitest ran
+other matching files successfully. Manager coverage above comes from the actual
+`manager-lifecycle`, `manager-health`, and `client` files, not that missing path.
+
+## Fixed: input diagnostics leaked across plan-cache reuse
+
+`planPromptContextBudgetV2()` originally decided cache eligibility before
+`validateBudgetItems()`. Duplicate IDs are dropped and invalid token estimates are
+recomputed. Their sanitized items can produce exactly the same plan key as valid
+input, but their input diagnostics are different.
+
+Three regressions failed before the fix:
+
+1. A cached valid plan hid a duplicate-ID diagnostic on a later call.
+2. A plan produced from duplicate IDs carried its diagnostic into a later valid call.
+3. A cached plan hid the diagnostic for a recomputed non-finite token estimate.
+
+Cache eligibility is now decided after input validation. Calls with input or
+budget diagnostics neither read nor write the plan cache. Representation-cache
+validation and normal valid-input plan reuse remain unchanged. The regression
+uses a required item to isolate plan reuse from the existing
+`cache_dependency_unsafe` rejection for plans containing representation-cache hits.
+
+Changed implementation: `src/core/context-budget-v2-planner.ts`.
+Regression: `test/context-budget-v2-validation-cache.test.ts` (3 passed).
+This preserves diagnostics; it does not redesign duplicate-item handling or tier
+allocation policy.
+
+## Remaining boundaries
+
+- Full `npm run check` has been blocked by unrelated local module-size growth in
+  `agent-session.ts` and `model-registry.ts`; those files and the ratchet baseline
+  are not changed by this fix. A passing focused compiler/test run does not close
+  the full repository gate.
+- General observation evaluation still has existential semantics. Passing
+  candidate-binding tests does not establish latest-result or complete-coverage
+  semantics, or independently authenticate a verifier.
+- ECRAF remains an internal planner. Resource normalization, fairness, live
+  admission integration, and equal-budget performance comparisons were not added.
+- This pass does not validate the complete timeout/ownership fault matrix,
+  verified-run crash recovery, all MCP authorization boundaries, remote CI,
+  branch protection, published artifacts, or router calibration.
+- No release, commit, push, paid benchmark, or new runtime default is implied.

package/docs/devin-harness.md

@@ -1,6 +1,6 @@
 # Devin SWE-2 harness
 
-This page is the canonical operator guide for the built-in `devin` provider and its only logical model, `swe-2`. Use `/login devin` for the Devin CLI subscription PKCE flow or `DEVIN_API_KEY` for an already-owned CLI session token. A user-local `~/.omk/agent/devin.md` may add operator notes, but it is not the portable product contract.
+This page is the canonical operator guide for the built-in `devin` provider, centered on the logical `swe-2` model. Use `/login devin` for the Devin CLI subscription PKCE flow or `DEVIN_API_KEY` for an already-owned CLI session token. A user-local `~/.omk/agent/devin.md` may add operator notes, but it is not the portable product contract.
 
 Authentication, transport, and verification limits are owned by [Providers](providers.md#devin-cli); this page covers how OMK drives SWE-2 as a harness.
 
@@ -44,12 +44,12 @@ Guidance from the [SWE-2 announcement](https://cognition.com/blog/swe-2): `mediu
 
 ## Context budget: 1,000,000 tokens
 
-`devin/swe-2` ships with `contextWindow: 1000000` and `maxTokens: 16384`. These are local budgets that drive OMK's context budgeting and compaction, **not published SWE-2 limits**; Cognition has not published a context window for SWE-2. The budget also selects the catalog lane:
+`devin/swe-2` ships with `contextWindow: 1000000` and `maxTokens: 16384`. These are local budgets that drive OMK's context budgeting and compaction, **not published SWE-2 limits**; Cognition has not published a context window for SWE-2. Chat completion settings follow the captured native Devin CLI 3000.6.2 defaults (`maxNewlines` 400, empty stop list). `topP=0.95` is protobuf field 8; field 6 is `firstTemperature` and is omitted. This removes the old 200-newline cap and synthetic stops, but does not prove that every interrupted reply had that cause. The budget also selects the catalog lane:
 
 1. Before each turn OMK reads `GetCliModelConfigs`. SWE-2 family entries may carry a `1M Context` axis (order `1`) beside the effort axis. A local budget of 1,000,000 or more asks for that 1M-context lane; below it, the standard lane is used and 1M entries are ignored.
 2. A catalog with no 1M-context lane keeps the standard lane for the selected effort.
 3. If the chosen lane declares a context window smaller than the local budget, the request fails with `... declares a N-token context window; lower the models.json contextWindow before retrying`. OMK never shrinks the budget silently, never invents a wire UID, and never downgrades to another effort.
-4. Fast-lane (`Fast Mode`) entries are always excluded. Output is capped against the authenticated catalog's declared maximum.
+4. Fast-lane (`Fast Mode`) entries are excluded from effort routing and are reachable only through their own UID models (ids ending in `-fast` or `-priority`). Output is capped against the authenticated catalog's declared maximum.
 
 To lower the budget (for example if your account only serves the standard lane at 262,144 tokens), override the built-in model in `~/.omk/agent/models.json`:
 
@@ -87,7 +87,7 @@ General prompt-based domain routing is separate and opt-in through `OMK_DOMAIN_R
 
 ## Model selection
 
-The `devin` catalog contains only the logical `swe-2` model; the server's SWE-2 family metadata supplies each effort's wire UID at request time. Use `/model` or `omk --list-models devin` for the current list. Image input is unsupported; provide text.
+The `devin` catalog leads with the logical `swe-2` model; the server's SWE-2 family metadata supplies each effort's wire UID at request time. Every other lane the account catalog advertises is its own logical model whose id is the wire UID — for example `devin/claude-opus-5-high`, `devin/gpt-5-6-sol-xhigh`, `devin/gemini-3-8-flash-medium`, `devin/kimi-k3-max`, `devin/glm-5-3-high`, `devin/grok-4-6-xhigh`, `devin/deepseek-v4-pro-max`, `devin/swe-1-7`, or `devin/inkling-max`. Flat models pin their declared effort lane, so `/think` levels are fixed per model and `No Thinking`/`None` lanes report `reasoning: false`. Availability is account- and plan-dependent: a lane absent from your catalog fails loudly instead of being remapped. Use `/model` or `omk --list-models devin` for the current list. Image input is unsupported; provide text.
 
 ## Skill and MCP matrix summary
 
@@ -116,6 +116,35 @@ Relevant evidence hooks for SWE-2 lanes are `pre-shell-guard`, `protect-secrets`
 4. If a turn fails with an "unavailable or ambiguous" route or a smaller declared context window, treat it as a configuration signal: check `devin models list`, or lower `contextWindow` as shown above. Do not retry with a guessed wire UID.
 5. Keep credentials out of preset JSON, prompts, and logs: the session token, the exchanged user JWT, and `auth.json` contents are secrets under `protect-secrets`.
 
+## Troubleshooting `does not provide an export named`
+
+If Devin fails with `The requested module './devin-connect.js' does not provide an export named 'MAX_FRAME_BYTES'`, the loaded stream module is mixed with an older unary module. That is a client load error, not an orphan tool call or a remote protocol trailer.
+
+- Current OMK keeps the 16 MiB Connect frame cap inside `devin-connect-stream.ts`, so a stale `devin-connect.js` cannot fail that named import.
+- `/new` does not reload already-imported provider modules. Quit and restart OMK after a rebuild.
+- The failure banner should say to restart OMK, not to sanitize a sticky transcript.
+
+## Troubleshooting `invalid_argument`
+
+A Connect `invalid_argument` trailer is a provider/request failure, not evidence of
+an orphan tool call or a safety refusal. Keep any reported trace ID for support;
+OMK includes only a bounded hexadecimal trace ID, never the remote error body.
+
+- The SWE-2 adapter rejects zero, negative, and non-finite `temperature` values
+  before sending credentials. A controlled high-effort probe returned
+  `invalid_argument` at `temperature: 0`, while the default temperature completed
+  the same prompt. Omit the option to use the native default of `1`; OMK does not
+  silently replace an explicit zero.
+- Check model, effort, context budget, and request settings with `/debug`. Repair
+  tool history only when a tool/message mismatch is actually identified.
+- After updating or rebuilding the adapter, quit and restart the OMK process.
+  `/new` replaces conversation state; it does not reload an imported provider
+  module. This is an update-application step, not a guaranteed fix for every
+  provider error.
+- If a minimal tool-free request still fails at the default temperature, preserve
+  the trace ID and investigate provider compatibility or availability rather than
+  repeatedly sanitizing the same transcript.
+
 ## Local overlay
 
 When the `devin` provider is active, OMK appends `~/.omk/agent/devin.md` (capped at 24,000 characters) to the system prompt, mirroring the Grok `grok.md` overlay. Treat that file as optional host configuration for effort defaults, compaction notes, or team conventions; this page and the current provider documentation remain authoritative and it cannot override higher-priority instructions.

package/docs/ecraf-normalization.md

@@ -0,0 +1,83 @@
+# ECRAF dimensionless normalization (R11)
+
+Status: **pure planner, opt-in, not wired** — the same gate vocabulary as
+[runtime-algorithms](./runtime-algorithms.md) applies. This page documents what is
+implemented and verified, and states explicitly what remains unproven.
+
+## Versions
+
+`planEcrafAdmissions()` accepts an explicit `algorithmVersion`:
+
+| Version | Density formula | When selected |
+| --- | --- | --- |
+| `legacy-v1` (default when omitted) | `P_i / (epsilon + Σ_r weight_r · a_ir)` | No normalization options supplied. |
+| `normalized-v2` | `P_i / (epsilon + slotCost + Σ_r weight_r · a_ir / s_r)` | `algorithmVersion: "normalized-v2"` **or** `referenceScales` supplied without a version (compatibility with the earlier scales-only opt-in). |
+
+Compatibility policy:
+
+- Omitting `algorithmVersion` and every normalization option reproduces the
+  byte-for-byte legacy plan. Legacy regression and property tests are unchanged.
+- Supplying `referenceScales` (or `slotCost`) with `legacy-v1` is rejected with
+  `RangeError`; the scales-only shape silently choosing a different algorithm was
+  the ambiguity this version policy closes.
+- Unknown versions and unknown future options are rejected, not coerced.
+
+## normalized-v2 semantics (spec §13.2)
+
+- Every resource with a nonzero demand needs a positive finite reference scale
+  `s_r`. In `normalized-v2` omitted entries default to the resource's **positive
+  total capacity** — never remaining headroom — so the caller cannot implicitly
+  re-scale ranking by scheduling pressure. Unbounded resources (capacity omitted)
+  cannot fall back to a scale and require an explicit one.
+- Zero capacity is a **feasibility gate**, not a scale: a positive demand on a
+  zero-capacity resource is deferred before scoring; a zero demand still uses the
+  resource in the legacy sense (admission fails on held usage), so the documented
+  "missing capacity = unbounded" and `capacity: 0` meanings are preserved.
+- `slotCost` (λ_slot) is finite and **positive**; the slot term charges every
+  running candidate one execution slot even when its resource vector is empty or
+  all-zero, so an empty node cannot dominate on `epsilon` alone.
+- Infinite capacities are rejected in v2 (`RangeError`); the legacy finite-input
+  contract is unchanged. Finite inputs can still overflow the denominator,
+  density, or reserved usage, and those derived values are rejected with
+  `RangeError` as before.
+
+## Verified properties (unit invariance, spec §13.3)
+
+`a'_ir = c_r·a_ir` with `s'_r = c_r·s_r` (`c_r > 0`) produces the identical plan.
+The seeded property test (`tool-dag-ecraf-normalization.test.ts`) replays the same
+batch under independent power-of-two memory/CPU rescaling, both bounded and
+unbounded, with conflicts, held usage, and slot caps, and additionally asserts
+partition completeness, slot bounds, feasibility, conflict invariants, and input
+immutability. The spec's worked example holds: memory scale 4 GiB / CPU scale 8
+gives A = 0.625 < B = 0.75 in both GiB and byte units.
+
+Unit normalization is **not** a fairness guarantee or an optimality proof, and it
+is not equivalent to DRF.
+
+## What this is not
+
+- **No live path calls the planner.** `runDagFrontier()` in
+  `packages/agent/src/agent-loop.ts` admits ready calls by source order and
+  settled-claim conflicts; it does not import `tool-dag-ecraf`. There is no
+  shadow recording, feature flag, or default change, and **no measured benefit**
+  is claimed anywhere.
+- **The conflict predicate covers only this pass.** A live caller must re-check
+  unsettled claims, re-validate post-hook arguments, and refuse stale plans
+  before granting (spec §13.4). None of that wiring exists.
+- Starvation/fairness accounting (spec §13.5) and same-budget comparisons
+  (§13.6 steps 4–6) are separate, unstarted work.
+
+## Tests
+
+- `packages/agent/test/tool-dag-ecraf-normalization.test.ts` — version policy,
+  scale derivation, zero-capacity gating, slot cost, overflow/validation
+  boundaries, unit-invariance property test (seed 110917, 300 runs).
+- `packages/agent/test/tool-dag-ecraf.test.ts` — legacy behavior, input
+  rejection, admission invariants, and the §13.3 GiB/bytes ranking-flip example.
+- `packages/agent/test/tool-dag-ecraf-arithmetic.test.ts` — finite-arithmetic
+  overflow rejection, unchanged.
+
+Mutation/negative-control evidence: removing the demand/scale division, weakening
+slot-cost positivity to `< 0`, removing the zero-capacity gate, or removing the
+version whitelist each makes the assertion harness fail (run from a /tmp mutant
+copy; the working tree was not modified during the check).

package/docs/metacognition.md

@@ -0,0 +1,51 @@
+# Metacognitive Control Kernel
+
+`src/metacognition/` implements the observation / control / evaluation loop from
+`docs/OMK_metacognitive_control_algorithms_2026-09-19.md`, on top of the
+skill-and-knowledge control kernel from `docs/OMK_skill_knowledge_control_2026-09-19.zip`.
+
+This is a decision-rules library, not a performance claim. It manages what the
+agent *expects*, which *obligations* remain, whether *checks* can actually
+detect the defects they cover, and when a *strategy* should switch — all as
+host-owned structured state, never as model self-report.
+
+## Modules
+
+| Module | Spec | Purpose |
+| --- | --- | --- |
+| `knowledge.ts` | §13 core | Claim/evidence gap inspection (`inspectKnowledge`) |
+| `knowledge-action.ts` | §13 core | Bounded next action (`nextKnowledgeAction`) |
+| `skills.ts` | §13 core | Capability-coverage skill planning (`planSkills`) |
+| `retrieval.ts` | §13 core | Local BM25 (`searchCorpus`), owned-promise `AcquisitionPool` |
+| `context7.ts` | §13 core | Approved-egress Context7 GET adapter (`Context7Client`) |
+| `runtime-bridge.ts` | §13 attach | ClaimGraph/ObservationNode → kernel inputs (`toMetaState`) |
+| `evaluation.ts` | §11, §15 | DR offline estimator, experience records, completion metrics |
+| `observe.ts` | §13 observe | Observation-mode diagnostics (`attachMetaDiagnostics`) |
+| `obligations.ts` | A / §4 | Change-atom rules → candidate vs required obligations |
+| `predictions.ts` | B / §5 | Pre-registered prediction ledger, Brier/surprise scoring |
+| `decision.ts` | C / §6 | Finite Bayes risk + one-step VOI (`experimentValue`) |
+| `verifier.ts` | D / §7 | Obligation-scoped negative-control evaluation (`evaluateVerifier`) |
+| `calibration.ts` | E+G / §8, §10 | Condition-bucket Beta records + drift demotion |
+| `state.ts` | §3, §9.5 | `MetaState` tuple and the three finish states |
+| `policy.ts` | F / §9, §14 | Feasibility gating + priority-table action selection |
+| `checkpoint.ts` | §9.4 | One ordered checkpoint evaluation (`checkpoint`) |
+
+## Invariants enforced
+
+- Required approvals and required checks are hard constraints, not optimization
+  inputs.
+- Predictions are registered before outcomes and never overwritten; edits append.
+- Model-produced obligations stay candidates until host facts promote them.
+- Mutant counts exclude compile-broken, environment-failed, and equivalent
+  mutants; an empty denominator reports `unknown`, never a score.
+- `max VOI <= 0` never implies verified completion; receipts must bind to the
+  current candidate hash.
+- Environment failures are recorded separately from code failures — neither
+  inflates nor silently discards the other.
+
+## Tests
+
+`test/metacognition-*.test.ts` — 94 tests, including the 13 numerical checks
+ported from `check_examples.py` (Brier 0.9025 at p=0.95 failure, VOI 0.84,
+XOR two-bit synergy 0.40, probability-vector rejection) and the reference
+kernel's contract tests.