open-multi-agent-kit 0.99.0 → 1.2.0

package/dist/metacognition/skills.js

@@ -0,0 +1,220 @@
+/**
+ * Capability-coverage skill planning under host-approved constraints.
+ *
+ * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip
+ * (src/skills.ts). Exact search for small sets, bounded greedy for large sets.
+ */
+import { arrayBound, ensure, integer, lexical, text, unique } from "./validation.js";
+export function planSkills(input) {
+    text(input.phase, "phase", 128);
+    integer(input.tokenBudget, "tokenBudget", 10_000_000);
+    integer(input.maxSkills, "maxSkills", 64);
+    arrayBound(input.catalog, "catalog", 500);
+    arrayBound(input.needs, "needs", 128);
+    unique(input.catalog.map((s) => s.id), "catalog ids");
+    unique(input.needs.map((n) => n.capability), "need ids", 128);
+    unique(input.allowedPermissions, "permissions");
+    unique(input.explicitSkills, "explicitSkills", 64);
+    for (const need of input.needs) {
+        ensure(Number.isFinite(need.weight) && need.weight > 0 && need.weight <= 1_000_000, "invalid need weight");
+        ensure(typeof need.required === "boolean", "required must be boolean");
+    }
+    const byId = new Map(input.catalog.map((skill) => [skill.id, skill]));
+    const rejected = new Map();
+    for (const skill of input.catalog) {
+        text(skill.contentHash, "contentHash");
+        integer(skill.tokenCost, "tokenCost", 1_000_000);
+        unique(skill.capabilities, "capabilities", 128);
+        unique(skill.phases, "phases", 32);
+        unique(skill.dependencies, "dependencies", 64);
+        unique(skill.conflicts, "conflicts", 64);
+        unique(skill.permissions, "skill permissions", 64);
+        ensure(typeof skill.explicitOnly === "boolean", "explicitOnly must be boolean");
+        ensure(skill.packages !== null && typeof skill.packages === "object", "packages must be a record");
+        for (const [name, versions] of Object.entries(skill.packages)) {
+            text(name, "package");
+            unique(versions, "versions", 128);
+            ensure(versions.length > 0, "empty supported versions");
+        }
+        if (input.approvedHashes[skill.id] !== skill.contentHash)
+            rejected.set(skill.id, "unapproved-or-changed-content");
+        else if (!skill.phases.includes(input.phase))
+            rejected.set(skill.id, "phase-mismatch");
+        else if (skill.explicitOnly && !input.explicitSkills.includes(skill.id))
+            rejected.set(skill.id, "explicit-only");
+        else if (skill.permissions.some((permission) => !input.allowedPermissions.includes(permission))) {
+            rejected.set(skill.id, "permission-denied");
+        }
+        else if (Object.entries(skill.packages).some(([name, versions]) => !versions.includes(input.installedVersions[name] ?? ""))) {
+            rejected.set(skill.id, "version-unknown-or-incompatible");
+        }
+    }
+    // A cycle or unavailable prerequisite invalidates the entire dependent closure.
+    const closureCache = new Map();
+    const closure = (id, trail = new Set()) => {
+        if (trail.has(id) || rejected.has(id))
+            return undefined;
+        if (closureCache.has(id))
+            return closureCache.get(id);
+        const skill = byId.get(id);
+        if (!skill)
+            return undefined;
+        const result = new Set([id]);
+        const next = new Set([...trail, id]);
+        for (const dependency of skill.dependencies) {
+            const children = closure(dependency, next);
+            if (!children) {
+                closureCache.set(id, undefined);
+                return undefined;
+            }
+            for (const child of children)
+                result.add(child);
+        }
+        closureCache.set(id, result);
+        return result;
+    };
+    const closures = new Map();
+    for (const id of [...byId.keys()].sort(lexical)) {
+        const set = closure(id);
+        if (set)
+            closures.set(id, set);
+        else if (!rejected.has(id))
+            rejected.set(id, "invalid-dependency-closure");
+    }
+    const feasible = (ids) => {
+        if (ids.size > input.maxSkills)
+            return false;
+        let cost = 0;
+        for (const id of ids) {
+            const skill = byId.get(id);
+            if (!skill || rejected.has(id))
+                return false;
+            if (skill.dependencies.some((d) => !ids.has(d)))
+                return false;
+            if (skill.conflicts.some((c) => ids.has(c)))
+                return false;
+            cost += skill.tokenCost;
+        }
+        return cost <= input.tokenBudget;
+    };
+    const value = (ids) => {
+        const coverage = new Set();
+        let cost = 0;
+        for (const id of ids) {
+            const skill = byId.get(id);
+            cost += skill.tokenCost;
+            for (const capability of skill.capabilities)
+                coverage.add(capability);
+        }
+        let required = 0, optional = 0;
+        for (const need of input.needs) {
+            if (coverage.has(need.capability)) {
+                if (need.required)
+                    required += need.weight;
+                else
+                    optional += need.weight;
+            }
+        }
+        return { required, optional, cost, ids: [...ids].sort(lexical) };
+    };
+    const better = (left, right) => left.required !== right.required
+        ? left.required > right.required
+        : left.optional !== right.optional
+            ? left.optional > right.optional
+            : left.cost !== right.cost
+                ? left.cost < right.cost
+                : left.ids.length !== right.ids.length
+                    ? left.ids.length < right.ids.length
+                    : lexical(left.ids.join("\0"), right.ids.join("\0")) < 0;
+    let base = new Set();
+    const blockedExplicit = [];
+    for (const id of [...input.explicitSkills].sort(lexical)) {
+        const set = closures.get(id);
+        if (!set)
+            blockedExplicit.push(id);
+        else
+            for (const item of set)
+                base.add(item);
+    }
+    if (!feasible(base))
+        blockedExplicit.push(...input.explicitSkills.filter((id) => !blockedExplicit.includes(id)));
+    // Conflicting explicit requests are never silently replaced by automatic picks.
+    if (blockedExplicit.length > 0)
+        base = new Set();
+    let best = base;
+    const candidates = [...closures.entries()].filter(([id]) => !base.has(id));
+    const algorithm = candidates.length <= 12 ? "exact-small" : "greedy-with-singleton";
+    if (blockedExplicit.length === 0) {
+        if (algorithm === "exact-small") {
+            const visit = (position, current) => {
+                if (!feasible(current))
+                    return;
+                if (better(value(current), value(best)))
+                    best = current;
+                const candidate = candidates[position];
+                if (!candidate)
+                    return;
+                visit(position + 1, current);
+                visit(position + 1, new Set([...current, ...candidate[1]]));
+            };
+            visit(0, base);
+        }
+        else {
+            let current = base;
+            while (true) {
+                const previous = value(current);
+                let winner;
+                let rank = [-1, -1, ""];
+                for (const [id, set] of candidates) {
+                    if (current.has(id))
+                        continue;
+                    const joined = new Set([...current, ...set]);
+                    if (!feasible(joined))
+                        continue;
+                    const after = value(joined);
+                    const requiredGain = after.required - previous.required;
+                    const optionalGain = after.optional - previous.optional;
+                    if (requiredGain <= 0 && optionalGain <= 0)
+                        continue;
+                    const cost = Math.max(1, after.cost - previous.cost);
+                    const proposal = [requiredGain / cost, optionalGain / cost, id];
+                    if (!winner ||
+                        proposal[0] > rank[0] ||
+                        (proposal[0] === rank[0] &&
+                            (proposal[1] > rank[1] || (proposal[1] === rank[1] && lexical(proposal[2], rank[2]) < 0)))) {
+                        winner = joined;
+                        rank = proposal;
+                    }
+                }
+                if (!winner)
+                    break;
+                current = winner;
+            }
+            best = current;
+            for (const [, set] of candidates) {
+                const joined = new Set([...base, ...set]);
+                if (feasible(joined) && better(value(joined), value(best)))
+                    best = joined;
+            }
+        }
+    }
+    const allCovered = new Set([...best].flatMap((id) => byId.get(id).capabilities));
+    const uncoveredRequired = input.needs
+        .filter((n) => n.required && !allCovered.has(n.capability))
+        .map((n) => n.capability)
+        .sort(lexical);
+    return {
+        selected: [...best].sort(lexical),
+        tokenCost: value(best).cost,
+        covered: input.needs
+            .filter((n) => allCovered.has(n.capability))
+            .map((n) => n.capability)
+            .sort(lexical),
+        uncoveredRequired,
+        blockedExplicit: blockedExplicit.sort(lexical),
+        rejected: Object.fromEntries([...rejected].sort(([a], [b]) => lexical(a, b))),
+        algorithm,
+        state: blockedExplicit.length ? "explicit-blocked" : uncoveredRequired.length ? "capability-gap" : "covered",
+    };
+}
+//# sourceMappingURL=skills.js.map

