@ai-agent-forge/plugin-memory 0.85.0

package/dist/memory/recall-index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Memory Foundation — minimal bounded recall index (1C.3).
+ *
+ * Deterministic anchor filtering over the 1C.1b store: time, scenes, projects,
+ * tasks, and facets. Anchors are validated BEFORE querying (锚点校验);
+ * narrowing is a pure query merge; results are sorted deterministically
+ * (recency desc, memoryId asc tie-break) and paginated with limit/offset.
+ * No Memory Network, vector retrieval, or semantic reranking.
+ */
+import type { MemoryScopeV1 } from "./foundation.ts";
+import { type MemorySuiteFilterStatsV1 } from "./foundation.ts";
+import type { CommittedMemoryV1, MemoryStoreV1 } from "./store.ts";
+export type { MemoryScopeV1 };
+export interface MemoryRecallQueryV1 {
+    readonly owner: string;
+    readonly scope?: MemoryScopeV1;
+    /**
+     * Suite-scoped read boundary (方案系统设计 §6.1/§11): only atoms visible in
+     * this suite are recalled; legacy (suiteId-less) atoms are skipped
+     * fail-safe and counted on the page. This is a boundary, not an anchor —
+     * {@link narrowMemoryRecallQuery} never widens or merges it.
+     */
+    readonly suiteId?: string;
+    /** Inclusive ISO-8601 bounds on the atom's `occurredAt`. */
+    readonly timeRange?: {
+        readonly from?: string;
+        readonly to?: string;
+    };
+    readonly scenes?: readonly string[];
+    readonly projects?: readonly string[];
+    readonly tasks?: readonly string[];
+    readonly facets?: readonly {
+        readonly namespace: string;
+        readonly key?: string;
+        readonly value?: string;
+    }[];
+    /** Page size. Default 20, maximum 100. */
+    readonly limit?: number;
+    readonly offset?: number;
+    /**
+     * Exact-lookup fast path (记忆系统设计 §5.2): when set, the index locates
+     * this memoryId directly — attention/state/score filters do not apply.
+     */
+    readonly memoryIdEquals?: string;
+}
+/**
+ * Anchor validation happens before any query runs: malformed time bounds,
+ * empty anchor entries, or out-of-range paging are explicit errors instead of
+ * silently empty results.
+ */
+export declare function validateMemoryRecallQuery(query: MemoryRecallQueryV1): void;
+/** Pure narrowing: merges extra anchors into the query without running it. */
+export declare function narrowMemoryRecallQuery(query: MemoryRecallQueryV1, extra: {
+    readonly scope?: MemoryScopeV1;
+    readonly timeRange?: {
+        readonly from?: string;
+        readonly to?: string;
+    };
+    readonly scenes?: readonly string[];
+    readonly projects?: readonly string[];
+    readonly tasks?: readonly string[];
+    readonly facets?: readonly {
+        readonly namespace: string;
+        readonly key?: string;
+        readonly value?: string;
+    }[];
+}): MemoryRecallQueryV1;
+export interface MemoryRecallPageV1 {
+    readonly items: readonly CommittedMemoryV1[];
+    readonly total: number;
+    readonly offset: number;
+    readonly limit: number;
+    /** True when the page came from the exact-lookup fast path (§5.2). */
+    readonly lookupUsed: boolean;
+    /**
+     * Present only when the query carried a suiteId: how many legacy and
+     * foreign-suite records the suite read boundary excluded (设计 §11).
+     */
+    readonly suiteFilter?: MemorySuiteFilterStatsV1;
+}
+/** Deterministic bounded recall index over a 1C.1b store. */
+export declare function createMemoryRecallIndex(options: {
+    readonly store: MemoryStoreV1;
+}): {
+    query(query: MemoryRecallQueryV1): MemoryRecallPageV1;
+};
+//# sourceMappingURL=recall-index.d.ts.map

