@snoai/memory 0.0.0-stage → 1.0.1

package/dist/rolldown-runtime-D7D4PA-g.js

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll as t };

package/dist/routes-DLHT__Ay.js

@@ -0,0 +1,60 @@
+//#region src/contract/routes.ts
+const MEMORY_ROUTES = {
+	init: {
+		path: "/v1/init",
+		timeoutMs: 3e4
+	},
+	hostEvent: {
+		path: "/v1/host-event",
+		timeoutMs: 3e4
+	},
+	getRecall: {
+		path: "/v1/get-recall",
+		timeoutMs: 12e4
+	},
+	capture: {
+		path: "/v1/capture",
+		timeoutMs: 9e5
+	},
+	mutate: {
+		path: "/v1/mutate",
+		timeoutMs: 9e5
+	},
+	inspect: {
+		path: "/v1/inspect",
+		timeoutMs: 3e4
+	},
+	recordUsage: {
+		path: "/v1/record-usage",
+		timeoutMs: 3e4
+	},
+	onSessionEnd: {
+		path: "/v1/on-session-end",
+		timeoutMs: 9e5
+	},
+	staticBlock: {
+		path: "/v1/static-block",
+		timeoutMs: 3e4
+	}
+};
+const MEMORY_BODY_LIMIT_BYTES = 8388608;
+const MEMORY_SKIN_HEADER = "x-sno-station-mem-skin";
+const REM_SIDECAR_TOKEN_HEADER = "x-sidecar-token";
+function memoryMethod(pathname) {
+	return Object.keys(MEMORY_ROUTES).find((method) => MEMORY_ROUTES[method].path === pathname);
+}
+const MEMORY_ERROR_STATUS = {
+	"sidecar-unreachable": 503,
+	"sidecar-unresponsive": 503,
+	"principal-mismatch": 403,
+	"store-mismatch": 409,
+	"no-agent-endpoint": 503,
+	"invalid-input": 400,
+	timeout: 504,
+	"storage-unavailable": 503,
+	"engine-failed": 500
+};
+const MEMORY_RECONNECT_INTERVAL_MS = 1e3;
+const MEMORY_DEFAULT_SKIN_ID = "default";
+//#endregion
+export { MEMORY_ROUTES as a, memoryMethod as c, MEMORY_RECONNECT_INTERVAL_MS as i, MEMORY_DEFAULT_SKIN_ID as n, MEMORY_SKIN_HEADER as o, MEMORY_ERROR_STATUS as r, REM_SIDECAR_TOKEN_HEADER as s, MEMORY_BODY_LIMIT_BYTES as t };

package/dist/runtime-audit-log-BCeujlEp.js