package/dist/metacognition/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/metacognition/skills.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Capability-coverage skill planning under host-approved constraints.\n *\n * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip\n * (src/skills.ts). Exact search for small sets, bounded greedy for large sets.\n */\nimport { arrayBound, ensure, integer, lexical, text, unique } from \"./validation.ts\";\n\nexport interface CapabilityNeed {\n\treadonly capability: string;\n\treadonly weight: number;\n\treadonly required: boolean;\n}\nexport interface SkillDescriptor {\n\treadonly id: string;\n\treadonly contentHash: string;\n\treadonly capabilities: readonly string[];\n\treadonly phases: readonly string[];\n\treadonly tokenCost: number;\n\treadonly dependencies: readonly string[];\n\treadonly conflicts: readonly string[];\n\treadonly permissions: readonly string[];\n\treadonly explicitOnly: boolean;\n\t/** Exact versions intentionally, never a hand-written semver implementation. */\n\treadonly packages: Readonly<Record<string, readonly string[]>>;\n}\nexport interface SkillPlanInput {\n\treadonly phase: string;\n\treadonly needs: readonly CapabilityNeed[];\n\treadonly catalog: readonly SkillDescriptor[];\n\t/** Host-owned content pins, not fields supplied by the skill being selected. */\n\treadonly approvedHashes: Readonly<Record<string, string>>;\n\treadonly installedVersions: Readonly<Record<string, string>>;\n\treadonly allowedPermissions: readonly string[];\n\treadonly explicitSkills: readonly string[];\n\treadonly tokenBudget: number;\n\treadonly maxSkills: number;\n}\nexport interface SkillPlan {\n\treadonly selected: readonly string[];\n\treadonly tokenCost: number;\n\treadonly covered: readonly string[];\n\treadonly uncoveredRequired: readonly string[];\n\treadonly blockedExplicit: readonly string[];\n\treadonly rejected: Readonly<Record<string, string>>;\n\treadonly algorithm: \"exact-small\" | \"greedy-with-singleton\";\n\treadonly state: \"covered\" | \"capability-gap\" | \"explicit-blocked\";\n}\ninterface Value {\n\trequired: number;\n\toptional: number;\n\tcost: number;\n\tids: string[];\n}\n\nexport function planSkills(input: SkillPlanInput): SkillPlan {\n\ttext(input.phase, \"phase\", 128);\n\tinteger(input.tokenBudget, \"tokenBudget\", 10_000_000);\n\tinteger(input.maxSkills, \"maxSkills\", 64);\n\tarrayBound(input.catalog, \"catalog\", 500);\n\tarrayBound(input.needs, \"needs\", 128);\n\tunique(\n\t\tinput.catalog.map((s) => s.id),\n\t\t\"catalog ids\",\n\t);\n\tunique(\n\t\tinput.needs.map((n) => n.capability),\n\t\t\"need ids\",\n\t\t128,\n\t);\n\tunique(input.allowedPermissions, \"permissions\");\n\tunique(input.explicitSkills, \"explicitSkills\", 64);\n\tfor (const need of input.needs) {\n\t\tensure(Number.isFinite(need.weight) && need.weight > 0 && need.weight <= 1_000_000, \"invalid need weight\");\n\t\tensure(typeof need.required === \"boolean\", \"required must be boolean\");\n\t}\n\tconst byId = new Map(input.catalog.map((skill) => [skill.id, skill]));\n\tconst rejected = new Map<string, string>();\n\tfor (const skill of input.catalog) {\n\t\ttext(skill.contentHash, \"contentHash\");\n\t\tinteger(skill.tokenCost, \"tokenCost\", 1_000_000);\n\t\tunique(skill.capabilities, \"capabilities\", 128);\n\t\tunique(skill.phases, \"phases\", 32);\n\t\tunique(skill.dependencies, \"dependencies\", 64);\n\t\tunique(skill.conflicts, \"conflicts\", 64);\n\t\tunique(skill.permissions, \"skill permissions\", 64);\n\t\tensure(typeof skill.explicitOnly === \"boolean\", \"explicitOnly must be boolean\");\n\t\tensure(skill.packages !== null && typeof skill.packages === \"object\", \"packages must be a record\");\n\t\tfor (const [name, versions] of Object.entries(skill.packages)) {\n\t\t\ttext(name, \"package\");\n\t\t\tunique(versions, \"versions\", 128);\n\t\t\tensure(versions.length > 0, \"empty supported versions\");\n\t\t}\n\t\tif (input.approvedHashes[skill.id] !== skill.contentHash) rejected.set(skill.id, \"unapproved-or-changed-content\");\n\t\telse if (!skill.phases.includes(input.phase)) rejected.set(skill.id, \"phase-mismatch\");\n\t\telse if (skill.explicitOnly && !input.explicitSkills.includes(skill.id)) rejected.set(skill.id, \"explicit-only\");\n\t\telse if (skill.permissions.some((permission) => !input.allowedPermissions.includes(permission))) {\n\t\t\trejected.set(skill.id, \"permission-denied\");\n\t\t} else if (\n\t\t\tObject.entries(skill.packages).some(\n\t\t\t\t([name, versions]) => !versions.includes(input.installedVersions[name] ?? \"\"),\n\t\t\t)\n\t\t) {\n\t\t\trejected.set(skill.id, \"version-unknown-or-incompatible\");\n\t\t}\n\t}\n\t// A cycle or unavailable prerequisite invalidates the entire dependent closure.\n\tconst closureCache = new Map<string, Set<string> | undefined>();\n\tconst closure = (id: string, trail = new Set<string>()): Set<string> | undefined => {\n\t\tif (trail.has(id) || rejected.has(id)) return undefined;\n\t\tif (closureCache.has(id)) return closureCache.get(id);\n\t\tconst skill = byId.get(id);\n\t\tif (!skill) return undefined;\n\t\tconst result = new Set([id]);\n\t\tconst next = new Set([...trail, id]);\n\t\tfor (const dependency of skill.dependencies) {\n\t\t\tconst children = closure(dependency, next);\n\t\t\tif (!children) {\n\t\t\t\tclosureCache.set(id, undefined);\n\t\t\t\treturn undefined;\n\t\t\t}\n\t\t\tfor (const child of children) result.add(child);\n\t\t}\n\t\tclosureCache.set(id, result);\n\t\treturn result;\n\t};\n\tconst closures = new Map<string, Set<string>>();\n\tfor (const id of [...byId.keys()].sort(lexical)) {\n\t\tconst set = closure(id);\n\t\tif (set) closures.set(id, set);\n\t\telse if (!rejected.has(id)) rejected.set(id, \"invalid-dependency-closure\");\n\t}\n\tconst feasible = (ids: ReadonlySet<string>): boolean => {\n\t\tif (ids.size > input.maxSkills) return false;\n\t\tlet cost = 0;\n\t\tfor (const id of ids) {\n\t\t\tconst skill = byId.get(id);\n\t\t\tif (!skill || rejected.has(id)) return false;\n\t\t\tif (skill.dependencies.some((d) => !ids.has(d))) return false;\n\t\t\tif (skill.conflicts.some((c) => ids.has(c))) return false;\n\t\t\tcost += skill.tokenCost;\n\t\t}\n\t\treturn cost <= input.tokenBudget;\n\t};\n\tconst value = (ids: ReadonlySet<string>): Value => {\n\t\tconst coverage = new Set<string>();\n\t\tlet cost = 0;\n\t\tfor (const id of ids) {\n\t\t\tconst skill = byId.get(id)!;\n\t\t\tcost += skill.tokenCost;\n\t\t\tfor (const capability of skill.capabilities) coverage.add(capability);\n\t\t}\n\t\tlet required = 0,\n\t\t\toptional = 0;\n\t\tfor (const need of input.needs) {\n\t\t\tif (coverage.has(need.capability)) {\n\t\t\t\tif (need.required) required += need.weight;\n\t\t\t\telse optional += need.weight;\n\t\t\t}\n\t\t}\n\t\treturn { required, optional, cost, ids: [...ids].sort(lexical) };\n\t};\n\tconst better = (left: Value, right: Value): boolean =>\n\t\tleft.required !== right.required\n\t\t\t? left.required > right.required\n\t\t\t: left.optional !== right.optional\n\t\t\t\t? left.optional > right.optional\n\t\t\t\t: left.cost !== right.cost\n\t\t\t\t\t? left.cost < right.cost\n\t\t\t\t\t: left.ids.length !== right.ids.length\n\t\t\t\t\t\t? left.ids.length < right.ids.length\n\t\t\t\t\t\t: lexical(left.ids.join(\"\\0\"), right.ids.join(\"\\0\")) < 0;\n\tlet base = new Set<string>();\n\tconst blockedExplicit: string[] = [];\n\tfor (const id of [...input.explicitSkills].sort(lexical)) {\n\t\tconst set = closures.get(id);\n\t\tif (!set) blockedExplicit.push(id);\n\t\telse for (const item of set) base.add(item);\n\t}\n\tif (!feasible(base)) blockedExplicit.push(...input.explicitSkills.filter((id) => !blockedExplicit.includes(id)));\n\t// Conflicting explicit requests are never silently replaced by automatic picks.\n\tif (blockedExplicit.length > 0) base = new Set();\n\tlet best = base;\n\tconst candidates = [...closures.entries()].filter(([id]) => !base.has(id));\n\tconst algorithm = candidates.length <= 12 ? \"exact-small\" : \"greedy-with-singleton\";\n\tif (blockedExplicit.length === 0) {\n\t\tif (algorithm === \"exact-small\") {\n\t\t\tconst visit = (position: number, current: Set<string>): void => {\n\t\t\t\tif (!feasible(current)) return;\n\t\t\t\tif (better(value(current), value(best))) best = current;\n\t\t\t\tconst candidate = candidates[position];\n\t\t\t\tif (!candidate) return;\n\t\t\t\tvisit(position + 1, current);\n\t\t\t\tvisit(position + 1, new Set([...current, ...candidate[1]]));\n\t\t\t};\n\t\t\tvisit(0, base);\n\t\t} else {\n\t\t\tlet current = base;\n\t\t\twhile (true) {\n\t\t\t\tconst previous = value(current);\n\t\t\t\tlet winner: Set<string> | undefined;\n\t\t\t\tlet rank: readonly [number, number, string] = [-1, -1, \"\"];\n\t\t\t\tfor (const [id, set] of candidates) {\n\t\t\t\t\tif (current.has(id)) continue;\n\t\t\t\t\tconst joined = new Set([...current, ...set]);\n\t\t\t\t\tif (!feasible(joined)) continue;\n\t\t\t\t\tconst after = value(joined);\n\t\t\t\t\tconst requiredGain = after.required - previous.required;\n\t\t\t\t\tconst optionalGain = after.optional - previous.optional;\n\t\t\t\t\tif (requiredGain <= 0 && optionalGain <= 0) continue;\n\t\t\t\t\tconst cost = Math.max(1, after.cost - previous.cost);\n\t\t\t\t\tconst proposal = [requiredGain / cost, optionalGain / cost, id] as const;\n\t\t\t\t\tif (\n\t\t\t\t\t\t!winner ||\n\t\t\t\t\t\tproposal[0] > rank[0] ||\n\t\t\t\t\t\t(proposal[0] === rank[0] &&\n\t\t\t\t\t\t\t(proposal[1] > rank[1] || (proposal[1] === rank[1] && lexical(proposal[2], rank[2]) < 0)))\n\t\t\t\t\t) {\n\t\t\t\t\t\twinner = joined;\n\t\t\t\t\t\trank = proposal;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tif (!winner) break;\n\t\t\t\tcurrent = winner;\n\t\t\t}\n\t\t\tbest = current;\n\t\t\tfor (const [, set] of candidates) {\n\t\t\t\tconst joined = new Set([...base, ...set]);\n\t\t\t\tif (feasible(joined) && better(value(joined), value(best))) best = joined;\n\t\t\t}\n\t\t}\n\t}\n\tconst allCovered = new Set([...best].flatMap((id) => byId.get(id)!.capabilities));\n\tconst uncoveredRequired = input.needs\n\t\t.filter((n) => n.required && !allCovered.has(n.capability))\n\t\t.map((n) => n.capability)\n\t\t.sort(lexical);\n\treturn {\n\t\tselected: [...best].sort(lexical),\n\t\ttokenCost: value(best).cost,\n\t\tcovered: input.needs\n\t\t\t.filter((n) => allCovered.has(n.capability))\n\t\t\t.map((n) => n.capability)\n\t\t\t.sort(lexical),\n\t\tuncoveredRequired,\n\t\tblockedExplicit: blockedExplicit.sort(lexical),\n\t\trejected: Object.fromEntries([...rejected].sort(([a], [b]) => lexical(a, b))),\n\t\talgorithm,\n\t\tstate: blockedExplicit.length ? \"explicit-blocked\" : uncoveredRequired.length ? \"capability-gap\" : \"covered\",\n\t};\n}\n"]}