package/dist/memory/recall-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-index.d.ts","sourceRoot":"","sources":["../../src/memory/recall-index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Memory Foundation — minimal bounded recall index (1C.3).\n *\n * Deterministic anchor filtering over the 1C.1b store: time, scenes, projects,\n * tasks, and facets. Anchors are validated BEFORE querying (锚点校验);\n * narrowing is a pure query merge; results are sorted deterministically\n * (recency desc, memoryId asc tie-break) and paginated with limit/offset.\n * No Memory Network, vector retrieval, or semantic reranking.\n */\nimport type { MemoryScopeV1 } from \"./foundation.ts\";\nimport { type MemorySuiteFilterStatsV1, memorySuiteVisibility } from \"./foundation.ts\";\nimport type { CommittedMemoryV1, MemoryStoreV1 } from \"./store.ts\";\n\nexport type { MemoryScopeV1 };\n\nexport interface MemoryRecallQueryV1 {\n\treadonly owner: string;\n\treadonly scope?: MemoryScopeV1;\n\t/**\n\t * Suite-scoped read boundary (方案系统设计 §6.1/§11): only atoms visible in\n\t * this suite are recalled; legacy (suiteId-less) atoms are skipped\n\t * fail-safe and counted on the page. This is a boundary, not an anchor —\n\t * {@link narrowMemoryRecallQuery} never widens or merges it.\n\t */\n\treadonly suiteId?: string;\n\t/** Inclusive ISO-8601 bounds on the atom's `occurredAt`. */\n\treadonly timeRange?: { readonly from?: string; readonly to?: string };\n\treadonly scenes?: readonly string[];\n\treadonly projects?: readonly string[];\n\treadonly tasks?: readonly string[];\n\treadonly facets?: readonly { readonly namespace: string; readonly key?: string; readonly value?: string }[];\n\t/** Page size. Default 20, maximum 100. */\n\treadonly limit?: number;\n\treadonly offset?: number;\n\t/**\n\t * Exact-lookup fast path (记忆系统设计 §5.2): when set, the index locates\n\t * this memoryId directly — attention/state/score filters do not apply.\n\t */\n\treadonly memoryIdEquals?: string;\n}\n\nconst DEFAULT_LIMIT = 20;\nconst MAX_LIMIT = 100;\n\nfunction assertNonEmptyString(value: unknown, label: string): asserts value is string {\n\tif (typeof value !== \"string\" || value.trim().length === 0) throw new Error(`${label} must be a non-empty string`);\n}\n\nfunction assertIsoTimestamp(value: unknown, label: string): asserts value is string {\n\tassertNonEmptyString(value, label);\n\tif (Number.isNaN(Date.parse(value))) throw new Error(`${label} must be an ISO-8601 timestamp`);\n}\n\nfunction assertStringArray(value: unknown, label: string): asserts value is readonly string[] {\n\tif (!Array.isArray(value)) throw new Error(`${label} must be an array`);\n\tfor (const [index, item] of value.entries()) {\n\t\tassertNonEmptyString(item, `${label}[${index}]`);\n\t}\n}\n\n/**\n * Anchor validation happens before any query runs: malformed time bounds,\n * empty anchor entries, or out-of-range paging are explicit errors instead of\n * silently empty results.\n */\nexport function validateMemoryRecallQuery(query: MemoryRecallQueryV1): void {\n\tassertNonEmptyString(query.owner, \"Recall query.owner\");\n\tif (query.suiteId !== undefined && (typeof query.suiteId !== \"string\" || query.suiteId.trim() === \"\")) {\n\t\tthrow new Error(\"Recall query.suiteId must be a non-empty string\");\n\t}\n\tif (query.scope !== undefined && ![\"session\", \"cycle\", \"long-term\"].includes(query.scope)) {\n\t\tthrow new Error(`Recall query.scope is invalid: ${String(query.scope)}`);\n\t}\n\tif (query.timeRange !== undefined) {\n\t\tif (query.timeRange.from !== undefined) assertIsoTimestamp(query.timeRange.from, \"Recall query.timeRange.from\");\n\t\tif (query.timeRange.to !== undefined) assertIsoTimestamp(query.timeRange.to, \"Recall query.timeRange.to\");\n\t\tif (\n\t\t\tquery.timeRange.from !== undefined &&\n\t\t\tquery.timeRange.to !== undefined &&\n\t\t\tDate.parse(query.timeRange.from) > Date.parse(query.timeRange.to)\n\t\t) {\n\t\t\tthrow new Error(\"Recall query.timeRange.from must not be after timeRange.to\");\n\t\t}\n\t}\n\tfor (const key of [\"scenes\", \"projects\", \"tasks\"] as const) {\n\t\tconst value = query[key];\n\t\tif (value !== undefined) {\n\t\t\tassertStringArray(value, `Recall query.${key}`);\n\t\t\tif (value.length === 0) throw new Error(`Recall query.${key} must not be an empty array`);\n\t\t}\n\t}\n\tif (query.facets !== undefined) {\n\t\tif (!Array.isArray(query.facets)) throw new Error(\"Recall query.facets must be an array\");\n\t\tfor (const [index, facet] of query.facets.entries()) {\n\t\t\tconst label = `Recall query.facets[${index}]`;\n\t\t\tif (facet === null || typeof facet !== \"object\" || Array.isArray(facet)) {\n\t\t\t\tthrow new Error(`${label} must be a plain object`);\n\t\t\t}\n\t\t\tconst record = facet as Record<string, unknown>;\n\t\t\tassertNonEmptyString(record.namespace, `${label}.namespace`);\n\t\t\tif (record.key !== undefined) assertNonEmptyString(record.key, `${label}.key`);\n\t\t\tif (record.value !== undefined) assertNonEmptyString(record.value, `${label}.value`);\n\t\t}\n\t}\n\tif (\n\t\tquery.limit !== undefined &&\n\t\t(!Number.isSafeInteger(query.limit) || query.limit < 1 || query.limit > MAX_LIMIT)\n\t) {\n\t\tthrow new Error(`Recall query.limit must be a safe integer between 1 and ${MAX_LIMIT}`);\n\t}\n\tif (query.offset !== undefined && (!Number.isSafeInteger(query.offset) || query.offset < 0)) {\n\t\tthrow new Error(\"Recall query.offset must be a non-negative safe integer\");\n\t}\n}\n\n/** Pure narrowing: merges extra anchors into the query without running it. */\nexport function narrowMemoryRecallQuery(\n\tquery: MemoryRecallQueryV1,\n\textra: {\n\t\treadonly scope?: MemoryScopeV1;\n\t\treadonly timeRange?: { readonly from?: string; readonly to?: string };\n\t\treadonly scenes?: readonly string[];\n\t\treadonly projects?: readonly string[];\n\t\treadonly tasks?: readonly string[];\n\t\treadonly facets?: readonly { readonly namespace: string; readonly key?: string; readonly value?: string }[];\n\t},\n): MemoryRecallQueryV1 {\n\tconst nonEmpty = (list: readonly string[] | undefined): readonly string[] | undefined =>\n\t\tlist !== undefined && list.length > 0 ? [...list] : undefined;\n\tconst scenes = nonEmpty([...(query.scenes ?? []), ...(extra.scenes ?? [])]);\n\tconst projects = nonEmpty([...(query.projects ?? []), ...(extra.projects ?? [])]);\n\tconst tasks = nonEmpty([...(query.tasks ?? []), ...(extra.tasks ?? [])]);\n\tconst facets = [...(query.facets ?? []), ...(extra.facets ?? [])];\n\tconst timeRange =\n\t\tquery.timeRange === undefined && extra.timeRange === undefined\n\t\t\t? undefined\n\t\t\t: {\n\t\t\t\t\tfrom: query.timeRange?.from ?? extra.timeRange?.from,\n\t\t\t\t\tto: query.timeRange?.to ?? extra.timeRange?.to,\n\t\t\t\t};\n\treturn {\n\t\t...query,\n\t\t...(extra.scope === undefined ? {} : { scope: extra.scope }),\n\t\t...(timeRange === undefined ? {} : { timeRange }),\n\t\t...(scenes === undefined ? {} : { scenes }),\n\t\t...(projects === undefined ? {} : { projects }),\n\t\t...(tasks === undefined ? {} : { tasks }),\n\t\t...(facets.length === 0 ? {} : { facets }),\n\t};\n}\n\nfunction matchesAny(haystack: readonly string[] | undefined, needles: readonly string[]): boolean {\n\t// v8 ignore next -- 锚点校验先于匹配执行，空数组已被拒绝\n\tif (needles.length === 0) return true;\n\tif (!haystack) return false;\n\treturn needles.some((needle) => haystack.includes(needle));\n}\n\nfunction facetMatches(\n\tfacet: { readonly namespace: string; readonly key?: string; readonly value?: string },\n\tatomFacet: { readonly namespace: string; readonly key: string; readonly value: string },\n): boolean {\n\tif (facet.namespace !== atomFacet.namespace) return false;\n\tif (facet.key !== undefined && facet.key !== atomFacet.key) return false;\n\tif (facet.value !== undefined && facet.value !== atomFacet.value) return false;\n\treturn true;\n}\n\nfunction matchesAnchors(\n\trecord: CommittedMemoryV1,\n\tquery: Pick<MemoryRecallQueryV1, \"timeRange\" | \"scenes\" | \"projects\" | \"tasks\" | \"facets\">,\n): boolean {\n\tconst atom = record.atom;\n\tconst occurred = Date.parse(atom.occurredAt);\n\tif (query.timeRange) {\n\t\tif (query.timeRange.from !== undefined && occurred < Date.parse(query.timeRange.from)) return false;\n\t\tif (query.timeRange.to !== undefined && occurred > Date.parse(query.timeRange.to)) return false;\n\t}\n\tif (query.scenes !== undefined && !matchesAny(atom.applicability?.scenes, query.scenes)) return false;\n\tif (query.projects !== undefined) {\n\t\t// v8 ignore next -- projectRefs 是必填字段\n\t\tconst pool = [...(atom.projectRefs ?? []), ...(atom.applicability?.projects ?? [])];\n\t\tif (!matchesAny(pool, query.projects)) return false;\n\t}\n\tif (query.tasks !== undefined) {\n\t\t// v8 ignore next -- subjectRefs 是必填字段\n\t\tconst pool = [...(atom.subjectRefs ?? []), ...(atom.applicability?.tasks ?? [])];\n\t\tif (!matchesAny(pool, query.tasks)) return false;\n\t}\n\tif (query.facets !== undefined && query.facets.length > 0) {\n\t\tconst atomFacets = atom.facets;\n\t\tconst everyAnchorSatisfied = query.facets.every((anchor) =>\n\t\t\tatomFacets.some((atomFacet) => facetMatches(anchor, atomFacet)),\n\t\t);\n\t\tif (!everyAnchorSatisfied) return false;\n\t}\n\treturn true;\n}\n\nexport interface MemoryRecallPageV1 {\n\treadonly items: readonly CommittedMemoryV1[];\n\treadonly total: number;\n\treadonly offset: number;\n\treadonly limit: number;\n\t/** True when the page came from the exact-lookup fast path (§5.2). */\n\treadonly lookupUsed: boolean;\n\t/**\n\t * Present only when the query carried a suiteId: how many legacy and\n\t * foreign-suite records the suite read boundary excluded (设计 §11).\n\t */\n\treadonly suiteFilter?: MemorySuiteFilterStatsV1;\n}\n\n/** Deterministic bounded recall index over a 1C.1b store. */\nexport function createMemoryRecallIndex(options: { readonly store: MemoryStoreV1 }): {\n\tquery(query: MemoryRecallQueryV1): MemoryRecallPageV1;\n} {\n\tconst store = options.store;\n\treturn {\n\t\tquery(query: MemoryRecallQueryV1): MemoryRecallPageV1 {\n\t\t\t// Exact-lookup fast path: a memoryId hit bypasses anchors, ordering,\n\t\t\t// and scoring entirely (§5.2) but keeps owner scoping AND the suite\n\t\t\t// read boundary — a legacy or foreign-suite atom is never resurrected\n\t\t\t// through exact lookup.\n\t\t\tif (query.memoryIdEquals !== undefined) {\n\t\t\t\tconst found = store.get(query.memoryIdEquals, { owner: query.owner });\n\t\t\t\tif (query.suiteId === undefined) {\n\t\t\t\t\tconst items = found === undefined ? [] : [found];\n\t\t\t\t\treturn Object.freeze({\n\t\t\t\t\t\titems: Object.freeze(items),\n\t\t\t\t\t\ttotal: items.length,\n\t\t\t\t\t\toffset: query.offset ?? 0,\n\t\t\t\t\t\tlimit: query.limit ?? DEFAULT_LIMIT,\n\t\t\t\t\t\tlookupUsed: true,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tlet suiteFilter: MemorySuiteFilterStatsV1 = Object.freeze({ legacySkipped: 0, foreignSuiteSkipped: 0 });\n\t\t\t\tlet items: readonly CommittedMemoryV1[] = [];\n\t\t\t\tif (found !== undefined) {\n\t\t\t\t\tconst visibility = memorySuiteVisibility(found.atom, query.suiteId);\n\t\t\t\t\tif (visibility === \"visible\") {\n\t\t\t\t\t\titems = [found];\n\t\t\t\t\t} else {\n\t\t\t\t\t\tsuiteFilter = Object.freeze({\n\t\t\t\t\t\t\tlegacySkipped: visibility === \"legacy\" ? 1 : 0,\n\t\t\t\t\t\t\tforeignSuiteSkipped: visibility === \"foreign-suite\" ? 1 : 0,\n\t\t\t\t\t\t});\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn Object.freeze({\n\t\t\t\t\titems: Object.freeze(items),\n\t\t\t\t\ttotal: items.length,\n\t\t\t\t\toffset: query.offset ?? 0,\n\t\t\t\t\tlimit: query.limit ?? DEFAULT_LIMIT,\n\t\t\t\t\tlookupUsed: true,\n\t\t\t\t\tsuiteFilter,\n\t\t\t\t});\n\t\t\t}\n\t\t\tvalidateMemoryRecallQuery(query);\n\t\t\tconst limit = query.limit ?? DEFAULT_LIMIT;\n\t\t\tconst offset = query.offset ?? 0;\n\t\t\t// Suite-scoped reads go through listForSuite so excluded-record counts\n\t\t\t// cover the owner's full ledger, not just the anchor-matched slice.\n\t\t\tconst suitePage =\n\t\t\t\tquery.suiteId === undefined\n\t\t\t\t\t? undefined\n\t\t\t\t\t: store.listForSuite({ owner: query.owner, suiteId: query.suiteId }, query.scope);\n\t\t\tconst matches = (suitePage === undefined ? store.list({ owner: query.owner }, query.scope) : suitePage.records)\n\t\t\t\t.filter((record) => matchesAnchors(record, query))\n\t\t\t\t// Deterministic order: most recent first, memoryId as tie-break.\n\t\t\t\t.sort((left, right) => {\n\t\t\t\t\tconst byTime = Date.parse(right.atom.occurredAt) - Date.parse(left.atom.occurredAt);\n\t\t\t\t\tif (byTime !== 0) return byTime;\n\t\t\t\t\t// v8 ignore next -- memoryId 是 store 主键恒唯一，相等路径不可达\n\t\t\t\t\treturn left.atom.memoryId < right.atom.memoryId ? -1 : left.atom.memoryId > right.atom.memoryId ? 1 : 0;\n\t\t\t\t});\n\t\t\tconst total = matches.length;\n\t\t\tconst items = matches.slice(offset, offset + limit);\n\t\t\treturn Object.freeze({\n\t\t\t\titems: Object.freeze(items),\n\t\t\t\ttotal,\n\t\t\t\toffset,\n\t\t\t\tlimit,\n\t\t\t\tlookupUsed: false,\n\t\t\t\t...(suitePage === undefined ? {} : { suiteFilter: suitePage.filter }),\n\t\t\t});\n\t\t},\n\t};\n}\n"]}

