@asm-agent/retrieval 0.8.2

package/README.md

@@ -0,0 +1,10 @@
+# `@asm-agent/retrieval`
+
+Causal Head and Dual-ASM retrieval backends run behind the versioned retrieval
+contract. New backends begin in shadow mode: callers receive the frozen
+lexical/vector baseline result while candidate output and latency are observed.
+
+Checkpoints are data-only JSON envelopes validated against an inference
+manifest and SHA-256 digest. Executable pickle/torch deserialization is not
+supported. Promotion requires a persisted passing evaluation; rollback is a
+transactional configuration change.

package/dist/causal-head.d.ts

@@ -0,0 +1,29 @@
+import type { RankedItem, RetrievalBackend, RetrievalItem, RetrievalQuery } from "./types.js";
+export interface CausalHeadState {
+    sequence: number;
+    slots: Array<{
+        vector: number[];
+        strength: number;
+        lastSequence: number;
+    }>;
+}
+export interface CausalHeadParameters {
+    dimensions: number;
+    capacity: number;
+    queryWeight: number;
+    stateWeight: number;
+    writeRate: number;
+    decay: number;
+}
+export declare class CausalHeadBackend implements RetrievalBackend<CausalHeadState> {
+    readonly parameters: CausalHeadParameters;
+    readonly name: "causal-head-v1";
+    readonly dimensions: number;
+    constructor(parameters: CausalHeadParameters);
+    emptyState(): CausalHeadState;
+    retrieve(query: RetrievalQuery, items: readonly RetrievalItem[], state: CausalHeadState): RankedItem[];
+    update(state: CausalHeadState, selected: readonly RetrievalItem[], feedback?: string): CausalHeadState;
+    serializeState(state: CausalHeadState): Record<string, unknown>;
+    deserializeState(value: unknown): CausalHeadState;
+}
+//# sourceMappingURL=causal-head.d.ts.map

package/dist/causal-head.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"causal-head.d.ts","sourceRoot":"","sources":["../src/causal-head.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE9F,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3E;AAED,MAAM,WAAW,oBAAoB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,iBAAkB,YAAW,gBAAgB,CAAC,eAAe,CAAC;IAI9D,QAAQ,CAAC,UAAU,EAAE,oBAAoB;IAHrD,QAAQ,CAAC,IAAI,mBAA6B;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,YAAqB,UAAU,EAAE,oBAAoB,EASpD;IAED,UAAU,IAAI,eAAe,CAE5B;IAED,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,aAAa,EAAE,EAAE,KAAK,EAAE,eAAe,GAAG,UAAU,EAAE,CAcrG;IAED,MAAM,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,SAAS,aAAa,EAAE,EAAE,QAAQ,SAAa,GAAG,eAAe,CA4BzG;IAED,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9D;IAED,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAMhD;CACD","sourcesContent":["import { assertVector, average, blend, clamp01, cosine } from \"./math.js\";\nimport type { RankedItem, RetrievalBackend, RetrievalItem, RetrievalQuery } from \"./types.js\";\n\nexport interface CausalHeadState {\n\tsequence: number;\n\tslots: Array<{ vector: number[]; strength: number; lastSequence: number }>;\n}\n\nexport interface CausalHeadParameters {\n\tdimensions: number;\n\tcapacity: number;\n\tqueryWeight: number;\n\tstateWeight: number;\n\twriteRate: number;\n\tdecay: number;\n}\n\nexport class CausalHeadBackend implements RetrievalBackend<CausalHeadState> {\n\treadonly name = \"causal-head-v1\" as const;\n\treadonly dimensions: number;\n\n\tconstructor(readonly parameters: CausalHeadParameters) {\n\t\tthis.dimensions = parameters.dimensions;\n\t\tif (!Number.isInteger(parameters.capacity) || parameters.capacity < 1)\n\t\t\tthrow new Error(\"Causal Head capacity must be positive\");\n\t\tfor (const [name, value] of Object.entries(parameters)) {\n\t\t\tif (name !== \"dimensions\" && name !== \"capacity\" && (!Number.isFinite(value) || value < 0 || value > 1)) {\n\t\t\t\tthrow new Error(`Invalid Causal Head parameter: ${name}`);\n\t\t\t}\n\t\t}\n\t}\n\n\temptyState(): CausalHeadState {\n\t\treturn { sequence: 0, slots: [] };\n\t}\n\n\tretrieve(query: RetrievalQuery, items: readonly RetrievalItem[], state: CausalHeadState): RankedItem[] {\n\t\tassertVector(query.embedding, this.dimensions, \"query embedding\");\n\t\tconst stateVector = weightedStateVector(state, this.dimensions);\n\t\treturn eligibleItems(query, items, this.dimensions)\n\t\t\t.map((item) => ({\n\t\t\t\tid: item.id,\n\t\t\t\tscore: clamp01(\n\t\t\t\t\tcosine(query.embedding, item.embedding) * this.parameters.queryWeight +\n\t\t\t\t\t\tcosine(stateVector, item.embedding) * this.parameters.stateWeight,\n\t\t\t\t),\n\t\t\t\treasonCodes: [\"query_similarity\", \"causal_state_similarity\"],\n\t\t\t}))\n\t\t\t.sort((left, right) => right.score - left.score || left.id.localeCompare(right.id))\n\t\t\t.slice(0, query.limit);\n\t}\n\n\tupdate(state: CausalHeadState, selected: readonly RetrievalItem[], feedback = \"positive\"): CausalHeadState {\n\t\tconst sequence = state.sequence + 1;\n\t\tconst slots = state.slots.map((slot) => ({\n\t\t\t...slot,\n\t\t\tvector: [...slot.vector],\n\t\t\tstrength: slot.strength * this.parameters.decay,\n\t\t}));\n\t\tif (selected.length > 0) {\n\t\t\tfor (const item of selected) assertVector(item.embedding, this.dimensions, \"selected embedding\");\n\t\t\tconst candidate = average(\n\t\t\t\tselected.map((item) => item.embedding),\n\t\t\t\tthis.dimensions,\n\t\t\t);\n\t\t\tconst nearest = slots\n\t\t\t\t.map((slot, index) => ({ index, score: cosine(slot.vector, candidate) }))\n\t\t\t\t.sort((left, right) => right.score - left.score)[0];\n\t\t\tconst strengthDelta = feedback === \"positive\" ? this.parameters.writeRate : -this.parameters.writeRate;\n\t\t\tif (nearest && nearest.score >= 0.75) {\n\t\t\t\tconst slot = slots[nearest.index]!;\n\t\t\t\tslot.vector = blend(slot.vector, candidate, this.parameters.writeRate);\n\t\t\t\tslot.strength = clamp01(slot.strength + strengthDelta);\n\t\t\t\tslot.lastSequence = sequence;\n\t\t\t} else if (feedback === \"positive\") {\n\t\t\t\tslots.push({ vector: candidate, strength: this.parameters.writeRate, lastSequence: sequence });\n\t\t\t}\n\t\t}\n\t\tslots.sort((left, right) => right.strength - left.strength || right.lastSequence - left.lastSequence);\n\t\treturn { sequence, slots: slots.filter((slot) => slot.strength > 0.001).slice(0, this.parameters.capacity) };\n\t}\n\n\tserializeState(state: CausalHeadState): Record<string, unknown> {\n\t\treturn { sequence: state.sequence, slots: state.slots.map((slot) => ({ ...slot, vector: [...slot.vector] })) };\n\t}\n\n\tdeserializeState(value: unknown): CausalHeadState {\n\t\tif (!isCausalState(value)) throw new Error(\"Invalid Causal Head state snapshot\");\n\t\tfor (const slot of value.slots) assertVector(slot.vector, this.dimensions, \"state slot\");\n\t\tif (value.slots.length > this.parameters.capacity)\n\t\t\tthrow new Error(\"Causal Head state exceeds configured capacity\");\n\t\treturn structuredClone(value);\n\t}\n}\n\nfunction weightedStateVector(state: CausalHeadState, dimensions: number): number[] {\n\tconst total = state.slots.reduce((sum, slot) => sum + slot.strength, 0);\n\tif (total === 0) return Array.from({ length: dimensions }, () => 0);\n\treturn Array.from(\n\t\t{ length: dimensions },\n\t\t(_, index) => state.slots.reduce((sum, slot) => sum + (slot.vector[index] ?? 0) * slot.strength, 0) / total,\n\t);\n}\n\nfunction eligibleItems(query: RetrievalQuery, items: readonly RetrievalItem[], dimensions: number): RetrievalItem[] {\n\treturn items.filter((item) => {\n\t\tassertVector(item.embedding, dimensions, \"item embedding\");\n\t\treturn item.ownerId === query.ownerId && item.projectId === query.projectId && !item.revoked;\n\t});\n}\n\nfunction isCausalState(value: unknown): value is CausalHeadState {\n\tif (!value || typeof value !== \"object\") return false;\n\tconst state = value as Partial<CausalHeadState>;\n\treturn (\n\t\tNumber.isInteger(state.sequence) &&\n\t\t(state.sequence ?? -1) >= 0 &&\n\t\tArray.isArray(state.slots) &&\n\t\tstate.slots.every(\n\t\t\t(slot) =>\n\t\t\t\tArray.isArray(slot.vector) &&\n\t\t\t\ttypeof slot.strength === \"number\" &&\n\t\t\t\tNumber.isFinite(slot.strength) &&\n\t\t\t\tNumber.isInteger(slot.lastSequence),\n\t\t)\n\t);\n}\n"]}