package/dist/metacognition/state.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Metacognitive state tuple and checkpoint evaluation.
+ * Spec §3: X_t = (G, F, O, E, Z, H, M, V, B, P).
+ *
+ * The tuple is host-owned structured state; the model receives only the
+ * hypotheses, evidence, and questions it needs right now. Recommended
+ * computation unit is a decision checkpoint — before a new external symbol,
+ * after an important change, after a check failure, after verification, after
+ * a source conflict, or when strategy repetition is detected.
+ */
+import type { CalibrationStore } from "./calibration.ts";
+import type { KnowledgeReport } from "./knowledge.ts";
+import type { Obligation } from "./obligations.ts";
+import type { Prediction } from "./predictions.ts";
+import type { VerifierEvaluation } from "./verifier.ts";
+/** G_t: current goal, stage, target artifact. */
+export interface GoalState {
+    readonly taskId: string;
+    readonly stageId: string;
+    readonly targetArtifact: string;
+    readonly goalScope: string;
+}
+/** F_t: observed facts about repository, environment, pinned versions, change scope. */
+export interface FactState {
+    readonly candidateHash: string;
+    readonly environmentHash: string;
+    readonly changeScope: readonly string[];
+    readonly analyzerCoverage: "covered" | "partial" | "unsupported" | "unknown";
+}
+/** E_t: evidence candidates, adopted evidence, checks bound to the current artifact. */
+export interface EvidenceState {
+    readonly report: KnowledgeReport | null;
+    readonly adoptedSourceIds: readonly string[];
+}
+/** H_t: competing cause/design hypotheses and unresolved classification. */
+export interface HypothesisState {
+    readonly open: readonly string[];
+    readonly discriminatorCandidates: readonly string[];
+    readonly modelMismatch: boolean;
+}
+/** V_t: verifier detection coverage, known blind spots, runner health. */
+export interface VerifierState {
+    readonly evaluations: readonly VerifierEvaluation[];
+    readonly runnerHealth: "healthy" | "degraded" | "unverified";
+}
+/** B_t: remaining time, requests, tokens, concurrency budget. */
+export interface BudgetState {
+    readonly remainingMs: number;
+    readonly remainingRequests: number;
+    readonly remainingTokens: number;
+    readonly remainingConcurrent: number;
+}
+/** P_t: host-owned authorization, verification, interruption policy. */
+export interface PolicyState {
+    readonly policyVersion: string;
+    readonly authorizedActions: readonly string[];
+    readonly requiredApprovals: readonly string[];
+    readonly interruptionReason: string | null;
+}
+/** Z_t: predictions registered before execution and post-execution mismatches. */
+export type PredictionState = readonly Prediction[];
+/** O_t: premises and completion obligations, plus unverified candidate duties. */
+export type ObligationState = readonly Obligation[];
+/** M_t: conditional performance and calibration records. */
+export type CalibrationState = CalibrationStore;
+export interface MetaState {
+    readonly goal: GoalState;
+    readonly facts: FactState;
+    readonly obligations: ObligationState;
+    readonly evidence: EvidenceState;
+    readonly predictions: PredictionState;
+    readonly hypotheses: HypothesisState;
+    readonly calibration: CalibrationState;
+    readonly verifier: VerifierState;
+    readonly budget: BudgetState;
+    readonly policy: PolicyState;
+    readonly hostSequence: number;
+    readonly progressHistory: readonly {
+        key: string;
+        newEvidence: boolean;
+        resolvedObligations: number;
+        newValidChecks: number;
+    }[];
+    readonly checkpointCount: number;
+}
+export declare function validateMetaState(state: MetaState): void;
+/** Finish states per §9.5: continue, verified-bounded completion, inconclusive stop. */
+export type FinishState = {
+    readonly kind: "continue";
+} | {
+    readonly kind: "verified-completion";
+    readonly receiptId: string;
+    readonly scope: string;
+} | {
+    readonly kind: "inconclusive";
+    readonly reason: string;
+};
+/**
+ * §9.5: a VOI of zero never implies verified completion. Completion requires
+ * required obligations satisfied AND an approved completion receipt bound to
+ * the current candidate.
+ */
+export declare function finishState(state: MetaState, receipt: {
+    receiptId: string;
+    candidateHash: string;
+    scope: string;
+} | null): FinishState;
+/** Fingerprint of the full state for checkpoint diffs and receipts. */
+export declare function stateFingerprint(state: MetaState): string;
+//# sourceMappingURL=state.d.ts.map