package/dist/memory/recall-index.js

@@ -0,0 +1,222 @@
+import { memorySuiteVisibility } from "./foundation.js";
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+function assertNonEmptyString(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        throw new Error(`${label} must be a non-empty string`);
+}
+function assertIsoTimestamp(value, label) {
+    assertNonEmptyString(value, label);
+    if (Number.isNaN(Date.parse(value)))
+        throw new Error(`${label} must be an ISO-8601 timestamp`);
+}
+function assertStringArray(value, label) {
+    if (!Array.isArray(value))
+        throw new Error(`${label} must be an array`);
+    for (const [index, item] of value.entries()) {
+        assertNonEmptyString(item, `${label}[${index}]`);
+    }
+}
+/**
+ * Anchor validation happens before any query runs: malformed time bounds,
+ * empty anchor entries, or out-of-range paging are explicit errors instead of
+ * silently empty results.
+ */
+export function validateMemoryRecallQuery(query) {
+    assertNonEmptyString(query.owner, "Recall query.owner");
+    if (query.suiteId !== undefined && (typeof query.suiteId !== "string" || query.suiteId.trim() === "")) {
+        throw new Error("Recall query.suiteId must be a non-empty string");
+    }
+    if (query.scope !== undefined && !["session", "cycle", "long-term"].includes(query.scope)) {
+        throw new Error(`Recall query.scope is invalid: ${String(query.scope)}`);
+    }
+    if (query.timeRange !== undefined) {
+        if (query.timeRange.from !== undefined)
+            assertIsoTimestamp(query.timeRange.from, "Recall query.timeRange.from");
+        if (query.timeRange.to !== undefined)
+            assertIsoTimestamp(query.timeRange.to, "Recall query.timeRange.to");
+        if (query.timeRange.from !== undefined &&
+            query.timeRange.to !== undefined &&
+            Date.parse(query.timeRange.from) > Date.parse(query.timeRange.to)) {
+            throw new Error("Recall query.timeRange.from must not be after timeRange.to");
+        }
+    }
+    for (const key of ["scenes", "projects", "tasks"]) {
+        const value = query[key];
+        if (value !== undefined) {
+            assertStringArray(value, `Recall query.${key}`);
+            if (value.length === 0)
+                throw new Error(`Recall query.${key} must not be an empty array`);
+        }
+    }
+    if (query.facets !== undefined) {
+        if (!Array.isArray(query.facets))
+            throw new Error("Recall query.facets must be an array");
+        for (const [index, facet] of query.facets.entries()) {
+            const label = `Recall query.facets[${index}]`;
+            if (facet === null || typeof facet !== "object" || Array.isArray(facet)) {
+                throw new Error(`${label} must be a plain object`);
+            }
+            const record = facet;
+            assertNonEmptyString(record.namespace, `${label}.namespace`);
+            if (record.key !== undefined)
+                assertNonEmptyString(record.key, `${label}.key`);
+            if (record.value !== undefined)
+                assertNonEmptyString(record.value, `${label}.value`);
+        }
+    }
+    if (query.limit !== undefined &&
+        (!Number.isSafeInteger(query.limit) || query.limit < 1 || query.limit > MAX_LIMIT)) {
+        throw new Error(`Recall query.limit must be a safe integer between 1 and ${MAX_LIMIT}`);
+    }
+    if (query.offset !== undefined && (!Number.isSafeInteger(query.offset) || query.offset < 0)) {
+        throw new Error("Recall query.offset must be a non-negative safe integer");
+    }
+}
+/** Pure narrowing: merges extra anchors into the query without running it. */
+export function narrowMemoryRecallQuery(query, extra) {
+    const nonEmpty = (list) => list !== undefined && list.length > 0 ? [...list] : undefined;
+    const scenes = nonEmpty([...(query.scenes ?? []), ...(extra.scenes ?? [])]);
+    const projects = nonEmpty([...(query.projects ?? []), ...(extra.projects ?? [])]);
+    const tasks = nonEmpty([...(query.tasks ?? []), ...(extra.tasks ?? [])]);
+    const facets = [...(query.facets ?? []), ...(extra.facets ?? [])];
+    const timeRange = query.timeRange === undefined && extra.timeRange === undefined
+        ? undefined
+        : {
+            from: query.timeRange?.from ?? extra.timeRange?.from,
+            to: query.timeRange?.to ?? extra.timeRange?.to,
+        };
+    return {
+        ...query,
+        ...(extra.scope === undefined ? {} : { scope: extra.scope }),
+        ...(timeRange === undefined ? {} : { timeRange }),
+        ...(scenes === undefined ? {} : { scenes }),
+        ...(projects === undefined ? {} : { projects }),
+        ...(tasks === undefined ? {} : { tasks }),
+        ...(facets.length === 0 ? {} : { facets }),
+    };
+}
+function matchesAny(haystack, needles) {
+    // v8 ignore next -- 锚点校验先于匹配执行，空数组已被拒绝
+    if (needles.length === 0)
+        return true;
+    if (!haystack)
+        return false;
+    return needles.some((needle) => haystack.includes(needle));
+}
+function facetMatches(facet, atomFacet) {
+    if (facet.namespace !== atomFacet.namespace)
+        return false;
+    if (facet.key !== undefined && facet.key !== atomFacet.key)
+        return false;
+    if (facet.value !== undefined && facet.value !== atomFacet.value)
+        return false;
+    return true;
+}
+function matchesAnchors(record, query) {
+    const atom = record.atom;
+    const occurred = Date.parse(atom.occurredAt);
+    if (query.timeRange) {
+        if (query.timeRange.from !== undefined && occurred < Date.parse(query.timeRange.from))
+            return false;
+        if (query.timeRange.to !== undefined && occurred > Date.parse(query.timeRange.to))
+            return false;
+    }
+    if (query.scenes !== undefined && !matchesAny(atom.applicability?.scenes, query.scenes))
+        return false;
+    if (query.projects !== undefined) {
+        // v8 ignore next -- projectRefs 是必填字段
+        const pool = [...(atom.projectRefs ?? []), ...(atom.applicability?.projects ?? [])];
+        if (!matchesAny(pool, query.projects))
+            return false;
+    }
+    if (query.tasks !== undefined) {
+        // v8 ignore next -- subjectRefs 是必填字段
+        const pool = [...(atom.subjectRefs ?? []), ...(atom.applicability?.tasks ?? [])];
+        if (!matchesAny(pool, query.tasks))
+            return false;
+    }
+    if (query.facets !== undefined && query.facets.length > 0) {
+        const atomFacets = atom.facets;
+        const everyAnchorSatisfied = query.facets.every((anchor) => atomFacets.some((atomFacet) => facetMatches(anchor, atomFacet)));
+        if (!everyAnchorSatisfied)
+            return false;
+    }
+    return true;
+}
+/** Deterministic bounded recall index over a 1C.1b store. */
+export function createMemoryRecallIndex(options) {
+    const store = options.store;
+    return {
+        query(query) {
+            // Exact-lookup fast path: a memoryId hit bypasses anchors, ordering,
+            // and scoring entirely (§5.2) but keeps owner scoping AND the suite
+            // read boundary — a legacy or foreign-suite atom is never resurrected
+            // through exact lookup.
+            if (query.memoryIdEquals !== undefined) {
+                const found = store.get(query.memoryIdEquals, { owner: query.owner });
+                if (query.suiteId === undefined) {
+                    const items = found === undefined ? [] : [found];
+                    return Object.freeze({
+                        items: Object.freeze(items),
+                        total: items.length,
+                        offset: query.offset ?? 0,
+                        limit: query.limit ?? DEFAULT_LIMIT,
+                        lookupUsed: true,
+                    });
+                }
+                let suiteFilter = Object.freeze({ legacySkipped: 0, foreignSuiteSkipped: 0 });
+                let items = [];
+                if (found !== undefined) {
+                    const visibility = memorySuiteVisibility(found.atom, query.suiteId);
+                    if (visibility === "visible") {
+                        items = [found];
+                    }
+                    else {
+                        suiteFilter = Object.freeze({
+                            legacySkipped: visibility === "legacy" ? 1 : 0,
+                            foreignSuiteSkipped: visibility === "foreign-suite" ? 1 : 0,
+                        });
+                    }
+                }
+                return Object.freeze({
+                    items: Object.freeze(items),
+                    total: items.length,
+                    offset: query.offset ?? 0,
+                    limit: query.limit ?? DEFAULT_LIMIT,
+                    lookupUsed: true,
+                    suiteFilter,
+                });
+            }
+            validateMemoryRecallQuery(query);
+            const limit = query.limit ?? DEFAULT_LIMIT;
+            const offset = query.offset ?? 0;
+            // Suite-scoped reads go through listForSuite so excluded-record counts
+            // cover the owner's full ledger, not just the anchor-matched slice.
+            const suitePage = query.suiteId === undefined
+                ? undefined
+                : store.listForSuite({ owner: query.owner, suiteId: query.suiteId }, query.scope);
+            const matches = (suitePage === undefined ? store.list({ owner: query.owner }, query.scope) : suitePage.records)
+                .filter((record) => matchesAnchors(record, query))
+                // Deterministic order: most recent first, memoryId as tie-break.
+                .sort((left, right) => {
+                const byTime = Date.parse(right.atom.occurredAt) - Date.parse(left.atom.occurredAt);
+                if (byTime !== 0)
+                    return byTime;
+                // v8 ignore next -- memoryId 是 store 主键恒唯一，相等路径不可达
+                return left.atom.memoryId < right.atom.memoryId ? -1 : left.atom.memoryId > right.atom.memoryId ? 1 : 0;
+            });
+            const total = matches.length;
+            const items = matches.slice(offset, offset + limit);
+            return Object.freeze({
+                items: Object.freeze(items),
+                total,
+                offset,
+                limit,
+                lookupUsed: false,
+                ...(suitePage === undefined ? {} : { suiteFilter: suitePage.filter }),
+            });
+        },
+    };
+}
+//# sourceMappingURL=recall-index.js.map

