@ai-agent-forge/plugin-memory 0.85.0

package/dist/memory/model-cache-hygiene.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Zero-byte cache-artifact hygiene for transformers.js model downloads.
+ *
+ * A failed download attempt (unreachable mirror, aborted transfer) can leave a
+ * 0-byte file in the cache; transformers.js then treats the file as a cache
+ * hit on the NEXT attempt — including attempts against a different mirror —
+ * and never heals. Empty tokenizer/weight files are unambiguously failed
+ * downloads (real tokenizer.json is never empty), so the mirror-rotation loop
+ * purges zero-byte files between hosts. Non-empty-but-truncated files are
+ * deliberately NOT touched: those stay terminal per 设计 §3.2 (manual action
+ * list), because deleting user-provided manual imports on a guess would be
+ * worse than failing loudly.
+ *
+ * Best effort: purge failures propagate — if we cannot even delete an empty
+ * file, the subsequent download attempt should fail with that truth.
+ */
+export declare function purgeZeroByteCacheArtifacts(modelDir: string): void;
+//# sourceMappingURL=model-cache-hygiene.d.ts.map

package/dist/memory/model-cache-hygiene.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-cache-hygiene.d.ts","sourceRoot":"","sources":["../../src/memory/model-cache-hygiene.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAiBlE","sourcesContent":["import type { Dirent } from \"node:fs\";\nimport { readdirSync, rmSync, statSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\n/**\n * Zero-byte cache-artifact hygiene for transformers.js model downloads.\n *\n * A failed download attempt (unreachable mirror, aborted transfer) can leave a\n * 0-byte file in the cache; transformers.js then treats the file as a cache\n * hit on the NEXT attempt — including attempts against a different mirror —\n * and never heals. Empty tokenizer/weight files are unambiguously failed\n * downloads (real tokenizer.json is never empty), so the mirror-rotation loop\n * purges zero-byte files between hosts. Non-empty-but-truncated files are\n * deliberately NOT touched: those stay terminal per 设计 §3.2 (manual action\n * list), because deleting user-provided manual imports on a guess would be\n * worse than failing loudly.\n *\n * Best effort: purge failures propagate — if we cannot even delete an empty\n * file, the subsequent download attempt should fail with that truth.\n */\nexport function purgeZeroByteCacheArtifacts(modelDir: string): void {\n\tlet entries: Dirent[];\n\ttry {\n\t\tentries = readdirSync(modelDir, { withFileTypes: true }) as Dirent[];\n\t} catch {\n\t\treturn; // No dir yet = nothing to purge.\n\t}\n\tfor (const entry of entries) {\n\t\tconst entryPath = join(modelDir, entry.name.toString());\n\t\tif (entry.isDirectory()) {\n\t\t\tpurgeZeroByteCacheArtifacts(entryPath);\n\t\t\tcontinue;\n\t\t}\n\t\tif (statSync(entryPath).size === 0) {\n\t\t\trmSync(entryPath, { force: true });\n\t\t}\n\t}\n}\n"]}

package/dist/memory/model-cache-hygiene.js

@@ -0,0 +1,38 @@
+import { readdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Zero-byte cache-artifact hygiene for transformers.js model downloads.
+ *
+ * A failed download attempt (unreachable mirror, aborted transfer) can leave a
+ * 0-byte file in the cache; transformers.js then treats the file as a cache
+ * hit on the NEXT attempt — including attempts against a different mirror —
+ * and never heals. Empty tokenizer/weight files are unambiguously failed
+ * downloads (real tokenizer.json is never empty), so the mirror-rotation loop
+ * purges zero-byte files between hosts. Non-empty-but-truncated files are
+ * deliberately NOT touched: those stay terminal per 设计 §3.2 (manual action
+ * list), because deleting user-provided manual imports on a guess would be
+ * worse than failing loudly.
+ *
+ * Best effort: purge failures propagate — if we cannot even delete an empty
+ * file, the subsequent download attempt should fail with that truth.
+ */
+export function purgeZeroByteCacheArtifacts(modelDir) {
+    let entries;
+    try {
+        entries = readdirSync(modelDir, { withFileTypes: true });
+    }
+    catch {
+        return; // No dir yet = nothing to purge.
+    }
+    for (const entry of entries) {
+        const entryPath = join(modelDir, entry.name.toString());
+        if (entry.isDirectory()) {
+            purgeZeroByteCacheArtifacts(entryPath);
+            continue;
+        }
+        if (statSync(entryPath).size === 0) {
+            rmSync(entryPath, { force: true });
+        }
+    }
+}
+//# sourceMappingURL=model-cache-hygiene.js.map

package/dist/memory/model-cache-hygiene.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-cache-hygiene.js","sourceRoot":"","sources":["../../src/memory/model-cache-hygiene.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,2BAA2B,CAAC,QAAgB,EAAQ;IACnE,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACJ,OAAO,GAAG,WAAW,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAa,CAAC;IACtE,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,CAAC,iCAAiC;IAC1C,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACxD,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACzB,2BAA2B,CAAC,SAAS,CAAC,CAAC;YACvC,SAAS;QACV,CAAC;QACD,IAAI,QAAQ,CAAC,SAAS,CAAC,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACpC,MAAM,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACpC,CAAC;IACF,CAAC;AAAA,CACD","sourcesContent":["import type { Dirent } from \"node:fs\";\nimport { readdirSync, rmSync, statSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\n/**\n * Zero-byte cache-artifact hygiene for transformers.js model downloads.\n *\n * A failed download attempt (unreachable mirror, aborted transfer) can leave a\n * 0-byte file in the cache; transformers.js then treats the file as a cache\n * hit on the NEXT attempt — including attempts against a different mirror —\n * and never heals. Empty tokenizer/weight files are unambiguously failed\n * downloads (real tokenizer.json is never empty), so the mirror-rotation loop\n * purges zero-byte files between hosts. Non-empty-but-truncated files are\n * deliberately NOT touched: those stay terminal per 设计 §3.2 (manual action\n * list), because deleting user-provided manual imports on a guess would be\n * worse than failing loudly.\n *\n * Best effort: purge failures propagate — if we cannot even delete an empty\n * file, the subsequent download attempt should fail with that truth.\n */\nexport function purgeZeroByteCacheArtifacts(modelDir: string): void {\n\tlet entries: Dirent[];\n\ttry {\n\t\tentries = readdirSync(modelDir, { withFileTypes: true }) as Dirent[];\n\t} catch {\n\t\treturn; // No dir yet = nothing to purge.\n\t}\n\tfor (const entry of entries) {\n\t\tconst entryPath = join(modelDir, entry.name.toString());\n\t\tif (entry.isDirectory()) {\n\t\t\tpurgeZeroByteCacheArtifacts(entryPath);\n\t\t\tcontinue;\n\t\t}\n\t\tif (statSync(entryPath).size === 0) {\n\t\t\trmSync(entryPath, { force: true });\n\t\t}\n\t}\n}\n"]}

package/dist/memory/preference-disambiguator.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Complex semantic disambiguator (2.4d2) — deterministic, replayable
+ * disambiguation over competing preference candidates that a resolver marked
+ * conflicting (2.4c `conflict_unconfirmed`).
+ *
+ * Scope-specificity signal, most specific wins:
+ *   task match > project match > scene match > scopeless.
+ * When the signal cannot separate the candidates (ties at the same
+ * specificity level), the outcome is `unresolvable` — every candidate fact
+ * (value, scope, evidence class, confidence) is included in the structured
+ * explanation so the boundary stays auditable and the caller can surface an
+ * explicit user choice. The same input always yields the same decision and
+ * explanation. Relation diffusion and Memory Networks are out of scope.
+ */
+import type { JsonValue } from "@agent-forge/plugin-sdk";
+import type { MemoryPreferenceEnvelopeV1 } from "./foundation.ts";
+export interface DisambiguationCandidateV1 {
+    readonly memoryId: string;
+    readonly preferredValue: JsonValue;
+    readonly scope: MemoryPreferenceEnvelopeV1["scope"];
+    readonly evidenceClass: MemoryPreferenceEnvelopeV1["evidence"]["class"];
+    readonly applicabilityConfidence: number;
+}
+export interface DisambiguationContextV1 {
+    readonly scenes?: readonly string[];
+    readonly projects?: readonly string[];
+    readonly tasks?: readonly string[];
+}
+export type DisambiguationOutcomeV1 = {
+    readonly status: "resolved";
+    readonly winnerMemoryId: string;
+    readonly winnerValue: JsonValue;
+    readonly basis: "task" | "project" | "scene" | "scopeless";
+    readonly explanation: readonly string[];
+} | {
+    readonly status: "unresolvable";
+    readonly explanation: readonly string[];
+};
+export interface PreferenceDisambiguatorV1 {
+    disambiguate(candidates: readonly DisambiguationCandidateV1[], context: DisambiguationContextV1): DisambiguationOutcomeV1;
+}
+export declare function createPreferenceDisambiguator(): PreferenceDisambiguatorV1;
+//# sourceMappingURL=preference-disambiguator.d.ts.map