package/dist/causal-head.js

@@ -0,0 +1,98 @@
+import { assertVector, average, blend, clamp01, cosine } from "./math.js";
+export class CausalHeadBackend {
+    parameters;
+    name = "causal-head-v1";
+    dimensions;
+    constructor(parameters) {
+        this.parameters = parameters;
+        this.dimensions = parameters.dimensions;
+        if (!Number.isInteger(parameters.capacity) || parameters.capacity < 1)
+            throw new Error("Causal Head capacity must be positive");
+        for (const [name, value] of Object.entries(parameters)) {
+            if (name !== "dimensions" && name !== "capacity" && (!Number.isFinite(value) || value < 0 || value > 1)) {
+                throw new Error(`Invalid Causal Head parameter: ${name}`);
+            }
+        }
+    }
+    emptyState() {
+        return { sequence: 0, slots: [] };
+    }
+    retrieve(query, items, state) {
+        assertVector(query.embedding, this.dimensions, "query embedding");
+        const stateVector = weightedStateVector(state, this.dimensions);
+        return eligibleItems(query, items, this.dimensions)
+            .map((item) => ({
+            id: item.id,
+            score: clamp01(cosine(query.embedding, item.embedding) * this.parameters.queryWeight +
+                cosine(stateVector, item.embedding) * this.parameters.stateWeight),
+            reasonCodes: ["query_similarity", "causal_state_similarity"],
+        }))
+            .sort((left, right) => right.score - left.score || left.id.localeCompare(right.id))
+            .slice(0, query.limit);
+    }
+    update(state, selected, feedback = "positive") {
+        const sequence = state.sequence + 1;
+        const slots = state.slots.map((slot) => ({
+            ...slot,
+            vector: [...slot.vector],
+            strength: slot.strength * this.parameters.decay,
+        }));
+        if (selected.length > 0) {
+            for (const item of selected)
+                assertVector(item.embedding, this.dimensions, "selected embedding");
+            const candidate = average(selected.map((item) => item.embedding), this.dimensions);
+            const nearest = slots
+                .map((slot, index) => ({ index, score: cosine(slot.vector, candidate) }))
+                .sort((left, right) => right.score - left.score)[0];
+            const strengthDelta = feedback === "positive" ? this.parameters.writeRate : -this.parameters.writeRate;
+            if (nearest && nearest.score >= 0.75) {
+                const slot = slots[nearest.index];
+                slot.vector = blend(slot.vector, candidate, this.parameters.writeRate);
+                slot.strength = clamp01(slot.strength + strengthDelta);
+                slot.lastSequence = sequence;
+            }
+            else if (feedback === "positive") {
+                slots.push({ vector: candidate, strength: this.parameters.writeRate, lastSequence: sequence });
+            }
+        }
+        slots.sort((left, right) => right.strength - left.strength || right.lastSequence - left.lastSequence);
+        return { sequence, slots: slots.filter((slot) => slot.strength > 0.001).slice(0, this.parameters.capacity) };
+    }
+    serializeState(state) {
+        return { sequence: state.sequence, slots: state.slots.map((slot) => ({ ...slot, vector: [...slot.vector] })) };
+    }
+    deserializeState(value) {
+        if (!isCausalState(value))
+            throw new Error("Invalid Causal Head state snapshot");
+        for (const slot of value.slots)
+            assertVector(slot.vector, this.dimensions, "state slot");
+        if (value.slots.length > this.parameters.capacity)
+            throw new Error("Causal Head state exceeds configured capacity");
+        return structuredClone(value);
+    }
+}
+function weightedStateVector(state, dimensions) {
+    const total = state.slots.reduce((sum, slot) => sum + slot.strength, 0);
+    if (total === 0)
+        return Array.from({ length: dimensions }, () => 0);
+    return Array.from({ length: dimensions }, (_, index) => state.slots.reduce((sum, slot) => sum + (slot.vector[index] ?? 0) * slot.strength, 0) / total);
+}
+function eligibleItems(query, items, dimensions) {
+    return items.filter((item) => {
+        assertVector(item.embedding, dimensions, "item embedding");
+        return item.ownerId === query.ownerId && item.projectId === query.projectId && !item.revoked;
+    });
+}
+function isCausalState(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const state = value;
+    return (Number.isInteger(state.sequence) &&
+        (state.sequence ?? -1) >= 0 &&
+        Array.isArray(state.slots) &&
+        state.slots.every((slot) => Array.isArray(slot.vector) &&
+            typeof slot.strength === "number" &&
+            Number.isFinite(slot.strength) &&
+            Number.isInteger(slot.lastSequence)));
+}
+//# sourceMappingURL=causal-head.js.map