package/dist/memory/recall-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-index.js","sourceRoot":"","sources":["../../src/memory/recall-index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Memory Foundation — minimal bounded recall index (1C.3).\n *\n * Deterministic anchor filtering over the 1C.1b store: time, scenes, projects,\n * tasks, and facets. Anchors are validated BEFORE querying (锚点校验);\n * narrowing is a pure query merge; results are sorted deterministically\n * (recency desc, memoryId asc tie-break) and paginated with limit/offset.\n * No Memory Network, vector retrieval, or semantic reranking.\n */\nimport type { MemoryScopeV1 } from \"./foundation.ts\";\nimport { type MemorySuiteFilterStatsV1, memorySuiteVisibility } from \"./foundation.ts\";\nimport type { CommittedMemoryV1, MemoryStoreV1 } from \"./store.ts\";\n\nexport type { MemoryScopeV1 };\n\nexport interface MemoryRecallQueryV1 {\n\treadonly owner: string;\n\treadonly scope?: MemoryScopeV1;\n\t/**\n\t * Suite-scoped read boundary (方案系统设计 §6.1/§11): only atoms visible in\n\t * this suite are recalled; legacy (suiteId-less) atoms are skipped\n\t * fail-safe and counted on the page. This is a boundary, not an anchor —\n\t * {@link narrowMemoryRecallQuery} never widens or merges it.\n\t */\n\treadonly suiteId?: string;\n\t/** Inclusive ISO-8601 bounds on the atom's `occurredAt`. */\n\treadonly timeRange?: { readonly from?: string; readonly to?: string };\n\treadonly scenes?: readonly string[];\n\treadonly projects?: readonly string[];\n\treadonly tasks?: readonly string[];\n\treadonly facets?: readonly { readonly namespace: string; readonly key?: string; readonly value?: string }[];\n\t/** Page size. Default 20, maximum 100. */\n\treadonly limit?: number;\n\treadonly offset?: number;\n\t/**\n\t * Exact-lookup fast path (记忆系统设计 §5.2): when set, the index locates\n\t * this memoryId directly — attention/state/score filters do not apply.\n\t */\n\treadonly memoryIdEquals?: string;\n}\n\nconst DEFAULT_LIMIT = 20;\nconst MAX_LIMIT = 100;\n\nfunction assertNonEmptyString(value: unknown, label: string): asserts value is string {\n\tif (typeof value !== \"string\" || value.trim().length === 0) throw new Error(`${label} must be a non-empty string`);\n}\n\nfunction assertIsoTimestamp(value: unknown, label: string): asserts value is string {\n\tassertNonEmptyString(value, label);\n\tif (Number.isNaN(Date.parse(value))) throw new Error(`${label} must be an ISO-8601 timestamp`);\n}\n\nfunction assertStringArray(value: unknown, label: string): asserts value is readonly string[] {\n\tif (!Array.isArray(value)) throw new Error(`${label} must be an array`);\n\tfor (const [index, item] of value.entries()) {\n\t\tassertNonEmptyString(item, `${label}[${index}]`);\n\t}\n}\n\n/**\n * Anchor validation happens before any query runs: malformed time bounds,\n * empty anchor entries, or out-of-range paging are explicit errors instead of\n * silently empty results.\n */\nexport function validateMemoryRecallQuery(query: MemoryRecallQueryV1): void {\n\tassertNonEmptyString(query.owner, \"Recall query.owner\");\n\tif (query.suiteId !== undefined && (typeof query.suiteId !== \"string\" || query.suiteId.trim() === \"\")) {\n\t\tthrow new Error(\"Recall query.suiteId must be a non-empty string\");\n\t}\n\tif (query.scope !== undefined && ![\"session\", \"cycle\", \"long-term\"].includes(query.scope)) {\n\t\tthrow new Error(`Recall query.scope is invalid: ${String(query.scope)}`);\n\t}\n\tif (query.timeRange !== undefined) {\n\t\tif (query.timeRange.from !== undefined) assertIsoTimestamp(query.timeRange.from, \"Recall query.timeRange.from\");\n\t\tif (query.timeRange.to !== undefined) assertIsoTimestamp(query.timeRange.to, \"Recall query.timeRange.to\");\n\t\tif (\n\t\t\tquery.timeRange.from !== undefined &&\n\t\t\tquery.timeRange.to !== undefined &&\n\t\t\tDate.parse(query.timeRange.from) > Date.parse(query.timeRange.to)\n\t\t) {\n\t\t\tthrow new Error(\"Recall query.timeRange.from must not be after timeRange.to\");\n\t\t}\n\t}\n\tfor (const key of [\"scenes\", \"projects\", \"tasks\"] as const) {\n\t\tconst value = query[key];\n\t\tif (value !== undefined) {\n\t\t\tassertStringArray(value, `Recall query.${key}`);\n\t\t\tif (value.length === 0) throw new Error(`Recall query.${key} must not be an empty array`);\n\t\t}\n\t}\n\tif (query.facets !== undefined) {\n\t\tif (!Array.isArray(query.facets)) throw new Error(\"Recall query.facets must be an array\");\n\t\tfor (const [index, facet] of query.facets.entries()) {\n\t\t\tconst label = `Recall query.facets[${index}]`;\n\t\t\tif (facet === null || typeof facet !== \"object\" || Array.isArray(facet)) {\n\t\t\t\tthrow new Error(`${label} must be a plain object`);\n\t\t\t}\n\t\t\tconst record = facet as Record<string, unknown>;\n\t\t\tassertNonEmptyString(record.namespace, `${label}.namespace`);\n\t\t\tif (record.key !== undefined) assertNonEmptyString(record.key, `${label}.key`);\n\t\t\tif (record.value !== undefined) assertNonEmptyString(record.value, `${label}.value`);\n\t\t}\n\t}\n\tif (\n\t\tquery.limit !== undefined &&\n\t\t(!Number.isSafeInteger(query.limit) || query.limit < 1 || query.limit > MAX_LIMIT)\n\t) {\n\t\tthrow new Error(`Recall query.limit must be a safe integer between 1 and ${MAX_LIMIT}`);\n\t}\n\tif (query.offset !== undefined && (!Number.isSafeInteger(query.offset) || query.offset < 0)) {\n\t\tthrow new Error(\"Recall query.offset must be a non-negative safe integer\");\n\t}\n}\n\n/** Pure narrowing: merges extra anchors into the query without running it. */\nexport function narrowMemoryRecallQuery(\n\tquery: MemoryRecallQueryV1,\n\textra: {\n\t\treadonly scope?: MemoryScopeV1;\n\t\treadonly timeRange?: { readonly from?: string; readonly to?: string };\n\t\treadonly scenes?: readonly string[];\n\t\treadonly projects?: readonly string[];\n\t\treadonly tasks?: readonly string[];\n\t\treadonly facets?: readonly { readonly namespace: string; readonly key?: string; readonly value?: string }[];\n\t},\n): MemoryRecallQueryV1 {\n\tconst nonEmpty = (list: readonly string[] | undefined): readonly string[] | undefined =>\n\t\tlist !== undefined && list.length > 0 ? [...list] : undefined;\n\tconst scenes = nonEmpty([...(query.scenes ?? []), ...(extra.scenes ?? [])]);\n\tconst projects = nonEmpty([...(query.projects ?? []), ...(extra.projects ?? [])]);\n\tconst tasks = nonEmpty([...(query.tasks ?? []), ...(extra.tasks ?? [])]);\n\tconst facets = [...(query.facets ?? []), ...(extra.facets ?? [])];\n\tconst timeRange =\n\t\tquery.timeRange === undefined && extra.timeRange === undefined\n\t\t\t? undefined\n\t\t\t: {\n\t\t\t\t\tfrom: query.timeRange?.from ?? extra.timeRange?.from,\n\t\t\t\t\tto: query.timeRange?.to ?? extra.timeRange?.to,\n\t\t\t\t};\n\treturn {\n\t\t...query,\n\t\t...(extra.scope === undefined ? {} : { scope: extra.scope }),\n\t\t...(timeRange === undefined ? {} : { timeRange }),\n\t\t...(scenes === undefined ? {} : { scenes }),\n\t\t...(projects === undefined ? {} : { projects }),\n\t\t...(tasks === undefined ? {} : { tasks }),\n\t\t...(facets.length === 0 ? {} : { facets }),\n\t};\n}\n\nfunction matchesAny(haystack: readonly string[] | undefined, needles: readonly string[]): boolean {\n\t// v8 ignore next -- 锚点校验先于匹配执行，空数组已被拒绝\n\tif (needles.length === 0) return true;\n\tif (!haystack) return false;\n\treturn needles.some((needle) => haystack.includes(needle));\n}\n\nfunction facetMatches(\n\tfacet: { readonly namespace: string; readonly key?: string; readonly value?: string },\n\tatomFacet: { readonly namespace: string; readonly key: string; readonly value: string },\n): boolean {\n\tif (facet.namespace !== atomFacet.namespace) return false;\n\tif (facet.key !== undefined && facet.key !== atomFacet.key) return false;\n\tif (facet.value !== undefined && facet.value !== atomFacet.value) return false;\n\treturn true;\n}\n\nfunction matchesAnchors(\n\trecord: CommittedMemoryV1,\n\tquery: Pick<MemoryRecallQueryV1, \"timeRange\" | \"scenes\" | \"projects\" | \"tasks\" | \"facets\">,\n): boolean {\n\tconst atom = record.atom;\n\tconst occurred = Date.parse(atom.occurredAt);\n\tif (query.timeRange) {\n\t\tif (query.timeRange.from !== undefined && occurred < Date.parse(query.timeRange.from)) return false;\n\t\tif (query.timeRange.to !== undefined && occurred > Date.parse(query.timeRange.to)) return false;\n\t}\n\tif (query.scenes !== undefined && !matchesAny(atom.applicability?.scenes, query.scenes)) return false;\n\tif (query.projects !== undefined) {\n\t\t// v8 ignore next -- projectRefs 是必填字段\n\t\tconst pool = [...(atom.projectRefs ?? []), ...(atom.applicability?.projects ?? [])];\n\t\tif (!matchesAny(pool, query.projects)) return false;\n\t}\n\tif (query.tasks !== undefined) {\n\t\t// v8 ignore next -- subjectRefs 是必填字段\n\t\tconst pool = [...(atom.subjectRefs ?? []), ...(atom.applicability?.tasks ?? [])];\n\t\tif (!matchesAny(pool, query.tasks)) return false;\n\t}\n\tif (query.facets !== undefined && query.facets.length > 0) {\n\t\tconst atomFacets = atom.facets;\n\t\tconst everyAnchorSatisfied = query.facets.every((anchor) =>\n\t\t\tatomFacets.some((atomFacet) => facetMatches(anchor, atomFacet)),\n\t\t);\n\t\tif (!everyAnchorSatisfied) return false;\n\t}\n\treturn true;\n}\n\nexport interface MemoryRecallPageV1 {\n\treadonly items: readonly CommittedMemoryV1[];\n\treadonly total: number;\n\treadonly offset: number;\n\treadonly limit: number;\n\t/** True when the page came from the exact-lookup fast path (§5.2). */\n\treadonly lookupUsed: boolean;\n\t/**\n\t * Present only when the query carried a suiteId: how many legacy and\n\t * foreign-suite records the suite read boundary excluded (设计 §11).\n\t */\n\treadonly suiteFilter?: MemorySuiteFilterStatsV1;\n}\n\n/** Deterministic bounded recall index over a 1C.1b store. */\nexport function createMemoryRecallIndex(options: { readonly store: MemoryStoreV1 }): {\n\tquery(query: MemoryRecallQueryV1): MemoryRecallPageV1;\n} {\n\tconst store = options.store;\n\treturn {\n\t\tquery(query: MemoryRecallQueryV1): MemoryRecallPageV1 {\n\t\t\t// Exact-lookup fast path: a memoryId hit bypasses anchors, ordering,\n\t\t\t// and scoring entirely (§5.2) but keeps owner scoping AND the suite\n\t\t\t// read boundary — a legacy or foreign-suite atom is never resurrected\n\t\t\t// through exact lookup.\n\t\t\tif (query.memoryIdEquals !== undefined) {\n\t\t\t\tconst found = store.get(query.memoryIdEquals, { owner: query.owner });\n\t\t\t\tif (query.suiteId === undefined) {\n\t\t\t\t\tconst items = found === undefined ? [] : [found];\n\t\t\t\t\treturn Object.freeze({\n\t\t\t\t\t\titems: Object.freeze(items),\n\t\t\t\t\t\ttotal: items.length,\n\t\t\t\t\t\toffset: query.offset ?? 0,\n\t\t\t\t\t\tlimit: query.limit ?? DEFAULT_LIMIT,\n\t\t\t\t\t\tlookupUsed: true,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tlet suiteFilter: MemorySuiteFilterStatsV1 = Object.freeze({ legacySkipped: 0, foreignSuiteSkipped: 0 });\n\t\t\t\tlet items: readonly CommittedMemoryV1[] = [];\n\t\t\t\tif (found !== undefined) {\n\t\t\t\t\tconst visibility = memorySuiteVisibility(found.atom, query.suiteId);\n\t\t\t\t\tif (visibility === \"visible\") {\n\t\t\t\t\t\titems = [found];\n\t\t\t\t\t} else {\n\t\t\t\t\t\tsuiteFilter = Object.freeze({\n\t\t\t\t\t\t\tlegacySkipped: visibility === \"legacy\" ? 1 : 0,\n\t\t\t\t\t\t\tforeignSuiteSkipped: visibility === \"foreign-suite\" ? 1 : 0,\n\t\t\t\t\t\t});\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn Object.freeze({\n\t\t\t\t\titems: Object.freeze(items),\n\t\t\t\t\ttotal: items.length,\n\t\t\t\t\toffset: query.offset ?? 0,\n\t\t\t\t\tlimit: query.limit ?? DEFAULT_LIMIT,\n\t\t\t\t\tlookupUsed: true,\n\t\t\t\t\tsuiteFilter,\n\t\t\t\t});\n\t\t\t}\n\t\t\tvalidateMemoryRecallQuery(query);\n\t\t\tconst limit = query.limit ?? DEFAULT_LIMIT;\n\t\t\tconst offset = query.offset ?? 0;\n\t\t\t// Suite-scoped reads go through listForSuite so excluded-record counts\n\t\t\t// cover the owner's full ledger, not just the anchor-matched slice.\n\t\t\tconst suitePage =\n\t\t\t\tquery.suiteId === undefined\n\t\t\t\t\t? undefined\n\t\t\t\t\t: store.listForSuite({ owner: query.owner, suiteId: query.suiteId }, query.scope);\n\t\t\tconst matches = (suitePage === undefined ? store.list({ owner: query.owner }, query.scope) : suitePage.records)\n\t\t\t\t.filter((record) => matchesAnchors(record, query))\n\t\t\t\t// Deterministic order: most recent first, memoryId as tie-break.\n\t\t\t\t.sort((left, right) => {\n\t\t\t\t\tconst byTime = Date.parse(right.atom.occurredAt) - Date.parse(left.atom.occurredAt);\n\t\t\t\t\tif (byTime !== 0) return byTime;\n\t\t\t\t\t// v8 ignore next -- memoryId 是 store 主键恒唯一，相等路径不可达\n\t\t\t\t\treturn left.atom.memoryId < right.atom.memoryId ? -1 : left.atom.memoryId > right.atom.memoryId ? 1 : 0;\n\t\t\t\t});\n\t\t\tconst total = matches.length;\n\t\t\tconst items = matches.slice(offset, offset + limit);\n\t\t\treturn Object.freeze({\n\t\t\t\titems: Object.freeze(items),\n\t\t\t\ttotal,\n\t\t\t\toffset,\n\t\t\t\tlimit,\n\t\t\t\tlookupUsed: false,\n\t\t\t\t...(suitePage === undefined ? {} : { suiteFilter: suitePage.filter }),\n\t\t\t});\n\t\t},\n\t};\n}\n"]}

