open-multi-agent-kit 1.0.0 → 1.2.0

package/dist/observation/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Observation kernel types — U1/U2 of the upgraded SoL-Pi design.
+ *
+ * Raw observations are host-owned execution artifacts. Model-facing views are
+ * derived projections and never replace the raw authority: `taskVerdict` is
+ * always `not-assessed` here because a view cannot prove completion.
+ */
+export type ObservationStatus = "exit" | "signal" | "partial" | "unavailable";
+export type ObservationPrivacy = "raw-private" | "approved-sanitized";
+export type ObservationKind = "log" | "test" | "command" | "file" | "dom" | "network" | "generic";
+/**
+ * A stored execution artifact. `observationId` binds the run, operation and
+ * sequence to the content digest, so two identical byte outputs from different
+ * executions remain distinct events (never content-hash deduped into one).
+ */
+export interface RawObservation {
+    readonly observationId: string;
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly operationId: string;
+    readonly sequence: number;
+    readonly rawDigest: string;
+    readonly byteLength: number;
+    readonly bytes: Uint8Array;
+    readonly status: ObservationStatus;
+    readonly kind: ObservationKind;
+    readonly privacy: ObservationPrivacy;
+    /** False when the capture itself was truncated upstream — never claim "full raw". */
+    readonly sourceComplete: boolean;
+    readonly toolCallId?: string;
+}
+export type ObservationViewKind = "full" | "excerpt" | "evidence" | "pointer";
+export type ObservationCoverageStatus = "complete" | "partial" | "unknown";
+/**
+ * A model-facing projection of a stored observation. `transformationDigest`
+ * binds the view to the deterministic transform that produced it, and
+ * `coverageStatus` records whether the view preserves the required fact atoms.
+ */
+export interface ObservationView {
+    readonly viewKind: ObservationViewKind;
+    readonly observationId: string;
+    readonly parentDigest: string;
+    readonly transformationDigest: string;
+    readonly text: string;
+    readonly estimatedTokens: number;
+    readonly coveredFactIds: readonly string[];
+    readonly missingRequiredFactIds: readonly string[];
+    readonly coverageStatus: ObservationCoverageStatus;
+    readonly taskVerdict: "not-assessed";
+}
+/** Result of a scoped, byte-bounded read against a stored observation. */
+export interface ObservationRead {
+    readonly observationId: string;
+    readonly text: string;
+    readonly byteOffset: number;
+    readonly byteLength: number;
+    readonly nextOffset: number;
+    readonly eof: boolean;
+    readonly truncated: boolean;
+    readonly sourceComplete: boolean;
+    /** True when the requested byte range was snapped to UTF-8 boundaries. */
+    readonly normalized: boolean;
+}
+export type ObservationReadError = "observation-not-found" | "scope-mismatch" | "invalid-range" | "utf8-boundary" | "archive-unavailable";
+export type ObservationReadResult = {
+    readonly ok: true;
+    readonly read: ObservationRead;
+} | {
+    readonly ok: false;
+    readonly error: ObservationReadError;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/observation/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,CAAC;AAC9E,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,oBAAoB,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;AAElG;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,uFAAqF;IACrF,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAC9E,MAAM,MAAM,yBAAyB,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAE3E;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;IACnD,QAAQ,CAAC,cAAc,EAAE,yBAAyB,CAAC;IACnD,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC;CACrC;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,MAAM,oBAAoB,GAC7B,uBAAuB,GACvB,gBAAgB,GAChB,eAAe,GACf,eAAe,GACf,qBAAqB,CAAC;AAEzB,MAAM,MAAM,qBAAqB,GAC9B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAA;CAAE,CAAC","sourcesContent":["/**\n * Observation kernel types — U1/U2 of the upgraded SoL-Pi design.\n *\n * Raw observations are host-owned execution artifacts. Model-facing views are\n * derived projections and never replace the raw authority: `taskVerdict` is\n * always `not-assessed` here because a view cannot prove completion.\n */\n\nexport type ObservationStatus = \"exit\" | \"signal\" | \"partial\" | \"unavailable\";\nexport type ObservationPrivacy = \"raw-private\" | \"approved-sanitized\";\nexport type ObservationKind = \"log\" | \"test\" | \"command\" | \"file\" | \"dom\" | \"network\" | \"generic\";\n\n/**\n * A stored execution artifact. `observationId` binds the run, operation and\n * sequence to the content digest, so two identical byte outputs from different\n * executions remain distinct events (never content-hash deduped into one).\n */\nexport interface RawObservation {\n\treadonly observationId: string;\n\treadonly sessionId: string;\n\treadonly runId: string;\n\treadonly operationId: string;\n\treadonly sequence: number;\n\treadonly rawDigest: string;\n\treadonly byteLength: number;\n\treadonly bytes: Uint8Array;\n\treadonly status: ObservationStatus;\n\treadonly kind: ObservationKind;\n\treadonly privacy: ObservationPrivacy;\n\t/** False when the capture itself was truncated upstream — never claim \"full raw\". */\n\treadonly sourceComplete: boolean;\n\treadonly toolCallId?: string;\n}\n\nexport type ObservationViewKind = \"full\" | \"excerpt\" | \"evidence\" | \"pointer\";\nexport type ObservationCoverageStatus = \"complete\" | \"partial\" | \"unknown\";\n\n/**\n * A model-facing projection of a stored observation. `transformationDigest`\n * binds the view to the deterministic transform that produced it, and\n * `coverageStatus` records whether the view preserves the required fact atoms.\n */\nexport interface ObservationView {\n\treadonly viewKind: ObservationViewKind;\n\treadonly observationId: string;\n\treadonly parentDigest: string;\n\treadonly transformationDigest: string;\n\treadonly text: string;\n\treadonly estimatedTokens: number;\n\treadonly coveredFactIds: readonly string[];\n\treadonly missingRequiredFactIds: readonly string[];\n\treadonly coverageStatus: ObservationCoverageStatus;\n\treadonly taskVerdict: \"not-assessed\";\n}\n\n/** Result of a scoped, byte-bounded read against a stored observation. */\nexport interface ObservationRead {\n\treadonly observationId: string;\n\treadonly text: string;\n\treadonly byteOffset: number;\n\treadonly byteLength: number;\n\treadonly nextOffset: number;\n\treadonly eof: boolean;\n\treadonly truncated: boolean;\n\treadonly sourceComplete: boolean;\n\t/** True when the requested byte range was snapped to UTF-8 boundaries. */\n\treadonly normalized: boolean;\n}\n\nexport type ObservationReadError =\n\t| \"observation-not-found\"\n\t| \"scope-mismatch\"\n\t| \"invalid-range\"\n\t| \"utf8-boundary\"\n\t| \"archive-unavailable\";\n\nexport type ObservationReadResult =\n\t| { readonly ok: true; readonly read: ObservationRead }\n\t| { readonly ok: false; readonly error: ObservationReadError };\n"]}

