open-multi-agent-kit 0.99.0 → 1.2.0

package/dist/metacognition/calibration.d.ts

@@ -0,0 +1,62 @@
+export interface ConditionKey {
+    readonly modelRevision: string;
+    readonly skillHashes: readonly string[];
+    readonly toolchain: string;
+    readonly taskBand: string;
+    readonly checkKind: string;
+    readonly checkHealth: "healthy" | "degraded" | "unverified";
+    readonly budgetBand: string;
+    readonly policyVersion: string;
+}
+export type BucketState = "insufficient-data" | "active" | "demoted";
+export interface CalibrationBucket {
+    readonly key: ConditionKey;
+    readonly keyHash: string;
+    readonly priorAlpha: number;
+    readonly priorBeta: number;
+    successes: number;
+    failures: number;
+    drift: number;
+    state: BucketState;
+    readonly demotedReason?: string;
+}
+export interface CalibrationStore {
+    readonly buckets: Readonly<Record<string, CalibrationBucket>>;
+    readonly minSamples: number;
+    readonly referenceMean: number;
+    readonly slack: number;
+    readonly threshold: number;
+}
+export declare function conditionKeyHash(key: ConditionKey): string;
+export declare function createCalibrationStore(options: {
+    readonly minSamples: number;
+    readonly priorAlpha: number;
+    readonly priorBeta: number;
+    readonly referenceMean: number;
+    readonly slack: number;
+    readonly threshold: number;
+}): CalibrationStore;
+/**
+ * Record one independent task outcome. Never count 100 runs of one task as
+ * 100 independent tasks; the caller supplies one pre-registered binary outcome
+ * per task. Environment failures belong in delivery metrics, not here.
+ */
+export declare function recordOutcome(store: CalibrationStore, key: ConditionKey, outcome: "success" | "failure", loss: number): CalibrationStore;
+/**
+ * Demote every bucket whose condition changed underneath it: new model
+ * revision, new check definition, or new major toolchain version. Explicit
+ * condition changes never wait for statistical drift detection.
+ */
+export declare function demoteOnConditionChange(store: CalibrationStore, change: {
+    modelRevision?: string;
+    checkKind?: string;
+    toolchain?: string;
+    policyVersion?: string;
+}): CalibrationStore;
+/** Posterior mean success rate for one bucket, or `insufficient-data`. */
+export declare function conditionalSuccessRate(store: CalibrationStore, key: ConditionKey): {
+    state: BucketState;
+    rate?: number;
+    samples: number;
+};
+//# sourceMappingURL=calibration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"calibration.d.ts","sourceRoot":"","sources":["../../src/metacognition/calibration.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,SAAS,GAAG,UAAU,GAAG,YAAY,CAAC;IAC5D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAC/B;AACD,MAAM,MAAM,WAAW,GAAG,mBAAmB,GAAG,QAAQ,GAAG,SAAS,CAAC;AACrE,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CAChC;AACD,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC9D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAkB1D;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B,GAAG,gBAAgB,CAenB;AAkBD;;;;GAIG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,gBAAgB,EACvB,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,SAAS,GAAG,SAAS,EAC9B,IAAI,EAAE,MAAM,GACV,gBAAgB,CAoBlB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAChG,gBAAgB,CAclB;AAED,0EAA0E;AAC1E,wBAAgB,sBAAsB,CACrC,KAAK,EAAE,gBAAgB,EACvB,GAAG,EAAE,YAAY,GACf;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAUxD","sourcesContent":["/**\n * Algorithms E and G — conditional capability/calibration records and\n * drift-triggered demotion. Spec §8, §10.3.\n *\n * Records are per condition bucket: model revision + loaded skill content\n * fingerprints + toolchain version + task/effect/difficulty band + check\n * type/health + budget band + selection policy version. A bucket with too few\n * samples stays `insufficient-data`; a new provider revision, check\n * definition, or major library version demotes the bucket immediately,\n * without waiting for statistical detection.\n */\nimport { betaPosteriorMean, driftStatistic } from \"./decision.ts\";\nimport { canonical, ensure, finite, integer, lexical, member, text } from \"./validation.ts\";\n\nexport interface ConditionKey {\n\treadonly modelRevision: string;\n\treadonly skillHashes: readonly string[];\n\treadonly toolchain: string;\n\treadonly taskBand: string;\n\treadonly checkKind: string;\n\treadonly checkHealth: \"healthy\" | \"degraded\" | \"unverified\";\n\treadonly budgetBand: string;\n\treadonly policyVersion: string;\n}\nexport type BucketState = \"insufficient-data\" | \"active\" | \"demoted\";\nexport interface CalibrationBucket {\n\treadonly key: ConditionKey;\n\treadonly keyHash: string;\n\treadonly priorAlpha: number;\n\treadonly priorBeta: number;\n\tsuccesses: number;\n\tfailures: number;\n\tdrift: number;\n\tstate: BucketState;\n\treadonly demotedReason?: string;\n}\nexport interface CalibrationStore {\n\treadonly buckets: Readonly<Record<string, CalibrationBucket>>;\n\treadonly minSamples: number;\n\treadonly referenceMean: number;\n\treadonly slack: number;\n\treadonly threshold: number;\n}\n\nexport function conditionKeyHash(key: ConditionKey): string {\n\ttext(key.modelRevision, \"modelRevision\", 128);\n\ttext(key.toolchain, \"toolchain\", 128);\n\ttext(key.taskBand, \"taskBand\", 128);\n\ttext(key.checkKind, \"checkKind\", 128);\n\tmember(key.checkHealth, [\"healthy\", \"degraded\", \"unverified\"], \"checkHealth\");\n\ttext(key.budgetBand, \"budgetBand\", 128);\n\ttext(key.policyVersion, \"policyVersion\", 64);\n\treturn canonical([\n\t\tkey.modelRevision,\n\t\t[...key.skillHashes].sort(lexical),\n\t\tkey.toolchain,\n\t\tkey.taskBand,\n\t\tkey.checkKind,\n\t\tkey.checkHealth,\n\t\tkey.budgetBand,\n\t\tkey.policyVersion,\n\t]);\n}\n\nexport function createCalibrationStore(options: {\n\treadonly minSamples: number;\n\treadonly priorAlpha: number;\n\treadonly priorBeta: number;\n\treadonly referenceMean: number;\n\treadonly slack: number;\n\treadonly threshold: number;\n}): CalibrationStore {\n\tinteger(options.minSamples, \"minSamples\", 100_000);\n\tfinite(options.priorAlpha, \"priorAlpha\", 1e9);\n\tfinite(options.priorBeta, \"priorBeta\", 1e9);\n\tensure(options.priorAlpha > 0 && options.priorBeta > 0, \"beta prior must be positive\");\n\tfinite(options.referenceMean, \"referenceMean\");\n\tfinite(options.slack, \"slack\");\n\tfinite(options.threshold, \"threshold\");\n\treturn {\n\t\tbuckets: {},\n\t\tminSamples: options.minSamples,\n\t\treferenceMean: options.referenceMean,\n\t\tslack: options.slack,\n\t\tthreshold: options.threshold,\n\t};\n}\n\nfunction bucketFor(store: CalibrationStore, key: ConditionKey): CalibrationBucket {\n\tconst keyHash = conditionKeyHash(key);\n\treturn (\n\t\tstore.buckets[keyHash] ?? {\n\t\t\tkey,\n\t\t\tkeyHash,\n\t\t\tpriorAlpha: 1,\n\t\t\tpriorBeta: 1,\n\t\t\tsuccesses: 0,\n\t\t\tfailures: 0,\n\t\t\tdrift: 0,\n\t\t\tstate: \"insufficient-data\",\n\t\t}\n\t);\n}\n\n/**\n * Record one independent task outcome. Never count 100 runs of one task as\n * 100 independent tasks; the caller supplies one pre-registered binary outcome\n * per task. Environment failures belong in delivery metrics, not here.\n */\nexport function recordOutcome(\n\tstore: CalibrationStore,\n\tkey: ConditionKey,\n\toutcome: \"success\" | \"failure\",\n\tloss: number,\n): CalibrationStore {\n\tmember(outcome, [\"success\", \"failure\"], \"outcome\");\n\tfinite(loss, \"loss\");\n\tconst bucket = bucketFor(store, key);\n\tif (bucket.state === \"demoted\") return store;\n\tconst next: CalibrationBucket = {\n\t\t...bucket,\n\t\tsuccesses: bucket.successes + (outcome === \"success\" ? 1 : 0),\n\t\tfailures: bucket.failures + (outcome === \"failure\" ? 1 : 0),\n\t\tdrift: driftStatistic(bucket.drift, loss, store.referenceMean, store.slack),\n\t\tstate: bucket.successes + bucket.failures + 1 >= store.minSamples ? \"active\" : \"insufficient-data\",\n\t};\n\tconst demoted = next.drift > store.threshold;\n\treturn {\n\t\t...store,\n\t\tbuckets: {\n\t\t\t...store.buckets,\n\t\t\t[next.keyHash]: demoted ? { ...next, state: \"demoted\", demotedReason: \"drift-threshold\" } : next,\n\t\t},\n\t};\n}\n\n/**\n * Demote every bucket whose condition changed underneath it: new model\n * revision, new check definition, or new major toolchain version. Explicit\n * condition changes never wait for statistical drift detection.\n */\nexport function demoteOnConditionChange(\n\tstore: CalibrationStore,\n\tchange: { modelRevision?: string; checkKind?: string; toolchain?: string; policyVersion?: string },\n): CalibrationStore {\n\tconst buckets: Record<string, CalibrationBucket> = {};\n\tfor (const [hash, bucket] of Object.entries(store.buckets)) {\n\t\tconst changed =\n\t\t\t(change.modelRevision !== undefined && bucket.key.modelRevision !== change.modelRevision) ||\n\t\t\t(change.checkKind !== undefined && bucket.key.checkKind !== change.checkKind) ||\n\t\t\t(change.toolchain !== undefined && bucket.key.toolchain !== change.toolchain) ||\n\t\t\t(change.policyVersion !== undefined && bucket.key.policyVersion !== change.policyVersion);\n\t\tbuckets[hash] =\n\t\t\tchanged && bucket.state !== \"demoted\"\n\t\t\t\t? { ...bucket, state: \"demoted\", demotedReason: \"condition-change\" }\n\t\t\t\t: bucket;\n\t}\n\treturn { ...store, buckets };\n}\n\n/** Posterior mean success rate for one bucket, or `insufficient-data`. */\nexport function conditionalSuccessRate(\n\tstore: CalibrationStore,\n\tkey: ConditionKey,\n): { state: BucketState; rate?: number; samples: number } {\n\tconst bucket = store.buckets[conditionKeyHash(key)];\n\tif (!bucket) return { state: \"insufficient-data\", samples: 0 };\n\tconst samples = bucket.successes + bucket.failures;\n\tif (bucket.state !== \"active\") return { state: bucket.state, samples };\n\treturn {\n\t\tstate: \"active\",\n\t\tsamples,\n\t\trate: betaPosteriorMean(bucket.priorAlpha, bucket.priorBeta, bucket.successes, bucket.failures),\n\t};\n}\n"]}