package/dist/memory/recall-packet.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Memory Foundation — recall budgets and bounded recall packet (1C.5a).
+ *
+ * Three-layer budgets (candidateBudget / modelInspectionLimit /
+ * finalResultLimit) plus host hard limits govern every recall. Resolution
+ * rules are frozen (记忆系统设计.md §6.4):
+ * - Caller-provided values may only TIGHTEN limits. Negative, non-finite,
+ *   non-integer, or over-hard-limit caller values are explicitly rejected —
+ *   never silently clamped.
+ * - Only Profile/Policy default values may be clamped down to host limits,
+ *   and every such adjustment is recorded with its reason.
+ * - Hitting any limit yields `omittedCount`, `truncated: true` with a
+ *   `truncationScope` and narrowing hints — candidates are never silently
+ *   passed to the main agent.
+ * V1 recall is deterministic: no model inspection happens in this slice, the
+ * inspection limit still bounds the deterministic stage.
+ */
+import type { MemoryAtomV1, MemorySuiteFilterStatsV1 } from "./foundation.ts";
+export interface MemoryRecallBudgetsV1 {
+    readonly candidateBudget: number;
+    readonly modelInspectionLimit: number;
+    readonly finalResultLimit: number;
+    readonly maxRelationHops: number;
+    readonly maxModelCalls: number;
+    readonly maxOutputTokens: number;
+    readonly maxOutputBytes: number;
+    readonly maxRounds: number;
+}
+export type MemoryRecallBudgetContributionV1 = Partial<MemoryRecallBudgetsV1>;
+export declare const MEMORY_RECALL_BUDGET_FIELDS: readonly ["candidateBudget", "modelInspectionLimit", "finalResultLimit", "maxRelationHops", "maxModelCalls", "maxOutputTokens", "maxOutputBytes", "maxRounds"];
+export type MemoryRecallBudgetField = (typeof MEMORY_RECALL_BUDGET_FIELDS)[number];
+export interface MemoryRecallBudgetsResolution {
+    readonly budgets: MemoryRecallBudgetsV1;
+    /** Recorded default-clamp decisions (Policy defaults narrowed by host limits). */
+    readonly adjustments: readonly string[];
+    /** Caller contributions that were accepted. */
+    readonly callerTightened: readonly MemoryRecallBudgetField[];
+}
+/**
+ * Resolves the effective budgets. Resolution priority: caller request (tighten
+ * only) → Policy defaults (clamped to host limits, adjustments recorded) →
+ * host hard limits. Caller values over the host limit are explicitly rejected.
+ */
+export declare function resolveMemoryRecallBudgets(input: {
+    readonly requested?: MemoryRecallBudgetContributionV1;
+    readonly policyDefaults: MemoryRecallBudgetsV1;
+    readonly hostLimits: MemoryRecallBudgetsV1;
+}): MemoryRecallBudgetsResolution;
+export interface MemoryRecallPacketBudgetUsageV1 {
+    readonly candidateCount: number;
+    readonly modelInspectedCount: number;
+    readonly finalResultCount: number;
+}
+export type MemoryRecallTruncationScopeV1 = "none" | "operation" | "round" | "final_packet";
+export interface MemoryRecallPacketErrorV1 {
+    readonly code: string;
+    readonly message: string;
+    readonly stage: "authorize" | "anchor" | "query" | "model" | "validate" | "serialize" | "purge";
+    readonly retryable: boolean;
+}
+export interface MemoryRecallPacketV1 {
+    readonly operationId: string;
+    readonly status: "completed" | "empty" | "needs_narrowing" | "failed";
+    readonly facts: readonly {
+        readonly memoryId: string;
+        readonly contentRevision: string;
+        readonly statement: string;
+        readonly confidence: number;
+    }[];
+    /** Query plan facts (设计 §6.3): what the recall actually did. */
+    readonly queryPlan: {
+        readonly lookupUsed: boolean;
+        readonly filtersApplied: readonly string[];
+        /** Version of the deterministic scorer that ordered the facts. */
+        readonly scorerVersion: string;
+    };
+    /** Model-call attempts spent (V1 deterministic: 0 or 1). */
+    readonly attempts: number;
+    readonly narrowingHints: readonly string[];
+    readonly omittedCount: number;
+    readonly truncated: boolean;
+    readonly truncationScope: MemoryRecallTruncationScopeV1;
+    /** Present only on failed packets — failures resolve as structured packets, never throw. */
+    readonly error?: MemoryRecallPacketErrorV1;
+    /**
+     * Present only when the recall query carried a suiteId: how many legacy and
+     * foreign-suite records the suite read boundary excluded (方案系统设计
+     * §6.1/§11, 读取边界惰性可观测).
+     */
+    readonly suiteFilter?: MemorySuiteFilterStatsV1;
+    readonly budget: {
+        readonly candidateBudget: number;
+        readonly modelInspectionLimit: number;
+        readonly finalResultLimit: number;
+        readonly used: {
+            readonly candidateCount: number;
+            readonly modelInspectedCount: number;
+            readonly finalResultCount: number;
+        };
+    };
+}
+export interface MemoryRecallPacketInputV1 {
+    readonly operationId: string;
+    readonly candidates: readonly MemoryAtomV1[];
+    readonly budgets: MemoryRecallBudgetsV1;
+    /** Deterministic statement projector; defaults to the payload JSON. */
+    readonly buildStatement?: (atom: MemoryAtomV1) => string;
+    /** Suite read-boundary skip counters; present only on suite-scoped recalls. */
+    readonly suiteFilter?: MemorySuiteFilterStatsV1;
+}
+/**
+ * Builds the bounded recall packet from deterministic candidates:
+ * 1. candidates over `candidateBudget` → `needs_narrowing` with hints,
+ *    omittedCount = full candidate count (nothing is passed on).
+ * 2. `modelInspectionLimit` bounds the inspected stage (V1 inspects
+ *    deterministically); overflow is omitted with `round` scope.
+ * 3. `finalResultLimit` bounds the packet facts; overflow is omitted with
+ *    `final_packet` scope.
+ */
+export declare function buildMemoryRecallPacketV1(input: MemoryRecallPacketInputV1): MemoryRecallPacketV1;
+//# sourceMappingURL=recall-packet.d.ts.map