package/dist/observation/types.js

@@ -0,0 +1,9 @@
+/**
+ * Observation kernel types — U1/U2 of the upgraded SoL-Pi design.
+ *
+ * Raw observations are host-owned execution artifacts. Model-facing views are
+ * derived projections and never replace the raw authority: `taskVerdict` is
+ * always `not-assessed` here because a view cannot prove completion.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/observation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/observation/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG","sourcesContent":["/**\n * Observation kernel types — U1/U2 of the upgraded SoL-Pi design.\n *\n * Raw observations are host-owned execution artifacts. Model-facing views are\n * derived projections and never replace the raw authority: `taskVerdict` is\n * always `not-assessed` here because a view cannot prove completion.\n */\n\nexport type ObservationStatus = \"exit\" | \"signal\" | \"partial\" | \"unavailable\";\nexport type ObservationPrivacy = \"raw-private\" | \"approved-sanitized\";\nexport type ObservationKind = \"log\" | \"test\" | \"command\" | \"file\" | \"dom\" | \"network\" | \"generic\";\n\n/**\n * A stored execution artifact. `observationId` binds the run, operation and\n * sequence to the content digest, so two identical byte outputs from different\n * executions remain distinct events (never content-hash deduped into one).\n */\nexport interface RawObservation {\n\treadonly observationId: string;\n\treadonly sessionId: string;\n\treadonly runId: string;\n\treadonly operationId: string;\n\treadonly sequence: number;\n\treadonly rawDigest: string;\n\treadonly byteLength: number;\n\treadonly bytes: Uint8Array;\n\treadonly status: ObservationStatus;\n\treadonly kind: ObservationKind;\n\treadonly privacy: ObservationPrivacy;\n\t/** False when the capture itself was truncated upstream — never claim \"full raw\". */\n\treadonly sourceComplete: boolean;\n\treadonly toolCallId?: string;\n}\n\nexport type ObservationViewKind = \"full\" | \"excerpt\" | \"evidence\" | \"pointer\";\nexport type ObservationCoverageStatus = \"complete\" | \"partial\" | \"unknown\";\n\n/**\n * A model-facing projection of a stored observation. `transformationDigest`\n * binds the view to the deterministic transform that produced it, and\n * `coverageStatus` records whether the view preserves the required fact atoms.\n */\nexport interface ObservationView {\n\treadonly viewKind: ObservationViewKind;\n\treadonly observationId: string;\n\treadonly parentDigest: string;\n\treadonly transformationDigest: string;\n\treadonly text: string;\n\treadonly estimatedTokens: number;\n\treadonly coveredFactIds: readonly string[];\n\treadonly missingRequiredFactIds: readonly string[];\n\treadonly coverageStatus: ObservationCoverageStatus;\n\treadonly taskVerdict: \"not-assessed\";\n}\n\n/** Result of a scoped, byte-bounded read against a stored observation. */\nexport interface ObservationRead {\n\treadonly observationId: string;\n\treadonly text: string;\n\treadonly byteOffset: number;\n\treadonly byteLength: number;\n\treadonly nextOffset: number;\n\treadonly eof: boolean;\n\treadonly truncated: boolean;\n\treadonly sourceComplete: boolean;\n\t/** True when the requested byte range was snapped to UTF-8 boundaries. */\n\treadonly normalized: boolean;\n}\n\nexport type ObservationReadError =\n\t| \"observation-not-found\"\n\t| \"scope-mismatch\"\n\t| \"invalid-range\"\n\t| \"utf8-boundary\"\n\t| \"archive-unavailable\";\n\nexport type ObservationReadResult =\n\t| { readonly ok: true; readonly read: ObservationRead }\n\t| { readonly ok: false; readonly error: ObservationReadError };\n"]}