package/dist/metacognition/calibration.js

@@ -0,0 +1,122 @@
+/**
+ * Algorithms E and G — conditional capability/calibration records and
+ * drift-triggered demotion. Spec §8, §10.3.
+ *
+ * Records are per condition bucket: model revision + loaded skill content
+ * fingerprints + toolchain version + task/effect/difficulty band + check
+ * type/health + budget band + selection policy version. A bucket with too few
+ * samples stays `insufficient-data`; a new provider revision, check
+ * definition, or major library version demotes the bucket immediately,
+ * without waiting for statistical detection.
+ */
+import { betaPosteriorMean, driftStatistic } from "./decision.js";
+import { canonical, ensure, finite, integer, lexical, member, text } from "./validation.js";
+export function conditionKeyHash(key) {
+    text(key.modelRevision, "modelRevision", 128);
+    text(key.toolchain, "toolchain", 128);
+    text(key.taskBand, "taskBand", 128);
+    text(key.checkKind, "checkKind", 128);
+    member(key.checkHealth, ["healthy", "degraded", "unverified"], "checkHealth");
+    text(key.budgetBand, "budgetBand", 128);
+    text(key.policyVersion, "policyVersion", 64);
+    return canonical([
+        key.modelRevision,
+        [...key.skillHashes].sort(lexical),
+        key.toolchain,
+        key.taskBand,
+        key.checkKind,
+        key.checkHealth,
+        key.budgetBand,
+        key.policyVersion,
+    ]);
+}
+export function createCalibrationStore(options) {
+    integer(options.minSamples, "minSamples", 100_000);
+    finite(options.priorAlpha, "priorAlpha", 1e9);
+    finite(options.priorBeta, "priorBeta", 1e9);
+    ensure(options.priorAlpha > 0 && options.priorBeta > 0, "beta prior must be positive");
+    finite(options.referenceMean, "referenceMean");
+    finite(options.slack, "slack");
+    finite(options.threshold, "threshold");
+    return {
+        buckets: {},
+        minSamples: options.minSamples,
+        referenceMean: options.referenceMean,
+        slack: options.slack,
+        threshold: options.threshold,
+    };
+}
+function bucketFor(store, key) {
+    const keyHash = conditionKeyHash(key);
+    return (store.buckets[keyHash] ?? {
+        key,
+        keyHash,
+        priorAlpha: 1,
+        priorBeta: 1,
+        successes: 0,
+        failures: 0,
+        drift: 0,
+        state: "insufficient-data",
+    });
+}
+/**
+ * Record one independent task outcome. Never count 100 runs of one task as
+ * 100 independent tasks; the caller supplies one pre-registered binary outcome
+ * per task. Environment failures belong in delivery metrics, not here.
+ */
+export function recordOutcome(store, key, outcome, loss) {
+    member(outcome, ["success", "failure"], "outcome");
+    finite(loss, "loss");
+    const bucket = bucketFor(store, key);
+    if (bucket.state === "demoted")
+        return store;
+    const next = {
+        ...bucket,
+        successes: bucket.successes + (outcome === "success" ? 1 : 0),
+        failures: bucket.failures + (outcome === "failure" ? 1 : 0),
+        drift: driftStatistic(bucket.drift, loss, store.referenceMean, store.slack),
+        state: bucket.successes + bucket.failures + 1 >= store.minSamples ? "active" : "insufficient-data",
+    };
+    const demoted = next.drift > store.threshold;
+    return {
+        ...store,
+        buckets: {
+            ...store.buckets,
+            [next.keyHash]: demoted ? { ...next, state: "demoted", demotedReason: "drift-threshold" } : next,
+        },
+    };
+}
+/**
+ * Demote every bucket whose condition changed underneath it: new model
+ * revision, new check definition, or new major toolchain version. Explicit
+ * condition changes never wait for statistical drift detection.
+ */
+export function demoteOnConditionChange(store, change) {
+    const buckets = {};
+    for (const [hash, bucket] of Object.entries(store.buckets)) {
+        const changed = (change.modelRevision !== undefined && bucket.key.modelRevision !== change.modelRevision) ||
+            (change.checkKind !== undefined && bucket.key.checkKind !== change.checkKind) ||
+            (change.toolchain !== undefined && bucket.key.toolchain !== change.toolchain) ||
+            (change.policyVersion !== undefined && bucket.key.policyVersion !== change.policyVersion);
+        buckets[hash] =
+            changed && bucket.state !== "demoted"
+                ? { ...bucket, state: "demoted", demotedReason: "condition-change" }
+                : bucket;
+    }
+    return { ...store, buckets };
+}
+/** Posterior mean success rate for one bucket, or `insufficient-data`. */
+export function conditionalSuccessRate(store, key) {
+    const bucket = store.buckets[conditionKeyHash(key)];
+    if (!bucket)
+        return { state: "insufficient-data", samples: 0 };
+    const samples = bucket.successes + bucket.failures;
+    if (bucket.state !== "active")
+        return { state: bucket.state, samples };
+    return {
+        state: "active",
+        samples,
+        rate: betaPosteriorMean(bucket.priorAlpha, bucket.priorBeta, bucket.successes, bucket.failures),
+    };
+}
+//# sourceMappingURL=calibration.js.map