package/dist/causal-head.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"causal-head.js","sourceRoot":"","sources":["../src/causal-head.ts"],"names":[],"mappings":"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","sourcesContent":["import { assertVector, average, blend, clamp01, cosine } from \"./math.js\";\nimport type { RankedItem, RetrievalBackend, RetrievalItem, RetrievalQuery } from \"./types.js\";\n\nexport interface CausalHeadState {\n\tsequence: number;\n\tslots: Array<{ vector: number[]; strength: number; lastSequence: number }>;\n}\n\nexport interface CausalHeadParameters {\n\tdimensions: number;\n\tcapacity: number;\n\tqueryWeight: number;\n\tstateWeight: number;\n\twriteRate: number;\n\tdecay: number;\n}\n\nexport class CausalHeadBackend implements RetrievalBackend<CausalHeadState> {\n\treadonly name = \"causal-head-v1\" as const;\n\treadonly dimensions: number;\n\n\tconstructor(readonly parameters: CausalHeadParameters) {\n\t\tthis.dimensions = parameters.dimensions;\n\t\tif (!Number.isInteger(parameters.capacity) || parameters.capacity < 1)\n\t\t\tthrow new Error(\"Causal Head capacity must be positive\");\n\t\tfor (const [name, value] of Object.entries(parameters)) {\n\t\t\tif (name !== \"dimensions\" && name !== \"capacity\" && (!Number.isFinite(value) || value < 0 || value > 1)) {\n\t\t\t\tthrow new Error(`Invalid Causal Head parameter: ${name}`);\n\t\t\t}\n\t\t}\n\t}\n\n\temptyState(): CausalHeadState {\n\t\treturn { sequence: 0, slots: [] };\n\t}\n\n\tretrieve(query: RetrievalQuery, items: readonly RetrievalItem[], state: CausalHeadState): RankedItem[] {\n\t\tassertVector(query.embedding, this.dimensions, \"query embedding\");\n\t\tconst stateVector = weightedStateVector(state, this.dimensions);\n\t\treturn eligibleItems(query, items, this.dimensions)\n\t\t\t.map((item) => ({\n\t\t\t\tid: item.id,\n\t\t\t\tscore: clamp01(\n\t\t\t\t\tcosine(query.embedding, item.embedding) * this.parameters.queryWeight +\n\t\t\t\t\t\tcosine(stateVector, item.embedding) * this.parameters.stateWeight,\n\t\t\t\t),\n\t\t\t\treasonCodes: [\"query_similarity\", \"causal_state_similarity\"],\n\t\t\t}))\n\t\t\t.sort((left, right) => right.score - left.score || left.id.localeCompare(right.id))\n\t\t\t.slice(0, query.limit);\n\t}\n\n\tupdate(state: CausalHeadState, selected: readonly RetrievalItem[], feedback = \"positive\"): CausalHeadState {\n\t\tconst sequence = state.sequence + 1;\n\t\tconst slots = state.slots.map((slot) => ({\n\t\t\t...slot,\n\t\t\tvector: [...slot.vector],\n\t\t\tstrength: slot.strength * this.parameters.decay,\n\t\t}));\n\t\tif (selected.length > 0) {\n\t\t\tfor (const item of selected) assertVector(item.embedding, this.dimensions, \"selected embedding\");\n\t\t\tconst candidate = average(\n\t\t\t\tselected.map((item) => item.embedding),\n\t\t\t\tthis.dimensions,\n\t\t\t);\n\t\t\tconst nearest = slots\n\t\t\t\t.map((slot, index) => ({ index, score: cosine(slot.vector, candidate) }))\n\t\t\t\t.sort((left, right) => right.score - left.score)[0];\n\t\t\tconst strengthDelta = feedback === \"positive\" ? this.parameters.writeRate : -this.parameters.writeRate;\n\t\t\tif (nearest && nearest.score >= 0.75) {\n\t\t\t\tconst slot = slots[nearest.index]!;\n\t\t\t\tslot.vector = blend(slot.vector, candidate, this.parameters.writeRate);\n\t\t\t\tslot.strength = clamp01(slot.strength + strengthDelta);\n\t\t\t\tslot.lastSequence = sequence;\n\t\t\t} else if (feedback === \"positive\") {\n\t\t\t\tslots.push({ vector: candidate, strength: this.parameters.writeRate, lastSequence: sequence });\n\t\t\t}\n\t\t}\n\t\tslots.sort((left, right) => right.strength - left.strength || right.lastSequence - left.lastSequence);\n\t\treturn { sequence, slots: slots.filter((slot) => slot.strength > 0.001).slice(0, this.parameters.capacity) };\n\t}\n\n\tserializeState(state: CausalHeadState): Record<string, unknown> {\n\t\treturn { sequence: state.sequence, slots: state.slots.map((slot) => ({ ...slot, vector: [...slot.vector] })) };\n\t}\n\n\tdeserializeState(value: unknown): CausalHeadState {\n\t\tif (!isCausalState(value)) throw new Error(\"Invalid Causal Head state snapshot\");\n\t\tfor (const slot of value.slots) assertVector(slot.vector, this.dimensions, \"state slot\");\n\t\tif (value.slots.length > this.parameters.capacity)\n\t\t\tthrow new Error(\"Causal Head state exceeds configured capacity\");\n\t\treturn structuredClone(value);\n\t}\n}\n\nfunction weightedStateVector(state: CausalHeadState, dimensions: number): number[] {\n\tconst total = state.slots.reduce((sum, slot) => sum + slot.strength, 0);\n\tif (total === 0) return Array.from({ length: dimensions }, () => 0);\n\treturn Array.from(\n\t\t{ length: dimensions },\n\t\t(_, index) => state.slots.reduce((sum, slot) => sum + (slot.vector[index] ?? 0) * slot.strength, 0) / total,\n\t);\n}\n\nfunction eligibleItems(query: RetrievalQuery, items: readonly RetrievalItem[], dimensions: number): RetrievalItem[] {\n\treturn items.filter((item) => {\n\t\tassertVector(item.embedding, dimensions, \"item embedding\");\n\t\treturn item.ownerId === query.ownerId && item.projectId === query.projectId && !item.revoked;\n\t});\n}\n\nfunction isCausalState(value: unknown): value is CausalHeadState {\n\tif (!value || typeof value !== \"object\") return false;\n\tconst state = value as Partial<CausalHeadState>;\n\treturn (\n\t\tNumber.isInteger(state.sequence) &&\n\t\t(state.sequence ?? -1) >= 0 &&\n\t\tArray.isArray(state.slots) &&\n\t\tstate.slots.every(\n\t\t\t(slot) =>\n\t\t\t\tArray.isArray(slot.vector) &&\n\t\t\t\ttypeof slot.strength === \"number\" &&\n\t\t\t\tNumber.isFinite(slot.strength) &&\n\t\t\t\tNumber.isInteger(slot.lastSequence),\n\t\t)\n\t);\n}\n"]}

package/dist/checkpoint.d.ts

@@ -0,0 +1,8 @@
+import type { InferenceManifestContract } from "@asm-agent/contracts";
+import type { RetrievalBackend } from "./types.js";
+export interface LoadedCheckpoint {
+    digest: string;
+    backend: RetrievalBackend;
+}
+export declare function loadCheckpoint(manifest: InferenceManifestContract, bytes: Uint8Array): LoadedCheckpoint;
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../src/checkpoint.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAItE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AASnD,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,gBAAgB,CAAC;CAC1B;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,yBAAyB,EAAE,KAAK,EAAE,UAAU,GAAG,gBAAgB,CA2BvG","sourcesContent":["import { createHash } from \"node:crypto\";\nimport type { InferenceManifestContract } from \"@asm-agent/contracts\";\nimport { assertContract } from \"@asm-agent/contracts\";\nimport { CausalHeadBackend, type CausalHeadParameters } from \"./causal-head.js\";\nimport { DualAsmBackend, type DualAsmParameters } from \"./dual-asm.js\";\nimport type { RetrievalBackend } from \"./types.js\";\n\ninterface CheckpointEnvelope {\n\tformatVersion: 1;\n\tbackend: \"causal_head\" | \"dual_asm\";\n\tdimensions: number;\n\tparameters: Record<string, number>;\n}\n\nexport interface LoadedCheckpoint {\n\tdigest: string;\n\tbackend: RetrievalBackend;\n}\n\nexport function loadCheckpoint(manifest: InferenceManifestContract, bytes: Uint8Array): LoadedCheckpoint {\n\tassertContract(\"inferenceManifest\", manifest);\n\tif (manifest.backend !== \"causal_head\" && manifest.backend !== \"dual_asm\") {\n\t\tthrow new Error(`Manifest backend is not learned retrieval: ${manifest.backend}`);\n\t}\n\tif (manifest.contractMajors.retrieval !== 1 || manifest.contractMajors.stateSnapshot !== 1) {\n\t\tthrow new Error(\"Checkpoint manifest requires unsupported contract majors\");\n\t}\n\tconst digest = createHash(\"sha256\").update(bytes).digest(\"hex\");\n\tif (!manifest.artifactDigest || manifest.artifactDigest !== digest) throw new Error(\"Checkpoint SHA-256 mismatch\");\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(new TextDecoder().decode(bytes));\n\t} catch {\n\t\tthrow new Error(\"Checkpoint must be valid JSON; executable serialization is not supported\");\n\t}\n\tif (!isCheckpointEnvelope(value)) throw new Error(\"Invalid checkpoint envelope\");\n\tif (value.backend !== manifest.backend) throw new Error(\"Checkpoint backend does not match manifest\");\n\tconst manifestDimensions = manifest.parameters.dimensions;\n\tif (manifestDimensions !== value.dimensions) throw new Error(\"Checkpoint dimensions do not match manifest\");\n\treturn {\n\t\tdigest,\n\t\tbackend:\n\t\t\tvalue.backend === \"causal_head\"\n\t\t\t\t? new CausalHeadBackend(value.parameters as unknown as CausalHeadParameters)\n\t\t\t\t: new DualAsmBackend(value.parameters as unknown as DualAsmParameters),\n\t};\n}\n\nfunction isCheckpointEnvelope(value: unknown): value is CheckpointEnvelope {\n\tif (!value || typeof value !== \"object\") return false;\n\tconst record = value as Record<string, unknown>;\n\tif (Object.keys(record).some((key) => ![\"formatVersion\", \"backend\", \"dimensions\", \"parameters\"].includes(key)))\n\t\treturn false;\n\tif (\n\t\trecord.formatVersion !== 1 ||\n\t\t(record.backend !== \"causal_head\" && record.backend !== \"dual_asm\") ||\n\t\t!Number.isInteger(record.dimensions) ||\n\t\t(record.dimensions as number) < 1 ||\n\t\t!record.parameters ||\n\t\ttypeof record.parameters !== \"object\" ||\n\t\tArray.isArray(record.parameters)\n\t) {\n\t\treturn false;\n\t}\n\treturn Object.values(record.parameters).every((item) => typeof item === \"number\" && Number.isFinite(item));\n}\n"]}

