@snoai/memory 0.0.0-stage → 1.0.0

package/dist/internal/engine/telemetry/memory-telemetry-observability.d.ts

@@ -0,0 +1,24 @@
+import { r as SqliteDatabaseLike } from "../../../sqlite-runtime-L_ywirTm.js";
+import { JsonObject } from "@snoai/observability";
+//#region src/engine/telemetry/memory-telemetry-observability.d.ts
+export interface MemoryTelemetryObserveEmitInput {
+  eventType: "memory.telemetry";
+  payload: JsonObject;
+}
+export interface MemoryTelemetryObserveSink {
+  tryEmit(input: MemoryTelemetryObserveEmitInput): boolean | Promise<boolean>;
+}
+export interface ForwardMemoryTelemetryToObserveOptions {
+  sqlite: SqliteDatabaseLike;
+  observe: MemoryTelemetryObserveSink;
+  sink?: string;
+  batchSize?: number;
+  nowMs?: number;
+}
+export interface MemoryTelemetryObserveForwardResult {
+  status: "idle" | "forwarded" | "failed";
+  forwarded: number;
+  lastEventId: number;
+}
+export declare function forwardMemoryTelemetryToObserve(options: ForwardMemoryTelemetryToObserveOptions): Promise<MemoryTelemetryObserveForwardResult>;
+//#endregion

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

@@ -0,0 +1,133 @@
+import { isMemoryTelemetryEventType } from "./memory-telemetry-types.js";
+//#region src/engine/telemetry/memory-telemetry-observability.ts
+const DEFAULT_SINK = "sno-observe";
+const MAX_BATCH_SIZE = 50;
+async function forwardMemoryTelemetryToObserve(options) {
+	const sink = normalizeSink(options.sink);
+	const lastEventId = readWatermark(options.sqlite, sink);
+	const rows = readRows(options.sqlite, lastEventId, normalizeBatchSize(options.batchSize));
+	if (rows.length === 0) return {
+		status: "idle",
+		forwarded: 0,
+		lastEventId
+	};
+	const firstRow = rows[0];
+	const lastRow = rows[rows.length - 1];
+	if (!firstRow || !lastRow) return {
+		status: "idle",
+		forwarded: 0,
+		lastEventId
+	};
+	const nextEventId = lastRow.id;
+	const payload = buildPayload(rows, firstRow.id, nextEventId);
+	try {
+		if (!await options.observe.tryEmit({
+			eventType: "memory.telemetry",
+			payload
+		})) return {
+			status: "failed",
+			forwarded: 0,
+			lastEventId
+		};
+		writeWatermark(options.sqlite, sink, nextEventId, options.nowMs ?? Date.now());
+		return {
+			status: "forwarded",
+			forwarded: rows.length,
+			lastEventId: nextEventId
+		};
+	} catch {
+		return {
+			status: "failed",
+			forwarded: 0,
+			lastEventId
+		};
+	}
+}
+function readWatermark(sqlite, sink) {
+	const row = sqlite.prepare("SELECT last_event_id FROM nodix_memory_telemetry_sync_state WHERE sink = ?").get(sink);
+	return typeof row?.last_event_id === "number" ? row.last_event_id : 0;
+}
+function readRows(sqlite, lastEventId, batchSize) {
+	return sqlite.prepare(`SELECT id, event_type, fact_id, memory_kind, timestamp_ms, session_uuid, turn_id,
+			        agent_id, project_id, content_hash, retrieval_rank, retrieval_score,
+			        consolidation_epoch_id, metadata_json
+			 FROM nodix_memory_events
+			 WHERE id > ?
+			 ORDER BY id ASC
+			 LIMIT ?`).all(lastEventId, batchSize);
+}
+function buildPayload(rows, firstEventId, lastEventId) {
+	const eventTypes = {};
+	const events = rows.map((row) => {
+		const eventType = parseEventType(row.event_type);
+		eventTypes[eventType] = typeof eventTypes[eventType] === "number" ? eventTypes[eventType] + 1 : 1;
+		return sanitizeEvent(row, eventType);
+	});
+	return {
+		sync_kind: "memory_events",
+		first_event_id: firstEventId,
+		last_event_id: lastEventId,
+		event_count: events.length,
+		event_types: eventTypes,
+		events
+	};
+}
+function sanitizeEvent(row, eventType) {
+	const event = {
+		event_id: row.id,
+		event_type: eventType,
+		timestamp_ms: row.timestamp_ms,
+		agent_id: row.agent_id
+	};
+	addString(event, "fact_id", row.fact_id);
+	addString(event, "memory_kind", row.memory_kind);
+	addString(event, "session_uuid", row.session_uuid);
+	addString(event, "turn_id", row.turn_id);
+	addString(event, "project_id", row.project_id);
+	addString(event, "content_hash", row.content_hash);
+	addNumber(event, "retrieval_rank", row.retrieval_rank);
+	addNumber(event, "retrieval_score", row.retrieval_score);
+	addString(event, "consolidation_epoch_id", row.consolidation_epoch_id);
+	addString(event, "status", readMetadataString(row.metadata_json, "status"));
+	if (eventType === "inject") addString(event, "source_agent_id", readMetadataString(row.metadata_json, "source_agent_id"));
+	return event;
+}
+function readMetadataString(metadataJson, key) {
+	if (!metadataJson) return null;
+	try {
+		const parsed = JSON.parse(metadataJson);
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+		const value = parsed[key];
+		return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+	} catch {
+		return null;
+	}
+}
+function writeWatermark(sqlite, sink, lastEventId, updatedAtMs) {
+	sqlite.prepare(`INSERT INTO nodix_memory_telemetry_sync_state (sink, last_event_id, updated_at_ms)
+			 VALUES (?, ?, ?)
+			 ON CONFLICT(sink) DO UPDATE SET
+			   last_event_id = excluded.last_event_id,
+			   updated_at_ms = excluded.updated_at_ms
+			 WHERE excluded.last_event_id > nodix_memory_telemetry_sync_state.last_event_id`).run(sink, lastEventId, updatedAtMs);
+}
+function parseEventType(value) {
+	if (isMemoryTelemetryEventType(value)) return value;
+	throw new Error(`unknown memory telemetry event type: ${value}`);
+}
+function normalizeSink(value) {
+	if (typeof value === "string" && value.trim().length > 0) return value.trim();
+	return DEFAULT_SINK;
+}
+function normalizeBatchSize(value) {
+	if (!Number.isFinite(value)) return MAX_BATCH_SIZE;
+	return Math.max(1, Math.min(MAX_BATCH_SIZE, Math.floor(Number(value))));
+}
+function addString(target, key, value) {
+	if (typeof value === "string" && value.trim().length > 0) target[key] = value.trim();
+}
+function addNumber(target, key, value) {
+	if (typeof value === "number" && Number.isFinite(value)) target[key] = value;
+}
+//#endregion
+export { forwardMemoryTelemetryToObserve };