package/dist/memory/preference-disambiguator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preference-disambiguator.d.ts","sourceRoot":"","sources":["../../src/memory/preference-disambiguator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAElE,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,SAAS,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC,OAAO,CAAC,CAAC;IACpD,QAAQ,CAAC,aAAa,EAAE,0BAA0B,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,CAAC;IACxE,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;CACzC;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,MAAM,uBAAuB,GAChC;IACA,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,CAAC;IAC3D,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GACD;IACA,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,CAAC;AAEL,MAAM,WAAW,yBAAyB;IACzC,YAAY,CACX,UAAU,EAAE,SAAS,yBAAyB,EAAE,EAChD,OAAO,EAAE,uBAAuB,GAC9B,uBAAuB,CAAC;CAC3B;AAqCD,wBAAgB,6BAA6B,IAAI,yBAAyB,CA0DzE","sourcesContent":["/**\n * Complex semantic disambiguator (2.4d2) — deterministic, replayable\n * disambiguation over competing preference candidates that a resolver marked\n * conflicting (2.4c `conflict_unconfirmed`).\n *\n * Scope-specificity signal, most specific wins:\n *   task match > project match > scene match > scopeless.\n * When the signal cannot separate the candidates (ties at the same\n * specificity level), the outcome is `unresolvable` — every candidate fact\n * (value, scope, evidence class, confidence) is included in the structured\n * explanation so the boundary stays auditable and the caller can surface an\n * explicit user choice. The same input always yields the same decision and\n * explanation. Relation diffusion and Memory Networks are out of scope.\n */\nimport type { JsonValue } from \"@agent-forge/plugin-sdk\";\nimport type { MemoryPreferenceEnvelopeV1 } from \"./foundation.ts\";\n\nexport interface DisambiguationCandidateV1 {\n\treadonly memoryId: string;\n\treadonly preferredValue: JsonValue;\n\treadonly scope: MemoryPreferenceEnvelopeV1[\"scope\"];\n\treadonly evidenceClass: MemoryPreferenceEnvelopeV1[\"evidence\"][\"class\"];\n\treadonly applicabilityConfidence: number;\n}\n\nexport interface DisambiguationContextV1 {\n\treadonly scenes?: readonly string[];\n\treadonly projects?: readonly string[];\n\treadonly tasks?: readonly string[];\n}\n\nexport type DisambiguationOutcomeV1 =\n\t| {\n\t\t\treadonly status: \"resolved\";\n\t\t\treadonly winnerMemoryId: string;\n\t\t\treadonly winnerValue: JsonValue;\n\t\t\treadonly basis: \"task\" | \"project\" | \"scene\" | \"scopeless\";\n\t\t\treadonly explanation: readonly string[];\n\t  }\n\t| {\n\t\t\treadonly status: \"unresolvable\";\n\t\t\treadonly explanation: readonly string[];\n\t  };\n\nexport interface PreferenceDisambiguatorV1 {\n\tdisambiguate(\n\t\tcandidates: readonly DisambiguationCandidateV1[],\n\t\tcontext: DisambiguationContextV1,\n\t): DisambiguationOutcomeV1;\n}\n\nconst SPECIFICITY_ORDER = [\"task\", \"project\", \"scene\", \"scopeless\"] as const;\ntype SpecificityLevel = (typeof SPECIFICITY_ORDER)[number];\n\nfunction candidateSpecificity(\n\tcandidate: DisambiguationCandidateV1,\n\tcontext: DisambiguationContextV1,\n): SpecificityLevel | undefined {\n\tconst scope = candidate.scope;\n\tconst intersects = (scopeValues: readonly string[] | undefined, current: readonly string[] | undefined): boolean =>\n\t\tscopeValues !== undefined && current !== undefined && scopeValues.some((value) => current.includes(value));\n\tif (intersects(scope.tasks, context.tasks)) return \"task\";\n\tif (intersects(scope.projects, context.projects)) return \"project\";\n\tif (intersects(scope.scenes, context.scenes)) return \"scene\";\n\tif (\n\t\t(scope.tasks === undefined || scope.tasks.length === 0) &&\n\t\t(scope.projects === undefined || scope.projects.length === 0) &&\n\t\t(scope.scenes === undefined || scope.scenes.length === 0)\n\t) {\n\t\treturn \"scopeless\";\n\t}\n\t// The candidate's scope exists but does not match the current context.\n\treturn undefined;\n}\n\nfunction describeCandidate(candidate: DisambiguationCandidateV1): string {\n\tconst scope = candidate.scope;\n\tconst scopeText = JSON.stringify({\n\t\tlevel: scope.level,\n\t\ttasks: scope.tasks ?? [],\n\t\tprojects: scope.projects ?? [],\n\t\tscenes: scope.scenes ?? [],\n\t});\n\treturn `candidate ${candidate.memoryId} value=${JSON.stringify(candidate.preferredValue)} evidence=${candidate.evidenceClass} confidence=${candidate.applicabilityConfidence} scope=${scopeText}`;\n}\n\nexport function createPreferenceDisambiguator(): PreferenceDisambiguatorV1 {\n\treturn {\n\t\tdisambiguate(candidates, context) {\n\t\t\tif (candidates.length < 2) {\n\t\t\t\treturn {\n\t\t\t\t\tstatus: \"unresolvable\",\n\t\t\t\t\texplanation: [\"Disambiguation requires at least two competing candidates\"],\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst explanations = candidates.map(describeCandidate);\n\t\t\tconst scored = candidates.map((candidate) => ({\n\t\t\t\tcandidate,\n\t\t\t\tlevel: candidateSpecificity(candidate, context),\n\t\t\t}));\n\t\t\tconst matched = scored.filter(\n\t\t\t\t(entry): entry is { candidate: DisambiguationCandidateV1; level: SpecificityLevel } =>\n\t\t\t\t\tentry.level !== undefined,\n\t\t\t);\n\t\t\tif (matched.length === 0) {\n\t\t\t\treturn {\n\t\t\t\t\tstatus: \"unresolvable\",\n\t\t\t\t\texplanation: [\"No candidate scope matches the current context\", ...explanations],\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst bestLevel = matched.reduce(\n\t\t\t\t(best, entry) =>\n\t\t\t\t\tSPECIFICITY_ORDER.indexOf(entry.level) < SPECIFICITY_ORDER.indexOf(best) ? entry.level : best,\n\t\t\t\t\"scopeless\" as SpecificityLevel,\n\t\t\t);\n\t\t\tconst finalists = matched.filter((entry) => entry.level === bestLevel);\n\t\t\tif (finalists.length !== 1) {\n\t\t\t\treturn {\n\t\t\t\t\tstatus: \"unresolvable\",\n\t\t\t\t\texplanation: [\n\t\t\t\t\t\t`${finalists.length} candidates tie at scope specificity \"${bestLevel}\"; explicit confirmation required`,\n\t\t\t\t\t\t...explanations,\n\t\t\t\t\t],\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst winner = finalists[0]!.candidate;\n\t\t\tconst losers = matched.filter((entry) => entry.candidate !== winner);\n\t\t\tconst unmatched = scored.length - matched.length;\n\t\t\treturn {\n\t\t\t\tstatus: \"resolved\",\n\t\t\t\twinnerMemoryId: winner.memoryId,\n\t\t\t\twinnerValue: winner.preferredValue,\n\t\t\t\tbasis: bestLevel,\n\t\t\t\texplanation: [\n\t\t\t\t\t`Winner ${winner.memoryId} selected by scope specificity \"${bestLevel}\"`,\n\t\t\t\t\t...losers.map((entry) => `Loser ${entry.candidate.memoryId} at specificity \"${entry.level}\"`),\n\t\t\t\t\t...(unmatched > 0\n\t\t\t\t\t\t? [`${unmatched} candidate(s) excluded: scope does not match the current context`]\n\t\t\t\t\t\t: []),\n\t\t\t\t\t...explanations,\n\t\t\t\t],\n\t\t\t};\n\t\t},\n\t};\n}\n"]}

package/dist/memory/preference-disambiguator.js