package/dist/checkpoint.js

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+import { assertContract } from "@asm-agent/contracts";
+import { CausalHeadBackend } from "./causal-head.js";
+import { DualAsmBackend } from "./dual-asm.js";
+export function loadCheckpoint(manifest, bytes) {
+    assertContract("inferenceManifest", manifest);
+    if (manifest.backend !== "causal_head" && manifest.backend !== "dual_asm") {
+        throw new Error(`Manifest backend is not learned retrieval: ${manifest.backend}`);
+    }
+    if (manifest.contractMajors.retrieval !== 1 || manifest.contractMajors.stateSnapshot !== 1) {
+        throw new Error("Checkpoint manifest requires unsupported contract majors");
+    }
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (!manifest.artifactDigest || manifest.artifactDigest !== digest)
+        throw new Error("Checkpoint SHA-256 mismatch");
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        throw new Error("Checkpoint must be valid JSON; executable serialization is not supported");
+    }
+    if (!isCheckpointEnvelope(value))
+        throw new Error("Invalid checkpoint envelope");
+    if (value.backend !== manifest.backend)
+        throw new Error("Checkpoint backend does not match manifest");
+    const manifestDimensions = manifest.parameters.dimensions;
+    if (manifestDimensions !== value.dimensions)
+        throw new Error("Checkpoint dimensions do not match manifest");
+    return {
+        digest,
+        backend: value.backend === "causal_head"
+            ? new CausalHeadBackend(value.parameters)
+            : new DualAsmBackend(value.parameters),
+    };
+}
+function isCheckpointEnvelope(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    if (Object.keys(record).some((key) => !["formatVersion", "backend", "dimensions", "parameters"].includes(key)))
+        return false;
+    if (record.formatVersion !== 1 ||
+        (record.backend !== "causal_head" && record.backend !== "dual_asm") ||
+        !Number.isInteger(record.dimensions) ||
+        record.dimensions < 1 ||
+        !record.parameters ||
+        typeof record.parameters !== "object" ||
+        Array.isArray(record.parameters)) {
+        return false;
+    }
+    return Object.values(record.parameters).every((item) => typeof item === "number" && Number.isFinite(item));
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../src/checkpoint.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport type { InferenceManifestContract } from \"@asm-agent/contracts\";\nimport { assertContract } from \"@asm-agent/contracts\";\nimport { CausalHeadBackend, type CausalHeadParameters } from \"./causal-head.js\";\nimport { DualAsmBackend, type DualAsmParameters } from \"./dual-asm.js\";\nimport type { RetrievalBackend } from \"./types.js\";\n\ninterface CheckpointEnvelope {\n\tformatVersion: 1;\n\tbackend: \"causal_head\" | \"dual_asm\";\n\tdimensions: number;\n\tparameters: Record<string, number>;\n}\n\nexport interface LoadedCheckpoint {\n\tdigest: string;\n\tbackend: RetrievalBackend;\n}\n\nexport function loadCheckpoint(manifest: InferenceManifestContract, bytes: Uint8Array): LoadedCheckpoint {\n\tassertContract(\"inferenceManifest\", manifest);\n\tif (manifest.backend !== \"causal_head\" && manifest.backend !== \"dual_asm\") {\n\t\tthrow new Error(`Manifest backend is not learned retrieval: ${manifest.backend}`);\n\t}\n\tif (manifest.contractMajors.retrieval !== 1 || manifest.contractMajors.stateSnapshot !== 1) {\n\t\tthrow new Error(\"Checkpoint manifest requires unsupported contract majors\");\n\t}\n\tconst digest = createHash(\"sha256\").update(bytes).digest(\"hex\");\n\tif (!manifest.artifactDigest || manifest.artifactDigest !== digest) throw new Error(\"Checkpoint SHA-256 mismatch\");\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(new TextDecoder().decode(bytes));\n\t} catch {\n\t\tthrow new Error(\"Checkpoint must be valid JSON; executable serialization is not supported\");\n\t}\n\tif (!isCheckpointEnvelope(value)) throw new Error(\"Invalid checkpoint envelope\");\n\tif (value.backend !== manifest.backend) throw new Error(\"Checkpoint backend does not match manifest\");\n\tconst manifestDimensions = manifest.parameters.dimensions;\n\tif (manifestDimensions !== value.dimensions) throw new Error(\"Checkpoint dimensions do not match manifest\");\n\treturn {\n\t\tdigest,\n\t\tbackend:\n\t\t\tvalue.backend === \"causal_head\"\n\t\t\t\t? new CausalHeadBackend(value.parameters as unknown as CausalHeadParameters)\n\t\t\t\t: new DualAsmBackend(value.parameters as unknown as DualAsmParameters),\n\t};\n}\n\nfunction isCheckpointEnvelope(value: unknown): value is CheckpointEnvelope {\n\tif (!value || typeof value !== \"object\") return false;\n\tconst record = value as Record<string, unknown>;\n\tif (Object.keys(record).some((key) => ![\"formatVersion\", \"backend\", \"dimensions\", \"parameters\"].includes(key)))\n\t\treturn false;\n\tif (\n\t\trecord.formatVersion !== 1 ||\n\t\t(record.backend !== \"causal_head\" && record.backend !== \"dual_asm\") ||\n\t\t!Number.isInteger(record.dimensions) ||\n\t\t(record.dimensions as number) < 1 ||\n\t\t!record.parameters ||\n\t\ttypeof record.parameters !== \"object\" ||\n\t\tArray.isArray(record.parameters)\n\t) {\n\t\treturn false;\n\t}\n\treturn Object.values(record.parameters).every((item) => typeof item === \"number\" && Number.isFinite(item));\n}\n"]}

package/dist/dual-asm.d.ts

@@ -0,0 +1,27 @@
+import type { RankedItem, RetrievalBackend, RetrievalItem, RetrievalQuery } from "./types.js";
+export interface DualAsmState {
+    sequence: number;
+    positive: number[];
+    negative: number[];
+    positiveWrites: number;
+    negativeWrites: number;
+}
+export interface DualAsmParameters {
+    dimensions: number;
+    queryWeight: number;
+    positiveWeight: number;
+    negativeWeight: number;
+    writeRate: number;
+}
+export declare class DualAsmBackend implements RetrievalBackend<DualAsmState> {
+    readonly parameters: DualAsmParameters;
+    readonly name: "dual-asm-v1";
+    readonly dimensions: number;
+    constructor(parameters: DualAsmParameters);
+    emptyState(): DualAsmState;
+    retrieve(query: RetrievalQuery, items: readonly RetrievalItem[], state: DualAsmState): RankedItem[];
+    update(state: DualAsmState, selected: readonly RetrievalItem[], feedback?: string): DualAsmState;
+    serializeState(state: DualAsmState): Record<string, unknown>;
+    deserializeState(value: unknown): DualAsmState;
+}
+//# sourceMappingURL=dual-asm.d.ts.map

