@snoai/memory 0.0.0-stage → 1.0.0

package/dist/internal/engine/telemetry/memory-telemetry-api.js

@@ -0,0 +1,730 @@
+import "../../../signed-registry-constants-yq3DlG3B.js";
+import { u as runWithMemoryAuditSync } from "../../../runtime-audit-log-BCeujlEp.js";
+import { getSnoStationMemStateDir } from "../../contract/profile.js";
+import { n as loadMemoryTelemetryKeySet, t as createMemoryTelemetryReceiptService } from "../../../memory-telemetry-receipts-YsxbwOAf.js";
+import { t as validateMemoryTelemetryMetadata } from "../../../memory-telemetry-metadata-CA7W8tK6.js";
+//#region src/engine/telemetry/memory-telemetry-purge.ts
+const DELETE_BATCH_SIZE = 500;
+function createMemoryTelemetryPurgeService(options) {
+	return new DefaultMemoryTelemetryPurgeService(options.sqlite, options.agentId ?? "sno-mem-claw", options.canDeleteFact ?? (() => true));
+}
+var DefaultMemoryTelemetryPurgeService = class {
+	sqlite;
+	agentId;
+	canDeleteFact;
+	constructor(sqlite, agentId, canDeleteFact) {
+		this.sqlite = sqlite;
+		this.agentId = agentId;
+		this.canDeleteFact = canDeleteFact;
+	}
+	previewImpact(factId, _options = {}) {
+		return runWithMemoryAuditSync({
+			stateDir: getSnoStationMemStateDir(),
+			event: "memory_read",
+			operation: "previewImpact",
+			startedDetails: {
+				requested_fact_id: factId,
+				fact_ids: [factId],
+				requested_count: 1
+			},
+			run: () => this.buildPreview(normalizeRequired$1(factId, "fact_id")),
+			completedDetails: (preview) => ({
+				requested_fact_id: factId,
+				resolved_fact_id: preview.targetFactId,
+				fact_ids: preview.affectedFactIds,
+				requested_count: 1,
+				result_count: preview.affectedFactCount
+			})
+		});
+	}
+	confirmPurge(input) {
+		return runWithMemoryAuditSync({
+			stateDir: getSnoStationMemStateDir(),
+			event: "memory_purged",
+			operation: "confirmPurge",
+			startedDetails: { target_fact_id: input.factId },
+			run: () => this.confirmPurgeUnaudited(input),
+			completedDetails: (result) => ({
+				target_fact_id: result.targetFactId,
+				purged_fact_ids: result.purgedFactIds,
+				failed_fact_ids: result.failedFactIds,
+				status: result.status,
+				...result.blockedReason ? { blocked_reason: result.blockedReason } : {}
+			})
+		});
+	}
+	confirmPurgeUnaudited(input) {
+		const targetFactId = normalizeRequired$1(input.factId, "fact_id");
+		if (input.actor !== "operator") throw new Error("cascade purge confirmation requires an operator actor");
+		const expectedToken = `PURGE ${targetFactId}`;
+		if (input.confirmationToken !== expectedToken) throw new Error(`cascade purge confirmation token must equal '${expectedToken}'`);
+		return this.sqlite.transaction(() => {
+			const preview = this.buildPreview(targetFactId);
+			const anchor = this.readPurgeEventAnchor(targetFactId);
+			if (preview.blocked) {
+				const result = {
+					targetFactId,
+					status: "blocked",
+					purgedFactIds: [],
+					failedFactIds: preview.affectedFactIds,
+					blockedReason: "cycle_detected"
+				};
+				this.insertPurgeEvent(targetFactId, result, preview, anchor);
+				return result;
+			}
+			if (this.readRecentRecallCount(preview.affectedFactIds) > 0) {
+				const result = {
+					targetFactId,
+					status: "blocked",
+					purgedFactIds: [],
+					failedFactIds: preview.affectedFactIds,
+					blockedReason: "recent_recall"
+				};
+				this.insertPurgeEvent(targetFactId, result, preview, anchor);
+				return result;
+			}
+			const deletionCandidates = preview.affectedFactIds.filter((fact) => this.canDeleteFact(fact));
+			const purgedFactIds = this.deleteFacts(deletionCandidates);
+			const purgedFactIdSet = new Set(purgedFactIds);
+			const failedFactIds = preview.affectedFactIds.filter((fact) => !purgedFactIdSet.has(fact));
+			const result = {
+				targetFactId,
+				status: failedFactIds.length === 0 ? "complete" : "partial",
+				purgedFactIds,
+				failedFactIds
+			};
+			this.insertPurgeEvent(targetFactId, result, preview, anchor);
+			return result;
+		}).immediate();
+	}
+	buildPreview(targetFactId) {
+		const graph = this.buildForwardGraph();
+		if (!graph.knownFactIds.has(targetFactId)) throw new Error(`missing fact: fact_id=${targetFactId}`);
+		const traversal = traverseDownstream(targetFactId, graph.edges);
+		return {
+			targetFactId,
+			affectedFactIds: traversal.affectedFactIds,
+			downstreamFactIds: traversal.affectedFactIds.slice(1),
+			affectedFactCount: traversal.affectedFactIds.length,
+			recentRecallCount: this.readRecentRecallCount([targetFactId]),
+			affectedEpochIds: this.readAffectedEpochIds(traversal.affectedFactIds),
+			blocked: traversal.blocked,
+			...traversal.blocked ? { blockedReason: "cycle_detected" } : {}
+		};
+	}
+	buildForwardGraph() {
+		const memoryRows = this.sqlite.prepare("SELECT id, fact_id, category, project_id, derived_from FROM nodix_memories").all();
+		const graph = /* @__PURE__ */ new Map();
+		const knownFactIds = /* @__PURE__ */ new Set();
+		for (const row of memoryRows) {
+			const factId = row.fact_id ?? row.id;
+			knownFactIds.add(factId);
+			for (const parentFactId of parseFactIdArray(row.derived_from)) addEdge(graph, parentFactId, factId);
+			if (!graph.has(factId)) graph.set(factId, graph.get(factId) ?? []);
+		}
+		const eventRows = this.sqlite.prepare(`SELECT fact_id, memory_kind, project_id, derived_from
+				 FROM nodix_memory_events
+				 WHERE fact_id IS NOT NULL
+				   AND derived_from IS NOT NULL
+				 ORDER BY id ASC`).all();
+		for (const row of eventRows) {
+			if (!row.fact_id) continue;
+			knownFactIds.add(row.fact_id);
+			for (const parentFactId of parseFactIdArray(row.derived_from)) addEdge(graph, parentFactId, row.fact_id);
+			if (!graph.has(row.fact_id)) graph.set(row.fact_id, graph.get(row.fact_id) ?? []);
+		}
+		return {
+			edges: graph,
+			knownFactIds
+		};
+	}
+	deleteFacts(factIds) {
+		const purgedFactIds = [];
+		for (let i = 0; i < factIds.length; i += DELETE_BATCH_SIZE) {
+			const batchFactIds = factIds.slice(i, i + DELETE_BATCH_SIZE);
+			const batch = JSON.stringify(batchFactIds);
+			const memoryIds = this.sqlite.prepare("SELECT id FROM nodix_memories WHERE fact_id IN (SELECT value FROM json_each(?))").all(batch).map((row) => row.id);
+			this.deleteChunksByMemoryIds(memoryIds);
+			const deletedRows = this.sqlite.prepare(`DELETE FROM nodix_memories
+					 WHERE fact_id IN (SELECT value FROM json_each(?))
+					 RETURNING fact_id`).all(batch);
+			const deletedFactIds = new Set(deletedRows.flatMap((row) => row.fact_id === null ? [] : [row.fact_id]));
+			purgedFactIds.push(...batchFactIds.filter((factId) => deletedFactIds.has(factId)));
+		}
+		return purgedFactIds;
+	}
+	deleteChunksByMemoryIds(memoryIds) {
+		if (memoryIds.length === 0) return;
+		for (let i = 0; i < memoryIds.length; i += DELETE_BATCH_SIZE) {
+			const batch = JSON.stringify(memoryIds.slice(i, i + DELETE_BATCH_SIZE));
+			const chunkIds = this.sqlite.prepare("SELECT chunk_id FROM nodix_memory_chunks WHERE memory_id IN (SELECT value FROM json_each(?))").all(batch).map((row) => row.chunk_id);
+			for (let j = 0; j < chunkIds.length; j += DELETE_BATCH_SIZE) {
+				const chunkBatch = JSON.stringify(chunkIds.slice(j, j + DELETE_BATCH_SIZE));
+				this.sqlite.prepare("DELETE FROM nodix_memory_chunk_vectors WHERE id IN (SELECT value FROM json_each(?))").run(chunkBatch);
+			}
+			this.sqlite.prepare("DELETE FROM nodix_memory_chunks WHERE memory_id IN (SELECT value FROM json_each(?))").run(batch);
+		}
+	}
+	readRecentRecallCount(factIds) {
+		if (factIds.length === 0) return 0;
+		const batch = JSON.stringify(factIds);
+		return this.sqlite.prepare(`SELECT COUNT(*) AS count
+				 FROM nodix_memory_events
+				 WHERE event_type = 'recall'
+				   AND fact_id IN (SELECT value FROM json_each(?))
+				   AND timestamp_ms >= ?`).get(batch, Date.now() - 2592e6)?.count ?? 0;
+	}
+	readAffectedEpochIds(factIds) {
+		if (factIds.length === 0) return [];
+		const epochIds = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (let i = 0; i < factIds.length; i += DELETE_BATCH_SIZE) {
+			const batch = JSON.stringify(factIds.slice(i, i + DELETE_BATCH_SIZE));
+			const memoryRows = this.sqlite.prepare(`SELECT consolidation_epoch_id
+					 FROM nodix_memories
+					 WHERE fact_id IN (SELECT value FROM json_each(?))
+					   AND consolidation_epoch_id IS NOT NULL
+					 ORDER BY id ASC`).all(batch);
+			const eventRows = this.sqlite.prepare(`SELECT consolidation_epoch_id
+					 FROM nodix_memory_events
+					 WHERE fact_id IN (SELECT value FROM json_each(?))
+					   AND consolidation_epoch_id IS NOT NULL
+					 ORDER BY id ASC`).all(batch);
+			for (const row of [...memoryRows, ...eventRows]) {
+				if (!row.consolidation_epoch_id || seen.has(row.consolidation_epoch_id)) continue;
+				seen.add(row.consolidation_epoch_id);
+				epochIds.push(row.consolidation_epoch_id);
+			}
+		}
+		return epochIds;
+	}
+	insertPurgeEvent(targetFactId, result, preview, anchor) {
+		const metadata = validateMemoryTelemetryMetadata("purge", {
+			status: result.status,
+			affected_fact_count: preview.affectedFactCount,
+			purged_fact_ids: result.purgedFactIds,
+			failed_fact_ids: result.failedFactIds,
+			...result.blockedReason ? { blocked_reason: result.blockedReason } : {}
+		});
+		this.sqlite.prepare(`INSERT INTO nodix_memory_events
+				 (event_type, fact_id, memory_kind, timestamp_ms, agent_id, project_id, metadata_json)
+				 VALUES (?, ?, ?, ?, ?, ?, ?)`).run("purge", targetFactId, anchor.memoryKind, Date.now(), this.agentId, anchor.projectId, JSON.stringify(metadata));
+	}
+	readPurgeEventAnchor(targetFactId) {
+		const primary = this.sqlite.prepare("SELECT id, fact_id, category, project_id FROM nodix_memories WHERE fact_id = ? ORDER BY id ASC LIMIT 1").get(targetFactId);
+		if (primary) return {
+			memoryKind: primary.category,
+			projectId: primary.project_id
+		};
+		const event = this.sqlite.prepare(`SELECT memory_kind, project_id
+				 FROM nodix_memory_events
+				 WHERE fact_id = ?
+				 ORDER BY id DESC
+				 LIMIT 1`).get(targetFactId);
+		return {
+			memoryKind: event?.memory_kind ?? null,
+			projectId: event?.project_id ?? null
+		};
+	}
+};
+function addEdge(graph, parentFactId, childFactId) {
+	const children = graph.get(parentFactId) ?? [];
+	if (!children.includes(childFactId)) children.push(childFactId);
+	graph.set(parentFactId, children);
+}
+function traverseDownstream(targetFactId, graph) {
+	const affectedFactIds = [];
+	const visited = /* @__PURE__ */ new Set();
+	const active = /* @__PURE__ */ new Set();
+	let blocked = false;
+	function visit(factId) {
+		if (active.has(factId)) {
+			blocked = true;
+			return;
+		}
+		if (visited.has(factId)) return;
+		visited.add(factId);
+		active.add(factId);
+		affectedFactIds.push(factId);
+		const children = graph.get(factId) ?? [];
+		for (const child of children) visit(child);
+		active.delete(factId);
+	}
+	visit(targetFactId);
+	return {
+		affectedFactIds,
+		blocked
+	};
+}
+function parseFactIdArray(value) {
+	if (!value) return [];
+	try {
+		const parsed = JSON.parse(value);
+		if (!Array.isArray(parsed)) return [];
+		return parsed.filter((item) => typeof item === "string" && item.length > 0);
+	} catch {
+		return [];
+	}
+}
+function normalizeRequired$1(value, label) {
+	const normalized = value?.trim();
+	if (!normalized) throw new Error(`${label} is required`);
+	return normalized;
+}
+//#endregion
+//#region src/engine/telemetry/memory-telemetry-api.ts
+function createMemoryTelemetryApi(options) {
+	const receiptService = options.receiptService ?? createMemoryTelemetryReceiptService(options.keySet ?? loadMemoryTelemetryKeySet({
+		enabled: true,
+		key: options.key ?? "",
+		historicKeys: options.historicKeys ?? []
+	}));
+	const purgeService = createMemoryTelemetryPurgeService({
+		sqlite: options.sqlite,
+		agentId: options.agentId
+	});
+	return new DefaultMemoryTelemetryApi(options.sqlite, receiptService, purgeService);
+}
+var DefaultMemoryTelemetryApi = class {
+	sqlite;
+	receiptService;
+	purgeService;
+	constructor(sqlite, receiptService, purgeService) {
+		this.sqlite = sqlite;
+		this.receiptService = receiptService;
+		this.purgeService = purgeService;
+	}
+	verifyReceipt(factId) {
+		return runWithMemoryAuditSync({
+			stateDir: getSnoStationMemStateDir(),
+			event: "memory_read",
+			operation: "verifyReceipt",
+			startedDetails: {
+				requested_fact_id: factId,
+				fact_ids: [factId],
+				requested_count: 1
+			},
+			run: () => this.verifyReceiptUnaudited(factId),
+			completedDetails: (result) => ({
+				requested_fact_id: result.requestedFactId,
+				resolved_fact_id: result.terminalFactId,
+				fact_ids: [result.terminalFactId],
+				requested_count: 1,
+				result_count: 1,
+				outcome: result.status
+			})
+		});
+	}
+	verifyReceiptUnaudited(factId) {
+		const requestedFactId = normalizeRequired(factId, "fact_id");
+		const terminalFactId = this.resolveTerminalFactId(requestedFactId);
+		const receiptRows = this.readReceiptRows(terminalFactId);
+		if (receiptRows.length === 0) throw new Error(`missing fact receipt for fact_id=${requestedFactId}`);
+		const historicalReceipts = receiptRows.map((row) => this.verifyReceiptRow(row));
+		const latestReceipt = historicalReceipts[historicalReceipts.length - 1];
+		if (!latestReceipt) throw new Error(`missing fact receipt for fact_id=${requestedFactId}`);
+		const currentHash = this.readCurrentContentHash(terminalFactId);
+		const status = latestReceipt.status === "valid" && currentHash && currentHash !== latestReceipt.contentHash ? "tampered" : latestReceipt.status;
+		return {
+			status,
+			requestedFactId,
+			terminalFactId,
+			latestReceipt: {
+				...latestReceipt,
+				status
+			},
+			historicalReceipts
+		};
+	}
+	provenanceChain(factId, depth = 100) {
+		const normalizedFactId = normalizeRequired(factId, "fact_id");
+		const nodes = this.sqlite.prepare(`SELECT *
+				 FROM nodix_memory_events
+				 WHERE fact_id = ?
+				 ORDER BY id ASC
+				 LIMIT ?`).all(normalizedFactId, normalizeLimit(depth)).map((row) => ({
+			eventId: row.id,
+			eventType: parseEventType(row.event_type),
+			factId: row.fact_id,
+			timestampMs: row.timestamp_ms,
+			sourceEventId: row.source_event_id,
+			derivedFrom: parseStringArray(row.derived_from)
+		}));
+		return {
+			factId: normalizedFactId,
+			currentState: currentState(nodes),
+			nodes
+		};
+	}
+	editImpactPreview(factId, options) {
+		return this.purgeService.previewImpact(factId, options);
+	}
+	confirmPurge(input) {
+		return this.purgeService.confirmPurge(input);
+	}
+	usageSummary(input) {
+		if (!input.factId && !input.agentId) throw new Error("usage_summary requires fact_id or agent_id");
+		const committed = this.readCommittedUsage(input);
+		const pending = this.readPendingUsage(input);
+		return {
+			...input.factId ? { factId: input.factId } : {},
+			...input.agentId ? { agentId: input.agentId } : {},
+			recallCount: committed.recallCount + pending.recallCount,
+			injectionCount: committed.injectionCount + pending.injectionCount,
+			lastRecalledAt: maxNullable(committed.lastRecalledAt, pending.lastRecalledAt),
+			lastInjectedAt: maxNullable(committed.lastInjectedAt, pending.lastInjectedAt),
+			source: "local",
+			cloudForwarding: "ignored",
+			tenantBoundary: {
+				status: "unavailable",
+				queryTenantId: null,
+				resultTenantId: null
+			}
+		};
+	}
+	recallTrace(input) {
+		const sessionUuid = normalizeRequired(input.sessionUuid, "session_uuid");
+		const turnId = normalizeRequired(input.turnId, "turn_id");
+		const committed = this.sqlite.prepare(`SELECT *
+				 FROM nodix_memory_events
+				 WHERE event_type = 'recall'
+				   AND session_uuid = ?
+				   AND turn_id = ?
+				 ORDER BY timestamp_ms ASC, id ASC`).all(sessionUuid, turnId);
+		const pending = this.readPendingUsageRows({
+			sessionUuid,
+			turnId,
+			eventType: "recall"
+		});
+		return {
+			sessionUuid,
+			turnId,
+			events: [...committed.map((row) => ({
+				eventId: row.id,
+				factId: row.fact_id ?? "",
+				timestampMs: row.timestamp_ms,
+				rank: row.retrieval_rank,
+				score: row.retrieval_score,
+				agentId: row.agent_id,
+				projectId: row.project_id,
+				source: "nodix_memory_events"
+			})), ...pending.map((row) => ({
+				eventId: null,
+				factId: row.payload.fact_id,
+				timestampMs: row.acceptedAtMs,
+				rank: row.payload.retrieval_rank,
+				score: row.payload.retrieval_score,
+				agentId: row.payload.agent_id,
+				projectId: row.payload.project_id,
+				source: "nodix_memory_usage_outbox"
+			}))].sort((a, b) => a.timestampMs - b.timestampMs)
+		};
+	}
+	epochReport(epochId) {
+		const normalizedEpochId = normalizeRequired(epochId, "epoch_id");
+		const rows = this.sqlite.prepare(`SELECT *
+				 FROM nodix_memory_events
+				 WHERE consolidation_epoch_id = ?
+				 ORDER BY id ASC`).all(normalizedEpochId);
+		if (rows.length === 0) return {
+			epochId: normalizedEpochId,
+			status: "unavailable",
+			boundaryEvents: [],
+			createdFactIds: [],
+			supersededFactIds: []
+		};
+		const boundaryRows = rows.filter((row) => row.event_type === "epoch_boundary");
+		return {
+			epochId: normalizedEpochId,
+			status: boundaryRows.some((row) => readMetadata(row).subtype === "synthetic") ? "synthetic" : "real",
+			boundaryEvents: boundaryRows.map((row) => row.id),
+			createdFactIds: factIdsFor(rows, "create"),
+			supersededFactIds: factIdsFor(rows, "supersede")
+		};
+	}
+	resolveTerminalFactId(factId) {
+		const seen = /* @__PURE__ */ new Set();
+		let current = factId;
+		while (!seen.has(current)) {
+			seen.add(current);
+			const row = this.sqlite.prepare(`SELECT metadata_json
+					 FROM nodix_memory_events
+					 WHERE fact_id = ? AND event_type = 'supersede'
+					 ORDER BY id DESC
+					 LIMIT 1`).get(current);
+			const nextRowId = row ? readMetadata(row).superseded_by : void 0;
+			if (typeof nextRowId !== "string" || nextRowId.trim().length === 0) return current;
+			const nextFact = this.sqlite.prepare("SELECT fact_id FROM nodix_memories WHERE id = ? LIMIT 1").get(nextRowId);
+			if (!nextFact?.fact_id || nextFact.fact_id === current) return current;
+			current = nextFact.fact_id;
+		}
+		return current;
+	}
+	readReceiptRows(factId) {
+		return this.sqlite.prepare(`SELECT *
+				 FROM nodix_memory_events
+				 WHERE fact_id = ?
+				   AND event_type IN ('create', 'update')
+				   AND content_hash IS NOT NULL
+				   AND receipt_hmac IS NOT NULL
+				   AND key_version IS NOT NULL
+				 ORDER BY id ASC`).all(factId);
+	}
+	verifyReceiptRow(row) {
+		const factId = row.fact_id ?? "";
+		const contentHash = row.content_hash ?? "";
+		const timestampMs = row.timestamp_ms;
+		const receiptHmac = row.receipt_hmac ?? "";
+		const keyVersion = row.key_version ?? 0;
+		const verification = this.receiptService.verify({
+			factId,
+			contentHash,
+			timestampMs,
+			receiptHmac,
+			keyVersion
+		});
+		return {
+			eventId: row.id,
+			factId,
+			memoryRowId: this.readMemoryRowId(factId, contentHash),
+			contentHash,
+			timestampMs,
+			receiptHmac,
+			keyVersion,
+			status: verification.status
+		};
+	}
+	readMemoryRowId(factId, contentHash) {
+		return this.sqlite.prepare(`SELECT id
+				 FROM nodix_memories
+				 WHERE fact_id = ? AND content_hash = ?
+				 ORDER BY timestamp DESC
+				 LIMIT 1`).get(factId, contentHash)?.id ?? null;
+	}
+	readCurrentContentHash(factId) {
+		return this.sqlite.prepare(`SELECT id, fact_id, content_hash, timestamp
+				 FROM nodix_memories
+				 WHERE fact_id = ?
+				 ORDER BY timestamp DESC
+				 LIMIT 1`).get(factId)?.content_hash ?? null;
+	}
+	readCommittedUsage(input) {
+		const clauses = ["event_type IN ('recall', 'inject')"];
+		const params = [];
+		if (input.factId) {
+			clauses.push("fact_id = ?");
+			params.push(input.factId);
+		}
+		if (input.agentId) {
+			clauses.push("agent_id = ?");
+			params.push(input.agentId);
+		}
+		if (input.projectId) {
+			clauses.push("project_id = ?");
+			params.push(input.projectId);
+		}
+		addWindowClauses(clauses, params, "timestamp_ms", input.window);
+		return aggregateUsageRows(this.sqlite.prepare(`SELECT event_type, timestamp_ms
+				 FROM nodix_memory_events
+				 WHERE ${clauses.join(" AND ")}`).all(...params).map((row) => ({
+			eventType: row.event_type,
+			timestampMs: row.timestamp_ms
+		})));
+	}
+	readPendingUsage(input) {
+		return aggregateUsageRows(this.readPendingUsageRows({
+			factId: input.factId,
+			agentId: input.agentId,
+			projectId: input.projectId,
+			window: input.window
+		}).map((row) => ({
+			eventType: row.payload.event_type,
+			timestampMs: row.acceptedAtMs
+		})));
+	}
+	readPendingUsageRows(filter) {
+		const clauses = ["status IN ('pending', 'failed', 'flushing')"];
+		const params = [];
+		if (filter.eventType) {
+			clauses.push("event_type = ?");
+			params.push(filter.eventType);
+		}
+		addWindowClauses(clauses, params, "accepted_at_ms", filter.window);
+		return this.sqlite.prepare(`SELECT id, event_type, payload_json, accepted_at_ms
+				 FROM nodix_memory_usage_outbox
+				 WHERE ${clauses.join(" AND ")}
+				 ORDER BY accepted_at_ms ASC, id ASC`).all(...params).flatMap((row) => {
+			const payload = parseUsagePayload(row.payload_json);
+			if (!payload) return [];
+			if (this.hasCommittedUsage(payload, row.accepted_at_ms)) return [];
+			if (filter.factId && payload.fact_id !== filter.factId) return [];
+			if (filter.agentId && payload.agent_id !== filter.agentId) return [];
+			if (filter.projectId && payload.project_id !== filter.projectId) return [];
+			if (filter.sessionUuid && payload.session_uuid !== filter.sessionUuid) return [];
+			if (filter.turnId && payload.turn_id !== filter.turnId) return [];
+			return [{
+				id: row.id,
+				acceptedAtMs: row.accepted_at_ms,
+				payload
+			}];
+		});
+	}
+	hasCommittedUsage(payload, acceptedAtMs) {
+		const clauses = [
+			"event_type = ?",
+			"fact_id = ?",
+			"timestamp_ms = ?"
+		];
+		const params = [
+			payload.event_type,
+			payload.fact_id,
+			acceptedAtMs
+		];
+		addNullableMatchClause(clauses, params, "memory_kind", payload.memory_kind);
+		addNullableMatchClause(clauses, params, "agent_id", payload.agent_id);
+		addNullableMatchClause(clauses, params, "project_id", payload.project_id);
+		addNullableMatchClause(clauses, params, "session_uuid", payload.session_uuid);
+		addNullableMatchClause(clauses, params, "turn_id", payload.turn_id);
+		addNullableMatchClause(clauses, params, "retrieval_rank", payload.retrieval_rank);
+		addNullableMatchClause(clauses, params, "retrieval_score", payload.retrieval_score);
+		return this.sqlite.prepare(`SELECT COUNT(*) AS count FROM nodix_memory_events WHERE ${clauses.join(" AND ")}`).get(...params).count > 0;
+	}
+};
+function normalizeRequired(value, field) {
+	if (typeof value === "string" && value.trim().length > 0) return value.trim();
+	throw new Error(`${field} is required`);
+}
+function normalizeLimit(value) {
+	if (!Number.isFinite(value)) return 100;
+	return Math.max(1, Math.min(500, Math.floor(value)));
+}
+function parseEventType(value) {
+	switch (value) {
+		case "create":
+		case "update":
+		case "recall":
+		case "supersede":
+		case "delete":
+		case "inject":
+		case "epoch_boundary":
+		case "purge": return value;
+		default: throw new Error(`unknown memory telemetry event type: ${value}`);
+	}
+}
+function parseStringArray(value) {
+	if (!value) return [];
+	try {
+		const parsed = JSON.parse(value);
+		if (!Array.isArray(parsed)) return [];
+		return parsed.filter((item) => typeof item === "string");
+	} catch {
+		return [];
+	}
+}
+function readMetadata(row) {
+	if (!row.metadata_json) return {};
+	try {
+		const parsed = JSON.parse(row.metadata_json);
+		if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) return parsed;
+		return {};
+	} catch {
+		return {};
+	}
+}
+function currentState(nodes) {
+	const last = nodes[nodes.length - 1];
+	if (!last) return "missing";
+	if (last.eventType === "supersede") return "superseded";
+	if (last.eventType === "delete") return "deleted";
+	if (last.eventType === "purge") return "purged";
+	return "active";
+}
+function addWindowClauses(clauses, params, column, window) {
+	if (!window) return;
+	if (Number.isFinite(window.sinceMs)) {
+		clauses.push(`${column} >= ?`);
+		params.push(Number(window.sinceMs));
+	}
+	if (Number.isFinite(window.untilMs)) {
+		clauses.push(`${column} <= ?`);
+		params.push(Number(window.untilMs));
+	}
+}
+function addNullableMatchClause(clauses, params, column, value) {
+	if (value === null) {
+		clauses.push(`${column} IS NULL`);
+		return;
+	}
+	clauses.push(`${column} = ?`);
+	params.push(value);
+}
+function aggregateUsageRows(rows) {
+	let recallCount = 0;
+	let injectionCount = 0;
+	let lastRecalledAt = null;
+	let lastInjectedAt = null;
+	for (const row of rows) {
+		if (row.eventType === "recall") {
+			recallCount += 1;
+			lastRecalledAt = maxNullable(lastRecalledAt, row.timestampMs);
+		}
+		if (row.eventType === "inject") {
+			injectionCount += 1;
+			lastInjectedAt = maxNullable(lastInjectedAt, row.timestampMs);
+		}
+	}
+	return {
+		recallCount,
+		injectionCount,
+		lastRecalledAt,
+		lastInjectedAt
+	};
+}
+function maxNullable(left, right) {
+	if (left === null) return right;
+	if (right === null) return left;
+	return Math.max(left, right);
+}
+function parseUsagePayload(payloadJson) {
+	try {
+		const parsed = JSON.parse(payloadJson);
+		if (!isRecord(parsed)) return null;
+		if (parsed.event_type !== "recall" && parsed.event_type !== "inject") return null;
+		const factId = requiredString(parsed.fact_id);
+		const memoryKind = requiredString(parsed.memory_kind);
+		if (!factId || !memoryKind) return null;
+		return {
+			event_type: parsed.event_type,
+			fact_id: factId,
+			memory_kind: memoryKind,
+			project_id: nullableString(parsed.project_id),
+			agent_id: nullableString(parsed.agent_id),
+			session_uuid: nullableString(parsed.session_uuid),
+			turn_id: nullableString(parsed.turn_id),
+			retrieval_rank: nullableNumber(parsed.retrieval_rank),
+			retrieval_score: nullableNumber(parsed.retrieval_score)
+		};
+	} catch {
+		return null;
+	}
+}
+function factIdsFor(rows, eventType) {
+	return rows.flatMap((row) => row.event_type === eventType && row.fact_id ? [row.fact_id] : []);
+}
+function requiredString(value) {
+	if (typeof value === "string" && value.trim().length > 0) return value;
+	return null;
+}
+function nullableString(value) {
+	if (value === null || value === void 0) return null;
+	return typeof value === "string" ? value : null;
+}
+function nullableNumber(value) {
+	if (value === null || value === void 0) return null;
+	return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+export { createMemoryTelemetryApi };