@@ -0,0 +1,81 @@
+const SPECIFICITY_ORDER = ["task", "project", "scene", "scopeless"];
+function candidateSpecificity(candidate, context) {
+    const scope = candidate.scope;
+    const intersects = (scopeValues, current) => scopeValues !== undefined && current !== undefined && scopeValues.some((value) => current.includes(value));
+    if (intersects(scope.tasks, context.tasks))
+        return "task";
+    if (intersects(scope.projects, context.projects))
+        return "project";
+    if (intersects(scope.scenes, context.scenes))
+        return "scene";
+    if ((scope.tasks === undefined || scope.tasks.length === 0) &&
+        (scope.projects === undefined || scope.projects.length === 0) &&
+        (scope.scenes === undefined || scope.scenes.length === 0)) {
+        return "scopeless";
+    }
+    // The candidate's scope exists but does not match the current context.
+    return undefined;
+}
+function describeCandidate(candidate) {
+    const scope = candidate.scope;
+    const scopeText = JSON.stringify({
+        level: scope.level,
+        tasks: scope.tasks ?? [],
+        projects: scope.projects ?? [],
+        scenes: scope.scenes ?? [],
+    });
+    return `candidate ${candidate.memoryId} value=${JSON.stringify(candidate.preferredValue)} evidence=${candidate.evidenceClass} confidence=${candidate.applicabilityConfidence} scope=${scopeText}`;
+}
+export function createPreferenceDisambiguator() {
+    return {
+        disambiguate(candidates, context) {
+            if (candidates.length < 2) {
+                return {
+                    status: "unresolvable",
+                    explanation: ["Disambiguation requires at least two competing candidates"],
+                };
+            }
+            const explanations = candidates.map(describeCandidate);
+            const scored = candidates.map((candidate) => ({
+                candidate,
+                level: candidateSpecificity(candidate, context),
+            }));
+            const matched = scored.filter((entry) => entry.level !== undefined);
+            if (matched.length === 0) {
+                return {
+                    status: "unresolvable",
+                    explanation: ["No candidate scope matches the current context", ...explanations],
+                };
+            }
+            const bestLevel = matched.reduce((best, entry) => SPECIFICITY_ORDER.indexOf(entry.level) < SPECIFICITY_ORDER.indexOf(best) ? entry.level : best, "scopeless");
+            const finalists = matched.filter((entry) => entry.level === bestLevel);
+            if (finalists.length !== 1) {
+                return {
+                    status: "unresolvable",
+                    explanation: [
+                        `${finalists.length} candidates tie at scope specificity "${bestLevel}"; explicit confirmation required`,
+                        ...explanations,
+                    ],
+                };
+            }
+            const winner = finalists[0].candidate;
+            const losers = matched.filter((entry) => entry.candidate !== winner);
+            const unmatched = scored.length - matched.length;
+            return {
+                status: "resolved",
+                winnerMemoryId: winner.memoryId,
+                winnerValue: winner.preferredValue,
+                basis: bestLevel,
+                explanation: [
+                    `Winner ${winner.memoryId} selected by scope specificity "${bestLevel}"`,
+                    ...losers.map((entry) => `Loser ${entry.candidate.memoryId} at specificity "${entry.level}"`),
+                    ...(unmatched > 0
+                        ? [`${unmatched} candidate(s) excluded: scope does not match the current context`]
+                        : []),
+                    ...explanations,
+                ],
+            };
+        },
+    };
+}
+//# sourceMappingURL=preference-disambiguator.js.map

package/dist/memory/preference-disambiguator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preference-disambiguator.js","sourceRoot":"","sources":["../../src/memory/preference-disambiguator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Complex semantic disambiguator (2.4d2) — deterministic, replayable\n * disambiguation over competing preference candidates that a resolver marked\n * conflicting (2.4c `conflict_unconfirmed`).\n *\n * Scope-specificity signal, most specific wins:\n *   task match > project match > scene match > scopeless.\n * When the signal cannot separate the candidates (ties at the same\n * specificity level), the outcome is `unresolvable` — every candidate fact\n * (value, scope, evidence class, confidence) is included in the structured\n * explanation so the boundary stays auditable and the caller can surface an\n * explicit user choice. The same input always yields the same decision and\n * explanation. Relation diffusion and Memory Networks are out of scope.\n */\nimport type { JsonValue } from \"@agent-forge/plugin-sdk\";\nimport type { MemoryPreferenceEnvelopeV1 } from \"./foundation.ts\";\n\nexport interface DisambiguationCandidateV1 {\n\treadonly memoryId: string;\n\treadonly preferredValue: JsonValue;\n\treadonly scope: MemoryPreferenceEnvelopeV1[\"scope\"];\n\treadonly evidenceClass: MemoryPreferenceEnvelopeV1[\"evidence\"][\"class\"];\n\treadonly applicabilityConfidence: number;\n}\n\nexport interface DisambiguationContextV1 {\n\treadonly scenes?: readonly string[];\n\treadonly projects?: readonly string[];\n\treadonly tasks?: readonly string[];\n}\n\nexport type DisambiguationOutcomeV1 =\n\t| {\n\t\t\treadonly status: \"resolved\";\n\t\t\treadonly winnerMemoryId: string;\n\t\t\treadonly winnerValue: JsonValue;\n\t\t\treadonly basis: \"task\" | \"project\" | \"scene\" | \"scopeless\";\n\t\t\treadonly explanation: readonly string[];\n\t  }\n\t| {\n\t\t\treadonly status: \"unresolvable\";\n\t\t\treadonly explanation: readonly string[];\n\t  };\n\nexport interface PreferenceDisambiguatorV1 {\n\tdisambiguate(\n\t\tcandidates: readonly DisambiguationCandidateV1[],\n\t\tcontext: DisambiguationContextV1,\n\t): DisambiguationOutcomeV1;\n}\n\nconst SPECIFICITY_ORDER = [\"task\", \"project\", \"scene\", \"scopeless\"] as const;\ntype SpecificityLevel = (typeof SPECIFICITY_ORDER)[number];\n\nfunction candidateSpecificity(\n\tcandidate: DisambiguationCandidateV1,\n\tcontext: DisambiguationContextV1,\n): SpecificityLevel | undefined {\n\tconst scope = candidate.scope;\n\tconst intersects = (scopeValues: readonly string[] | undefined, current: readonly string[] | undefined): boolean =>\n\t\tscopeValues !== undefined && current !== undefined && scopeValues.some((value) => current.includes(value));\n\tif (intersects(scope.tasks, context.tasks)) return \"task\";\n\tif (intersects(scope.projects, context.projects)) return \"project\";\n\tif (intersects(scope.scenes, context.scenes)) return \"scene\";\n\tif (\n\t\t(scope.tasks === undefined || scope.tasks.length === 0) &&\n\t\t(scope.projects === undefined || scope.projects.length === 0) &&\n\t\t(scope.scenes === undefined || scope.scenes.length === 0)\n\t) {\n\t\treturn \"scopeless\";\n\t}\n\t// The candidate's scope exists but does not match the current context.\n\treturn undefined;\n}\n\nfunction describeCandidate(candidate: DisambiguationCandidateV1): string {\n\tconst scope = candidate.scope;\n\tconst scopeText = JSON.stringify({\n\t\tlevel: scope.level,\n\t\ttasks: scope.tasks ?? [],\n\t\tprojects: scope.projects ?? [],\n\t\tscenes: scope.scenes ?? [],\n\t});\n\treturn `candidate ${candidate.memoryId} value=${JSON.stringify(candidate.preferredValue)} evidence=${candidate.evidenceClass} confidence=${candidate.applicabilityConfidence} scope=${scopeText}`;\n}\n\nexport function createPreferenceDisambiguator(): PreferenceDisambiguatorV1 {\n\treturn {\n\t\tdisambiguate(candidates, context) {\n\t\t\tif (candidates.length < 2) {\n\t\t\t\treturn {\n\t\t\t\t\tstatus: \"unresolvable\",\n\t\t\t\t\texplanation: [\"Disambiguation requires at least two competing candidates\"],\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst explanations = candidates.map(describeCandidate);\n\t\t\tconst scored = candidates.map((candidate) => ({\n\t\t\t\tcandidate,\n\t\t\t\tlevel: candidateSpecificity(candidate, context),\n\t\t\t}));\n\t\t\tconst matched = scored.filter(\n\t\t\t\t(entry): entry is { candidate: DisambiguationCandidateV1; level: SpecificityLevel } =>\n\t\t\t\t\tentry.level !== undefined,\n\t\t\t);\n\t\t\tif (matched.length === 0) {\n\t\t\t\treturn {\n\t\t\t\t\tstatus: \"unresolvable\",\n\t\t\t\t\texplanation: [\"No candidate scope matches the current context\", ...explanations],\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst bestLevel = matched.reduce(\n\t\t\t\t(best, entry) =>\n\t\t\t\t\tSPECIFICITY_ORDER.indexOf(entry.level) < SPECIFICITY_ORDER.indexOf(best) ? entry.level : best,\n\t\t\t\t\"scopeless\" as SpecificityLevel,\n\t\t\t);\n\t\t\tconst finalists = matched.filter((entry) => entry.level === bestLevel);\n\t\t\tif (finalists.length !== 1) {\n\t\t\t\treturn {\n\t\t\t\t\tstatus: \"unresolvable\",\n\t\t\t\t\texplanation: [\n\t\t\t\t\t\t`${finalists.length} candidates tie at scope specificity \"${bestLevel}\"; explicit confirmation required`,\n\t\t\t\t\t\t...explanations,\n\t\t\t\t\t],\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst winner = finalists[0]!.candidate;\n\t\t\tconst losers = matched.filter((entry) => entry.candidate !== winner);\n\t\t\tconst unmatched = scored.length - matched.length;\n\t\t\treturn {\n\t\t\t\tstatus: \"resolved\",\n\t\t\t\twinnerMemoryId: winner.memoryId,\n\t\t\t\twinnerValue: winner.preferredValue,\n\t\t\t\tbasis: bestLevel,\n\t\t\t\texplanation: [\n\t\t\t\t\t`Winner ${winner.memoryId} selected by scope specificity \"${bestLevel}\"`,\n\t\t\t\t\t...losers.map((entry) => `Loser ${entry.candidate.memoryId} at specificity \"${entry.level}\"`),\n\t\t\t\t\t...(unmatched > 0\n\t\t\t\t\t\t? [`${unmatched} candidate(s) excluded: scope does not match the current context`]\n\t\t\t\t\t\t: []),\n\t\t\t\t\t...explanations,\n\t\t\t\t],\n\t\t\t};\n\t\t},\n\t};\n}\n"]}

