@snoai/memory 0.0.0-stage → 1.0.1

package/dist/memory-kind-policy-BiuRjSJc.d.ts

@@ -0,0 +1,23 @@
+import { h as MemoryCategory } from "./types-CWdhXLxr.js";
+//#region src/engine/shared/memory-kind-policy.d.ts
+type WritePolicy = "append-only" | "mutation-native" | "derived-only";
+type DedupePolicy = {
+  mode: "none";
+} | {
+  mode: "signature";
+  field: "anti_pattern_signature";
+};
+type WriterAuthority = "extraction" | "profile-writer" | "offline-family";
+declare function isAppendOnly(kind: MemoryCategory): boolean;
+declare function isMutationNative(kind: MemoryCategory): boolean;
+declare function isDerivedOnly(kind: MemoryCategory): boolean;
+declare function writePolicy(kind: MemoryCategory): WritePolicy;
+declare function dedupePolicy(kind: MemoryCategory): DedupePolicy;
+declare function allowedWriters(kind: MemoryCategory): readonly WriterAuthority[];
+declare function canExtractorWrite(kind: MemoryCategory): boolean;
+declare function canProfileWriterWrite(kind: MemoryCategory): boolean;
+declare function canToolWrite(kind: MemoryCategory): boolean;
+declare function canTrustedWrite(kind: MemoryCategory): boolean;
+declare function canOfflineFamilyWrite(kind: MemoryCategory): boolean;
+//#endregion
+export { canExtractorWrite as a, canToolWrite as c, isAppendOnly as d, isDerivedOnly as f, allowedWriters as i, canTrustedWrite as l, writePolicy as m, WritePolicy as n, canOfflineFamilyWrite as o, isMutationNative as p, WriterAuthority as r, canProfileWriterWrite as s, DedupePolicy as t, dedupePolicy as u };

package/dist/memory-metadata-codec-DL1sbJiN.js

