open-multi-agent-kit 1.0.0 → 1.2.0

package/dist/metacognition/runtime-bridge.js

@@ -0,0 +1,140 @@
+import { createCalibrationStore } from "./calibration.js";
+import { ensure, integer, lexical, member, text } from "./validation.js";
+const ISO_MS = (iso) => {
+    const ms = Date.parse(iso);
+    ensure(Number.isFinite(ms), `invalid ISO timestamp: ${iso}`);
+    return ms;
+};
+/** ClaimNode → kernel Claim. Severity maps to impact; leaves keep their check demands. */
+export function toKernelClaim(node, stage, binding) {
+    text(node.claimId, "claimId", 256);
+    text(node.statement, "statement", 2048);
+    member(stage, ["before-change", "after-change"], "stage");
+    let impact = 100;
+    if (node.kind === "safety")
+        impact = 1_000;
+    else if (node.severity === "required")
+        impact = 500;
+    return {
+        id: node.claimId,
+        binding,
+        phase: node.kind === "requirement" || node.kind === "safety" ? "precondition" : "postcondition",
+        statement: node.statement,
+        required: node.severity === "required",
+        impact,
+        needsReference: false,
+        requiresVersion: false,
+        version: null,
+        minSourceFamilies: node.requiredWitnesses ?? 1,
+        requiredCheckIds: node.invalidationKeys,
+        needsUserDecision: node.trustFloor === "model_narrative",
+        publicQuery: null,
+    };
+}
+/** ObservationNode → kernel observation. Trust floor rank maps to source admissibility. */
+export function toKernelObservation(node, binding, nowMs, claimById) {
+    text(node.observationId, "observationId", 256);
+    text(binding, "binding", 512);
+    integer(nowMs, "nowMs");
+    const observedAtMs = nowMs;
+    const expiresAtMs = node.validUntil !== undefined ? ISO_MS(node.validUntil) : nowMs + 1;
+    const claimId = node.claimIds[0] ?? "";
+    const base = { id: node.observationId, claimId, binding, observedAtMs, expiresAtMs };
+    if (node.receiptId !== undefined) {
+        // checkId is the claim's required check predicate (its invalidation key),
+        // not the receipt id — receipts are evidence artifacts, checkIds are obligations.
+        const checkId = claimById?.get(claimId)?.requiredCheckIds[0] ?? node.receiptId;
+        return {
+            ...base,
+            kind: "check",
+            runnerId: node.source,
+            checkId,
+            sequence: 0,
+            verdict: node.polarity === "supports" ? "pass" : "fail",
+        };
+    }
+    if (node.source === "model_narrative") {
+        return { ...base, kind: "decision", actorId: "model", accepted: node.polarity === "supports" };
+    }
+    return {
+        ...base,
+        kind: "reference",
+        sourceId: node.source,
+        version: null,
+        stance: node.polarity === "supports" ? "support" : "refute",
+        documentDigest: node.environmentDigest,
+        locator: node.sourceRoot,
+    };
+}
+/** Build kernel inputs plus a MetaState for one safe checkpoint. Host-owned inputs only. */
+export function toMetaState(input) {
+    text(input.taskId, "taskId", 128);
+    text(input.stageId, "stageId", 128);
+    text(input.goalScope, "goalScope", 256);
+    text(input.targetArtifact, "targetArtifact", 512);
+    text(input.candidateHash, "candidateHash", 128);
+    text(input.environmentHash, "environmentHash", 128);
+    text(input.policyVersion, "policyVersion", 64);
+    text(input.modelRevision, "modelRevision", 128);
+    integer(input.nowMs, "nowMs");
+    ensure(input.claims.length <= 128 && input.observations.length <= 4096, "runtime bridge input too large");
+    // Only leaf claims map to kernel claims — compound satisfaction is the
+    // protocol layer's job, not a kernel evidence predicate.
+    const binding = `${input.candidateHash}@${input.environmentHash}`;
+    const leafClaims = input.claims.filter((c) => c.satisfaction.inputs.length === 0);
+    const claimById = new Map(leafClaims.map((c) => [c.claimId, toKernelClaim(c, input.stage, binding)]));
+    const kernelClaims = [...claimById.values()].sort((a, b) => lexical(a.id, b.id));
+    const kernelObservations = input.observations.map((o) => toKernelObservation(o, binding, input.nowMs, claimById));
+    const state = {
+        goal: {
+            taskId: input.taskId,
+            stageId: input.stageId,
+            targetArtifact: input.targetArtifact,
+            goalScope: input.goalScope,
+        },
+        facts: {
+            candidateHash: input.candidateHash,
+            environmentHash: input.environmentHash,
+            changeScope: [input.targetArtifact],
+            analyzerCoverage: "unknown",
+        },
+        obligations: [],
+        evidence: { report: null, adoptedSourceIds: [] },
+        predictions: [],
+        hypotheses: { open: [], discriminatorCandidates: [], modelMismatch: false },
+        calibration: createCalibrationStore({
+            minSamples: 5,
+            priorAlpha: 1,
+            priorBeta: 1,
+            referenceMean: 0.3,
+            slack: 0.15,
+            threshold: 3,
+        }),
+        verifier: { evaluations: [], runnerHealth: "unverified" },
+        budget: input.budget,
+        policy: {
+            policyVersion: input.policyVersion,
+            authorizedActions: input.authorizedActions,
+            requiredApprovals: [],
+            interruptionReason: input.interruptionReason ?? null,
+        },
+        hostSequence: 0,
+        progressHistory: input.progressHistory ?? [],
+        checkpointCount: 0,
+    };
+    return { state, claims: kernelClaims, observations: kernelObservations };
+}
+/** Sources admitted for reference evidence: only repository/official qualify. */
+export function sourceIdentities(overrides = []) {
+    return [
+        { id: "deterministic_validator", family: "host", kind: "repository" },
+        { id: "workspace_witness", family: "host", kind: "repository" },
+        { id: "trusted_attestation", family: "attestation", kind: "official" },
+        { id: "effect_reconciliation", family: "host", kind: "repository" },
+        { id: "independent_review", family: "review", kind: "official" },
+        { id: "self_review", family: "model", kind: "model" },
+        { id: "model_narrative", family: "model", kind: "model" },
+        ...overrides,
+    ];
+}
+//# sourceMappingURL=runtime-bridge.js.map