package/dist/memory/preference-lifecycle.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Complete preference lifecycle projection (2.4d3) — promotion (2.4d1),
+ * deterministic decay, reactivation, and archiving over an event sequence.
+ *
+ * The projection is a pure fold over a replayable event log: the same event
+ * sequence always yields the same state and transition audit, on any
+ * projection instance. Decay uses the 1C.6b half-life formula
+ * w × 2^(-elapsed/halfLife) anchored at the last usage/promotion; falling
+ * below the floor marks the preference `decayed` (kept in the ledger, hidden
+ * from recall per 1C store semantics). New evidence reactivates a decayed
+ * preference; archiving is terminal and ignores later events. Every
+ * transition records the policy version that governed it, so policy
+ * migrations are auditable across replays. Relation networks and advanced
+ * indexing remain out of scope (2.4d4).
+ */
+import type { PreferenceEvidenceClassV1 } from "./preference-promotion.ts";
+export interface PreferenceLifecyclePolicyV1 {
+    readonly policyVersion: string;
+    readonly halfLifeMs: number;
+    /** Confidence at or below which the preference becomes `decayed` (0..1). */
+    readonly decayFloor: number;
+    /** Confidence assigned on reactivation from `decayed`. */
+    readonly reactivationConfidence: number;
+}
+export type PreferenceLifecycleEventV1 = {
+    readonly kind: "observed";
+    readonly at: number;
+    readonly evidenceClass: PreferenceEvidenceClassV1;
+} | {
+    readonly kind: "promoted";
+    readonly at: number;
+    readonly toConfidence: number;
+    readonly policyVersion: string;
+} | {
+    readonly kind: "used";
+    readonly at: number;
+} | {
+    readonly kind: "decay_tick";
+    readonly at: number;
+} | {
+    readonly kind: "archive";
+    readonly at: number;
+    readonly reason: string;
+};
+export type PreferenceLifecycleStateV1 = "active" | "decayed" | "archived";
+export interface PreferenceLifecycleTransitionV1 {
+    readonly kind: "observed" | "promoted" | "used" | "decay_tick" | "decayed" | "reactivated" | "archived" | "ignored";
+    readonly at: number;
+    readonly confidence: number;
+    readonly state: PreferenceLifecycleStateV1;
+    readonly policyVersion: string;
+    readonly detail?: string;
+}
+export interface PreferenceLifecycleProjectionV1 {
+    readonly state: PreferenceLifecycleStateV1;
+    readonly confidence: number;
+    readonly transitions: readonly PreferenceLifecycleTransitionV1[];
+}
+export interface PreferenceLifecycleProjectorV1 {
+    project(events: readonly PreferenceLifecycleEventV1[], initialConfidence?: number): PreferenceLifecycleProjectionV1;
+    readonly policyVersion: string;
+}
+export declare function createPreferenceLifecycleProjector(options: {
+    readonly policy: PreferenceLifecyclePolicyV1;
+}): PreferenceLifecycleProjectorV1;
+//# sourceMappingURL=preference-lifecycle.d.ts.map

package/dist/memory/preference-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preference-lifecycle.d.ts","sourceRoot":"","sources":["../../src/memory/preference-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAE3E,MAAM,WAAW,2BAA2B;IAC3C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,MAAM,0BAA0B,GACnC;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,yBAAyB,CAAA;CAAE,GACrG;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GACjH;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9E,MAAM,MAAM,0BAA0B,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AAE3E,MAAM,WAAW,+BAA+B;IAC/C,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,YAAY,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,GAAG,SAAS,CAAC;IACpH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC;IAC3C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,+BAA+B;IAC/C,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,SAAS,+BAA+B,EAAE,CAAC;CACjE;AAED,MAAM,WAAW,8BAA8B;IAC9C,OAAO,CAAC,MAAM,EAAE,SAAS,0BAA0B,EAAE,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,+BAA+B,CAAC;IACpH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,kCAAkC,CAAC,OAAO,EAAE;IAC3D,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;CAC7C,GAAG,8BAA8B,CA6HjC","sourcesContent":["/**\n * Complete preference lifecycle projection (2.4d3) — promotion (2.4d1),\n * deterministic decay, reactivation, and archiving over an event sequence.\n *\n * The projection is a pure fold over a replayable event log: the same event\n * sequence always yields the same state and transition audit, on any\n * projection instance. Decay uses the 1C.6b half-life formula\n * w × 2^(-elapsed/halfLife) anchored at the last usage/promotion; falling\n * below the floor marks the preference `decayed` (kept in the ledger, hidden\n * from recall per 1C store semantics). New evidence reactivates a decayed\n * preference; archiving is terminal and ignores later events. Every\n * transition records the policy version that governed it, so policy\n * migrations are auditable across replays. Relation networks and advanced\n * indexing remain out of scope (2.4d4).\n */\nimport type { PreferenceEvidenceClassV1 } from \"./preference-promotion.ts\";\n\nexport interface PreferenceLifecyclePolicyV1 {\n\treadonly policyVersion: string;\n\treadonly halfLifeMs: number;\n\t/** Confidence at or below which the preference becomes `decayed` (0..1). */\n\treadonly decayFloor: number;\n\t/** Confidence assigned on reactivation from `decayed`. */\n\treadonly reactivationConfidence: number;\n}\n\nexport type PreferenceLifecycleEventV1 =\n\t| { readonly kind: \"observed\"; readonly at: number; readonly evidenceClass: PreferenceEvidenceClassV1 }\n\t| { readonly kind: \"promoted\"; readonly at: number; readonly toConfidence: number; readonly policyVersion: string }\n\t| { readonly kind: \"used\"; readonly at: number }\n\t| { readonly kind: \"decay_tick\"; readonly at: number }\n\t| { readonly kind: \"archive\"; readonly at: number; readonly reason: string };\n\nexport type PreferenceLifecycleStateV1 = \"active\" | \"decayed\" | \"archived\";\n\nexport interface PreferenceLifecycleTransitionV1 {\n\treadonly kind: \"observed\" | \"promoted\" | \"used\" | \"decay_tick\" | \"decayed\" | \"reactivated\" | \"archived\" | \"ignored\";\n\treadonly at: number;\n\treadonly confidence: number;\n\treadonly state: PreferenceLifecycleStateV1;\n\treadonly policyVersion: string;\n\treadonly detail?: string;\n}\n\nexport interface PreferenceLifecycleProjectionV1 {\n\treadonly state: PreferenceLifecycleStateV1;\n\treadonly confidence: number;\n\treadonly transitions: readonly PreferenceLifecycleTransitionV1[];\n}\n\nexport interface PreferenceLifecycleProjectorV1 {\n\tproject(events: readonly PreferenceLifecycleEventV1[], initialConfidence?: number): PreferenceLifecycleProjectionV1;\n\treadonly policyVersion: string;\n}\n\nexport function createPreferenceLifecycleProjector(options: {\n\treadonly policy: PreferenceLifecyclePolicyV1;\n}): PreferenceLifecycleProjectorV1 {\n\tconst policy = options.policy;\n\tif (policy.halfLifeMs <= 0) throw new Error(\"Lifecycle halfLifeMs must be positive\");\n\tif (policy.decayFloor < 0 || policy.decayFloor >= 1) throw new Error(\"Lifecycle decayFloor must be within [0..1)\");\n\tif (policy.reactivationConfidence <= policy.decayFloor) {\n\t\tthrow new Error(\"Lifecycle reactivationConfidence must exceed decayFloor\");\n\t}\n\n\treturn {\n\t\tpolicyVersion: policy.policyVersion,\n\t\tproject(events, initialConfidence = 0.5) {\n\t\t\tlet state: PreferenceLifecycleStateV1 = \"active\";\n\t\t\tlet confidence = initialConfidence;\n\t\t\tlet anchor = events[0]?.at ?? 0;\n\t\t\tconst transitions: PreferenceLifecycleTransitionV1[] = [];\n\t\t\tconst record = (transition: PreferenceLifecycleTransitionV1): void => {\n\t\t\t\ttransitions.push(transition);\n\t\t\t};\n\n\t\t\tfor (const event of events) {\n\t\t\t\tif (state === \"archived\") {\n\t\t\t\t\trecord({\n\t\t\t\t\t\tkind: \"ignored\",\n\t\t\t\t\t\tat: event.at,\n\t\t\t\t\t\tconfidence,\n\t\t\t\t\t\tstate,\n\t\t\t\t\t\tpolicyVersion: policy.policyVersion,\n\t\t\t\t\t\tdetail: \"Terminal archived state ignores later events\",\n\t\t\t\t\t});\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tswitch (event.kind) {\n\t\t\t\t\tcase \"observed\": {\n\t\t\t\t\t\tif (state === \"decayed\") {\n\t\t\t\t\t\t\tstate = \"active\";\n\t\t\t\t\t\t\tconfidence = policy.reactivationConfidence;\n\t\t\t\t\t\t\trecord({\n\t\t\t\t\t\t\t\tkind: \"reactivated\",\n\t\t\t\t\t\t\t\tat: event.at,\n\t\t\t\t\t\t\t\tconfidence,\n\t\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\t\tpolicyVersion: policy.policyVersion,\n\t\t\t\t\t\t\t\tdetail: `Reactivated by ${event.evidenceClass} evidence`,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\trecord({\n\t\t\t\t\t\t\t\tkind: \"observed\",\n\t\t\t\t\t\t\t\tat: event.at,\n\t\t\t\t\t\t\t\tconfidence,\n\t\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\t\tpolicyVersion: policy.policyVersion,\n\t\t\t\t\t\t\t\tdetail: event.evidenceClass,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t}\n\t\t\t\t\t\tanchor = event.at;\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tcase \"promoted\": {\n\t\t\t\t\t\tconfidence = Math.max(event.toConfidence, confidence);\n\t\t\t\t\t\tanchor = event.at;\n\t\t\t\t\t\trecord({\n\t\t\t\t\t\t\tkind: \"promoted\",\n\t\t\t\t\t\t\tat: event.at,\n\t\t\t\t\t\t\tconfidence,\n\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\tpolicyVersion: event.policyVersion,\n\t\t\t\t\t\t\tdetail: \"Confidence raised by promotion policy\",\n\t\t\t\t\t\t});\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tcase \"used\": {\n\t\t\t\t\t\tanchor = event.at;\n\t\t\t\t\t\trecord({\n\t\t\t\t\t\t\tkind: \"used\",\n\t\t\t\t\t\t\tat: event.at,\n\t\t\t\t\t\t\tconfidence,\n\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\tpolicyVersion: policy.policyVersion,\n\t\t\t\t\t\t\tdetail: \"Decay anchor refreshed\",\n\t\t\t\t\t\t});\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tcase \"decay_tick\": {\n\t\t\t\t\t\tconst elapsed = event.at - anchor;\n\t\t\t\t\t\tconfidence = elapsed > 0 ? confidence * 2 ** (-elapsed / policy.halfLifeMs) : confidence;\n\t\t\t\t\t\tanchor = event.at;\n\t\t\t\t\t\tif (confidence <= policy.decayFloor) {\n\t\t\t\t\t\t\tstate = \"decayed\";\n\t\t\t\t\t\t\trecord({\n\t\t\t\t\t\t\t\tkind: \"decayed\",\n\t\t\t\t\t\t\t\tat: event.at,\n\t\t\t\t\t\t\t\tconfidence,\n\t\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\t\tpolicyVersion: policy.policyVersion,\n\t\t\t\t\t\t\t\tdetail: `Confidence fell to the decay floor ${policy.decayFloor}`,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\trecord({\n\t\t\t\t\t\t\t\tkind: \"decay_tick\",\n\t\t\t\t\t\t\t\tat: event.at,\n\t\t\t\t\t\t\t\tconfidence,\n\t\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\t\tpolicyVersion: policy.policyVersion,\n\t\t\t\t\t\t\t\tdetail: `Decayed to ${confidence}`,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t}\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tcase \"archive\": {\n\t\t\t\t\t\tstate = \"archived\";\n\t\t\t\t\t\trecord({\n\t\t\t\t\t\t\tkind: \"archived\",\n\t\t\t\t\t\t\tat: event.at,\n\t\t\t\t\t\t\tconfidence,\n\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\tpolicyVersion: policy.policyVersion,\n\t\t\t\t\t\t\tdetail: event.reason,\n\t\t\t\t\t\t});\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn { state, confidence, transitions: Object.freeze(transitions) };\n\t\t},\n\t};\n}\n"]}