package/dist/dual-asm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dual-asm.d.ts","sourceRoot":"","sources":["../src/dual-asm.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE9F,MAAM,WAAW,YAAY;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,cAAe,YAAW,gBAAgB,CAAC,YAAY,CAAC;IAIxD,QAAQ,CAAC,UAAU,EAAE,iBAAiB;IAHlD,QAAQ,CAAC,IAAI,gBAA0B;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,YAAqB,UAAU,EAAE,iBAAiB,EASjD;IAED,UAAU,IAAI,YAAY,CAQzB;IAED,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,aAAa,EAAE,EAAE,KAAK,EAAE,YAAY,GAAG,UAAU,EAAE,CAiBlG;IAED,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,SAAS,aAAa,EAAE,EAAE,QAAQ,SAAa,GAAG,YAAY,CA4BnG;IAED,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE3D;IAED,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAK7C;CACD","sourcesContent":["import { assertVector, average, blend, clamp01, cosine } from \"./math.js\";\nimport type { RankedItem, RetrievalBackend, RetrievalItem, RetrievalQuery } from \"./types.js\";\n\nexport interface DualAsmState {\n\tsequence: number;\n\tpositive: number[];\n\tnegative: number[];\n\tpositiveWrites: number;\n\tnegativeWrites: number;\n}\n\nexport interface DualAsmParameters {\n\tdimensions: number;\n\tqueryWeight: number;\n\tpositiveWeight: number;\n\tnegativeWeight: number;\n\twriteRate: number;\n}\n\nexport class DualAsmBackend implements RetrievalBackend<DualAsmState> {\n\treadonly name = \"dual-asm-v1\" as const;\n\treadonly dimensions: number;\n\n\tconstructor(readonly parameters: DualAsmParameters) {\n\t\tthis.dimensions = parameters.dimensions;\n\t\tif (!Number.isInteger(this.dimensions) || this.dimensions < 1)\n\t\t\tthrow new Error(\"Dual-ASM dimensions must be positive\");\n\t\tfor (const [name, value] of Object.entries(parameters)) {\n\t\t\tif (name !== \"dimensions\" && (!Number.isFinite(value) || value < 0 || value > 1)) {\n\t\t\t\tthrow new Error(`Invalid Dual-ASM parameter: ${name}`);\n\t\t\t}\n\t\t}\n\t}\n\n\temptyState(): DualAsmState {\n\t\treturn {\n\t\t\tsequence: 0,\n\t\t\tpositive: Array.from({ length: this.dimensions }, () => 0),\n\t\t\tnegative: Array.from({ length: this.dimensions }, () => 0),\n\t\t\tpositiveWrites: 0,\n\t\t\tnegativeWrites: 0,\n\t\t};\n\t}\n\n\tretrieve(query: RetrievalQuery, items: readonly RetrievalItem[], state: DualAsmState): RankedItem[] {\n\t\tassertVector(query.embedding, this.dimensions, \"query embedding\");\n\t\treturn items\n\t\t\t.filter((item) => {\n\t\t\t\tassertVector(item.embedding, this.dimensions, \"item embedding\");\n\t\t\t\treturn item.ownerId === query.ownerId && item.projectId === query.projectId && !item.revoked;\n\t\t\t})\n\t\t\t.map((item) => {\n\t\t\t\tconst score = clamp01(\n\t\t\t\t\tcosine(query.embedding, item.embedding) * this.parameters.queryWeight +\n\t\t\t\t\t\tcosine(state.positive, item.embedding) * this.parameters.positiveWeight -\n\t\t\t\t\t\tcosine(state.negative, item.embedding) * this.parameters.negativeWeight,\n\t\t\t\t);\n\t\t\t\treturn { id: item.id, score, reasonCodes: [\"query_similarity\", \"positive_state\", \"negative_state\"] };\n\t\t\t})\n\t\t\t.sort((left, right) => right.score - left.score || left.id.localeCompare(right.id))\n\t\t\t.slice(0, query.limit);\n\t}\n\n\tupdate(state: DualAsmState, selected: readonly RetrievalItem[], feedback = \"positive\"): DualAsmState {\n\t\tfor (const item of selected) assertVector(item.embedding, this.dimensions, \"selected embedding\");\n\t\tif (selected.length === 0)\n\t\t\treturn {\n\t\t\t\t...state,\n\t\t\t\tpositive: [...state.positive],\n\t\t\t\tnegative: [...state.negative],\n\t\t\t\tsequence: state.sequence + 1,\n\t\t\t};\n\t\tconst candidate = average(\n\t\t\tselected.map((item) => item.embedding),\n\t\t\tthis.dimensions,\n\t\t);\n\t\treturn feedback === \"positive\"\n\t\t\t? {\n\t\t\t\t\t...state,\n\t\t\t\t\tsequence: state.sequence + 1,\n\t\t\t\t\tpositive: blend(state.positive, candidate, this.parameters.writeRate),\n\t\t\t\t\tnegative: [...state.negative],\n\t\t\t\t\tpositiveWrites: state.positiveWrites + 1,\n\t\t\t\t}\n\t\t\t: {\n\t\t\t\t\t...state,\n\t\t\t\t\tsequence: state.sequence + 1,\n\t\t\t\t\tpositive: [...state.positive],\n\t\t\t\t\tnegative: blend(state.negative, candidate, this.parameters.writeRate),\n\t\t\t\t\tnegativeWrites: state.negativeWrites + 1,\n\t\t\t\t};\n\t}\n\n\tserializeState(state: DualAsmState): Record<string, unknown> {\n\t\treturn { ...state, positive: [...state.positive], negative: [...state.negative] };\n\t}\n\n\tdeserializeState(value: unknown): DualAsmState {\n\t\tif (!isDualState(value)) throw new Error(\"Invalid Dual-ASM state snapshot\");\n\t\tassertVector(value.positive, this.dimensions, \"positive state\");\n\t\tassertVector(value.negative, this.dimensions, \"negative state\");\n\t\treturn structuredClone(value);\n\t}\n}\n\nfunction isDualState(value: unknown): value is DualAsmState {\n\tif (!value || typeof value !== \"object\") return false;\n\tconst state = value as Partial<DualAsmState>;\n\treturn (\n\t\tNumber.isInteger(state.sequence) &&\n\t\t(state.sequence ?? -1) >= 0 &&\n\t\tArray.isArray(state.positive) &&\n\t\tArray.isArray(state.negative) &&\n\t\tNumber.isInteger(state.positiveWrites) &&\n\t\tNumber.isInteger(state.negativeWrites)\n\t);\n}\n"]}

package/dist/dual-asm.js

@@ -0,0 +1,91 @@
+import { assertVector, average, blend, clamp01, cosine } from "./math.js";
+export class DualAsmBackend {
+    parameters;
+    name = "dual-asm-v1";
+    dimensions;
+    constructor(parameters) {
+        this.parameters = parameters;
+        this.dimensions = parameters.dimensions;
+        if (!Number.isInteger(this.dimensions) || this.dimensions < 1)
+            throw new Error("Dual-ASM dimensions must be positive");
+        for (const [name, value] of Object.entries(parameters)) {
+            if (name !== "dimensions" && (!Number.isFinite(value) || value < 0 || value > 1)) {
+                throw new Error(`Invalid Dual-ASM parameter: ${name}`);
+            }
+        }
+    }
+    emptyState() {
+        return {
+            sequence: 0,
+            positive: Array.from({ length: this.dimensions }, () => 0),
+            negative: Array.from({ length: this.dimensions }, () => 0),
+            positiveWrites: 0,
+            negativeWrites: 0,
+        };
+    }
+    retrieve(query, items, state) {
+        assertVector(query.embedding, this.dimensions, "query embedding");
+        return items
+            .filter((item) => {
+            assertVector(item.embedding, this.dimensions, "item embedding");
+            return item.ownerId === query.ownerId && item.projectId === query.projectId && !item.revoked;
+        })
+            .map((item) => {
+            const score = clamp01(cosine(query.embedding, item.embedding) * this.parameters.queryWeight +
+                cosine(state.positive, item.embedding) * this.parameters.positiveWeight -
+                cosine(state.negative, item.embedding) * this.parameters.negativeWeight);
+            return { id: item.id, score, reasonCodes: ["query_similarity", "positive_state", "negative_state"] };
+        })
+            .sort((left, right) => right.score - left.score || left.id.localeCompare(right.id))
+            .slice(0, query.limit);
+    }
+    update(state, selected, feedback = "positive") {
+        for (const item of selected)
+            assertVector(item.embedding, this.dimensions, "selected embedding");
+        if (selected.length === 0)
+            return {
+                ...state,
+                positive: [...state.positive],
+                negative: [...state.negative],
+                sequence: state.sequence + 1,
+            };
+        const candidate = average(selected.map((item) => item.embedding), this.dimensions);
+        return feedback === "positive"
+            ? {
+                ...state,
+                sequence: state.sequence + 1,
+                positive: blend(state.positive, candidate, this.parameters.writeRate),
+                negative: [...state.negative],
+                positiveWrites: state.positiveWrites + 1,
+            }
+            : {
+                ...state,
+                sequence: state.sequence + 1,
+                positive: [...state.positive],
+                negative: blend(state.negative, candidate, this.parameters.writeRate),
+                negativeWrites: state.negativeWrites + 1,
+            };
+    }
+    serializeState(state) {
+        return { ...state, positive: [...state.positive], negative: [...state.negative] };
+    }
+    deserializeState(value) {
+        if (!isDualState(value))
+            throw new Error("Invalid Dual-ASM state snapshot");
+        assertVector(value.positive, this.dimensions, "positive state");
+        assertVector(value.negative, this.dimensions, "negative state");
+        return structuredClone(value);
+    }
+}
+function isDualState(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const state = value;
+    return (Number.isInteger(state.sequence) &&
+        (state.sequence ?? -1) >= 0 &&
+        Array.isArray(state.positive) &&
+        Array.isArray(state.negative) &&
+        Number.isInteger(state.positiveWrites) &&
+        Number.isInteger(state.negativeWrites));
+}
+//# sourceMappingURL=dual-asm.js.map