package/dist/metacognition/calibration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calibration.js","sourceRoot":"","sources":["../../src/metacognition/calibration.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Algorithms E and G — conditional capability/calibration records and\n * drift-triggered demotion. Spec §8, §10.3.\n *\n * Records are per condition bucket: model revision + loaded skill content\n * fingerprints + toolchain version + task/effect/difficulty band + check\n * type/health + budget band + selection policy version. A bucket with too few\n * samples stays `insufficient-data`; a new provider revision, check\n * definition, or major library version demotes the bucket immediately,\n * without waiting for statistical detection.\n */\nimport { betaPosteriorMean, driftStatistic } from \"./decision.ts\";\nimport { canonical, ensure, finite, integer, lexical, member, text } from \"./validation.ts\";\n\nexport interface ConditionKey {\n\treadonly modelRevision: string;\n\treadonly skillHashes: readonly string[];\n\treadonly toolchain: string;\n\treadonly taskBand: string;\n\treadonly checkKind: string;\n\treadonly checkHealth: \"healthy\" | \"degraded\" | \"unverified\";\n\treadonly budgetBand: string;\n\treadonly policyVersion: string;\n}\nexport type BucketState = \"insufficient-data\" | \"active\" | \"demoted\";\nexport interface CalibrationBucket {\n\treadonly key: ConditionKey;\n\treadonly keyHash: string;\n\treadonly priorAlpha: number;\n\treadonly priorBeta: number;\n\tsuccesses: number;\n\tfailures: number;\n\tdrift: number;\n\tstate: BucketState;\n\treadonly demotedReason?: string;\n}\nexport interface CalibrationStore {\n\treadonly buckets: Readonly<Record<string, CalibrationBucket>>;\n\treadonly minSamples: number;\n\treadonly referenceMean: number;\n\treadonly slack: number;\n\treadonly threshold: number;\n}\n\nexport function conditionKeyHash(key: ConditionKey): string {\n\ttext(key.modelRevision, \"modelRevision\", 128);\n\ttext(key.toolchain, \"toolchain\", 128);\n\ttext(key.taskBand, \"taskBand\", 128);\n\ttext(key.checkKind, \"checkKind\", 128);\n\tmember(key.checkHealth, [\"healthy\", \"degraded\", \"unverified\"], \"checkHealth\");\n\ttext(key.budgetBand, \"budgetBand\", 128);\n\ttext(key.policyVersion, \"policyVersion\", 64);\n\treturn canonical([\n\t\tkey.modelRevision,\n\t\t[...key.skillHashes].sort(lexical),\n\t\tkey.toolchain,\n\t\tkey.taskBand,\n\t\tkey.checkKind,\n\t\tkey.checkHealth,\n\t\tkey.budgetBand,\n\t\tkey.policyVersion,\n\t]);\n}\n\nexport function createCalibrationStore(options: {\n\treadonly minSamples: number;\n\treadonly priorAlpha: number;\n\treadonly priorBeta: number;\n\treadonly referenceMean: number;\n\treadonly slack: number;\n\treadonly threshold: number;\n}): CalibrationStore {\n\tinteger(options.minSamples, \"minSamples\", 100_000);\n\tfinite(options.priorAlpha, \"priorAlpha\", 1e9);\n\tfinite(options.priorBeta, \"priorBeta\", 1e9);\n\tensure(options.priorAlpha > 0 && options.priorBeta > 0, \"beta prior must be positive\");\n\tfinite(options.referenceMean, \"referenceMean\");\n\tfinite(options.slack, \"slack\");\n\tfinite(options.threshold, \"threshold\");\n\treturn {\n\t\tbuckets: {},\n\t\tminSamples: options.minSamples,\n\t\treferenceMean: options.referenceMean,\n\t\tslack: options.slack,\n\t\tthreshold: options.threshold,\n\t};\n}\n\nfunction bucketFor(store: CalibrationStore, key: ConditionKey): CalibrationBucket {\n\tconst keyHash = conditionKeyHash(key);\n\treturn (\n\t\tstore.buckets[keyHash] ?? {\n\t\t\tkey,\n\t\t\tkeyHash,\n\t\t\tpriorAlpha: 1,\n\t\t\tpriorBeta: 1,\n\t\t\tsuccesses: 0,\n\t\t\tfailures: 0,\n\t\t\tdrift: 0,\n\t\t\tstate: \"insufficient-data\",\n\t\t}\n\t);\n}\n\n/**\n * Record one independent task outcome. Never count 100 runs of one task as\n * 100 independent tasks; the caller supplies one pre-registered binary outcome\n * per task. Environment failures belong in delivery metrics, not here.\n */\nexport function recordOutcome(\n\tstore: CalibrationStore,\n\tkey: ConditionKey,\n\toutcome: \"success\" | \"failure\",\n\tloss: number,\n): CalibrationStore {\n\tmember(outcome, [\"success\", \"failure\"], \"outcome\");\n\tfinite(loss, \"loss\");\n\tconst bucket = bucketFor(store, key);\n\tif (bucket.state === \"demoted\") return store;\n\tconst next: CalibrationBucket = {\n\t\t...bucket,\n\t\tsuccesses: bucket.successes + (outcome === \"success\" ? 1 : 0),\n\t\tfailures: bucket.failures + (outcome === \"failure\" ? 1 : 0),\n\t\tdrift: driftStatistic(bucket.drift, loss, store.referenceMean, store.slack),\n\t\tstate: bucket.successes + bucket.failures + 1 >= store.minSamples ? \"active\" : \"insufficient-data\",\n\t};\n\tconst demoted = next.drift > store.threshold;\n\treturn {\n\t\t...store,\n\t\tbuckets: {\n\t\t\t...store.buckets,\n\t\t\t[next.keyHash]: demoted ? { ...next, state: \"demoted\", demotedReason: \"drift-threshold\" } : next,\n\t\t},\n\t};\n}\n\n/**\n * Demote every bucket whose condition changed underneath it: new model\n * revision, new check definition, or new major toolchain version. Explicit\n * condition changes never wait for statistical drift detection.\n */\nexport function demoteOnConditionChange(\n\tstore: CalibrationStore,\n\tchange: { modelRevision?: string; checkKind?: string; toolchain?: string; policyVersion?: string },\n): CalibrationStore {\n\tconst buckets: Record<string, CalibrationBucket> = {};\n\tfor (const [hash, bucket] of Object.entries(store.buckets)) {\n\t\tconst changed =\n\t\t\t(change.modelRevision !== undefined && bucket.key.modelRevision !== change.modelRevision) ||\n\t\t\t(change.checkKind !== undefined && bucket.key.checkKind !== change.checkKind) ||\n\t\t\t(change.toolchain !== undefined && bucket.key.toolchain !== change.toolchain) ||\n\t\t\t(change.policyVersion !== undefined && bucket.key.policyVersion !== change.policyVersion);\n\t\tbuckets[hash] =\n\t\t\tchanged && bucket.state !== \"demoted\"\n\t\t\t\t? { ...bucket, state: \"demoted\", demotedReason: \"condition-change\" }\n\t\t\t\t: bucket;\n\t}\n\treturn { ...store, buckets };\n}\n\n/** Posterior mean success rate for one bucket, or `insufficient-data`. */\nexport function conditionalSuccessRate(\n\tstore: CalibrationStore,\n\tkey: ConditionKey,\n): { state: BucketState; rate?: number; samples: number } {\n\tconst bucket = store.buckets[conditionKeyHash(key)];\n\tif (!bucket) return { state: \"insufficient-data\", samples: 0 };\n\tconst samples = bucket.successes + bucket.failures;\n\tif (bucket.state !== \"active\") return { state: bucket.state, samples };\n\treturn {\n\t\tstate: \"active\",\n\t\tsamples,\n\t\trate: betaPosteriorMean(bucket.priorAlpha, bucket.priorBeta, bucket.successes, bucket.failures),\n\t};\n}\n"]}

package/dist/metacognition/checkpoint.d.ts