package/dist/memory/preference-lifecycle.js

@@ -0,0 +1,129 @@
+export function createPreferenceLifecycleProjector(options) {
+    const policy = options.policy;
+    if (policy.halfLifeMs <= 0)
+        throw new Error("Lifecycle halfLifeMs must be positive");
+    if (policy.decayFloor < 0 || policy.decayFloor >= 1)
+        throw new Error("Lifecycle decayFloor must be within [0..1)");
+    if (policy.reactivationConfidence <= policy.decayFloor) {
+        throw new Error("Lifecycle reactivationConfidence must exceed decayFloor");
+    }
+    return {
+        policyVersion: policy.policyVersion,
+        project(events, initialConfidence = 0.5) {
+            let state = "active";
+            let confidence = initialConfidence;
+            let anchor = events[0]?.at ?? 0;
+            const transitions = [];
+            const record = (transition) => {
+                transitions.push(transition);
+            };
+            for (const event of events) {
+                if (state === "archived") {
+                    record({
+                        kind: "ignored",
+                        at: event.at,
+                        confidence,
+                        state,
+                        policyVersion: policy.policyVersion,
+                        detail: "Terminal archived state ignores later events",
+                    });
+                    continue;
+                }
+                switch (event.kind) {
+                    case "observed": {
+                        if (state === "decayed") {
+                            state = "active";
+                            confidence = policy.reactivationConfidence;
+                            record({
+                                kind: "reactivated",
+                                at: event.at,
+                                confidence,
+                                state,
+                                policyVersion: policy.policyVersion,
+                                detail: `Reactivated by ${event.evidenceClass} evidence`,
+                            });
+                        }
+                        else {
+                            record({
+                                kind: "observed",
+                                at: event.at,
+                                confidence,
+                                state,
+                                policyVersion: policy.policyVersion,
+                                detail: event.evidenceClass,
+                            });
+                        }
+                        anchor = event.at;
+                        break;
+                    }
+                    case "promoted": {
+                        confidence = Math.max(event.toConfidence, confidence);
+                        anchor = event.at;
+                        record({
+                            kind: "promoted",
+                            at: event.at,
+                            confidence,
+                            state,
+                            policyVersion: event.policyVersion,
+                            detail: "Confidence raised by promotion policy",
+                        });
+                        break;
+                    }
+                    case "used": {
+                        anchor = event.at;
+                        record({
+                            kind: "used",
+                            at: event.at,
+                            confidence,
+                            state,
+                            policyVersion: policy.policyVersion,
+                            detail: "Decay anchor refreshed",
+                        });
+                        break;
+                    }
+                    case "decay_tick": {
+                        const elapsed = event.at - anchor;
+                        confidence = elapsed > 0 ? confidence * 2 ** (-elapsed / policy.halfLifeMs) : confidence;
+                        anchor = event.at;
+                        if (confidence <= policy.decayFloor) {
+                            state = "decayed";
+                            record({
+                                kind: "decayed",
+                                at: event.at,
+                                confidence,
+                                state,
+                                policyVersion: policy.policyVersion,
+                                detail: `Confidence fell to the decay floor ${policy.decayFloor}`,
+                            });
+                        }
+                        else {
+                            record({
+                                kind: "decay_tick",
+                                at: event.at,
+                                confidence,
+                                state,
+                                policyVersion: policy.policyVersion,
+                                detail: `Decayed to ${confidence}`,
+                            });
+                        }
+                        break;
+                    }
+                    case "archive": {
+                        state = "archived";
+                        record({
+                            kind: "archived",
+                            at: event.at,
+                            confidence,
+                            state,
+                            policyVersion: policy.policyVersion,
+                            detail: event.reason,
+                        });
+                        break;
+                    }
+                }
+            }
+            return { state, confidence, transitions: Object.freeze(transitions) };
+        },
+    };
+}
+//# sourceMappingURL=preference-lifecycle.js.map