package/dist/dual-asm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dual-asm.js","sourceRoot":"","sources":["../src/dual-asm.ts"],"names":[],"mappings":"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","sourcesContent":["import { assertVector, average, blend, clamp01, cosine } from \"./math.js\";\nimport type { RankedItem, RetrievalBackend, RetrievalItem, RetrievalQuery } from \"./types.js\";\n\nexport interface DualAsmState {\n\tsequence: number;\n\tpositive: number[];\n\tnegative: number[];\n\tpositiveWrites: number;\n\tnegativeWrites: number;\n}\n\nexport interface DualAsmParameters {\n\tdimensions: number;\n\tqueryWeight: number;\n\tpositiveWeight: number;\n\tnegativeWeight: number;\n\twriteRate: number;\n}\n\nexport class DualAsmBackend implements RetrievalBackend<DualAsmState> {\n\treadonly name = \"dual-asm-v1\" as const;\n\treadonly dimensions: number;\n\n\tconstructor(readonly parameters: DualAsmParameters) {\n\t\tthis.dimensions = parameters.dimensions;\n\t\tif (!Number.isInteger(this.dimensions) || this.dimensions < 1)\n\t\t\tthrow new Error(\"Dual-ASM dimensions must be positive\");\n\t\tfor (const [name, value] of Object.entries(parameters)) {\n\t\t\tif (name !== \"dimensions\" && (!Number.isFinite(value) || value < 0 || value > 1)) {\n\t\t\t\tthrow new Error(`Invalid Dual-ASM parameter: ${name}`);\n\t\t\t}\n\t\t}\n\t}\n\n\temptyState(): DualAsmState {\n\t\treturn {\n\t\t\tsequence: 0,\n\t\t\tpositive: Array.from({ length: this.dimensions }, () => 0),\n\t\t\tnegative: Array.from({ length: this.dimensions }, () => 0),\n\t\t\tpositiveWrites: 0,\n\t\t\tnegativeWrites: 0,\n\t\t};\n\t}\n\n\tretrieve(query: RetrievalQuery, items: readonly RetrievalItem[], state: DualAsmState): RankedItem[] {\n\t\tassertVector(query.embedding, this.dimensions, \"query embedding\");\n\t\treturn items\n\t\t\t.filter((item) => {\n\t\t\t\tassertVector(item.embedding, this.dimensions, \"item embedding\");\n\t\t\t\treturn item.ownerId === query.ownerId && item.projectId === query.projectId && !item.revoked;\n\t\t\t})\n\t\t\t.map((item) => {\n\t\t\t\tconst score = clamp01(\n\t\t\t\t\tcosine(query.embedding, item.embedding) * this.parameters.queryWeight +\n\t\t\t\t\t\tcosine(state.positive, item.embedding) * this.parameters.positiveWeight -\n\t\t\t\t\t\tcosine(state.negative, item.embedding) * this.parameters.negativeWeight,\n\t\t\t\t);\n\t\t\t\treturn { id: item.id, score, reasonCodes: [\"query_similarity\", \"positive_state\", \"negative_state\"] };\n\t\t\t})\n\t\t\t.sort((left, right) => right.score - left.score || left.id.localeCompare(right.id))\n\t\t\t.slice(0, query.limit);\n\t}\n\n\tupdate(state: DualAsmState, selected: readonly RetrievalItem[], feedback = \"positive\"): DualAsmState {\n\t\tfor (const item of selected) assertVector(item.embedding, this.dimensions, \"selected embedding\");\n\t\tif (selected.length === 0)\n\t\t\treturn {\n\t\t\t\t...state,\n\t\t\t\tpositive: [...state.positive],\n\t\t\t\tnegative: [...state.negative],\n\t\t\t\tsequence: state.sequence + 1,\n\t\t\t};\n\t\tconst candidate = average(\n\t\t\tselected.map((item) => item.embedding),\n\t\t\tthis.dimensions,\n\t\t);\n\t\treturn feedback === \"positive\"\n\t\t\t? {\n\t\t\t\t\t...state,\n\t\t\t\t\tsequence: state.sequence + 1,\n\t\t\t\t\tpositive: blend(state.positive, candidate, this.parameters.writeRate),\n\t\t\t\t\tnegative: [...state.negative],\n\t\t\t\t\tpositiveWrites: state.positiveWrites + 1,\n\t\t\t\t}\n\t\t\t: {\n\t\t\t\t\t...state,\n\t\t\t\t\tsequence: state.sequence + 1,\n\t\t\t\t\tpositive: [...state.positive],\n\t\t\t\t\tnegative: blend(state.negative, candidate, this.parameters.writeRate),\n\t\t\t\t\tnegativeWrites: state.negativeWrites + 1,\n\t\t\t\t};\n\t}\n\n\tserializeState(state: DualAsmState): Record<string, unknown> {\n\t\treturn { ...state, positive: [...state.positive], negative: [...state.negative] };\n\t}\n\n\tdeserializeState(value: unknown): DualAsmState {\n\t\tif (!isDualState(value)) throw new Error(\"Invalid Dual-ASM state snapshot\");\n\t\tassertVector(value.positive, this.dimensions, \"positive state\");\n\t\tassertVector(value.negative, this.dimensions, \"negative state\");\n\t\treturn structuredClone(value);\n\t}\n}\n\nfunction isDualState(value: unknown): value is DualAsmState {\n\tif (!value || typeof value !== \"object\") return false;\n\tconst state = value as Partial<DualAsmState>;\n\treturn (\n\t\tNumber.isInteger(state.sequence) &&\n\t\t(state.sequence ?? -1) >= 0 &&\n\t\tArray.isArray(state.positive) &&\n\t\tArray.isArray(state.negative) &&\n\t\tNumber.isInteger(state.positiveWrites) &&\n\t\tNumber.isInteger(state.negativeWrites)\n\t);\n}\n"]}

package/dist/evaluation.d.ts

@@ -0,0 +1,61 @@
+import type { RankedItem, RetrievalItem, RetrievalQuery } from "./types.js";
+export interface Ranker {
+    readonly name: string;
+    retrieve(query: RetrievalQuery, items: readonly RetrievalItem[]): RankedItem[];
+}
+export interface BenchmarkCase {
+    id: string;
+    query: RetrievalQuery;
+    items: RetrievalItem[];
+    relevantIds: string[];
+}
+export interface BenchmarkMetrics {
+    recallAtK: number;
+    meanReciprocalRank: number;
+    p95LatencyMs: number;
+    p99LatencyMs: number;
+    capacityRetention: number;
+    falseForgettingRate: number;
+    revocationLeakage: number;
+    projectIsolationLeakage: number;
+}
+export interface PromotionThresholds {
+    minimumRecallAtK: number;
+    minimumMeanReciprocalRank: number;
+    maximumLatencyRatio: number;
+    maximumP99LatencyRatio: number;
+    minimumCapacityRetention: number;
+    maximumFalseForgettingRate: number;
+    maximumRevocationLeakage: number;
+    maximumProjectIsolationLeakage: number;
+}
+export interface PromotionEvaluation {
+    passed: boolean;
+    reasons: string[];
+    baseline: BenchmarkMetrics;
+    candidate: BenchmarkMetrics;
+    thresholds: PromotionThresholds;
+}
+export declare const DEFAULT_PROMOTION_THRESHOLDS: Readonly<PromotionThresholds>;
+export declare function benchmark(ranker: Ranker, cases: readonly BenchmarkCase[], options?: {
+    capacityRetention?: number;
+    forgottenRelevantIds?: ReadonlySet<string>;
+}): BenchmarkMetrics;
+export declare function evaluatePromotion(baseline: BenchmarkMetrics, candidate: BenchmarkMetrics, thresholds: PromotionThresholds): PromotionEvaluation;
+export declare class ShadowRetrievalRunner {
+    private readonly primary;
+    private readonly shadow;
+    private readonly onObservation?;
+    constructor(primary: Ranker, shadow: Ranker, onObservation?: ((observation: ShadowObservation) => void) | undefined);
+    retrieve(query: RetrievalQuery, items: readonly RetrievalItem[]): RankedItem[];
+}
+export interface ShadowObservation {
+    primaryBackend: string;
+    shadowBackend: string;
+    primaryIds: string[];
+    shadowIds: string[];
+    primaryLatencyMs: number;
+    shadowLatencyMs: number;
+    error?: string;
+}
+//# sourceMappingURL=evaluation.d.ts.map

