open-multi-agent-kit 0.99.0 → 1.2.0

package/dist/metacognition/knowledge-action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-action.js","sourceRoot":"","sources":["../../src/metacognition/knowledge-action.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Bounded next-action selector for knowledge gaps.\n *\n * Split from knowledge.ts to keep each module under the repository's\n * 250-line module-size ratchet. Same behavior as the reference port.\n */\n\nimport type { Claim, KnowledgeReport } from \"./knowledge.ts\";\nimport { ensure, integer, member, text, unique } from \"./validation.ts\";\n\nexport type SearchChannel = \"local\" | \"official\" | \"web\";\nexport interface SearchAttempt {\n\treadonly claimId: string;\n\treadonly binding: string;\n\treadonly channel: SearchChannel;\n\treadonly result: \"empty\" | \"failed\" | \"candidates\" | \"in-flight\";\n}\nexport interface ActionPolicy {\n\treadonly availableChannels: readonly SearchChannel[];\n\treadonly remoteQueryApprovedClaimIds: readonly string[];\n\treadonly remainingRequests: number;\n\treadonly remainingMs: number;\n}\nexport type KnowledgeAction =\n\t| { readonly kind: \"proceed\"; readonly meaning: \"evidence-predicates-satisfied-not-general-correctness\" }\n\t| { readonly kind: \"search\"; readonly claimId: string; readonly channel: SearchChannel; readonly query: string }\n\t| { readonly kind: \"run-check\"; readonly claimId: string; readonly checkId: string }\n\t| {\n\t\t\treadonly kind:\n\t\t\t\t| \"inspect-local\"\n\t\t\t\t| \"repair\"\n\t\t\t\t| \"review-candidates\"\n\t\t\t\t| \"await-owned-work\"\n\t\t\t\t| \"ask-user\"\n\t\t\t\t| \"form-obligations\";\n\t\t\treadonly claimId: string;\n\t  }\n\t| { readonly kind: \"blocked\"; readonly claimId: string; readonly reason: string };\n\n/** One bounded next action, not an autonomous recursion that can spend unbounded API calls. */\nexport function nextKnowledgeAction(\n\treport: KnowledgeReport,\n\tclaims: readonly Claim[],\n\tattempts: readonly SearchAttempt[],\n\tpolicy: ActionPolicy,\n): KnowledgeAction {\n\tinteger(policy.remainingRequests, \"remainingRequests\");\n\tinteger(policy.remainingMs, \"remainingMs\");\n\tunique(policy.availableChannels, \"availableChannels\", 3);\n\tfor (const channel of policy.availableChannels) member(channel, [\"local\", \"official\", \"web\"], \"search channel\");\n\tunique(policy.remoteQueryApprovedClaimIds, \"remote approvals\", 128);\n\tensure(attempts.length <= 4096, \"too many search attempts\");\n\tfor (const attempt of attempts) {\n\t\ttext(attempt.claimId, \"attempt claim\");\n\t\ttext(attempt.binding, \"attempt binding\");\n\t\tmember(attempt.channel, [\"local\", \"official\", \"web\"], \"attempt channel\");\n\t\tmember(attempt.result, [\"empty\", \"failed\", \"candidates\", \"in-flight\"], \"attempt result\");\n\t}\n\tconst gap = report.gaps.find((g) => g.required);\n\tif (!gap) return { kind: \"proceed\", meaning: \"evidence-predicates-satisfied-not-general-correctness\" };\n\tconst claimId = gap.claimId;\n\tif (gap.reason === \"unassessed-step\") return { kind: \"form-obligations\", claimId };\n\tif (gap.reason === \"missing-user-decision\") return { kind: \"ask-user\", claimId };\n\tif (gap.reason === \"unknown-version\") return { kind: \"inspect-local\", claimId };\n\tif (gap.reason === \"failed-check\") return { kind: \"repair\", claimId };\n\tif (gap.reason === \"pending-check\") return { kind: \"await-owned-work\", claimId };\n\tif (gap.reason === \"missing-check\") {\n\t\tensure(gap.checkId !== null, \"missing checkId\");\n\t\treturn { kind: \"run-check\", claimId, checkId: gap.checkId };\n\t}\n\tconst claim = claims.find((c) => c.id === claimId && c.binding === gap.binding);\n\tensure(claim !== undefined, \"report has stale or unknown claim\");\n\tconst history = attempts.filter((a) => a.claimId === claimId && a.binding === gap.binding);\n\tif (history.some((a) => a.result === \"in-flight\")) return { kind: \"await-owned-work\", claimId };\n\tif (history.some((a) => a.result === \"candidates\")) return { kind: \"review-candidates\", claimId };\n\tif (policy.remainingRequests === 0 || policy.remainingMs === 0) {\n\t\treturn { kind: \"blocked\", claimId, reason: \"acquisition-budget-exhausted\" };\n\t}\n\tfor (const channel of [\"local\", \"official\", \"web\"] as const) {\n\t\tif (!policy.availableChannels.includes(channel) || history.some((a) => a.channel === channel)) continue;\n\t\tif (channel !== \"local\" && (!policy.remoteQueryApprovedClaimIds.includes(claimId) || claim.publicQuery === null))\n\t\t\tcontinue;\n\t\treturn { kind: \"search\", claimId, channel, query: channel === \"local\" ? claim.statement : claim.publicQuery! };\n\t}\n\treturn { kind: \"blocked\", claimId, reason: \"no-approved-untried-source\" };\n}\n"]}

package/dist/metacognition/knowledge.d.ts