package/dist/memory/recall-packet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-packet.d.ts","sourceRoot":"","sources":["../../src/memory/recall-packet.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Memory Foundation — recall budgets and bounded recall packet (1C.5a).\n *\n * Three-layer budgets (candidateBudget / modelInspectionLimit /\n * finalResultLimit) plus host hard limits govern every recall. Resolution\n * rules are frozen (记忆系统设计.md §6.4):\n * - Caller-provided values may only TIGHTEN limits. Negative, non-finite,\n *   non-integer, or over-hard-limit caller values are explicitly rejected —\n *   never silently clamped.\n * - Only Profile/Policy default values may be clamped down to host limits,\n *   and every such adjustment is recorded with its reason.\n * - Hitting any limit yields `omittedCount`, `truncated: true` with a\n *   `truncationScope` and narrowing hints — candidates are never silently\n *   passed to the main agent.\n * V1 recall is deterministic: no model inspection happens in this slice, the\n * inspection limit still bounds the deterministic stage.\n */\nimport type { MemoryAtomV1, MemorySuiteFilterStatsV1 } from \"./foundation.ts\";\n\nexport interface MemoryRecallBudgetsV1 {\n\treadonly candidateBudget: number;\n\treadonly modelInspectionLimit: number;\n\treadonly finalResultLimit: number;\n\treadonly maxRelationHops: number;\n\treadonly maxModelCalls: number;\n\treadonly maxOutputTokens: number;\n\treadonly maxOutputBytes: number;\n\treadonly maxRounds: number;\n}\n\nexport type MemoryRecallBudgetContributionV1 = Partial<MemoryRecallBudgetsV1>;\n\nexport const MEMORY_RECALL_BUDGET_FIELDS = [\n\t\"candidateBudget\",\n\t\"modelInspectionLimit\",\n\t\"finalResultLimit\",\n\t\"maxRelationHops\",\n\t\"maxModelCalls\",\n\t\"maxOutputTokens\",\n\t\"maxOutputBytes\",\n\t\"maxRounds\",\n] as const;\n\nexport type MemoryRecallBudgetField = (typeof MEMORY_RECALL_BUDGET_FIELDS)[number];\n\nfunction assertBudgetValue(value: unknown, field: MemoryRecallBudgetField, label: string): asserts value is number {\n\tif (typeof value !== \"number\" || !Number.isFinite(value) || !Number.isSafeInteger(value) || value < 1) {\n\t\tthrow new Error(`${label}.${field} must be a positive safe integer`);\n\t}\n}\n\nexport interface MemoryRecallBudgetsResolution {\n\treadonly budgets: MemoryRecallBudgetsV1;\n\t/** Recorded default-clamp decisions (Policy defaults narrowed by host limits). */\n\treadonly adjustments: readonly string[];\n\t/** Caller contributions that were accepted. */\n\treadonly callerTightened: readonly MemoryRecallBudgetField[];\n}\n\n/**\n * Resolves the effective budgets. Resolution priority: caller request (tighten\n * only) → Policy defaults (clamped to host limits, adjustments recorded) →\n * host hard limits. Caller values over the host limit are explicitly rejected.\n */\nexport function resolveMemoryRecallBudgets(input: {\n\treadonly requested?: MemoryRecallBudgetContributionV1;\n\treadonly policyDefaults: MemoryRecallBudgetsV1;\n\treadonly hostLimits: MemoryRecallBudgetsV1;\n}): MemoryRecallBudgetsResolution {\n\tconst adjustments: string[] = [];\n\tconst callerTightened: MemoryRecallBudgetField[] = [];\n\tconst budgets = {} as Record<MemoryRecallBudgetField, number>;\n\tfor (const field of MEMORY_RECALL_BUDGET_FIELDS) {\n\t\tconst requested = input.requested?.[field];\n\t\tif (requested !== undefined) {\n\t\t\tassertBudgetValue(requested, field, \"Requested recall budgets\");\n\t\t\tconst hardLimit = input.hostLimits[field];\n\t\t\tif (requested > hardLimit) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Requested recall budgets.${field} (${requested}) exceeds the host hard limit (${hardLimit}); callers may only tighten limits`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tbudgets[field] = requested;\n\t\t\tcallerTightened.push(field);\n\t\t\tcontinue;\n\t\t}\n\t\tconst hardLimit = input.hostLimits[field];\n\t\tconst policyDefault = input.policyDefaults[field];\n\t\tassertBudgetValue(policyDefault, field, \"Policy default recall budgets\");\n\t\tassertBudgetValue(hardLimit, field, \"Host limit recall budgets\");\n\t\tif (policyDefault > hardLimit) {\n\t\t\tadjustments.push(`Policy default ${field}=${policyDefault} clamped to host limit ${hardLimit}`);\n\t\t\tbudgets[field] = hardLimit;\n\t\t} else {\n\t\t\tbudgets[field] = policyDefault;\n\t\t}\n\t}\n\treturn {\n\t\tbudgets: Object.freeze(budgets),\n\t\tadjustments: Object.freeze(adjustments),\n\t\tcallerTightened: Object.freeze(callerTightened),\n\t};\n}\n\nexport interface MemoryRecallPacketBudgetUsageV1 {\n\treadonly candidateCount: number;\n\treadonly modelInspectedCount: number;\n\treadonly finalResultCount: number;\n}\n\nexport type MemoryRecallTruncationScopeV1 = \"none\" | \"operation\" | \"round\" | \"final_packet\";\n\nexport interface MemoryRecallPacketErrorV1 {\n\treadonly code: string;\n\treadonly message: string;\n\treadonly stage: \"authorize\" | \"anchor\" | \"query\" | \"model\" | \"validate\" | \"serialize\" | \"purge\";\n\treadonly retryable: boolean;\n}\n\nexport interface MemoryRecallPacketV1 {\n\treadonly operationId: string;\n\treadonly status: \"completed\" | \"empty\" | \"needs_narrowing\" | \"failed\";\n\treadonly facts: readonly {\n\t\treadonly memoryId: string;\n\t\treadonly contentRevision: string;\n\t\treadonly statement: string;\n\t\treadonly confidence: number;\n\t}[];\n\t/** Query plan facts (设计 §6.3): what the recall actually did. */\n\treadonly queryPlan: {\n\t\treadonly lookupUsed: boolean;\n\t\treadonly filtersApplied: readonly string[];\n\t\t/** Version of the deterministic scorer that ordered the facts. */\n\t\treadonly scorerVersion: string;\n\t};\n\t/** Model-call attempts spent (V1 deterministic: 0 or 1). */\n\treadonly attempts: number;\n\treadonly narrowingHints: readonly string[];\n\treadonly omittedCount: number;\n\treadonly truncated: boolean;\n\treadonly truncationScope: MemoryRecallTruncationScopeV1;\n\t/** Present only on failed packets — failures resolve as structured packets, never throw. */\n\treadonly error?: MemoryRecallPacketErrorV1;\n\t/**\n\t * Present only when the recall query carried a suiteId: how many legacy and\n\t * foreign-suite records the suite read boundary excluded (方案系统设计\n\t * §6.1/§11, 读取边界惰性可观测).\n\t */\n\treadonly suiteFilter?: MemorySuiteFilterStatsV1;\n\treadonly budget: {\n\t\treadonly candidateBudget: number;\n\t\treadonly modelInspectionLimit: number;\n\t\treadonly finalResultLimit: number;\n\t\treadonly used: {\n\t\t\treadonly candidateCount: number;\n\t\t\treadonly modelInspectedCount: number;\n\t\t\treadonly finalResultCount: number;\n\t\t};\n\t};\n}\n\nfunction defaultStatement(atom: MemoryAtomV1): string {\n\treturn JSON.stringify(atom.payload);\n}\n\nexport interface MemoryRecallPacketInputV1 {\n\treadonly operationId: string;\n\treadonly candidates: readonly MemoryAtomV1[];\n\treadonly budgets: MemoryRecallBudgetsV1;\n\t/** Deterministic statement projector; defaults to the payload JSON. */\n\treadonly buildStatement?: (atom: MemoryAtomV1) => string;\n\t/** Suite read-boundary skip counters; present only on suite-scoped recalls. */\n\treadonly suiteFilter?: MemorySuiteFilterStatsV1;\n}\n\n/**\n * Builds the bounded recall packet from deterministic candidates:\n * 1. candidates over `candidateBudget` → `needs_narrowing` with hints,\n *    omittedCount = full candidate count (nothing is passed on).\n * 2. `modelInspectionLimit` bounds the inspected stage (V1 inspects\n *    deterministically); overflow is omitted with `round` scope.\n * 3. `finalResultLimit` bounds the packet facts; overflow is omitted with\n *    `final_packet` scope.\n */\nexport function buildMemoryRecallPacketV1(input: MemoryRecallPacketInputV1): MemoryRecallPacketV1 {\n\tconst budgets = input.budgets;\n\tconst buildStatement = input.buildStatement ?? defaultStatement;\n\n\tif (input.candidates.length > budgets.candidateBudget) {\n\t\treturn Object.freeze({\n\t\t\toperationId: input.operationId,\n\t\t\tstatus: \"needs_narrowing\" as const,\n\t\t\tfacts: Object.freeze([]),\n\t\t\tnarrowingHints: Object.freeze([\n\t\t\t\t`Candidate count ${input.candidates.length} exceeds candidateBudget ${budgets.candidateBudget}`,\n\t\t\t\t\"Add time, scene, project, task, or facet anchors to narrow the query\",\n\t\t\t]),\n\t\t\tomittedCount: input.candidates.length,\n\t\t\ttruncated: true,\n\t\t\ttruncationScope: \"round\" as const,\n\t\t\tqueryPlan: { lookupUsed: false, filtersApplied: [], scorerVersion: \"scorer@1\" },\n\t\t\tattempts: 0,\n\t\t\t...(input.suiteFilter === undefined ? {} : { suiteFilter: input.suiteFilter }),\n\t\t\tbudget: Object.freeze({\n\t\t\t\tcandidateBudget: budgets.candidateBudget,\n\t\t\t\tmodelInspectionLimit: budgets.modelInspectionLimit,\n\t\t\t\tfinalResultLimit: budgets.finalResultLimit,\n\t\t\t\tused: Object.freeze({\n\t\t\t\t\tcandidateCount: input.candidates.length,\n\t\t\t\t\tmodelInspectedCount: 0,\n\t\t\t\t\tfinalResultCount: 0,\n\t\t\t\t}),\n\t\t\t}),\n\t\t});\n\t}\n\n\tconst inspected = input.candidates.slice(0, budgets.modelInspectionLimit);\n\tconst factsSource = inspected.slice(0, budgets.finalResultLimit);\n\tconst facts = factsSource.map((atom) => ({\n\t\tmemoryId: atom.memoryId,\n\t\tcontentRevision: atom.contentRevision,\n\t\tstatement: buildStatement(atom),\n\t\tconfidence: atom.confidence,\n\t}));\n\tconst omittedFromFinal = inspected.length - facts.length;\n\tconst omittedFromInspection = input.candidates.length - inspected.length;\n\tconst omittedCount = omittedFromFinal + omittedFromInspection;\n\n\tif (input.candidates.length === 0) {\n\t\treturn Object.freeze({\n\t\t\toperationId: input.operationId,\n\t\t\tstatus: \"empty\" as const,\n\t\t\tfacts: Object.freeze([]),\n\t\t\tnarrowingHints: Object.freeze([]),\n\t\t\tomittedCount: 0,\n\t\t\ttruncated: false,\n\t\t\ttruncationScope: \"none\" as const,\n\t\t\tqueryPlan: { lookupUsed: false, filtersApplied: [], scorerVersion: \"scorer@1\" },\n\t\t\tattempts: 0,\n\t\t\t...(input.suiteFilter === undefined ? {} : { suiteFilter: input.suiteFilter }),\n\t\t\tbudget: Object.freeze({\n\t\t\t\tcandidateBudget: budgets.candidateBudget,\n\t\t\t\tmodelInspectionLimit: budgets.modelInspectionLimit,\n\t\t\t\tfinalResultLimit: budgets.finalResultLimit,\n\t\t\t\tused: Object.freeze({ candidateCount: 0, modelInspectedCount: 0, finalResultCount: 0 }),\n\t\t\t}),\n\t\t});\n\t}\n\n\tconst status: MemoryRecallPacketV1[\"status\"] = facts.length > 0 ? \"completed\" : \"empty\";\n\treturn Object.freeze({\n\t\toperationId: input.operationId,\n\t\tstatus,\n\t\tfacts: Object.freeze(facts),\n\t\tnarrowingHints: Object.freeze([]),\n\t\tqueryPlan: { lookupUsed: false, filtersApplied: [], scorerVersion: \"scorer@1\" },\n\t\tattempts: 0,\n\t\tomittedCount,\n\t\ttruncated: omittedCount > 0,\n\t\ttruncationScope:\n\t\t\tomittedCount === 0\n\t\t\t\t? (\"none\" as const)\n\t\t\t\t: omittedFromInspection > 0\n\t\t\t\t\t? (\"round\" as const)\n\t\t\t\t\t: (\"final_packet\" as const),\n\t\t...(input.suiteFilter === undefined ? {} : { suiteFilter: input.suiteFilter }),\n\t\tbudget: Object.freeze({\n\t\t\tcandidateBudget: budgets.candidateBudget,\n\t\t\tmodelInspectionLimit: budgets.modelInspectionLimit,\n\t\t\tfinalResultLimit: budgets.finalResultLimit,\n\t\t\tused: Object.freeze({\n\t\t\t\tcandidateCount: input.candidates.length,\n\t\t\t\tmodelInspectedCount: inspected.length,\n\t\t\t\tfinalResultCount: facts.length,\n\t\t\t}),\n\t\t}),\n\t});\n}\n"]}