package/dist/evaluation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluation.d.ts","sourceRoot":"","sources":["../src/evaluation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5E,MAAM,WAAW,MAAM;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,UAAU,EAAE,CAAC;CAC/E;AAED,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uBAAuB,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,yBAAyB,EAAE,MAAM,CAAC;IAClC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,wBAAwB,EAAE,MAAM,CAAC;IACjC,0BAA0B,EAAE,MAAM,CAAC;IACnC,wBAAwB,EAAE,MAAM,CAAC;IACjC,8BAA8B,EAAE,MAAM,CAAC;CACvC;AAED,MAAM,WAAW,mBAAmB;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,UAAU,EAAE,mBAAmB,CAAC;CAChC;AAED,eAAO,MAAM,4BAA4B,EAAE,QAAQ,CAAC,mBAAmB,CAStE,CAAC;AAEF,wBAAgB,SAAS,CACxB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,OAAO,GAAE;IAAE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAAC,oBAAoB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAAO,GACtF,gBAAgB,CA2ClB;AAED,wBAAgB,iBAAiB,CAChC,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,EAAE,gBAAgB,EAC3B,UAAU,EAAE,mBAAmB,GAC7B,mBAAmB,CAiBrB;AAED,qBAAa,qBAAqB;IAEhC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAHhC,YACkB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,aAAa,CAAC,wDAA0C,EACtE;IAEJ,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,UAAU,EAAE,CA2B7E;CACD;AAED,MAAM,WAAW,iBAAiB;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf","sourcesContent":["import { performance } from \"node:perf_hooks\";\nimport type { RankedItem, RetrievalItem, RetrievalQuery } from \"./types.js\";\n\nexport interface Ranker {\n\treadonly name: string;\n\tretrieve(query: RetrievalQuery, items: readonly RetrievalItem[]): RankedItem[];\n}\n\nexport interface BenchmarkCase {\n\tid: string;\n\tquery: RetrievalQuery;\n\titems: RetrievalItem[];\n\trelevantIds: string[];\n}\n\nexport interface BenchmarkMetrics {\n\trecallAtK: number;\n\tmeanReciprocalRank: number;\n\tp95LatencyMs: number;\n\tp99LatencyMs: number;\n\tcapacityRetention: number;\n\tfalseForgettingRate: number;\n\trevocationLeakage: number;\n\tprojectIsolationLeakage: number;\n}\n\nexport interface PromotionThresholds {\n\tminimumRecallAtK: number;\n\tminimumMeanReciprocalRank: number;\n\tmaximumLatencyRatio: number;\n\tmaximumP99LatencyRatio: number;\n\tminimumCapacityRetention: number;\n\tmaximumFalseForgettingRate: number;\n\tmaximumRevocationLeakage: number;\n\tmaximumProjectIsolationLeakage: number;\n}\n\nexport interface PromotionEvaluation {\n\tpassed: boolean;\n\treasons: string[];\n\tbaseline: BenchmarkMetrics;\n\tcandidate: BenchmarkMetrics;\n\tthresholds: PromotionThresholds;\n}\n\nexport const DEFAULT_PROMOTION_THRESHOLDS: Readonly<PromotionThresholds> = {\n\tminimumRecallAtK: 0.9,\n\tminimumMeanReciprocalRank: 0.85,\n\tmaximumLatencyRatio: 2,\n\tmaximumP99LatencyRatio: 2.5,\n\tminimumCapacityRetention: 0.95,\n\tmaximumFalseForgettingRate: 0.02,\n\tmaximumRevocationLeakage: 0,\n\tmaximumProjectIsolationLeakage: 0,\n};\n\nexport function benchmark(\n\tranker: Ranker,\n\tcases: readonly BenchmarkCase[],\n\toptions: { capacityRetention?: number; forgottenRelevantIds?: ReadonlySet<string> } = {},\n): BenchmarkMetrics {\n\tif (cases.length === 0) throw new Error(\"Benchmark requires frozen cases\");\n\tlet recall = 0;\n\tlet reciprocalRank = 0;\n\tlet revokedReturned = 0;\n\tlet crossProjectReturned = 0;\n\tlet totalReturned = 0;\n\tlet relevantCount = 0;\n\tlet forgotten = 0;\n\tconst latencies: number[] = [];\n\tfor (const fixture of cases) {\n\t\tconst started = performance.now();\n\t\tconst ranked = ranker.retrieve(fixture.query, fixture.items);\n\t\tlatencies.push(Math.max(0.001, performance.now() - started));\n\t\tconst ids = ranked.map((item) => item.id);\n\t\tconst relevant = new Set(fixture.relevantIds);\n\t\tconst hits = ids.filter((id) => relevant.has(id));\n\t\trecall += relevant.size === 0 ? 1 : hits.length / relevant.size;\n\t\tconst firstRelevant = ids.findIndex((id) => relevant.has(id));\n\t\treciprocalRank += firstRelevant < 0 ? 0 : 1 / (firstRelevant + 1);\n\t\trelevantCount += relevant.size;\n\t\tforgotten += fixture.relevantIds.filter((id) => options.forgottenRelevantIds?.has(id)).length;\n\t\tfor (const result of ranked) {\n\t\t\tconst item = fixture.items.find((candidate) => candidate.id === result.id);\n\t\t\tif (item?.revoked) revokedReturned++;\n\t\t\tif (item && (item.ownerId !== fixture.query.ownerId || item.projectId !== fixture.query.projectId))\n\t\t\t\tcrossProjectReturned++;\n\t\t\ttotalReturned++;\n\t\t}\n\t}\n\tlatencies.sort((left, right) => left - right);\n\tconst p95Index = Math.min(latencies.length - 1, Math.ceil(latencies.length * 0.95) - 1);\n\tconst p99Index = Math.min(latencies.length - 1, Math.ceil(latencies.length * 0.99) - 1);\n\treturn {\n\t\trecallAtK: recall / cases.length,\n\t\tmeanReciprocalRank: reciprocalRank / cases.length,\n\t\tp95LatencyMs: latencies[p95Index] ?? 0,\n\t\tp99LatencyMs: latencies[p99Index] ?? 0,\n\t\tcapacityRetention: options.capacityRetention ?? 1,\n\t\tfalseForgettingRate: relevantCount === 0 ? 0 : forgotten / relevantCount,\n\t\trevocationLeakage: totalReturned === 0 ? 0 : revokedReturned / totalReturned,\n\t\tprojectIsolationLeakage: totalReturned === 0 ? 0 : crossProjectReturned / totalReturned,\n\t};\n}\n\nexport function evaluatePromotion(\n\tbaseline: BenchmarkMetrics,\n\tcandidate: BenchmarkMetrics,\n\tthresholds: PromotionThresholds,\n): PromotionEvaluation {\n\tconst reasons: string[] = [];\n\tif (candidate.recallAtK < thresholds.minimumRecallAtK) reasons.push(\"recall_below_threshold\");\n\tif (candidate.meanReciprocalRank < thresholds.minimumMeanReciprocalRank) reasons.push(\"mrr_below_threshold\");\n\tconst latencyRatio = baseline.p95LatencyMs === 0 ? 1 : candidate.p95LatencyMs / baseline.p95LatencyMs;\n\tif (latencyRatio > thresholds.maximumLatencyRatio) reasons.push(\"latency_ratio_above_threshold\");\n\tconst p99LatencyRatio = baseline.p99LatencyMs === 0 ? 1 : candidate.p99LatencyMs / baseline.p99LatencyMs;\n\tif (p99LatencyRatio > thresholds.maximumP99LatencyRatio) reasons.push(\"p99_latency_ratio_above_threshold\");\n\tif (candidate.capacityRetention < thresholds.minimumCapacityRetention)\n\t\treasons.push(\"capacity_retention_below_threshold\");\n\tif (candidate.falseForgettingRate > thresholds.maximumFalseForgettingRate)\n\t\treasons.push(\"false_forgetting_above_threshold\");\n\tif (candidate.revocationLeakage > thresholds.maximumRevocationLeakage)\n\t\treasons.push(\"revocation_leakage_above_threshold\");\n\tif (candidate.projectIsolationLeakage > thresholds.maximumProjectIsolationLeakage)\n\t\treasons.push(\"project_isolation_leakage_above_threshold\");\n\treturn { passed: reasons.length === 0, reasons, baseline, candidate, thresholds };\n}\n\nexport class ShadowRetrievalRunner {\n\tconstructor(\n\t\tprivate readonly primary: Ranker,\n\t\tprivate readonly shadow: Ranker,\n\t\tprivate readonly onObservation?: (observation: ShadowObservation) => void,\n\t) {}\n\n\tretrieve(query: RetrievalQuery, items: readonly RetrievalItem[]): RankedItem[] {\n\t\tconst primaryStarted = performance.now();\n\t\tconst primary = this.primary.retrieve(query, items);\n\t\tconst primaryLatencyMs = performance.now() - primaryStarted;\n\t\ttry {\n\t\t\tconst shadowStarted = performance.now();\n\t\t\tconst shadow = this.shadow.retrieve(query, items);\n\t\t\tthis.onObservation?.({\n\t\t\t\tprimaryBackend: this.primary.name,\n\t\t\t\tshadowBackend: this.shadow.name,\n\t\t\t\tprimaryIds: primary.map((item) => item.id),\n\t\t\t\tshadowIds: shadow.map((item) => item.id),\n\t\t\t\tprimaryLatencyMs,\n\t\t\t\tshadowLatencyMs: performance.now() - shadowStarted,\n\t\t\t});\n\t\t} catch (error) {\n\t\t\tthis.onObservation?.({\n\t\t\t\tprimaryBackend: this.primary.name,\n\t\t\t\tshadowBackend: this.shadow.name,\n\t\t\t\tprimaryIds: primary.map((item) => item.id),\n\t\t\t\tshadowIds: [],\n\t\t\t\tprimaryLatencyMs,\n\t\t\t\tshadowLatencyMs: 0,\n\t\t\t\terror: error instanceof Error ? error.message : String(error),\n\t\t\t});\n\t\t}\n\t\treturn primary;\n\t}\n}\n\nexport interface ShadowObservation {\n\tprimaryBackend: string;\n\tshadowBackend: string;\n\tprimaryIds: string[];\n\tshadowIds: string[];\n\tprimaryLatencyMs: number;\n\tshadowLatencyMs: number;\n\terror?: string;\n}\n"]}