package/dist/observation/view.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 type { ObservationView, RawObservation } from "./types.ts";
+export declare function estimateViewTokens(text: string): number;
+/** A host-verifiable fact atom extracted from raw bytes, e.g. exitCode=1. */
+export interface FactAtom {
+    readonly id: string;
+    /** The verbatim text that must appear in a view for the atom to count as covered. */
+    readonly evidence: string;
+    readonly byteOffset: number;
+    readonly byteLength: number;
+}
+/**
+ * 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 declare function extractFacts(raw: Uint8Array, requiredFactIds?: readonly string[]): FactAtom[];
+/**
+ * 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 declare function makeViews(observation: RawObservation, requiredFactIds?: readonly string[]): readonly ObservationView[];
+/**
+ * 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 declare function chooseView(views: readonly ObservationView[], budgetTokens: number, requiredFactIds?: readonly string[]): ObservationView | null;
+//# sourceMappingURL=view.d.ts.map

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/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.

package/docs/model-catalog-refresh.md

@@ -3,6 +3,65 @@
 확인일: 2026-09-09. 생성기와 공급자 어댑터를 수정한 뒤 `npm run models:refresh`로
 두 카탈로그를 재생성했다. 생성 파일을 손으로 수정하지 않았다.
 
+## 2026-09-19 갱신: 라이브 재생성과 생성기 결함 3건 교정
+
+`npm run models:refresh`를 종료0으로 재생성했다(전 소스 응답, `--allow-partial` 미사용,
+키 없는 Zyloo는 정적 6개 유지). 결과는 **39 providers, 1,795→1,799 모델**, 추가 4·제거 0·
+변경 22(가격 20, OpenRouter 선언 thinking 2), 이미지 카탈로그 54개 변화 없음.
+
+첫 재생성에서는 제거 4·변경 220이 나왔고, 그중 상류 변화가 아닌 항목이 셋이었다.
+각각 실패하는 검사를 먼저 쓰고(11개 RED) 생성기를 고친 뒤 다시 생성했다.
+
+| 결함 | 원인 | 조치 |
+| --- | --- | --- |
+| `kimi-coding` 공급자 4개 전부 소실 | models.dev가 `kimi-for-coding` 키를 `kimi-code-plan-global`(api.kimi.ai)·`kimi-code-plan-cn`(api.kimi.com)으로 분리. 생성기는 옛 키만 읽어 조용히 빈 결과 | 세 키를 순서대로 조회. OMK endpoint(`api.kimi.com/coding`)·헤더·thinking 맵은 그대로. `kimi-coding-catalog.test.ts` |
+| cursor 143·devin 55개 고정-노력 레인에 `xhigh/max` 추가 | 직전 커밋은 `--cursor-only`로 가족 단위 pass를 우회했지만 전체 재생성은 `applyModelMetadata`(Fable→xhigh/max, Opus 5→전체 사다리 등)를 정적 레인에도 적용 | devin/cursor 항목을 pass 이후에 붙여 fast path와 동일하게 유지. `fixed-effort-lanes.test.ts`가 정적 카탈로그와 생성 결과의 동일성을 검사 |
+| OpenCode Zen `deepseek-v4.1-flash`가 구형 V4 맵(`high`, `xhigh→max`)만 받음 | V4.1 계약 보정 조건이 `opencode-go`만 인식 | [Zen 문서](https://opencode.ai/docs/zen/)가 같은 `chat/completions` gateway를 명시하므로 `opencode`도 `off/low/high/max`·`max_tokens`·`supportsReasoningEffort` 적용. `deepseek-v41-native.test.ts` route에 추가 |
+
+두 번째 결함은 cursor/devin 항목이 정적 카탈로그와 다르게 저장될 때 즉시 실패하므로,
+앞으로 fast path와 전체 재생성이 갈라지면 검사에서 드러난다.
+
+### 추가된 항목
+
+| 공급자 | 요청 ID | thinking | 가격(1M) | 근거 |
+| --- | --- | --- | --- | --- |
+| `opencode` | `deepseek-v4.1-flash` | `off/low/high/max`, `thinking.type`+`reasoning_effort`, `max_tokens` | $0.30/$1.20, cache $0.006 | Zen 문서 endpoint·가격표 |
+| `opencode` | `qwen3.8-flash` | Messages 예산 경로(기존 Zen Qwen과 동일) | $0.15/$0.47, cache read $0.016·write $0.20 | Zen 문서 |
+| `openrouter` | `z-ai/glm-5.3-flashx` | mandatory, `low/high/max` (route 선언) | $0.37/$1.25, cache $0.075 | OpenRouter `created` 09-18 |
+| `openrouter` | `prism-ml/ternary-bonsai-2-27b` | optional off, `medium/xhigh` (route 선언) | $0.075/$0.50 | OpenRouter `created` 09-18 |
+
+### 상류 변경(가격·선언)
+
+- OpenCode Zen·Vercel의 `gpt-5.6-sol`은 "50% Off" 표시가 끝나 $4/$20(cache $0.40/$5)로 복귀. Vercel `gpt-5.6-sol-fast`는 $8/$40.
+- OpenRouter DeepSeek 계열 인하: `deepseek-v4.1-flash` $0.15/$0.60, `deepseek-v4-pro` $0.54/$1.09, `-latest` 별칭 3개 동반 조정.
+  목록 값이며 DeepSeek 직접 API의 시간대별 가격과 다르다.
+- OpenRouter `moonshotai/kimi-k3`·`~moonshotai/kimi-latest` $1.70/$8.50, `z-ai/glm-5.3` $0.91/$2.86, `meta/muse-glimmer-30b` $0.35/$1.50, Nemotron 3 Ultra·3.5 Lightning 출력 상한 상향.
+- `upstage/solar-pro-3`(`off/minimal~high`)·`solar-pro4`(`off/minimal~max`)가 route 선언을 얻어 thinking 맵이 생겼다.
+
+### 조사했으나 넣지 않은 항목
+
+- **Amazon Bedrock Kimi K3** (09-18 GA). [모델 카드](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-moonshot-ai-kimi-k3.html)
+  기준 ID `global.moonshotai.kimi-k3`(Global $3/$15, cache read $0.30·write $3.75) ·
+  `us.moonshotai.kimi-k3`(US $3.30/$16.50), in-region 없음, 1M context, 이미지 입력, Converse·도구·스트리밍 지원.
+  같은 카드가 "Converse는 이전 턴의 reasoning content가 포함되면 `InternalServerException`"을 명시하는데,
+  OMK `amazon-bedrock`은 non-Claude 모델의 thinking을 `reasoningContent`로 그대로 replay한다(`convertMessages`).
+  카탈로그만 넣으면 두 번째 턴부터 실패하는 경로를 광고하므로, 공급자에서 이전 턴 reasoning을 제거하는
+  수정과 유료 실검증을 묶은 후속 단위로 미룬다. models.dev bedrock 목록에도 아직 없다.
+- **Qwen3.8-Omni-Flash** (Alibaba, 09-18): OpenRouter·Vercel·models.dev의 tool 지원 목록에 없다. Model Studio 직접 경로는 OMK 내장 공급자가 아니다.
+- **Gemini 3.8 Live / Live Extended Thinking** (09-15~16): 오디오 네이티브 경로로 코딩 카탈로그 소스에 없다.
+- **GPT-6 Astra Law** (`gpt-6-astra-law`): OpenAI가 "coming soon"으로만 공지, API 미제공.
+- **Union Alpha**: `stealth/union-alpha`는 09-18 갱신에서 이미 빠졌고, 정식 `unbiased/pareto`($2.50/$7.50, cache $0.25, thinking 미선언)가 HEAD에 있다. 이번 갱신에서 변화 없음.
+
+### 검증과 한계
+
+표적 vitest 13파일 **149개 통과**(신규 `fixed-effort-lanes`·`kimi-coding-catalog`, 확장한
+`deepseek-v41-native` 포함), 전체 `tsgo --noEmit`, 변경 파일 Biome, module-size·import-cycles
+ baseline, `git diff --check` 모두 종료0. 공급자 추론, 전체 `npm run check`, build/install,
+commit/push는 실행하지 않았다. 계정별 사용 가능 여부와 실제 청구액은 검증 범위 밖이다.
+
+변경 단위: `packages/ai/scripts/{generate-models,catalog-thinking}.ts`, 생성 카탈로그, 검사 3파일, 본 문서.
+제안 메시지: `fix(ai): 모델 카탈로그 09-19 갱신과 생성기 결함 교정 (kimi-coding 소실·고정 레인 확장·Zen V4.1 계약)`.
+
 ## 2026-09-17 후속: OpenCode Go DeepSeek V4.1 ID 변경
 
 [OpenCode Go 공식 endpoint 목록](https://opencode.ai/docs/go/)의 현재 ID는

package/docs/providers.md

@@ -271,6 +271,7 @@ omk
 | Fireworks | `FIREWORKS_API_KEY` | `fireworks` |
 | Together AI | `TOGETHER_API_KEY` | `together` |
 | Kimi For Coding | `KIMI_API_KEY` | `kimi-coding` |
+| WorkBuddy (CodeBuddy) | `WORKBUDDY_API_KEY` | `workbuddy` |
 | Meta Model API | `META_API_KEY` (or `META_MODEL_API_KEY`, `MODEL_API_KEY`) | `meta` |
 | MiniMax | `MINIMAX_API_KEY` | `minimax` |
 | MiniMax (China) | `MINIMAX_CN_API_KEY` | `minimax-cn` |
@@ -282,6 +283,58 @@ omk
 
 Reference for environment variables and `auth.json` keys: [`const envMap`](https://github.com/dmae97/omk/blob/main/packages/ai/src/env-api-keys.ts) in [`packages/ai/src/env-api-keys.ts`](https://github.com/dmae97/omk/blob/main/packages/ai/src/env-api-keys.ts).
 
+#### WorkBuddy (Tencent CodeBuddy)
+
+The cloud inference behind Tencent's CodeBuddy / WorkBuddy agents. Plan keys start
+with `ck_` and are issued by the CodeBuddy login flow:
+
+```bash
+export WORKBUDDY_API_KEY=ck_...
+omk --provider workbuddy --model glm-5.3
+```
+
+Endpoint and limits, verified against the live service on 2026-09-19:
+
+- Chat requests go to `https://www.workbuddy.ai/v2/chat/completions` and must
+  stream; a non-streaming request is rejected. The same key is accepted by
+  `www.codebuddy.ai`, not by the `*.cn` hosts.
+- The first message must be a `system` message. OMK sends the system prompt in
+  that position and prepends an empty one when a session has no system prompt.
+- `max_tokens` carries the output cap; `max_completion_tokens` is ignored
+  upstream.
+- Images are sent as data URIs, which is the only form the endpoint accepts.
+- Thinking levels expose only the effort values the provider declares for that
+  model (`glm-5.3`: low/high/max, `glm-5.2`: high/xhigh, `gpt-5.6-*`:
+  low/medium/high/xhigh, …). The endpoint accepts `reasoning_effort`, but its
+  effect on reasoning volume is not verified, and no `off` value is offered
+  because none was verified. Thinking can therefore not be disabled per request.
+- Model entitlement is per plan: the built-in catalog lists the 27 lanes verified
+  for one account, including eight the CLI's bundled product JSON never declares
+  (`claude-opus-5`, `claude-opus-4.6`, `claude-sonnet-4.6`,
+  `deepseek-v4.1-flash`, `gemini-3.8-flash`, `gpt-6-astra`, `grok-4.6`,
+  `hy4-preview`) which a cross-sweep of this repository's own model ids found.
+  `glm-5.0` answered `429` while its siblings answered `200`, so it is not
+  listed; the CLI's role aliases (`fast-model`, `balanced-model`,
+  `primary-model`, `deep-model`) resolve server-side to targets this catalog
+  cannot declare and are not listed either.
+- Billing is metered in the provider's own credit unit, which OMK reports as
+  zero cost rather than inventing a USD rate. Measured per-call charges on one
+  account (small prompts): `claude-opus-5` 0.26, `claude-opus-4.6` 0.20,
+  `claude-sonnet-4.6` 0.12, `grok-4.6` 0.06–0.08, `gpt-5.6-sol` 0.04,
+  `gemini-3.8-flash` 0.02–0.06, `glm-5.3` 0.01, and 0 credits on `hy3`,
+  `deepseek-v3-0324`, `deepseek-v4.1-flash`, `glm-5.2`, `kimi-k2.5/k2.6` and
+  `minimax-m3`. A charge scales with tokens, so these are magnitudes, not
+  tariffs.
+- Plan allowances (provider documentation, 2026-09-19): Free 100 credits/month,
+  Pro $10/month or $96/year for 2,000 credits/month, plus a limited-time
+  activity bonus of 30 credits/day on Free and 50/day on Pro. Credits are issued
+  monthly, do not carry over, and new accounts get 250 credits valid for 14 days;
+  Pro has a 7-day trial of 500 credits. Check the provider console for the
+  account's own balance: at the measured rates, the Free plan's 100 credits is
+  roughly 380 calls at `claude-opus-5` size, ~830 at `claude-sonnet-4.6`, and
+  1,600-5,000 at `gemini-3.8-flash`, while the 0-credit lanes above did not draw
+  on the allowance at all in these probes.
+
 #### NVIDIA NIM
 
 Set `NVIDIA_API_KEY` and select a currently listed NVIDIA model with `/model`.