package/dist/metacognition/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/metacognition/state.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Metacognitive state tuple and checkpoint evaluation.\n * Spec §3: X_t = (G, F, O, E, Z, H, M, V, B, P).\n *\n * The tuple is host-owned structured state; the model receives only the\n * hypotheses, evidence, and questions it needs right now. Recommended\n * computation unit is a decision checkpoint — before a new external symbol,\n * after an important change, after a check failure, after verification, after\n * a source conflict, or when strategy repetition is detected.\n */\nimport type { CalibrationStore } from \"./calibration.ts\";\nimport type { KnowledgeReport } from \"./knowledge.ts\";\nimport type { Obligation } from \"./obligations.ts\";\nimport type { Prediction } from \"./predictions.ts\";\nimport { canonical, ensure, integer, member, text } from \"./validation.ts\";\nimport type { VerifierEvaluation } from \"./verifier.ts\";\n\n/** G_t: current goal, stage, target artifact. */\nexport interface GoalState {\n\treadonly taskId: string;\n\treadonly stageId: string;\n\treadonly targetArtifact: string;\n\treadonly goalScope: string;\n}\n/** F_t: observed facts about repository, environment, pinned versions, change scope. */\nexport interface FactState {\n\treadonly candidateHash: string;\n\treadonly environmentHash: string;\n\treadonly changeScope: readonly string[];\n\treadonly analyzerCoverage: \"covered\" | \"partial\" | \"unsupported\" | \"unknown\";\n}\n/** E_t: evidence candidates, adopted evidence, checks bound to the current artifact. */\nexport interface EvidenceState {\n\treadonly report: KnowledgeReport | null;\n\treadonly adoptedSourceIds: readonly string[];\n}\n/** H_t: competing cause/design hypotheses and unresolved classification. */\nexport interface HypothesisState {\n\treadonly open: readonly string[];\n\treadonly discriminatorCandidates: readonly string[];\n\treadonly modelMismatch: boolean;\n}\n/** V_t: verifier detection coverage, known blind spots, runner health. */\nexport interface VerifierState {\n\treadonly evaluations: readonly VerifierEvaluation[];\n\treadonly runnerHealth: \"healthy\" | \"degraded\" | \"unverified\";\n}\n/** B_t: remaining time, requests, tokens, concurrency budget. */\nexport interface BudgetState {\n\treadonly remainingMs: number;\n\treadonly remainingRequests: number;\n\treadonly remainingTokens: number;\n\treadonly remainingConcurrent: number;\n}\n/** P_t: host-owned authorization, verification, interruption policy. */\nexport interface PolicyState {\n\treadonly policyVersion: string;\n\treadonly authorizedActions: readonly string[];\n\treadonly requiredApprovals: readonly string[];\n\treadonly interruptionReason: string | null;\n}\n/** Z_t: predictions registered before execution and post-execution mismatches. */\nexport type PredictionState = readonly Prediction[];\n/** O_t: premises and completion obligations, plus unverified candidate duties. */\nexport type ObligationState = readonly Obligation[];\n/** M_t: conditional performance and calibration records. */\nexport type CalibrationState = CalibrationStore;\n\nexport interface MetaState {\n\treadonly goal: GoalState;\n\treadonly facts: FactState;\n\treadonly obligations: ObligationState;\n\treadonly evidence: EvidenceState;\n\treadonly predictions: PredictionState;\n\treadonly hypotheses: HypothesisState;\n\treadonly calibration: CalibrationState;\n\treadonly verifier: VerifierState;\n\treadonly budget: BudgetState;\n\treadonly policy: PolicyState;\n\treadonly hostSequence: number;\n\treadonly progressHistory: readonly {\n\t\tkey: string;\n\t\tnewEvidence: boolean;\n\t\tresolvedObligations: number;\n\t\tnewValidChecks: number;\n\t}[];\n\treadonly checkpointCount: number;\n}\n\nexport function validateMetaState(state: MetaState): void {\n\ttext(state.goal.taskId, \"taskId\", 128);\n\ttext(state.goal.stageId, \"stageId\", 128);\n\ttext(state.goal.targetArtifact, \"targetArtifact\", 512);\n\ttext(state.goal.goalScope, \"goalScope\", 256);\n\ttext(state.facts.candidateHash, \"candidateHash\", 128);\n\ttext(state.facts.environmentHash, \"environmentHash\", 128);\n\tmember(state.facts.analyzerCoverage, [\"covered\", \"partial\", \"unsupported\", \"unknown\"], \"analyzerCoverage\");\n\tmember(state.verifier.runnerHealth, [\"healthy\", \"degraded\", \"unverified\"], \"runnerHealth\");\n\ttext(state.policy.policyVersion, \"policyVersion\", 64);\n\tinteger(state.budget.remainingMs, \"remainingMs\");\n\tinteger(state.budget.remainingRequests, \"remainingRequests\");\n\tinteger(state.budget.remainingTokens, \"remainingTokens\");\n\tinteger(state.budget.remainingConcurrent, \"remainingConcurrent\");\n\tinteger(state.hostSequence, \"hostSequence\");\n\tinteger(state.checkpointCount, \"checkpointCount\");\n}\n\n/** Finish states per §9.5: continue, verified-bounded completion, inconclusive stop. */\nexport type FinishState =\n\t| { readonly kind: \"continue\" }\n\t| { readonly kind: \"verified-completion\"; readonly receiptId: string; readonly scope: string }\n\t| { readonly kind: \"inconclusive\"; readonly reason: string };\n\n/**\n * §9.5: a VOI of zero never implies verified completion. Completion requires\n * required obligations satisfied AND an approved completion receipt bound to\n * the current candidate.\n */\nexport function finishState(\n\tstate: MetaState,\n\treceipt: { receiptId: string; candidateHash: string; scope: string } | null,\n): FinishState {\n\tconst openRequired = state.obligations.filter((o) => o.status === \"required\" || o.status === \"violated\");\n\tif (receipt !== null) {\n\t\tensure(receipt.candidateHash === state.facts.candidateHash, \"receipt candidate binding mismatch\");\n\t\tif (openRequired.length === 0) {\n\t\t\treturn { kind: \"verified-completion\", receiptId: receipt.receiptId, scope: receipt.scope };\n\t\t}\n\t}\n\tif (openRequired.length > 0) {\n\t\treturn { kind: \"inconclusive\", reason: `unresolved-obligations:${openRequired.length}` };\n\t}\n\tif (state.budget.remainingMs === 0 || state.budget.remainingRequests === 0) {\n\t\treturn { kind: \"inconclusive\", reason: \"budget-exhausted\" };\n\t}\n\treturn { kind: \"continue\" };\n}\n\n/** Fingerprint of the full state for checkpoint diffs and receipts. */\nexport function stateFingerprint(state: MetaState): string {\n\treturn canonical([\n\t\tstate.goal.taskId,\n\t\tstate.goal.stageId,\n\t\tstate.facts.candidateHash,\n\t\tstate.facts.environmentHash,\n\t\tstate.policy.policyVersion,\n\t\tstate.obligations.map((o) => [o.id, o.status]),\n\t\tstate.predictions.map((p) => [p.predictionId, p.status]),\n\t]);\n}\n"]}