@@ -0,0 +1,84 @@
+export type Stage = "before-change" | "after-change";
+export interface Claim {
+    readonly id: string;
+    /** Hash/fingerprint computed by the host over the relevant subject and environment. */
+    readonly binding: string;
+    readonly phase: "precondition" | "postcondition";
+    readonly statement: string;
+    readonly required: boolean;
+    readonly impact: number;
+    readonly needsReference: boolean;
+    readonly requiresVersion: boolean;
+    readonly version: string | null;
+    readonly minSourceFamilies: number;
+    readonly requiredCheckIds: readonly string[];
+    readonly needsUserDecision: boolean;
+    /** Only explicit, host-approved public text can leave the repository. */
+    readonly publicQuery: string | null;
+}
+export interface SourceIdentity {
+    readonly id: string;
+    readonly family: string;
+    readonly kind: "repository" | "official" | "community" | "model";
+}
+interface ObservationBase {
+    readonly id: string;
+    readonly claimId: string;
+    readonly binding: string;
+    readonly observedAtMs: number;
+    readonly expiresAtMs: number;
+}
+export interface ReferenceObservation extends ObservationBase {
+    readonly kind: "reference";
+    readonly sourceId: string;
+    readonly version: string | null;
+    readonly stance: "support" | "refute";
+    readonly documentDigest: string;
+    readonly locator: string;
+}
+export interface CheckObservation extends ObservationBase {
+    readonly kind: "check";
+    readonly runnerId: string;
+    readonly checkId: string;
+    /** Host-ordered snapshot. In OMK, project the existing strict evidence ledger here. */
+    readonly sequence: number;
+    readonly verdict: "pass" | "fail" | "pending";
+}
+export interface DecisionObservation extends ObservationBase {
+    readonly kind: "decision";
+    readonly actorId: string;
+    readonly accepted: boolean;
+}
+export type Observation = ReferenceObservation | CheckObservation | DecisionObservation;
+export type GapReason = "unassessed-step" | "unknown-version" | "unsupported-reference" | "contradictory-reference" | "missing-check" | "failed-check" | "pending-check" | "missing-user-decision";
+export interface KnowledgeGap {
+    readonly claimId: string;
+    readonly binding: string;
+    readonly reason: GapReason;
+    readonly required: boolean;
+    readonly impact: number;
+    readonly checkId: string | null;
+}
+export interface KnowledgeReport {
+    readonly state: "supported" | "gaps";
+    readonly gaps: readonly KnowledgeGap[];
+    readonly supportedClaimIds: readonly string[];
+    readonly rejectedObservations: readonly {
+        id: string;
+        reason: string;
+    }[];
+}
+export interface KnowledgeInput {
+    readonly stage: Stage;
+    readonly requiresAssessment: boolean;
+    readonly nowMs: number;
+    readonly claims: readonly Claim[];
+    /** Admitted host observations only. Never pass a model's JSON here as runner truth. */
+    readonly observations: readonly Observation[];
+    readonly sources: readonly SourceIdentity[];
+    readonly trustedRunnerIds: readonly string[];
+    readonly decisionActorIds: readonly string[];
+}
+export declare function inspectKnowledge(input: KnowledgeInput): KnowledgeReport;
+export {};
+//# sourceMappingURL=knowledge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../src/metacognition/knowledge.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Claim/evidence gap inspection and the bounded next-action selector.\n *\n * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip\n * (src/knowledge.ts). Host-owned observations only; a model's JSON is never\n * runner truth. See OMK_metacognitive_control_algorithms_2026-09-19.md §13.\n */\nimport { canonical, ensure, integer, lexical, member, text, unique } from \"./validation.ts\";\n\nexport type Stage = \"before-change\" | \"after-change\";\nexport interface Claim {\n\treadonly id: string;\n\t/** Hash/fingerprint computed by the host over the relevant subject and environment. */\n\treadonly binding: string;\n\treadonly phase: \"precondition\" | \"postcondition\";\n\treadonly statement: string;\n\treadonly required: boolean;\n\treadonly impact: number;\n\treadonly needsReference: boolean;\n\treadonly requiresVersion: boolean;\n\treadonly version: string | null;\n\treadonly minSourceFamilies: number;\n\treadonly requiredCheckIds: readonly string[];\n\treadonly needsUserDecision: boolean;\n\t/** Only explicit, host-approved public text can leave the repository. */\n\treadonly publicQuery: string | null;\n}\nexport interface SourceIdentity {\n\treadonly id: string;\n\treadonly family: string;\n\treadonly kind: \"repository\" | \"official\" | \"community\" | \"model\";\n}\ninterface ObservationBase {\n\treadonly id: string;\n\treadonly claimId: string;\n\treadonly binding: string;\n\treadonly observedAtMs: number;\n\treadonly expiresAtMs: number;\n}\nexport interface ReferenceObservation extends ObservationBase {\n\treadonly kind: \"reference\";\n\treadonly sourceId: string;\n\treadonly version: string | null;\n\treadonly stance: \"support\" | \"refute\";\n\treadonly documentDigest: string;\n\treadonly locator: string;\n}\nexport interface CheckObservation extends ObservationBase {\n\treadonly kind: \"check\";\n\treadonly runnerId: string;\n\treadonly checkId: string;\n\t/** Host-ordered snapshot. In OMK, project the existing strict evidence ledger here. */\n\treadonly sequence: number;\n\treadonly verdict: \"pass\" | \"fail\" | \"pending\";\n}\nexport interface DecisionObservation extends ObservationBase {\n\treadonly kind: \"decision\";\n\treadonly actorId: string;\n\treadonly accepted: boolean;\n}\nexport type Observation = ReferenceObservation | CheckObservation | DecisionObservation;\nexport type GapReason =\n\t| \"unassessed-step\"\n\t| \"unknown-version\"\n\t| \"unsupported-reference\"\n\t| \"contradictory-reference\"\n\t| \"missing-check\"\n\t| \"failed-check\"\n\t| \"pending-check\"\n\t| \"missing-user-decision\";\nexport interface KnowledgeGap {\n\treadonly claimId: string;\n\treadonly binding: string;\n\treadonly reason: GapReason;\n\treadonly required: boolean;\n\treadonly impact: number;\n\treadonly checkId: string | null;\n}\nexport interface KnowledgeReport {\n\treadonly state: \"supported\" | \"gaps\";\n\treadonly gaps: readonly KnowledgeGap[];\n\treadonly supportedClaimIds: readonly string[];\n\treadonly rejectedObservations: readonly { id: string; reason: string }[];\n}\nexport interface KnowledgeInput {\n\treadonly stage: Stage;\n\treadonly requiresAssessment: boolean;\n\treadonly nowMs: number;\n\treadonly claims: readonly Claim[];\n\t/** Admitted host observations only. Never pass a model's JSON here as runner truth. */\n\treadonly observations: readonly Observation[];\n\treadonly sources: readonly SourceIdentity[];\n\treadonly trustedRunnerIds: readonly string[];\n\treadonly decisionActorIds: readonly string[];\n}\n\nexport function inspectKnowledge(input: KnowledgeInput): KnowledgeReport {\n\tmember(input.stage, [\"before-change\", \"after-change\"], \"stage\");\n\tinteger(input.nowMs, \"nowMs\");\n\tensure(typeof input.requiresAssessment === \"boolean\", \"requiresAssessment must be boolean\");\n\tensure(input.claims.length <= 128 && input.observations.length <= 4096, \"knowledge input too large\");\n\tunique(\n\t\tinput.claims.map((c) => c.id),\n\t\t\"claim ids\",\n\t\t128,\n\t);\n\tunique(\n\t\tinput.sources.map((s) => s.id),\n\t\t\"source ids\",\n\t\t512,\n\t);\n\tunique(input.trustedRunnerIds, \"runner ids\");\n\tunique(input.decisionActorIds, \"decision actor ids\");\n\tfor (const c of input.claims) {\n\t\ttext(c.binding, \"binding\");\n\t\ttext(c.statement, \"statement\");\n\t\tmember(c.phase, [\"precondition\", \"postcondition\"], \"claim phase\");\n\t\tfor (const v of [c.required, c.needsReference, c.requiresVersion, c.needsUserDecision]) {\n\t\t\tensure(typeof v === \"boolean\", \"invalid claim flag\");\n\t\t}\n\t\tensure(Number.isFinite(c.impact) && c.impact >= 0 && c.impact <= 1_000_000, \"invalid impact\");\n\t\tinteger(c.minSourceFamilies, \"minSourceFamilies\", 16);\n\t\tensure(!c.needsReference || c.minSourceFamilies > 0, \"reference needs at least one source family\");\n\t\tif (c.version !== null) text(c.version, \"version\", 128);\n\t\tif (c.publicQuery !== null) text(c.publicQuery, \"publicQuery\", 500);\n\t\tunique(c.requiredCheckIds, \"check ids\", 128);\n\t\tensure(\n\t\t\tc.needsReference || c.requiredCheckIds.length > 0 || c.needsUserDecision,\n\t\t\t\"claim has no evidence predicate\",\n\t\t);\n\t}\n\tconst sources = new Map(\n\t\tinput.sources.map((s) => {\n\t\t\ttext(s.family, \"source family\");\n\t\t\tmember(s.kind, [\"repository\", \"official\", \"community\", \"model\"], \"source kind\");\n\t\t\treturn [s.id, s] as const;\n\t\t}),\n\t);\n\tconst observations = new Map<string, Observation>();\n\tconst sequences = new Map<string, string>();\n\tfor (const obs of input.observations) {\n\t\ttext(obs.id, \"observation id\");\n\t\ttext(obs.claimId, \"observation claim\");\n\t\ttext(obs.binding, \"observation binding\");\n\t\tinteger(obs.observedAtMs, \"observedAtMs\");\n\t\tinteger(obs.expiresAtMs, \"expiresAtMs\");\n\t\tensure(obs.expiresAtMs >= obs.observedAtMs, \"invalid observation validity interval\");\n\t\tmember(obs.kind, [\"reference\", \"check\", \"decision\"], \"observation kind\");\n\t\tif (obs.kind === \"reference\") {\n\t\t\ttext(obs.sourceId, \"sourceId\");\n\t\t\ttext(obs.documentDigest, \"documentDigest\");\n\t\t\ttext(obs.locator, \"locator\");\n\t\t\tif (obs.version !== null) text(obs.version, \"observation version\", 128);\n\t\t\tmember(obs.stance, [\"support\", \"refute\"], \"stance\");\n\t\t} else if (obs.kind === \"check\") {\n\t\t\ttext(obs.runnerId, \"runnerId\");\n\t\t\ttext(obs.checkId, \"checkId\");\n\t\t\tinteger(obs.sequence, \"sequence\");\n\t\t\tmember(obs.verdict, [\"pass\", \"fail\", \"pending\"], \"check verdict\");\n\t\t\tconst key = canonical([obs.claimId, obs.binding, obs.checkId, obs.sequence]);\n\t\t\tconst previous = sequences.get(key);\n\t\t\tensure(previous === undefined || previous === canonical(obs), \"conflicting check sequence\");\n\t\t\tsequences.set(key, canonical(obs));\n\t\t} else {\n\t\t\ttext(obs.actorId, \"actorId\");\n\t\t\tensure(typeof obs.accepted === \"boolean\", \"invalid decision\");\n\t\t}\n\t\tconst previous = observations.get(obs.id);\n\t\tensure(previous === undefined || canonical(previous) === canonical(obs), \"conflicting observation id\");\n\t\tobservations.set(obs.id, obs);\n\t}\n\tconst relevantClaims = input.claims.filter((c) => input.stage === \"after-change\" || c.phase === \"precondition\");\n\tconst rejectedObservations: { id: string; reason: string }[] = [];\n\tconst admissible = new Map<string, Observation[]>();\n\tconst claimMap = new Map(relevantClaims.map((c) => [c.id, c]));\n\tfor (const obs of observations.values()) {\n\t\tconst c = claimMap.get(obs.claimId);\n\t\tlet reason: string | undefined;\n\t\tif (!c) reason = \"irrelevant-claim-or-stage\";\n\t\telse if (obs.binding !== c.binding) reason = \"stale-binding\";\n\t\telse if (obs.observedAtMs > input.nowMs || obs.expiresAtMs <= input.nowMs) reason = \"expired-or-future\";\n\t\telse if (obs.kind === \"reference\") {\n\t\t\tconst source = sources.get(obs.sourceId);\n\t\t\tif (!source || (source.kind !== \"repository\" && source.kind !== \"official\")) reason = \"inadmissible-source\";\n\t\t\telse if (c.requiresVersion && (c.version === null || obs.version !== c.version)) reason = \"version-mismatch\";\n\t\t} else if (obs.kind === \"check\" && !input.trustedRunnerIds.includes(obs.runnerId)) reason = \"untrusted-runner\";\n\t\telse if (obs.kind === \"decision\" && !input.decisionActorIds.includes(obs.actorId)) {\n\t\t\treason = \"untrusted-decision-actor\";\n\t\t}\n\t\tif (reason) rejectedObservations.push({ id: obs.id, reason });\n\t\telse admissible.set(obs.claimId, [...(admissible.get(obs.claimId) ?? []), obs]);\n\t}\n\tconst gaps: KnowledgeGap[] = [];\n\tconst supportedClaimIds: string[] = [];\n\tif (input.requiresAssessment && relevantClaims.filter((c) => c.required).length === 0) {\n\t\tgaps.push({\n\t\t\tclaimId: \"$step\",\n\t\t\tbinding: \"unassessed\",\n\t\t\treason: \"unassessed-step\",\n\t\t\trequired: true,\n\t\t\timpact: 1_000_000,\n\t\t\tcheckId: null,\n\t\t});\n\t}\n\tfor (const c of relevantClaims) {\n\t\tconst before = gaps.length;\n\t\tconst evidence = admissible.get(c.id) ?? [];\n\t\tconst add = (reason: GapReason, checkId: string | null = null): void => {\n\t\t\tgaps.push({ claimId: c.id, binding: c.binding, reason, required: c.required, impact: c.impact, checkId });\n\t\t};\n\t\tif (c.requiresVersion && c.version === null) add(\"unknown-version\");\n\t\tif (c.needsReference) {\n\t\t\tconst refs = evidence.filter((obs): obs is ReferenceObservation => obs.kind === \"reference\");\n\t\t\tconst support = new Set(\n\t\t\t\trefs.filter((r) => r.stance === \"support\").map((r) => sources.get(r.sourceId)!.family),\n\t\t\t);\n\t\t\tif (refs.some((r) => r.stance === \"refute\")) add(\"contradictory-reference\");\n\t\t\telse if (support.size < c.minSourceFamilies) add(\"unsupported-reference\");\n\t\t}\n\t\tfor (const checkId of c.requiredCheckIds) {\n\t\t\tconst records = evidence\n\t\t\t\t.filter((obs): obs is CheckObservation => obs.kind === \"check\" && obs.checkId === checkId)\n\t\t\t\t.sort((a, b) => a.sequence - b.sequence);\n\t\t\tconst latest = records.at(-1);\n\t\t\tif (!latest) add(\"missing-check\", checkId);\n\t\t\telse if (latest.verdict === \"fail\") add(\"failed-check\", checkId);\n\t\t\telse if (latest.verdict === \"pending\") add(\"pending-check\", checkId);\n\t\t}\n\t\tif (c.needsUserDecision) {\n\t\t\tconst decisions = evidence.filter((obs): obs is DecisionObservation => obs.kind === \"decision\");\n\t\t\tif (!decisions.some((d) => d.accepted) || decisions.some((d) => !d.accepted)) add(\"missing-user-decision\");\n\t\t}\n\t\tif (before === gaps.length) supportedClaimIds.push(c.id);\n\t}\n\tgaps.sort(\n\t\t(a, b) =>\n\t\t\tNumber(b.required) - Number(a.required) ||\n\t\t\tb.impact - a.impact ||\n\t\t\tlexical(a.claimId, b.claimId) ||\n\t\t\tlexical(a.reason, b.reason),\n\t);\n\treturn {\n\t\tstate: gaps.some((g) => g.required) ? \"gaps\" : \"supported\",\n\t\tgaps,\n\t\tsupportedClaimIds: supportedClaimIds.sort(lexical),\n\t\trejectedObservations,\n\t};\n}\n"]}