package/dist/metacognition/runtime-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-bridge.js","sourceRoot":"","sources":["../../src/metacognition/runtime-bridge.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runtime bridge — §13 \"기존 완료 판정 호출부\": projects host-owned OMK\n * runtime artifacts (protocol ClaimGraph claims, ObservationNodes, waiver\n * records, workspace/session facts) onto the metacognition kernel's input\n * types. It only translates; it never relaxes trust floors, never admits a\n * model's JSON as runner truth, and never fabricates completion.\n */\nimport type { ClaimNode, ObservationNode } from \"omk-protocol\";\nimport { createCalibrationStore } from \"./calibration.ts\";\nimport type {\n\tCheckObservation,\n\tClaim,\n\tDecisionObservation,\n\tReferenceObservation,\n\tSourceIdentity,\n\tStage,\n} from \"./knowledge.ts\";\nimport type { MetaState } from \"./state.ts\";\nimport { ensure, integer, lexical, member, text } from \"./validation.ts\";\n\nconst ISO_MS = (iso: string): number => {\n\tconst ms = Date.parse(iso);\n\tensure(Number.isFinite(ms), `invalid ISO timestamp: ${iso}`);\n\treturn ms;\n};\n\n/** ClaimNode → kernel Claim. Severity maps to impact; leaves keep their check demands. */\nexport function toKernelClaim(node: ClaimNode, stage: Stage, binding: string): Claim {\n\ttext(node.claimId, \"claimId\", 256);\n\ttext(node.statement, \"statement\", 2048);\n\tmember(stage, [\"before-change\", \"after-change\"], \"stage\");\n\tlet impact = 100;\n\tif (node.kind === \"safety\") impact = 1_000;\n\telse if (node.severity === \"required\") impact = 500;\n\treturn {\n\t\tid: node.claimId,\n\t\tbinding,\n\t\tphase: node.kind === \"requirement\" || node.kind === \"safety\" ? \"precondition\" : \"postcondition\",\n\t\tstatement: node.statement,\n\t\trequired: node.severity === \"required\",\n\t\timpact,\n\t\tneedsReference: false,\n\t\trequiresVersion: false,\n\t\tversion: null,\n\t\tminSourceFamilies: node.requiredWitnesses ?? 1,\n\t\trequiredCheckIds: node.invalidationKeys,\n\t\tneedsUserDecision: node.trustFloor === \"model_narrative\",\n\t\tpublicQuery: null,\n\t};\n}\n\n/** ObservationNode → kernel observation. Trust floor rank maps to source admissibility. */\nexport function toKernelObservation(\n\tnode: ObservationNode,\n\tbinding: string,\n\tnowMs: number,\n\tclaimById?: ReadonlyMap<string, Claim>,\n): CheckObservation | ReferenceObservation | DecisionObservation {\n\ttext(node.observationId, \"observationId\", 256);\n\ttext(binding, \"binding\", 512);\n\tinteger(nowMs, \"nowMs\");\n\tconst observedAtMs = nowMs;\n\tconst expiresAtMs = node.validUntil !== undefined ? ISO_MS(node.validUntil) : nowMs + 1;\n\tconst claimId = node.claimIds[0] ?? \"\";\n\tconst base = { id: node.observationId, claimId, binding, observedAtMs, expiresAtMs };\n\tif (node.receiptId !== undefined) {\n\t\t// checkId is the claim's required check predicate (its invalidation key),\n\t\t// not the receipt id — receipts are evidence artifacts, checkIds are obligations.\n\t\tconst checkId = claimById?.get(claimId)?.requiredCheckIds[0] ?? node.receiptId;\n\t\treturn {\n\t\t\t...base,\n\t\t\tkind: \"check\",\n\t\t\trunnerId: node.source,\n\t\t\tcheckId,\n\t\t\tsequence: 0,\n\t\t\tverdict: node.polarity === \"supports\" ? \"pass\" : \"fail\",\n\t\t};\n\t}\n\tif (node.source === \"model_narrative\") {\n\t\treturn { ...base, kind: \"decision\", actorId: \"model\", accepted: node.polarity === \"supports\" };\n\t}\n\treturn {\n\t\t...base,\n\t\tkind: \"reference\",\n\t\tsourceId: node.source,\n\t\tversion: null,\n\t\tstance: node.polarity === \"supports\" ? \"support\" : \"refute\",\n\t\tdocumentDigest: node.environmentDigest,\n\t\tlocator: node.sourceRoot,\n\t};\n}\n\nexport interface RuntimeBridgeOutput {\n\treadonly state: MetaState;\n\treadonly claims: readonly Claim[];\n\treadonly observations: readonly (CheckObservation | ReferenceObservation | DecisionObservation)[];\n}\nexport interface RuntimeBridgeInput {\n\treadonly taskId: string;\n\treadonly stageId: string;\n\treadonly goalScope: string;\n\treadonly targetArtifact: string;\n\treadonly candidateHash: string;\n\treadonly environmentHash: string;\n\treadonly claims: readonly ClaimNode[];\n\treadonly observations: readonly ObservationNode[];\n\treadonly trustedRunnerIds: readonly string[];\n\treadonly decisionActorIds: readonly string[];\n\treadonly authorizedActions: readonly string[];\n\treadonly budget: {\n\t\tremainingMs: number;\n\t\tremainingRequests: number;\n\t\tremainingTokens: number;\n\t\tremainingConcurrent: number;\n\t};\n\treadonly policyVersion: string;\n\treadonly modelRevision: string;\n\treadonly interruptionReason?: string | null;\n\treadonly stage: Stage;\n\treadonly nowMs: number;\n\treadonly progressHistory?: readonly {\n\t\tkey: string;\n\t\tnewEvidence: boolean;\n\t\tresolvedObligations: number;\n\t\tnewValidChecks: number;\n\t}[];\n}\n\n/** Build kernel inputs plus a MetaState for one safe checkpoint. Host-owned inputs only. */\nexport function toMetaState(input: RuntimeBridgeInput): RuntimeBridgeOutput {\n\ttext(input.taskId, \"taskId\", 128);\n\ttext(input.stageId, \"stageId\", 128);\n\ttext(input.goalScope, \"goalScope\", 256);\n\ttext(input.targetArtifact, \"targetArtifact\", 512);\n\ttext(input.candidateHash, \"candidateHash\", 128);\n\ttext(input.environmentHash, \"environmentHash\", 128);\n\ttext(input.policyVersion, \"policyVersion\", 64);\n\ttext(input.modelRevision, \"modelRevision\", 128);\n\tinteger(input.nowMs, \"nowMs\");\n\tensure(input.claims.length <= 128 && input.observations.length <= 4096, \"runtime bridge input too large\");\n\t// Only leaf claims map to kernel claims — compound satisfaction is the\n\t// protocol layer's job, not a kernel evidence predicate.\n\tconst binding = `${input.candidateHash}@${input.environmentHash}`;\n\tconst leafClaims = input.claims.filter((c) => c.satisfaction.inputs.length === 0);\n\tconst claimById = new Map(leafClaims.map((c) => [c.claimId, toKernelClaim(c, input.stage, binding)]));\n\tconst kernelClaims = [...claimById.values()].sort((a, b) => lexical(a.id, b.id));\n\tconst kernelObservations = input.observations.map((o) => toKernelObservation(o, binding, input.nowMs, claimById));\n\tconst state: MetaState = {\n\t\tgoal: {\n\t\t\ttaskId: input.taskId,\n\t\t\tstageId: input.stageId,\n\t\t\ttargetArtifact: input.targetArtifact,\n\t\t\tgoalScope: input.goalScope,\n\t\t},\n\t\tfacts: {\n\t\t\tcandidateHash: input.candidateHash,\n\t\t\tenvironmentHash: input.environmentHash,\n\t\t\tchangeScope: [input.targetArtifact],\n\t\t\tanalyzerCoverage: \"unknown\",\n\t\t},\n\t\tobligations: [],\n\t\tevidence: { report: null, adoptedSourceIds: [] },\n\t\tpredictions: [],\n\t\thypotheses: { open: [], discriminatorCandidates: [], modelMismatch: false },\n\t\tcalibration: createCalibrationStore({\n\t\t\tminSamples: 5,\n\t\t\tpriorAlpha: 1,\n\t\t\tpriorBeta: 1,\n\t\t\treferenceMean: 0.3,\n\t\t\tslack: 0.15,\n\t\t\tthreshold: 3,\n\t\t}),\n\t\tverifier: { evaluations: [], runnerHealth: \"unverified\" },\n\t\tbudget: input.budget,\n\t\tpolicy: {\n\t\t\tpolicyVersion: input.policyVersion,\n\t\t\tauthorizedActions: input.authorizedActions,\n\t\t\trequiredApprovals: [],\n\t\t\tinterruptionReason: input.interruptionReason ?? null,\n\t\t},\n\t\thostSequence: 0,\n\t\tprogressHistory: input.progressHistory ?? [],\n\t\tcheckpointCount: 0,\n\t};\n\treturn { state, claims: kernelClaims, observations: kernelObservations };\n}\n\n/** Sources admitted for reference evidence: only repository/official qualify. */\nexport function sourceIdentities(overrides: readonly SourceIdentity[] = []): readonly SourceIdentity[] {\n\treturn [\n\t\t{ id: \"deterministic_validator\", family: \"host\", kind: \"repository\" },\n\t\t{ id: \"workspace_witness\", family: \"host\", kind: \"repository\" },\n\t\t{ id: \"trusted_attestation\", family: \"attestation\", kind: \"official\" },\n\t\t{ id: \"effect_reconciliation\", family: \"host\", kind: \"repository\" },\n\t\t{ id: \"independent_review\", family: \"review\", kind: \"official\" },\n\t\t{ id: \"self_review\", family: \"model\", kind: \"model\" },\n\t\t{ id: \"model_narrative\", family: \"model\", kind: \"model\" },\n\t\t...overrides,\n\t];\n}\n"]}

