@snoai/memory 0.0.0-stage → 1.0.1

package/dist/data-bootstrap-P8sie9WA.js

@@ -0,0 +1,172 @@
+import { assertLocalFilesystem, getInstallManifestPath, getSnoStationMemDataDir } from "./internal/store/data-paths.js";
+import { z } from "zod";
+import { createLogger } from "@snoai/utils/logger";
+import { basename, dirname } from "node:path";
+import { createUUIDv7, isLowercaseCanonicalUUIDv7 } from "@snoai/common-core";
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+const INSTALL_MANIFEST_TEMP_SUFFIX = ".tmp-";
+/** Schema. No `lastSeenVersion` / `lastSeenAt`. */
+const InstallManifestSchema = z.object({
+	schemaVersion: z.literal(1),
+	dataFormatVersion: z.literal(1),
+	installationId: z.string().refine(isLowercaseCanonicalUUIDv7, { message: "installationId must be a lowercase canonical UUID-v7" }),
+	createdAt: z.string().datetime(),
+	dbPath: z.string().min(1)
+});
+/** Thrown when the on-disk manifest fails Zod validation or JSON parsing. */
+var ManifestSchemaError = class extends Error {
+	path;
+	kind = "ManifestSchemaError";
+	constructor(path, cause) {
+		super(`install manifest at ${path} is corrupt or has unexpected schema: ${cause instanceof Error ? cause.message : String(cause)}`, { cause: cause instanceof Error ? cause : void 0 });
+		this.path = path;
+		this.name = "ManifestSchemaError";
+	}
+};
+/**
+* Thrown when the data dir contains user data (DB / audit log / cost log) but
+* `install.json` is missing, so nothing destructive happens
+* here; the user must restore `install.json` from backup or move the data aside.
+*/
+var ManifestMissingButDataPresentError = class extends Error {
+	dataDir;
+	kind = "ManifestMissingButDataPresentError";
+	constructor(dataDir) {
+		super(`install.json is missing but the data dir at ${dataDir} contains user data; refusing to overwrite. Restore install.json from backup or move the data aside.`);
+		this.dataDir = dataDir;
+		this.name = "ManifestMissingButDataPresentError";
+	}
+};
+/** Read + Zod-validate `install.json`. Throws `ManifestSchemaError` on any failure. */
+function readInstallManifest(path) {
+	let raw;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (err) {
+		throw new ManifestSchemaError(path, err);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new ManifestSchemaError(path, err);
+	}
+	const result = InstallManifestSchema.safeParse(parsed);
+	if (!result.success) throw new ManifestSchemaError(path, result.error);
+	return result.data;
+}
+/**
+* Atomic write: tmp → fsync(tmp) → rename(tmp, target) → fsync(parent dir).
+* POSIX rename is atomic on local FS; the parent fsync makes the rename
+* durable across a power loss. Mode 0644 (no secrets in the manifest).
+*/
+function writeInstallManifestAtomic(path, manifest) {
+	const validated = InstallManifestSchema.parse(manifest);
+	const dir = dirname(path);
+	mkdirSync(dir, {
+		recursive: true,
+		mode: 448
+	});
+	const tmp = `${path}${INSTALL_MANIFEST_TEMP_SUFFIX}${process.pid}-${Date.now().toString(36)}`;
+	writeFileSync(tmp, JSON.stringify(validated), { mode: 420 });
+	chmodSync(tmp, 420);
+	const fd = openSync(tmp, "r");
+	try {
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+	renameSync(tmp, path);
+	const dirFd = openSync(dir, 0);
+	try {
+		fsyncSync(dirFd);
+	} finally {
+		closeSync(dirFd);
+	}
+}
+/** Build a fresh manifest at first-install time. UUIDv7 for time-ordering. */
+function freshInstallManifest(args) {
+	return InstallManifestSchema.parse({
+		schemaVersion: 1,
+		dataFormatVersion: 1,
+		installationId: createUUIDv7(),
+		createdAt: args.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		dbPath: args.dbPath
+	});
+}
+//#endregion
+//#region src/store/data-bootstrap.ts
+/** @file data-bootstrap.ts
+* @purpose Drive the boot flow: ensure data dir exists, probe
+*   filesystem, then resolve or create the install manifest
+*   and return the settings-selected DB path the rest of the runtime should open.
+* @boundary Called once at plugin register-time, AFTER `initSqliteRuntime()`
+*   resolves the DEK. Returns `{ dbPath, manifest, manifestPath }`.
+*/
+const log = createLogger("sno-station-mem:data-bootstrap");
+/** Detect "data exists but manifest missing". */
+function newDirHasUserData(dataDir, manifestPath) {
+	const manifestTempPrefix = `${basename(manifestPath)}${INSTALL_MANIFEST_TEMP_SUFFIX}`;
+	try {
+		return readdirSync(dataDir, { withFileTypes: true }).some((entry) => !(entry.isFile() && entry.name.startsWith(manifestTempPrefix)));
+	} catch {
+		return false;
+	}
+}
+/**
+* Branches:
+*   1. manifest exists → read + validate.
+*   2. manifest missing AND data dir contains user data → refuse.
+*   3. manifest missing, dir empty → fresh install.
+*/
+function bootstrapDataLayout(storePath) {
+	const dataDir = getSnoStationMemDataDir();
+	mkdirSync(dataDir, {
+		recursive: true,
+		mode: 448
+	});
+	assertLocalFilesystem(dataDir);
+	const manifestPath = getInstallManifestPath();
+	if (existsSync(manifestPath)) {
+		const manifest = readInstallManifest(manifestPath);
+		const dbPath = storePath;
+		log.info("manifest loaded", {
+			installationId: manifest.installationId,
+			dataFormatVersion: manifest.dataFormatVersion,
+			dbPath
+		}, {
+			event_name: "sno_station_mem.data-bootstrap.manifest.loaded",
+			file: "packages/memory/src/store/data-bootstrap.ts",
+			function: "bootstrapDataLayout",
+			site_id: "data-bootstrap.bootstrapDataLayout.4fc42585ae"
+		});
+		return {
+			dbPath,
+			manifest,
+			manifestPath,
+			dataDir
+		};
+	}
+	if (newDirHasUserData(dataDir, manifestPath)) throw new ManifestMissingButDataPresentError(dataDir);
+	const manifest = freshInstallManifest({ dbPath: storePath });
+	writeInstallManifestAtomic(manifestPath, manifest);
+	const resolved = storePath;
+	log.info("fresh install bootstrapped", {
+		installationId: manifest.installationId,
+		dataFormatVersion: manifest.dataFormatVersion,
+		dbPath: resolved
+	}, {
+		event_name: "sno_station_mem.data-bootstrap.fresh.install.bootstrapped",
+		file: "packages/memory/src/store/data-bootstrap.ts",
+		function: "bootstrapDataLayout",
+		site_id: "data-bootstrap.bootstrapDataLayout.4af3189946"
+	});
+	return {
+		dbPath: resolved,
+		manifest,
+		manifestPath,
+		dataDir
+	};
+}
+//#endregion
+export { bootstrapDataLayout as t };

package/dist/data-paths-C7sNdqvP.d.ts

@@ -0,0 +1,22 @@
+//#region src/store/data-paths.d.ts
+/** Typed boundary error for refuse-to-operate when data dir is on NFS/SMB/FUSE. */
+declare class NonLocalFilesystemError extends Error {
+  readonly dir: string;
+  readonly fsType: number;
+  readonly kind: "NonLocalFilesystemError";
+  constructor(dir: string, fsType: number);
+}
+declare function getSnoStationMemDataDir(): string;
+declare function getInstallManifestPath(): string;
+declare function getAuditLogPath(): string;
+declare function getCostLogPath(): string;
+declare function getKillswitchPath(): string;
+declare function getBackupsDir(): string;
+/**
+ * `statfs(2)`-based check: throws `NonLocalFilesystemError` when `dir` sits on
+ * NFS / SMB / FUSE (which includes iCloud-Drive-watched directories). POSIX
+ * only — Windows is out of v1 projectId.
+ */
+declare function assertLocalFilesystem(dir: string): void;
+//#endregion
+export { getCostLogPath as a, getSnoStationMemDataDir as c, getBackupsDir as i, assertLocalFilesystem as n, getInstallManifestPath as o, getAuditLogPath as r, getKillswitchPath as s, NonLocalFilesystemError as t };

package/dist/derived-suppression-cache-CI0durYx.d.ts

@@ -0,0 +1,36 @@
+import "./types-CWdhXLxr.js";
+//#region src/engine/reflection/reflection-line-loader.d.ts
+interface ReflectionLineSource {
+  line: string;
+  rowId: string;
+  factId: string;
+  sourceAgentId: string;
+  memoryKind: string;
+  projectId: string;
+  rank: number;
+  score: number;
+}
+interface LoadedReflectionSlices {
+  invariants: string[];
+  derived: string[];
+  invariantSources: ReflectionLineSource[];
+  derivedSources: ReflectionLineSource[];
+}
+//#endregion
+//#region src/engine/reflection/derived-line-cache.d.ts
+type ReflectionDerivedCacheEntry = {
+  updatedAt: number;
+  derived: string[];
+  derivedSources?: ReflectionLineSource[];
+};
+type ReflectionDerivedCache = Map<string, ReflectionDerivedCacheEntry>;
+//#endregion
+//#region src/engine/reflection/derived-suppression-cache.d.ts
+type ReflectionDerivedSuppressionEntry = {
+  updatedAt: number;
+  until: number;
+  reason: string;
+};
+type ReflectionDerivedSuppressionCache = Map<string, ReflectionDerivedSuppressionEntry>;
+//#endregion
+export { ReflectionDerivedCache as n, LoadedReflectionSlices as r, ReflectionDerivedSuppressionCache as t };

package/dist/diagnostic-encoder.d.ts

@@ -0,0 +1,6 @@
+import { DiagnosticInput, DiagnosticInput as DiagnosticInput$1, LogLevel, LogSource } from "@snoai/utils/log-encoder";
+//#region src/engine/observability/early-diagnostics.d.ts
+export declare function encodeDiagnostic(input: DiagnosticInput$1): string;
+export declare function writeEmergencyDiagnostic(input: DiagnosticInput$1): void;
+//#endregion
+export type { DiagnosticInput, LogLevel, LogSource };

package/dist/diagnostic-encoder.js

@@ -0,0 +1,29 @@
+import { n as version, t as logSiteCatalog } from "./log-site-catalog.generated-BMKWj-Nx.js";
+import { diagnosticProcessInstanceId, encodeDiagnostic as encodeDiagnostic$1, writeEmergencyDiagnostic as writeEmergencyDiagnostic$1 } from "@snoai/utils/log-encoder";
+//#region src/engine/observability/early-diagnostics.ts
+function bindApplication(input) {
+	const site = logSiteCatalog.sites[input.source.site_id];
+	const matched = site?.file === input.source.file && site?.function === input.source.function;
+	return {
+		...input,
+		resource: {
+			service_name: "sno-station-mem",
+			service_version: version,
+			build_id: logSiteCatalog.build_id,
+			process_id: process.pid,
+			process_instance_id: diagnosticProcessInstanceId
+		},
+		resolvedSource: {
+			catalog_status: matched ? "available" : "unavailable",
+			...!matched ? { catalog_reason: "site_not_in_catalog" } : {}
+		}
+	};
+}
+function encodeDiagnostic(input) {
+	return encodeDiagnostic$1(bindApplication(input));
+}
+function writeEmergencyDiagnostic(input) {
+	writeEmergencyDiagnostic$1(bindApplication(input));
+}
+//#endregion
+export { encodeDiagnostic, writeEmergencyDiagnostic };

package/dist/embedding-provider-client-Q_hJonK9.js

@@ -0,0 +1,294 @@
+import { CACHE_TTL_MS, RETRIEVAL_STORAGE_CHUNK_PROFILE } from "./internal/config/index.js";
+import { EmbeddingError } from "./internal/engine/shared/errors.js";
+import { chunk } from "@snoai/chunking";
+import { CachedEmbeddingProvider, LOCAL_EMBEDDING_CACHE_DIR_DEFAULT, LOCAL_EMBEDDING_MODEL, LOCAL_EMBEDDING_MODEL_REVISION, LocalEmbedProvider, ensureModelDownloaded } from "@snoai/embedder";
+import { createLogger } from "@snoai/utils/logger";
+//#region src/engine/extraction/embedding-provider-factory.ts
+function resolveEmbeddingCacheDir(config) {
+	return config.cacheDir || LOCAL_EMBEDDING_CACHE_DIR_DEFAULT;
+}
+/** Assembles provider from validated inputs for deterministic embedding generation. */
+function buildProvider(config) {
+	return new LocalEmbedProvider({
+		...config.cacheDir ? { cacheDir: config.cacheDir } : {},
+		offline: config.offline,
+		mirror: config.mirror,
+		dtype: config.dtype,
+		sessionOptions: config.sessionOptions,
+		...config.model !== void 0 ? { model: config.model } : {},
+		...config.revision !== void 0 ? { revision: config.revision } : {},
+		...config.nativeDim !== void 0 ? { nativeDim: config.nativeDim } : {},
+		...config.dimensions !== void 0 ? { outputDim: config.dimensions } : {},
+		...config.pooling !== void 0 ? { pooling: config.pooling } : {}
+	});
+}
+//#endregion
+//#region src/engine/extraction/embedding-vector-aggregation.ts
+/**
+* Compute L2-normalized weighted average of Float32Array vectors.
+* Weights are typically chunk char lengths so longer chunks contribute more.
+*/
+function weightedAverageFloat32(vectors, weights, dim) {
+	const acc = new Array(dim).fill(0);
+	let totalWeight = 0;
+	for (let i = 0; i < vectors.length; i++) {
+		const w = weights[i] ?? 1;
+		const vec = vectors[i];
+		if (!vec) continue;
+		totalWeight += w;
+		for (let j = 0; j < dim; j++) acc[j] = (acc[j] ?? 0) + (vec[j] ?? 0) * w;
+	}
+	if (totalWeight > 0) for (let j = 0; j < dim; j++) acc[j] = (acc[j] ?? 0) / totalWeight;
+	let norm = 0;
+	for (let j = 0; j < dim; j++) {
+		const v = acc[j] ?? 0;
+		norm += v * v;
+	}
+	norm = Math.sqrt(norm);
+	if (norm > 0) for (let j = 0; j < dim; j++) acc[j] = (acc[j] ?? 0) / norm;
+	return Float32Array.from(acc);
+}
+//#endregion
+//#region src/engine/shared/token-bound.ts
+/** @file token-bound.ts
+* @purpose Cuts text to a token budget under any monotonic token counter.
+* @boundary Pure text function; the caller supplies the counter.
+*/
+/**
+* Longest prefix of `text` costing at most `maxTokens` under `countTokens`. Bounding by
+* token cost rather than character count keeps the budget honest across scripts: a
+* character bound buys several times more prompt for Latin text than for CJK.
+*
+* Binary search is safe because every counter used here 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, which can only
+* lower the token count, so the budget still holds.
+*/
+function truncateToTokens(text, maxTokens, countTokens) {
+	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();
+}
+//#endregion
+//#region src/engine/extraction/embedding-provider-client.ts
+/** @file embedding-provider-client.ts
+* @purpose Adapts embedding providers to the plugin retrieval and storage contract.
+* @boundary Local ONNX embeddings, chunk sizing, and vector dimensions.
+* @see store.ts, retriever.ts.
+*/
+/** Local ONNX embedding with an LRU cache and oversized-text chunking. */
+const log = createLogger("sno-station-mem:embed");
+var Embedder = class {
+	provider;
+	chunkingEnabled;
+	dimensions;
+	providerKind;
+	model;
+	warmupPromise = null;
+	modelDownload;
+	/**
+	* Initializes embedding generation collaborators while keeping runtime work in explicit
+	* methods.
+	*/
+	constructor(config, _stateDir) {
+		this.chunkingEnabled = config.chunking !== false;
+		const providerKind = config.provider ?? "local-onnx";
+		const inner = buildProvider(config);
+		this.modelDownload = config.model && config.model !== LOCAL_EMBEDDING_MODEL || config.revision && config.revision !== LOCAL_EMBEDDING_MODEL_REVISION ? void 0 : {
+			cacheDir: resolveEmbeddingCacheDir(config),
+			offline: config.offline,
+			mirror: config.mirror,
+			...config.dtype ? { dtype: config.dtype } : {}
+		};
+		this.dimensions = inner.dimension;
+		this.providerKind = providerKind;
+		this.model = config.model && config.model.trim().length > 0 ? config.model : LOCAL_EMBEDDING_MODEL;
+		this.provider = new CachedEmbeddingProvider(inner, {
+			maxSize: 256,
+			ttlMs: CACHE_TTL_MS
+		});
+		log.info("embedder initialized", {
+			provider: providerKind,
+			model: this.model,
+			dimensions: this.dimensions,
+			chunking: this.chunkingEnabled,
+			maxContextTokens: 512
+		}, {
+			event_name: "sno_station_mem.embedding-provider-client.embedder.initialized",
+			file: "packages/memory/src/engine/extraction/embedding-provider-client.ts",
+			function: "<anonymous callback>",
+			site_id: "embedding-provider-client.<anonymous callback>.3c8d5ee192"
+		});
+	}
+	/** Converts float32 into the transport shape expected by embedding generation. */
+	toFloat32(vector) {
+		if (vector.length !== this.dimensions) throw new EmbeddingError(`Embedding dimension mismatch: expected ${this.dimensions}, got ${vector.length}`);
+		return Float32Array.from(vector);
+	}
+	buildEmbedderChunkConfig() {
+		return {
+			contentType: "prose",
+			minTokens: RETRIEVAL_STORAGE_CHUNK_PROFILE.minTokens,
+			targetTokens: 512,
+			maxTokens: 512,
+			overlapTokens: RETRIEVAL_STORAGE_CHUNK_PROFILE.overlapTokens
+		};
+	}
+	/**
+	* Exact token count under the embedding model's own tokenizer — the count the model
+	* sees, so `DEFAULT_MAX_CONTEXT_TOKENS` checked against it is a hard limit. Synchronous;
+	* throws until the model has loaded, which `warmup()` does at plugin register time.
+	*/
+	countTokens(text) {
+		return this.provider.countTokens(text);
+	}
+	/** Longest prefix of `text` within `maxTokens` under {@link countTokens}. */
+	truncateToTokens(text, maxTokens) {
+		return truncateToTokens(text, maxTokens, (t) => this.countTokens(t));
+	}
+	/**
+	* Wait for warmup before issuing real embedding work. Calls `warmup()`
+	* itself so callers that bypass register-time warmup (tests, ad-hoc
+	* scripts) still get the same fail-loud probe — `warmup()` is memoized,
+	* so repeated calls reuse the in-flight or completed promise.
+	*/
+	async awaitWarmup() {
+		await this.warmup();
+	}
+	/** Implements embed as the local embedding generation operation. */
+	async embed(text) {
+		await this.awaitWarmup();
+		if (!this.chunkingEnabled) return this.embedDirect(text);
+		const tokens = this.countTokens(text);
+		if (tokens <= 512) return this.embedDirect(text);
+		const chunks = chunk(text, this.buildEmbedderChunkConfig()).map((draft) => draft.chunkText);
+		for (const piece of chunks) {
+			const pieceTokens = this.countTokens(piece);
+			if (pieceTokens > 512) throw new EmbeddingError(`Embedder chunk of ${pieceTokens} tokens exceeds DEFAULT_MAX_CONTEXT_TOKENS (512)`);
+		}
+		if (chunks.length <= 1) return this.embedDirect(chunks[0] ?? text);
+		log.warn("legacy chunker invoked (embedding-API safety net)", {
+			chunks: chunks.length,
+			totalTokens: tokens,
+			maxTokens: 512
+		}, {
+			event_name: "sno_station_mem.embedding-provider-client.legacy.chunker.invoked.embedding.api.safety.net",
+			file: "packages/memory/src/engine/extraction/embedding-provider-client.ts",
+			function: "embed",
+			site_id: "embedding-provider-client.embed.ab60111378"
+		});
+		return weightedAverageFloat32(await this.embedMany(chunks), chunks.map((c) => c.length), this.dimensions);
+	}
+	/** Implements embed direct as the local embedding generation operation. */
+	async embedDirect(text) {
+		try {
+			const vector = await this.provider.embed(text);
+			return this.toFloat32(vector);
+		} catch (error) {
+			log.error("passage embedding failed", {
+				textLength: text.length,
+				error
+			}, {
+				event_name: "sno_station_mem.embedding-provider-client.passage.embedding.failed",
+				file: "packages/memory/src/engine/extraction/embedding-provider-client.ts",
+				function: "embedDirect",
+				site_id: "embedding-provider-client.embedDirect.c6998ac2fb"
+			});
+			throw new EmbeddingError("Failed to generate passage embedding", error);
+		}
+	}
+	/** Implements embed many as the local embedding generation operation. */
+	async embedMany(values) {
+		await this.awaitWarmup();
+		log.debug("batch embedding", { count: values.length }, {
+			event_name: "sno_station_mem.embedding-provider-client.batch.embedding",
+			file: "packages/memory/src/engine/extraction/embedding-provider-client.ts",
+			function: "embedMany",
+			site_id: "embedding-provider-client.embedMany.8ffe2fb365"
+		});
+		try {
+			const vectors = await this.provider.embedDocuments(values);
+			if (vectors.length !== values.length) throw new EmbeddingError(`Embedding provider returned ${vectors.length} vectors for ${values.length} inputs`);
+			return vectors.map((v) => this.toFloat32(v));
+		} catch (error) {
+			log.error("batch embedding failed", {
+				count: values.length,
+				error
+			}, {
+				event_name: "sno_station_mem.embedding-provider-client.batch.embedding.failed",
+				file: "packages/memory/src/engine/extraction/embedding-provider-client.ts",
+				function: "embedMany",
+				site_id: "embedding-provider-client.embedMany.71b35eadaf"
+			});
+			if (error instanceof EmbeddingError) throw error;
+			throw new EmbeddingError("Failed to generate batch embeddings", error);
+		}
+	}
+	/**
+	* Embed each input text individually as a passage. Used by chunk-level
+	* ingestion in `MemoryStore` — one vector per chunk, no averaging. Reuses
+	* the batch primitive and its cache.
+	*/
+	async embedChunks(texts) {
+		if (texts.length === 0) return [];
+		return this.embedMany(texts);
+	}
+	/**
+	* Force the underlying ONNX model to load and run one real inference.
+	*
+	* LocalEmbedProvider lazy-loads the model on first `embed()` call. That
+	* means `new Embedder(...)` succeeds even if the model file is missing —
+	* the failure only surfaces later, per-turn, during ambient-learning, where
+	* the error is swallowed by `Promise.allSettled`. Calling `warmup()` at
+	* plugin-register time turns a latent misconfiguration into a hard,
+	* loud registration failure. Caller should let the error propagate.
+	*/
+	async warmup() {
+		if (this.warmupPromise) return this.warmupPromise;
+		const probe = (async () => {
+			try {
+				if (this.modelDownload) await ensureModelDownloaded(this.modelDownload);
+				const vector = await this.provider.embed("warmup");
+				if (vector.length !== this.dimensions) throw new EmbeddingError(`Embedder warmup dimension mismatch: expected ${this.dimensions}, got ${vector.length}`);
+				log.info("embedder warmup ok", { dimensions: this.dimensions }, {
+					event_name: "sno_station_mem.embedding-provider-client.embedder.warmup.ok",
+					file: "packages/memory/src/engine/extraction/embedding-provider-client.ts",
+					function: "<anonymous callback>",
+					site_id: "embedding-provider-client.<anonymous callback>.32cc9ec43e"
+				});
+			} catch (error) {
+				log.error("embedder warmup failed", { error }, {
+					event_name: "sno_station_mem.embedding-provider-client.embedder.warmup.failed",
+					file: "packages/memory/src/engine/extraction/embedding-provider-client.ts",
+					function: "<anonymous callback>",
+					site_id: "embedding-provider-client.<anonymous callback>.d7a3f8337c"
+				});
+				throw new EmbeddingError("Embedder warmup failed — the plugin cannot capture or recall memories. Check that the local ONNX model exists at the configured cacheDir.", error);
+			}
+		})();
+		this.warmupPromise = probe.catch((err) => {
+			this.warmupPromise = null;
+			throw err;
+		});
+		return this.warmupPromise;
+	}
+	/** Implements dispose as the local embedding generation operation. */
+	async dispose() {
+		const warmup = this.warmupPromise;
+		if (warmup) await warmup.catch(() => void 0);
+		await this.provider.dispose();
+	}
+};
+/** Creates the embedder facade around the local ONNX provider. */
+function createEmbedder(config, stateDir) {
+	return new Embedder(config, stateDir);
+}
+//#endregion
+export { createEmbedder as n, Embedder as t };

package/dist/embedding-provider-client-vynZMuit.d.ts

@@ -0,0 +1,94 @@
+import { LocalEmbedDtype, LocalEmbedSessionOptions } from "@snoai/embedder";
+//#region src/engine/extraction/embedding-provider-factory.d.ts
+type EmbeddingProviderKind = "local-onnx";
+interface EmbeddingConfig {
+  /** Which provider to instantiate. Defaults to local-onnx. */
+  provider?: EmbeddingProviderKind;
+  /** Hugging Face model id. Defaults to the bundled PPLX INT8 model. */
+  model?: string;
+  /** Output dimension. Smaller values truncate and re-normalize the native vector. */
+  dimensions?: number;
+  /** Native model dimension. Defaults to 1024 for bundled PPLX. */
+  nativeDim?: number;
+  /** Pinned HuggingFace revision SHA for local-onnx (defaults to bundled 0.6B revision). */
+  revision?: string;
+  /**
+   * Pooling strategy for local-onnx. Defaults to `mean` for bundled PPLX.
+   * Read the model's `1_Pooling/config.json`.
+   */
+  pooling?: "last_token" | "mean" | "cls";
+  normalized?: boolean;
+  /** Local ONNX model cache directory (default: ./embedding/models) */
+  cacheDir?: string;
+  offline?: boolean;
+  mirror?: string;
+  /** Quantization dtype. Default: q8. */
+  dtype?: LocalEmbedDtype;
+  /** ONNX Runtime session options for local low-memory operation. */
+  sessionOptions?: LocalEmbedSessionOptions;
+  /** Enable text chunking for long passages (default: true) */
+  chunking?: boolean;
+}
+//#endregion
+//#region src/engine/extraction/embedding-provider-client.d.ts
+declare class Embedder {
+  private readonly provider;
+  private readonly chunkingEnabled;
+  readonly dimensions: number;
+  readonly providerKind: EmbeddingProviderKind;
+  readonly model: string;
+  private warmupPromise;
+  private readonly modelDownload;
+  /**
+   * Initializes embedding generation collaborators while keeping runtime work in explicit
+   * methods.
+   */
+  constructor(config: EmbeddingConfig, _stateDir: string);
+  /** Converts float32 into the transport shape expected by embedding generation. */
+  private toFloat32;
+  private buildEmbedderChunkConfig;
+  /**
+   * Exact token count under the embedding model's own tokenizer — the count the model
+   * sees, so `DEFAULT_MAX_CONTEXT_TOKENS` checked against it is a hard limit. Synchronous;
+   * throws until the model has loaded, which `warmup()` does at plugin register time.
+   */
+  countTokens(text: string): number;
+  /** Longest prefix of `text` within `maxTokens` under {@link countTokens}. */
+  truncateToTokens(text: string, maxTokens: number): string;
+  /**
+   * Wait for warmup before issuing real embedding work. Calls `warmup()`
+   * itself so callers that bypass register-time warmup (tests, ad-hoc
+   * scripts) still get the same fail-loud probe — `warmup()` is memoized,
+   * so repeated calls reuse the in-flight or completed promise.
+   */
+  private awaitWarmup;
+  /** Implements embed as the local embedding generation operation. */
+  embed(text: string): Promise<Float32Array>;
+  /** Implements embed direct as the local embedding generation operation. */
+  protected embedDirect(text: string): Promise<Float32Array>;
+  /** Implements embed many as the local embedding generation operation. */
+  embedMany(values: string[]): Promise<Float32Array[]>;
+  /**
+   * Embed each input text individually as a passage. Used by chunk-level
+   * ingestion in `MemoryStore` — one vector per chunk, no averaging. Reuses
+   * the batch primitive and its cache.
+   */
+  embedChunks(texts: string[]): Promise<Float32Array[]>;
+  /**
+   * Force the underlying ONNX model to load and run one real inference.
+   *
+   * LocalEmbedProvider lazy-loads the model on first `embed()` call. That
+   * means `new Embedder(...)` succeeds even if the model file is missing —
+   * the failure only surfaces later, per-turn, during ambient-learning, where
+   * the error is swallowed by `Promise.allSettled`. Calling `warmup()` at
+   * plugin-register time turns a latent misconfiguration into a hard,
+   * loud registration failure. Caller should let the error propagate.
+   */
+  warmup(): Promise<void>;
+  /** Implements dispose as the local embedding generation operation. */
+  dispose(): Promise<void>;
+}
+/** Creates the embedder facade around the local ONNX provider. */
+declare function createEmbedder(config: EmbeddingConfig, stateDir: string): Embedder;
+//#endregion
+export { EmbeddingProviderKind as i, createEmbedder as n, EmbeddingConfig as r, Embedder as t };

package/dist/entry-metadata-parser-BIVSMCIk.js

@@ -0,0 +1,20 @@
+//#region src/engine/reflection/entry-metadata-parser.ts
+/** @file entry-metadata-parser.ts
+* @purpose Defines metadata helpers for reflection provenance, severity, and grouping.
+* @boundary Reflection item storage, retry handling, and reporting surfaces.
+* @see daily-log-generator.ts, slice-item-payload-builder.ts, transient-generation-retry.ts.
+*/
+/**
+* Reflection metadata parsing utilities.
+*/
+function parseReflectionMetadata(metadataRaw) {
+	if (!metadataRaw) return {};
+	try {
+		const parsed = JSON.parse(metadataRaw);
+		return parsed && typeof parsed === "object" ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+//#endregion
+export { parseReflectionMetadata as t };