@@ -0,0 +1,60 @@
+/**
+ * §9.4 checkpoint ordering: refresh obligations from host observations,
+ * evaluate knowledge gaps, classify prediction mismatches, evaluate verifier
+ * blind spots and runner health, then select one bounded action.
+ *
+ * The host calls this at a safe decision boundary — never mid-stream, and
+ * never as a path for model reasoning to remove a `required` obligation.
+ */
+import type { ChangeAtom, ObligationRule } from "./obligations.ts";
+import { type ActionConstraints, type MetaAction, type MetaActionKind } from "./policy.ts";
+import type { MetaState } from "./state.ts";
+import { type FinishState } from "./state.ts";
+import { type MutantRecord, type VerifierEvaluation } from "./verifier.ts";
+export interface CheckpointInput {
+    readonly state: MetaState;
+    readonly atoms?: readonly ChangeAtom[];
+    readonly rules?: readonly ObligationRule[];
+    readonly nowMs: number;
+    readonly constraints: ActionConstraints;
+    readonly mutants?: readonly MutantRecord[];
+    readonly receipt?: {
+        receiptId: string;
+        candidateHash: string;
+        scope: string;
+    } | null;
+    readonly options?: {
+        readonly maxRepetitions?: number;
+        readonly switchCost?: number;
+        readonly estimatedSwitchGain?: number;
+        readonly voiCandidates?: readonly {
+            kind: MetaActionKind;
+            voi: number;
+        }[];
+        readonly progress?: {
+            readonly goalScope: string;
+            readonly candidateFamily: string;
+            readonly errorClass: string;
+            readonly approach: string;
+            readonly checkMethod: string;
+            readonly sourceFamily: string;
+        };
+    };
+}
+export interface CheckpointResult {
+    readonly state: MetaState;
+    readonly action: MetaAction;
+    readonly finish: FinishState;
+    readonly newObligations: number;
+    readonly newPredictions: number;
+    readonly mismatches: number;
+    readonly verifierEvaluations: readonly VerifierEvaluation[];
+}
+/**
+ * One checkpoint evaluation. Refreshes obligations from observed atoms when
+ * provided, resolves registered predictions against fresh observations when
+ * provided, evaluates verifier mutants when provided, then selects the next
+ * action under the §14 priority table.
+ */
+export declare function checkpoint(input: CheckpointInput): CheckpointResult;
+//# sourceMappingURL=checkpoint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../src/metacognition/checkpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEnE,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAgB,MAAM,aAAa,CAAC;AACzG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,KAAK,WAAW,EAAkC,MAAM,YAAY,CAAC;AAE9E,OAAO,EAAoB,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAE7F,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACtF,QAAQ,CAAC,OAAO,CAAC,EAAE;QAClB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;QACtC,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS;YAAE,IAAI,EAAE,cAAc,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE;YACnB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;YAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;YACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;YAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;YAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;YAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;SAC9B,CAAC;KACF,CAAC;CACF;AACD,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,mBAAmB,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC5D;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,CA4CnE","sourcesContent":["/**\n * §9.4 checkpoint ordering: refresh obligations from host observations,\n * evaluate knowledge gaps, classify prediction mismatches, evaluate verifier\n * blind spots and runner health, then select one bounded action.\n *\n * The host calls this at a safe decision boundary — never mid-stream, and\n * never as a path for model reasoning to remove a `required` obligation.\n */\nimport type { ChangeAtom, ObligationRule } from \"./obligations.ts\";\nimport { instantiateObligations } from \"./obligations.ts\";\nimport { type ActionConstraints, type MetaAction, type MetaActionKind, selectAction } from \"./policy.ts\";\nimport type { MetaState } from \"./state.ts\";\nimport { type FinishState, finishState, validateMetaState } from \"./state.ts\";\nimport { integer } from \"./validation.ts\";\nimport { evaluateVerifier, type MutantRecord, type VerifierEvaluation } from \"./verifier.ts\";\n\nexport interface CheckpointInput {\n\treadonly state: MetaState;\n\treadonly atoms?: readonly ChangeAtom[];\n\treadonly rules?: readonly ObligationRule[];\n\treadonly nowMs: number;\n\treadonly constraints: ActionConstraints;\n\treadonly mutants?: readonly MutantRecord[];\n\treadonly receipt?: { receiptId: string; candidateHash: string; scope: string } | null;\n\treadonly options?: {\n\t\treadonly maxRepetitions?: number;\n\t\treadonly switchCost?: number;\n\t\treadonly estimatedSwitchGain?: number;\n\t\treadonly voiCandidates?: readonly { kind: MetaActionKind; voi: number }[];\n\t\treadonly progress?: {\n\t\t\treadonly goalScope: string;\n\t\t\treadonly candidateFamily: string;\n\t\t\treadonly errorClass: string;\n\t\t\treadonly approach: string;\n\t\t\treadonly checkMethod: string;\n\t\t\treadonly sourceFamily: string;\n\t\t};\n\t};\n}\nexport interface CheckpointResult {\n\treadonly state: MetaState;\n\treadonly action: MetaAction;\n\treadonly finish: FinishState;\n\treadonly newObligations: number;\n\treadonly newPredictions: number;\n\treadonly mismatches: number;\n\treadonly verifierEvaluations: readonly VerifierEvaluation[];\n}\n\n/**\n * One checkpoint evaluation. Refreshes obligations from observed atoms when\n * provided, resolves registered predictions against fresh observations when\n * provided, evaluates verifier mutants when provided, then selects the next\n * action under the §14 priority table.\n */\nexport function checkpoint(input: CheckpointInput): CheckpointResult {\n\tinteger(input.nowMs, \"nowMs\");\n\tvalidateMetaState(input.state);\n\tlet state = input.state;\n\tlet newObligations = 0;\n\tif (input.atoms && input.rules) {\n\t\tconst report = instantiateObligations(input.atoms, input.rules, input.nowMs);\n\t\tconst merged = [...state.obligations, ...report.required, ...report.candidates];\n\t\tnewObligations = report.required.length + report.candidates.length;\n\t\tstate = { ...state, obligations: merged };\n\t}\n\tlet mismatches = 0;\n\tfor (const p of state.predictions) {\n\t\tif (p.status === \"resolved\" && p.mismatch !== undefined && p.mismatch !== \"none\") mismatches += 1;\n\t}\n\tconst verifierEvaluations: VerifierEvaluation[] = [...state.verifier.evaluations];\n\tif (input.mutants) {\n\t\tfor (const obligation of state.obligations) {\n\t\t\tconst scoped = input.mutants.filter((m) => m.obligationId === obligation.id);\n\t\t\tif (scoped.length === 0) continue;\n\t\t\tverifierEvaluations.push(\n\t\t\t\tevaluateVerifier(obligation.id, input.mutants, state.verifier.runnerHealth === \"healthy\"),\n\t\t\t);\n\t\t}\n\t\tstate = { ...state, verifier: { ...state.verifier, evaluations: verifierEvaluations } };\n\t}\n\tconst action = selectAction(state, input.constraints, {\n\t\treceipt: input.receipt ?? null,\n\t\tmaxRepetitions: input.options?.maxRepetitions,\n\t\tswitchCost: input.options?.switchCost,\n\t\testimatedSwitchGain: input.options?.estimatedSwitchGain,\n\t\tvoiCandidates: input.options?.voiCandidates,\n\t\tprogress: input.options?.progress,\n\t});\n\tconst finish = finishState(state, input.receipt ?? null);\n\treturn {\n\t\tstate: { ...state, checkpointCount: state.checkpointCount + 1 },\n\t\taction,\n\t\tfinish,\n\t\tnewObligations,\n\t\tnewPredictions: 0,\n\t\tmismatches,\n\t\tverifierEvaluations,\n\t};\n}\n"]}

package/dist/metacognition/checkpoint.js