package/dist/memory/preference-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preference-lifecycle.js","sourceRoot":"","sources":["../../src/memory/preference-lifecycle.ts"],"names":[],"mappings":"AAuDA,MAAM,UAAU,kCAAkC,CAAC,OAElD,EAAkC;IAClC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9B,IAAI,MAAM,CAAC,UAAU,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IACrF,IAAI,MAAM,CAAC,UAAU,GAAG,CAAC,IAAI,MAAM,CAAC,UAAU,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IACnH,IAAI,MAAM,CAAC,sBAAsB,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO;QACN,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,GAAG,EAAE;YACxC,IAAI,KAAK,GAA+B,QAAQ,CAAC;YACjD,IAAI,UAAU,GAAG,iBAAiB,CAAC;YACnC,IAAI,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YAChC,MAAM,WAAW,GAAsC,EAAE,CAAC;YAC1D,MAAM,MAAM,GAAG,CAAC,UAA2C,EAAQ,EAAE,CAAC;gBACrE,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAAA,CAC7B,CAAC;YAEF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC5B,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;oBAC1B,MAAM,CAAC;wBACN,IAAI,EAAE,SAAS;wBACf,EAAE,EAAE,KAAK,CAAC,EAAE;wBACZ,UAAU;wBACV,KAAK;wBACL,aAAa,EAAE,MAAM,CAAC,aAAa;wBACnC,MAAM,EAAE,8CAA8C;qBACtD,CAAC,CAAC;oBACH,SAAS;gBACV,CAAC;gBACD,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;oBACpB,KAAK,UAAU,EAAE,CAAC;wBACjB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;4BACzB,KAAK,GAAG,QAAQ,CAAC;4BACjB,UAAU,GAAG,MAAM,CAAC,sBAAsB,CAAC;4BAC3C,MAAM,CAAC;gCACN,IAAI,EAAE,aAAa;gCACnB,EAAE,EAAE,KAAK,CAAC,EAAE;gCACZ,UAAU;gCACV,KAAK;gCACL,aAAa,EAAE,MAAM,CAAC,aAAa;gCACnC,MAAM,EAAE,kBAAkB,KAAK,CAAC,aAAa,WAAW;6BACxD,CAAC,CAAC;wBACJ,CAAC;6BAAM,CAAC;4BACP,MAAM,CAAC;gCACN,IAAI,EAAE,UAAU;gCAChB,EAAE,EAAE,KAAK,CAAC,EAAE;gCACZ,UAAU;gCACV,KAAK;gCACL,aAAa,EAAE,MAAM,CAAC,aAAa;gCACnC,MAAM,EAAE,KAAK,CAAC,aAAa;6BAC3B,CAAC,CAAC;wBACJ,CAAC;wBACD,MAAM,GAAG,KAAK,CAAC,EAAE,CAAC;wBAClB,MAAM;oBACP,CAAC;oBACD,KAAK,UAAU,EAAE,CAAC;wBACjB,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;wBACtD,MAAM,GAAG,KAAK,CAAC,EAAE,CAAC;wBAClB,MAAM,CAAC;4BACN,IAAI,EAAE,UAAU;4BAChB,EAAE,EAAE,KAAK,CAAC,EAAE;4BACZ,UAAU;4BACV,KAAK;4BACL,aAAa,EAAE,KAAK,CAAC,aAAa;4BAClC,MAAM,EAAE,uCAAuC;yBAC/C,CAAC,CAAC;wBACH,MAAM;oBACP,CAAC;oBACD,KAAK,MAAM,EAAE,CAAC;wBACb,MAAM,GAAG,KAAK,CAAC,EAAE,CAAC;wBAClB,MAAM,CAAC;4BACN,IAAI,EAAE,MAAM;4BACZ,EAAE,EAAE,KAAK,CAAC,EAAE;4BACZ,UAAU;4BACV,KAAK;4BACL,aAAa,EAAE,MAAM,CAAC,aAAa;4BACnC,MAAM,EAAE,wBAAwB;yBAChC,CAAC,CAAC;wBACH,MAAM;oBACP,CAAC;oBACD,KAAK,YAAY,EAAE,CAAC;wBACnB,MAAM,OAAO,GAAG,KAAK,CAAC,EAAE,GAAG,MAAM,CAAC;wBAClC,UAAU,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,IAAI,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;wBACzF,MAAM,GAAG,KAAK,CAAC,EAAE,CAAC;wBAClB,IAAI,UAAU,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;4BACrC,KAAK,GAAG,SAAS,CAAC;4BAClB,MAAM,CAAC;gCACN,IAAI,EAAE,SAAS;gCACf,EAAE,EAAE,KAAK,CAAC,EAAE;gCACZ,UAAU;gCACV,KAAK;gCACL,aAAa,EAAE,MAAM,CAAC,aAAa;gCACnC,MAAM,EAAE,sCAAsC,MAAM,CAAC,UAAU,EAAE;6BACjE,CAAC,CAAC;wBACJ,CAAC;6BAAM,CAAC;4BACP,MAAM,CAAC;gCACN,IAAI,EAAE,YAAY;gCAClB,EAAE,EAAE,KAAK,CAAC,EAAE;gCACZ,UAAU;gCACV,KAAK;gCACL,aAAa,EAAE,MAAM,CAAC,aAAa;gCACnC,MAAM,EAAE,cAAc,UAAU,EAAE;6BAClC,CAAC,CAAC;wBACJ,CAAC;wBACD,MAAM;oBACP,CAAC;oBACD,KAAK,SAAS,EAAE,CAAC;wBAChB,KAAK,GAAG,UAAU,CAAC;wBACnB,MAAM,CAAC;4BACN,IAAI,EAAE,UAAU;4BAChB,EAAE,EAAE,KAAK,CAAC,EAAE;4BACZ,UAAU;4BACV,KAAK;4BACL,aAAa,EAAE,MAAM,CAAC,aAAa;4BACnC,MAAM,EAAE,KAAK,CAAC,MAAM;yBACpB,CAAC,CAAC;wBACH,MAAM;oBACP,CAAC;gBACF,CAAC;YACF,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QAAA,CACtE;KACD,CAAC;AAAA,CACF","sourcesContent":["/**\n * Complete preference lifecycle projection (2.4d3) — promotion (2.4d1),\n * deterministic decay, reactivation, and archiving over an event sequence.\n *\n * The projection is a pure fold over a replayable event log: the same event\n * sequence always yields the same state and transition audit, on any\n * projection instance. Decay uses the 1C.6b half-life formula\n * w × 2^(-elapsed/halfLife) anchored at the last usage/promotion; falling\n * below the floor marks the preference `decayed` (kept in the ledger, hidden\n * from recall per 1C store semantics). New evidence reactivates a decayed\n * preference; archiving is terminal and ignores later events. Every\n * transition records the policy version that governed it, so policy\n * migrations are auditable across replays. Relation networks and advanced\n * indexing remain out of scope (2.4d4).\n */\nimport type { PreferenceEvidenceClassV1 } from \"./preference-promotion.ts\";\n\nexport interface PreferenceLifecyclePolicyV1 {\n\treadonly policyVersion: string;\n\treadonly halfLifeMs: number;\n\t/** Confidence at or below which the preference becomes `decayed` (0..1). */\n\treadonly decayFloor: number;\n\t/** Confidence assigned on reactivation from `decayed`. */\n\treadonly reactivationConfidence: number;\n}\n\nexport type PreferenceLifecycleEventV1 =\n\t| { readonly kind: \"observed\"; readonly at: number; readonly evidenceClass: PreferenceEvidenceClassV1 }\n\t| { readonly kind: \"promoted\"; readonly at: number; readonly toConfidence: number; readonly policyVersion: string }\n\t| { readonly kind: \"used\"; readonly at: number }\n\t| { readonly kind: \"decay_tick\"; readonly at: number }\n\t| { readonly kind: \"archive\"; readonly at: number; readonly reason: string };\n\nexport type PreferenceLifecycleStateV1 = \"active\" | \"decayed\" | \"archived\";\n\nexport interface PreferenceLifecycleTransitionV1 {\n\treadonly kind: \"observed\" | \"promoted\" | \"used\" | \"decay_tick\" | \"decayed\" | \"reactivated\" | \"archived\" | \"ignored\";\n\treadonly at: number;\n\treadonly confidence: number;\n\treadonly state: PreferenceLifecycleStateV1;\n\treadonly policyVersion: string;\n\treadonly detail?: string;\n}\n\nexport interface PreferenceLifecycleProjectionV1 {\n\treadonly state: PreferenceLifecycleStateV1;\n\treadonly confidence: number;\n\treadonly transitions: readonly PreferenceLifecycleTransitionV1[];\n}\n\nexport interface PreferenceLifecycleProjectorV1 {\n\tproject(events: readonly PreferenceLifecycleEventV1[], initialConfidence?: number): PreferenceLifecycleProjectionV1;\n\treadonly policyVersion: string;\n}\n\nexport function createPreferenceLifecycleProjector(options: {\n\treadonly policy: PreferenceLifecyclePolicyV1;\n}): PreferenceLifecycleProjectorV1 {\n\tconst policy = options.policy;\n\tif (policy.halfLifeMs <= 0) throw new Error(\"Lifecycle halfLifeMs must be positive\");\n\tif (policy.decayFloor < 0 || policy.decayFloor >= 1) throw new Error(\"Lifecycle decayFloor must be within [0..1)\");\n\tif (policy.reactivationConfidence <= policy.decayFloor) {\n\t\tthrow new Error(\"Lifecycle reactivationConfidence must exceed decayFloor\");\n\t}\n\n\treturn {\n\t\tpolicyVersion: policy.policyVersion,\n\t\tproject(events, initialConfidence = 0.5) {\n\t\t\tlet state: PreferenceLifecycleStateV1 = \"active\";\n\t\t\tlet confidence = initialConfidence;\n\t\t\tlet anchor = events[0]?.at ?? 0;\n\t\t\tconst transitions: PreferenceLifecycleTransitionV1[] = [];\n\t\t\tconst record = (transition: PreferenceLifecycleTransitionV1): void => {\n\t\t\t\ttransitions.push(transition);\n\t\t\t};\n\n\t\t\tfor (const event of events) {\n\t\t\t\tif (state === \"archived\") {\n\t\t\t\t\trecord({\n\t\t\t\t\t\tkind: \"ignored\",\n\t\t\t\t\t\tat: event.at,\n\t\t\t\t\t\tconfidence,\n\t\t\t\t\t\tstate,\n\t\t\t\t\t\tpolicyVersion: policy.policyVersion,\n\t\t\t\t\t\tdetail: \"Terminal archived state ignores later events\",\n\t\t\t\t\t});\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tswitch (event.kind) {\n\t\t\t\t\tcase \"observed\": {\n\t\t\t\t\t\tif (state === \"decayed\") {\n\t\t\t\t\t\t\tstate = \"active\";\n\t\t\t\t\t\t\tconfidence = policy.reactivationConfidence;\n\t\t\t\t\t\t\trecord({\n\t\t\t\t\t\t\t\tkind: \"reactivated\",\n\t\t\t\t\t\t\t\tat: event.at,\n\t\t\t\t\t\t\t\tconfidence,\n\t\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\t\tpolicyVersion: policy.policyVersion,\n\t\t\t\t\t\t\t\tdetail: `Reactivated by ${event.evidenceClass} evidence`,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\trecord({\n\t\t\t\t\t\t\t\tkind: \"observed\",\n\t\t\t\t\t\t\t\tat: event.at,\n\t\t\t\t\t\t\t\tconfidence,\n\t\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\t\tpolicyVersion: policy.policyVersion,\n\t\t\t\t\t\t\t\tdetail: event.evidenceClass,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t}\n\t\t\t\t\t\tanchor = event.at;\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tcase \"promoted\": {\n\t\t\t\t\t\tconfidence = Math.max(event.toConfidence, confidence);\n\t\t\t\t\t\tanchor = event.at;\n\t\t\t\t\t\trecord({\n\t\t\t\t\t\t\tkind: \"promoted\",\n\t\t\t\t\t\t\tat: event.at,\n\t\t\t\t\t\t\tconfidence,\n\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\tpolicyVersion: event.policyVersion,\n\t\t\t\t\t\t\tdetail: \"Confidence raised by promotion policy\",\n\t\t\t\t\t\t});\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tcase \"used\": {\n\t\t\t\t\t\tanchor = event.at;\n\t\t\t\t\t\trecord({\n\t\t\t\t\t\t\tkind: \"used\",\n\t\t\t\t\t\t\tat: event.at,\n\t\t\t\t\t\t\tconfidence,\n\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\tpolicyVersion: policy.policyVersion,\n\t\t\t\t\t\t\tdetail: \"Decay anchor refreshed\",\n\t\t\t\t\t\t});\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tcase \"decay_tick\": {\n\t\t\t\t\t\tconst elapsed = event.at - anchor;\n\t\t\t\t\t\tconfidence = elapsed > 0 ? confidence * 2 ** (-elapsed / policy.halfLifeMs) : confidence;\n\t\t\t\t\t\tanchor = event.at;\n\t\t\t\t\t\tif (confidence <= policy.decayFloor) {\n\t\t\t\t\t\t\tstate = \"decayed\";\n\t\t\t\t\t\t\trecord({\n\t\t\t\t\t\t\t\tkind: \"decayed\",\n\t\t\t\t\t\t\t\tat: event.at,\n\t\t\t\t\t\t\t\tconfidence,\n\t\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\t\tpolicyVersion: policy.policyVersion,\n\t\t\t\t\t\t\t\tdetail: `Confidence fell to the decay floor ${policy.decayFloor}`,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\trecord({\n\t\t\t\t\t\t\t\tkind: \"decay_tick\",\n\t\t\t\t\t\t\t\tat: event.at,\n\t\t\t\t\t\t\t\tconfidence,\n\t\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\t\tpolicyVersion: policy.policyVersion,\n\t\t\t\t\t\t\t\tdetail: `Decayed to ${confidence}`,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t}\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t\tcase \"archive\": {\n\t\t\t\t\t\tstate = \"archived\";\n\t\t\t\t\t\trecord({\n\t\t\t\t\t\t\tkind: \"archived\",\n\t\t\t\t\t\t\tat: event.at,\n\t\t\t\t\t\t\tconfidence,\n\t\t\t\t\t\t\tstate,\n\t\t\t\t\t\t\tpolicyVersion: policy.policyVersion,\n\t\t\t\t\t\t\tdetail: event.reason,\n\t\t\t\t\t\t});\n\t\t\t\t\t\tbreak;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn { state, confidence, transitions: Object.freeze(transitions) };\n\t\t},\n\t};\n}\n"]}