package/dist/evaluation.js

@@ -0,0 +1,119 @@
+import { performance } from "node:perf_hooks";
+export const DEFAULT_PROMOTION_THRESHOLDS = {
+    minimumRecallAtK: 0.9,
+    minimumMeanReciprocalRank: 0.85,
+    maximumLatencyRatio: 2,
+    maximumP99LatencyRatio: 2.5,
+    minimumCapacityRetention: 0.95,
+    maximumFalseForgettingRate: 0.02,
+    maximumRevocationLeakage: 0,
+    maximumProjectIsolationLeakage: 0,
+};
+export function benchmark(ranker, cases, options = {}) {
+    if (cases.length === 0)
+        throw new Error("Benchmark requires frozen cases");
+    let recall = 0;
+    let reciprocalRank = 0;
+    let revokedReturned = 0;
+    let crossProjectReturned = 0;
+    let totalReturned = 0;
+    let relevantCount = 0;
+    let forgotten = 0;
+    const latencies = [];
+    for (const fixture of cases) {
+        const started = performance.now();
+        const ranked = ranker.retrieve(fixture.query, fixture.items);
+        latencies.push(Math.max(0.001, performance.now() - started));
+        const ids = ranked.map((item) => item.id);
+        const relevant = new Set(fixture.relevantIds);
+        const hits = ids.filter((id) => relevant.has(id));
+        recall += relevant.size === 0 ? 1 : hits.length / relevant.size;
+        const firstRelevant = ids.findIndex((id) => relevant.has(id));
+        reciprocalRank += firstRelevant < 0 ? 0 : 1 / (firstRelevant + 1);
+        relevantCount += relevant.size;
+        forgotten += fixture.relevantIds.filter((id) => options.forgottenRelevantIds?.has(id)).length;
+        for (const result of ranked) {
+            const item = fixture.items.find((candidate) => candidate.id === result.id);
+            if (item?.revoked)
+                revokedReturned++;
+            if (item && (item.ownerId !== fixture.query.ownerId || item.projectId !== fixture.query.projectId))
+                crossProjectReturned++;
+            totalReturned++;
+        }
+    }
+    latencies.sort((left, right) => left - right);
+    const p95Index = Math.min(latencies.length - 1, Math.ceil(latencies.length * 0.95) - 1);
+    const p99Index = Math.min(latencies.length - 1, Math.ceil(latencies.length * 0.99) - 1);
+    return {
+        recallAtK: recall / cases.length,
+        meanReciprocalRank: reciprocalRank / cases.length,
+        p95LatencyMs: latencies[p95Index] ?? 0,
+        p99LatencyMs: latencies[p99Index] ?? 0,
+        capacityRetention: options.capacityRetention ?? 1,
+        falseForgettingRate: relevantCount === 0 ? 0 : forgotten / relevantCount,
+        revocationLeakage: totalReturned === 0 ? 0 : revokedReturned / totalReturned,
+        projectIsolationLeakage: totalReturned === 0 ? 0 : crossProjectReturned / totalReturned,
+    };
+}
+export function evaluatePromotion(baseline, candidate, thresholds) {
+    const reasons = [];
+    if (candidate.recallAtK < thresholds.minimumRecallAtK)
+        reasons.push("recall_below_threshold");
+    if (candidate.meanReciprocalRank < thresholds.minimumMeanReciprocalRank)
+        reasons.push("mrr_below_threshold");
+    const latencyRatio = baseline.p95LatencyMs === 0 ? 1 : candidate.p95LatencyMs / baseline.p95LatencyMs;
+    if (latencyRatio > thresholds.maximumLatencyRatio)
+        reasons.push("latency_ratio_above_threshold");
+    const p99LatencyRatio = baseline.p99LatencyMs === 0 ? 1 : candidate.p99LatencyMs / baseline.p99LatencyMs;
+    if (p99LatencyRatio > thresholds.maximumP99LatencyRatio)
+        reasons.push("p99_latency_ratio_above_threshold");
+    if (candidate.capacityRetention < thresholds.minimumCapacityRetention)
+        reasons.push("capacity_retention_below_threshold");
+    if (candidate.falseForgettingRate > thresholds.maximumFalseForgettingRate)
+        reasons.push("false_forgetting_above_threshold");
+    if (candidate.revocationLeakage > thresholds.maximumRevocationLeakage)
+        reasons.push("revocation_leakage_above_threshold");
+    if (candidate.projectIsolationLeakage > thresholds.maximumProjectIsolationLeakage)
+        reasons.push("project_isolation_leakage_above_threshold");
+    return { passed: reasons.length === 0, reasons, baseline, candidate, thresholds };
+}
+export class ShadowRetrievalRunner {
+    primary;
+    shadow;
+    onObservation;
+    constructor(primary, shadow, onObservation) {
+        this.primary = primary;
+        this.shadow = shadow;
+        this.onObservation = onObservation;
+    }
+    retrieve(query, items) {
+        const primaryStarted = performance.now();
+        const primary = this.primary.retrieve(query, items);
+        const primaryLatencyMs = performance.now() - primaryStarted;
+        try {
+            const shadowStarted = performance.now();
+            const shadow = this.shadow.retrieve(query, items);
+            this.onObservation?.({
+                primaryBackend: this.primary.name,
+                shadowBackend: this.shadow.name,
+                primaryIds: primary.map((item) => item.id),
+                shadowIds: shadow.map((item) => item.id),
+                primaryLatencyMs,
+                shadowLatencyMs: performance.now() - shadowStarted,
+            });
+        }
+        catch (error) {
+            this.onObservation?.({
+                primaryBackend: this.primary.name,
+                shadowBackend: this.shadow.name,
+                primaryIds: primary.map((item) => item.id),
+                shadowIds: [],
+                primaryLatencyMs,
+                shadowLatencyMs: 0,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        return primary;
+    }
+}
+//# sourceMappingURL=evaluation.js.map