@@ -0,0 +1,57 @@
+import { instantiateObligations } from "./obligations.js";
+import { selectAction } from "./policy.js";
+import { finishState, validateMetaState } from "./state.js";
+import { integer } from "./validation.js";
+import { evaluateVerifier } from "./verifier.js";
+/**
+ * One checkpoint evaluation. Refreshes obligations from observed atoms when
+ * provided, resolves registered predictions against fresh observations when
+ * provided, evaluates verifier mutants when provided, then selects the next
+ * action under the §14 priority table.
+ */
+export function checkpoint(input) {
+    integer(input.nowMs, "nowMs");
+    validateMetaState(input.state);
+    let state = input.state;
+    let newObligations = 0;
+    if (input.atoms && input.rules) {
+        const report = instantiateObligations(input.atoms, input.rules, input.nowMs);
+        const merged = [...state.obligations, ...report.required, ...report.candidates];
+        newObligations = report.required.length + report.candidates.length;
+        state = { ...state, obligations: merged };
+    }
+    let mismatches = 0;
+    for (const p of state.predictions) {
+        if (p.status === "resolved" && p.mismatch !== undefined && p.mismatch !== "none")
+            mismatches += 1;
+    }
+    const verifierEvaluations = [...state.verifier.evaluations];
+    if (input.mutants) {
+        for (const obligation of state.obligations) {
+            const scoped = input.mutants.filter((m) => m.obligationId === obligation.id);
+            if (scoped.length === 0)
+                continue;
+            verifierEvaluations.push(evaluateVerifier(obligation.id, input.mutants, state.verifier.runnerHealth === "healthy"));
+        }
+        state = { ...state, verifier: { ...state.verifier, evaluations: verifierEvaluations } };
+    }
+    const action = selectAction(state, input.constraints, {
+        receipt: input.receipt ?? null,
+        maxRepetitions: input.options?.maxRepetitions,
+        switchCost: input.options?.switchCost,
+        estimatedSwitchGain: input.options?.estimatedSwitchGain,
+        voiCandidates: input.options?.voiCandidates,
+        progress: input.options?.progress,
+    });
+    const finish = finishState(state, input.receipt ?? null);
+    return {
+        state: { ...state, checkpointCount: state.checkpointCount + 1 },
+        action,
+        finish,
+        newObligations,
+        newPredictions: 0,
+        mismatches,
+        verifierEvaluations,
+    };
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/metacognition/checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../../src/metacognition/checkpoint.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * §9.4 checkpoint ordering: refresh obligations from host observations,\n * evaluate knowledge gaps, classify prediction mismatches, evaluate verifier\n * blind spots and runner health, then select one bounded action.\n *\n * The host calls this at a safe decision boundary — never mid-stream, and\n * never as a path for model reasoning to remove a `required` obligation.\n */\nimport type { ChangeAtom, ObligationRule } from \"./obligations.ts\";\nimport { instantiateObligations } from \"./obligations.ts\";\nimport { type ActionConstraints, type MetaAction, type MetaActionKind, selectAction } from \"./policy.ts\";\nimport type { MetaState } from \"./state.ts\";\nimport { type FinishState, finishState, validateMetaState } from \"./state.ts\";\nimport { integer } from \"./validation.ts\";\nimport { evaluateVerifier, type MutantRecord, type VerifierEvaluation } from \"./verifier.ts\";\n\nexport interface CheckpointInput {\n\treadonly state: MetaState;\n\treadonly atoms?: readonly ChangeAtom[];\n\treadonly rules?: readonly ObligationRule[];\n\treadonly nowMs: number;\n\treadonly constraints: ActionConstraints;\n\treadonly mutants?: readonly MutantRecord[];\n\treadonly receipt?: { receiptId: string; candidateHash: string; scope: string } | null;\n\treadonly options?: {\n\t\treadonly maxRepetitions?: number;\n\t\treadonly switchCost?: number;\n\t\treadonly estimatedSwitchGain?: number;\n\t\treadonly voiCandidates?: readonly { kind: MetaActionKind; voi: number }[];\n\t\treadonly progress?: {\n\t\t\treadonly goalScope: string;\n\t\t\treadonly candidateFamily: string;\n\t\t\treadonly errorClass: string;\n\t\t\treadonly approach: string;\n\t\t\treadonly checkMethod: string;\n\t\t\treadonly sourceFamily: string;\n\t\t};\n\t};\n}\nexport interface CheckpointResult {\n\treadonly state: MetaState;\n\treadonly action: MetaAction;\n\treadonly finish: FinishState;\n\treadonly newObligations: number;\n\treadonly newPredictions: number;\n\treadonly mismatches: number;\n\treadonly verifierEvaluations: readonly VerifierEvaluation[];\n}\n\n/**\n * One checkpoint evaluation. Refreshes obligations from observed atoms when\n * provided, resolves registered predictions against fresh observations when\n * provided, evaluates verifier mutants when provided, then selects the next\n * action under the §14 priority table.\n */\nexport function checkpoint(input: CheckpointInput): CheckpointResult {\n\tinteger(input.nowMs, \"nowMs\");\n\tvalidateMetaState(input.state);\n\tlet state = input.state;\n\tlet newObligations = 0;\n\tif (input.atoms && input.rules) {\n\t\tconst report = instantiateObligations(input.atoms, input.rules, input.nowMs);\n\t\tconst merged = [...state.obligations, ...report.required, ...report.candidates];\n\t\tnewObligations = report.required.length + report.candidates.length;\n\t\tstate = { ...state, obligations: merged };\n\t}\n\tlet mismatches = 0;\n\tfor (const p of state.predictions) {\n\t\tif (p.status === \"resolved\" && p.mismatch !== undefined && p.mismatch !== \"none\") mismatches += 1;\n\t}\n\tconst verifierEvaluations: VerifierEvaluation[] = [...state.verifier.evaluations];\n\tif (input.mutants) {\n\t\tfor (const obligation of state.obligations) {\n\t\t\tconst scoped = input.mutants.filter((m) => m.obligationId === obligation.id);\n\t\t\tif (scoped.length === 0) continue;\n\t\t\tverifierEvaluations.push(\n\t\t\t\tevaluateVerifier(obligation.id, input.mutants, state.verifier.runnerHealth === \"healthy\"),\n\t\t\t);\n\t\t}\n\t\tstate = { ...state, verifier: { ...state.verifier, evaluations: verifierEvaluations } };\n\t}\n\tconst action = selectAction(state, input.constraints, {\n\t\treceipt: input.receipt ?? null,\n\t\tmaxRepetitions: input.options?.maxRepetitions,\n\t\tswitchCost: input.options?.switchCost,\n\t\testimatedSwitchGain: input.options?.estimatedSwitchGain,\n\t\tvoiCandidates: input.options?.voiCandidates,\n\t\tprogress: input.options?.progress,\n\t});\n\tconst finish = finishState(state, input.receipt ?? null);\n\treturn {\n\t\tstate: { ...state, checkpointCount: state.checkpointCount + 1 },\n\t\taction,\n\t\tfinish,\n\t\tnewObligations,\n\t\tnewPredictions: 0,\n\t\tmismatches,\n\t\tverifierEvaluations,\n\t};\n}\n"]}