package/dist/metacognition/state.js

@@ -0,0 +1,52 @@
+import { canonical, ensure, integer, member, text } from "./validation.js";
+export function validateMetaState(state) {
+    text(state.goal.taskId, "taskId", 128);
+    text(state.goal.stageId, "stageId", 128);
+    text(state.goal.targetArtifact, "targetArtifact", 512);
+    text(state.goal.goalScope, "goalScope", 256);
+    text(state.facts.candidateHash, "candidateHash", 128);
+    text(state.facts.environmentHash, "environmentHash", 128);
+    member(state.facts.analyzerCoverage, ["covered", "partial", "unsupported", "unknown"], "analyzerCoverage");
+    member(state.verifier.runnerHealth, ["healthy", "degraded", "unverified"], "runnerHealth");
+    text(state.policy.policyVersion, "policyVersion", 64);
+    integer(state.budget.remainingMs, "remainingMs");
+    integer(state.budget.remainingRequests, "remainingRequests");
+    integer(state.budget.remainingTokens, "remainingTokens");
+    integer(state.budget.remainingConcurrent, "remainingConcurrent");
+    integer(state.hostSequence, "hostSequence");
+    integer(state.checkpointCount, "checkpointCount");
+}
+/**
+ * §9.5: a VOI of zero never implies verified completion. Completion requires
+ * required obligations satisfied AND an approved completion receipt bound to
+ * the current candidate.
+ */
+export function finishState(state, receipt) {
+    const openRequired = state.obligations.filter((o) => o.status === "required" || o.status === "violated");
+    if (receipt !== null) {
+        ensure(receipt.candidateHash === state.facts.candidateHash, "receipt candidate binding mismatch");
+        if (openRequired.length === 0) {
+            return { kind: "verified-completion", receiptId: receipt.receiptId, scope: receipt.scope };
+        }
+    }
+    if (openRequired.length > 0) {
+        return { kind: "inconclusive", reason: `unresolved-obligations:${openRequired.length}` };
+    }
+    if (state.budget.remainingMs === 0 || state.budget.remainingRequests === 0) {
+        return { kind: "inconclusive", reason: "budget-exhausted" };
+    }
+    return { kind: "continue" };
+}
+/** Fingerprint of the full state for checkpoint diffs and receipts. */
+export function stateFingerprint(state) {
+    return canonical([
+        state.goal.taskId,
+        state.goal.stageId,
+        state.facts.candidateHash,
+        state.facts.environmentHash,
+        state.policy.policyVersion,
+        state.obligations.map((o) => [o.id, o.status]),
+        state.predictions.map((p) => [p.predictionId, p.status]),
+    ]);
+}
+//# sourceMappingURL=state.js.map