package/dist/memory/preference-promotion.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Automatic preference promotion (2.4d1) — the explicit-confirmation-free
+ * promotion policy over preference observations.
+ *
+ * Promotion NEVER fakes a user confirmation (no `confirmedAt`, no
+ * `explicit` evidence class): it deterministically raises the winning
+ * preference's `applicabilityConfidence` once independent repeated-behavior
+ * or inferred observations reach the policy thresholds. Policies carry a
+ * version and an explicit `enabled` switch — a disabled policy returns
+ * `disabled` for every input and never promotes silently. The same
+ * observation sequence under the same policy version resolves identically
+ * on any engine instance, so decisions are migratable/replayable.
+ * Complex disambiguation (2.4d2), full lifecycle promotion/decay (2.4d3),
+ * and networks (2.4d4) are out of scope.
+ */
+import type { JsonValue } from "@agent-forge/plugin-sdk";
+import type { MemoryAtomV1, MemoryPreferenceEnvelopeV1 } from "./foundation.ts";
+export interface PreferencePromotionPolicyV1 {
+    /** Master switch; disabled engines never promote. */
+    readonly enabled: boolean;
+    readonly policyVersion: string;
+    /** Independent repeated-behavior observations required for promotion. */
+    readonly repeatedBehaviorThreshold: number;
+    /** Independent inferred observations required for promotion. */
+    readonly inferredThreshold: number;
+    /** The confidence assigned by a promotion decision (0..1]. */
+    readonly promotedConfidence: number;
+}
+export type PreferenceEvidenceClassV1 = MemoryPreferenceEnvelopeV1["evidence"]["class"];
+export interface PreferenceObservationV1 {
+    readonly evidenceClass: PreferenceEvidenceClassV1;
+    /** Distinct observation identity; duplicates within a sequence are ignored. */
+    readonly observationId: string;
+    readonly confidence?: number;
+}
+export type PreferencePromotionDecisionV1 = {
+    readonly decision: "promoted";
+    readonly policyVersion: string;
+    readonly fromConfidence: number;
+    readonly toConfidence: number;
+    readonly supportingObservations: number;
+} | {
+    readonly decision: "not_promoted";
+    readonly policyVersion: string;
+    readonly supportingObservations: number;
+    readonly requiredObservations: number;
+} | {
+    readonly decision: "disabled";
+    readonly policyVersion: string;
+};
+export interface PreferencePromotionEngineV1 {
+    /** Evaluates one preference candidate (same subject+key+value) deterministically. */
+    evaluate(input: {
+        readonly currentConfidence: number;
+        readonly observations: readonly PreferenceObservationV1[];
+    }): PreferencePromotionDecisionV1;
+    readonly policyVersion: string;
+}
+export declare function createPreferencePromotionEngine(options: {
+    readonly policy: PreferencePromotionPolicyV1;
+}): PreferencePromotionEngineV1;
+/** Serializes a policy for migration/replay ledgers. */
+export declare function serializePromotionPolicy(policy: PreferencePromotionPolicyV1): JsonValue;
+export interface PromotePreferenceToUserDefaultInputV1 {
+    /** The source preference atom; it is preserved untouched. */
+    readonly atom: MemoryAtomV1;
+    /** Who authorized the promotion (explicit confirmation provenance); required. */
+    readonly authorizedBy: string;
+    /** ISO-8601 confirmation timestamp stamped into the promoted envelope's `confirmedAt`. */
+    readonly confirmedAt: string;
+}
+/**
+ * Explicitly promotes a preference atom to the user-default scope (方案系统
+ * 设计 §6.1 跨方案规则). Produces a NEW canonical atom — the original is never
+ * rewritten — whose envelope carries `scope.level "user-default"` and
+ * `confirmedAt`, the canonical explicit-confirmation marker the suite read
+ * boundary ({@link memorySuiteVisibility} in foundation.ts) requires for
+ * cross-suite visibility. Scope anchors are intentionally dropped: a
+ * user-default preference applies without narrowing. The automatic
+ * applicabilityConfidence policy above stays orthogonal — it never touches
+ * user-default and never sets `confirmedAt`.
+ *
+ * Rejects non-preference atoms, atoms already at user-default, and missing
+ * `authorizedBy`/`confirmedAt`.
+ */
+export declare function promotePreferenceToUserDefault(input: PromotePreferenceToUserDefaultInputV1): MemoryAtomV1;
+//# sourceMappingURL=preference-promotion.d.ts.map