package/dist/metacognition/context7.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Fixed-origin Context7 GET adapter with explicit egress approval.
+ *
+ * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip
+ * (src/context7.ts). Every attempted HTTP request consumes a shared
+ * AcquisitionPool permit; there is no retry, redirect-following, or
+ * auto-selection of the first result. Returned `rules` fields are data, never
+ * promoted to instructions.
+ */
+import type { AcquisitionPool, AcquisitionResult } from "./retrieval.ts";
+export interface Context7Options {
+    readonly apiKey: string;
+    readonly enabled: boolean;
+    readonly approvedLibraryNames: readonly string[];
+    readonly approvedLibraryIds: readonly string[];
+    readonly approvedQueries: readonly string[];
+    readonly pool: AcquisitionPool;
+    readonly maxResponseBytes?: number;
+    readonly fetchImpl?: typeof fetch;
+}
+export interface LibraryCandidate {
+    readonly id: string;
+    readonly title: string;
+    readonly versions: readonly string[];
+}
+export interface DocumentationCandidate {
+    readonly uri: string;
+    readonly body: string;
+    readonly requestedLibraryId: string;
+    readonly trust: "candidate-only";
+}
+/** Fixed-origin GET adapter. In OMK prefer routing equivalent requests through admitted MCP tools. */
+export declare class Context7Client {
+    private readonly key;
+    private readonly enabled;
+    private readonly names;
+    private readonly ids;
+    private readonly queries;
+    private readonly pool;
+    private readonly fetcher;
+    private readonly limit;
+    constructor(options: Context7Options);
+    resolveLibraries(name: string, query: string, signal?: AbortSignal): Promise<AcquisitionResult<readonly LibraryCandidate[]>>;
+    getDocumentation(id: string, query: string, signal?: AbortSignal): Promise<AcquisitionResult<readonly DocumentationCandidate[]>>;
+    private authorize;
+    private get;
+}
+//# sourceMappingURL=context7.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context7.d.ts","sourceRoot":"","sources":["../../src/metacognition/context7.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGzE,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAClC;AACD,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AACD,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;CACjC;AACD,sGAAsG;AACtG,qBAAa,cAAc;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsB;IAC5C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,YAAY,OAAO,EAAE,eAAe,EAanC;IACD,gBAAgB,CACf,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,iBAAiB,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAAC,CAkBzD;IACD,gBAAgB,CACf,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,iBAAiB,CAAC,SAAS,sBAAsB,EAAE,CAAC,CAAC,CAqC/D;IACD,OAAO,CAAC,SAAS;YAKH,GAAG;CAiDjB","sourcesContent":["/**\n * Fixed-origin Context7 GET adapter with explicit egress approval.\n *\n * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip\n * (src/context7.ts). Every attempted HTTP request consumes a shared\n * AcquisitionPool permit; there is no retry, redirect-following, or\n * auto-selection of the first result. Returned `rules` fields are data, never\n * promoted to instructions.\n */\nimport type { AcquisitionPool, AcquisitionResult } from \"./retrieval.ts\";\nimport { ensure, integer, text } from \"./validation.ts\";\n\nexport interface Context7Options {\n\treadonly apiKey: string;\n\treadonly enabled: boolean;\n\treadonly approvedLibraryNames: readonly string[];\n\treadonly approvedLibraryIds: readonly string[];\n\treadonly approvedQueries: readonly string[];\n\treadonly pool: AcquisitionPool;\n\treadonly maxResponseBytes?: number;\n\treadonly fetchImpl?: typeof fetch;\n}\nexport interface LibraryCandidate {\n\treadonly id: string;\n\treadonly title: string;\n\treadonly versions: readonly string[];\n}\nexport interface DocumentationCandidate {\n\treadonly uri: string;\n\treadonly body: string;\n\treadonly requestedLibraryId: string;\n\treadonly trust: \"candidate-only\";\n}\n/** Fixed-origin GET adapter. In OMK prefer routing equivalent requests through admitted MCP tools. */\nexport class Context7Client {\n\tprivate readonly key: string;\n\tprivate readonly enabled: boolean;\n\tprivate readonly names: ReadonlySet<string>;\n\tprivate readonly ids: ReadonlySet<string>;\n\tprivate readonly queries: ReadonlySet<string>;\n\tprivate readonly pool: AcquisitionPool;\n\tprivate readonly fetcher: typeof fetch;\n\tprivate readonly limit: number;\n\tconstructor(options: Context7Options) {\n\t\ttext(options.apiKey, \"apiKey\", 4096);\n\t\tensure(typeof options.enabled === \"boolean\", \"enabled must be boolean\");\n\t\tthis.limit = options.maxResponseBytes ?? 200_000;\n\t\tinteger(this.limit, \"maxResponseBytes\", 2_000_000);\n\t\tensure(this.limit > 0, \"response limit must be positive\");\n\t\tthis.key = options.apiKey;\n\t\tthis.enabled = options.enabled;\n\t\tthis.names = new Set(options.approvedLibraryNames);\n\t\tthis.ids = new Set(options.approvedLibraryIds);\n\t\tthis.queries = new Set(options.approvedQueries);\n\t\tthis.pool = options.pool;\n\t\tthis.fetcher = options.fetchImpl ?? fetch;\n\t}\n\tresolveLibraries(\n\t\tname: string,\n\t\tquery: string,\n\t\tsignal?: AbortSignal,\n\t): Promise<AcquisitionResult<readonly LibraryCandidate[]>> {\n\t\tthis.authorize(query);\n\t\ttext(name, \"libraryName\", 500);\n\t\tensure(this.names.has(name), \"unapproved library name\");\n\t\treturn this.pool.run(async (abort) => {\n\t\t\tconst payload = await this.get(\"/api/v2/libs/search\", { libraryName: name, query }, abort);\n\t\t\tconst object = record(payload);\n\t\t\tensure(Array.isArray(object.results), \"invalid search response\");\n\t\t\tensure(object.results.length <= 256, \"too many library candidates\");\n\t\t\treturn object.results.map((raw): LibraryCandidate => {\n\t\t\t\tconst candidate = record(raw);\n\t\t\t\tconst id = string(candidate.id),\n\t\t\t\t\ttitle = string(candidate.title);\n\t\t\t\tconst versions = candidate.versions ?? [];\n\t\t\t\tensure(Array.isArray(versions) && versions.every((v) => typeof v === \"string\"), \"invalid versions\");\n\t\t\t\treturn { id, title, versions: versions as string[] };\n\t\t\t});\n\t\t}, signal);\n\t}\n\tgetDocumentation(\n\t\tid: string,\n\t\tquery: string,\n\t\tsignal?: AbortSignal,\n\t): Promise<AcquisitionResult<readonly DocumentationCandidate[]>> {\n\t\tthis.authorize(query);\n\t\ttext(id, \"libraryId\", 500);\n\t\tensure(this.ids.has(id), \"unapproved library id: validate identity/version before retrieval\");\n\t\treturn this.pool.run(async (abort) => {\n\t\t\tconst object = record(await this.get(\"/api/v2/context\", { libraryId: id, query, type: \"json\" }, abort));\n\t\t\tconst info = object.infoSnippets,\n\t\t\t\tcode = object.codeSnippets;\n\t\t\tensure(Array.isArray(info) && Array.isArray(code), \"invalid documentation response\");\n\t\t\tensure(info.length + code.length <= 256, \"too many snippets\");\n\t\t\tconst result: DocumentationCandidate[] = [];\n\t\t\tconst add = (uri: unknown, body: string): void => {\n\t\t\t\tif (typeof uri !== \"string\") return;\n\t\t\t\tlet parsed: URL;\n\t\t\t\ttry {\n\t\t\t\t\tparsed = new URL(uri);\n\t\t\t\t} catch {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\t// Metadata only, never followed. Reject executable/non-web references.\n\t\t\t\tif (parsed.protocol !== \"https:\" || parsed.username || parsed.password) return;\n\t\t\t\tresult.push({ uri: parsed.href, body, requestedLibraryId: id, trust: \"candidate-only\" });\n\t\t\t};\n\t\t\tfor (const raw of info) {\n\t\t\t\tconst v = record(raw);\n\t\t\t\tadd(v.pageId, string(v.content));\n\t\t\t}\n\t\t\tfor (const raw of code) {\n\t\t\t\tconst v = record(raw);\n\t\t\t\tconst list = v.codeList;\n\t\t\t\tensure(Array.isArray(list), \"invalid codeList\");\n\t\t\t\tconst body = list.map((item) => string(record(item).code)).join(\"\\n\\n\");\n\t\t\t\tadd(v.codeId, body);\n\t\t\t}\n\t\t\t// The response's optional `rules` field is deliberately not promoted to instructions.\n\t\t\treturn result;\n\t\t}, signal);\n\t}\n\tprivate authorize(query: string): void {\n\t\tensure(this.enabled, \"remote acquisition disabled\");\n\t\ttext(query, \"public query\", 500);\n\t\tensure(this.queries.has(query), \"query has not been approved for egress\");\n\t}\n\tprivate async get(path: string, parameters: Record<string, string>, signal: AbortSignal): Promise<unknown> {\n\t\tconst url = new URL(path, \"https://context7.com\");\n\t\tfor (const [key, value] of Object.entries(parameters)) url.searchParams.set(key, value);\n\t\tconst response = await this.fetcher(url, {\n\t\t\tmethod: \"GET\",\n\t\t\tredirect: \"error\",\n\t\t\tsignal,\n\t\t\theaders: { Authorization: `Bearer ${this.key}`, Accept: \"application/json\" },\n\t\t});\n\t\t// No retry here: every attempted HTTP request must acquire a fresh shared budget slot.\n\t\tif (response.status !== 200) {\n\t\t\tif (response.body) await response.body.cancel();\n\t\t\tthrow new Error(`context7-http-${response.status}`);\n\t\t}\n\t\tconst contentType = response.headers.get(\"content-type\") ?? \"\";\n\t\tif (!contentType.includes(\"application/json\")) {\n\t\t\tif (response.body) await response.body.cancel();\n\t\t\tthrow new Error(\"unexpected response content type\");\n\t\t}\n\t\tensure(response.body !== null, \"missing response body\");\n\t\tconst reader = response.body.getReader();\n\t\tlet bytes = 0;\n\t\tconst chunks: Uint8Array[] = [];\n\t\ttry {\n\t\t\twhile (true) {\n\t\t\t\tconst next = await reader.read();\n\t\t\t\tif (next.done) break;\n\t\t\t\tbytes += next.value.byteLength;\n\t\t\t\tensure(bytes <= this.limit, \"response byte budget exceeded\");\n\t\t\t\tchunks.push(next.value);\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tawait reader.cancel();\n\t\t\tthrow error;\n\t\t} finally {\n\t\t\treader.releaseLock();\n\t\t}\n\t\tconst joined = new Uint8Array(bytes);\n\t\tlet at = 0;\n\t\tfor (const chunk of chunks) {\n\t\t\tjoined.set(chunk, at);\n\t\t\tat += chunk.byteLength;\n\t\t}\n\t\ttry {\n\t\t\treturn JSON.parse(new TextDecoder(\"utf-8\", { fatal: true }).decode(joined)) as unknown;\n\t\t} catch {\n\t\t\tthrow new Error(\"malformed context7 response body\");\n\t\t}\n\t}\n}\nfunction record(value: unknown): Record<string, unknown> {\n\tensure(value !== null && typeof value === \"object\" && !Array.isArray(value), \"expected response object\");\n\treturn value as Record<string, unknown>;\n}\nfunction string(value: unknown): string {\n\tensure(typeof value === \"string\", \"expected response string\");\n\treturn value;\n}\n"]}