package/dist/metacognition/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/metacognition/state.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Metacognitive state tuple and checkpoint evaluation.\n * Spec §3: X_t = (G, F, O, E, Z, H, M, V, B, P).\n *\n * The tuple is host-owned structured state; the model receives only the\n * hypotheses, evidence, and questions it needs right now. Recommended\n * computation unit is a decision checkpoint — before a new external symbol,\n * after an important change, after a check failure, after verification, after\n * a source conflict, or when strategy repetition is detected.\n */\nimport type { CalibrationStore } from \"./calibration.ts\";\nimport type { KnowledgeReport } from \"./knowledge.ts\";\nimport type { Obligation } from \"./obligations.ts\";\nimport type { Prediction } from \"./predictions.ts\";\nimport { canonical, ensure, integer, member, text } from \"./validation.ts\";\nimport type { VerifierEvaluation } from \"./verifier.ts\";\n\n/** G_t: current goal, stage, target artifact. */\nexport interface GoalState {\n\treadonly taskId: string;\n\treadonly stageId: string;\n\treadonly targetArtifact: string;\n\treadonly goalScope: string;\n}\n/** F_t: observed facts about repository, environment, pinned versions, change scope. */\nexport interface FactState {\n\treadonly candidateHash: string;\n\treadonly environmentHash: string;\n\treadonly changeScope: readonly string[];\n\treadonly analyzerCoverage: \"covered\" | \"partial\" | \"unsupported\" | \"unknown\";\n}\n/** E_t: evidence candidates, adopted evidence, checks bound to the current artifact. */\nexport interface EvidenceState {\n\treadonly report: KnowledgeReport | null;\n\treadonly adoptedSourceIds: readonly string[];\n}\n/** H_t: competing cause/design hypotheses and unresolved classification. */\nexport interface HypothesisState {\n\treadonly open: readonly string[];\n\treadonly discriminatorCandidates: readonly string[];\n\treadonly modelMismatch: boolean;\n}\n/** V_t: verifier detection coverage, known blind spots, runner health. */\nexport interface VerifierState {\n\treadonly evaluations: readonly VerifierEvaluation[];\n\treadonly runnerHealth: \"healthy\" | \"degraded\" | \"unverified\";\n}\n/** B_t: remaining time, requests, tokens, concurrency budget. */\nexport interface BudgetState {\n\treadonly remainingMs: number;\n\treadonly remainingRequests: number;\n\treadonly remainingTokens: number;\n\treadonly remainingConcurrent: number;\n}\n/** P_t: host-owned authorization, verification, interruption policy. */\nexport interface PolicyState {\n\treadonly policyVersion: string;\n\treadonly authorizedActions: readonly string[];\n\treadonly requiredApprovals: readonly string[];\n\treadonly interruptionReason: string | null;\n}\n/** Z_t: predictions registered before execution and post-execution mismatches. */\nexport type PredictionState = readonly Prediction[];\n/** O_t: premises and completion obligations, plus unverified candidate duties. */\nexport type ObligationState = readonly Obligation[];\n/** M_t: conditional performance and calibration records. */\nexport type CalibrationState = CalibrationStore;\n\nexport interface MetaState {\n\treadonly goal: GoalState;\n\treadonly facts: FactState;\n\treadonly obligations: ObligationState;\n\treadonly evidence: EvidenceState;\n\treadonly predictions: PredictionState;\n\treadonly hypotheses: HypothesisState;\n\treadonly calibration: CalibrationState;\n\treadonly verifier: VerifierState;\n\treadonly budget: BudgetState;\n\treadonly policy: PolicyState;\n\treadonly hostSequence: number;\n\treadonly progressHistory: readonly {\n\t\tkey: string;\n\t\tnewEvidence: boolean;\n\t\tresolvedObligations: number;\n\t\tnewValidChecks: number;\n\t}[];\n\treadonly checkpointCount: number;\n}\n\nexport function validateMetaState(state: MetaState): void {\n\ttext(state.goal.taskId, \"taskId\", 128);\n\ttext(state.goal.stageId, \"stageId\", 128);\n\ttext(state.goal.targetArtifact, \"targetArtifact\", 512);\n\ttext(state.goal.goalScope, \"goalScope\", 256);\n\ttext(state.facts.candidateHash, \"candidateHash\", 128);\n\ttext(state.facts.environmentHash, \"environmentHash\", 128);\n\tmember(state.facts.analyzerCoverage, [\"covered\", \"partial\", \"unsupported\", \"unknown\"], \"analyzerCoverage\");\n\tmember(state.verifier.runnerHealth, [\"healthy\", \"degraded\", \"unverified\"], \"runnerHealth\");\n\ttext(state.policy.policyVersion, \"policyVersion\", 64);\n\tinteger(state.budget.remainingMs, \"remainingMs\");\n\tinteger(state.budget.remainingRequests, \"remainingRequests\");\n\tinteger(state.budget.remainingTokens, \"remainingTokens\");\n\tinteger(state.budget.remainingConcurrent, \"remainingConcurrent\");\n\tinteger(state.hostSequence, \"hostSequence\");\n\tinteger(state.checkpointCount, \"checkpointCount\");\n}\n\n/** Finish states per §9.5: continue, verified-bounded completion, inconclusive stop. */\nexport type FinishState =\n\t| { readonly kind: \"continue\" }\n\t| { readonly kind: \"verified-completion\"; readonly receiptId: string; readonly scope: string }\n\t| { readonly kind: \"inconclusive\"; readonly reason: string };\n\n/**\n * §9.5: a VOI of zero never implies verified completion. Completion requires\n * required obligations satisfied AND an approved completion receipt bound to\n * the current candidate.\n */\nexport function finishState(\n\tstate: MetaState,\n\treceipt: { receiptId: string; candidateHash: string; scope: string } | null,\n): FinishState {\n\tconst openRequired = state.obligations.filter((o) => o.status === \"required\" || o.status === \"violated\");\n\tif (receipt !== null) {\n\t\tensure(receipt.candidateHash === state.facts.candidateHash, \"receipt candidate binding mismatch\");\n\t\tif (openRequired.length === 0) {\n\t\t\treturn { kind: \"verified-completion\", receiptId: receipt.receiptId, scope: receipt.scope };\n\t\t}\n\t}\n\tif (openRequired.length > 0) {\n\t\treturn { kind: \"inconclusive\", reason: `unresolved-obligations:${openRequired.length}` };\n\t}\n\tif (state.budget.remainingMs === 0 || state.budget.remainingRequests === 0) {\n\t\treturn { kind: \"inconclusive\", reason: \"budget-exhausted\" };\n\t}\n\treturn { kind: \"continue\" };\n}\n\n/** Fingerprint of the full state for checkpoint diffs and receipts. */\nexport function stateFingerprint(state: MetaState): string {\n\treturn canonical([\n\t\tstate.goal.taskId,\n\t\tstate.goal.stageId,\n\t\tstate.facts.candidateHash,\n\t\tstate.facts.environmentHash,\n\t\tstate.policy.policyVersion,\n\t\tstate.obligations.map((o) => [o.id, o.status]),\n\t\tstate.predictions.map((p) => [p.predictionId, p.status]),\n\t]);\n}\n"]}