package/dist/internal/engine/telemetry/memory-telemetry-outbox.d.ts

@@ -0,0 +1,2 @@
+import { a as MemoryTelemetryUsageSummary, i as MemoryTelemetryUsageOutboxOptions, n as MemoryTelemetryUsageInput, r as MemoryTelemetryUsageOutbox, t as MemoryTelemetryFlushResult } from "../../../memory-telemetry-outbox-ddTdImt7.js";
+export { MemoryTelemetryFlushResult, MemoryTelemetryUsageInput, MemoryTelemetryUsageOutbox, MemoryTelemetryUsageOutboxOptions, MemoryTelemetryUsageSummary };

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

@@ -0,0 +1,443 @@
+import "../../../signed-registry-constants-yq3DlG3B.js";
+import { t as validateMemoryTelemetryMetadata } from "../../../memory-telemetry-metadata-CA7W8tK6.js";
+import { t as recordMemoryTelemetryIncident } from "../../../memory-telemetry-incidents-BWA9kcZx.js";
+import { createLogger, privateLogReference } from "@snoai/utils/logger";
+//#region src/engine/telemetry/memory-telemetry-outbox.ts
+const DEFAULT_USAGE_OUTBOX_BATCH_SIZE = 50;
+const USAGE_OUTBOX_CLAIM_LEASE_MS = 6e4;
+const activeFlushes = /* @__PURE__ */ new Map();
+const log = createLogger("sno-station-mem:usage-outbox");
+var MemoryTelemetryUsageOutbox = class {
+	sqlite;
+	dbPath;
+	agentId;
+	batchSize;
+	insertUsageStatement;
+	constructor(options) {
+		this.sqlite = options.sqlite;
+		this.dbPath = options.dbPath;
+		this.agentId = options.agentId ?? "sno-mem-claw";
+		this.batchSize = options.batchSize ?? DEFAULT_USAGE_OUTBOX_BATCH_SIZE;
+		this.insertUsageStatement = this.sqlite.prepare(`INSERT INTO nodix_memory_usage_outbox
+			 (event_type, payload_json, accepted_at_ms, status, attempt_count)
+			 VALUES (?, ?, ?, 'pending', 0)`);
+	}
+	acceptUsage(input) {
+		const payload = normalizeUsageInput(input, this.agentId);
+		this.insertUsageStatement.run(payload.event_type, JSON.stringify(payload), Date.now());
+	}
+	tryAcceptUsage(input) {
+		try {
+			this.acceptUsage(input);
+			return true;
+		} catch (error) {
+			let incidentPersisted = false;
+			try {
+				recordMemoryTelemetryIncident(this.sqlite, {
+					incidentType: "memory_usage_outbox_accept_failed",
+					severity: "error",
+					message: "memory telemetry usage accept failed",
+					payload: {
+						event_type: input.eventType,
+						fact_id: input.factId,
+						error_code: "usage_accept_failed",
+						retry_state: "not_counted"
+					}
+				});
+				incidentPersisted = true;
+			} catch {}
+			log.warn("Memory usage queue acceptance failed", {
+				outcome: "failed",
+				error,
+				accepted_count: 0,
+				incident_persisted: incidentPersisted,
+				memory_id: input.factId,
+				operation: input.eventType,
+				store_reference: privateLogReference(this.dbPath)
+			}, {
+				event_name: "memory.usage.accept.failed",
+				file: "packages/memory/src/engine/telemetry/memory-telemetry-outbox.ts",
+				function: "MemoryTelemetryUsageOutbox.tryAcceptUsage",
+				site_id: "memory.usage.accept.failed"
+			});
+			return false;
+		}
+	}
+	usageSummary(factId) {
+		const committedRecall = this.countCommitted(factId, "recall");
+		const committedInject = this.countCommitted(factId, "inject");
+		const pendingRecall = this.countPending(factId, "recall");
+		const pendingInject = this.countPending(factId, "inject");
+		return {
+			recall: committedRecall + pendingRecall,
+			inject: committedInject + pendingInject,
+			pendingRecall,
+			pendingInject,
+			committedRecall,
+			committedInject
+		};
+	}
+	flushPending(batchSize = this.batchSize) {
+		const started = performance.now();
+		let rows;
+		try {
+			rows = this.claimFlushRows(batchSize);
+		} catch (error) {
+			log.warn("Memory usage queue claim failed", {
+				error,
+				outcome: "failed",
+				committed_count: 0,
+				duration_ms: performance.now() - started,
+				store_reference: privateLogReference(this.dbPath)
+			}, {
+				event_name: "memory.usage.flush.failed",
+				file: "packages/memory/src/engine/telemetry/memory-telemetry-outbox.ts",
+				function: "MemoryTelemetryUsageOutbox.flushPending",
+				site_id: "memory.usage.flush.claim_failed"
+			});
+			throw error;
+		}
+		if (rows.length === 0) {
+			log.debug("Memory usage queue has no pending rows", {
+				outcome: "empty_success",
+				selected_count: 0,
+				committed_count: 0,
+				duration_ms: performance.now() - started
+			}, {
+				event_name: "memory.usage.flush.completed",
+				file: "packages/memory/src/engine/telemetry/memory-telemetry-outbox.ts",
+				function: "MemoryTelemetryUsageOutbox.flushPending",
+				site_id: "memory.usage.flush.empty"
+			});
+			return {
+				selected: 0,
+				inserted: 0,
+				deleted: 0,
+				failed: 0
+			};
+		}
+		let inserted = 0;
+		let deleted = 0;
+		let failed = 0;
+		const quarantined = [];
+		let failingRow;
+		try {
+			this.sqlite.transaction(() => {
+				for (const row of rows) try {
+					const payload = this.parseValidatedPayload(row);
+					if (this.deleteClaimedRow(row) !== 1) continue;
+					this.insertEvent(row, payload);
+					deleted += 1;
+					inserted += 1;
+				} catch (error) {
+					if (error instanceof PermanentUsageOutboxRowError) {
+						const message = safeErrorMessage(error);
+						if (this.quarantineClaimedRow(row, message) === 1) {
+							failed += 1;
+							quarantined.push({
+								row,
+								message
+							});
+						}
+						continue;
+					}
+					failingRow = row;
+					throw error;
+				}
+			}).immediate();
+		} catch (error) {
+			inserted = 0;
+			deleted = 0;
+			failed = 0;
+			log.warn("Memory usage queue flush rolled back", {
+				error,
+				outcome: "failed",
+				selected_count: rows.length,
+				committed_count: 0,
+				deleted_count: 0,
+				quarantined_count: 0,
+				duration_ms: performance.now() - started,
+				store_reference: privateLogReference(this.dbPath)
+			}, {
+				event_name: "memory.usage.flush.failed",
+				file: "packages/memory/src/engine/telemetry/memory-telemetry-outbox.ts",
+				function: "MemoryTelemetryUsageOutbox.flushPending",
+				site_id: "memory.usage.flush.rollback"
+			});
+			if (failingRow) this.markRowsFailed([failingRow], safeErrorMessage(error));
+			throw error;
+		}
+		for (const entry of quarantined) this.recordQuarantineIncident(entry.row, entry.message);
+		log.info("Memory usage queue flush completed", {
+			outcome: failed > 0 ? "partial" : "success",
+			selected_count: rows.length,
+			committed_count: inserted,
+			deleted_count: deleted,
+			quarantined_count: failed,
+			duration_ms: performance.now() - started,
+			store_reference: privateLogReference(this.dbPath)
+		}, {
+			event_name: "memory.usage.flush.completed",
+			file: "packages/memory/src/engine/telemetry/memory-telemetry-outbox.ts",
+			function: "MemoryTelemetryUsageOutbox.flushPending",
+			site_id: "memory.usage.flush.completed"
+		});
+		return {
+			selected: rows.length,
+			inserted,
+			deleted,
+			failed
+		};
+	}
+	/**
+	* 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 = 3e4) {
+		const startedAt = Date.now();
+		const totals = {
+			selected: 0,
+			inserted: 0,
+			deleted: 0,
+			failed: 0
+		};
+		while (Date.now() - startedAt < budgetMs) {
+			const pass = this.flushPending();
+			totals.selected += pass.selected;
+			totals.inserted += pass.inserted;
+			totals.deleted += pass.deleted;
+			totals.failed += pass.failed;
+			if (pass.selected === 0) break;
+		}
+		return totals;
+	}
+	/**
+	* Deletes quarantined rows older than the cutoff. Portable batched shape
+	* (`DELETE ... LIMIT` is a compile-option extension — never assume it).
+	*/
+	pruneQuarantined(cutoffMs) {
+		let pruned = 0;
+		while (true) {
+			const changes = this.sqlite.prepare(`DELETE FROM nodix_memory_usage_outbox
+					 WHERE id IN (
+					   SELECT id FROM nodix_memory_usage_outbox
+					   WHERE status = 'quarantined' AND accepted_at_ms < ?
+					   LIMIT 5000
+					 )`).run(cutoffMs).changes ?? 0;
+			pruned += changes;
+			if (changes === 0) break;
+		}
+		return pruned;
+	}
+	flushPendingAsync(batchSize = this.batchSize) {
+		const active = activeFlushes.get(this.dbPath);
+		if (active) return active;
+		const promise = Promise.resolve().then(() => this.flushPending(batchSize)).finally(() => {
+			if (activeFlushes.get(this.dbPath) === promise) activeFlushes.delete(this.dbPath);
+		});
+		activeFlushes.set(this.dbPath, promise);
+		return promise;
+	}
+	countCommitted(factId, eventType) {
+		return this.sqlite.prepare("SELECT COUNT(*) AS count FROM nodix_memory_events WHERE fact_id = ? AND event_type = ?").get(factId, eventType).count;
+	}
+	countPending(factId, eventType) {
+		return this.sqlite.prepare(`SELECT COUNT(*) AS count
+				 FROM nodix_memory_usage_outbox
+				 WHERE event_type = ?
+				   AND status IN ('pending', 'failed', 'flushing')
+				   AND json_extract(payload_json, '$.fact_id') = ?`).get(eventType, factId).count;
+	}
+	claimFlushRows(batchSize) {
+		const now = Date.now();
+		const claimExpiresAt = now + USAGE_OUTBOX_CLAIM_LEASE_MS;
+		return this.sqlite.transaction(() => {
+			const candidates = this.readFlushCandidates(batchSize, now);
+			const claimed = [];
+			for (const row of candidates) if (this.claimRow(row.id, now, claimExpiresAt) === 1) claimed.push({
+				...row,
+				claim_expires_at_ms: claimExpiresAt
+			});
+			return claimed;
+		}).immediate();
+	}
+	readFlushCandidates(batchSize, now) {
+		return this.sqlite.prepare(`SELECT id, event_type, payload_json, accepted_at_ms, status
+				 FROM nodix_memory_usage_outbox
+				 WHERE (
+				     status IN ('pending', 'failed')
+				     AND (next_attempt_ms IS NULL OR next_attempt_ms <= ?)
+				   )
+				   OR (
+				     status = 'flushing'
+				     AND next_attempt_ms IS NOT NULL
+				     AND next_attempt_ms <= ?
+				   )
+				 ORDER BY id ASC
+				 LIMIT ?`).all(now, now, batchSize);
+	}
+	claimRow(id, now, claimExpiresAt) {
+		return this.sqlite.prepare(`UPDATE nodix_memory_usage_outbox
+				 SET status = 'flushing',
+				     last_error = NULL,
+				     next_attempt_ms = ?
+				 WHERE id = ?
+				   AND (
+				     (
+				       status IN ('pending', 'failed')
+				       AND (next_attempt_ms IS NULL OR next_attempt_ms <= ?)
+				     )
+				     OR (
+				       status = 'flushing'
+				       AND next_attempt_ms IS NOT NULL
+				       AND next_attempt_ms <= ?
+				     )
+				   )`).run(claimExpiresAt, id, now, now).changes ?? 0;
+	}
+	/** Parses and validates a claimed row; throws PermanentUsageOutboxRowError on bad payloads. */
+	parseValidatedPayload(row) {
+		const payload = parseUsagePayload(row);
+		try {
+			return {
+				...payload,
+				metadata_json: validateMemoryTelemetryMetadata(payload.event_type, payload.metadata_json)
+			};
+		} catch (error) {
+			if (error instanceof PermanentUsageOutboxRowError) throw error;
+			throw new PermanentUsageOutboxRowError(`nodix_memory_usage_outbox row ${row.id} has invalid metadata_json: ${safeErrorMessage(error)}`);
+		}
+	}
+	insertEvent(row, payload) {
+		const metadata = payload.metadata_json;
+		this.sqlite.prepare(`INSERT INTO nodix_memory_events
+				 (event_type, fact_id, memory_kind, timestamp_ms, agent_id, project_id,
+				  session_uuid, turn_id, retrieval_rank, retrieval_score, metadata_json)
+				 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(payload.event_type, payload.fact_id, payload.memory_kind, row.accepted_at_ms, payload.agent_id ?? this.agentId, payload.project_id, payload.session_uuid, payload.turn_id, payload.retrieval_rank, payload.retrieval_score, JSON.stringify(metadata));
+	}
+	deleteClaimedRow(row) {
+		return this.sqlite.prepare(`DELETE FROM nodix_memory_usage_outbox
+				 WHERE id = ?
+				   AND status = 'flushing'
+				   AND next_attempt_ms = ?`).run(row.id, row.claim_expires_at_ms).changes ?? 0;
+	}
+	markRowsFailed(rows, lastError) {
+		let changed = 0;
+		for (const row of rows) {
+			const result = this.sqlite.prepare(`UPDATE nodix_memory_usage_outbox
+					 SET status = 'failed',
+					     attempt_count = attempt_count + 1,
+					     last_error = ?,
+					     next_attempt_ms = NULL
+					 WHERE id = ?
+					   AND status = 'flushing'
+					   AND next_attempt_ms = ?`).run(lastError, row.id, row.claim_expires_at_ms);
+			changed += result.changes ?? 0;
+		}
+		return changed;
+	}
+	quarantineClaimedRow(row, lastError) {
+		return this.sqlite.prepare(`UPDATE nodix_memory_usage_outbox
+				 SET status = 'quarantined',
+				     attempt_count = attempt_count + 1,
+				     last_error = ?,
+				     next_attempt_ms = NULL
+				 WHERE id = ?
+				   AND status = 'flushing'
+				   AND next_attempt_ms = ?`).run(lastError, row.id, row.claim_expires_at_ms).changes ?? 0;
+	}
+	recordQuarantineIncident(row, lastError) {
+		try {
+			recordMemoryTelemetryIncident(this.sqlite, {
+				incidentType: "memory_usage_outbox_quarantined",
+				severity: "error",
+				message: "memory telemetry usage outbox row quarantined",
+				payload: {
+					row_id: row.id,
+					event_type: row.event_type,
+					error_code: "usage_outbox_invalid_payload",
+					retry_state: "quarantined",
+					last_error: lastError
+				}
+			});
+		} catch {}
+	}
+};
+function normalizeUsageInput(input, defaultAgentId) {
+	if (input.eventType !== "recall" && input.eventType !== "inject") throw new Error(`Unsupported memory telemetry usage event type: ${String(input.eventType)}`);
+	if (input.factId.trim().length === 0) throw new Error("memory telemetry usage requires factId");
+	if (input.memoryKind.trim().length === 0) throw new Error("memory telemetry usage requires memoryKind");
+	if (input.projectId.trim().length === 0) throw new Error("memory telemetry usage requires projectId");
+	const metadata = validateMemoryTelemetryMetadata(input.eventType, input.metadata);
+	return {
+		event_type: input.eventType,
+		fact_id: input.factId,
+		memory_kind: input.memoryKind,
+		project_id: input.projectId,
+		agent_id: input.agentId ?? defaultAgentId,
+		session_uuid: input.sessionUuid ?? null,
+		turn_id: input.turnId ?? null,
+		retrieval_rank: input.retrievalRank ?? null,
+		retrieval_score: input.retrievalScore ?? null,
+		metadata_json: metadata
+	};
+}
+function parseUsagePayload(row) {
+	let parsed;
+	try {
+		parsed = JSON.parse(row.payload_json);
+	} catch (error) {
+		throw new PermanentUsageOutboxRowError(`nodix_memory_usage_outbox row ${row.id} has invalid payload_json: ${safeErrorMessage(error)}`);
+	}
+	if (!isRecord(parsed)) throw new PermanentUsageOutboxRowError(`nodix_memory_usage_outbox row ${row.id} has invalid payload`);
+	if (parsed.event_type !== row.event_type) throw new PermanentUsageOutboxRowError(`nodix_memory_usage_outbox row ${row.id} event type drifted`);
+	return {
+		event_type: parseUsageEventType(parsed.event_type, row.id),
+		fact_id: parseRequiredString(parsed.fact_id, "fact_id", row.id),
+		memory_kind: parseRequiredString(parsed.memory_kind, "memory_kind", row.id),
+		project_id: parseRequiredString(parsed.project_id, "project_id", row.id),
+		agent_id: parseNullableString(parsed.agent_id, "agent_id", row.id),
+		session_uuid: parseNullableString(parsed.session_uuid, "session_uuid", row.id),
+		turn_id: parseNullableString(parsed.turn_id, "turn_id", row.id),
+		retrieval_rank: parseNullableNumber(parsed.retrieval_rank, "retrieval_rank", row.id),
+		retrieval_score: parseNullableNumber(parsed.retrieval_score, "retrieval_score", row.id),
+		metadata_json: parseMetadata(parsed.metadata_json, row.id)
+	};
+}
+function parseUsageEventType(value, rowId) {
+	if (value === "recall" || value === "inject") return value;
+	throw new PermanentUsageOutboxRowError(`nodix_memory_usage_outbox row ${rowId} has invalid event_type`);
+}
+function parseRequiredString(value, field, rowId) {
+	if (typeof value === "string" && value.trim().length > 0) return value;
+	throw new PermanentUsageOutboxRowError(`nodix_memory_usage_outbox row ${rowId} has invalid ${field}`);
+}
+function parseNullableString(value, field, rowId) {
+	if (value === null) return null;
+	if (typeof value === "string") return value;
+	throw new PermanentUsageOutboxRowError(`nodix_memory_usage_outbox row ${rowId} has invalid ${field}`);
+}
+function parseNullableNumber(value, field, rowId) {
+	if (value === null) return null;
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	throw new PermanentUsageOutboxRowError(`nodix_memory_usage_outbox row ${rowId} has invalid ${field}`);
+}
+function parseMetadata(value, rowId) {
+	if (isRecord(value)) return value;
+	throw new PermanentUsageOutboxRowError(`nodix_memory_usage_outbox row ${rowId} has invalid metadata_json`);
+}
+var PermanentUsageOutboxRowError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "PermanentUsageOutboxRowError";
+	}
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function safeErrorMessage(error) {
+	if (error instanceof Error && error.message.trim().length > 0) return error.message.slice(0, 500);
+	return "memory telemetry usage flush failed";
+}
+//#endregion
+export { MemoryTelemetryUsageOutbox };

package/dist/internal/engine/telemetry/memory-telemetry-types.d.ts

@@ -0,0 +1,2 @@
+import { a as MemoryTelemetryMetadata, i as MemoryTelemetryEventType, n as MEMORY_TELEMETRY_EVENT_TYPES, o as MemoryTelemetryReceiptStatus, r as MemoryTelemetryDeleteReason, s as isMemoryTelemetryEventType, t as MEMORY_TELEMETRY_DELETE_REASONS } from "../../../memory-telemetry-types-CufVmrCs.js";
+export { MEMORY_TELEMETRY_DELETE_REASONS, MEMORY_TELEMETRY_EVENT_TYPES, MemoryTelemetryDeleteReason, MemoryTelemetryEventType, MemoryTelemetryMetadata, MemoryTelemetryReceiptStatus, isMemoryTelemetryEventType };

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

@@ -0,0 +1,21 @@
+//#region src/engine/telemetry/memory-telemetry-types.ts
+const MEMORY_TELEMETRY_EVENT_TYPES = [
+	"create",
+	"update",
+	"recall",
+	"supersede",
+	"delete",
+	"inject",
+	"epoch_boundary",
+	"purge"
+];
+const MEMORY_TELEMETRY_DELETE_REASONS = {
+	admin: "admin_delete",
+	cli: "cli_delete",
+	memoryForget: "memory_forget"
+};
+function isMemoryTelemetryEventType(value) {
+	return typeof value === "string" && MEMORY_TELEMETRY_EVENT_TYPES.includes(value);
+}
+//#endregion
+export { MEMORY_TELEMETRY_DELETE_REASONS, MEMORY_TELEMETRY_EVENT_TYPES, isMemoryTelemetryEventType };

package/dist/internal/engine/telemetry/observe-ledger.d.ts

@@ -0,0 +1,30 @@
+import { t as ObserveLogger } from "../../../best-effort-BPZSzKk0.js";
+import { t as EmitInput } from "../../../adapter-DMEmCTKo.js";
+import { EventLane, EventType, JsonObject } from "@snoai/observability";
+//#region src/engine/telemetry/observe-ledger.d.ts
+export interface ObserveLedgerRow {
+  ts_ms: number;
+  event_type: EventType;
+  lane: EventLane;
+  project_id?: string;
+  payload: JsonObject;
+}
+interface LedgerObserve {
+  tryEmit(input: EmitInput): boolean | Promise<boolean>;
+  emitError?(kind: string, error: unknown): void | Promise<void>;
+  readonly logger?: ObserveLogger | undefined;
+}
+interface ForwardResult {
+  status: "idle" | "forwarded" | "failed";
+  forwarded: number;
+  offset: number;
+}
+export declare function observeLedgerPath(profileDir: string): string;
+export declare function observeLedgerSyncedPath(profileDir: string): string;
+export declare function appendObserveLedgerRows(profileDir: string, rows: readonly ObserveLedgerRow[]): void;
+export declare function forwardObserveLedger(options: {
+  profileDir: string;
+  observe: LedgerObserve;
+  batchSize?: number;
+}): Promise<ForwardResult>;
+//#endregion