package/dist/metacognition/skills.d.ts

@@ -0,0 +1,42 @@
+export interface CapabilityNeed {
+    readonly capability: string;
+    readonly weight: number;
+    readonly required: boolean;
+}
+export interface SkillDescriptor {
+    readonly id: string;
+    readonly contentHash: string;
+    readonly capabilities: readonly string[];
+    readonly phases: readonly string[];
+    readonly tokenCost: number;
+    readonly dependencies: readonly string[];
+    readonly conflicts: readonly string[];
+    readonly permissions: readonly string[];
+    readonly explicitOnly: boolean;
+    /** Exact versions intentionally, never a hand-written semver implementation. */
+    readonly packages: Readonly<Record<string, readonly string[]>>;
+}
+export interface SkillPlanInput {
+    readonly phase: string;
+    readonly needs: readonly CapabilityNeed[];
+    readonly catalog: readonly SkillDescriptor[];
+    /** Host-owned content pins, not fields supplied by the skill being selected. */
+    readonly approvedHashes: Readonly<Record<string, string>>;
+    readonly installedVersions: Readonly<Record<string, string>>;
+    readonly allowedPermissions: readonly string[];
+    readonly explicitSkills: readonly string[];
+    readonly tokenBudget: number;
+    readonly maxSkills: number;
+}
+export interface SkillPlan {
+    readonly selected: readonly string[];
+    readonly tokenCost: number;
+    readonly covered: readonly string[];
+    readonly uncoveredRequired: readonly string[];
+    readonly blockedExplicit: readonly string[];
+    readonly rejected: Readonly<Record<string, string>>;
+    readonly algorithm: "exact-small" | "greedy-with-singleton";
+    readonly state: "covered" | "capability-gap" | "explicit-blocked";
+}
+export declare function planSkills(input: SkillPlanInput): SkillPlan;
+//# sourceMappingURL=skills.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/metacognition/skills.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC3B;AACD,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;CAC/D;AACD,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,gFAAgF;IAChF,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AACD,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,SAAS,EAAE,aAAa,GAAG,uBAAuB,CAAC;IAC5D,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;CAClE;AAQD,wBAAgB,UAAU,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAmM3D","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/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":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAiDrF,MAAM,UAAU,UAAU,CAAC,KAAqB,EAAa;IAC5D,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,WAAW,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC;IACtD,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC;IAC1C,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;IAC1C,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IACtC,MAAM,CACL,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAC9B,aAAa,CACb,CAAC;IACF,MAAM,CACL,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,EACpC,UAAU,EACV,GAAG,CACH,CAAC;IACF,MAAM,CAAC,KAAK,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;IAChD,MAAM,CAAC,KAAK,CAAC,cAAc,EAAE,gBAAgB,EAAE,EAAE,CAAC,CAAC;IACnD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAChC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS,EAAE,qBAAqB,CAAC,CAAC;QAC3G,MAAM,CAAC,OAAO,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,0BAA0B,CAAC,CAAC;IACxE,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QACnC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;QACvC,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC;QACjD,MAAM,CAAC,KAAK,CAAC,YAAY,EAAE,cAAc,EAAE,GAAG,CAAC,CAAC;QAChD,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;QACnC,MAAM,CAAC,KAAK,CAAC,YAAY,EAAE,cAAc,EAAE,EAAE,CAAC,CAAC;QAC/C,MAAM,CAAC,KAAK,CAAC,SAAS,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC;QACzC,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,mBAAmB,EAAE,EAAE,CAAC,CAAC;QACnD,MAAM,CAAC,OAAO,KAAK,CAAC,YAAY,KAAK,SAAS,EAAE,8BAA8B,CAAC,CAAC;QAChF,MAAM,CAAC,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,2BAA2B,CAAC,CAAC;QACnG,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC/D,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;YACtB,MAAM,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC;YAClC,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,0BAA0B,CAAC,CAAC;QACzD,CAAC;QACD,IAAI,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,KAAK,CAAC,WAAW;YAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,+BAA+B,CAAC,CAAC;aAC7G,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC;YAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,gBAAgB,CAAC,CAAC;aAClF,IAAI,KAAK,CAAC,YAAY,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,eAAe,CAAC,CAAC;aAC5G,IAAI,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;YACjG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,mBAAmB,CAAC,CAAC;QAC7C,CAAC;aAAM,IACN,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,CAClC,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAC7E,EACA,CAAC;YACF,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,iCAAiC,CAAC,CAAC;QAC3D,CAAC;IACF,CAAC;IACD,gFAAgF;IAChF,MAAM,YAAY,GAAG,IAAI,GAAG,EAAmC,CAAC;IAChE,MAAM,OAAO,GAAG,CAAC,EAAU,EAAE,KAAK,GAAG,IAAI,GAAG,EAAU,EAA2B,EAAE,CAAC;QACnF,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,OAAO,SAAS,CAAC;QACxD,IAAI,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,OAAO,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACtD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3B,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC7B,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;QACrC,KAAK,MAAM,UAAU,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;YAC7C,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;YAC3C,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACf,YAAY,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;gBAChC,OAAO,SAAS,CAAC;YAClB,CAAC;YACD,KAAK,MAAM,KAAK,IAAI,QAAQ;gBAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACjD,CAAC;QACD,YAAY,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAC7B,OAAO,MAAM,CAAC;IAAA,CACd,CAAC;IACF,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;IAChD,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACjD,MAAM,GAAG,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC;QACxB,IAAI,GAAG;YAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;aAC1B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,4BAA4B,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,QAAQ,GAAG,CAAC,GAAwB,EAAW,EAAE,CAAC;QACvD,IAAI,GAAG,CAAC,IAAI,GAAG,KAAK,CAAC,SAAS;YAAE,OAAO,KAAK,CAAC;QAC7C,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;YACtB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC3B,IAAI,CAAC,KAAK,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,OAAO,KAAK,CAAC;YAC7C,IAAI,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAC;YAC9D,IAAI,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAC;YAC1D,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC;QACzB,CAAC;QACD,OAAO,IAAI,IAAI,KAAK,CAAC,WAAW,CAAC;IAAA,CACjC,CAAC;IACF,MAAM,KAAK,GAAG,CAAC,GAAwB,EAAS,EAAE,CAAC;QAClD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;QACnC,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;YACtB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC;YAC5B,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC;YACxB,KAAK,MAAM,UAAU,IAAI,KAAK,CAAC,YAAY;gBAAE,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,QAAQ,GAAG,CAAC,EACf,QAAQ,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAChC,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;gBACnC,IAAI,IAAI,CAAC,QAAQ;oBAAE,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC;;oBACtC,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC;YAC9B,CAAC;QACF,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;IAAA,CACjE,CAAC;IACF,MAAM,MAAM,GAAG,CAAC,IAAW,EAAE,KAAY,EAAW,EAAE,CACrD,IAAI,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ;QAC/B,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ;QAChC,CAAC,CAAC,IAAI,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ;YACjC,CAAC,CAAC,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ;YAChC,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI;gBACzB,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;gBACxB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,KAAK,CAAC,GAAG,CAAC,MAAM;oBACrC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM;oBACpC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9D,IAAI,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC7B,MAAM,eAAe,GAAa,EAAE,CAAC;IACrC,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,KAAK,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1D,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC7B,IAAI,CAAC,GAAG;YAAE,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;;YAC9B,KAAK,MAAM,IAAI,IAAI,GAAG;gBAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,eAAe,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACjH,gFAAgF;IAChF,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC;QAAE,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC;IACjD,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,MAAM,UAAU,GAAG,CAAC,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3E,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,uBAAuB,CAAC;IACpF,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,IAAI,SAAS,KAAK,aAAa,EAAE,CAAC;YACjC,MAAM,KAAK,GAAG,CAAC,QAAgB,EAAE,OAAoB,EAAQ,EAAE,CAAC;gBAC/D,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;oBAAE,OAAO;gBAC/B,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;oBAAE,IAAI,GAAG,OAAO,CAAC;gBACxD,MAAM,SAAS,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;gBACvC,IAAI,CAAC,SAAS;oBAAE,OAAO;gBACvB,KAAK,CAAC,QAAQ,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;gBAC7B,KAAK,CAAC,QAAQ,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAAA,CAC5D,CAAC;YACF,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAChB,CAAC;aAAM,CAAC;YACP,IAAI,OAAO,GAAG,IAAI,CAAC;YACnB,OAAO,IAAI,EAAE,CAAC;gBACb,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;gBAChC,IAAI,MAA+B,CAAC;gBACpC,IAAI,IAAI,GAAsC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC3D,KAAK,MAAM,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,UAAU,EAAE,CAAC;oBACpC,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;wBAAE,SAAS;oBAC9B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;oBAC7C,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;wBAAE,SAAS;oBAChC,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;oBAC5B,MAAM,YAAY,GAAG,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;oBACxD,MAAM,YAAY,GAAG,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;oBACxD,IAAI,YAAY,IAAI,CAAC,IAAI,YAAY,IAAI,CAAC;wBAAE,SAAS;oBACrD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;oBACrD,MAAM,QAAQ,GAAG,CAAC,YAAY,GAAG,IAAI,EAAE,YAAY,GAAG,IAAI,EAAE,EAAE,CAAU,CAAC;oBACzE,IACC,CAAC,MAAM;wBACP,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;wBACrB,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;4BACvB,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAC1F,CAAC;wBACF,MAAM,GAAG,MAAM,CAAC;wBAChB,IAAI,GAAG,QAAQ,CAAC;oBACjB,CAAC;gBACF,CAAC;gBACD,IAAI,CAAC,MAAM;oBAAE,MAAM;gBACnB,OAAO,GAAG,MAAM,CAAC;YAClB,CAAC;YACD,IAAI,GAAG,OAAO,CAAC;YACf,KAAK,MAAM,CAAC,EAAE,GAAG,CAAC,IAAI,UAAU,EAAE,CAAC;gBAClC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;gBAC1C,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;oBAAE,IAAI,GAAG,MAAM,CAAC;YAC3E,CAAC;QACF,CAAC;IACF,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC,YAAY,CAAC,CAAC,CAAC;IAClF,MAAM,iBAAiB,GAAG,KAAK,CAAC,KAAK;SACnC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;SAC1D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;SACxB,IAAI,CAAC,OAAO,CAAC,CAAC;IAChB,OAAO;QACN,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;QACjC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI;QAC3B,OAAO,EAAE,KAAK,CAAC,KAAK;aAClB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;aAC3C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;aACxB,IAAI,CAAC,OAAO,CAAC;QACf,iBAAiB;QACjB,eAAe,EAAE,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC;QAC9C,QAAQ,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC7E,SAAS;QACT,KAAK,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS;KAC5G,CAAC;AAAA,CACF","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