package/dist/metacognition/context7.js

@@ -0,0 +1,154 @@
+import { ensure, integer, text } from "./validation.js";
+/** Fixed-origin GET adapter. In OMK prefer routing equivalent requests through admitted MCP tools. */
+export class Context7Client {
+    key;
+    enabled;
+    names;
+    ids;
+    queries;
+    pool;
+    fetcher;
+    limit;
+    constructor(options) {
+        text(options.apiKey, "apiKey", 4096);
+        ensure(typeof options.enabled === "boolean", "enabled must be boolean");
+        this.limit = options.maxResponseBytes ?? 200_000;
+        integer(this.limit, "maxResponseBytes", 2_000_000);
+        ensure(this.limit > 0, "response limit must be positive");
+        this.key = options.apiKey;
+        this.enabled = options.enabled;
+        this.names = new Set(options.approvedLibraryNames);
+        this.ids = new Set(options.approvedLibraryIds);
+        this.queries = new Set(options.approvedQueries);
+        this.pool = options.pool;
+        this.fetcher = options.fetchImpl ?? fetch;
+    }
+    resolveLibraries(name, query, signal) {
+        this.authorize(query);
+        text(name, "libraryName", 500);
+        ensure(this.names.has(name), "unapproved library name");
+        return this.pool.run(async (abort) => {
+            const payload = await this.get("/api/v2/libs/search", { libraryName: name, query }, abort);
+            const object = record(payload);
+            ensure(Array.isArray(object.results), "invalid search response");
+            ensure(object.results.length <= 256, "too many library candidates");
+            return object.results.map((raw) => {
+                const candidate = record(raw);
+                const id = string(candidate.id), title = string(candidate.title);
+                const versions = candidate.versions ?? [];
+                ensure(Array.isArray(versions) && versions.every((v) => typeof v === "string"), "invalid versions");
+                return { id, title, versions: versions };
+            });
+        }, signal);
+    }
+    getDocumentation(id, query, signal) {
+        this.authorize(query);
+        text(id, "libraryId", 500);
+        ensure(this.ids.has(id), "unapproved library id: validate identity/version before retrieval");
+        return this.pool.run(async (abort) => {
+            const object = record(await this.get("/api/v2/context", { libraryId: id, query, type: "json" }, abort));
+            const info = object.infoSnippets, code = object.codeSnippets;
+            ensure(Array.isArray(info) && Array.isArray(code), "invalid documentation response");
+            ensure(info.length + code.length <= 256, "too many snippets");
+            const result = [];
+            const add = (uri, body) => {
+                if (typeof uri !== "string")
+                    return;
+                let parsed;
+                try {
+                    parsed = new URL(uri);
+                }
+                catch {
+                    return;
+                }
+                // Metadata only, never followed. Reject executable/non-web references.
+                if (parsed.protocol !== "https:" || parsed.username || parsed.password)
+                    return;
+                result.push({ uri: parsed.href, body, requestedLibraryId: id, trust: "candidate-only" });
+            };
+            for (const raw of info) {
+                const v = record(raw);
+                add(v.pageId, string(v.content));
+            }
+            for (const raw of code) {
+                const v = record(raw);
+                const list = v.codeList;
+                ensure(Array.isArray(list), "invalid codeList");
+                const body = list.map((item) => string(record(item).code)).join("\n\n");
+                add(v.codeId, body);
+            }
+            // The response's optional `rules` field is deliberately not promoted to instructions.
+            return result;
+        }, signal);
+    }
+    authorize(query) {
+        ensure(this.enabled, "remote acquisition disabled");
+        text(query, "public query", 500);
+        ensure(this.queries.has(query), "query has not been approved for egress");
+    }
+    async get(path, parameters, signal) {
+        const url = new URL(path, "https://context7.com");
+        for (const [key, value] of Object.entries(parameters))
+            url.searchParams.set(key, value);
+        const response = await this.fetcher(url, {
+            method: "GET",
+            redirect: "error",
+            signal,
+            headers: { Authorization: `Bearer ${this.key}`, Accept: "application/json" },
+        });
+        // No retry here: every attempted HTTP request must acquire a fresh shared budget slot.
+        if (response.status !== 200) {
+            if (response.body)
+                await response.body.cancel();
+            throw new Error(`context7-http-${response.status}`);
+        }
+        const contentType = response.headers.get("content-type") ?? "";
+        if (!contentType.includes("application/json")) {
+            if (response.body)
+                await response.body.cancel();
+            throw new Error("unexpected response content type");
+        }
+        ensure(response.body !== null, "missing response body");
+        const reader = response.body.getReader();
+        let bytes = 0;
+        const chunks = [];
+        try {
+            while (true) {
+                const next = await reader.read();
+                if (next.done)
+                    break;
+                bytes += next.value.byteLength;
+                ensure(bytes <= this.limit, "response byte budget exceeded");
+                chunks.push(next.value);
+            }
+        }
+        catch (error) {
+            await reader.cancel();
+            throw error;
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const joined = new Uint8Array(bytes);
+        let at = 0;
+        for (const chunk of chunks) {
+            joined.set(chunk, at);
+            at += chunk.byteLength;
+        }
+        try {
+            return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(joined));
+        }
+        catch {
+            throw new Error("malformed context7 response body");
+        }
+    }
+}
+function record(value) {
+    ensure(value !== null && typeof value === "object" && !Array.isArray(value), "expected response object");
+    return value;
+}
+function string(value) {
+    ensure(typeof value === "string", "expected response string");
+    return value;
+}
+//# sourceMappingURL=context7.js.map