package/dist/metacognition/knowledge.js

@@ -0,0 +1,165 @@
+/**
+ * Claim/evidence gap inspection and the bounded next-action selector.
+ *
+ * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip
+ * (src/knowledge.ts). Host-owned observations only; a model's JSON is never
+ * runner truth. See OMK_metacognitive_control_algorithms_2026-09-19.md §13.
+ */
+import { canonical, ensure, integer, lexical, member, text, unique } from "./validation.js";
+export function inspectKnowledge(input) {
+    member(input.stage, ["before-change", "after-change"], "stage");
+    integer(input.nowMs, "nowMs");
+    ensure(typeof input.requiresAssessment === "boolean", "requiresAssessment must be boolean");
+    ensure(input.claims.length <= 128 && input.observations.length <= 4096, "knowledge input too large");
+    unique(input.claims.map((c) => c.id), "claim ids", 128);
+    unique(input.sources.map((s) => s.id), "source ids", 512);
+    unique(input.trustedRunnerIds, "runner ids");
+    unique(input.decisionActorIds, "decision actor ids");
+    for (const c of input.claims) {
+        text(c.binding, "binding");
+        text(c.statement, "statement");
+        member(c.phase, ["precondition", "postcondition"], "claim phase");
+        for (const v of [c.required, c.needsReference, c.requiresVersion, c.needsUserDecision]) {
+            ensure(typeof v === "boolean", "invalid claim flag");
+        }
+        ensure(Number.isFinite(c.impact) && c.impact >= 0 && c.impact <= 1_000_000, "invalid impact");
+        integer(c.minSourceFamilies, "minSourceFamilies", 16);
+        ensure(!c.needsReference || c.minSourceFamilies > 0, "reference needs at least one source family");
+        if (c.version !== null)
+            text(c.version, "version", 128);
+        if (c.publicQuery !== null)
+            text(c.publicQuery, "publicQuery", 500);
+        unique(c.requiredCheckIds, "check ids", 128);
+        ensure(c.needsReference || c.requiredCheckIds.length > 0 || c.needsUserDecision, "claim has no evidence predicate");
+    }
+    const sources = new Map(input.sources.map((s) => {
+        text(s.family, "source family");
+        member(s.kind, ["repository", "official", "community", "model"], "source kind");
+        return [s.id, s];
+    }));
+    const observations = new Map();
+    const sequences = new Map();
+    for (const obs of input.observations) {
+        text(obs.id, "observation id");
+        text(obs.claimId, "observation claim");
+        text(obs.binding, "observation binding");
+        integer(obs.observedAtMs, "observedAtMs");
+        integer(obs.expiresAtMs, "expiresAtMs");
+        ensure(obs.expiresAtMs >= obs.observedAtMs, "invalid observation validity interval");
+        member(obs.kind, ["reference", "check", "decision"], "observation kind");
+        if (obs.kind === "reference") {
+            text(obs.sourceId, "sourceId");
+            text(obs.documentDigest, "documentDigest");
+            text(obs.locator, "locator");
+            if (obs.version !== null)
+                text(obs.version, "observation version", 128);
+            member(obs.stance, ["support", "refute"], "stance");
+        }
+        else if (obs.kind === "check") {
+            text(obs.runnerId, "runnerId");
+            text(obs.checkId, "checkId");
+            integer(obs.sequence, "sequence");
+            member(obs.verdict, ["pass", "fail", "pending"], "check verdict");
+            const key = canonical([obs.claimId, obs.binding, obs.checkId, obs.sequence]);
+            const previous = sequences.get(key);
+            ensure(previous === undefined || previous === canonical(obs), "conflicting check sequence");
+            sequences.set(key, canonical(obs));
+        }
+        else {
+            text(obs.actorId, "actorId");
+            ensure(typeof obs.accepted === "boolean", "invalid decision");
+        }
+        const previous = observations.get(obs.id);
+        ensure(previous === undefined || canonical(previous) === canonical(obs), "conflicting observation id");
+        observations.set(obs.id, obs);
+    }
+    const relevantClaims = input.claims.filter((c) => input.stage === "after-change" || c.phase === "precondition");
+    const rejectedObservations = [];
+    const admissible = new Map();
+    const claimMap = new Map(relevantClaims.map((c) => [c.id, c]));
+    for (const obs of observations.values()) {
+        const c = claimMap.get(obs.claimId);
+        let reason;
+        if (!c)
+            reason = "irrelevant-claim-or-stage";
+        else if (obs.binding !== c.binding)
+            reason = "stale-binding";
+        else if (obs.observedAtMs > input.nowMs || obs.expiresAtMs <= input.nowMs)
+            reason = "expired-or-future";
+        else if (obs.kind === "reference") {
+            const source = sources.get(obs.sourceId);
+            if (!source || (source.kind !== "repository" && source.kind !== "official"))
+                reason = "inadmissible-source";
+            else if (c.requiresVersion && (c.version === null || obs.version !== c.version))
+                reason = "version-mismatch";
+        }
+        else if (obs.kind === "check" && !input.trustedRunnerIds.includes(obs.runnerId))
+            reason = "untrusted-runner";
+        else if (obs.kind === "decision" && !input.decisionActorIds.includes(obs.actorId)) {
+            reason = "untrusted-decision-actor";
+        }
+        if (reason)
+            rejectedObservations.push({ id: obs.id, reason });
+        else
+            admissible.set(obs.claimId, [...(admissible.get(obs.claimId) ?? []), obs]);
+    }
+    const gaps = [];
+    const supportedClaimIds = [];
+    if (input.requiresAssessment && relevantClaims.filter((c) => c.required).length === 0) {
+        gaps.push({
+            claimId: "$step",
+            binding: "unassessed",
+            reason: "unassessed-step",
+            required: true,
+            impact: 1_000_000,
+            checkId: null,
+        });
+    }
+    for (const c of relevantClaims) {
+        const before = gaps.length;
+        const evidence = admissible.get(c.id) ?? [];
+        const add = (reason, checkId = null) => {
+            gaps.push({ claimId: c.id, binding: c.binding, reason, required: c.required, impact: c.impact, checkId });
+        };
+        if (c.requiresVersion && c.version === null)
+            add("unknown-version");
+        if (c.needsReference) {
+            const refs = evidence.filter((obs) => obs.kind === "reference");
+            const support = new Set(refs.filter((r) => r.stance === "support").map((r) => sources.get(r.sourceId).family));
+            if (refs.some((r) => r.stance === "refute"))
+                add("contradictory-reference");
+            else if (support.size < c.minSourceFamilies)
+                add("unsupported-reference");
+        }
+        for (const checkId of c.requiredCheckIds) {
+            const records = evidence
+                .filter((obs) => obs.kind === "check" && obs.checkId === checkId)
+                .sort((a, b) => a.sequence - b.sequence);
+            const latest = records.at(-1);
+            if (!latest)
+                add("missing-check", checkId);
+            else if (latest.verdict === "fail")
+                add("failed-check", checkId);
+            else if (latest.verdict === "pending")
+                add("pending-check", checkId);
+        }
+        if (c.needsUserDecision) {
+            const decisions = evidence.filter((obs) => obs.kind === "decision");
+            if (!decisions.some((d) => d.accepted) || decisions.some((d) => !d.accepted))
+                add("missing-user-decision");
+        }
+        if (before === gaps.length)
+            supportedClaimIds.push(c.id);
+    }
+    gaps.sort((a, b) => Number(b.required) - Number(a.required) ||
+        b.impact - a.impact ||
+        lexical(a.claimId, b.claimId) ||
+        lexical(a.reason, b.reason));
+    return {
+        state: gaps.some((g) => g.required) ? "gaps" : "supported",
+        gaps,
+        supportedClaimIds: supportedClaimIds.sort(lexical),
+        rejectedObservations,
+    };
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/metacognition/knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.js","sourceRoot":"","sources":["../../src/metacognition/knowledge.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Claim/evidence gap inspection and the bounded next-action selector.\n *\n * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip\n * (src/knowledge.ts). Host-owned observations only; a model's JSON is never\n * runner truth. See OMK_metacognitive_control_algorithms_2026-09-19.md §13.\n */\nimport { canonical, ensure, integer, lexical, member, text, unique } from \"./validation.ts\";\n\nexport type Stage = \"before-change\" | \"after-change\";\nexport interface Claim {\n\treadonly id: string;\n\t/** Hash/fingerprint computed by the host over the relevant subject and environment. */\n\treadonly binding: string;\n\treadonly phase: \"precondition\" | \"postcondition\";\n\treadonly statement: string;\n\treadonly required: boolean;\n\treadonly impact: number;\n\treadonly needsReference: boolean;\n\treadonly requiresVersion: boolean;\n\treadonly version: string | null;\n\treadonly minSourceFamilies: number;\n\treadonly requiredCheckIds: readonly string[];\n\treadonly needsUserDecision: boolean;\n\t/** Only explicit, host-approved public text can leave the repository. */\n\treadonly publicQuery: string | null;\n}\nexport interface SourceIdentity {\n\treadonly id: string;\n\treadonly family: string;\n\treadonly kind: \"repository\" | \"official\" | \"community\" | \"model\";\n}\ninterface ObservationBase {\n\treadonly id: string;\n\treadonly claimId: string;\n\treadonly binding: string;\n\treadonly observedAtMs: number;\n\treadonly expiresAtMs: number;\n}\nexport interface ReferenceObservation extends ObservationBase {\n\treadonly kind: \"reference\";\n\treadonly sourceId: string;\n\treadonly version: string | null;\n\treadonly stance: \"support\" | \"refute\";\n\treadonly documentDigest: string;\n\treadonly locator: string;\n}\nexport interface CheckObservation extends ObservationBase {\n\treadonly kind: \"check\";\n\treadonly runnerId: string;\n\treadonly checkId: string;\n\t/** Host-ordered snapshot. In OMK, project the existing strict evidence ledger here. */\n\treadonly sequence: number;\n\treadonly verdict: \"pass\" | \"fail\" | \"pending\";\n}\nexport interface DecisionObservation extends ObservationBase {\n\treadonly kind: \"decision\";\n\treadonly actorId: string;\n\treadonly accepted: boolean;\n}\nexport type Observation = ReferenceObservation | CheckObservation | DecisionObservation;\nexport type GapReason =\n\t| \"unassessed-step\"\n\t| \"unknown-version\"\n\t| \"unsupported-reference\"\n\t| \"contradictory-reference\"\n\t| \"missing-check\"\n\t| \"failed-check\"\n\t| \"pending-check\"\n\t| \"missing-user-decision\";\nexport interface KnowledgeGap {\n\treadonly claimId: string;\n\treadonly binding: string;\n\treadonly reason: GapReason;\n\treadonly required: boolean;\n\treadonly impact: number;\n\treadonly checkId: string | null;\n}\nexport interface KnowledgeReport {\n\treadonly state: \"supported\" | \"gaps\";\n\treadonly gaps: readonly KnowledgeGap[];\n\treadonly supportedClaimIds: readonly string[];\n\treadonly rejectedObservations: readonly { id: string; reason: string }[];\n}\nexport interface KnowledgeInput {\n\treadonly stage: Stage;\n\treadonly requiresAssessment: boolean;\n\treadonly nowMs: number;\n\treadonly claims: readonly Claim[];\n\t/** Admitted host observations only. Never pass a model's JSON here as runner truth. */\n\treadonly observations: readonly Observation[];\n\treadonly sources: readonly SourceIdentity[];\n\treadonly trustedRunnerIds: readonly string[];\n\treadonly decisionActorIds: readonly string[];\n}\n\nexport function inspectKnowledge(input: KnowledgeInput): KnowledgeReport {\n\tmember(input.stage, [\"before-change\", \"after-change\"], \"stage\");\n\tinteger(input.nowMs, \"nowMs\");\n\tensure(typeof input.requiresAssessment === \"boolean\", \"requiresAssessment must be boolean\");\n\tensure(input.claims.length <= 128 && input.observations.length <= 4096, \"knowledge input too large\");\n\tunique(\n\t\tinput.claims.map((c) => c.id),\n\t\t\"claim ids\",\n\t\t128,\n\t);\n\tunique(\n\t\tinput.sources.map((s) => s.id),\n\t\t\"source ids\",\n\t\t512,\n\t);\n\tunique(input.trustedRunnerIds, \"runner ids\");\n\tunique(input.decisionActorIds, \"decision actor ids\");\n\tfor (const c of input.claims) {\n\t\ttext(c.binding, \"binding\");\n\t\ttext(c.statement, \"statement\");\n\t\tmember(c.phase, [\"precondition\", \"postcondition\"], \"claim phase\");\n\t\tfor (const v of [c.required, c.needsReference, c.requiresVersion, c.needsUserDecision]) {\n\t\t\tensure(typeof v === \"boolean\", \"invalid claim flag\");\n\t\t}\n\t\tensure(Number.isFinite(c.impact) && c.impact >= 0 && c.impact <= 1_000_000, \"invalid impact\");\n\t\tinteger(c.minSourceFamilies, \"minSourceFamilies\", 16);\n\t\tensure(!c.needsReference || c.minSourceFamilies > 0, \"reference needs at least one source family\");\n\t\tif (c.version !== null) text(c.version, \"version\", 128);\n\t\tif (c.publicQuery !== null) text(c.publicQuery, \"publicQuery\", 500);\n\t\tunique(c.requiredCheckIds, \"check ids\", 128);\n\t\tensure(\n\t\t\tc.needsReference || c.requiredCheckIds.length > 0 || c.needsUserDecision,\n\t\t\t\"claim has no evidence predicate\",\n\t\t);\n\t}\n\tconst sources = new Map(\n\t\tinput.sources.map((s) => {\n\t\t\ttext(s.family, \"source family\");\n\t\t\tmember(s.kind, [\"repository\", \"official\", \"community\", \"model\"], \"source kind\");\n\t\t\treturn [s.id, s] as const;\n\t\t}),\n\t);\n\tconst observations = new Map<string, Observation>();\n\tconst sequences = new Map<string, string>();\n\tfor (const obs of input.observations) {\n\t\ttext(obs.id, \"observation id\");\n\t\ttext(obs.claimId, \"observation claim\");\n\t\ttext(obs.binding, \"observation binding\");\n\t\tinteger(obs.observedAtMs, \"observedAtMs\");\n\t\tinteger(obs.expiresAtMs, \"expiresAtMs\");\n\t\tensure(obs.expiresAtMs >= obs.observedAtMs, \"invalid observation validity interval\");\n\t\tmember(obs.kind, [\"reference\", \"check\", \"decision\"], \"observation kind\");\n\t\tif (obs.kind === \"reference\") {\n\t\t\ttext(obs.sourceId, \"sourceId\");\n\t\t\ttext(obs.documentDigest, \"documentDigest\");\n\t\t\ttext(obs.locator, \"locator\");\n\t\t\tif (obs.version !== null) text(obs.version, \"observation version\", 128);\n\t\t\tmember(obs.stance, [\"support\", \"refute\"], \"stance\");\n\t\t} else if (obs.kind === \"check\") {\n\t\t\ttext(obs.runnerId, \"runnerId\");\n\t\t\ttext(obs.checkId, \"checkId\");\n\t\t\tinteger(obs.sequence, \"sequence\");\n\t\t\tmember(obs.verdict, [\"pass\", \"fail\", \"pending\"], \"check verdict\");\n\t\t\tconst key = canonical([obs.claimId, obs.binding, obs.checkId, obs.sequence]);\n\t\t\tconst previous = sequences.get(key);\n\t\t\tensure(previous === undefined || previous === canonical(obs), \"conflicting check sequence\");\n\t\t\tsequences.set(key, canonical(obs));\n\t\t} else {\n\t\t\ttext(obs.actorId, \"actorId\");\n\t\t\tensure(typeof obs.accepted === \"boolean\", \"invalid decision\");\n\t\t}\n\t\tconst previous = observations.get(obs.id);\n\t\tensure(previous === undefined || canonical(previous) === canonical(obs), \"conflicting observation id\");\n\t\tobservations.set(obs.id, obs);\n\t}\n\tconst relevantClaims = input.claims.filter((c) => input.stage === \"after-change\" || c.phase === \"precondition\");\n\tconst rejectedObservations: { id: string; reason: string }[] = [];\n\tconst admissible = new Map<string, Observation[]>();\n\tconst claimMap = new Map(relevantClaims.map((c) => [c.id, c]));\n\tfor (const obs of observations.values()) {\n\t\tconst c = claimMap.get(obs.claimId);\n\t\tlet reason: string | undefined;\n\t\tif (!c) reason = \"irrelevant-claim-or-stage\";\n\t\telse if (obs.binding !== c.binding) reason = \"stale-binding\";\n\t\telse if (obs.observedAtMs > input.nowMs || obs.expiresAtMs <= input.nowMs) reason = \"expired-or-future\";\n\t\telse if (obs.kind === \"reference\") {\n\t\t\tconst source = sources.get(obs.sourceId);\n\t\t\tif (!source || (source.kind !== \"repository\" && source.kind !== \"official\")) reason = \"inadmissible-source\";\n\t\t\telse if (c.requiresVersion && (c.version === null || obs.version !== c.version)) reason = \"version-mismatch\";\n\t\t} else if (obs.kind === \"check\" && !input.trustedRunnerIds.includes(obs.runnerId)) reason = \"untrusted-runner\";\n\t\telse if (obs.kind === \"decision\" && !input.decisionActorIds.includes(obs.actorId)) {\n\t\t\treason = \"untrusted-decision-actor\";\n\t\t}\n\t\tif (reason) rejectedObservations.push({ id: obs.id, reason });\n\t\telse admissible.set(obs.claimId, [...(admissible.get(obs.claimId) ?? []), obs]);\n\t}\n\tconst gaps: KnowledgeGap[] = [];\n\tconst supportedClaimIds: string[] = [];\n\tif (input.requiresAssessment && relevantClaims.filter((c) => c.required).length === 0) {\n\t\tgaps.push({\n\t\t\tclaimId: \"$step\",\n\t\t\tbinding: \"unassessed\",\n\t\t\treason: \"unassessed-step\",\n\t\t\trequired: true,\n\t\t\timpact: 1_000_000,\n\t\t\tcheckId: null,\n\t\t});\n\t}\n\tfor (const c of relevantClaims) {\n\t\tconst before = gaps.length;\n\t\tconst evidence = admissible.get(c.id) ?? [];\n\t\tconst add = (reason: GapReason, checkId: string | null = null): void => {\n\t\t\tgaps.push({ claimId: c.id, binding: c.binding, reason, required: c.required, impact: c.impact, checkId });\n\t\t};\n\t\tif (c.requiresVersion && c.version === null) add(\"unknown-version\");\n\t\tif (c.needsReference) {\n\t\t\tconst refs = evidence.filter((obs): obs is ReferenceObservation => obs.kind === \"reference\");\n\t\t\tconst support = new Set(\n\t\t\t\trefs.filter((r) => r.stance === \"support\").map((r) => sources.get(r.sourceId)!.family),\n\t\t\t);\n\t\t\tif (refs.some((r) => r.stance === \"refute\")) add(\"contradictory-reference\");\n\t\t\telse if (support.size < c.minSourceFamilies) add(\"unsupported-reference\");\n\t\t}\n\t\tfor (const checkId of c.requiredCheckIds) {\n\t\t\tconst records = evidence\n\t\t\t\t.filter((obs): obs is CheckObservation => obs.kind === \"check\" && obs.checkId === checkId)\n\t\t\t\t.sort((a, b) => a.sequence - b.sequence);\n\t\t\tconst latest = records.at(-1);\n\t\t\tif (!latest) add(\"missing-check\", checkId);\n\t\t\telse if (latest.verdict === \"fail\") add(\"failed-check\", checkId);\n\t\t\telse if (latest.verdict === \"pending\") add(\"pending-check\", checkId);\n\t\t}\n\t\tif (c.needsUserDecision) {\n\t\t\tconst decisions = evidence.filter((obs): obs is DecisionObservation => obs.kind === \"decision\");\n\t\t\tif (!decisions.some((d) => d.accepted) || decisions.some((d) => !d.accepted)) add(\"missing-user-decision\");\n\t\t}\n\t\tif (before === gaps.length) supportedClaimIds.push(c.id);\n\t}\n\tgaps.sort(\n\t\t(a, b) =>\n\t\t\tNumber(b.required) - Number(a.required) ||\n\t\t\tb.impact - a.impact ||\n\t\t\tlexical(a.claimId, b.claimId) ||\n\t\t\tlexical(a.reason, b.reason),\n\t);\n\treturn {\n\t\tstate: gaps.some((g) => g.required) ? \"gaps\" : \"supported\",\n\t\tgaps,\n\t\tsupportedClaimIds: supportedClaimIds.sort(lexical),\n\t\trejectedObservations,\n\t};\n}\n"]}

package/dist/metacognition/obligations.d.ts

@@ -0,0 +1,82 @@
+export type ObservationSource = "host-observed" | "analyzer-inferred" | "model-hypothesized";
+export type Coverage = "covered" | "partial" | "unsupported" | "unknown";
+/** §4.2: one observable change atom, not a filename or keyword. */
+export interface ChangeAtom {
+    readonly id: string;
+    readonly targetId: string;
+    readonly operation: string;
+    readonly trustBoundary: string;
+    readonly temporal: "synchronous" | "async" | "concurrent" | "retried" | "none";
+    readonly externalEffect: "none" | "read" | "write" | "network" | "payment" | "delete";
+    readonly source: ObservationSource;
+    readonly analyzerCoverage: Coverage;
+}
+/** A versioned host rule: when its predicates hold, instantiate obligations. */
+export interface ObligationRule {
+    readonly ruleId: string;
+    readonly ruleVersion: string;
+    readonly description: string;
+    readonly match: {
+        readonly temporal?: readonly ChangeAtom["temporal"][];
+        readonly externalEffect?: readonly ChangeAtom["externalEffect"][];
+        readonly trustBoundary?: readonly string[];
+        readonly operation?: readonly string[];
+    };
+    /** Obligations instantiated when this rule fires. */
+    readonly produce: readonly {
+        readonly obligationId: string;
+        readonly statement: string;
+        readonly kind: "precondition" | "postcondition";
+        readonly checkMethodId: string | null;
+        readonly required: boolean;
+        readonly impact: number;
+        readonly minSourceFamilies?: number;
+        readonly requiresVersion?: boolean;
+    }[];
+}
+export type ObligationStatus = "candidate" | "required" | "satisfied" | "violated" | "blocked-high-risk";
+export interface Obligation {
+    readonly id: string;
+    readonly atomId: string;
+    readonly ruleId: string;
+    readonly ruleVersion: string;
+    readonly statement: string;
+    readonly kind: "precondition" | "postcondition";
+    readonly checkMethodId: string | null;
+    readonly scope: string;
+    readonly triggerObservationIds: readonly string[];
+    readonly required: boolean;
+    readonly impact: number;
+    readonly novelty: number;
+    readonly normalizedCost: number;
+    readonly coverageFraction: number;
+    status: ObligationStatus;
+}
+export interface ObligationReport {
+    readonly required: readonly Obligation[];
+    readonly candidates: readonly Obligation[];
+    /** Effects/rules we could not map — never claim completeness. */
+    readonly unmappedEffects: readonly string[];
+    readonly unsupportedSyntax: readonly string[];
+    readonly unobservedConsumers: readonly string[];
+    readonly coverage: "complete" | "partial" | "unknown";
+}
+export declare function validateAtom(atom: ChangeAtom): void;
+/**
+ * Instantiate host rules over observed atoms. Rules fire only on atoms whose
+ * predicates are satisfied; `model-hypothesized` atoms produce candidates,
+ * never required obligations. High-risk effects on unverified hypotheses are
+ * surfaced as `blocked-high-risk` candidates so the host can gate the effect.
+ */
+export declare function instantiateObligations(atoms: readonly ChangeAtom[], rules: readonly ObligationRule[], nowMs: number): ObligationReport;
+/**
+ * §4.4 ranking score. NOT a failure probability — an explainable ordering key:
+ * J(o) = impact·(1-coverage)·(1+novelty) / (ε + normalizedCost).
+ * Priority classes are applied by the caller before this score is consulted.
+ */
+export declare function obligationPriority(o: Obligation, epsilon?: number): number;
+/** Close an obligation when its bound check passes; open violations when it fails. */
+export declare function settleObligation(obligations: readonly Obligation[], obligationId: string, checkOutcome: "pass" | "fail" | "unverifiable"): readonly Obligation[];
+/** Structural fingerprint for de-duplication across checkpoints. */
+export declare function obligationFingerprint(o: Obligation): string;
+//# sourceMappingURL=obligations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"obligations.d.ts","sourceRoot":"","sources":["../../src/metacognition/obligations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Algorithm A — missing-condition discovery and obligation generation.\n * Spec: OMK_metacognitive_control_algorithms_2026-09-19.md §4.\n *\n * Change atoms (target + operation + trust boundary + temporal property +\n * external effect + observation source + analyzer coverage) are matched\n * against a versioned host rule set. Host facts promote candidates to\n * required obligations; model hypotheses stay candidates. Model proposals\n * can never remove user or policy obligations.\n */\nimport { canonical, ensure, finite, integer, lexical, member, text, unique } from \"./validation.ts\";\n\nexport type ObservationSource = \"host-observed\" | \"analyzer-inferred\" | \"model-hypothesized\";\nexport type Coverage = \"covered\" | \"partial\" | \"unsupported\" | \"unknown\";\n\n/** §4.2: one observable change atom, not a filename or keyword. */\nexport interface ChangeAtom {\n\treadonly id: string;\n\treadonly targetId: string;\n\treadonly operation: string;\n\treadonly trustBoundary: string;\n\treadonly temporal: \"synchronous\" | \"async\" | \"concurrent\" | \"retried\" | \"none\";\n\treadonly externalEffect: \"none\" | \"read\" | \"write\" | \"network\" | \"payment\" | \"delete\";\n\treadonly source: ObservationSource;\n\treadonly analyzerCoverage: Coverage;\n}\n/** A versioned host rule: when its predicates hold, instantiate obligations. */\nexport interface ObligationRule {\n\treadonly ruleId: string;\n\treadonly ruleVersion: string;\n\treadonly description: string;\n\treadonly match: {\n\t\treadonly temporal?: readonly ChangeAtom[\"temporal\"][];\n\t\treadonly externalEffect?: readonly ChangeAtom[\"externalEffect\"][];\n\t\treadonly trustBoundary?: readonly string[];\n\t\treadonly operation?: readonly string[];\n\t};\n\t/** Obligations instantiated when this rule fires. */\n\treadonly produce: readonly {\n\t\treadonly obligationId: string;\n\t\treadonly statement: string;\n\t\treadonly kind: \"precondition\" | \"postcondition\";\n\t\treadonly checkMethodId: string | null;\n\t\treadonly required: boolean;\n\t\treadonly impact: number;\n\t\treadonly minSourceFamilies?: number;\n\t\treadonly requiresVersion?: boolean;\n\t}[];\n}\nexport type ObligationStatus = \"candidate\" | \"required\" | \"satisfied\" | \"violated\" | \"blocked-high-risk\";\nexport interface Obligation {\n\treadonly id: string;\n\treadonly atomId: string;\n\treadonly ruleId: string;\n\treadonly ruleVersion: string;\n\treadonly statement: string;\n\treadonly kind: \"precondition\" | \"postcondition\";\n\treadonly checkMethodId: string | null;\n\treadonly scope: string;\n\treadonly triggerObservationIds: readonly string[];\n\treadonly required: boolean;\n\treadonly impact: number;\n\treadonly novelty: number;\n\treadonly normalizedCost: number;\n\treadonly coverageFraction: number;\n\tstatus: ObligationStatus;\n}\nexport interface ObligationReport {\n\treadonly required: readonly Obligation[];\n\treadonly candidates: readonly Obligation[];\n\t/** Effects/rules we could not map — never claim completeness. */\n\treadonly unmappedEffects: readonly string[];\n\treadonly unsupportedSyntax: readonly string[];\n\treadonly unobservedConsumers: readonly string[];\n\treadonly coverage: \"complete\" | \"partial\" | \"unknown\";\n}\n\nconst ATOM_BOUND = 512;\nconst RULE_BOUND = 256;\n\nexport function validateAtom(atom: ChangeAtom): void {\n\ttext(atom.id, \"atom id\", 128);\n\ttext(atom.targetId, \"targetId\", 512);\n\ttext(atom.operation, \"operation\", 128);\n\ttext(atom.trustBoundary, \"trustBoundary\", 256);\n\tmember(atom.temporal, [\"synchronous\", \"async\", \"concurrent\", \"retried\", \"none\"], \"temporal\");\n\tmember(atom.externalEffect, [\"none\", \"read\", \"write\", \"network\", \"payment\", \"delete\"], \"externalEffect\");\n\tmember(atom.source, [\"host-observed\", \"analyzer-inferred\", \"model-hypothesized\"], \"atom source\");\n\tmember(atom.analyzerCoverage, [\"covered\", \"partial\", \"unsupported\", \"unknown\"], \"analyzerCoverage\");\n}\n\n/**\n * Instantiate host rules over observed atoms. Rules fire only on atoms whose\n * predicates are satisfied; `model-hypothesized` atoms produce candidates,\n * never required obligations. High-risk effects on unverified hypotheses are\n * surfaced as `blocked-high-risk` candidates so the host can gate the effect.\n */\nexport function instantiateObligations(\n\tatoms: readonly ChangeAtom[],\n\trules: readonly ObligationRule[],\n\tnowMs: number,\n): ObligationReport {\n\tinteger(nowMs, \"nowMs\");\n\tensure(atoms.length <= ATOM_BOUND, \"too many atoms\");\n\tensure(rules.length <= RULE_BOUND, \"too many rules\");\n\tunique(\n\t\tatoms.map((a) => a.id),\n\t\t\"atom ids\",\n\t);\n\tunique(\n\t\trules.map((r) => r.ruleId),\n\t\t\"rule ids\",\n\t);\n\tfor (const atom of atoms) validateAtom(atom);\n\tfor (const rule of rules) {\n\t\ttext(rule.ruleVersion, \"ruleVersion\", 64);\n\t\ttext(rule.description, \"rule description\", 512);\n\t\tensure(rule.produce.length > 0 && rule.produce.length <= 32, \"rule produce bounds\");\n\t}\n\tconst required: Obligation[] = [];\n\tconst candidates: Obligation[] = [];\n\tconst unmappedEffects: string[] = [];\n\tconst unsupportedSyntax: string[] = [];\n\tconst _unobservedConsumers: string[] = [];\n\tlet sawUnknownCoverage = false;\n\tfor (const atom of atoms) {\n\t\tif (atom.analyzerCoverage === \"unknown\") sawUnknownCoverage = true;\n\t\tif (atom.analyzerCoverage === \"unsupported\") unsupportedSyntax.push(atom.id);\n\t\tlet matched = false;\n\t\tfor (const rule of rules) {\n\t\t\tconst m = rule.match;\n\t\t\tif (m.temporal && !m.temporal.includes(atom.temporal)) continue;\n\t\t\tif (m.externalEffect && !m.externalEffect.includes(atom.externalEffect)) continue;\n\t\t\tif (m.trustBoundary && !m.trustBoundary.includes(atom.trustBoundary)) continue;\n\t\t\tif (m.operation && !m.operation.includes(atom.operation)) continue;\n\t\t\tmatched = true;\n\t\t\tfor (const prod of rule.produce) {\n\t\t\t\tfinite(prod.impact, \"obligation impact\", 1_000_000);\n\t\t\t\tconst novelty = atom.source === \"model-hypothesized\" ? 1 : 0.5;\n\t\t\t\tconst obligation: Obligation = {\n\t\t\t\t\tid: `${rule.ruleId}:${atom.id}:${prod.obligationId}`,\n\t\t\t\t\tatomId: atom.id,\n\t\t\t\t\truleId: rule.ruleId,\n\t\t\t\t\truleVersion: rule.ruleVersion,\n\t\t\t\t\tstatement: prod.statement,\n\t\t\t\t\tkind: prod.kind,\n\t\t\t\t\tcheckMethodId: prod.checkMethodId,\n\t\t\t\t\tscope: atom.targetId,\n\t\t\t\t\ttriggerObservationIds: [atom.id],\n\t\t\t\t\trequired: prod.required,\n\t\t\t\t\timpact: prod.impact,\n\t\t\t\t\tnovelty,\n\t\t\t\t\tnormalizedCost: 1,\n\t\t\t\t\tcoverageFraction: 0,\n\t\t\t\t\tstatus:\n\t\t\t\t\t\tatom.source === \"model-hypothesized\"\n\t\t\t\t\t\t\t? atom.externalEffect === \"write\" ||\n\t\t\t\t\t\t\t\tatom.externalEffect === \"payment\" ||\n\t\t\t\t\t\t\t\tatom.externalEffect === \"delete\"\n\t\t\t\t\t\t\t\t? \"blocked-high-risk\"\n\t\t\t\t\t\t\t\t: \"candidate\"\n\t\t\t\t\t\t\t: prod.required\n\t\t\t\t\t\t\t\t? \"required\"\n\t\t\t\t\t\t\t\t: \"candidate\",\n\t\t\t\t};\n\t\t\t\t(atom.source === \"model-hypothesized\" ? candidates : required).push(obligation);\n\t\t\t}\n\t\t}\n\t\tif (!matched && atom.externalEffect !== \"none\") unmappedEffects.push(atom.id);\n\t}\n\tconst sortObligations = (a: Obligation, b: Obligation): number => b.impact - a.impact || lexical(a.id, b.id);\n\trequired.sort(sortObligations);\n\tcandidates.sort(sortObligations);\n\treturn {\n\t\trequired: required.filter((o) => o.status === \"required\"),\n\t\tcandidates,\n\t\tunmappedEffects: unmappedEffects.sort(lexical),\n\t\tunsupportedSyntax: unsupportedSyntax.sort(lexical),\n\t\tunobservedConsumers: [],\n\t\tcoverage:\n\t\t\tsawUnknownCoverage || unmappedEffects.length > 0 || unsupportedSyntax.length > 0 ? \"unknown\" : \"partial\",\n\t};\n}\n\n/**\n * §4.4 ranking score. NOT a failure probability — an explainable ordering key:\n * J(o) = impact·(1-coverage)·(1+novelty) / (ε + normalizedCost).\n * Priority classes are applied by the caller before this score is consulted.\n */\nexport function obligationPriority(o: Obligation, epsilon = 0.01): number {\n\tfinite(o.impact, \"impact\", 1_000_000);\n\tfinite(o.coverageFraction, \"coverage\", 1);\n\tfinite(o.novelty, \"novelty\", 1);\n\tfinite(o.normalizedCost, \"cost\", 1_000_000);\n\tfinite(epsilon, \"epsilon\", 1);\n\treturn (o.impact * (1 - o.coverageFraction) * (1 + o.novelty)) / (epsilon + o.normalizedCost);\n}\n\n/** Close an obligation when its bound check passes; open violations when it fails. */\nexport function settleObligation(\n\tobligations: readonly Obligation[],\n\tobligationId: string,\n\tcheckOutcome: \"pass\" | \"fail\" | \"unverifiable\",\n): readonly Obligation[] {\n\ttext(obligationId, \"obligationId\", 512);\n\treturn obligations.map((o) => {\n\t\tif (o.id !== obligationId) return o;\n\t\tconst status: ObligationStatus =\n\t\t\tcheckOutcome === \"pass\" ? \"satisfied\" : checkOutcome === \"fail\" ? \"violated\" : o.status;\n\t\treturn { ...o, status };\n\t});\n}\n\n/** Structural fingerprint for de-duplication across checkpoints. */\nexport function obligationFingerprint(o: Obligation): string {\n\treturn canonical([o.ruleId, o.ruleVersion, o.atomId, o.statement, o.scope]);\n}\n"]}

package/dist/metacognition/obligations.js

@@ -0,0 +1,139 @@
+/**
+ * Algorithm A — missing-condition discovery and obligation generation.
+ * Spec: OMK_metacognitive_control_algorithms_2026-09-19.md §4.
+ *
+ * Change atoms (target + operation + trust boundary + temporal property +
+ * external effect + observation source + analyzer coverage) are matched
+ * against a versioned host rule set. Host facts promote candidates to
+ * required obligations; model hypotheses stay candidates. Model proposals
+ * can never remove user or policy obligations.
+ */
+import { canonical, ensure, finite, integer, lexical, member, text, unique } from "./validation.js";
+const ATOM_BOUND = 512;
+const RULE_BOUND = 256;
+export function validateAtom(atom) {
+    text(atom.id, "atom id", 128);
+    text(atom.targetId, "targetId", 512);
+    text(atom.operation, "operation", 128);
+    text(atom.trustBoundary, "trustBoundary", 256);
+    member(atom.temporal, ["synchronous", "async", "concurrent", "retried", "none"], "temporal");
+    member(atom.externalEffect, ["none", "read", "write", "network", "payment", "delete"], "externalEffect");
+    member(atom.source, ["host-observed", "analyzer-inferred", "model-hypothesized"], "atom source");
+    member(atom.analyzerCoverage, ["covered", "partial", "unsupported", "unknown"], "analyzerCoverage");
+}
+/**
+ * Instantiate host rules over observed atoms. Rules fire only on atoms whose
+ * predicates are satisfied; `model-hypothesized` atoms produce candidates,
+ * never required obligations. High-risk effects on unverified hypotheses are
+ * surfaced as `blocked-high-risk` candidates so the host can gate the effect.
+ */
+export function instantiateObligations(atoms, rules, nowMs) {
+    integer(nowMs, "nowMs");
+    ensure(atoms.length <= ATOM_BOUND, "too many atoms");
+    ensure(rules.length <= RULE_BOUND, "too many rules");
+    unique(atoms.map((a) => a.id), "atom ids");
+    unique(rules.map((r) => r.ruleId), "rule ids");
+    for (const atom of atoms)
+        validateAtom(atom);
+    for (const rule of rules) {
+        text(rule.ruleVersion, "ruleVersion", 64);
+        text(rule.description, "rule description", 512);
+        ensure(rule.produce.length > 0 && rule.produce.length <= 32, "rule produce bounds");
+    }
+    const required = [];
+    const candidates = [];
+    const unmappedEffects = [];
+    const unsupportedSyntax = [];
+    const _unobservedConsumers = [];
+    let sawUnknownCoverage = false;
+    for (const atom of atoms) {
+        if (atom.analyzerCoverage === "unknown")
+            sawUnknownCoverage = true;
+        if (atom.analyzerCoverage === "unsupported")
+            unsupportedSyntax.push(atom.id);
+        let matched = false;
+        for (const rule of rules) {
+            const m = rule.match;
+            if (m.temporal && !m.temporal.includes(atom.temporal))
+                continue;
+            if (m.externalEffect && !m.externalEffect.includes(atom.externalEffect))
+                continue;
+            if (m.trustBoundary && !m.trustBoundary.includes(atom.trustBoundary))
+                continue;
+            if (m.operation && !m.operation.includes(atom.operation))
+                continue;
+            matched = true;
+            for (const prod of rule.produce) {
+                finite(prod.impact, "obligation impact", 1_000_000);
+                const novelty = atom.source === "model-hypothesized" ? 1 : 0.5;
+                const obligation = {
+                    id: `${rule.ruleId}:${atom.id}:${prod.obligationId}`,
+                    atomId: atom.id,
+                    ruleId: rule.ruleId,
+                    ruleVersion: rule.ruleVersion,
+                    statement: prod.statement,
+                    kind: prod.kind,
+                    checkMethodId: prod.checkMethodId,
+                    scope: atom.targetId,
+                    triggerObservationIds: [atom.id],
+                    required: prod.required,
+                    impact: prod.impact,
+                    novelty,
+                    normalizedCost: 1,
+                    coverageFraction: 0,
+                    status: atom.source === "model-hypothesized"
+                        ? atom.externalEffect === "write" ||
+                            atom.externalEffect === "payment" ||
+                            atom.externalEffect === "delete"
+                            ? "blocked-high-risk"
+                            : "candidate"
+                        : prod.required
+                            ? "required"
+                            : "candidate",
+                };
+                (atom.source === "model-hypothesized" ? candidates : required).push(obligation);
+            }
+        }
+        if (!matched && atom.externalEffect !== "none")
+            unmappedEffects.push(atom.id);
+    }
+    const sortObligations = (a, b) => b.impact - a.impact || lexical(a.id, b.id);
+    required.sort(sortObligations);
+    candidates.sort(sortObligations);
+    return {
+        required: required.filter((o) => o.status === "required"),
+        candidates,
+        unmappedEffects: unmappedEffects.sort(lexical),
+        unsupportedSyntax: unsupportedSyntax.sort(lexical),
+        unobservedConsumers: [],
+        coverage: sawUnknownCoverage || unmappedEffects.length > 0 || unsupportedSyntax.length > 0 ? "unknown" : "partial",
+    };
+}
+/**
+ * §4.4 ranking score. NOT a failure probability — an explainable ordering key:
+ * J(o) = impact·(1-coverage)·(1+novelty) / (ε + normalizedCost).
+ * Priority classes are applied by the caller before this score is consulted.
+ */
+export function obligationPriority(o, epsilon = 0.01) {
+    finite(o.impact, "impact", 1_000_000);
+    finite(o.coverageFraction, "coverage", 1);
+    finite(o.novelty, "novelty", 1);
+    finite(o.normalizedCost, "cost", 1_000_000);
+    finite(epsilon, "epsilon", 1);
+    return (o.impact * (1 - o.coverageFraction) * (1 + o.novelty)) / (epsilon + o.normalizedCost);
+}
+/** Close an obligation when its bound check passes; open violations when it fails. */
+export function settleObligation(obligations, obligationId, checkOutcome) {
+    text(obligationId, "obligationId", 512);
+    return obligations.map((o) => {
+        if (o.id !== obligationId)
+            return o;
+        const status = checkOutcome === "pass" ? "satisfied" : checkOutcome === "fail" ? "violated" : o.status;
+        return { ...o, status };
+    });
+}
+/** Structural fingerprint for de-duplication across checkpoints. */
+export function obligationFingerprint(o) {
+    return canonical([o.ruleId, o.ruleVersion, o.atomId, o.statement, o.scope]);
+}
+//# sourceMappingURL=obligations.js.map