@snoai/memory 0.0.0-stage → 1.0.1

package/dist/memory-store-shared-DqpWJXZZ.js

@@ -0,0 +1,158 @@
+import "./internal/config/index.js";
+import { Ct as PERSISTED_CONTENT_HASH_V3, St as PERSISTED_CONTENT_HASH_V1 } from "./signed-registry-constants-yq3DlG3B.js";
+import { StorageError } from "./internal/engine/shared/errors.js";
+import "./internal/engine/shared/utils.js";
+import "./connection-C9YD5sgm.js";
+import { CHUNKING_VERSION, aggregateChunksToMemories, buildChunkId, buildDensePayload, chunk as chunk$1, expandSnippetWindow, extractMetadataHeader, headExtract, shouldDropSummary } from "@snoai/chunking";
+import { createLogger } from "@snoai/utils/logger";
+import { randomUUID as randomUUID$1 } from "node:crypto";
+import { Mutex as Mutex$1 } from "async-mutex";
+//#region src/engine/shared/ambient-capture-hash.ts
+function normalizeAmbientCaptureHashMetadata(metadata) {
+	return {
+		source: metadata.source,
+		role: metadata.role,
+		...metadata.session_key ? { session_key: metadata.session_key } : {},
+		...metadata.session_id ? { session_id: metadata.session_id } : {},
+		chunk_index: metadata.chunk_index,
+		chunk_count: metadata.chunk_count,
+		chunking_version: metadata.chunking_version,
+		content_type: metadata.content_type
+	};
+}
+function buildAmbientCaptureHashInput(text, metadata) {
+	return JSON.stringify([
+		"sno-station-mem:ambient-chunk:v1",
+		text,
+		normalizeAmbientCaptureHashMetadata(metadata)
+	]);
+}
+function readAmbientCaptureHashMetadata(metadata) {
+	if (metadata.source !== "agent_end") return void 0;
+	if (metadata.role !== "user" && metadata.role !== "assistant") return void 0;
+	if (typeof metadata.chunk_index !== "number") return void 0;
+	if (typeof metadata.chunk_count !== "number") return void 0;
+	if (typeof metadata.chunking_version !== "string") return void 0;
+	if (metadata.content_type !== "conversation" && metadata.content_type !== "prose" && metadata.content_type !== "structured") return;
+	return {
+		source: metadata.source,
+		role: metadata.role,
+		...typeof metadata.session_key === "string" ? { session_key: metadata.session_key } : {},
+		...typeof metadata.session_id === "string" ? { session_id: metadata.session_id } : {},
+		chunk_index: metadata.chunk_index,
+		chunk_count: metadata.chunk_count,
+		chunking_version: metadata.chunking_version,
+		content_type: metadata.content_type
+	};
+}
+//#endregion
+//#region src/store/memory-store-shared.ts
+/** @file memory-store-shared.ts
+* @purpose Implements memory persistence, search, updates, deletion, and statistics.
+* @boundary SQLite schema, embedding vectors, FTS, and metadata invariants.
+* @see connection.ts, schema.ts, retriever.ts.
+*/
+const log = createLogger("sno-station-mem:store");
+/**
+* Reflection v3: discriminator added to content-hash input when the
+* row carries a `metadata.mappedKind`. Two rows with same projectId + same store
+* category + same text but distinct mappedKinds (e.g. user-model vs
+* agent-model both → category=preference) must coexist as distinct rows. The
+* SQL UNIQUE index `(projectId, content_hash, category)` cannot key on metadata
+* JSON; mixing mappedKind into the hash input solves it without a schema
+* change. Non-reflection callers pass undefined/missing mappedKind, get the
+* legacy text-only hash.
+*/
+function hashInputForEntry(text, metadata) {
+	if (!metadata) return text;
+	let parsed;
+	try {
+		parsed = JSON.parse(metadata);
+	} catch {
+		return text;
+	}
+	const ambientCaptureMetadata = readAmbientCaptureHashMetadata(parsed);
+	if (ambientCaptureMetadata) return buildAmbientCaptureHashInput(text, ambientCaptureMetadata);
+	const mergeLineage = Array.isArray(parsed.merge_lineage) ? parsed.merge_lineage.filter((item) => typeof item === "string") : [];
+	if (mergeLineage.length > 0) return JSON.stringify([
+		PERSISTED_CONTENT_HASH_V1,
+		text,
+		{ merge_lineage: mergeLineage }
+	]);
+	const contentIdentityKey = parsed.content_identity_key;
+	if (typeof contentIdentityKey === "string" && contentIdentityKey.length > 0) return JSON.stringify([
+		PERSISTED_CONTENT_HASH_V3,
+		text,
+		{ content_identity_key: contentIdentityKey }
+	]);
+	const mappedKind = parsed.mappedKind;
+	if (typeof mappedKind !== "string" || mappedKind.length === 0) return text;
+	return JSON.stringify([
+		PERSISTED_CONTENT_HASH_V1,
+		text,
+		mappedKind
+	]);
+}
+function valuesDiffer(left, right) {
+	return JSON.stringify(left) !== JSON.stringify(right);
+}
+function metadataRecord(metadata) {
+	const record = {};
+	for (const key of Object.keys(metadata)) record[key] = Reflect.get(metadata, key);
+	return record;
+}
+function readNonEmptyString(metadata, key) {
+	const value = Reflect.get(metadata, key);
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function readMergeLineage(metadata) {
+	const value = Reflect.get(metadata, "merge_lineage");
+	if (!Array.isArray(value)) return void 0;
+	const lineage = value.filter((item) => typeof item === "string");
+	return lineage.length > 0 ? lineage : void 0;
+}
+function projectHashSignificantMetadata(metadata) {
+	const record = metadataRecord(metadata);
+	return {
+		idempotency_key: readNonEmptyString(record, "idempotency_key"),
+		content_identity_key: readNonEmptyString(record, "content_identity_key"),
+		ambient_capture: readAmbientCaptureHashMetadata(record),
+		merge_lineage: readMergeLineage(record),
+		mappedKind: readNonEmptyString(record, "mappedKind")
+	};
+}
+function changedHashSignificantMetadataKeys(current, next) {
+	const currentProjection = projectHashSignificantMetadata(current);
+	const nextProjection = projectHashSignificantMetadata(next);
+	const changed = [];
+	if (valuesDiffer(currentProjection.idempotency_key, nextProjection.idempotency_key)) changed.push("idempotency_key");
+	if (valuesDiffer(currentProjection.content_identity_key, nextProjection.content_identity_key)) changed.push("content_identity_key");
+	if (valuesDiffer(currentProjection.ambient_capture, nextProjection.ambient_capture)) changed.push("ambient_capture");
+	if (valuesDiffer(currentProjection.merge_lineage, nextProjection.merge_lineage)) changed.push("merge_lineage");
+	if (valuesDiffer(currentProjection.mappedKind, nextProjection.mappedKind)) changed.push("mappedKind");
+	return changed;
+}
+function assertMetadataOnlyUpdatePreservesHashInput(operation, current, next) {
+	const changedKeys = changedHashSignificantMetadataKeys(current, next);
+	if (changedKeys.length === 0) return;
+	throw new StorageError(`${operation} cannot change hash-significant metadata through metadata-only update: ${changedKeys.join(", ")}`);
+}
+/**
+* Batch bound for `IN (SELECT value FROM json_each(?))` id lists. json_each removes
+* the 999-placeholder ceiling and keeps SQL strings stable for the per-connection
+* statement cache; the slice is a defensive bound on single-statement argument size.
+*/
+const JSON_ID_BATCH_SIZE = 5e3;
+const CHUNK_BACKFILL_RETRY_BASE_MS = 3e4;
+const CHUNK_BACKFILL_FAILURE_RESET_MS = CHUNK_BACKFILL_RETRY_BASE_MS * 10;
+function withStoreWriteOutcome(entry, outcome) {
+	Object.defineProperty(entry, "storeWriteOutcome", {
+		value: outcome,
+		enumerable: false,
+		configurable: false,
+		writable: false
+	});
+	return entry;
+}
+//#endregion
+export { shouldDropSummary as _, Mutex$1 as a, buildChunkId as c, expandSnippetWindow as d, extractMetadataHeader as f, randomUUID$1 as g, log as h, JSON_ID_BATCH_SIZE as i, buildDensePayload as l, headExtract as m, CHUNK_BACKFILL_FAILURE_RESET_MS as n, aggregateChunksToMemories as o, hashInputForEntry as p, CHUNK_BACKFILL_RETRY_BASE_MS as r, assertMetadataOnlyUpdatePreservesHashInput as s, CHUNKING_VERSION as t, chunk$1 as u, withStoreWriteOutcome as v };

package/dist/memory-store-write-validation-B_hDG2zf.js

@@ -0,0 +1,243 @@
+import "./internal/config/index.js";
+import { MEMORY_CATEGORIES, normalizeCategory } from "./internal/engine/shared/types.js";
+import { StorageError } from "./internal/engine/shared/errors.js";
+import { a as buildInsightMetadata, c as stringifyInsightMetadata, s as parseInsightMetadata } from "./memory-metadata-codec-DL1sbJiN.js";
+import { c as b_profile_section_registry_default, i as getActiveSectionRegistry } from "./b-profile-section-dictionary-provider-BHkoNqgk.js";
+import { canToolWrite, canTrustedWrite } from "./internal/engine/shared/memory-kind-policy.js";
+import { countTokens } from "@snoai/chunking";
+import { createLogger } from "@snoai/utils/logger";
+import { Temporal } from "@js-temporal/polyfill";
+b_profile_section_registry_default.active_task_shape.projection_max_items;
+/**
+* The live task-shape bounds. Read per call, from the same activated registry
+* the section gate, matcher, and re-key already use, so a restored dictionary
+* cannot leave this module rendering to a stale bound while the rest of
+* extraction honours a newer one.
+*/
+function activeTaskShape() {
+	const shape = getActiveSectionRegistry().active_task_shape;
+	return {
+		maxItems: shape.projection_max_items,
+		titleMaxTokens: shape.projection_title_max_tokens
+	};
+}
+/**
+* Longest prefix of `text` costing at most `maxTokens`. Bounding the briefing
+* line by token cost rather than character count keeps the budget honest across
+* scripts: `countTokens` charges CJK roughly 2.5x what it charges Latin, so a
+* character bound would silently buy far more prompt for one script than the
+* other.
+*
+* Binary search is safe because `countTokens` never decreases as the substring
+* is extended, and searching over code points rather than UTF-16 units means a
+* cut can never split a surrogate pair.
+*
+* The result is right-trimmed, and that is load-bearing rather than cosmetic: a
+* prefix ending in whitespace renders a projection line with a trailing space,
+* the metadata codec trims `l2_content`, and the write validator's exact-text
+* check then fails and throws away the entire lifecycle write. Trimming can only
+* lower the token count, so the budget still holds.
+*/
+function boundActiveTaskTitle(text, maxTokens) {
+	if (countTokens(text) <= maxTokens) return text;
+	const codePoints = Array.from(text);
+	let low = 0;
+	let high = codePoints.length;
+	while (low < high) {
+		const mid = Math.ceil((low + high) / 2);
+		if (countTokens(codePoints.slice(0, mid).join("")) <= maxTokens) low = mid;
+		else high = mid - 1;
+	}
+	return codePoints.slice(0, low).join("").trimEnd();
+}
+function buildActiveTaskProjection(tasks) {
+	const { maxItems, titleMaxTokens } = activeTaskShape();
+	const selected = tasks.filter((task) => task.status === "active").toSorted((left, right) => left.createdAt - right.createdAt || left.id.localeCompare(right.id)).slice(0, maxItems);
+	const taskIds = selected.map((task) => task.id);
+	const titles = selected.map((task) => {
+		return boundActiveTaskTitle(task.description.replace(/\s+/gu, " ").trim(), titleMaxTokens);
+	});
+	return {
+		taskIds,
+		titles,
+		text: titles.length === 0 ? "Active tasks: none" : `Active tasks:\n${titles.map((title) => `- ${title}`).join("\n")}`
+	};
+}
+//#endregion
+//#region src/engine/extraction/b-profile-section-canonicalizer.ts
+/** @file b-profile-section-canonicalizer.ts
+* @purpose Canonicalizes the written form of open B-profile section keys.
+* @boundary Pure deterministic transform; no registry lookup, I/O, or rejection.
+*/
+const DOMAIN_ALIASES = /* @__PURE__ */ new Map([
+	["interests", "preferences"],
+	["goals", "preferences"],
+	["work", "preferences"]
+]);
+const GENERAL_SECTION = "preferences.general";
+function canonicalizeProfileSectionName(sectionName) {
+	const normalized = normalizeProfileSectionForm(sectionName);
+	if (!normalized) return GENERAL_SECTION;
+	if (normalized.split(".").some((segment) => !segment)) return GENERAL_SECTION;
+	const separator = normalized.indexOf(".");
+	if (separator < 0) return normalized;
+	const domain = normalized.slice(0, separator);
+	const topic = normalized.slice(separator + 1);
+	const canonicalDomain = DOMAIN_ALIASES.get(domain) ?? domain;
+	return topic ? `${canonicalDomain}.${topic}` : canonicalDomain;
+}
+function normalizeProfileSectionForm(sectionName) {
+	return sectionName.normalize("NFKC").trim().toLowerCase().replace(/[-_\s]+/g, "_").replace(/^_+|_+$/g, "").replace(/_*\._*/g, ".");
+}
+//#endregion
+//#region src/store/memory-store-write-validation.ts
+/** @file memory-store-write-validation.ts
+* @purpose Validates and normalizes memory-kind metadata before direct store writes.
+* @boundary Storage write chokepoint only; extraction owns metadata semantics.
+*/
+const log = createLogger("sno-station-mem:active-task-shape-alarm");
+function validateAtomicCardWrite(input) {
+	if (input.category !== "state") return;
+	if (input.subject === null || !input.subject.startsWith("entity:") || input.subject.length === 7) throw new StorageError("state memory requires a non-empty entity subject");
+	if (Object.hasOwn(input.metadata ?? {}, "event_at")) throw new StorageError("state memory must not carry event_at");
+}
+function isFixedOffset(value) {
+	if (value.length !== 6 || value[0] !== "+" && value[0] !== "-" || value[3] !== ":") return false;
+	for (const index of [
+		1,
+		2,
+		4,
+		5
+	]) {
+		const code = value.charCodeAt(index);
+		if (code < 48 || code > 57) return false;
+	}
+	try {
+		Temporal.PlainDateTime.from("2000-01-01T00:00").toZonedDateTime(value);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function isIanaTimezone(value) {
+	try {
+		new Intl.DateTimeFormat("en-US", { timeZone: value });
+		return true;
+	} catch {
+		return false;
+	}
+}
+function hostTimezone() {
+	return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+function validateMemoryTimezone(value, operation) {
+	const timezone = value ?? hostTimezone();
+	if (timezone === "user" || isFixedOffset(timezone) || isIanaTimezone(timezone)) return timezone;
+	throw new StorageError(`${operation}: invalid memory timezone`);
+}
+function formatCause(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function shapeAlarm(operation, reason) {
+	log.error("Active task shape validation failed", {
+		operation,
+		reason_code: reason.replace(/[^a-z0-9]+/gi, "_").toLowerCase()
+	}, {
+		event_name: "sno_station_mem.memory-store-write-validation.active.task.shape.alarm",
+		file: "packages/memory/src/store/memory-store-write-validation.ts",
+		function: "shapeAlarm",
+		site_id: "memory-store-write-validation.shapeAlarm.3383666e9c"
+	});
+	throw new Error(`active-task shape alarm: ${reason}`);
+}
+function assertActiveTaskShape(metadata, input, operation) {
+	if (metadata.kind !== "profile" || metadata.section_name !== "active_tasks" || (input.lane ?? "active") !== "active") return;
+	if (metadata.active_task_kind === "projection") {
+		const { maxItems, titleMaxTokens } = activeTaskShape();
+		const ids = metadata.active_task_ids;
+		const titles = metadata.active_task_titles;
+		if (!Array.isArray(ids) || !Array.isArray(titles) || ids.length !== titles.length) shapeAlarm(operation, "projection ids and titles must be parallel arrays");
+		if (ids.length > maxItems) shapeAlarm(operation, "projection exceeds the item limit");
+		if (new Set(ids).size !== ids.length) shapeAlarm(operation, "projection contains duplicate task ids");
+		if (titles.some((title) => typeof title !== "string" || countTokens(title) > titleMaxTokens)) shapeAlarm(operation, "projection title exceeds the token limit");
+		const expectedText = titles.length === 0 ? "Active tasks: none" : `Active tasks:\n${titles.map((title) => `- ${title}`).join("\n")}`;
+		if (input.text !== expectedText || metadata.l2_content !== expectedText) shapeAlarm(operation, "projection text must exactly match its titles");
+		return;
+	}
+	if (metadata.active_task_kind !== "task") shapeAlarm(operation, "active-task domain rows must be a task or projection");
+	if (typeof metadata.active_task_id !== "string" || metadata.fact_key !== `profile:active_tasks:${metadata.active_task_id}` || metadata.active_task_origin === void 0 || metadata.active_task_status === void 0 || typeof metadata.active_task_created_at !== "number" || typeof metadata.active_task_transitioned_at !== "number" || !Array.isArray(metadata.active_task_lifecycle) || typeof metadata.l2_content !== "string" || metadata.l2_content.trim().length === 0) shapeAlarm(operation, "task row is missing required identity or lifecycle metadata");
+	const lifecycle = metadata.active_task_lifecycle;
+	const first = lifecycle[0];
+	const last = lifecycle[lifecycle.length - 1];
+	if (lifecycle.length < 1 || lifecycle.length > 2 || first?.from !== null || first.to !== "active" || first.at !== metadata.active_task_created_at || last?.to !== metadata.active_task_status || last.at !== metadata.active_task_transitioned_at) shapeAlarm(operation, "task lifecycle timestamps or endpoints are inconsistent");
+	if (lifecycle.length === 2 && (lifecycle[1]?.from !== "active" || lifecycle[1].to !== "completed" && lifecycle[1].to !== "removed")) shapeAlarm(operation, "task lifecycle transition is not allowed");
+	if (metadata.active_tasks !== void 0) shapeAlarm(operation, "task rows cannot carry an omnibus active_tasks array");
+}
+function assertLegalAxes(metadata, offlineFamily) {
+	if (metadata.state === "pending") throw new Error("state=pending is not writable");
+	if (offlineFamily) return;
+	if (!(metadata.kind === "profile" && metadata.state === "confirmed" && metadata.tier === "core" || metadata.kind === "episodic" && metadata.state === "confirmed" && (metadata.tier === "working" || metadata.tier === "peripheral"))) throw new Error(`forbidden live axes category=${metadata.kind} state=${metadata.state} tier=${metadata.tier}`);
+}
+/**
+* The exact record counter, ready to use. The embedder's tokenizer loads with its model, and
+* the OpenClaw skin registers without waiting for that load, so a write can arrive first;
+* `warmup()` is memoized and instant once the model is up, so every write door awaits it here
+* rather than throwing on the first capture after boot.
+*/
+async function recordTokenCounter(embedder) {
+	await embedder.warmup();
+	return (text) => embedder.countTokens(text);
+}
+/**
+* The record token ceiling, enforced at the store door. `countRecordTokens` is the
+* embedder's exact count (`Embedder.countTokens`), never a character estimate: the
+* embedder and the reranker both truncate silently past this size, so a longer record
+* would be indexed and ranked on its head only. Refusing is the honest outcome.
+*/
+function assertRecordWithinTokenCeiling(text, countRecordTokens, operation) {
+	const tokens = countRecordTokens(text);
+	if (tokens > 512) throw new StorageError(`${operation}: memory text is ${tokens} tokens; DEFAULT_MAX_CONTEXT_TOKENS is 512`);
+}
+function validateStoreWriteMetadata(input, operation, countRecordTokens) {
+	assertRecordWithinTokenCeiling(input.text, countRecordTokens, operation);
+	if (typeof input.category !== "string") throw new StorageError(`${operation}: memory category must be a string`);
+	const category = normalizeCategory(input.category);
+	if (!category) throw new StorageError(`${operation}: memory category must be one of ${MEMORY_CATEGORIES.join(", ")}`);
+	if (input.enforceWriteAuthority) {
+		if (!(input.offlineFamily === true || input.trusted === true && canTrustedWrite(category) || input.system !== true && input.trusted !== true && canToolWrite(category))) throw new StorageError(`${operation}: write authority for memory category "${category}" requires ${category === "profile" ? "a trusted store boundary" : "an offline-family store boundary with offline-family authority"}`);
+	}
+	try {
+		let metadata = input.metadata ?? void 0;
+		if (category === "profile" && metadata) try {
+			const raw = JSON.parse(metadata);
+			if (raw && typeof raw === "object" && typeof raw.section_name === "string") metadata = JSON.stringify({
+				...raw,
+				section_name: canonicalizeProfileSectionName(raw.section_name)
+			});
+		} catch {}
+		const entry = {
+			text: input.text,
+			category,
+			timestamp: input.timestamp,
+			metadata
+		};
+		const parsed = parseInsightMetadata(metadata, entry);
+		let normalized = parsed;
+		if (category === "profile") {
+			if (typeof parsed.section_name !== "string") throw new Error("profile metadata requires a string section_name");
+			normalized = buildInsightMetadata(entry, { section_name: canonicalizeProfileSectionName(parsed.section_name) });
+		}
+		if (normalized.kind !== category || normalized.memory_category !== category) throw new Error(`row/category/kind mismatch (entry=${category}, kind=${normalized.kind}, memory_category=${normalized.memory_category})`);
+		assertLegalAxes(normalized, input.offlineFamily === true);
+		assertActiveTaskShape(normalized, input, operation);
+		return {
+			category,
+			metadata: stringifyInsightMetadata(normalized),
+			timezone: validateMemoryTimezone(input.timezone, operation)
+		};
+	} catch (error) {
+		throw new StorageError(`${operation}: invalid memory metadata: ${formatCause(error)}`);
+	}
+}
+//#endregion
+export { validateStoreWriteMetadata as a, validateAtomicCardWrite as i, hostTimezone as n, canonicalizeProfileSectionName as o, recordTokenCounter as r, buildActiveTaskProjection as s, assertRecordWithinTokenCeiling as t };

package/dist/memory-telemetry-incidents-BWA9kcZx.js

@@ -0,0 +1,8 @@
+//#region src/engine/telemetry/memory-telemetry-incidents.ts
+function recordMemoryTelemetryIncident(sqlite, input) {
+	sqlite.prepare(`INSERT INTO nodix_memory_telemetry_incidents
+			 (incident_type, severity, message, payload_json, created_at_ms)
+			 VALUES (?, ?, ?, ?, ?)`).run(input.incidentType, input.severity, input.message, input.payload ? JSON.stringify(input.payload) : null, input.createdAtMs ?? Date.now());
+}
+//#endregion
+export { recordMemoryTelemetryIncident as t };

package/dist/memory-telemetry-metadata-CA7W8tK6.js

@@ -0,0 +1,77 @@
+import { isMemoryTelemetryEventType } from "./internal/engine/telemetry/memory-telemetry-types.js";
+//#region src/engine/telemetry/memory-telemetry-metadata.ts
+const RAW_CONTENT_KEYS = /* @__PURE__ */ new Set([
+	"text",
+	"content",
+	"l0_abstract",
+	"l1_overview",
+	"l2_content",
+	"chunk_text",
+	"dense_payload",
+	"summary"
+]);
+const METADATA_ALLOWED_KEYS = {
+	create: [
+		"operation_source",
+		"dedupe_status",
+		"content_hash",
+		"receipt_status"
+	],
+	update: [
+		"changed_keys",
+		"changed_lifecycle_keys",
+		"content_hash",
+		"receipt_hmac",
+		"key_version"
+	],
+	recall: [
+		"dense_score",
+		"bm25_score",
+		"fused_score",
+		"rerank_score",
+		"mmr_score",
+		"retrieval_rank",
+		"retrieval_score"
+	],
+	supersede: [
+		"superseded_by",
+		"supersedes",
+		"source_event_id",
+		"supersede_mode"
+	],
+	delete: ["delete_reason", "source_event_id"],
+	inject: [
+		"injection_surface",
+		"retrieval_rank",
+		"retrieval_score",
+		"source_agent_id"
+	],
+	epoch_boundary: [
+		"subtype",
+		"baseline_pre",
+		"baseline_post",
+		"scorer_version"
+	],
+	purge: [
+		"status",
+		"affected_fact_count",
+		"purged_fact_ids",
+		"failed_fact_ids",
+		"blocked_reason"
+	]
+};
+function validateMemoryTelemetryMetadata(eventType, metadata) {
+	if (!isMemoryTelemetryEventType(eventType)) throw new Error(`Unsupported memory telemetry event type: ${String(eventType)}`);
+	const allowedKeys = new Set(METADATA_ALLOWED_KEYS[eventType]);
+	for (const key of Object.keys(metadata)) {
+		if (RAW_CONTENT_KEYS.has(key)) throw new Error(`Memory telemetry metadata must not contain raw content key: ${key}`);
+		if (!allowedKeys.has(key)) throw new Error(`Memory telemetry metadata key '${key}' is not allowed for ${eventType}`);
+	}
+	if (eventType === "delete") {
+		const deleteReason = metadata.delete_reason;
+		if (typeof deleteReason !== "string" || deleteReason.trim().length === 0) throw new Error("delete metadata requires a non-empty delete_reason");
+	}
+	return metadata;
+}
+//#endregion
+export { validateMemoryTelemetryMetadata as t };

package/dist/memory-telemetry-outbox-ddTdImt7.d.ts

@@ -0,0 +1,74 @@
+import { r as SqliteDatabaseLike } from "./sqlite-runtime-L_ywirTm.js";
+import { a as MemoryTelemetryMetadata } from "./memory-telemetry-types-CufVmrCs.js";
+//#region src/engine/telemetry/memory-telemetry-outbox.d.ts
+type MemoryTelemetryUsageEventType = "recall" | "inject";
+interface MemoryTelemetryUsageInput {
+  eventType: MemoryTelemetryUsageEventType;
+  factId: string;
+  memoryKind: string;
+  projectId: string;
+  agentId?: string;
+  sessionUuid?: string;
+  turnId?: string;
+  retrievalRank?: number;
+  retrievalScore?: number;
+  metadata: MemoryTelemetryMetadata;
+}
+interface MemoryTelemetryUsageSummary {
+  recall: number;
+  inject: number;
+  pendingRecall: number;
+  pendingInject: number;
+  committedRecall: number;
+  committedInject: number;
+}
+interface MemoryTelemetryFlushResult {
+  selected: number;
+  inserted: number;
+  deleted: number;
+  failed: number;
+}
+interface MemoryTelemetryUsageOutboxOptions {
+  sqlite: SqliteDatabaseLike;
+  dbPath: string;
+  agentId?: string;
+  batchSize?: number;
+}
+declare class MemoryTelemetryUsageOutbox {
+  private readonly sqlite;
+  private readonly dbPath;
+  private readonly agentId;
+  private readonly batchSize;
+  private readonly insertUsageStatement;
+  constructor(options: MemoryTelemetryUsageOutboxOptions);
+  acceptUsage(input: MemoryTelemetryUsageInput): void;
+  tryAcceptUsage(input: MemoryTelemetryUsageInput): boolean;
+  usageSummary(factId: string): MemoryTelemetryUsageSummary;
+  flushPending(batchSize?: number): MemoryTelemetryFlushResult;
+  /**
+   * Bounded catch-up drain: flush batches until a pass claims zero rows or the
+   * time budget is exhausted. Used by the hourly maintenance tick and shutdown so
+   * a historical backlog drains across passes without monopolizing the writer.
+   */
+  drainPending(budgetMs?: number): MemoryTelemetryFlushResult;
+  /**
+   * Deletes quarantined rows older than the cutoff. Portable batched shape
+   * (`DELETE ... LIMIT` is a compile-option extension — never assume it).
+   */
+  pruneQuarantined(cutoffMs: number): number;
+  flushPendingAsync(batchSize?: number): Promise<MemoryTelemetryFlushResult>;
+  private countCommitted;
+  private countPending;
+  private claimFlushRows;
+  private readFlushCandidates;
+  private claimRow;
+  /** Parses and validates a claimed row; throws PermanentUsageOutboxRowError on bad payloads. */
+  private parseValidatedPayload;
+  private insertEvent;
+  private deleteClaimedRow;
+  private markRowsFailed;
+  private quarantineClaimedRow;
+  private recordQuarantineIncident;
+}
+//#endregion
+export { MemoryTelemetryUsageSummary as a, MemoryTelemetryUsageOutboxOptions as i, MemoryTelemetryUsageInput as n, MemoryTelemetryUsageOutbox as r, MemoryTelemetryFlushResult as t };

package/dist/memory-telemetry-receipts-MAJecvXQ.d.ts

@@ -0,0 +1,34 @@
+import { o as MemoryTelemetryReceiptStatus } from "./memory-telemetry-types-CufVmrCs.js";
+//#region src/engine/telemetry/memory-telemetry-config.d.ts
+interface MemoryTelemetryKey {
+  version: number;
+  key: string;
+}
+interface MemoryTelemetryKeySet {
+  enabled: boolean;
+  current: MemoryTelemetryKey | null;
+  historic: Map<number, string>;
+}
+//#endregion
+//#region src/engine/telemetry/memory-telemetry-receipts.d.ts
+interface MemoryTelemetryReceiptInput {
+  factId: string;
+  contentHash: string;
+  timestampMs: number;
+}
+interface MemoryTelemetryReceipt extends MemoryTelemetryReceiptInput {
+  receiptHmac: string;
+  keyVersion: number;
+}
+interface MemoryTelemetryReceiptVerification {
+  status: MemoryTelemetryReceiptStatus;
+  contentHash: string;
+  timestampMs: number;
+  keyVersion: number;
+}
+interface MemoryTelemetryReceiptService {
+  sign(input: MemoryTelemetryReceiptInput): MemoryTelemetryReceipt;
+  verify(receipt: MemoryTelemetryReceipt): MemoryTelemetryReceiptVerification;
+}
+//#endregion
+export { MemoryTelemetryKeySet as n, MemoryTelemetryReceiptService as t };