@@ -0,0 +1,577 @@
+import { MEMORY_CATEGORIES, normalizeCategory } from "./internal/engine/shared/types.js";
+import { normalizeIsoDateTimeString } from "./internal/engine/shared/iso-date-time.js";
+import { z } from "zod";
+//#region src/engine/extraction/memory-metadata-normalizers.ts
+function validateMemoryCategory(raw) {
+	return normalizeCategory(raw) ?? void 0;
+}
+function clamp01(value, fallback) {
+	const n = typeof value === "number" ? value : Number(value);
+	if (!Number.isFinite(n)) return fallback;
+	return Math.min(1, Math.max(0, n));
+}
+function clampCount(value, fallback = 0) {
+	const n = typeof value === "number" ? value : Number(value);
+	if (!Number.isFinite(n) || n < 0) return fallback;
+	return Math.floor(n);
+}
+function normalizeTier(value) {
+	switch (value) {
+		case "core":
+		case "working":
+		case "peripheral": return value;
+		default: return "working";
+	}
+}
+function normalizeState(value) {
+	switch (value) {
+		case "pending":
+		case "confirmed":
+		case "archived": return value;
+		default: return "confirmed";
+	}
+}
+function normalizeSource(value) {
+	switch (value) {
+		case "manual":
+		case "ambient-learning":
+		case "agent_end":
+		case "reflection":
+		case "session-summary":
+		case "legacy": return value;
+		default: return "legacy";
+	}
+}
+function normalizeLayer(value) {
+	switch (value) {
+		case "durable":
+		case "working":
+		case "reflection":
+		case "archive": return value;
+		default: return "working";
+	}
+}
+function deriveDefaultLayer(source, memoryCategory, state) {
+	if (source === "reflection" || source === "session-summary") return "reflection";
+	if (state === "archived") return "archive";
+	if (memoryCategory === "summary") return "reflection";
+	if (memoryCategory === "profile" || memoryCategory === "persona" || memoryCategory === "episodic" || memoryCategory === "lesson") return "durable";
+	return "working";
+}
+function defaultOverview(text) {
+	return `- ${text}`;
+}
+function normalizeText(value, fallback) {
+	return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+function normalizeOptionalString(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function normalizeTimestamp(value, fallback) {
+	const n = typeof value === "number" ? value : Number(value);
+	if (!Number.isFinite(n) || n <= 0) return fallback;
+	return Math.floor(n);
+}
+function normalizeOptionalTimestamp(value) {
+	const n = typeof value === "number" ? value : Number(value);
+	if (!Number.isFinite(n) || n <= 0) return void 0;
+	return Math.floor(n);
+}
+function deriveFactKey(metadata) {
+	if (metadata.kind === "profile" || metadata.kind === "persona") {
+		const sectionName = normalizeOptionalString(metadata.section_name);
+		if (metadata.kind === "profile" && sectionName === "active_tasks" && metadata.active_task_kind === "task") {
+			const taskId = normalizeOptionalString(metadata.active_task_id);
+			return taskId ? `profile:active_tasks:${taskId}` : void 0;
+		}
+		return sectionName ? `${metadata.kind}:${sectionName}` : void 0;
+	}
+	if (metadata.kind === "lesson") {
+		const signature = normalizeOptionalString(metadata.anti_pattern_signature);
+		return signature ? `lesson:${signature}` : void 0;
+	}
+}
+//#endregion
+//#region src/engine/extraction/memory-metadata-types.ts
+/** @file memory-metadata-types.ts
+* @purpose Defines typed insight metadata contracts via Zod discriminated union.
+* @boundary Metadata shape declarations only.
+*/
+const memoryCategory = z.enum(MEMORY_CATEGORIES);
+const memoryTier = z.enum([
+	"core",
+	"working",
+	"peripheral"
+]);
+const memoryState = z.enum([
+	"pending",
+	"confirmed",
+	"archived"
+]);
+const memorySource = z.enum([
+	"manual",
+	"ambient-learning",
+	"agent_end",
+	"reflection",
+	"session-summary",
+	"legacy"
+]);
+const memoryLayer = z.enum([
+	"durable",
+	"working",
+	"reflection",
+	"archive"
+]);
+const memoryRelation = z.object({
+	type: z.string(),
+	targetId: z.string(),
+	source: z.string().optional()
+});
+const activeTaskStatus = z.enum([
+	"active",
+	"completed",
+	"removed"
+]);
+const activeTaskOrigin = z.discriminatedUnion("kind", [z.object({
+	kind: z.literal("runtime"),
+	source_id: z.string().min(1),
+	normalized_description: z.string().min(1)
+}), z.object({
+	kind: z.literal("legacy"),
+	omnibus_row_id: z.string().min(1),
+	item_index: z.number().int().nonnegative(),
+	legacy_item_id: z.string().min(1)
+})]);
+const activeTaskLifecycleEvent = z.object({
+	from: activeTaskStatus.nullable(),
+	to: activeTaskStatus,
+	at: z.number(),
+	source_id: z.string().min(1)
+});
+const memoryMetadataBase = z.object({
+	kind: memoryCategory,
+	l0_abstract: z.string(),
+	l1_overview: z.string(),
+	l2_content: z.string(),
+	memory_category: memoryCategory,
+	tier: memoryTier,
+	access_count: z.number(),
+	confidence: z.number(),
+	last_accessed_at: z.number(),
+	asserted_at: z.number(),
+	valid_from: z.number(),
+	invalidated_at: z.number().optional(),
+	fact_key: z.string().optional(),
+	supersedes: z.string().optional(),
+	superseded_by: z.string().optional(),
+	relations: z.array(memoryRelation).optional(),
+	source_session: z.string().optional(),
+	state: memoryState,
+	source: memorySource,
+	memory_layer: memoryLayer,
+	injected_count: z.number(),
+	last_injected_at: z.number().optional(),
+	last_confirmed_use_at: z.number().optional(),
+	bad_recall_count: z.number(),
+	suppressed_until_turn: z.number(),
+	canonical_id: z.string().optional(),
+	memory_temporal_type: z.enum(["static", "dynamic"]).optional(),
+	temporal_resolution_status: z.enum([
+		"resolved",
+		"unresolved",
+		"static"
+	]).optional(),
+	temporal_phrase: z.string().optional(),
+	valid_until: z.number().optional(),
+	merge_lineage: z.array(z.string()).optional()
+});
+const episodicMetadata = memoryMetadataBase.extend({
+	kind: z.literal("episodic"),
+	memory_category: z.literal("episodic"),
+	valid_from: z.number().optional(),
+	event_at: z.union([z.string(), z.number()]).optional(),
+	entity_kind: z.string().optional()
+}).catchall(z.unknown());
+const profileMetadata = memoryMetadataBase.extend({
+	kind: z.literal("profile"),
+	memory_category: z.literal("profile"),
+	section_name: z.string().min(1),
+	rawTopicPhrase: z.string().optional(),
+	active_task_kind: z.enum(["task", "projection"]).optional(),
+	active_task_id: z.string().min(1).optional(),
+	active_task_origin: activeTaskOrigin.optional(),
+	active_task_status: activeTaskStatus.optional(),
+	active_task_created_at: z.number().optional(),
+	active_task_transitioned_at: z.number().optional(),
+	active_task_lifecycle: z.array(activeTaskLifecycleEvent).optional(),
+	active_task_ids: z.array(z.string().min(1)).optional(),
+	active_task_titles: z.array(z.string()).optional()
+}).catchall(z.unknown());
+const personaMetadata = memoryMetadataBase.extend({
+	kind: z.literal("persona"),
+	memory_category: z.literal("persona"),
+	section_name: z.string().min(1)
+}).catchall(z.unknown());
+const lessonMetadata = memoryMetadataBase.extend({
+	kind: z.literal("lesson"),
+	memory_category: z.literal("lesson"),
+	anti_pattern_signature: z.string().min(1)
+}).catchall(z.unknown());
+const summaryMetadata = memoryMetadataBase.extend({
+	kind: z.literal("summary"),
+	memory_category: z.literal("summary"),
+	children_ids: z.array(z.string()),
+	depth: z.number().int().min(1)
+}).catchall(z.unknown());
+const stateMetadata = memoryMetadataBase.extend({
+	kind: z.literal("state"),
+	memory_category: z.literal("state")
+}).catchall(z.unknown());
+const memoryMetadata = z.discriminatedUnion("kind", [
+	episodicMetadata,
+	profileMetadata,
+	personaMetadata,
+	lessonMetadata,
+	summaryMetadata,
+	stateMetadata
+]);
+//#endregion
+//#region src/engine/extraction/memory-support-info.ts
+/** @file memory-support-info.ts
+* @purpose Parses and updates contextual support statistics for memories.
+* @boundary Support-info V2 vocabulary, parsing, and bounded updates only.
+*/
+const SUPPORT_CONTEXT_VOCABULARY = [
+	"general",
+	"morning",
+	"afternoon",
+	"evening",
+	"night",
+	"weekday",
+	"weekend",
+	"work",
+	"leisure",
+	"summer",
+	"winter",
+	"travel"
+];
+const MAX_SUPPORT_SLICES = 8;
+/** Normalizes context at the boundary before insight metadata parsing uses it. */
+function normalizeContext(raw) {
+	if (!raw?.trim()) return "general";
+	const lower = raw.trim().toLowerCase();
+	if (SUPPORT_CONTEXT_VOCABULARY.includes(lower)) return lower;
+	return {
+		早上: "morning",
+		上午: "morning",
+		早晨: "morning",
+		下午: "afternoon",
+		傍晚: "evening",
+		晚上: "evening",
+		深夜: "night",
+		夜晚: "night",
+		凌晨: "night",
+		工作日: "weekday",
+		平时: "weekday",
+		周末: "weekend",
+		假日: "weekend",
+		休息日: "weekend",
+		工作: "work",
+		上班: "work",
+		办公: "work",
+		休闲: "leisure",
+		放松: "leisure",
+		休息: "leisure",
+		夏天: "summer",
+		夏季: "summer",
+		冬天: "winter",
+		冬季: "winter",
+		旅行: "travel",
+		出差: "travel",
+		旅游: "travel"
+	}[lower] ?? lower;
+}
+/** Parses support info into the normalized shape used by insight metadata parsing. */
+function parseSupportInfo(raw) {
+	const defaultV2 = {
+		global_strength: .5,
+		total_observations: 0,
+		slices: []
+	};
+	if (!raw || typeof raw !== "object") return defaultV2;
+	const obj = raw;
+	if (Array.isArray(obj.slices)) return {
+		global_strength: typeof obj.global_strength === "number" ? obj.global_strength : .5,
+		total_observations: typeof obj.total_observations === "number" ? obj.total_observations : 0,
+		slices: obj.slices.filter((s) => s && typeof s.context === "string").map((s) => ({
+			context: String(s.context),
+			confirmations: typeof s.confirmations === "number" && s.confirmations >= 0 ? s.confirmations : 0,
+			contradictions: typeof s.contradictions === "number" && s.contradictions >= 0 ? s.contradictions : 0,
+			strength: typeof s.strength === "number" && s.strength >= 0 && s.strength <= 1 ? s.strength : .5,
+			last_observed_at: typeof s.last_observed_at === "number" ? s.last_observed_at : Date.now()
+		}))
+	};
+	const conf = typeof obj.confirmations === "number" ? obj.confirmations : 0;
+	const contra = typeof obj.contradictions === "number" ? obj.contradictions : 0;
+	const total = conf + contra;
+	if (total === 0) return defaultV2;
+	return {
+		global_strength: total > 0 ? conf / total : .5,
+		total_observations: total,
+		slices: [{
+			context: "general",
+			confirmations: conf,
+			contradictions: contra,
+			strength: total > 0 ? conf / total : .5,
+			last_observed_at: Date.now()
+		}]
+	};
+}
+/**
+* Implements update support stats as the local insight metadata parsing
+* operation. `at` is the observation event time (the session date when one is
+* known); it defaults to the wall clock only when no session anchor exists.
+*/
+function updateSupportStats(existing, contextLabel, event, at = Date.now()) {
+	const ctx = normalizeContext(contextLabel);
+	const base = {
+		...existing,
+		slices: [...existing.slices.map((s) => ({ ...s }))]
+	};
+	let slice = base.slices.find((s) => s.context === ctx);
+	if (!slice) {
+		slice = {
+			context: ctx,
+			confirmations: 0,
+			contradictions: 0,
+			strength: .5,
+			last_observed_at: at
+		};
+		base.slices.push(slice);
+	}
+	if (event === "support") slice.confirmations++;
+	else slice.contradictions++;
+	const sliceTotal = slice.confirmations + slice.contradictions;
+	slice.strength = sliceTotal > 0 ? slice.confirmations / sliceTotal : .5;
+	slice.last_observed_at = Math.max(slice.last_observed_at, at);
+	let slices = base.slices;
+	let droppedConf = 0;
+	let droppedContra = 0;
+	if (slices.length > 8) {
+		slices = slices.sort((a, b) => b.last_observed_at - a.last_observed_at);
+		const dropped = slices.slice(8);
+		for (const d of dropped) {
+			droppedConf += d.confirmations;
+			droppedContra += d.contradictions;
+		}
+		slices = slices.slice(0, 8);
+	}
+	let totalConf = droppedConf;
+	let totalContra = droppedContra;
+	for (const s of slices) {
+		totalConf += s.confirmations;
+		totalContra += s.contradictions;
+	}
+	const totalObs = totalConf + totalContra;
+	return {
+		global_strength: totalObs > 0 ? totalConf / totalObs : .5,
+		total_observations: totalObs,
+		slices
+	};
+}
+//#endregion
+//#region src/engine/extraction/memory-metadata-codec.ts
+/** @file memory-metadata-codec.ts
+* @purpose Normalizes extracted metadata into typed fields for ranking and filtering.
+* @boundary Extractor output, preference slots, and store metadata persistence.
+* @see memory-metadata-normalizers.ts, memory-support-info.ts.
+*/
+function normalizeEventTime(value) {
+	const iso = normalizeIsoDateTimeString(value);
+	if (iso !== void 0) return iso;
+	if (typeof value === "number" && Number.isFinite(new Date(value).getTime())) return value;
+}
+var ExtractionError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ExtractionError";
+	}
+};
+/** Check if a memory has passed its temporal expiry (valid_until). */
+function isMemoryExpired(metadata, at = Date.now()) {
+	if (metadata.memory_category === "episodic") return false;
+	return metadata.valid_until != null && metadata.valid_until <= at;
+}
+function parseRawMetadata(rawMetadata) {
+	if (!rawMetadata) return {};
+	try {
+		const obj = JSON.parse(rawMetadata);
+		if (obj && typeof obj === "object") return obj;
+	} catch {
+		return {};
+	}
+	return {};
+}
+function readCategoryField(label, value) {
+	if (value === void 0) return void 0;
+	if (typeof value !== "string") throw new Error(`memory-metadata-codec: ${label} category must be a string`);
+	const category = validateMemoryCategory(value);
+	if (!category) throw new Error(`memory-metadata-codec: unrecognized ${label} category: ${value}`);
+	return category;
+}
+function resolveMemoryCategory(fields) {
+	const categories = fields.map((field) => readCategoryField(field.label, field.value)).filter((category) => category !== void 0);
+	const first = categories[0];
+	if (!first) throw new Error("memory-metadata-codec: missing memory category/kind");
+	if (categories.some((category) => category !== first)) throw new Error(`memory-metadata-codec: row/category/kind mismatch (${fields.map((field) => `${field.label}=${String(field.value)}`).join(", ")})`);
+	return first;
+}
+function parseNormalizedMetadata(candidate) {
+	const result = memoryMetadata.safeParse(candidate);
+	if (result.success) return result.data;
+	const message = result.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
+	throw new Error(`memory-metadata-codec: invalid metadata (${message})`);
+}
+function requireNonEmptyField(kind, field, value) {
+	const normalized = normalizeOptionalString(value);
+	if (normalized) return normalized;
+	throw new ExtractionError(`memory-metadata-codec: ${field} is required for ${kind} metadata`);
+}
+function normalizeInsightMetadata(parsed, entry, patch = {}) {
+	const text = typeof patch.l2_content === "string" ? patch.l2_content : entry.text ?? "";
+	const timestamp = typeof entry.timestamp === "number" && Number.isFinite(entry.timestamp) ? entry.timestamp : Date.now();
+	const memoryCategory = resolveMemoryCategory([
+		{
+			label: "metadata.kind",
+			value: parsed.kind
+		},
+		{
+			label: "metadata.memory_category",
+			value: parsed.memory_category
+		},
+		{
+			label: "entry",
+			value: entry.category
+		},
+		{
+			label: "patch.kind",
+			value: patch.kind
+		},
+		{
+			label: "patch.memory_category",
+			value: patch.memory_category
+		}
+	]);
+	const l0 = normalizeText(patch.l0_abstract ?? parsed.l0_abstract, text);
+	const l2 = normalizeText(patch.l2_content ?? parsed.l2_content, text);
+	const validFrom = normalizeTimestamp(patch.valid_from ?? parsed.valid_from, timestamp);
+	const invalidatedAt = patch.invalidated_at === void 0 ? normalizeOptionalTimestamp(parsed.invalidated_at) : normalizeOptionalTimestamp(patch.invalidated_at);
+	const fallbackSource = parsed.type === "session-summary" ? "session-summary" : parsed.type === "memory-reflection" || parsed.type === "memory-reflection-item" || parsed.type === "memory-reflection-event" || parsed.type === "memory-reflection-mapped" ? "reflection" : "legacy";
+	const source = normalizeSource(patch.source ?? parsed.source ?? fallbackSource);
+	const defaultState = source === "session-summary" ? "archived" : "confirmed";
+	const state = normalizeState(patch.state ?? parsed.state ?? defaultState);
+	const memoryLayer = normalizeLayer(patch.memory_layer ?? parsed.memory_layer ?? deriveDefaultLayer(source, memoryCategory, state));
+	const candidate = {
+		...parsed,
+		...patch,
+		kind: memoryCategory,
+		l0_abstract: l0,
+		l1_overview: normalizeText(patch.l1_overview ?? parsed.l1_overview, defaultOverview(l0)),
+		l2_content: l2,
+		memory_category: memoryCategory,
+		tier: normalizeTier(patch.tier ?? parsed.tier ?? (memoryCategory === "profile" ? "core" : "working")),
+		access_count: clampCount(patch.access_count ?? parsed.access_count, 0),
+		confidence: clamp01(patch.confidence ?? parsed.confidence, .7),
+		last_accessed_at: clampCount(patch.last_accessed_at ?? parsed.last_accessed_at, timestamp),
+		asserted_at: normalizeTimestamp(patch.asserted_at ?? parsed.asserted_at, timestamp),
+		valid_from: validFrom,
+		invalidated_at: invalidatedAt && invalidatedAt >= validFrom ? invalidatedAt : void 0,
+		supersedes: normalizeOptionalString(patch.supersedes ?? parsed.supersedes),
+		superseded_by: normalizeOptionalString(patch.superseded_by ?? parsed.superseded_by),
+		source_session: typeof (patch.source_session ?? parsed.source_session) === "string" ? patch.source_session ?? parsed.source_session : void 0,
+		state,
+		source,
+		memory_layer: memoryLayer,
+		injected_count: clampCount(patch.injected_count ?? parsed.injected_count, 0),
+		last_injected_at: normalizeOptionalTimestamp(patch.last_injected_at ?? parsed.last_injected_at),
+		last_confirmed_use_at: normalizeOptionalTimestamp(patch.last_confirmed_use_at ?? parsed.last_confirmed_use_at),
+		bad_recall_count: clampCount(patch.bad_recall_count ?? parsed.bad_recall_count, 0),
+		suppressed_until_turn: clampCount(patch.suppressed_until_turn ?? parsed.suppressed_until_turn, 0),
+		canonical_id: normalizeOptionalString(patch.canonical_id ?? parsed.canonical_id),
+		memory_temporal_type: (patch.memory_temporal_type ?? parsed.memory_temporal_type) === "static" || (patch.memory_temporal_type ?? parsed.memory_temporal_type) === "dynamic" ? patch.memory_temporal_type ?? parsed.memory_temporal_type : void 0,
+		temporal_resolution_status: (patch.temporal_resolution_status ?? parsed.temporal_resolution_status) === "resolved" || (patch.temporal_resolution_status ?? parsed.temporal_resolution_status) === "unresolved" || (patch.temporal_resolution_status ?? parsed.temporal_resolution_status) === "static" ? patch.temporal_resolution_status ?? parsed.temporal_resolution_status : void 0,
+		temporal_phrase: normalizeOptionalString(patch.temporal_phrase ?? parsed.temporal_phrase),
+		valid_until: normalizeOptionalTimestamp(patch.valid_until ?? parsed.valid_until)
+	};
+	if (memoryCategory === "episodic") {
+		const dayUnknown = candidate.temporal_resolution_status === "unresolved" || candidate.temporal_resolution_status === "static" || [
+			"year",
+			"month",
+			"week"
+		].includes(String(candidate.temporal_precision));
+		if (candidate.temporal_resolution_status === "unresolved" || candidate.temporal_resolution_status === "static") {
+			delete candidate.valid_from;
+			delete candidate.valid_until;
+		}
+		candidate.event_at = normalizeEventTime(patch.event_at) ?? (dayUnknown ? void 0 : normalizeEventTime(parsed.event_at));
+		if (candidate.event_at === void 0 && candidate.temporal_date === void 0 && candidate.temporal_resolution_status === void 0) {
+			candidate.temporal_resolution_status = "unresolved";
+			delete candidate.valid_from;
+			delete candidate.valid_until;
+		}
+		candidate.entity_kind = normalizeOptionalString(patch.entity_kind ?? parsed.entity_kind);
+	}
+	if (memoryCategory === "profile") {
+		candidate.section_name = requireNonEmptyField(memoryCategory, "section_name", patch.section_name ?? parsed.section_name);
+		candidate.rawTopicPhrase = normalizeOptionalString(patch.rawTopicPhrase ?? parsed.rawTopicPhrase);
+	}
+	if (memoryCategory === "persona") candidate.section_name = requireNonEmptyField(memoryCategory, "section_name", patch.section_name ?? parsed.section_name);
+	if (memoryCategory === "lesson") candidate.anti_pattern_signature = requireNonEmptyField(memoryCategory, "anti_pattern_signature", patch.anti_pattern_signature ?? parsed.anti_pattern_signature);
+	if (memoryCategory === "summary") {
+		candidate.children_ids = patch.children_ids ?? parsed.children_ids;
+		candidate.depth = patch.depth ?? parsed.depth;
+	}
+	candidate.fact_key = deriveFactKey(candidate) ?? (memoryCategory === "episodic" ? normalizeOptionalString(patch.fact_key ?? parsed.fact_key) : void 0);
+	return parseNormalizedMetadata(candidate);
+}
+/** Parses insight metadata into the normalized shape expected by insight metadata parsing. */
+function parseInsightMetadata(rawMetadata, entry = {}) {
+	return normalizeInsightMetadata(parseRawMetadata(rawMetadata), entry);
+}
+/** Assembles insight metadata from validated inputs for deterministic insight metadata parsing. */
+function buildInsightMetadata(entry, patch = {}) {
+	return normalizeInsightMetadata(parseRawMetadata(entry.metadata), entry, patch);
+}
+const MAX_SOURCES = 20;
+const MAX_HISTORY = 50;
+const MAX_RELATIONS = 16;
+const DEFAULT_MERGE_LINEAGE_MAX = 32;
+function appendLineage(existing, additions, max = 32) {
+	const cap = Number.isInteger(max) && max > 0 ? max : 32;
+	const prior = Array.isArray(existing) ? existing.filter((item) => typeof item === "string" && item.length > 0) : [];
+	const appended = additions.filter((item) => item.length > 0);
+	return [...prior, ...appended].slice(-cap);
+}
+/**
+* Append a relation to an existing relations array, deduplicating by the
+* full triple (`source`, `type`, `targetId`). When `source` is absent the
+* parent record's `fact_key` is the implicit subject — two relations with
+* the same `(type, targetId)` and no explicit source are considered duplicates.
+*/
+function appendRelation(existing, relation) {
+	const rows = Array.isArray(existing) ? existing.filter((item) => !!item && typeof item === "object" && typeof item.type === "string" && typeof item.targetId === "string") : [];
+	const sameSource = (a, b) => (a.source ?? "") === (b.source ?? "");
+	if (rows.some((item) => item.type === relation.type && item.targetId === relation.targetId && sameSource(item, relation))) return rows;
+	return [...rows, relation];
+}
+/** Implements stringify insight metadata as the local insight metadata parsing operation. */
+function stringifyInsightMetadata(metadata) {
+	const capped = { ...metadata };
+	if (Array.isArray(capped.sources) && capped.sources.length > MAX_SOURCES) capped.sources = capped.sources.slice(-20);
+	if (Array.isArray(capped.history) && capped.history.length > MAX_HISTORY) capped.history = capped.history.slice(-50);
+	if (Array.isArray(capped.relations) && capped.relations.length > MAX_RELATIONS) capped.relations = capped.relations.slice(-16);
+	delete capped.memory_layer;
+	return JSON.stringify(capped);
+}
+//#endregion
+export { normalizeState as _, buildInsightMetadata as a, stringifyInsightMetadata as c, normalizeContext as d, parseSupportInfo as f, normalizeSource as g, deriveFactKey as h, appendRelation as i, MAX_SUPPORT_SLICES as l, deriveDefaultLayer as m, ExtractionError as n, isMemoryExpired as o, updateSupportStats as p, appendLineage as r, parseInsightMetadata as s, DEFAULT_MERGE_LINEAGE_MAX as t, SUPPORT_CONTEXT_VOCABULARY as u };