package/dist/metacognition/validation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Input-validation primitives for the metacognition kernel.
+ *
+ * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip
+ * (src/validation.ts). Deterministic, allocation-bounded, no I/O.
+ */
+export declare function ensure(condition: unknown, message: string): asserts condition;
+export declare function integer(value: number, label: string, max?: number): void;
+export declare function finite(value: number, label: string, max?: number): void;
+export declare function probability(value: number, label: string): void;
+export declare function text(value: string, label: string, max?: number): void;
+export declare function unique(values: readonly string[], label: string, max?: number): void;
+export declare function member<T extends string>(value: T, values: readonly T[] | readonly string[], label: string): void;
+export declare function lexical(a: string, b: string): number;
+export declare function canonical(value: unknown): string;
+export declare function arrayBound(value: unknown, label: string, max: number): void;
+/** Probability vector: finite, [0,1], sums to 1. Mirrors check_examples.py. */
+export declare function probabilityVector(values: readonly number[], label: string): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/metacognition/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/metacognition/validation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAE7E;AACD,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAA0B,GAAG,IAAI,CAEzF;AACD,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAAmB,GAAG,IAAI,CAKjF;AACD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAK9D;AACD,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAAO,GAAG,IAAI,CAEnE;AACD,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAAM,GAAG,IAAI,CAIhF;AACD,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,GAAG,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAEhH;AACD,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpD;AACD,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUhD;AACD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAE3E;AACD,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIhF","sourcesContent":["/**\n * Input-validation primitives for the metacognition kernel.\n *\n * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip\n * (src/validation.ts). Deterministic, allocation-bounded, no I/O.\n */\nexport function ensure(condition: unknown, message: string): asserts condition {\n\tif (!condition) throw new TypeError(message);\n}\nexport function integer(value: number, label: string, max = Number.MAX_SAFE_INTEGER): void {\n\tensure(Number.isSafeInteger(value) && value >= 0 && value <= max, `${label}: expected integer in [0, ${max}]`);\n}\nexport function finite(value: number, label: string, max = Number.MAX_VALUE): void {\n\tensure(\n\t\ttypeof value === \"number\" && Number.isFinite(value) && value >= 0 && value <= max,\n\t\t`${label}: expected finite number in [0, ${max}]`,\n\t);\n}\nexport function probability(value: number, label: string): void {\n\tensure(\n\t\ttypeof value === \"number\" && Number.isFinite(value) && value >= 0 && value <= 1,\n\t\t`${label}: expected probability in [0, 1]`,\n\t);\n}\nexport function text(value: string, label: string, max = 4096): void {\n\tensure(typeof value === \"string\" && value.trim().length > 0 && value.length <= max, `${label}: invalid string`);\n}\nexport function unique(values: readonly string[], label: string, max = 500): void {\n\tensure(Array.isArray(values) && values.length <= max, `${label}: invalid array`);\n\tfor (const value of values) text(value, label, 500);\n\tensure(new Set(values).size === values.length, `${label}: duplicate identifier`);\n}\nexport function member<T extends string>(value: T, values: readonly T[] | readonly string[], label: string): void {\n\tensure(values.includes(value), `${label}: invalid enum`);\n}\nexport function lexical(a: string, b: string): number {\n\treturn a < b ? -1 : a > b ? 1 : 0;\n}\nexport function canonical(value: unknown): string {\n\tif (value === undefined) return '\"__undefined__\"';\n\tif (Array.isArray(value)) return `[${value.map(canonical).join(\",\")}]`;\n\tif (value !== null && typeof value === \"object\") {\n\t\treturn `{${Object.entries(value)\n\t\t\t.sort(([a], [b]) => lexical(a, b))\n\t\t\t.map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)\n\t\t\t.join(\",\")}}`;\n\t}\n\treturn JSON.stringify(value);\n}\nexport function arrayBound(value: unknown, label: string, max: number): void {\n\tensure(Array.isArray(value) && value.length <= max, `${label}: invalid array`);\n}\n/** Probability vector: finite, [0,1], sums to 1. Mirrors check_examples.py. */\nexport function probabilityVector(values: readonly number[], label: string): void {\n\tensure(values.length > 0, `${label}: empty probability vector`);\n\tfor (const v of values) probability(v, label);\n\tensure(Math.abs(values.reduce((a, b) => a + b, 0) - 1) <= 1e-9, `${label}: probabilities must sum to one`);\n}\n"]}