package/dist/metacognition/context7.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context7.js","sourceRoot":"","sources":["../../src/metacognition/context7.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Fixed-origin Context7 GET adapter with explicit egress approval.\n *\n * Ported from docs/OMK_skill_knowledge_control_2026-09-19.zip\n * (src/context7.ts). Every attempted HTTP request consumes a shared\n * AcquisitionPool permit; there is no retry, redirect-following, or\n * auto-selection of the first result. Returned `rules` fields are data, never\n * promoted to instructions.\n */\nimport type { AcquisitionPool, AcquisitionResult } from \"./retrieval.ts\";\nimport { ensure, integer, text } from \"./validation.ts\";\n\nexport interface Context7Options {\n\treadonly apiKey: string;\n\treadonly enabled: boolean;\n\treadonly approvedLibraryNames: readonly string[];\n\treadonly approvedLibraryIds: readonly string[];\n\treadonly approvedQueries: readonly string[];\n\treadonly pool: AcquisitionPool;\n\treadonly maxResponseBytes?: number;\n\treadonly fetchImpl?: typeof fetch;\n}\nexport interface LibraryCandidate {\n\treadonly id: string;\n\treadonly title: string;\n\treadonly versions: readonly string[];\n}\nexport interface DocumentationCandidate {\n\treadonly uri: string;\n\treadonly body: string;\n\treadonly requestedLibraryId: string;\n\treadonly trust: \"candidate-only\";\n}\n/** Fixed-origin GET adapter. In OMK prefer routing equivalent requests through admitted MCP tools. */\nexport class Context7Client {\n\tprivate readonly key: string;\n\tprivate readonly enabled: boolean;\n\tprivate readonly names: ReadonlySet<string>;\n\tprivate readonly ids: ReadonlySet<string>;\n\tprivate readonly queries: ReadonlySet<string>;\n\tprivate readonly pool: AcquisitionPool;\n\tprivate readonly fetcher: typeof fetch;\n\tprivate readonly limit: number;\n\tconstructor(options: Context7Options) {\n\t\ttext(options.apiKey, \"apiKey\", 4096);\n\t\tensure(typeof options.enabled === \"boolean\", \"enabled must be boolean\");\n\t\tthis.limit = options.maxResponseBytes ?? 200_000;\n\t\tinteger(this.limit, \"maxResponseBytes\", 2_000_000);\n\t\tensure(this.limit > 0, \"response limit must be positive\");\n\t\tthis.key = options.apiKey;\n\t\tthis.enabled = options.enabled;\n\t\tthis.names = new Set(options.approvedLibraryNames);\n\t\tthis.ids = new Set(options.approvedLibraryIds);\n\t\tthis.queries = new Set(options.approvedQueries);\n\t\tthis.pool = options.pool;\n\t\tthis.fetcher = options.fetchImpl ?? fetch;\n\t}\n\tresolveLibraries(\n\t\tname: string,\n\t\tquery: string,\n\t\tsignal?: AbortSignal,\n\t): Promise<AcquisitionResult<readonly LibraryCandidate[]>> {\n\t\tthis.authorize(query);\n\t\ttext(name, \"libraryName\", 500);\n\t\tensure(this.names.has(name), \"unapproved library name\");\n\t\treturn this.pool.run(async (abort) => {\n\t\t\tconst payload = await this.get(\"/api/v2/libs/search\", { libraryName: name, query }, abort);\n\t\t\tconst object = record(payload);\n\t\t\tensure(Array.isArray(object.results), \"invalid search response\");\n\t\t\tensure(object.results.length <= 256, \"too many library candidates\");\n\t\t\treturn object.results.map((raw): LibraryCandidate => {\n\t\t\t\tconst candidate = record(raw);\n\t\t\t\tconst id = string(candidate.id),\n\t\t\t\t\ttitle = string(candidate.title);\n\t\t\t\tconst versions = candidate.versions ?? [];\n\t\t\t\tensure(Array.isArray(versions) && versions.every((v) => typeof v === \"string\"), \"invalid versions\");\n\t\t\t\treturn { id, title, versions: versions as string[] };\n\t\t\t});\n\t\t}, signal);\n\t}\n\tgetDocumentation(\n\t\tid: string,\n\t\tquery: string,\n\t\tsignal?: AbortSignal,\n\t): Promise<AcquisitionResult<readonly DocumentationCandidate[]>> {\n\t\tthis.authorize(query);\n\t\ttext(id, \"libraryId\", 500);\n\t\tensure(this.ids.has(id), \"unapproved library id: validate identity/version before retrieval\");\n\t\treturn this.pool.run(async (abort) => {\n\t\t\tconst object = record(await this.get(\"/api/v2/context\", { libraryId: id, query, type: \"json\" }, abort));\n\t\t\tconst info = object.infoSnippets,\n\t\t\t\tcode = object.codeSnippets;\n\t\t\tensure(Array.isArray(info) && Array.isArray(code), \"invalid documentation response\");\n\t\t\tensure(info.length + code.length <= 256, \"too many snippets\");\n\t\t\tconst result: DocumentationCandidate[] = [];\n\t\t\tconst add = (uri: unknown, body: string): void => {\n\t\t\t\tif (typeof uri !== \"string\") return;\n\t\t\t\tlet parsed: URL;\n\t\t\t\ttry {\n\t\t\t\t\tparsed = new URL(uri);\n\t\t\t\t} catch {\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\t// Metadata only, never followed. Reject executable/non-web references.\n\t\t\t\tif (parsed.protocol !== \"https:\" || parsed.username || parsed.password) return;\n\t\t\t\tresult.push({ uri: parsed.href, body, requestedLibraryId: id, trust: \"candidate-only\" });\n\t\t\t};\n\t\t\tfor (const raw of info) {\n\t\t\t\tconst v = record(raw);\n\t\t\t\tadd(v.pageId, string(v.content));\n\t\t\t}\n\t\t\tfor (const raw of code) {\n\t\t\t\tconst v = record(raw);\n\t\t\t\tconst list = v.codeList;\n\t\t\t\tensure(Array.isArray(list), \"invalid codeList\");\n\t\t\t\tconst body = list.map((item) => string(record(item).code)).join(\"\\n\\n\");\n\t\t\t\tadd(v.codeId, body);\n\t\t\t}\n\t\t\t// The response's optional `rules` field is deliberately not promoted to instructions.\n\t\t\treturn result;\n\t\t}, signal);\n\t}\n\tprivate authorize(query: string): void {\n\t\tensure(this.enabled, \"remote acquisition disabled\");\n\t\ttext(query, \"public query\", 500);\n\t\tensure(this.queries.has(query), \"query has not been approved for egress\");\n\t}\n\tprivate async get(path: string, parameters: Record<string, string>, signal: AbortSignal): Promise<unknown> {\n\t\tconst url = new URL(path, \"https://context7.com\");\n\t\tfor (const [key, value] of Object.entries(parameters)) url.searchParams.set(key, value);\n\t\tconst response = await this.fetcher(url, {\n\t\t\tmethod: \"GET\",\n\t\t\tredirect: \"error\",\n\t\t\tsignal,\n\t\t\theaders: { Authorization: `Bearer ${this.key}`, Accept: \"application/json\" },\n\t\t});\n\t\t// No retry here: every attempted HTTP request must acquire a fresh shared budget slot.\n\t\tif (response.status !== 200) {\n\t\t\tif (response.body) await response.body.cancel();\n\t\t\tthrow new Error(`context7-http-${response.status}`);\n\t\t}\n\t\tconst contentType = response.headers.get(\"content-type\") ?? \"\";\n\t\tif (!contentType.includes(\"application/json\")) {\n\t\t\tif (response.body) await response.body.cancel();\n\t\t\tthrow new Error(\"unexpected response content type\");\n\t\t}\n\t\tensure(response.body !== null, \"missing response body\");\n\t\tconst reader = response.body.getReader();\n\t\tlet bytes = 0;\n\t\tconst chunks: Uint8Array[] = [];\n\t\ttry {\n\t\t\twhile (true) {\n\t\t\t\tconst next = await reader.read();\n\t\t\t\tif (next.done) break;\n\t\t\t\tbytes += next.value.byteLength;\n\t\t\t\tensure(bytes <= this.limit, \"response byte budget exceeded\");\n\t\t\t\tchunks.push(next.value);\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tawait reader.cancel();\n\t\t\tthrow error;\n\t\t} finally {\n\t\t\treader.releaseLock();\n\t\t}\n\t\tconst joined = new Uint8Array(bytes);\n\t\tlet at = 0;\n\t\tfor (const chunk of chunks) {\n\t\t\tjoined.set(chunk, at);\n\t\t\tat += chunk.byteLength;\n\t\t}\n\t\ttry {\n\t\t\treturn JSON.parse(new TextDecoder(\"utf-8\", { fatal: true }).decode(joined)) as unknown;\n\t\t} catch {\n\t\t\tthrow new Error(\"malformed context7 response body\");\n\t\t}\n\t}\n}\nfunction record(value: unknown): Record<string, unknown> {\n\tensure(value !== null && typeof value === \"object\" && !Array.isArray(value), \"expected response object\");\n\treturn value as Record<string, unknown>;\n}\nfunction string(value: unknown): string {\n\tensure(typeof value === \"string\", \"expected response string\");\n\treturn value;\n}\n"]}