package/dist/memory-metadata-codec-DUvsYe_X.d.ts

@@ -0,0 +1,68 @@
+import { C as EntryLike, D as MemoryRelation, T as InsightMetadataPatch, h as MemoryCategory, w as InsightMetadata } from "./types-CWdhXLxr.js";
+//#region src/engine/extraction/memory-metadata-normalizers.d.ts
+type FactKeySource = {
+  kind: MemoryCategory;
+  section_name?: unknown;
+  anti_pattern_signature?: unknown;
+  active_task_kind?: unknown;
+  active_task_id?: unknown;
+};
+declare function deriveFactKey(metadata: FactKeySource): string | undefined;
+//#endregion
+//#region src/engine/extraction/memory-support-info.d.ts
+/** @file memory-support-info.ts
+ * @purpose Parses and updates contextual support statistics for memories.
+ * @boundary Support-info V2 vocabulary, parsing, and bounded updates only.
+ */
+declare const SUPPORT_CONTEXT_VOCABULARY: readonly ["general", "morning", "afternoon", "evening", "night", "weekday", "weekend", "work", "leisure", "summer", "winter", "travel"];
+type SupportContext = (typeof SUPPORT_CONTEXT_VOCABULARY)[number] | string;
+declare const MAX_SUPPORT_SLICES = 8;
+interface ContextualSupport {
+  context: SupportContext;
+  confirmations: number;
+  contradictions: number;
+  /** confirmations / (confirmations + contradictions) */
+  strength: number;
+  last_observed_at: number;
+}
+interface SupportInfoV2 {
+  /** Weighted average across all slices. */
+  global_strength: number;
+  /** Sum of all confirmations + contradictions. */
+  total_observations: number;
+  slices: ContextualSupport[];
+}
+/** Normalizes context at the boundary before insight metadata parsing uses it. */
+declare function normalizeContext(raw: string | undefined): SupportContext;
+/** Parses support info into the normalized shape used by insight metadata parsing. */
+declare function parseSupportInfo(raw: unknown): SupportInfoV2;
+/**
+ * Implements update support stats as the local insight metadata parsing
+ * operation. `at` is the observation event time (the session date when one is
+ * known); it defaults to the wall clock only when no session anchor exists.
+ */
+declare function updateSupportStats(existing: SupportInfoV2, contextLabel: string | undefined, event: "support" | "contradict", at?: number): SupportInfoV2;
+//#endregion
+//#region src/engine/extraction/memory-metadata-codec.d.ts
+declare class ExtractionError extends Error {
+  constructor(message: string);
+}
+/** Check if a memory has passed its temporal expiry (valid_until). */
+declare function isMemoryExpired(metadata: Pick<InsightMetadata, "valid_until" | "memory_category">, at?: number): boolean;
+/** Parses insight metadata into the normalized shape expected by insight metadata parsing. */
+declare function parseInsightMetadata(rawMetadata: string | undefined, entry?: EntryLike): InsightMetadata;
+/** Assembles insight metadata from validated inputs for deterministic insight metadata parsing. */
+declare function buildInsightMetadata(entry: EntryLike, patch?: InsightMetadataPatch): InsightMetadata;
+declare const DEFAULT_MERGE_LINEAGE_MAX = 32;
+declare function appendLineage(existing: unknown, additions: readonly string[], max?: number): string[];
+/**
+ * Append a relation to an existing relations array, deduplicating by the
+ * full triple (`source`, `type`, `targetId`). When `source` is absent the
+ * parent record's `fact_key` is the implicit subject — two relations with
+ * the same `(type, targetId)` and no explicit source are considered duplicates.
+ */
+declare function appendRelation(existing: unknown, relation: MemoryRelation): MemoryRelation[];
+/** Implements stringify insight metadata as the local insight metadata parsing operation. */
+declare function stringifyInsightMetadata(metadata: InsightMetadata | Record<string, unknown>): string;
+//#endregion
+export { deriveFactKey as _, buildInsightMetadata as a, stringifyInsightMetadata as c, SUPPORT_CONTEXT_VOCABULARY as d, SupportContext as f, updateSupportStats as g, parseSupportInfo as h, appendRelation as i, ContextualSupport as l, normalizeContext as m, ExtractionError as n, isMemoryExpired as o, SupportInfoV2 as p, appendLineage as r, parseInsightMetadata as s, DEFAULT_MERGE_LINEAGE_MAX as t, MAX_SUPPORT_SLICES as u };