package/dist/metacognition/validation.js

@@ -0,0 +1,58 @@
+/**
+ * Input-validation primitives for the metacognition kernel.
+ *
+ * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip
+ * (src/validation.ts). Deterministic, allocation-bounded, no I/O.
+ */
+export function ensure(condition, message) {
+    if (!condition)
+        throw new TypeError(message);
+}
+export function integer(value, label, max = Number.MAX_SAFE_INTEGER) {
+    ensure(Number.isSafeInteger(value) && value >= 0 && value <= max, `${label}: expected integer in [0, ${max}]`);
+}
+export function finite(value, label, max = Number.MAX_VALUE) {
+    ensure(typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= max, `${label}: expected finite number in [0, ${max}]`);
+}
+export function probability(value, label) {
+    ensure(typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1, `${label}: expected probability in [0, 1]`);
+}
+export function text(value, label, max = 4096) {
+    ensure(typeof value === "string" && value.trim().length > 0 && value.length <= max, `${label}: invalid string`);
+}
+export function unique(values, label, max = 500) {
+    ensure(Array.isArray(values) && values.length <= max, `${label}: invalid array`);
+    for (const value of values)
+        text(value, label, 500);
+    ensure(new Set(values).size === values.length, `${label}: duplicate identifier`);
+}
+export function member(value, values, label) {
+    ensure(values.includes(value), `${label}: invalid enum`);
+}
+export function lexical(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+export function canonical(value) {
+    if (value === undefined)
+        return '"__undefined__"';
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => lexical(a, b))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+export function arrayBound(value, label, max) {
+    ensure(Array.isArray(value) && value.length <= max, `${label}: invalid array`);
+}
+/** Probability vector: finite, [0,1], sums to 1. Mirrors check_examples.py. */
+export function probabilityVector(values, label) {
+    ensure(values.length > 0, `${label}: empty probability vector`);
+    for (const v of values)
+        probability(v, label);
+    ensure(Math.abs(values.reduce((a, b) => a + b, 0) - 1) <= 1e-9, `${label}: probabilities must sum to one`);
+}
+//# sourceMappingURL=validation.js.map

package/dist/metacognition/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/metacognition/validation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Input-validation primitives for the metacognition kernel.\n *\n * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip\n * (src/validation.ts). Deterministic, allocation-bounded, no I/O.\n */\nexport function ensure(condition: unknown, message: string): asserts condition {\n\tif (!condition) throw new TypeError(message);\n}\nexport function integer(value: number, label: string, max = Number.MAX_SAFE_INTEGER): void {\n\tensure(Number.isSafeInteger(value) && value >= 0 && value <= max, `${label}: expected integer in [0, ${max}]`);\n}\nexport function finite(value: number, label: string, max = Number.MAX_VALUE): void {\n\tensure(\n\t\ttypeof value === \"number\" && Number.isFinite(value) && value >= 0 && value <= max,\n\t\t`${label}: expected finite number in [0, ${max}]`,\n\t);\n}\nexport function probability(value: number, label: string): void {\n\tensure(\n\t\ttypeof value === \"number\" && Number.isFinite(value) && value >= 0 && value <= 1,\n\t\t`${label}: expected probability in [0, 1]`,\n\t);\n}\nexport function text(value: string, label: string, max = 4096): void {\n\tensure(typeof value === \"string\" && value.trim().length > 0 && value.length <= max, `${label}: invalid string`);\n}\nexport function unique(values: readonly string[], label: string, max = 500): void {\n\tensure(Array.isArray(values) && values.length <= max, `${label}: invalid array`);\n\tfor (const value of values) text(value, label, 500);\n\tensure(new Set(values).size === values.length, `${label}: duplicate identifier`);\n}\nexport function member<T extends string>(value: T, values: readonly T[] | readonly string[], label: string): void {\n\tensure(values.includes(value), `${label}: invalid enum`);\n}\nexport function lexical(a: string, b: string): number {\n\treturn a < b ? -1 : a > b ? 1 : 0;\n}\nexport function canonical(value: unknown): string {\n\tif (value === undefined) return '\"__undefined__\"';\n\tif (Array.isArray(value)) return `[${value.map(canonical).join(\",\")}]`;\n\tif (value !== null && typeof value === \"object\") {\n\t\treturn `{${Object.entries(value)\n\t\t\t.sort(([a], [b]) => lexical(a, b))\n\t\t\t.map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)\n\t\t\t.join(\",\")}}`;\n\t}\n\treturn JSON.stringify(value);\n}\nexport function arrayBound(value: unknown, label: string, max: number): void {\n\tensure(Array.isArray(value) && value.length <= max, `${label}: invalid array`);\n}\n/** Probability vector: finite, [0,1], sums to 1. Mirrors check_examples.py. */\nexport function probabilityVector(values: readonly number[], label: string): void {\n\tensure(values.length > 0, `${label}: empty probability vector`);\n\tfor (const v of values) probability(v, label);\n\tensure(Math.abs(values.reduce((a, b) => a + b, 0) - 1) <= 1e-9, `${label}: probabilities must sum to one`);\n}\n"]}