package/dist/memory/preference-promotion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preference-promotion.d.ts","sourceRoot":"","sources":["../../src/memory/preference-promotion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAGhF,MAAM,WAAW,2BAA2B;IAC3C,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;IAC3C,gEAAgE;IAChE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,8DAA8D;IAC9D,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,MAAM,yBAAyB,GAAG,0BAA0B,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,CAAC;AAExF,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,aAAa,EAAE,yBAAyB,CAAC;IAClD,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,6BAA6B,GACtC;IACA,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;CACvC,GACD;IACA,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACrC,GACD;IAAE,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE,MAAM,WAAW,2BAA2B;IAC3C,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE;QACf,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;QACnC,QAAQ,CAAC,YAAY,EAAE,SAAS,uBAAuB,EAAE,CAAC;KAC1D,GAAG,6BAA6B,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,+BAA+B,CAAC,OAAO,EAAE;IACxD,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;CAC7C,GAAG,2BAA2B,CAiD9B;AAED,wDAAwD;AACxD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,2BAA2B,GAAG,SAAS,CAQvF;AAMD,MAAM,WAAW,qCAAqC;IACrD,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,0FAA0F;IAC1F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,qCAAqC,GAAG,YAAY,CA6BzG","sourcesContent":["/**\n * Automatic preference promotion (2.4d1) — the explicit-confirmation-free\n * promotion policy over preference observations.\n *\n * Promotion NEVER fakes a user confirmation (no `confirmedAt`, no\n * `explicit` evidence class): it deterministically raises the winning\n * preference's `applicabilityConfidence` once independent repeated-behavior\n * or inferred observations reach the policy thresholds. Policies carry a\n * version and an explicit `enabled` switch — a disabled policy returns\n * `disabled` for every input and never promotes silently. The same\n * observation sequence under the same policy version resolves identically\n * on any engine instance, so decisions are migratable/replayable.\n * Complex disambiguation (2.4d2), full lifecycle promotion/decay (2.4d3),\n * and networks (2.4d4) are out of scope.\n */\nimport type { JsonValue } from \"@agent-forge/plugin-sdk\";\nimport type { MemoryAtomV1, MemoryPreferenceEnvelopeV1 } from \"./foundation.ts\";\nimport { validateMemoryAtomV1 } from \"./foundation.ts\";\n\nexport interface PreferencePromotionPolicyV1 {\n\t/** Master switch; disabled engines never promote. */\n\treadonly enabled: boolean;\n\treadonly policyVersion: string;\n\t/** Independent repeated-behavior observations required for promotion. */\n\treadonly repeatedBehaviorThreshold: number;\n\t/** Independent inferred observations required for promotion. */\n\treadonly inferredThreshold: number;\n\t/** The confidence assigned by a promotion decision (0..1]. */\n\treadonly promotedConfidence: number;\n}\n\nexport type PreferenceEvidenceClassV1 = MemoryPreferenceEnvelopeV1[\"evidence\"][\"class\"];\n\nexport interface PreferenceObservationV1 {\n\treadonly evidenceClass: PreferenceEvidenceClassV1;\n\t/** Distinct observation identity; duplicates within a sequence are ignored. */\n\treadonly observationId: string;\n\treadonly confidence?: number;\n}\n\nexport type PreferencePromotionDecisionV1 =\n\t| {\n\t\t\treadonly decision: \"promoted\";\n\t\t\treadonly policyVersion: string;\n\t\t\treadonly fromConfidence: number;\n\t\t\treadonly toConfidence: number;\n\t\t\treadonly supportingObservations: number;\n\t  }\n\t| {\n\t\t\treadonly decision: \"not_promoted\";\n\t\t\treadonly policyVersion: string;\n\t\t\treadonly supportingObservations: number;\n\t\t\treadonly requiredObservations: number;\n\t  }\n\t| { readonly decision: \"disabled\"; readonly policyVersion: string };\n\nexport interface PreferencePromotionEngineV1 {\n\t/** Evaluates one preference candidate (same subject+key+value) deterministically. */\n\tevaluate(input: {\n\t\treadonly currentConfidence: number;\n\t\treadonly observations: readonly PreferenceObservationV1[];\n\t}): PreferencePromotionDecisionV1;\n\treadonly policyVersion: string;\n}\n\nexport function createPreferencePromotionEngine(options: {\n\treadonly policy: PreferencePromotionPolicyV1;\n}): PreferencePromotionEngineV1 {\n\tconst policy = options.policy;\n\tif (policy.promotedConfidence <= 0 || policy.promotedConfidence > 1) {\n\t\tthrow new Error(\"Promotion promotedConfidence must be within (0..1]\");\n\t}\n\tif (policy.repeatedBehaviorThreshold < 1 || policy.inferredThreshold < 1) {\n\t\tthrow new Error(\"Promotion thresholds must be at least 1 observation\");\n\t}\n\n\treturn {\n\t\tpolicyVersion: policy.policyVersion,\n\t\tevaluate(input) {\n\t\t\tif (!policy.enabled) {\n\t\t\t\treturn { decision: \"disabled\", policyVersion: policy.policyVersion };\n\t\t\t}\n\t\t\t// Independent observations only: dedupe by observationId deterministically.\n\t\t\tconst seen = new Map<string, PreferenceObservationV1>();\n\t\t\tfor (const observation of input.observations) {\n\t\t\t\tif (observation.evidenceClass !== \"repeated_behavior\" && observation.evidenceClass !== \"inferred\") {\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tif (!seen.has(observation.observationId)) seen.set(observation.observationId, observation);\n\t\t\t}\n\t\t\tconst supporting = [...seen.values()].filter((observation) => (observation.confidence ?? 1) >= 0.5);\n\n\t\t\tconst repeatedCount = supporting.filter(\n\t\t\t\t(observation) => observation.evidenceClass === \"repeated_behavior\",\n\t\t\t).length;\n\t\t\tconst inferredCount = supporting.filter((observation) => observation.evidenceClass === \"inferred\").length;\n\t\t\tconst required = repeatedCount >= inferredCount ? policy.repeatedBehaviorThreshold : policy.inferredThreshold;\n\t\t\tconst eligibleCount = Math.max(repeatedCount, inferredCount);\n\n\t\t\tif (repeatedCount >= policy.repeatedBehaviorThreshold || inferredCount >= policy.inferredThreshold) {\n\t\t\t\treturn {\n\t\t\t\t\tdecision: \"promoted\",\n\t\t\t\t\tpolicyVersion: policy.policyVersion,\n\t\t\t\t\tfromConfidence: input.currentConfidence,\n\t\t\t\t\ttoConfidence: Math.max(policy.promotedConfidence, input.currentConfidence),\n\t\t\t\t\tsupportingObservations: eligibleCount,\n\t\t\t\t};\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tdecision: \"not_promoted\",\n\t\t\t\tpolicyVersion: policy.policyVersion,\n\t\t\t\tsupportingObservations: eligibleCount,\n\t\t\t\trequiredObservations: required,\n\t\t\t};\n\t\t},\n\t};\n}\n\n/** Serializes a policy for migration/replay ledgers. */\nexport function serializePromotionPolicy(policy: PreferencePromotionPolicyV1): JsonValue {\n\treturn {\n\t\tenabled: policy.enabled,\n\t\tpolicyVersion: policy.policyVersion,\n\t\trepeatedBehaviorThreshold: policy.repeatedBehaviorThreshold,\n\t\tinferredThreshold: policy.inferredThreshold,\n\t\tpromotedConfidence: policy.promotedConfidence,\n\t};\n}\n\n// ---------------------------------------------------------------------------\n// Explicit user-confirmed promotion to user-default (方案系统设计 §6.1, M5)\n// ---------------------------------------------------------------------------\n\nexport interface PromotePreferenceToUserDefaultInputV1 {\n\t/** The source preference atom; it is preserved untouched. */\n\treadonly atom: MemoryAtomV1;\n\t/** Who authorized the promotion (explicit confirmation provenance); required. */\n\treadonly authorizedBy: string;\n\t/** ISO-8601 confirmation timestamp stamped into the promoted envelope's `confirmedAt`. */\n\treadonly confirmedAt: string;\n}\n\n/**\n * Explicitly promotes a preference atom to the user-default scope (方案系统\n * 设计 §6.1 跨方案规则). Produces a NEW canonical atom — the original is never\n * rewritten — whose envelope carries `scope.level \"user-default\"` and\n * `confirmedAt`, the canonical explicit-confirmation marker the suite read\n * boundary ({@link memorySuiteVisibility} in foundation.ts) requires for\n * cross-suite visibility. Scope anchors are intentionally dropped: a\n * user-default preference applies without narrowing. The automatic\n * applicabilityConfidence policy above stays orthogonal — it never touches\n * user-default and never sets `confirmedAt`.\n *\n * Rejects non-preference atoms, atoms already at user-default, and missing\n * `authorizedBy`/`confirmedAt`.\n */\nexport function promotePreferenceToUserDefault(input: PromotePreferenceToUserDefaultInputV1): MemoryAtomV1 {\n\tif (typeof input.authorizedBy !== \"string\" || input.authorizedBy.trim().length === 0) {\n\t\tthrow new Error(\"User-default preference promotion requires a non-empty authorizedBy\");\n\t}\n\tif (typeof input.confirmedAt !== \"string\" || input.confirmedAt.trim().length === 0) {\n\t\tthrow new Error(\"User-default preference promotion requires a non-empty confirmedAt\");\n\t}\n\tif (Number.isNaN(Date.parse(input.confirmedAt))) {\n\t\tthrow new Error(\"User-default preference promotion confirmedAt must be an ISO-8601 timestamp\");\n\t}\n\tconst atom = input.atom;\n\tif (atom.memoryKind !== \"preference\" || atom.preference === undefined) {\n\t\tthrow new Error(\"User-default preference promotion requires a preference atom with a preference envelope\");\n\t}\n\tif (atom.preference.scope.level === \"user-default\") {\n\t\tthrow new Error(`Preference ${atom.memoryId} is already in the user-default scope`);\n\t}\n\tconst envelope: MemoryPreferenceEnvelopeV1 = {\n\t\t...atom.preference,\n\t\tscope: { level: \"user-default\" },\n\t\tconfirmedAt: input.confirmedAt,\n\t};\n\treturn validateMemoryAtomV1({\n\t\t...atom,\n\t\tmemoryId: `${atom.memoryId}-user-default`,\n\t\tobservationId: `${atom.observationId}-user-default`,\n\t\tpreference: envelope,\n\t\twriteReason: `promote-preference-to-user-default by ${input.authorizedBy}`,\n\t});\n}\n"]}