@@ -0,0 +1,430 @@
+import { redactSecrets } from "./internal/engine/security/redact.js";
+import "./internal/engine/shared/paths.js";
+import { createLogger } from "@snoai/utils/logger";
+import path from "node:path";
+import { appendFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { appendFileSync, createReadStream, existsSync, mkdirSync } from "node:fs";
+import { createInterface } from "node:readline";
+//#region src/engine/operations/jsonl-lines.ts
+const log = createLogger("sno-station-mem:jsonl");
+/** Preserve complete records without materializing an unbounded log as one string. */
+async function* readJsonlLines(file) {
+	const stream = createReadStream(file, { encoding: "utf8" });
+	const lines = createInterface({
+		input: stream,
+		crlfDelay: Infinity
+	});
+	try {
+		for await (const line of lines) if (line.trim()) yield line;
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return;
+		log.error("jsonl.read.failed", {
+			file,
+			error
+		}, {
+			event_name: "memory.jsonl.read.failed",
+			file: "packages/memory/src/engine/operations/jsonl-lines.ts",
+			function: "readJsonlLines",
+			site_id: "memory.jsonl.read.failed"
+		});
+	} finally {
+		lines.close();
+		stream.destroy();
+	}
+}
+//#endregion
+//#region src/engine/operations/runtime-audit-log.ts
+/** @file runtime-audit-log.ts
+* @purpose Records audit events for operational visibility and safety-sensitive actions.
+* @boundary Plugin runtime events and filesystem-backed audit persistence.
+* @see sno-station-mem-plugin-runtime.ts, memory-tool-registration.ts, errors.ts.
+*/
+const auditWriteQueues = /* @__PURE__ */ new Map();
+const memoryAuditScope = new AsyncLocalStorage();
+const mutationAttemptScope = new AsyncLocalStorage();
+const mutationRecoveryPromises = /* @__PURE__ */ new Map();
+const MEMORY_AUDIT_COMMON_KEYS = [
+	"operation",
+	"audit_phase",
+	"audit_operation_id"
+];
+const MUTATION_AUDIT_DETAIL_KEYS = [
+	"mutation_writer",
+	"mutation_subject",
+	"mutation_outcome",
+	"refusal_reason"
+];
+const MEMORY_AUDIT_ALLOWED_DETAIL_KEYS = {
+	memory_injected: /* @__PURE__ */ new Set([
+		...MEMORY_AUDIT_COMMON_KEYS,
+		"scope",
+		"category",
+		"lane",
+		"count",
+		"memory_ids",
+		"write_outcome",
+		"created_count",
+		"existing_count"
+	]),
+	memory_searched: /* @__PURE__ */ new Set([
+		...MEMORY_AUDIT_COMMON_KEYS,
+		"scope",
+		"query_kind",
+		"requested_count",
+		"result_count",
+		"memory_ids"
+	]),
+	memory_read: /* @__PURE__ */ new Set([
+		...MEMORY_AUDIT_COMMON_KEYS,
+		"scope",
+		"requested_count",
+		"result_count",
+		"memory_ids",
+		"requested_fact_id",
+		"resolved_fact_id",
+		"fact_ids",
+		"found",
+		"outcome"
+	]),
+	memory_updated: /* @__PURE__ */ new Set([
+		...MEMORY_AUDIT_COMMON_KEYS,
+		...MUTATION_AUDIT_DETAIL_KEYS,
+		"scope",
+		"requested_count",
+		"result_count",
+		"memory_ids",
+		"outcome",
+		"migration_status",
+		"rewritten_rows",
+		"checked_rows"
+	]),
+	memory_superseded: /* @__PURE__ */ new Set([
+		...MEMORY_AUDIT_COMMON_KEYS,
+		...MUTATION_AUDIT_DETAIL_KEYS,
+		"scope",
+		"replacement_memory_id",
+		"closed_memory_ids",
+		"write_outcome"
+	]),
+	memory_deleted: /* @__PURE__ */ new Set([
+		...MEMORY_AUDIT_COMMON_KEYS,
+		"scope",
+		"deleted_memory_ids",
+		"delete_reason",
+		"count",
+		"outcome",
+		"removed_files"
+	]),
+	memory_purged: /* @__PURE__ */ new Set([
+		...MEMORY_AUDIT_COMMON_KEYS,
+		"target_fact_id",
+		"purged_fact_ids",
+		"failed_fact_ids",
+		"status",
+		"blocked_reason"
+	])
+};
+/** Implements enqueue audit write as the local audit log state operation. */
+function enqueueAuditWrite(auditPath, line) {
+	const next = (auditWriteQueues.get(auditPath) ?? Promise.resolve(true)).catch(() => void 0).then(async () => {
+		mkdirSync(path.dirname(auditPath), { recursive: true });
+		await appendFile(auditPath, line);
+		return true;
+	}).catch((error) => {
+		createLogger("sno-station-mem:audit").error("Audit entry append failed", { error }, {
+			event_name: "memory.audit.append.failed",
+			file: "packages/memory/src/engine/operations/runtime-audit-log.ts",
+			function: "enqueueAuditWrite",
+			site_id: "memory.audit.append.failed"
+		});
+		return false;
+	});
+	auditWriteQueues.set(auditPath, next);
+	next.finally(() => {
+		if (auditWriteQueues.get(auditPath) === next) auditWriteQueues.delete(auditPath);
+	});
+	return next;
+}
+/** Returns audit path from audit log state state without side effects. */
+function getAuditPath(stateDir) {
+	return path.join(stateDir, "audit.jsonl");
+}
+/** Returns cost path from audit log state state without side effects. */
+function getCostPath(stateDir) {
+	return path.join(stateDir, "cost.jsonl");
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isMemoryAuditEvent(event) {
+	return event.startsWith("memory_");
+}
+function redactAuditValue(value) {
+	if (typeof value === "string") return redactSecrets(value);
+	if (Array.isArray(value)) return value.map(redactAuditValue);
+	if (!isRecord(value)) return value;
+	const redacted = {};
+	for (const [key, child] of Object.entries(value)) redacted[key] = redactAuditValue(child);
+	return redacted;
+}
+function prepareAuditEntry(entry) {
+	if (!isMemoryAuditEvent(entry.event) || entry.details?.["audit_phase"] === void 0) return entry;
+	const allowed = MEMORY_AUDIT_ALLOWED_DETAIL_KEYS[entry.event];
+	const details = {};
+	for (const [key, value] of Object.entries(entry.details)) if (allowed.has(key)) details[key] = value;
+	else createLogger("sno-station-mem:audit").error("memory.audit.detail.unknown", {
+		event: entry.event,
+		key
+	}, {
+		event_name: "memory.audit.detail.unknown",
+		file: "packages/memory/src/engine/operations/runtime-audit-log.ts",
+		function: "prepareAuditEntry",
+		site_id: "memory.audit.detail.unknown"
+	});
+	return {
+		...entry,
+		...entry.scope === void 0 ? {} : { scope: redactSecrets(entry.scope) },
+		details: redactAuditValue(details)
+	};
+}
+/** Persists audit entry through the single audit log state write path. */
+function appendAuditEntry(stateDir, entry) {
+	const auditPath = getAuditPath(stateDir);
+	const prepared = prepareAuditEntry(entry);
+	enqueueAuditWrite(auditPath, `${JSON.stringify({
+		...prepared,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	})}\n`);
+}
+/** Waits for the audit append; failures are logged without blocking the operation. */
+async function appendAuditEntryStrict(stateDir, entry) {
+	const auditPath = getAuditPath(stateDir);
+	const prepared = prepareAuditEntry(entry);
+	return enqueueAuditWrite(auditPath, `${JSON.stringify({
+		...prepared,
+		timestamp: (/* @__PURE__ */ new Date()).toISOString()
+	})}\n`);
+}
+/** Attempts a synchronous audit append and logs a failure. */
+function appendAuditEntrySync(stateDir, entry) {
+	const auditPath = getAuditPath(stateDir);
+	const prepared = prepareAuditEntry(entry);
+	try {
+		mkdirSync(path.dirname(auditPath), { recursive: true });
+		appendFileSync(auditPath, `${JSON.stringify({
+			...prepared,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		})}\n`);
+	} catch (error) {
+		createLogger("sno-station-mem:audit").error("memory.audit.append.failed", { error }, {
+			event_name: "memory.audit.append.failed",
+			file: "packages/memory/src/engine/operations/runtime-audit-log.ts",
+			function: "appendAuditEntrySync",
+			site_id: "memory.audit.sync.failed"
+		});
+	}
+}
+function memoryAuditDetails(operation, phase, operationId, details) {
+	return {
+		...details,
+		operation,
+		audit_phase: phase,
+		audit_operation_id: operationId
+	};
+}
+/** Records the start and outcome without using audit availability as admission. */
+async function runWithMemoryAudit(options) {
+	if (memoryAuditScope.getStore()) return options.run();
+	return memoryAuditScope.run(true, async () => {
+		const operationId = randomUUID();
+		await appendAuditEntryStrict(options.stateDir, {
+			event: options.event,
+			scope: options.scope,
+			resultStatus: "partial",
+			details: memoryAuditDetails(options.operation, "started", operationId, options.startedDetails)
+		});
+		let result;
+		try {
+			result = await options.run();
+		} catch (error) {
+			await appendAuditEntryStrict(options.stateDir, {
+				event: options.event,
+				scope: options.scope,
+				resultStatus: "error",
+				errorCode: "memory_operation_failed",
+				details: memoryAuditDetails(options.operation, "failed", operationId, options.startedDetails)
+			});
+			throw error;
+		}
+		await appendAuditEntryStrict(options.stateDir, {
+			event: options.event,
+			scope: options.scope,
+			resultStatus: "ok",
+			details: memoryAuditDetails(options.operation, "completed", operationId, options.completedDetails(result))
+		});
+		return result;
+	});
+}
+async function readOpenMutationAttempts(stateDir) {
+	const auditPath = getAuditPath(stateDir);
+	if (!existsSync(auditPath)) return [];
+	const openAttempts = /* @__PURE__ */ new Map();
+	for await (const line of readJsonlLines(auditPath)) {
+		if (!line.trim()) continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		if (!isRecord(parsed) || !isRecord(parsed["details"])) continue;
+		const event = parsed["event"];
+		const decision = parsed["decision"];
+		const details = parsed["details"];
+		const attemptId = details["audit_operation_id"];
+		if (typeof attemptId !== "string") continue;
+		if (details["mutation_outcome"] !== void 0) {
+			openAttempts.delete(attemptId);
+			continue;
+		}
+		if (decision !== "mutation-attempt-open" || details["audit_phase"] !== "started" || event !== "memory_updated" && event !== "memory_superseded" || typeof details["operation"] !== "string" || details["mutation_writer"] !== "profile-section" && details["mutation_writer"] !== "task-lifecycle" && details["mutation_writer"] !== "legacy-profile-refusal") continue;
+		openAttempts.set(attemptId, {
+			event,
+			operation: details["operation"],
+			attemptId,
+			writer: details["mutation_writer"],
+			...typeof details["mutation_subject"] === "string" ? { subject: details["mutation_subject"] } : {}
+		});
+	}
+	return [...openAttempts.values()];
+}
+function mutationAuditDetails(input) {
+	return {
+		operation: input.operation,
+		audit_phase: input.phase,
+		audit_operation_id: input.attemptId,
+		mutation_writer: input.writer,
+		...input.subject === void 0 ? {} : { mutation_subject: input.subject },
+		...input.outcome === void 0 ? {} : { mutation_outcome: input.outcome },
+		...input.refusalReason === void 0 ? {} : { refusal_reason: input.refusalReason }
+	};
+}
+function mutationAuditStatus(outcome) {
+	if (outcome === "failed" || outcome === "interrupted-unknown") return "error";
+	if (outcome.startsWith("refused-")) return "skipped";
+	return "ok";
+}
+async function closeMutationAttempt(stateDir, attempt, completion) {
+	const phase = completion.outcome === "failed" || completion.outcome === "interrupted-unknown" ? "failed" : "completed";
+	await appendAuditEntryStrict(stateDir, {
+		event: attempt.event,
+		resultStatus: mutationAuditStatus(completion.outcome),
+		decision: completion.outcome,
+		details: mutationAuditDetails({
+			operation: attempt.operation,
+			phase,
+			attemptId: attempt.attemptId,
+			writer: attempt.writer,
+			...attempt.subject === void 0 ? {} : { subject: attempt.subject },
+			outcome: completion.outcome,
+			...completion.refusalReason === void 0 ? {} : { refusalReason: completion.refusalReason }
+		})
+	});
+}
+/** Closes mutation attempts whose process stopped before a terminal audit record was written. */
+async function recoverInterruptedMutationAttempts(stateDir) {
+	const attempts = await readOpenMutationAttempts(stateDir);
+	for (const attempt of attempts) await closeMutationAttempt(stateDir, attempt, { outcome: "interrupted-unknown" });
+	return attempts.map((attempt) => attempt.attemptId);
+}
+function ensureMutationRecovery(stateDir) {
+	const existing = mutationRecoveryPromises.get(stateDir);
+	if (existing) return existing;
+	const recovery = recoverInterruptedMutationAttempts(stateDir).then(() => void 0);
+	mutationRecoveryPromises.set(stateDir, recovery);
+	return recovery;
+}
+/** Runs one mutation under a durable open record and exactly one terminal outcome. */
+async function runWithMutationAttempt(options) {
+	if (mutationAttemptScope.getStore()) return options.run();
+	await ensureMutationRecovery(options.stateDir);
+	const attempt = {
+		event: options.event,
+		operation: options.operation,
+		attemptId: randomUUID(),
+		writer: options.writer,
+		...options.subject === void 0 ? {} : { subject: options.subject }
+	};
+	return mutationAttemptScope.run(attempt.attemptId, async () => {
+		await appendAuditEntryStrict(options.stateDir, {
+			event: options.event,
+			resultStatus: "partial",
+			decision: "mutation-attempt-open",
+			details: mutationAuditDetails({
+				operation: attempt.operation,
+				phase: "started",
+				attemptId: attempt.attemptId,
+				writer: attempt.writer,
+				...attempt.subject === void 0 ? {} : { subject: attempt.subject }
+			})
+		});
+		let result;
+		try {
+			result = await options.run();
+		} catch (error) {
+			await closeMutationAttempt(options.stateDir, attempt, options.failedOutcome?.(error) ?? { outcome: "failed" });
+			throw error;
+		}
+		await closeMutationAttempt(options.stateDir, attempt, options.completedOutcome(result));
+		return result;
+	});
+}
+/** Returns the durable identifier owned by the current mutation boundary. */
+function currentMutationAttemptId() {
+	const attemptId = mutationAttemptScope.getStore();
+	if (!attemptId) throw new Error("mutation attempt identifier requested outside a mutation boundary");
+	return attemptId;
+}
+/** Runs a synchronous memory operation only after its durable start record is persisted. */
+function runWithMemoryAuditSync(options) {
+	if (memoryAuditScope.getStore()) return options.run();
+	return memoryAuditScope.run(true, () => {
+		const operationId = randomUUID();
+		appendAuditEntrySync(options.stateDir, {
+			event: options.event,
+			scope: options.scope,
+			resultStatus: "partial",
+			details: memoryAuditDetails(options.operation, "started", operationId, options.startedDetails)
+		});
+		let result;
+		try {
+			result = options.run();
+		} catch (error) {
+			appendAuditEntrySync(options.stateDir, {
+				event: options.event,
+				scope: options.scope,
+				resultStatus: "error",
+				errorCode: "memory_operation_failed",
+				details: memoryAuditDetails(options.operation, "failed", operationId, options.startedDetails)
+			});
+			throw error;
+		}
+		appendAuditEntrySync(options.stateDir, {
+			event: options.event,
+			scope: options.scope,
+			resultStatus: "ok",
+			details: memoryAuditDetails(options.operation, "completed", operationId, options.completedDetails(result))
+		});
+		return result;
+	});
+}
+/** Implements flush audit writes as the local audit log state operation. */
+async function flushAuditWrites() {
+	const pending = Array.from(auditWriteQueues.values());
+	if (pending.length === 0) return;
+	await Promise.allSettled(pending);
+}
+//#endregion
+export { flushAuditWrites as a, recoverInterruptedMutationAttempts as c, runWithMutationAttempt as d, currentMutationAttemptId as i, runWithMemoryAudit as l, appendAuditEntryStrict as n, getAuditPath as o, appendAuditEntrySync as r, getCostPath as s, appendAuditEntry as t, runWithMemoryAuditSync as u };

package/dist/runtime-audit-log-zpQiR9HT.d.ts

@@ -0,0 +1,149 @@
+import "./paths-qVF-5uBq.js";
+//#region src/engine/operations/runtime-audit-log.d.ts
+type AuditEvent = "tool_call" | "hook_trigger" | "kill_switch" | "startup" | "error" | "auto_recall" | "ambient_learning" | "session_summary" | "envelope_strip" | "storage_integrity" | "memory_injected" | "memory_searched" | "memory_read" | "memory_updated" | "memory_superseded" | "memory_deleted" | "memory_purged" | "rem_trigger_evaluated" | "rem_triggered" | "rem_completed" | "rem_failed";
+type AuditStatus = "ok" | "error" | "skipped" | "partial";
+interface AuditEntry {
+  timestamp: string;
+  event: AuditEvent;
+  tool?: string;
+  hook?: string;
+  scope?: string;
+  resultStatus: AuditStatus;
+  errorCode?: string;
+  durationMs?: number;
+  decision?: string;
+  details?: Record<string, unknown>;
+}
+type MemoryAuditEvent = "memory_injected" | "memory_searched" | "memory_read" | "memory_updated" | "memory_superseded" | "memory_deleted" | "memory_purged";
+type MemoryAuditPhase = "started" | "completed" | "failed";
+type MemoryAuditDetailBase = {
+  operation: string;
+  audit_phase: MemoryAuditPhase;
+  audit_operation_id: string;
+};
+type MutationAttemptOutcome = "committed" | "preserved-without-adjudication" | "repaired-merge-text" | "refused-by-authority" | "failed" | "interrupted-unknown" | "no-mutation";
+type MutationAttemptWriter = "profile-section" | "task-lifecycle" | "legacy-profile-refusal";
+type MutationAuditDetail = {
+  mutation_writer?: MutationAttemptWriter;
+  mutation_subject?: string;
+  mutation_outcome?: MutationAttemptOutcome;
+  refusal_reason?: string;
+};
+interface MemoryAuditDetailsByEvent {
+  memory_injected: MemoryAuditDetailBase & {
+    scope?: string;
+    category?: string;
+    lane?: string;
+    count?: number;
+    memory_ids?: string[];
+    write_outcome?: "created" | "existing" | "mixed";
+    created_count?: number;
+    existing_count?: number;
+  };
+  memory_searched: MemoryAuditDetailBase & {
+    scope?: string | string[];
+    query_kind?: string;
+    requested_count?: number;
+    result_count?: number;
+    memory_ids?: string[];
+  };
+  memory_read: MemoryAuditDetailBase & {
+    scope?: string;
+    requested_count?: number;
+    result_count?: number;
+    memory_ids?: string[];
+    requested_fact_id?: string;
+    resolved_fact_id?: string;
+    fact_ids?: string[];
+    found?: boolean;
+    outcome?: string;
+  };
+  memory_updated: MemoryAuditDetailBase & MutationAuditDetail & {
+    scope?: string;
+    requested_count?: number;
+    result_count?: number;
+    memory_ids?: string[];
+    outcome?: string;
+    migration_status?: "migrated" | "noop";
+    rewritten_rows?: number;
+    checked_rows?: number;
+  };
+  memory_superseded: MemoryAuditDetailBase & MutationAuditDetail & {
+    scope?: string;
+    replacement_memory_id?: string;
+    closed_memory_ids?: string[];
+    write_outcome?: "created" | "existing";
+  };
+  memory_deleted: MemoryAuditDetailBase & {
+    scope?: string;
+    deleted_memory_ids?: string[];
+    delete_reason?: string;
+    count?: number;
+    outcome?: "deleted" | "noop";
+    removed_files?: number;
+  };
+  memory_purged: MemoryAuditDetailBase & {
+    target_fact_id?: string;
+    purged_fact_ids?: string[];
+    failed_fact_ids?: string[];
+    status?: "complete" | "partial" | "blocked";
+    blocked_reason?: string;
+  };
+}
+type MemoryAuditDetailInput<E extends MemoryAuditEvent> = Partial<Omit<MemoryAuditDetailsByEvent[E], keyof MemoryAuditDetailBase>>;
+interface MemoryAuditRunOptions<T, E extends MemoryAuditEvent> {
+  stateDir: string;
+  event: E;
+  operation: string;
+  scope?: string;
+  startedDetails?: MemoryAuditDetailInput<E>;
+  run: () => Promise<T>;
+  completedDetails: (result: T) => MemoryAuditDetailInput<E>;
+}
+interface MemoryAuditSyncRunOptions<T, E extends MemoryAuditEvent> {
+  stateDir: string;
+  event: E;
+  operation: string;
+  scope?: string;
+  startedDetails?: MemoryAuditDetailInput<E>;
+  run: () => T;
+  completedDetails: (result: T) => MemoryAuditDetailInput<E>;
+}
+interface MutationAttemptCompletion {
+  outcome: MutationAttemptOutcome;
+  refusalReason?: string;
+}
+interface MutationAttemptRunOptions<T> {
+  stateDir: string;
+  event: "memory_updated" | "memory_superseded";
+  operation: string;
+  writer: MutationAttemptWriter;
+  subject?: string;
+  run: () => Promise<T>;
+  completedOutcome: (result: T) => MutationAttemptCompletion;
+  failedOutcome?: (error: unknown) => MutationAttemptCompletion;
+}
+/** Returns audit path from audit log state state without side effects. */
+declare function getAuditPath(stateDir: string): string;
+/** Returns cost path from audit log state state without side effects. */
+declare function getCostPath(stateDir: string): string;
+/** Persists audit entry through the single audit log state write path. */
+declare function appendAuditEntry(stateDir: string, entry: Omit<AuditEntry, "timestamp">): void;
+/** Waits for the audit append; failures are logged without blocking the operation. */
+declare function appendAuditEntryStrict(stateDir: string, entry: Omit<AuditEntry, "timestamp">): Promise<boolean>;
+/** Attempts a synchronous audit append and logs a failure. */
+declare function appendAuditEntrySync(stateDir: string, entry: Omit<AuditEntry, "timestamp">): void;
+/** Records the start and outcome without using audit availability as admission. */
+declare function runWithMemoryAudit<T, E extends MemoryAuditEvent>(options: MemoryAuditRunOptions<T, E>): Promise<T>;
+/** Closes mutation attempts whose process stopped before a terminal audit record was written. */
+declare function recoverInterruptedMutationAttempts(stateDir: string): Promise<string[]>;
+/** Runs one mutation under a durable open record and exactly one terminal outcome. */
+declare function runWithMutationAttempt<T>(options: MutationAttemptRunOptions<T>): Promise<T>;
+/** Returns the durable identifier owned by the current mutation boundary. */
+declare function currentMutationAttemptId(): string;
+/** Runs a synchronous memory operation only after its durable start record is persisted. */
+declare function runWithMemoryAuditSync<T, E extends MemoryAuditEvent>(options: MemoryAuditSyncRunOptions<T, E>): T;
+/** Implements flush audit writes as the local audit log state operation. */
+declare function flushAuditWrites(): Promise<void>;
+//#endregion
+export { runWithMutationAttempt as S, getAuditPath as _, MemoryAuditEvent as a, runWithMemoryAudit as b, MutationAttemptCompletion as c, MutationAttemptWriter as d, appendAuditEntry as f, flushAuditWrites as g, currentMutationAttemptId as h, MemoryAuditDetailsByEvent as i, MutationAttemptOutcome as l, appendAuditEntrySync as m, AuditEvent as n, MemoryAuditRunOptions as o, appendAuditEntryStrict as p, AuditStatus as r, MemoryAuditSyncRunOptions as s, AuditEntry as t, MutationAttemptRunOptions as u, getCostPath as v, runWithMemoryAuditSync as x, recoverInterruptedMutationAttempts as y };