memhtml 0.1.0

package/dist/memhtml-mcp.mjs

@@ -0,0 +1,4077 @@
+#!/usr/bin/env node
+import { A as makeIndexRecorder, B as makeGitPort, C as ModelClientLive, D as EMBED_DIM, E as EmbeddingsLive, F as reinforce, G as STATE_MIGRATIONS_DIR, H as DatabaseService, I as Indexer, J as expandRoot, L as makeIndexer, N as Retrieval, O as EMBED_WATERMARK, P as makeRetrieval, Q as STATE_DB_PATH, R as readIndexState, S as ModelClient, T as Embeddings, U as makeDatabase, V as sanitizeFtsQuery, W as MIGRATIONS_DIR, X as INDEX_DB_PATH, Y as makeStore, Z as SLEEP_REPORTS_DIR, ct as isValidDatetime, dt as REINFORCE_SIGNALS, ft as frameKeyOf, i as makeSleep, it as makeGit, k as IndexRecorder, lt as closesFence, q as Store, r as Sleep, rt as Git, ut as fenceOpeningOf, v as SLEEP_PHASES, w as wrapAsData, z as IndexGit } from "./dist-CrYVXFO2.mjs";
+import { B as ModelUnavailable, G as MEMORY_RELS, H as StorageFailure, J as relClassFor, K as TASK_RELS, N as hasConsolidatorCredentials, R as InvalidMemory, gt as TASK_STATUSES, i as makeConsolidator, mt as PARA_BUCKETS, ot as normalizePath, q as isEdgeRel, vt as WRITABLE_MEMORY_TYPES, yt as isTaskStatus } from "./dist-DUuomISL.mjs";
+import { createRequire } from "node:module";
+import { Config, Context, Effect, Layer, Logger, Schema } from "effect";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { NodeRuntime, NodeStdio } from "@effect/platform-node";
+import { McpProtocol, McpSchema, McpServer, Tool, Toolkit } from "effect/unstable/ai";
+
+//#region apps/cli/dist/serve.js
+/** An explicit path to the server, for a deployment that does not keep the two apps side by side. */
+const MCP_BIN_VAR = "MEMHTML_MCP_BIN";
+
+//#endregion
+//#region apps/cli/dist/config.js
+const CONFIG_VARS = [
+	{
+		name: "MEMHTML_ROOT",
+		description: "The memory repo's root: a git repository holding the corpus and `.memhtml/`.",
+		fallback: join("~", "memhtml")
+	},
+	{
+		name: "MEMHTML_TRACE_ROOT",
+		description: "Where `memhtml trace index` reads Claude Code transcripts from. Read-only; never written.",
+		fallback: join("~", ".claude")
+	},
+	{
+		name: "MEMHTML_AWS_REGION",
+		description: "The Bedrock region for embeddings and the sleep cycle's four LLM phases.",
+		fallback: "us-east-1"
+	},
+	{
+		name: "AWS_BEARER_TOKEN_BEDROCK",
+		description: "Bedrock bearer token, read by the AWS SDK itself. Absent means the default credential chain; retrieval then degrades to the lexical floor rather than failing.",
+		fallback: null
+	},
+	{
+		name: "MEMHTML_EMBED",
+		description: "`off` disables the embedder entirely. An explicit opt-out, distinct from a missing credential: a missing credential degrades one search at call time, `off` degrades every search, and an operator reading this manifest needs those to be different states.",
+		fallback: "on"
+	},
+	{
+		name: "MEMHTML_LLM",
+		description: "`off` makes the four LLM sleep phases report `no model bound` and stay `ok`, so a credential-free run is honest rather than red.",
+		fallback: "on"
+	},
+	{
+		name: "MEMHTML_EXTRACT_ENTITIES",
+		description: "`on` adds one GPT-5.6 Luna call per write batch that extracts `memhtml-entity` metas the ops did not declare. Opt-in, unlike MEMHTML_EMBED, because it changes what a write STORES: extracted entities land in the files as if authored, and the write itself never waits on or fails with the model. A failed extraction is a logged warning and an unextracted batch.",
+		fallback: "off"
+	},
+	{
+		/**
+		* The name is imported rather than retyped: this row and the `process.env` read at serve.ts:50
+		* must name the same string, and a literal here would let a rename disclose a variable nothing
+		* reads.
+		*/
+		name: MCP_BIN_VAR,
+		description: "An explicit path to the `memhtml-mcp` entry point, read only by the `memhtml serve mcp` supervisor. Absent means the sibling-path default. The two apps ship as one build, so `apps/cli/dist/serve.js` finds `apps/mcp/dist/bin.js` two directories over. An operator sets it for a split deployment that does not keep the apps side by side; it locates the server rather than configuring the store, so it changes no retrieval behaviour.",
+		fallback: null
+	}
+];
+/**
+* `MEMHTML_ROOT`. Re-exported from `@memhtml/store`'s own config rather than redeclared, because the
+* store's config expands a leading `~`. This value arrives from a shell profile, an MCP client
+* config, and a cron line, and only the shell expands tildes on its own.
+*/
+const MemhtmlRoot = Config.string("MEMHTML_ROOT").pipe(Config.withDefault(join("~", "memhtml")), Config.map(expandRoot));
+/**
+* `MEMHTML_TRACE_ROOT`, defaulting to `~/.claude`.
+*
+* A parameter rather than a constant so the trace indexer is drivable against a fixture tree and
+* against an archived copy, which is also what keeps real transcripts out of the test suite.
+*/
+const TraceRoot = Config.string("MEMHTML_TRACE_ROOT").pipe(Config.withDefault(join(homedir(), ".claude")), Config.map(expandRoot));
+
+//#endregion
+//#region apps/cli/dist/extraction.js
+/**
+* GPT-5.6 Luna, the fast high-volume model on the mantle endpoint. A constant rather than config
+* because the schema below is tested against this model's strict-mode behaviour. Changing the model
+* is a code change with a test run, not an env var.
+*/
+const EXTRACTION_MODEL_ID = "openai.gpt-5.6-luna";
+/**
+* The strict output schema. `additionalProperties: false` and `required` on every level because
+* the Responses API's `strict: true` demands both, and a lax schema invites the model to answer
+* with prose keys the parser would then be guessing at.
+*/
+const RESPONSE_SCHEMA = {
+	type: "object",
+	properties: { items: {
+		type: "array",
+		items: {
+			type: "object",
+			properties: {
+				index: { type: "integer" },
+				entities: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							type: {
+								type: "string",
+								enum: [...[
+									"person",
+									"org",
+									"service",
+									"place",
+									"work",
+									"concept",
+									"event"
+								]]
+							},
+							name: { type: "string" }
+						},
+						required: ["type", "name"],
+						additionalProperties: false
+					}
+				}
+			},
+			required: ["index", "entities"],
+			additionalProperties: false
+		}
+	} },
+	required: ["items"],
+	additionalProperties: false
+};
+const INSTRUCTIONS = "Extract the named entities each memory mentions. An entity is a specific nameable thing a later search would look up: a person, an organization, a service or system, a place, a titled work, a defined concept, or a named event. Skip generic nouns, dates, and quantities. Use the memory's own spelling for the name. Return one result per input index, with an empty entities array when a memory names nothing.";
+/** The request body for one batch. Exported for the wire test, where the schema is the contract. */
+const requestBodyOf = (modelId, items) => JSON.stringify({
+	model: modelId,
+	instructions: INSTRUCTIONS,
+	input: wrapAsData("memories", JSON.stringify(items.map((item, index) => ({
+		index,
+		title: item.title,
+		text: item.text
+	})))),
+	text: { format: {
+		type: "json_schema",
+		name: "entities",
+		strict: true,
+		schema: RESPONSE_SCHEMA
+	} }
+});
+/**
+* Decode one Responses-API payload into index-aligned `type:name` arrays.
+*
+* Total over unknown input: every malformed shape returns `undefined` and the caller maps that to
+* `ModelUnavailable`. A payload this code cannot read carries no answer, and treating it as
+* "no entities" would record a model failure as a fact about the corpus.
+*/
+const entitiesOf = (payload, expected) => {
+	const text = outputTextOf(payload);
+	if (text === void 0) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return;
+	}
+	const items = parsed.items;
+	if (!Array.isArray(items)) return void 0;
+	const results = Array.from({ length: expected }, () => []);
+	for (const item of items) {
+		const index = item.index;
+		const entities = item.entities;
+		if (typeof index !== "number" || !Number.isInteger(index) || index < 0 || index >= expected) continue;
+		if (!Array.isArray(entities)) continue;
+		results[index] = entities.flatMap((entity) => {
+			const type = entity.type;
+			const name = entity.name;
+			if (typeof type !== "string" || typeof name !== "string") return [];
+			const trimmedName = name.trim();
+			return trimmedName === "" ? [] : [`${type}:${trimmedName}`];
+		});
+	}
+	return results;
+};
+/** The assistant message text out of a Responses payload, or `undefined` off-shape. */
+const outputTextOf = (payload) => {
+	const output = payload.output;
+	if (!Array.isArray(output)) return void 0;
+	for (const entry of output) {
+		if (entry.type !== "message") continue;
+		const content = entry.content;
+		if (!Array.isArray(content)) continue;
+		for (const part of content) {
+			const text = part.text;
+			if (part.type === "output_text" && typeof text === "string") return text;
+		}
+	}
+};
+/**
+* Per-call ceiling. Generous against the probed ~1s because a batch of 256 ops is a bigger
+* prompt than the probe's one sentence, and a late abort costs only this batch's entities. The
+* write itself is unaffected.
+*/
+const EXTRACT_TIMEOUT_MS = 6e4;
+/** The extractor over a transport. The transport owns the endpoint; this owns prompt and parse. */
+const makeEntityExtractor = (transport, modelId) => ({ extract: (items) => items.length === 0 ? Effect.succeed([]) : Effect.gen(function* () {
+	const payload = yield* Effect.tryPromise({
+		try: (signal) => {
+			const timeout = AbortSignal.timeout(EXTRACT_TIMEOUT_MS);
+			return transport.post(requestBodyOf(modelId, items), AbortSignal.any([signal, timeout]));
+		},
+		catch: (cause) => ModelUnavailable.make({
+			modelId,
+			reason: cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause)
+		})
+	});
+	const entities = entitiesOf(payload, items.length);
+	if (entities === void 0) return yield* Effect.fail(ModelUnavailable.make({
+		modelId,
+		reason: "unreadable extraction payload"
+	}));
+	return entities;
+}) });
+/**
+* The production transport: bearer-token fetch against the mantle endpoint.
+*
+* A non-2xx status is a rejection carrying the status and the body's first line, because mantle
+* reports quota and auth failures as structured JSON the operator needs verbatim. Folding it into
+* a generic message was the mistake the embeddings lane made first.
+*/
+const fetchMantleTransport = (region, token) => ({ post: async (body, signal) => {
+	const response = await fetch(`https://bedrock-mantle.${region}.api.aws/openai/v1/responses`, {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${token}`,
+			"Content-Type": "application/json"
+		},
+		body,
+		signal
+	});
+	const text = await response.text();
+	if (!response.ok) throw new Error(`mantle ${response.status}: ${text.slice(0, 200)}`);
+	return JSON.parse(text);
+} });
+
+//#endregion
+//#region apps/cli/dist/api-layer.js
+const Roots = Context.Service("memhtml/Roots");
+/**
+* The roots layer. `repoOverride` is `--repo`, and it wins over `MEMHTML_ROOT` so an operator running
+* against a second repo does not have to mutate their environment to do it.
+*/
+const layerRoots = (repoOverride) => Layer.effect(Roots)(Effect.gen(function* () {
+	const fromConfig = yield* MemhtmlRoot;
+	const traceRoot = yield* TraceRoot;
+	return {
+		memhtmlRoot: repoOverride !== void 0 && repoOverride.trim() !== "" ? repoOverride.trim() : fromConfig,
+		traceRoot
+	};
+})).pipe(Layer.orDie);
+/**
+* The database, rooted in the repo's `.memhtml/`.
+*
+* Both planes on one connection, always. The salience retrieval arm `LEFT JOIN`s `state.access`
+* in the same statement as `main.files`, so a connection without the attachment silently drops
+* that arm. `DatabaseShape.hasState` is what the arm registry consults, and it is `false` only
+* for a caller that deliberately asked for the index alone.
+*/
+const layerDatabase = Layer.effect(DatabaseService)(Effect.gen(function* () {
+	const roots = yield* Roots;
+	return yield* makeDatabase(join(roots.memhtmlRoot, INDEX_DB_PATH), MIGRATIONS_DIR, {
+		path: join(roots.memhtmlRoot, STATE_DB_PATH),
+		migrationsDir: STATE_MIGRATIONS_DIR
+	});
+})).pipe(Layer.orDie);
+/** Git over the repo root. The store's shape, under the store's own tag. */
+const layerGit = Layer.effect(Git)(Effect.gen(function* () {
+	const roots = yield* Roots;
+	return makeGit(roots.memhtmlRoot);
+}));
+/**
+* The indexer's git port, over the store's git service.
+*
+* `readFile` is `Effect.tryPromise` rather than `Effect.promise`. `Effect.promise` turns an ENOENT
+* into a defect, and a defect travels past the `Effect.catch` the indexer wraps each projection in.
+* An absent path would then kill the fiber mid-update instead of becoming the counted skip the indexer
+* already handles. An agent listing a path it just archived is the normal case, which makes this
+* the difference between a working `index update` and a crash on an ordinary day.
+*/
+const layerIndexGit = Layer.effect(IndexGit)(Effect.gen(function* () {
+	const roots = yield* Roots;
+	const git = yield* Git;
+	return makeGitPort({
+		git,
+		readFile: (path) => Effect.tryPromise({
+			try: () => readFile(join(roots.memhtmlRoot, path), "utf8"),
+			catch: (cause) => cause
+		}),
+		fail: (operation) => Effect.fail(StorageFailure.make({ operation: `git.${operation}` }))
+	});
+}));
+/** The recorder: the dedupe lookup the store gates writes on, and the session-link writer. */
+const layerRecorder = Layer.effect(IndexRecorder)(Effect.gen(function* () {
+	const db = yield* DatabaseService;
+	return makeIndexRecorder(db);
+}));
+/**
+* The store, with the recorder's dedupe hook attached.
+*
+* `onMove` mirrors `state.access.path` across an archive. Cross-database foreign keys do not
+* exist, so the mirror is an explicit call at the one place a path can change; without it every
+* eviction leaves an orphan access row and the salience arm stops finding the memory it describes.
+*/
+const layerStore = Layer.effect(Store)(Effect.gen(function* () {
+	const git = yield* Git;
+	const recorder = yield* IndexRecorder;
+	const db = yield* DatabaseService;
+	return makeStore(git, {
+		dedupeLookup: recorder.activePathForHash,
+		onMove: (from, to) => db.run("UPDATE state.access SET path = ? WHERE path = ?", [to, from]).pipe(Effect.catch((error) => Effect.logWarning(`state.access mirror missed ${from} -> ${to}: ${error.operation}`)))
+	});
+}));
+const Embedder = Context.Service("memhtml/Embedder");
+/**
+* Bedrock embeddings when the region resolves, absent when `MEMHTML_EMBED` is `off`.
+*
+* The switch is an explicit opt-out rather than credential sniffing. A missing credential is
+* discovered at call time and degrades one search. A deliberate `off` degrades every search, and
+* an operator reading `memhtml manifest` needs those to be different states.
+*/
+const layerEmbedder = Layer.effect(Embedder)(Effect.gen(function* () {
+	if (!(yield* Config.string("MEMHTML_EMBED").pipe(Config.withDefault("on"), Config.map((value) => value.trim().toLowerCase() !== "off")))) return {
+		document: void 0,
+		query: void 0
+	};
+	const embeddings = yield* Embeddings;
+	return {
+		document: embeddings,
+		query: embeddings
+	};
+})).pipe(Layer.orDie);
+/** The indexer, over the database and the git port. */
+const layerIndexer = Layer.effect(Indexer)(Effect.gen(function* () {
+	const db = yield* DatabaseService;
+	const git = yield* IndexGit;
+	const embedder = yield* Embedder;
+	return makeIndexer({
+		db,
+		git,
+		embedWatermark: EMBED_WATERMARK,
+		embedDim: EMBED_DIM,
+		embeddings: embedder.document,
+		now: () => (/* @__PURE__ */ new Date()).toISOString()
+	});
+}));
+/** Retrieval, over the database and the query embedder. */
+const layerRetrieval = Layer.effect(Retrieval)(Effect.gen(function* () {
+	const db = yield* DatabaseService;
+	const embedder = yield* Embedder;
+	return makeRetrieval({
+		db,
+		embeddings: embedder.query
+	});
+}));
+const ModelPort = Context.Service("memhtml/ModelPort");
+const layerModelPort = Layer.effect(ModelPort)(Effect.gen(function* () {
+	if (!(yield* Config.string("MEMHTML_LLM").pipe(Config.withDefault("on"), Config.map((value) => value.trim().toLowerCase() !== "off")))) return { model: void 0 };
+	return { model: yield* ModelClient };
+})).pipe(Layer.orDie);
+const ExtractorPort = Context.Service("memhtml/ExtractorPort");
+const layerExtractorPort = Layer.effect(ExtractorPort)(Effect.gen(function* () {
+	if (!(yield* Config.string("MEMHTML_EXTRACT_ENTITIES").pipe(Config.withDefault("off"), Config.map((value) => value.trim().toLowerCase() === "on")))) return { extractor: void 0 };
+	const region = yield* Config.string("MEMHTML_AWS_REGION").pipe(Config.withDefault("us-east-1"));
+	const token = yield* Config.string("AWS_BEARER_TOKEN_BEDROCK").pipe(Config.withDefault(""));
+	if (token === "") {
+		yield* Effect.logWarning("MEMHTML_EXTRACT_ENTITIES=on but AWS_BEARER_TOKEN_BEDROCK is absent; writes proceed unextracted");
+		return { extractor: void 0 };
+	}
+	return { extractor: makeEntityExtractor(fetchMantleTransport(region, token), EXTRACTION_MODEL_ID) };
+})).pipe(Layer.orDie);
+const ConsolidatorPortService = Context.Service("memhtml/ConsolidatorPort");
+/**
+* Two gates, both cheap, both before anything is spawned.
+*
+* `MEMHTML_LLM=off` is the same explicit opt-out `layerModelPort` reads, and it covers the consolidator
+* too, because an operator who turned the models off did not mean "except the expensive agent".
+*
+* `hasConsolidatorCredentials` is the credential preflight, read here as well as inside the client.
+* The redundancy is deliberate and the two reads do different jobs. This one decides whether the phase
+* sees a consolidator at all, so a credential-free environment gets `detail: "no consolidator bound"`,
+* the same shape the other three LLM phases report with no model, rather than a bound port that
+* fails on every call and reports a degradation. CI has no credentials and must read as skipped rather
+* than degraded.
+*
+* The check cannot be skipped in favour of the client's own, because the provider is lazy.
+* `createAmazonBedrock` and `provider(modelId)` both succeed with zero credentials and nothing fails
+* until the first request (verified in T-EVE-1's probe, recorded at
+* `apps/consolidator/src/contract.ts:301-319`).
+*
+* **`env` is a parameter, and it has to be.** `Config` reads its values through a `ConfigProvider`,
+* which a test substitutes, while `hasConsolidatorCredentials` reads `process.env` directly, and
+* effect's default provider snapshots `process.env` at module load (probed 2026-08-08: mutating
+* `process.env.MEMHTML_LLM` after importing `effect` changes nothing `Config.string` returns). A test
+* that set both by mutation would read a stale snapshot for one gate and a live object for the other,
+* and the two gates would disagree about which environment they are in. Threading the credential
+* environment through as an argument makes both injectable from one call. See
+* `apps/cli/tests/consolidator-wiring.test.ts`, where that disagreement produced a false defect
+* before this parameter existed.
+*
+* **It now requires `RootsShape`, for `traceRoot`.** That is how transcripts reach the agent. The
+* consolidator mounts the trace root read-only rather than sending transcripts as a model message
+* (`apps/consolidator/src/client.ts`, `manifestFor`, records what the superseded path actually did).
+* The root is `MEMHTML_TRACE_ROOT` and this file is where config becomes services, so it is read from the
+* same `Roots` service `memhtml trace index` scans with. One resolution of one variable is what
+* keeps the mounted tree and the indexed `traces` rows describing the same directory. A second
+* `Config.string("MEMHTML_TRACE_ROOT")` here would be a second place the `~/.claude` default lives.
+*/
+const layerConsolidatorPort = (env = process.env) => Layer.effect(ConsolidatorPortService)(Effect.gen(function* () {
+	const roots = yield* Roots;
+	if (!(yield* Config.string("MEMHTML_LLM").pipe(Config.withDefault("on"), Config.map((value) => value.trim().toLowerCase() !== "off")))) return { consolidator: void 0 };
+	if (!hasConsolidatorCredentials(env)) {
+		yield* Effect.logDebug("trace consolidation unbound: no Bedrock credentials in the environment");
+		return { consolidator: void 0 };
+	}
+	/**
+	* The client is built over the same environment the gate just read. A client over ambient
+	* `process.env` while the gate read an injected one would pass the gate and fail at the call,
+	* which is the degradation-instead-of-skip outcome this gate exists to prevent.
+	*/
+	return { consolidator: makeConsolidator({
+		env,
+		traceRoot: roots.traceRoot
+	}) };
+})).pipe(Layer.orDie);
+/**
+* The sleep runner over the same services every other command uses.
+*
+* `@memhtml/sleep` deliberately ships no `SleepLive` that resolves its own git, database, and model.
+* A layer that built its own would open a second connection to one database file and a second git
+* wrapper on one root, and the run would then curate a corpus the indexer is not describing.
+*/
+const layerSleep = Layer.effect(Sleep)(Effect.gen(function* () {
+	const git = yield* Git;
+	const store = yield* Store;
+	const db = yield* DatabaseService;
+	const indexer = yield* Indexer;
+	const modelPort = yield* ModelPort;
+	const consolidatorPort = yield* ConsolidatorPortService;
+	return makeSleep({
+		git,
+		store,
+		db,
+		indexer,
+		model: modelPort.model,
+		consolidator: consolidatorPort.consolidator
+	});
+}));
+/**
+* Everything above the embedder and the model, as one layer requiring only the roots and those two.
+*
+* Written top-down because that is what `Layer.provideMerge(that)` means. It feeds `that`'s output
+* into `self`'s requirements, so the consumer is `self` and each `.pipe` step below adds the level
+* beneath it. Chaining in dependency order instead, with the database first, reads naturally and is
+* wrong. It would provide git to the database and leave `GitShape` in the final requirement set, which
+* typechecks as an unsatisfied layer rather than failing where the mistake is.
+*
+* Split out from `layerApp` so a test provides a deterministic embedder and a real temp repo with
+* no Bedrock anywhere in the graph. The composition under test is then the same composition
+* production runs, which a hand-assembled test wiring would not be.
+*/
+const layerCore = Layer.mergeAll(layerSleep, layerRetrieval).pipe(Layer.provideMerge(Layer.mergeAll(layerIndexer, layerStore)), Layer.provideMerge(Layer.mergeAll(layerIndexGit, layerRecorder)), Layer.provideMerge(Layer.mergeAll(layerDatabase, layerGit)));
+/**
+* The production graph: roots from config, Bedrock behind both model ports, everything else over
+* them. `repoOverride` is `--repo`.
+*
+* This is the one composition production runs. `memhtml serve mcp` runs the same one in a child
+* process, so an MCP tool and its CLI twin cannot be looking at different databases.
+*/
+const layerApp = (repoOverride) => layerCore.pipe(Layer.provideMerge(Layer.mergeAll(
+	layerRoots(repoOverride),
+	layerEmbedder.pipe(Layer.provide(EmbeddingsLive), Layer.orDie),
+	layerModelPort.pipe(Layer.provide(ModelClientLive), Layer.orDie),
+	layerExtractorPort,
+	/**
+	* `layerRoots` is provided to the consolidator port explicitly rather than merged beside it.
+	* The consolidator needs `traceRoot` to mount, and a sibling in one `mergeAll` is not a
+	* dependency. The roots layer is built once with `repoOverride` and fed in, so a `--repo`
+	* run and the mounted trace root cannot come from two different resolutions.
+	*/
+	layerConsolidatorPort().pipe(Layer.provide(layerRoots(repoOverride)))
+)));
+
+//#endregion
+//#region apps/cli/dist/errors.js
+const isTagged$1 = (value) => typeof value === "object" && value !== null && typeof value._tag === "string";
+const text$1 = (value) => typeof value === "string" ? value : void 0;
+const paths = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+/**
+* The code for a tag.
+*
+* `GitFailure` lives in `@memhtml/store` rather than `@memhtml/contracts`. It is the one error class
+* outside the shared contracts package, because it carries a git subcommand name and only the store
+* speaks git. It maps to `ERR_GIT` here at the CLI edge, the only place the two vocabularies meet.
+*
+* `EmbedModelMismatch` is a plain class rather than a schema error (it predates the contracts
+* package), so it arrives with the same `_tag` shape and needs no special case.
+*/
+const codeFor = (error) => {
+	if (!isTagged$1(error)) return "ERR_UNKNOWN";
+	switch (error._tag) {
+		case "GitFailure": return "ERR_GIT";
+		case "StorageFailure": return "ERR_STORAGE";
+		case "InvalidMemory": return "ERR_INVALID_MEMORY";
+		case "PathNotFound": return "ERR_PATH_NOT_FOUND";
+		case "WriteConflict": return "ERR_WRITE_CONFLICT";
+		case "DirtyTree": return "ERR_DIRTY_TREE";
+		case "DuplicateContent": return "ERR_DUPLICATE_CONTENT";
+		case "ModelUnavailable": return "ERR_MODEL_UNAVAILABLE";
+		case "EmbedModelMismatch": return "ERR_EMBED_MODEL_MISMATCH";
+		case "DiscriminationFailed": return "ERR_DISCRIMINATION_FAILED";
+		default: return "ERR_UNKNOWN";
+	}
+};
+/**
+* The human message for a failure.
+*
+* Deliberately narrow. Every payload field named here is one a caller can act on: a path to
+* re-read, two shas to reconcile, a model to check. The message omits the driver's own text, the
+* SQL, the git argv, and any memory body. Each typed error class already dropped those at its
+* adapter edge so a tool response could not carry corpus content, and reconstructing them here
+* would undo that.
+*/
+const messageFor = (error) => {
+	if (!isTagged$1(error)) return String(error);
+	switch (error._tag) {
+		case "GitFailure": return `git ${text$1(error.command) ?? "command"} failed (exit ${String(error.exitCode)})`;
+		case "StorageFailure": return `storage operation failed: ${text$1(error.operation) ?? "unknown"}`;
+		case "InvalidMemory": return `invalid memory: ${text$1(error.reason) ?? "unstated reason"}`;
+		case "PathNotFound": return `no memory at ${text$1(error.path) ?? "the given path"}`;
+		case "WriteConflict": return `write conflict on ${text$1(error.path) ?? "a path"}: ours ${text$1(error.ourSha) ?? "?"}, theirs ${text$1(error.theirSha) ?? "?"}`;
+		case "DirtyTree": return `the working tree has uncommitted changes: ${paths(error.paths).join(", ")}`;
+		case "DuplicateContent": return `this content already lives at ${text$1(error.existingPath) ?? "another path"}`;
+		case "ModelUnavailable": return `bedrock refused ${text$1(error.modelId) ?? "the model"}: ${text$1(error.reason) ?? "no reason given"}`;
+		case "EmbedModelMismatch": return `the index was built in vector space ${text$1(error.stored) ?? "?"}, configured is ${text$1(error.configured) ?? "?"}`;
+		case "LlmContractViolation": return `the model broke its structured-output contract: ${text$1(error.reason) ?? "no reason given"}`;
+		case "DiscriminationFailed": return text$1(error.reason) ?? "the discrimination gate refused";
+		default: return `unexpected failure: ${error._tag}`;
+	}
+};
+
+//#endregion
+//#region apps/cli/dist/operations.js
+/**
+* The use cases, one per tool. Every CLI command and every MCP tool is a thin adapter over exactly
+* one of these, which makes `memhtml search` and `memory_search` provably the same query
+* rather than two implementations that agree today.
+*
+* Nothing here parses argv or builds an envelope. A function takes decoded parameters, returns a
+* typed result, and fails with a typed error. The adapters own the shape of the wire.
+*/
+/** Wall-clock as an ISO-8601 UTC second, through the Effect clock so a test can pin it. */
+const nowSecond$1 = Effect.clockWith((clock) => Effect.map(clock.currentTimeMillis, (millis) => `${new Date(millis).toISOString().slice(0, 19)}Z`));
+/** Drop `undefined`-valued keys, so `exactOptionalPropertyTypes` sees an absent key. */
+const defined = (input) => {
+	const out = {};
+	for (const [key, value] of Object.entries(input)) if (value !== void 0) out[key] = value;
+	return out;
+};
+/**
+* Narrow an untrusted memory-type string.
+*
+* `arc` is refused even though it is a valid storage type. An arc is synthesized by the sleep
+* cycle from many memories, so an agent naming one directly would be asserting a conclusion the
+* corpus has not earned. The vocabulary the tool exposes is therefore narrower than the CHECK
+* constraint by exactly that one value.
+*/
+const decodeWritableType = (value) => WRITABLE_MEMORY_TYPES.includes(value) ? Effect.succeed(value) : Effect.fail(InvalidMemory.make({ reason: `unknown memory type: ${value}. One of: ${WRITABLE_MEMORY_TYPES.join(", ")}` }));
+/**
+* The rels a CALLER may author: the nine memory rels plus the two task rels.
+*
+* The two classes the vocabulary withholds are the ones the system mints itself. A `person` edge is
+* written by sleep's person-links phase against `resources/people/*`, and `from_session` is written
+* by the write path from the provenance a caller already supplied. Authoring either by hand would put
+* a hand-guessed row where a derivation belongs.
+*/
+const AUTHORABLE_RELS = [...MEMORY_RELS, ...TASK_RELS];
+/**
+* Narrow an untrusted rel to one a caller may author.
+*
+* A `blocks` edge between two tasks is a legitimate authored assertion, so the task class is in and
+* refusing it would leave the task graph writable by nothing. Whether the rel agrees with its
+* endpoints is not this function's business. `@memhtml/store`'s `linkMemories` reads both files'
+* `memhtml-type` and refuses a mismatch, and it is the only layer that can see the endpoints at all.
+*
+* `memory_link`'s MCP schema stays memory-rels-only (`MemoryRelSchema`, `apps/mcp/src/tools.ts`) and
+* refuses a task rel at decode. That is one narrow surface for agents and one wider one for the
+* operator, with the store's endpoint guard governing both.
+*/
+const decodeAuthorableRel = (value) => isEdgeRel(value) && AUTHORABLE_RELS.includes(value) ? Effect.succeed(value) : Effect.fail(InvalidMemory.make({ reason: `unknown rel: ${value}. One of: ${AUTHORABLE_RELS.join(", ")}` }));
+/** Narrow an untrusted task status. */
+const decodeTaskStatus = (value) => isTaskStatus(value) ? Effect.succeed(value) : Effect.fail(InvalidMemory.make({ reason: `unknown task status: ${value}. One of: ${TASK_STATUSES.join(", ")}` }));
+/**
+* Narrow an untrusted due date, using the FORMAT's own validator.
+*
+* `isValidDatetime` rather than a local regex or `Date.parse`, because `files.due_at` is compared and
+* ordered as a string. `2026-8-9` and `Aug 9 2026` both parse as instants and neither sorts alongside
+* `2026-08-09`, so the overdue query would silently miss them. Reusing the parser's own validator is
+* also what keeps this refusal and the parser's violation from drifting apart.
+*/
+const decodeDueAt = (value) => isValidDatetime(value) ? Effect.succeed(value) : Effect.fail(InvalidMemory.make({ reason: `due date is not an ISO date or datetime: ${value}. Expected YYYY-MM-DD or YYYY-MM-DDThh:mm:ssZ` }));
+/** Narrow an untrusted reinforcement signal. */
+const decodeSignal = (value) => REINFORCE_SIGNALS.includes(value) ? Effect.succeed(value) : Effect.fail(InvalidMemory.make({ reason: `unknown signal: ${value}. One of: ${REINFORCE_SIGNALS.join(", ")}` }));
+/**
+* Record the session link for an operation that touched a path.
+*
+* Fire-and-log rather than fail-the-call. The link is a note about what happened, and losing the
+* memory over a failed note about it would invert the priority. The file's own head already
+* carries `memhtml-session`/`memhtml-prompt`/`memhtml-turn`, so the durable half of the link survives even
+* when this row does not.
+*/
+const recordLink = (path, linkKind, provenance, at) => Effect.gen(function* () {
+	if (provenance.sessionId === void 0 || provenance.sessionId === "") return;
+	yield* (yield* IndexRecorder).recordLink({
+		path,
+		sessionId: provenance.sessionId,
+		linkKind,
+		at,
+		...defined({
+			promptId: provenance.promptId,
+			turnUuid: provenance.turnUuid
+		})
+	}).pipe(Effect.catch((error) => Effect.logWarning(`session link not recorded for ${path}: ${error.operation}`)));
+});
+/**
+* Bring the index up to the commit a write just made.
+*
+* `indexer.update()` rather than `indexPaths([…])`, and the difference changes behaviour twice:
+*
+* 1. **`indexPaths` cannot express a rename.** Every correction and every archive is a `git mv`, and
+*    an index that handled one as "index the destination" leaves the source row live. The archived
+*    memory stays in `memhtml list`, `files` gains a row the tree does not have, and the chunk rows the
+*    move exists to preserve are duplicated under two paths. `update()` reads `diff --name-status -M`,
+*    sees the `R`, and re-points the row, which keeps the embedding and drops nothing.
+* 2. **`indexPaths` never records the watermark.** `index_state.head_sha` is what makes
+*    "the index describes the current commit" answerable at all, so a write path that skipped it
+*    would leave `memhtml status` reporting `index_fresh: false` forever and `index update` re-deriving
+*    from a stale base.
+*
+* The cost is one `git diff` over one commit, which is what the watermark exists to bound. On the
+* very first write the watermark is absent and `update()` falls through to a full rebuild. That is
+* correct, and cheap on a corpus that has one file in it.
+*/
+const reindex = () => Effect.gen(function* () {
+	return yield* (yield* Indexer).update({ embed: true });
+});
+/**
+* Decode untrusted write parameters into the store's `WriteInput`.
+*
+* Shared by {@link writeMemory} and {@link batchWrite}, and the sharing matters. A batch that
+* re-derived this would be a second decode of the same vocabulary, and the two would agree today
+* and drift the first time a field is added. This is `symspec`'s lesson stated as code: the batch
+* folds the singular's own decode rather than a parallel one.
+*
+* The two task metas are decoded here, before any file is rendered, and only for a task.
+* `@memhtml/html`'s parser refuses `memhtml-task-status` on a non-task and refuses a `memhtml-due` that is not
+* an ISO datetime, so a bad value passed through would render a file the indexer then declines to
+* project. That file is present in the tree, absent from every search, and visible only as a log
+* line. Deciding here turns it into a typed `InvalidMemory` before the commit.
+*/
+const toWriteInput = (params, at) => Effect.gen(function* () {
+	const memoryType = yield* decodeWritableType(params.memoryType);
+	const taskStatus = memoryType === "task" && params.taskStatus !== void 0 && params.taskStatus !== "" ? yield* decodeTaskStatus(params.taskStatus) : void 0;
+	const dueAt = memoryType === "task" && params.dueAt !== void 0 && params.dueAt !== "" ? yield* decodeDueAt(params.dueAt) : void 0;
+	return {
+		title: params.title,
+		claim: params.claim,
+		memoryType,
+		at,
+		...defined({
+			body: params.body,
+			articleHtml: params.articleHtml,
+			path: params.path,
+			workspace: params.workspace,
+			tags: params.tags,
+			entities: params.entities,
+			importance: params.importance,
+			confidence: params.confidence,
+			sessionId: params.sessionId,
+			promptId: params.promptId,
+			turnUuid: params.turnUuid,
+			taskStatus,
+			dueAt
+		})
+	};
+});
+/**
+* Write one memory: render, dedupe, commit, index.
+*
+* On a dedupe nothing is indexed, because nothing changed. A dedupe writes no file, stages nothing,
+* and commits nothing, so the tree is byte-identical and the index already describes it.
+*/
+const writeMemory = (params) => Effect.gen(function* () {
+	const store = yield* Store;
+	const at = yield* nowSecond$1;
+	const result = yield* store.writeMemory(yield* toWriteInput(params, at));
+	if (result.created) yield* reindex();
+	yield* recordLink(result.path, "wrote", params, at);
+	return result;
+});
+/**
+* A typed failure as a per-op report, through the same `codeFor`/`messageFor` every envelope error
+* takes.
+*
+* Mapped here rather than in each door, deliberately. A per-op code is part of the batch's payload
+* rather than of the envelope, so two doors shaping it independently is two mappings that agree today.
+* `memhtml apply` and `memory_write_batch` reporting different codes for the same refused op is
+* the drift the shared-use-case rule exists to prevent.
+*/
+const reportFailure = (index, error) => ({
+	index,
+	ok: false,
+	code: codeFor(error),
+	error: messageFor(error)
+});
+/**
+* The `detect_conflicts` assist: which claim, if any, each op's own claim contradicts.
+*
+* **Propose-only, and that is the design rather than a v1 limitation.** The function returns a report
+* per op index and writes nothing, stages nothing, and refuses nothing, because sometimes the
+* contradiction is the answer. A memory recording that a runbook step changed necessarily contradicts
+* the memory stating the old step, and an assist that auto-archived, applied last-wins, or blocked the
+* write would destroy the pair a later reader needs to see the change in. The caller decides: write
+* anyway, `memory_correct` the match, or skip.
+*
+* **One query for the whole batch.** Every op's frame key is collected first and `activeFramesFor` is
+* called once with all of them. The signature takes an array so a caller cannot loop, and a
+* per-op lookup would be the quadratic-write-cost pattern this codebase has already paid for once.
+*
+* **Two match sources, checked in that order.** The store answers for active non-task memories. Its
+* predicate, and 0009's index, exclude archived rows and tasks, because an archived claim is not a
+* competing assertion and an open to-do phrased as a claim is working state rather than knowledge. Then
+* come the batch's own earlier ops, folded as this loop walks them in order. Two ops in one call can
+* occupy the same slot, and neither is in the store yet, so nothing but this fold can see that pair. A
+* store match wins when an op has both, because the store's memory is a fact already in the corpus
+* while the earlier op is one this same call is about to create.
+*
+* **A later op reports on an earlier one, never the reverse.** The fold is asymmetric on purpose. Op 3
+* matching op 1 tells a caller "you are about to restate something you just said", which is actionable
+* with op 3 still in hand. Reporting it on op 1 as well would name a conflict with something that did
+* not exist when op 1 was written, and would double one finding into two.
+*
+* **A lookup failure degrades to no conflicts.** The assist is a note about the writes, so losing the
+* memories over a failed note about them would invert the priority as it would for
+* {@link recordLink} and {@link bumpAccess}, with the same `Effect.catch` → `logWarning` → neutral value.
+* The write path never sees this function's failure, which makes "the assist cannot block a
+* write" true structurally rather than by review.
+*/
+const detectFrameConflicts = (ops) => Effect.gen(function* () {
+	/**
+	* `frameKeyOf(op.claim)` per op, computed once and kept alongside the index.
+	*
+	* On the `article_html` path `claim` is `""` by construction, because both doors leave it empty and
+	* the `<mark>` inside the markup is the claim. `frameKeyOf` therefore returns null and a markup op
+	* gets no assist. Deriving one here would mean parsing every op's article at the ops layer, a second
+	* render of bytes the store is about to render anyway. The boundary is stated in the tool
+	* description instead of hidden behind a duplicate parse.
+	*/
+	const keyed = [];
+	for (const [index, op] of ops.entries()) {
+		const key = frameKeyOf(op.claim);
+		if (key !== null) keyed.push({
+			index,
+			key,
+			claim: op.claim
+		});
+	}
+	if (keyed.length === 0) return /* @__PURE__ */ new Map();
+	const live = yield* (yield* IndexRecorder).activeFramesFor(keyed.map((entry) => entry.key)).pipe(Effect.catch((error) => Effect.logWarning(`conflict assist skipped: ${error.operation}`).pipe(Effect.as(/* @__PURE__ */ new Map()))));
+	const conflicts = /* @__PURE__ */ new Map();
+	/** frame key → the first op in this batch to occupy it. Built as the loop walks in order. */
+	const seen = /* @__PURE__ */ new Map();
+	for (const entry of keyed) {
+		const [stored] = live.get(entry.key) ?? [];
+		const earlier = seen.get(entry.key);
+		if (stored !== void 0) conflicts.set(entry.index, {
+			path: stored.path,
+			batchIndex: null,
+			claim: stored.gist
+		});
+		else if (earlier !== void 0) conflicts.set(entry.index, {
+			path: null,
+			batchIndex: earlier.index,
+			claim: earlier.claim
+		});
+		if (earlier === void 0) seen.set(entry.key, {
+			index: entry.index,
+			claim: entry.claim
+		});
+	}
+	return conflicts;
+});
+/**
+* Fold last-wins over the caller's op array, before the decode fold, so a batch-internal loser
+* never reaches disk. The surviving value simply occupies the earliest slot with that key.
+*
+* Not derived from {@link detectFrameConflicts}' output, although the walk mirrors it. A store
+* match wins there, masking the batch-internal pair the plan needs, and the plan needs both: the
+* batch collision decides which value writes, and the store match decides what that write supersedes.
+*
+* The slot rule: the first occupant of a key keeps its position and later ops with the same key
+* replace its content (`plannedOps[slot] = laterOp`, provenance and all, since the surviving value
+* is the later op's own statement). The occupant-tracking never moves, so a third restatement
+* replaces the slot again, last wins, at a stable position a caller can index by.
+*
+* Fail-closed on both of the rule's own guards: a null frame key is never consolidated, and a
+* failed store lookup degrades to batch-internal consolidation only, through the same
+* `Effect.catch` → `logWarning` → neutral-shape path the conflict assist takes, because an opt-in
+* consolidation must not become a new way to lose writes.
+*/
+const planLastWins = (ops) => Effect.gen(function* () {
+	/** frame key → the slot (earliest occupant's index) that carries this key's surviving value. */
+	const slotOf = /* @__PURE__ */ new Map();
+	/** slot index → the op whose value currently occupies it. */
+	const content = /* @__PURE__ */ new Map();
+	const losers = /* @__PURE__ */ new Map();
+	/** Slot indices in caller order, keyed and keyless alike. */
+	const order = [];
+	for (const [index, op] of ops.entries()) {
+		const key = frameKeyOf(op.claim);
+		if (key === null) {
+			order.push(index);
+			content.set(index, op);
+			continue;
+		}
+		const slot = slotOf.get(key);
+		if (slot === void 0) {
+			slotOf.set(key, index);
+			order.push(index);
+			content.set(index, op);
+			continue;
+		}
+		content.set(slot, op);
+		losers.set(index, slot);
+	}
+	const pendingSupersede = /* @__PURE__ */ new Map();
+	if (slotOf.size > 0) {
+		const live = yield* (yield* IndexRecorder).activeFramesFor([...slotOf.keys()]).pipe(Effect.catch((error) => Effect.logWarning(`consolidation store lookup skipped: ${error.operation}`).pipe(Effect.as(/* @__PURE__ */ new Map()))));
+		for (const [key, slot] of slotOf) {
+			const [stored] = live.get(key) ?? [];
+			if (stored !== void 0) pendingSupersede.set(slot, stored.path);
+		}
+	}
+	return {
+		ops: order.flatMap((index) => {
+			const op = content.get(index);
+			return op === void 0 ? [] : [{
+				index,
+				op
+			}];
+		}),
+		losers,
+		pendingSupersede
+	};
+});
+/**
+* Loser reports for a last-wins plan, derived from the winner slots' own final reports.
+*
+* A loser reports `ok` with `consolidatedInto` only when its slot's write landed, which means the
+* surviving value is on disk and the pointer names where. A slot that was skipped or refused took the
+* loser's value down with it, so the loser reports `skipped`, which is the retryable outcome and
+* the one an atomic abort already means: nothing of this op reached disk.
+*/
+const withConsolidation = (results, plan) => {
+	if (plan === null || plan.losers.size === 0) return results;
+	return results.map((report, index) => {
+		const slot = plan.losers.get(index);
+		if (slot === void 0) return report;
+		const winner = results[slot];
+		return winner?.ok === true && winner.skipped !== true ? {
+			index,
+			ok: true,
+			consolidatedInto: slot
+		} : {
+			index,
+			ok: false,
+			skipped: true
+		};
+	});
+};
+/**
+* Write N memories: one commit, one reindex, per-op results in input order.
+*
+* **Two folds, not one.** Decode is the operations layer's job and the store never sees it, so a
+* malformed `memory_type` on op 4 has to be caught here. This function therefore folds decode
+* over the ops and hands the store only what decoded. The store then folds the render gate, dedup,
+* and path claim over that, and this function splices the two result sets back into one array in
+* the caller's index space. Anything less and a decode failure would either be invisible per-op or
+* would shift every later op's index by one.
+*
+* **One reindex, gated on a file having been written** (G4). The indexer's `update()` reads
+* `git diff` over one commit, so a batch that committed once costs one diff. A dedupe-only
+* batch, which commits nothing, skips it entirely, because moving the watermark for a commit that
+* never happened is what `writeMemory`'s own `if (result.created)` guard exists to avoid.
+*
+* **The conflict assist is a third pass and it is read-only** (AC-1-2). It runs before the store's
+* fold, over the ops as the caller sent them, and its findings are merged into the reports at the
+* end, so it observes the batch and never participates in it. Nothing downstream of
+* {@link detectFrameConflicts} branches on its result: the same files are written, the same commit is
+* made, and the same ops are refused whether the flag is on or off. That is what propose-only means,
+* and it is checkable by reading this function rather than by trusting a description.
+*/
+const batchWrite = (params) => Effect.gen(function* () {
+	const continueOnError = params.continueOnError === true;
+	const store = yield* Store;
+	const at = yield* nowSecond$1;
+	/**
+	* The assist, over the caller's own op array and before anything is written.
+	*
+	* Over `params.ops` rather than the decoded `inputs` below, so a conflict is reported in the
+	* caller's index space directly and needs no `originOf` translation. An op the store then
+	* refuses still gets its finding, which is the more useful order, because a caller told both "this
+	* op is malformed" and "it also contradicts X" fixes one thing.
+	*
+	* Not gated on the ops being valid, and deliberately so. `frameKeyOf` is a pure lexical function
+	* over a string, so it has nothing to refuse and cannot fail on an op the decode is about to reject.
+	*/
+	const conflicts = params.detectConflicts === true ? yield* detectFrameConflicts(params.ops) : /* @__PURE__ */ new Map();
+	/**
+	* The consolidation plan, before the decode fold and in the caller's index space. A
+	* batch-internal loser is excluded from everything downstream, so its value never earns a file.
+	* The surviving value sits at the earliest slot with its key, so every later report and
+	* conflict finding stays at the index the caller sent.
+	*/
+	const plan = params.consolidate === "last-wins" ? yield* planLastWins(params.ops) : null;
+	const planned = plan === null ? [...params.ops.entries()].map(([index, op]) => ({
+		index,
+		op
+	})) : plan.ops;
+	/**
+	* Fold 1, decode. `Effect.result` rather than letting the failure escape, because a decode
+	* refusal is this op's result and not the batch's.
+	*/
+	const reports = params.ops.map(() => void 0);
+	const inputs = [];
+	/** Store-result position → caller's op index, since the store never sees a skipped op. */
+	const originOf = [];
+	let decodeAborted = false;
+	for (const { index, op } of planned) {
+		const decoded = yield* Effect.result(toWriteInput({
+			...op,
+			...provenanceOf(params, op)
+		}, at));
+		if (decoded._tag === "Failure") {
+			reports[index] = reportFailure(index, decoded.failure);
+			if (!continueOnError) {
+				decodeAborted = true;
+				break;
+			}
+			continue;
+		}
+		originOf.push(index);
+		inputs.push(decoded.success);
+	}
+	/**
+	* An atomic decode abort touches the store at all. Nothing was written, so every other op,
+	* including the ones that decoded, reports `skipped`, matching the store's own abort semantics
+	* exactly rather than inventing a second one.
+	*/
+	if (decodeAborted) {
+		const results = withConsolidation(merged(reports, conflicts), plan);
+		return {
+			results,
+			summary: summarize$1(results),
+			commitSha: null
+		};
+	}
+	/**
+	* The extraction assist: one model call over the decoded ops, extracted entities unioned into
+	* each op's own `entities` before anything is written, so they land as ordinary `memhtml-entity`
+	* metas and the git tree, rather than the index, is what remembers them.
+	*
+	* After the decode fold because a refused op must not reach the prompt, and before the store
+	* because the render is what serializes the metas. Failure costs exactly this batch's
+	* extracted entities. The port being absent, the model being down, and an unreadable payload
+	* all take the same logged-warning path, and the write itself never waits on a retry.
+	* `entities: []` is what every write produced before this assist existed.
+	*/
+	const extractor = (yield* ExtractorPort).extractor;
+	if (extractor !== void 0 && inputs.length > 0) {
+		const items = inputs.map((input) => ({
+			title: input.title,
+			text: input.articleHtml !== void 0 ? input.articleHtml : [input.claim, ...input.body ?? []].join("\n")
+		}));
+		const outcome = yield* Effect.result(extractor.extract(items));
+		if (outcome._tag === "Failure") yield* Effect.logWarning(`entity extraction skipped for this batch: ${outcome.failure.reason}`);
+		else for (const [index, extracted] of outcome.success.entries()) {
+			const input = inputs[index];
+			if (input === void 0 || extracted.length === 0) continue;
+			const declared = input.entities ?? [];
+			const union = [...declared, ...extracted.filter((entity) => !declared.includes(entity))];
+			inputs[index] = {
+				...input,
+				entities: union
+			};
+		}
+	}
+	const batch = yield* store.writeMemories(inputs, { continueOnError });
+	for (const entry of batch.results) {
+		const index = originOf[entry.index];
+		if (index === void 0) continue;
+		reports[index] = entry.ok || entry.skipped === true ? {
+			index,
+			ok: entry.ok,
+			...defined({
+				path: entry.path,
+				deduped: entry.deduped,
+				existingPath: entry.existingPath,
+				skipped: entry.skipped
+			})
+		} : reportFailure(index, entry.error);
+	}
+	if (batch.writtenPaths.length > 0) yield* reindex();
+	for (const path of batch.writtenPaths) yield* recordLink(path, "wrote", params, at);
+	/**
+	* The store-supersede pass, after a successful batch commit: every surviving slot whose frame
+	* key a live memory occupied archives that memory, in one `supersedeMemories` call.
+	*
+	* A slot qualifies when its report is `ok` with a path, including a dedupe, where the path is
+	* the pre-existing file that already carries this slot's value. The stored occupant still
+	* states the losing value, so superseding it is still correct. A slot that failed or was
+	* skipped wrote nothing, so there is nothing for its occupant to lose to.
+	*
+	* `Effect.result` rather than a bare yield, because a failed supersede must not fail a batch whose
+	* memories already landed. The degradation is annotate-only: `supersededPath` is omitted, the
+	* warning says why, and the corpus is merely unconsolidated, which is what every batch produced
+	* before this flag existed. On success there is one extra reindex, because archive paths moved.
+	*/
+	if (plan !== null && plan.pendingSupersede.size > 0) {
+		const pairs = [];
+		const winnerOf = /* @__PURE__ */ new Map();
+		for (const [slot, storedPath] of plan.pendingSupersede) {
+			const report = reports[slot];
+			if (report === void 0 || !report.ok || report.skipped === true) continue;
+			if (report.path === void 0) continue;
+			if (report.path === storedPath) continue;
+			pairs.push({
+				winnerPath: report.path,
+				loserPath: storedPath
+			});
+			winnerOf.set(storedPath, slot);
+		}
+		if (pairs.length > 0) {
+			const outcome = yield* Effect.result(store.supersedeMemories(pairs));
+			if (outcome._tag === "Failure") yield* Effect.logWarning(`consolidation supersede skipped: ${messageFor(outcome.failure)}`);
+			else {
+				for (const entry of outcome.success.archived) {
+					const slot = winnerOf.get(entry.loserPath);
+					const report = slot === void 0 ? void 0 : reports[slot];
+					if (slot === void 0 || report === void 0) continue;
+					reports[slot] = {
+						...report,
+						supersededPath: entry.archivePath
+					};
+				}
+				if (outcome.success.archived.length > 0) yield* reindex();
+			}
+		}
+	}
+	/**
+	* An op the store aborted before reaching has no result of its own, and neither does one whose
+	* decode succeeded in a batch the store then aborted. Both are `skipped`. Losers pick up their
+	* `consolidatedInto` pointer last, from their winner slot's own final report.
+	*/
+	const results = withConsolidation(merged(reports, conflicts), plan);
+	return {
+		results,
+		summary: summarize$1(results),
+		commitSha: batch.commitSha
+	};
+});
+/**
+* Per-op provenance falls back to the batch's own.
+*
+* The batch call carries the session the agent is in, and an op may name its own (a `memhtml apply`
+* file replaying a previous session's writes). Per-op wins, because it is the more specific statement
+* about where that one memory came from.
+*/
+const provenanceOf = (params, op) => defined({
+	sessionId: op.sessionId ?? params.sessionId,
+	promptId: op.promptId ?? params.promptId,
+	turnUuid: op.turnUuid ?? params.turnUuid
+});
+/**
+* The reports as their final array: an unreported op becomes `skipped`, and every op picks up the
+* assist's finding for its index.
+*
+* One function for both exit paths, the atomic decode abort and the normal return, because they had
+* already grown two copies of the same `?? skipped` fill and a third responsibility spliced into only
+* one of them is how a batch that aborted would silently lose its conflict findings. The abort path
+* needs them because nothing was written. A caller told "op 2 is malformed" and also "op 0
+* contradicts areas/x.html" can fix both before retrying, rather than discovering the second on the
+* next round trip.
+*
+* Merging here rather than at each report's construction site also keeps the assist out of the
+* write path. The reports are already final when the conflicts are attached, so there is no point at
+* which a conflict could be read by anything that decides an outcome.
+*/
+const merged = (reports, conflicts) => reports.map((report, index) => {
+	const base = report ?? {
+		index,
+		ok: false,
+		skipped: true
+	};
+	const conflict = conflicts.get(index);
+	return conflict === void 0 ? base : {
+		...base,
+		conflict
+	};
+});
+/** The counts, derived from the reports in one pass so they cannot disagree with them. */
+const summarize$1 = (results) => {
+	let written = 0;
+	let deduped = 0;
+	let failed = 0;
+	let skipped = 0;
+	let consolidated = 0;
+	for (const result of results) if (result.consolidatedInto !== void 0) consolidated += 1;
+	else if (result.skipped === true) skipped += 1;
+	else if (!result.ok) failed += 1;
+	else if (result.deduped === true) deduped += 1;
+	else written += 1;
+	return {
+		total: results.length,
+		written,
+		deduped,
+		failed,
+		skipped,
+		consolidated
+	};
+};
+/**
+* Read one memory, optionally recording that the session read it.
+*
+* The access bump lives here and nowhere else on the retrieval side, because salience accumulates
+* evidence that someone chose a memory and a ranker's guess is not a choice. An explicit open names
+* one path, through this call and the `memhtml://file/{path}` resource that funnels through it, which is
+* the strongest signal short of a write. A path merely returned by search or recall was the ranker's own
+* suggestion, and bumping it builds a rich-get-richer loop: today's top five rank higher
+* tomorrow while the memory that should displace them never breaks in to earn a first bump.
+*
+* `bumpAccess` sits beside `recordLink` deliberately. Both are notes about the read, both swallow their
+* own failures, and neither may cost the caller the memory it asked for.
+*/
+const readMemory = (path, provenance = {}) => Effect.gen(function* () {
+	const result = yield* (yield* Store).readMemory(path);
+	yield* recordLink(result.path, "read", provenance, yield* nowSecond$1);
+	yield* bumpAccess([result.path]);
+	return result;
+});
+/**
+* Ranked search. The retrieval service sanitizes the query text itself in `fts-query.ts`, so this
+* function never MATCHes user prose and neither does any caller of it.
+*
+* **No access bump, and the omission is the rule rather than an oversight.** A hit is the ranker's
+* guess about what the caller wanted, so counting it as salience would let the ranking teach itself.
+* A memory in today's top five would rank higher tomorrow purely for having been listed, and the
+* memory that should displace it never appears and so never earns a first bump. The cooldown does not
+* help, because it bounds one query replayed within 900 seconds, while the drift it would have to
+* bound operates across days. Salience moves when a caller opens a path ({@link readMemory}) or names
+* an outcome ({@link reinforceMemories}).
+*/
+const searchMemories = (params) => Effect.gen(function* () {
+	return yield* (yield* Retrieval).search(params);
+});
+/**
+* A context pack under a character budget.
+*
+* No access bump either, for {@link searchMemories}' reason. A disclosed body is still the ranker's
+* choice of what to spend the budget on rather than the caller's choice of what to read.
+*/
+const recallMemories = (params) => Effect.gen(function* () {
+	return yield* (yield* Retrieval).recall(params);
+});
+/**
+* Bump access bookkeeping for paths a caller chose to open. A missing state plane makes this a no-op.
+*
+* `reinforce` is the one SQL writer for `state.access` and this helper does not become a second one.
+* It moves callers to that writer rather than moving the write here.
+*/
+const bumpAccess = (paths) => Effect.gen(function* () {
+	if (paths.length === 0) return;
+	const db = yield* DatabaseService;
+	if (!db.hasState) return;
+	yield* reinforce(db, paths, "neutral", yield* nowSecond$1).pipe(Effect.catch((error) => Effect.logWarning(`access bookkeeping missed: ${error.operation}`).pipe(Effect.as({
+		bumped: [],
+		cooledDown: []
+	}))));
+});
+/**
+* Supersede a memory: the new file and the archived target land in one commit.
+*
+* The type defaults to the target's own. A correction that silently changed the type would move
+* the memory to a different retention profile and a different PARA directory, and that is a second
+* decision the caller did not make.
+*/
+const correctMemory = (params) => Effect.gen(function* () {
+	const store = yield* Store;
+	const target = yield* store.readMemory(params.targetPath);
+	const requested = params.memoryType ?? target.doc.metas.memoryType;
+	const memoryType = yield* decodeWritableType(requested);
+	const at = yield* nowSecond$1;
+	const result = yield* store.correctMemory(params.targetPath, {
+		title: params.title,
+		claim: params.claim,
+		memoryType,
+		at,
+		...defined({
+			body: params.body,
+			articleHtml: params.articleHtml,
+			reason: params.reason,
+			sessionId: params.sessionId,
+			promptId: params.promptId,
+			turnUuid: params.turnUuid
+		})
+	});
+	yield* reindex();
+	yield* recordLink(result.path, "corrected", params, at);
+	return result;
+});
+/**
+* Add an authored edge. Idempotent on `(rel, href)`, so a re-run commits nothing.
+*
+* The rel is decoded against {@link AUTHORABLE_RELS}, the memory class plus the task class, so
+* `memhtml link a.html blocks b.html` reaches the task graph while a person or provenance rel, both of
+* which the system mints itself, stays unauthorable.
+*/
+const linkMemories = (srcPath, rel, dstPath) => Effect.gen(function* () {
+	const edgeRel = yield* decodeAuthorableRel(rel);
+	const store = yield* Store;
+	const src = normalizePath(srcPath);
+	const result = yield* store.linkMemories(src, edgeRel, dstPath);
+	if (result.commitSha !== null) yield* reindex();
+	return {
+		...result,
+		srcPath: src,
+		dstPath: normalizePath(dstPath),
+		rel: edgeRel
+	};
+});
+/** Soft-evict: `git mv` into `archive/<YYYY>/` with the archive stamps. Never a delete. */
+const archiveMemory = (path, reason) => Effect.gen(function* () {
+	const result = yield* (yield* Store).archiveMemory(path, reason);
+	yield* reindex();
+	return result;
+});
+/** Bump access bookkeeping deliberately, with a caller-chosen signal. */
+const reinforceMemories = (paths, signal) => Effect.gen(function* () {
+	const decoded = yield* decodeSignal(signal);
+	const db = yield* DatabaseService;
+	const at = yield* nowSecond$1;
+	if (!db.hasState) return {
+		bumped: [],
+		cooledDown: paths,
+		signal: decoded
+	};
+	return {
+		...yield* reinforce(db, paths, decoded, at),
+		signal: decoded
+	};
+});
+/**
+* The memory graph around one path, to a fixed depth of at most two hops.
+*
+* **Two fixed-depth joins in a `UNION ALL`, deliberately not a recursive CTE.** The depth is
+* bounded at 2 by the tool's contract, so recursion buys nothing and costs the one thing a graph
+* query must not have here: an unbounded worst case on a corpus whose `relates_to` edges are
+* mined by the sleep cycle and can be dense. A fixed join is also index-covered by `edges_src`
+* and `edges_dst`, which a recursive walk is not.
+*
+* **Both directions, and `derived = 0 ∪ derived = 1`.** An edge is an assertion about a pair, and
+* which file happens to hold the `<link>` is authorship rather than direction of meaning. A
+* neighbourhood that read only outbound edges would show a superseding memory its target and hide
+* from the target that it had been superseded. Derived edges are included because lateral retrieval
+* is what they are for. `derived` is still reported per node so a caller can tell a
+* sleep-mined suspicion from an authored assertion.
+*
+* `edge_class = 'memory'` on every join. A person edge entering here would put
+* `resources/people/*` into a memory neighbourhood, and the class column exists to make that
+* structurally impossible.
+*/
+const neighborsOf = (params) => Effect.gen(function* () {
+	const db = yield* DatabaseService;
+	const centre = normalizePath(params.path);
+	const depth = Math.min(2, Math.max(1, Math.trunc(params.depth ?? 1)));
+	const rels = (params.rels ?? []).filter((rel) => isEdgeRel(rel) && relClassFor(rel) === "memory");
+	const relFilter = rels.length > 0 ? ` AND e.rel IN (${rels.map(() => "?").join(", ")})` : "";
+	const relFilter2 = rels.length > 0 ? ` AND e2.rel IN (${rels.map(() => "?").join(", ")})` : "";
+	/**
+	* Hop 1 is the centre's own edges, either direction. Hop 2 walks one further from each hop-1
+	* node and excludes the centre, so a two-cycle does not report the centre as its own neighbour
+	* at distance 2.
+	*/
+	const hopOne = `
+      SELECT e.dst_path AS path, e.rel AS rel, e.derived AS derived, 1 AS hop
+      FROM edges e
+      WHERE e.src_path = ?1 AND e.edge_class = 'memory'${relFilter}
+      UNION ALL
+      SELECT e.src_path AS path, e.rel AS rel, e.derived AS derived, 1 AS hop
+      FROM edges e
+      WHERE e.dst_path = ?1 AND e.edge_class = 'memory'${relFilter}`;
+	const hopTwo = `
+      SELECT e2.dst_path AS path, e2.rel AS rel, e2.derived AS derived, 2 AS hop
+      FROM edges e
+      JOIN edges e2 ON e2.src_path = e.dst_path
+      WHERE e.src_path = ?1 AND e.edge_class = 'memory' AND e2.edge_class = 'memory'
+        AND e2.dst_path <> ?1${relFilter}${relFilter2}
+      UNION ALL
+      SELECT e2.src_path AS path, e2.rel AS rel, e2.derived AS derived, 2 AS hop
+      FROM edges e
+      JOIN edges e2 ON e2.dst_path = e.src_path
+      WHERE e.dst_path = ?1 AND e.edge_class = 'memory' AND e2.edge_class = 'memory'
+        AND e2.src_path <> ?1${relFilter}${relFilter2}`;
+	const walk = depth === 1 ? hopOne : `${hopOne}\n      UNION ALL${hopTwo}`;
+	const nodes = (yield* db.all(`SELECT w.path AS path, f.title AS title, min(w.hop) AS hop,
+              min(w.rel) AS rel, max(w.derived) AS derived
+       FROM (${walk}) w
+       JOIN files f ON f.path = w.path
+       GROUP BY w.path
+       ORDER BY hop ASC, w.path ASC`, [centre, ...depth === 1 ? [...rels, ...rels] : [
+		...rels,
+		...rels,
+		...rels,
+		...rels,
+		...rels,
+		...rels
+	]])).map((row) => ({
+		path: row.path,
+		title: row.title,
+		hop: row.hop,
+		rel: row.rel
+	}));
+	return {
+		centre,
+		depth,
+		nodes,
+		edges: nodes.length
+	};
+});
+/**
+* Page the corpus by facet.
+*
+* Keyset pagination on `path` rather than `LIMIT/OFFSET`. `files.path` is the primary key and it also
+* moves, because eviction is a `git mv`, so an offset page taken while a sleep cycle archives a file
+* would skip a row or repeat one. A cursor on the path itself is stable against that.
+*/
+const listMemories = (params) => Effect.gen(function* () {
+	const db = yield* DatabaseService;
+	const limit = Math.min(500, Math.max(1, Math.trunc(params.limit ?? 50)));
+	const conditions = [];
+	const values = [];
+	if (params.includeArchived !== true) conditions.push("f.archived = 0");
+	if (params.memoryType !== void 0 && params.memoryType !== "") {
+		const memoryType = yield* decodeWritableType(params.memoryType);
+		conditions.push("f.memory_type = ?");
+		values.push(memoryType);
+	}
+	if (params.workspace !== void 0 && params.workspace !== "") {
+		conditions.push("f.workspace = ?");
+		values.push(params.workspace);
+	}
+	if (params.para !== void 0 && params.para !== "") {
+		conditions.push("f.para = ?");
+		values.push(params.para);
+	}
+	if (params.tag !== void 0 && params.tag !== "") {
+		conditions.push("EXISTS (SELECT 1 FROM file_tags t WHERE t.path = f.path AND t.tag = ?)");
+		values.push(params.tag);
+	}
+	if (params.entity !== void 0 && params.entity !== "") {
+		conditions.push("EXISTS (SELECT 1 FROM file_entities e WHERE e.path = f.path AND e.entity_type || ':' || e.entity_name = ?)");
+		values.push(params.entity);
+	}
+	if (params.cursor !== void 0 && params.cursor !== "") {
+		conditions.push("f.path > ?");
+		values.push(normalizePath(params.cursor));
+	}
+	const where = conditions.length === 0 ? "" : `WHERE ${conditions.join(" AND ")}`;
+	const rows = yield* db.all(`SELECT f.path, f.title, f.memory_type, f.gist, f.workspace, f.para,
+              f.confidence, f.importance, f.archived, f.updated_at
+       FROM files f ${where} ORDER BY f.path ASC LIMIT ?`, [...values, limit + 1]);
+	const page = rows.slice(0, limit);
+	const nextCursor = rows.length > limit ? page.at(-1)?.path ?? null : null;
+	return {
+		files: page.map((row) => ({
+			path: row.path,
+			title: row.title,
+			memoryType: row.memory_type,
+			gist: row.gist,
+			workspace: row.workspace,
+			para: row.para,
+			confidence: row.confidence,
+			importance: row.importance,
+			archived: row.archived === 1,
+			updatedAt: row.updated_at
+		})),
+		nextCursor
+	};
+});
+/**
+* FTS over session first-prompts and AI titles.
+*
+* The query goes through the same sanitizer the memory arms use, and it has to. An apostrophe is a
+* hard driver error rather than an empty result, and "what did I ask about don't-repeat-yourself"
+* is an ordinary trace query. An empty sanitized query returns the most recent sessions rather
+* than nothing, because a caller with no terms wants a listing and an empty MATCH is not a listing.
+*
+* This is the trace plane and it stops here. No memory table is named, and nothing in the
+* retrieval assembler names `traces`. The firewall is by table name, in both directions.
+*/
+const searchTraces = (params) => Effect.gen(function* () {
+	const db = yield* DatabaseService;
+	const match = sanitizeFtsQuery(params.query);
+	const limit = Math.min(200, Math.max(1, Math.trunc(params.limit ?? 20)));
+	const conditions = [];
+	const values = [];
+	/**
+	* The MATCH names `traces_fts` rather than a column of `traces`. The index is an external-content
+	* FTS5 table, so it is joined in by rowid and only reached when there is something to match. Without
+	* a query the statement never mentions it, which is what keeps a bare listing a plain table scan.
+	*/
+	const matched = match !== "";
+	const from = matched ? "FROM traces_fts JOIN traces t ON t.rowid = traces_fts.rowid" : "FROM traces t";
+	if (matched) {
+		conditions.push("traces_fts MATCH ?");
+		values.push(match);
+	}
+	if (params.cwd !== void 0 && params.cwd !== "") {
+		conditions.push("t.cwd = ?");
+		values.push(params.cwd);
+	}
+	if (params.since !== void 0 && params.since !== "") {
+		conditions.push("t.started_at >= ?");
+		values.push(params.since);
+	}
+	const where = conditions.length === 0 ? "" : `WHERE ${conditions.join(" AND ")}`;
+	const order = matched ? "ORDER BY bm25(traces_fts)" : "ORDER BY t.started_at DESC";
+	return {
+		sessions: (yield* db.all(`SELECT t.session_id, t.slug, t.cwd, t.started_at, t.prompt_count, t.first_prompt, t.ai_title
+       ${from} ${where} ${order} LIMIT ?`, [...values, limit])).map((row) => ({
+			sessionId: row.session_id,
+			slug: row.slug,
+			cwd: row.cwd,
+			startedAt: row.started_at,
+			promptCount: row.prompt_count,
+			firstPrompt: row.first_prompt,
+			aiTitle: row.ai_title
+		})),
+		degraded: match === ""
+	};
+});
+/**
+* The memory-session links, from either side.
+*
+* Both parameters absent is a refusal rather than an unbounded scan of every link ever recorded. A
+* tool whose no-argument form returns the whole table is a tool an agent calls by accident.
+*/
+const traceLinks = (params) => Effect.gen(function* () {
+	const hasSession = params.sessionId !== void 0 && params.sessionId !== "";
+	const hasPath = params.path !== void 0 && params.path !== "";
+	if (!hasSession && !hasPath) return yield* Effect.fail(InvalidMemory.make({ reason: "trace links needs a session_id or a path" }));
+	const db = yield* DatabaseService;
+	const conditions = [];
+	const values = [];
+	if (hasSession) {
+		conditions.push("l.session_id = ?");
+		values.push(params.sessionId);
+	}
+	if (hasPath) {
+		conditions.push("l.path = ?");
+		values.push(normalizePath(params.path));
+	}
+	return { links: (yield* db.all(`SELECT l.path, l.session_id, l.prompt_id, l.turn_uuid, l.link_kind, l.at
+       FROM memory_session_links l
+       WHERE ${conditions.join(" AND ")}
+       ORDER BY l.at DESC, l.path ASC`, values)).map((row) => ({
+		path: row.path,
+		sessionId: row.session_id,
+		promptId: row.prompt_id,
+		turnUuid: row.turn_uuid,
+		linkKind: row.link_kind,
+		at: row.at
+	})) };
+});
+/**
+* Corpus health, in one call.
+*
+* `indexFresh` compares the recorded watermark to `HEAD`, which is the only answer that means
+* anything. The index is a projection of a commit, so "fresh" means "the commit it describes is the
+* commit we are on". A count of rows would say the index exists rather than that it is current.
+*
+* `embedderUp` is read off the stored watermark rather than by probing Bedrock. A status call that
+* made a network request would fail for a reason unrelated to the corpus, and what a caller
+* needs to know is whether the vectors in this index are usable.
+*/
+const statusReport = () => Effect.gen(function* () {
+	const store = yield* Store;
+	const db = yield* DatabaseService;
+	const headSha = yield* store.git.revParseHead();
+	const dirty = yield* store.dirtyPaths();
+	const state = yield* readIndexState(db).pipe(Effect.orElseSucceed(() => void 0));
+	const byType = yield* countRows(db, "SELECT memory_type AS k, count(*) AS n FROM files WHERE archived = 0 GROUP BY memory_type");
+	const archivedCount = yield* countOne(db, "SELECT count(*) AS n FROM files WHERE archived = 1");
+	const edges = yield* countOne(db, "SELECT count(*) AS n FROM edges");
+	const derivedEdges = yield* countOne(db, "SELECT count(*) AS n FROM edges WHERE derived = 1");
+	const embeddings = yield* countOne(db, "SELECT count(*) AS n FROM embeddings");
+	const chunks = yield* countOne(db, "SELECT count(*) AS n FROM chunks");
+	const traces = yield* countOne(db, "SELECT count(*) AS n FROM traces");
+	const lastSleep = yield* db.get("SELECT run_id, status, started_at FROM sleep_runs ORDER BY started_at DESC LIMIT 1").pipe(Effect.orElseSucceed(() => void 0));
+	return {
+		root: store.root,
+		headSha,
+		dirty: dirty.length > 0,
+		dirtyPaths: dirty,
+		countsByType: byType,
+		archivedCount,
+		edges,
+		derivedEdges,
+		chunks,
+		embeddings,
+		traces,
+		indexFresh: state?.head_sha !== null && state?.head_sha === headSha,
+		indexHeadSha: state?.head_sha ?? null,
+		embedModel: state?.embed_model ?? null,
+		embedderUp: state !== void 0 && state.embed_model === EMBED_WATERMARK && embeddings > 0,
+		hasState: db.hasState,
+		lastSleep: lastSleep === void 0 ? null : {
+			runId: lastSleep.run_id,
+			status: lastSleep.status,
+			startedAt: lastSleep.started_at
+		}
+	};
+});
+/** One scalar count, `0` when the table is unreachable. */
+const countOne = (db, sql) => db.get(sql).pipe(Effect.map((row) => row?.n ?? 0));
+/** A `GROUP BY` into a record. An absent key means zero, so the caller never reads a null. */
+const countRows = (db, sql) => db.all(sql).pipe(Effect.map((rows) => Object.fromEntries(rows.map((row) => [row.k, row.n]))));
+
+//#endregion
+//#region apps/cli/dist/commands.js
+/** Flags every command accepts. Listed once so the manifest cannot drift from behavior. */
+const GLOBAL_FLAGS = [
+	{
+		name: "json",
+		type: "boolean",
+		description: "Emit the typed JSON envelope on stdout (default; logs go to stderr).",
+		default: true
+	},
+	{
+		name: "dense",
+		type: "boolean",
+		description: "Minify JSON and drop null fields, for pasting into a context window.",
+		default: false
+	},
+	{
+		name: "repo",
+		type: "string",
+		description: "Path to the memory repo. Defaults to $MEMHTML_ROOT.",
+		default: ""
+	}
+];
+/** Flags every retrieval command shares, so `search` and `recall` cannot scope differently. */
+const SCOPE_FLAGS = [
+	{
+		name: "type",
+		type: "string",
+		description: "Restrict to one memory type. Repeatable; each occurrence broadens (ANY-of).",
+		values: WRITABLE_MEMORY_TYPES,
+		repeatable: true
+	},
+	{
+		name: "workspace",
+		type: "string",
+		description: "Restrict to one workspace. STRICT: a scoped query never returns a memory with no workspace."
+	},
+	{
+		name: "tag",
+		type: "string",
+		description: "Restrict to memories carrying any of these tags. Repeatable; each broadens.",
+		repeatable: true
+	},
+	{
+		name: "entity",
+		type: "string",
+		description: "Restrict to memories carrying one `type:name` entity reference, e.g. service:checkout-api, the form a hit's `entities` publishes, so a hop is a copy. A scope matching nothing returns no hits and says so; it never widens."
+	},
+	{
+		name: "include-archived",
+		type: "boolean",
+		description: "Include archived memories. Eviction is a `git mv`, so they still exist.",
+		default: false
+	},
+	{
+		name: "as-of",
+		type: "string",
+		description: "Point-in-time view: returns what was believed valid at this ISO instant, including since-superseded memories (marked superseded_by). The validity window is coalesce(valid_from, event_at, created_at) <= as-of < valid_until."
+	}
+];
+/**
+* The single source of parsing, validation, and the manifest. A command lands here
+* before it lands anywhere else, so `memhtml manifest` and `memhtml agents-doc` describe
+* what the binary actually accepts rather than what someone remembered to document.
+*
+* A subcommand is one entry with a space in its name (`index rebuild`), not a nested tree.
+* Flattening keeps `nearest()` able to suggest across the whole surface, a typo in the noun
+* (`memhtml indx rebuild`) and a typo in the verb (`memhtml index rebiuld`) both get a candidate, and
+* keeps one table driving parsing, the manifest, and the generated doc.
+*/
+const COMMANDS = [
+	{
+		name: "manifest",
+		summary: "Emit this CLI's full machine-readable contract.",
+		args: [],
+		flags: [],
+		responseTypes: ["cli.manifest"]
+	},
+	{
+		name: "init",
+		summary: "Scaffold a memory repo at --repo/$MEMHTML_ROOT: git init, PARA dirs, merge driver.",
+		args: [],
+		flags: [],
+		responseTypes: ["repo.init"]
+	},
+	{
+		name: "write",
+		summary: "Write one memory. Content-hash duplicates return the existing path, uncommitted.",
+		args: [],
+		flags: [
+			{
+				name: "title",
+				type: "string",
+				description: "The memory's title. Becomes the <title> and the filename slug.",
+				required: true
+			},
+			{
+				name: "claim",
+				type: "string",
+				description: "The one load-bearing sentence. Becomes the <mark> span and files.gist. Exactly one of --claim or --article-html."
+			},
+			{
+				name: "body",
+				type: "string",
+				description: "A prose paragraph after the claim. Repeatable, one <p> each.",
+				repeatable: true
+			},
+			{
+				name: "article-html",
+				type: "string",
+				description: "Raw <article> markup used verbatim in place of --claim/--body. Must contain exactly one <mark> in the first <p> or <li>; the first <time datetime> becomes the memory's event time. The store refuses format violations before any commit. Exactly one of --claim or --article-html."
+			},
+			{
+				name: "type",
+				type: "string",
+				description: "The memory type. `arc` is absent: an arc is synthesized by sleep.",
+				values: WRITABLE_MEMORY_TYPES,
+				required: true
+			},
+			{
+				name: "path",
+				type: "string",
+				description: "An explicit path override. Ignored when it is not a valid memory path."
+			},
+			{
+				name: "workspace",
+				type: "string",
+				description: "Routes the memory to projects/<slug>/."
+			},
+			{
+				name: "tag",
+				type: "string",
+				description: "A tag. Repeatable; the first one routes an unplaced resource memory."
+			},
+			{
+				name: "entity",
+				type: "string",
+				description: "A `type:name` entity reference, e.g. service:checkout-api. Repeatable.",
+				repeatable: true
+			},
+			{
+				name: "importance",
+				type: "int",
+				description: "1-10, a display ordinal. The retention scorer divides by 10."
+			},
+			{
+				name: "confidence",
+				type: "string",
+				description: "0-1. 1.0 is an unqualified assertion."
+			},
+			{
+				name: "session-id",
+				type: "string",
+				description: "The Claude Code session. Stamped into the head AND indexed as a link."
+			},
+			{
+				name: "prompt-id",
+				type: "string",
+				description: "The prompt within that session."
+			},
+			{
+				name: "turn-uuid",
+				type: "string",
+				description: "The turn within that session."
+			}
+		],
+		responseTypes: ["memory.written"]
+	},
+	{
+		name: "apply",
+		summary: "Write many memories from a JSONL op stream: ONE commit, ONE index update, per-op results.",
+		args: [],
+		flags: [
+			{
+				name: "file",
+				type: "string",
+				description: "The JSONL file to read. One complete JSON object per line. Omit it (or pass `-`) to read the stream from stdin."
+			},
+			{
+				name: "continue-on-error",
+				type: "boolean",
+				description: "Best-effort: a refused op is reported and skipped while every surviving op lands in the one commit. Atomic by default. The first refused op aborts the batch and nothing is written.",
+				default: false
+			},
+			{
+				name: "detect-conflicts",
+				type: "boolean",
+				description: "Report each op's frame-matches as a per-op `conflict`: the ACTIVE memory (or the earlier op) whose claim occupies the same subject-and-relation slot. PROPOSE-ONLY: every op still writes exactly as it would have, because sometimes the contradiction is the answer. You decide: write anyway, `memhtml correct` the match, or drop the line.",
+				default: false
+			},
+			{
+				name: "consolidate",
+				type: "string",
+				values: ["last-wins"],
+				description: "Resolve frame-key matches instead of only reporting them: `--consolidate last-wins` makes the LATER op's value win a shared claim slot (one file, written at the FIRST index that claimed the slot, with each later restatement reporting `consolidated_into` naming that slot) and archives a stored ACTIVE memory a surviving slot displaces, reported as `superseded_path`. Off by default; claims with no frame shape are never consolidated."
+			},
+			{
+				name: "session-id",
+				type: "string",
+				description: "The Claude Code session for every op that names none. A line's own `session_id` wins over this."
+			},
+			{
+				name: "prompt-id",
+				type: "string",
+				description: "The prompt within that session."
+			},
+			{
+				name: "turn-uuid",
+				type: "string",
+				description: "The turn within that session."
+			}
+		],
+		responseTypes: ["batch.applied"]
+	},
+	{
+		name: "read",
+		summary: "Read one memory: its metas, links, article, and format warnings.",
+		args: [{
+			name: "path",
+			description: "Repo-root-relative path to the memory.",
+			required: true
+		}],
+		flags: [{
+			name: "session-id",
+			type: "string",
+			description: "Records a `read` session link, so provenance is queryable both ways."
+		}],
+		responseTypes: ["memory.detail"]
+	},
+	{
+		name: "search",
+		summary: "Ranked search: four RRF arms plus MMR. Degrades to the lexical floor.",
+		args: [{
+			name: "query",
+			description: "Prose. Never a query language.",
+			required: true
+		}],
+		flags: [...SCOPE_FLAGS, {
+			name: "limit",
+			type: "int",
+			description: "Hits to return.",
+			default: 10
+		}],
+		responseTypes: ["memory.hits"]
+	},
+	{
+		name: "recall",
+		summary: "A disclosure pack under a character budget: arcs and memories folded separately.",
+		args: [{
+			name: "query",
+			description: "Prose.",
+			required: true
+		}],
+		flags: [...SCOPE_FLAGS, {
+			name: "budget",
+			type: "int",
+			description: "Characters of quoted body. Arcs get their own envelope on top.",
+			default: 16e3
+		}],
+		responseTypes: ["recall.pack"]
+	},
+	{
+		name: "correct",
+		summary: "Supersede a memory: write the new file and archive the target in ONE commit.",
+		args: [{
+			name: "target",
+			description: "The memory being corrected.",
+			required: true
+		}],
+		flags: [
+			{
+				name: "title",
+				type: "string",
+				description: "The new memory's title.",
+				required: true
+			},
+			{
+				name: "claim",
+				type: "string",
+				description: "The corrected claim. Exactly one of --claim or --article-html."
+			},
+			{
+				name: "body",
+				type: "string",
+				description: "A prose paragraph. Repeatable.",
+				repeatable: true
+			},
+			{
+				name: "article-html",
+				type: "string",
+				description: "Raw <article> markup for the superseding memory, used verbatim in place of --claim/--body. Must contain exactly one <mark> in the first <p> or <li>; the first <time datetime> becomes the memory's event time. The store refuses format violations before any commit. Exactly one of --claim or --article-html."
+			},
+			{
+				name: "type",
+				type: "string",
+				description: "The new memory's type. Defaults to the target's.",
+				values: WRITABLE_MEMORY_TYPES
+			},
+			{
+				name: "reason",
+				type: "string",
+				description: "Why the correction was made."
+			},
+			{
+				name: "session-id",
+				type: "string",
+				description: "Records a `corrected` session link."
+			}
+		],
+		responseTypes: ["memory.corrected"]
+	},
+	{
+		name: "link",
+		summary: "Add an authored edge to the source file and commit it. Idempotent.",
+		args: [
+			{
+				name: "src",
+				description: "The asserting memory or task.",
+				required: true
+			},
+			{
+				name: "rel",
+				description: `One of: ${AUTHORABLE_RELS.join(", ")}. A task rel needs two tasks; a memory rel refuses a task endpoint.`,
+				required: true
+			},
+			{
+				name: "dst",
+				description: "The memory or task being pointed at.",
+				required: true
+			}
+		],
+		flags: [],
+		responseTypes: ["memory.linked"]
+	},
+	{
+		name: "neighbors",
+		summary: "The memory graph around one path, to a fixed depth of at most two hops.",
+		args: [{
+			name: "path",
+			description: "The centre of the neighbourhood.",
+			required: true
+		}],
+		flags: [{
+			name: "depth",
+			type: "int",
+			description: "1 or 2. Never more.",
+			default: 1
+		}, {
+			name: "rel",
+			type: "string",
+			description: "Restrict to these rels. Repeatable.",
+			values: MEMORY_RELS,
+			repeatable: true
+		}],
+		responseTypes: ["memory.neighbors"]
+	},
+	{
+		name: "archive",
+		summary: "Soft-evict: `git mv` into archive/<YYYY>/ with the archive stamps. Never a delete.",
+		args: [{
+			name: "path",
+			description: "The memory to archive.",
+			required: true
+		}],
+		flags: [{
+			name: "reason",
+			type: "string",
+			description: "Why it was evicted.",
+			required: true
+		}],
+		responseTypes: ["memory.archived"]
+	},
+	{
+		name: "reinforce",
+		summary: "Bump access bookkeeping, gated by a 900-second per-path cooldown.",
+		args: [{
+			name: "path",
+			description: "A memory path. Repeat the argument for more.",
+			required: true
+		}],
+		flags: [{
+			name: "signal",
+			type: "string",
+			description: "`neutral` bumps access without claiming the memory was right.",
+			values: REINFORCE_SIGNALS,
+			default: "neutral"
+		}],
+		responseTypes: ["memory.reinforced"]
+	},
+	{
+		name: "list",
+		summary: "Page through the corpus by type, workspace, tag, entity, or PARA bucket.",
+		args: [],
+		flags: [
+			{
+				name: "type",
+				type: "string",
+				description: "One memory type.",
+				values: WRITABLE_MEMORY_TYPES
+			},
+			{
+				name: "workspace",
+				type: "string",
+				description: "One workspace."
+			},
+			{
+				name: "tag",
+				type: "string",
+				description: "One tag."
+			},
+			{
+				name: "entity",
+				type: "string",
+				description: "One `type:name` entity reference."
+			},
+			{
+				name: "para",
+				type: "string",
+				description: "One PARA bucket.",
+				values: [
+					"projects",
+					"areas",
+					"resources",
+					"archive"
+				]
+			},
+			{
+				name: "limit",
+				type: "int",
+				description: "Rows per page.",
+				default: 50
+			},
+			{
+				name: "cursor",
+				type: "string",
+				description: "The `next_cursor` from the previous page: the last path returned."
+			},
+			{
+				name: "include-archived",
+				type: "boolean",
+				description: "Include archived memories.",
+				default: false
+			}
+		],
+		responseTypes: ["memory.list"]
+	},
+	(
+	/**
+	* The task family: CRUDL over the 10th memory type, without retrieval.
+	*
+	* Sugar over the same use cases everything else uses. `task add` is `writeMemory` with
+	* `--type task`, and `task status` is one head meta plus (for `done`) the archive machinery. The
+	* design intent is that an agent works tasks with `Read`, `Edit`, and `ls` as readily as with these.
+	* A task is a file in a directory, and this family exists so the common moves are one call rather
+	* than three.
+	*/
+	{
+		name: "task add",
+		summary: "Open a task: a `task` memory in projects/<ws>/tasks/ or areas/inbox/tasks/.",
+		args: [],
+		flags: [
+			{
+				name: "title",
+				type: "string",
+				description: "What the task is. Becomes the <title> and the filename slug.",
+				required: true
+			},
+			{
+				name: "claim",
+				type: "string",
+				description: "The task statement, as the <mark> span. Defaults to --title."
+			},
+			{
+				name: "body",
+				type: "string",
+				description: "A prose paragraph of working notes. Repeatable, one <p> each.",
+				repeatable: true
+			},
+			{
+				name: "status",
+				type: "string",
+				description: "The opening status. `todo` unless you are recording work already underway.",
+				values: TASK_STATUSES,
+				default: "todo"
+			},
+			{
+				name: "due",
+				type: "string",
+				description: "An ISO date or datetime deadline. Compared as a string, so the form matters."
+			},
+			{
+				name: "workspace",
+				type: "string",
+				description: "Routes the task to projects/<slug>/tasks/."
+			},
+			{
+				name: "tag",
+				type: "string",
+				description: "A tag. Repeatable; tags scope search but never route a task.",
+				repeatable: true
+			},
+			{
+				name: "entity",
+				type: "string",
+				description: "A `type:name` entity reference. Repeatable.",
+				repeatable: true
+			},
+			{
+				name: "session-id",
+				type: "string",
+				description: "The Claude Code session that opened the task."
+			},
+			{
+				name: "prompt-id",
+				type: "string",
+				description: "The prompt within that session."
+			},
+			{
+				name: "turn-uuid",
+				type: "string",
+				description: "The turn within that session."
+			}
+		],
+		responseTypes: ["task.written"]
+	}),
+	{
+		name: "task status",
+		summary: "Move a task's status. `done` stamps AND archives it, in one commit.",
+		args: [{
+			name: "path",
+			description: "The task file.",
+			required: true
+		}, {
+			name: "status",
+			description: `One of: ${TASK_STATUSES.join(", ")}.`,
+			required: true
+		}],
+		flags: [{
+			name: "reason",
+			type: "string",
+			description: "Why it closed. Recorded on the archive commit when the status is `done`."
+		}],
+		responseTypes: ["task.updated"]
+	},
+	{
+		name: "task list",
+		summary: "The task working set: a direct indexed scan with blockers, never ranked retrieval.",
+		args: [],
+		flags: [
+			{
+				name: "status",
+				type: "string",
+				description: "One task status.",
+				values: TASK_STATUSES
+			},
+			{
+				name: "workspace",
+				type: "string",
+				description: "One workspace."
+			},
+			{
+				name: "due-before",
+				type: "string",
+				description: "An ISO date. Returns tasks due strictly before it, by calendar day."
+			},
+			{
+				name: "limit",
+				type: "int",
+				description: "Rows per page.",
+				default: 50
+			},
+			{
+				name: "cursor",
+				type: "string",
+				description: "The `next_cursor` from the previous page: the last path returned."
+			},
+			{
+				name: "include-archived",
+				type: "boolean",
+				description: "Include finished tasks. `done` archives, so they are otherwise absent.",
+				default: false
+			}
+		],
+		responseTypes: ["task.list"]
+	},
+	{
+		name: "index rebuild",
+		summary: "Rebuild index.db from the git tree at HEAD. Destroys nothing outside .memhtml/.",
+		args: [],
+		flags: [{
+			name: "embed",
+			type: "boolean",
+			description: "Fill missing vectors from Bedrock. --no-embed makes the rebuild instant.",
+			default: true
+		}],
+		responseTypes: ["index.report"]
+	},
+	{
+		name: "index update",
+		summary: "Index only what moved since the recorded watermark, plus the dirty working tree.",
+		args: [],
+		flags: [{
+			name: "embed",
+			type: "boolean",
+			description: "Fill missing vectors.",
+			default: true
+		}],
+		responseTypes: ["index.report"]
+	},
+	{
+		name: "index status",
+		summary: "The index watermark, the vector space it was built in, and its row counts.",
+		args: [],
+		flags: [],
+		responseTypes: ["index.report"]
+	},
+	{
+		name: "trace index",
+		summary: "Scan $MEMHTML_TRACE_ROOT for Claude Code transcripts, reading only what changed.",
+		args: [],
+		flags: [],
+		responseTypes: ["trace.report"]
+	},
+	{
+		name: "trace search",
+		summary: "FTS over session first-prompts and AI titles. Never enters memory retrieval.",
+		args: [{
+			name: "query",
+			description: "Prose.",
+			required: true
+		}],
+		flags: [
+			{
+				name: "cwd",
+				type: "string",
+				description: "Restrict to sessions from this directory."
+			},
+			{
+				name: "since",
+				type: "string",
+				description: "ISO-8601 lower bound on started_at."
+			},
+			{
+				name: "limit",
+				type: "int",
+				description: "Sessions to return.",
+				default: 20
+			}
+		],
+		responseTypes: ["trace.sessions"]
+	},
+	{
+		name: "trace links",
+		summary: "The memory-session links, from either side.",
+		args: [],
+		flags: [{
+			name: "session-id",
+			type: "string",
+			description: "Every memory this session touched."
+		}, {
+			name: "path",
+			type: "string",
+			description: "Every session that touched this memory."
+		}],
+		responseTypes: ["trace.links"]
+	},
+	{
+		name: "sleep run",
+		summary: "The nightly curation cycle: 15 phases, each an isolated commit on a review branch.",
+		args: [],
+		flags: [
+			{
+				name: "date",
+				type: "string",
+				description: "The run date, `YYYY-MM-DD`. Defaults to today. Names the branch."
+			},
+			{
+				name: "phases",
+				type: "string",
+				description: `Comma-separated subset. All 15 by default: ${SLEEP_PHASES.join(", ")}.`
+			},
+			{
+				name: "dry-run",
+				type: "boolean",
+				description: "Report per-phase counts and commit nothing.",
+				default: false
+			}
+		],
+		responseTypes: ["sleep.report"]
+	},
+	{
+		name: "sleep resume",
+		summary: "Re-run only the phases with no Memhtml-Phase trailer on the branch.",
+		args: [{
+			name: "run-id",
+			description: "The run id, e.g. sleep/2026-08-02.",
+			required: true
+		}],
+		flags: [],
+		responseTypes: ["sleep.report"]
+	},
+	{
+		name: "sleep review",
+		summary: "Per-phase counts, the commit list, diff --stat, and a per-file classification.",
+		args: [{
+			name: "run-id",
+			description: "The run id.",
+			required: true
+		}],
+		flags: [{
+			name: "diff",
+			type: "boolean",
+			description: "Include the raw diff.",
+			default: false
+		}],
+		responseTypes: ["sleep.review"]
+	},
+	{
+		name: "sleep merge",
+		summary: "Fast-forward main to the run's branch, after the discrimination gate passes.",
+		args: [{
+			name: "run-id",
+			description: "The run id.",
+			required: true
+		}],
+		flags: [{
+			name: "skip-gate",
+			type: "boolean",
+			description: "Merge without re-running discrimination. A deliberate, logged override, never a default.",
+			default: false
+		}],
+		responseTypes: ["sleep.merge"]
+	},
+	{
+		name: "sleep status",
+		summary: "The latest sleep run and its per-phase outcomes.",
+		args: [],
+		flags: [],
+		responseTypes: ["sleep.report"]
+	},
+	{
+		name: "status",
+		summary: "Corpus health: HEAD, dirty state, counts by type, edges, index freshness.",
+		args: [],
+		flags: [],
+		responseTypes: ["status.health"]
+	},
+	{
+		name: "publish",
+		summary: "Regenerate the per-directory index.html listings and sitemap.xml, and commit them.",
+		args: [],
+		flags: [],
+		responseTypes: ["publish.report"]
+	},
+	{
+		name: "doctor",
+		summary: "Corpus health: dangling hrefs, orphan state rows, inbox depth, vocabulary, staleness.",
+		args: [],
+		flags: [{
+			name: "fix",
+			type: "boolean",
+			description: "Repair dangling hrefs and prune orphan access rows. The other findings need a decision.",
+			default: false
+		}],
+		responseTypes: ["doctor.report"]
+	},
+	{
+		name: "eval discriminate",
+		summary: "The refusable retrieval gate: every probe must outrank its own wrong-fact twins.",
+		args: [],
+		flags: [
+			{
+				name: "mode",
+				type: "string",
+				description: "`fake` is the deterministic embedder CI measures; `live` needs AWS_BEARER_TOKEN_BEDROCK and refuses loudly without it.",
+				values: ["fake", "live"],
+				default: "fake"
+			},
+			{
+				name: "seed",
+				type: "int",
+				description: "The fixture corpus seed. A failing run is reproducible from this number."
+			},
+			{
+				name: "size",
+				type: "int",
+				description: "Base memories to generate.",
+				default: 200
+			},
+			{
+				name: "probes",
+				type: "int",
+				description: "Probes to run. Design §5 wants ≥30.",
+				default: 36
+			},
+			{
+				name: "mrr-floor",
+				type: "string",
+				description: "Mean-reciprocal-rank floor. Lowering it is a deliberate, visible choice.",
+				default: "0.85"
+			}
+		],
+		responseTypes: ["eval.discrimination"]
+	},
+	(
+	/**
+	* Code-mode (ROADMAP item 7b): one script, one execution, one envelope.
+	*
+	* The flag surface answers three questions a script cannot answer for itself, and nothing else.
+	*
+	* **How does the script arrive?** Three doors, exactly one per call, enforced in `validate` so a
+	* wrong combination is exit 2. `--file` for a script under version control, `--script` for the
+	* inline one-liner an agent composes, and a bare `memhtml exec` (or `-`) for stdin, which is the same
+	* three-door shape and the same `-` spelling `memhtml apply` already uses for its op stream, so an
+	* agent that learned one learned both. `--script` rather than a positional argument, because the
+	* positional slot on a two-word command is where a run-id or a path goes on every other command
+	* here, and a multi-line program in that slot would read as one.
+	*
+	* **How long may it run?** `--timeout-ms`, bounded and defaulted, because the guest is a QuickJS
+	* worker with no reaper of its own and an unbounded script holds the CLI process open. The
+	* millisecond unit is in the flag name rather than left to a note, since `--timeout 30` is
+	* ambiguous by a factor of a thousand.
+	*
+	* **Which tree does it see?** `--sha`, defaulting to `HEAD`. Never the live working tree, which is
+	* a containment decision rather than a convenience. A mounted `$MEMHTML_ROOT` exposes `.memhtml/index.db`
+	* to the guest, whose `sqlite3` reads it happily (probed 2026-08-09: a read-only mount is no barrier
+	* to a reader). A gitignored file is absent from a detached worktree, so pinning a commit is what
+	* keeps the ranked planes out of reach, and the read-only mount is the second layer rather than
+	* the only one. A pin also makes the answer reproducible. `sha` rides back in the envelope, so a
+	* rerun is exact.
+	*
+	* There is deliberately no flag for the guest's own opt-ins. `javascript` is on because `js-exec`
+	* is the feature. `python` and `network` are off and unofferable, so no invocation can turn either
+	* on. `apps/cli/src/exec.ts` carries the mechanism and the egress probe.
+	*/
+	{
+		name: "exec",
+		summary: "Run a read-only traversal script over the corpus in a sandbox: multi-hop in ONE execution.",
+		args: [],
+		flags: [
+			{
+				name: "file",
+				type: "string",
+				description: "The script to run, as a path on the HOST. Omit it (or pass `-`) to read the script from stdin. Mutually exclusive with `--script`."
+			},
+			{
+				name: "script",
+				type: "string",
+				description: "The script source, inline. Mutually exclusive with `--file` and with reading stdin."
+			},
+			{
+				name: "timeout-ms",
+				type: "int",
+				description: "Wall-clock bound on the script. Exceeding it is `exitCode` 124 with `timedOut: true`, not an error envelope. Capped at 600000.",
+				default: 3e4
+			},
+			{
+				name: "sha",
+				type: "string",
+				description: "The commit to mount, materialized as a detached worktree. Defaults to HEAD. Never the live working tree, whose gitignored .memhtml/index.db a worktree omits."
+			}
+		],
+		responseTypes: ["exec.report"]
+	}),
+	{
+		name: "state export",
+		summary: "Write .memhtml/state/access.jsonl, the only durable copy of the state plane, and commit.",
+		args: [],
+		flags: [],
+		responseTypes: ["state.export"]
+	},
+	{
+		name: "state import",
+		summary: "Replay the committed sidecar into state.db. Counters merge by max, never last-wins.",
+		args: [],
+		flags: [],
+		responseTypes: ["state.import"]
+	},
+	{
+		name: "agents-doc",
+		summary: "Regenerate AGENTS.md from this command table. --check fails on drift.",
+		args: [],
+		flags: [{
+			name: "check",
+			type: "boolean",
+			description: "Compare the committed doc to the regenerated one and fail on a difference.",
+			default: false
+		}, {
+			name: "out",
+			type: "string",
+			description: "Where to write. Defaults to ./AGENTS.md."
+		}],
+		responseTypes: ["agents.doc"]
+	},
+	{
+		name: "serve mcp",
+		summary: "Run the `memhtml-mcp` stdio server: 14 tools and 2 resources over this same repo.",
+		args: [],
+		flags: [],
+		responseTypes: ["serve.exit"]
+	}
+];
+const COMMAND_NAMES = COMMANDS.map((command) => command.name);
+/**
+* The example op line, quoted verbatim into the `when-to-batch` block.
+*
+* A constant rather than a literal inside the prose, because a test parses it. An example an agent
+* copies has to be valid JSONL, and it stays valid because the doc and the parser read the
+* same bytes. A prose-only example drifts silently the first time a field is renamed.
+*/
+const GUIDE_OP_EXAMPLE = "{\"op\":\"write\",\"title\":\"One writer and many readers share the index\",\"type\":\"semantic\",\"body\":\"WAL admits a single writer at a time and any number of concurrent readers, so a CLI command and a running `memhtml serve mcp` can work against one store.\",\"tag\":\"infra\"}";
+/**
+* The guide: what an agent reads on its first call, before it has written anything.
+*
+* Prose, in a structured field, authored here beside `COMMANDS`, which is the design (spec
+* D8/G6). The manifest carries it on a bare `memhtml`, `memhtml help`, `memhtml --help`, and `memhtml manifest`, and
+* `memhtml agents-doc` renders these same strings into `AGENTS.md`, so the doc and the live answer cannot
+* disagree. Prose kept in a separate Markdown file would be a second copy that drifts, and prose kept
+* only in `AGENTS.md` would be invisible to an agent that never opens the repo.
+*
+* Written for an LLM agent mid-task rather than for an operator browsing: complete sentences, action
+* first, and every claim true of this build rather than of the design. A guide that describes an
+* intention is worse than no guide, because an agent acts on it.
+*/
+const GUIDE = [
+	{
+		topic: "first-call",
+		body: "You are reading this CLI's manifest: every command, argument, flag, response type, error code, and environment variable the binary accepts. A bare `memhtml`, `memhtml help`, `memhtml --help`, and `memhtml manifest` all return it, and all four answer on a machine with no repo, no database, and no credentials, so this is also the liveness check when something else has failed. Every command writes exactly ONE JSON envelope to stdout and nothing else; logs go to stderr. A success is `{apiVersion, type, data}` and a failure is `{apiVersion, error, code, suggestions}`. Branch on `code`, never on the `error` prose: the codes and response types are append-only and a shipped one never changes meaning, while the prose changes freely as wording improves. Exit 0 is success, exit 2 is a usage error you fix by changing the call, exit 1 is a runtime failure you fix by changing the repo or the environment. Add `--dense` to any command to get minified JSON with null fields dropped, which is what you want when the output goes into a prompt."
+	},
+	{
+		topic: "write-surfaces",
+		body: "There are three ways to put a memory into the corpus, and they are all legitimate. First, this CLI: `memhtml write` for one memory, `memhtml apply` for many. Second, the MCP server: `memhtml serve mcp` speaks stdio with 14 tools and 2 resources over this same repo, and it is the door to use when you are already an MCP client. Third, editing files under $MEMHTML_ROOT directly with your normal file tools: the git tree IS the system of record and `.memhtml/index.db` is only a projection of it, so a hand-written or hand-edited memory file is as real as one this CLI wrote. `memhtml index update` projects uncommitted working-tree changes as well as committed ones, so a dirty edit is searchable before you commit it. What you take on by editing directly is everything the write path would have done for you: the file must satisfy the format (run `memhtml doctor`, and `memhtml read <path>` reports per-file format warnings), you own choosing a path that does not collide, you own noticing that the content already exists somewhere else, and you own the commit. The nightly `memhtml sleep run` refuses to start on a dirty tree, so an uncommitted edit blocks curation until it is committed or stashed. A CLI command and a running `memhtml serve mcp` may share one store: the index is WAL SQLite, which admits one writer at a time and any number of concurrent readers, so a second writer waits its turn rather than failing. The one thing to keep clear of is `memhtml sleep run`, and for a git reason rather than a database one: a run holds a checked-out `sleep/<date>` branch, so a write landing during it commits onto that branch and is merged as if it were curation or lost when the branch is dropped."
+	},
+	{
+		topic: "when-to-batch",
+		body: `Writing more than about three memories in one task? Call \`memhtml apply\` once with a JSONL op stream instead of running \`memhtml write\` N times. A batch stages every file, makes ONE commit, and reindexes ONCE, where N separate writes make N commits and pay N index passes over N diffs. Pass the stream as \`memhtml apply --file ops.jsonl\`, or pipe it: \`memhtml apply -\` and a bare \`memhtml apply\` both read stdin. One complete JSON object per line, no wrapping array, no pretty-printing. A line looks like this:
+${GUIDE_OP_EXAMPLE}\n\`op\` is \`write\` (the only verb in the vocabulary today), \`title\` and \`type\` are required, and each op carries the same optional fields \`memhtml write\` takes, in snake_case: \`path\`, \`workspace\`, \`tag\`, \`entity\`, \`importance\`, \`confidence\`, \`session_id\`, \`prompt_id\`, \`turn_uuid\`. The whole file is validated for shape before ANY op executes, so a malformed line 7 is exit 2 naming line 7 with nothing written. A failed apply costs you nothing but the call. You get one result per op in INPUT ORDER, each naming its own \`index\`, so you can match results back to the lines you sent. A batch is ATOMIC by default: the first refused op aborts the whole batch, no file is written, no commit is made, and the surviving ops report \`skipped: true\`. Pass \`--continue-on-error\` for best-effort instead, and a refused op comes back as one failed result carrying its own \`code\` and \`error\` while every op that succeeded lands in the one commit. A duplicate is never an error: an op whose exact content is already stored comes back \`ok: true\` with \`deduped: true\` and the existing path, so re-applying a file you already applied is safe and writes nothing. \`commit_sha\` is null exactly when nothing was committed: a batch that only deduped, or one that aborted.`
+	},
+	{
+		topic: "conflicts",
+		body: "Pass `--detect-conflicts` to `memhtml apply` and each result gains a `conflict` field naming what that op's claim contradicts. Dedupe catches an op whose content is IDENTICAL to something stored; this catches an op that says something DIFFERENT about the same thing, the case dedupe is blind to and the one that actually rots a corpus. The match is grammatical, not semantic: a claim is split into a frame (the subject and relation, up to its last `of`/`is`/`in`/`to`/`by`/`as`) and a value, and two claims conflict when they share a frame. `The pool ceiling is 64` and `The pool ceiling is 128` share `the pool ceiling is`. `conflict.path` names an ACTIVE memory already holding that slot; `conflict.batch_index` names an EARLIER op in this same call, which is the case nothing else can see because neither op is stored yet; `conflict.claim` is the other claim's own text, so you can decide without a second read. It is null when nothing matched, and also when the claim has no frame shape. The rule refuses frames under three tokens and values over six, so short claims and claims trailed by a clause are deliberately unmatched rather than loosely matched. On a line using `article_html` instead of `body` it is always null, because the claim lives inside your markup and is not read until the store renders it. THE ASSIST NEVER CHANGES WHAT IS WRITTEN. An op carrying a conflict is written exactly as it would have been without the flag: nothing is archived, nothing is refused, and later does not win. That is deliberate, because sometimes the contradiction IS the answer. A memory recording that a runbook step changed necessarily contradicts the memory stating the old step, and a system that resolved that for you would delete the pair a reader needs in order to see the change at all. You decide per conflict: keep both (they are about different things, or both are true), `memhtml correct <path>` instead (the new claim supersedes the old one, and the old one stays readable under archive/), or drop the line (you were about to restate something already stored). Archived memories never match, so a superseded claim stops contradicting the claim that superseded it.\nWhen you have already decided that later wins (a re-scrape, a settings sync, any stream where each line is the newest statement of its slot), pass `--consolidate last-wins` (the batch tool's `consolidate: \"last-wins\"`) and the batch RESOLVES those matches instead of reporting them. Ops sharing a frame key write ONE file carrying the LATER value at the FIRST index that claimed the slot; each later restatement reports `consolidated_into` naming that slot and the summary counts it under `consolidated`, neither written nor failed. A stored ACTIVE memory occupying a surviving slot is archived with a supersedes link from the new file, its archive path reported as `superseded_path`, the same chain `memhtml correct` leaves, so ancestry reads identically. OFF by default, and the key is the conflict rule's own: the frame split is a rule measured in the eval harness before it was believed and ported verbatim into `@memhtml/domain`'s frame.ts, which detection and consolidation share, so anything the rule refuses to key (short frames, clause values) is never consolidated, and what you saw reported with `--detect-conflicts` is exactly what this flag would have acted on.\nEvery supersede, `memhtml correct` and `--consolidate last-wins` alike, also stamps a VALIDITY WINDOW, in the same one commit. The superseded memory gains `memhtml-valid-until` set to the moment the new fact became true (the winner's own `memhtml-valid-from`, else its first `<time datetime>`, else the operation's instant), and the winner gains `memhtml-valid-from` at that same moment, so one window closes exactly where the next opens. Min-wins: a memory already stating an EARLIER `memhtml-valid-until` keeps it, because a fact cannot outlive its earliest stated bound. That is what `--as-of` on `memhtml search` reads: pass an ISO instant and the result is what was believed valid AT THAT MOMENT. Since-superseded memories return, each marked `superseded_by` naming what replaced it, and facts not yet valid then are absent. History is read from the files, not replayed from git, so it survives a full index rebuild."
+	},
+	{
+		topic: "authoring",
+		body: "Every write authors the article in exactly one of two ways, and supplying both or neither is refused. Either you write prose and the template owns the markup (`--claim` is the one load-bearing sentence and becomes the `<mark>` claim span and `files.gist`, and each `--body` is one paragraph after it) or you supply `--article-html` and own the markup yourself. On a `memhtml apply` line the prose form is the `body` field, whose first sentence becomes the claim, and the markup form is `article_html`. When you supply markup you own two constraints. It must contain EXACTLY ONE `<mark>`, and that `<mark>` must sit in the article's first `<p>` or `<li>` and not inside an `<aside>` or `<details>`. The claim leads the article and is never a caveat or behind a fold. And the first `<time datetime>` in your markup becomes the memory's event time, which is what recency ranks on, so a memory about something that happened last year should say so rather than being ranked as today's news. Markup is checked before anything is written: the store renders your article, runs the format check, and refuses with the list of violations before it creates a file, stages it, or commits. A refused write leaves the tree byte-identical, so a failed attempt costs nothing and you can fix the markup and retry. Code goes in the prose path as a fenced block: a body paragraph that is entirely a ``` fence becomes <figure><pre><code>, whitespace preserved verbatim, and the fence's info string (```ts) is stamped as data-lang and promoted to a `lang:ts` entity, so `memhtml list --entity lang:ts` finds every memory carrying TypeScript. A blank line inside a fence does NOT split paragraphs. On the markup path write the same <figure><pre><code data-lang=\"ts\"> yourself; never `class` (forbidden) and never `lang=` (that attribute names human languages)."
+	},
+	{
+		topic: "code-mode",
+		body: "Answering a question that takes MORE THAN ONE HOP through the corpus? Write it as a script and run `memhtml exec` once, instead of spending a tool call per hop. Supersedence ancestry, live contradiction pairs, orphan census, entity co-occurrence, 'which of these 40 paths has no backlink': each of those is one traversal in code and N round trips through `memhtml read` and `memhtml neighbors`. Measured on a 305-file corpus: a full census in 598ms, and 410 edges resolved into 201 chains, longest 8 hops, in one execution at 430ms. The script runs under QuickJS in a sandbox with the corpus mounted READ-ONLY at `/mnt/memhtml`, and a helper is already seeded for you at `/workspace/lib/corpus.mjs`. Import it: `import { corpus, backlinks, chain, edges } from \"/workspace/lib/corpus.mjs\"`. `corpus()` returns a Map keyed by root-absolute path (the SAME string an edge's href holds, so `memories.get(link.href)` resolves with no path juggling) and each value carries `claim`, `memoryType`, `status`, `tags`, `entities`, `links`, `facets`, `citations`, `eventAt`, and a `document` escape hatch for any selector the fields do not cover. Print your answer as JSON on stdout with `console.log`; it comes back verbatim in `data.stdout`, so keep it small and structured rather than dumping the corpus. THREE THINGS IT CANNOT DO, by design. It cannot write: the corpus is read-only and a write answers EROFS, so every write still goes through `memhtml write` / `memhtml apply`, which own commits, dedup, and conflict detection. It cannot rank: no cosine, no RRF, no salience, and no index database. For ranked retrieval shell out to `memhtml search --json` and parse its envelope, which the one-envelope-per-command contract already makes a code-mode API. And it cannot reach the network: there is no curl and the guest's `fetch` refuses on call. The intended opening move is ranked retrieval FIRST, code-mode second: `memhtml search` or `memhtml recall` to get the handful of paths the ranking stack says matter, then `memhtml exec` to walk, join, count, and filter from there. Starting in code-mode means starting with a full-corpus scan and no relevance signal. A non-zero `exitCode` in the response is YOUR script failing, not the command failing. Read `data.stderr` for the diagnostic and the exit code is still 0. A script that runs past `--timeout-ms` (default 30000) comes back `exitCode: 124` with `timedOut: true`. The tree you get is a pinned commit, HEAD by default, named in `data.sha`, so an answer is reproducible with `--sha`, and an uncommitted edit is NOT visible to the script."
+	}
+];
+const GUIDE_TOPICS = GUIDE.map((block) => block.topic);
+
+//#endregion
+//#region apps/cli/dist/prose.js
+/**
+* Prose → claim derivation: the single implementation both write doors use.
+*
+* The tools take `{title, body}` because that is what a model produces, and the format needs a
+* `<mark>` claim plus one `<p>` per paragraph. Turning the first into the second is a text heuristic,
+* and it lives here for two reasons. It was duplicated once, as `claimOf`/`restOf` in `apps/mcp` and
+* `claimFromProse`/`proseTail` in `apps/cli`, the same regex in two packages. A sentence-splitting
+* rule that drifts between the doors also makes `memhtml apply` and `memory_write_batch` derive different
+* claims from the same body, so the gist of a memory would depend on which door wrote it.
+*
+* It does not live in `@memhtml/html`, which owns markup and the format's own rules. "Where does a
+* sentence end" is a guess about natural-language prose, and the format states no such constraint. It
+* is not in `operations.ts` either, because that module holds the use cases both doors call, and this
+* is a text helper they apply before calling one.
+*
+* The derivation is defense in depth now; it was once the only guard. `@memhtml/html` constraint 1 now
+* rejects an empty `<mark>` outright, so a door that skipped this would be stopped by the store's
+* render gate instead of landing a file with an empty `files.gist`. What is left here is the
+* authoring convenience the doors exist to provide: a JSONL line and an MCP call carry no `claim`
+* field, so the door derives one instead of asking an author to restate the body's first sentence.
+*/
+/**
+* Split prose into paragraphs on blank lines, dropping the empties. Inside a fenced code block a
+* blank line is content, so the split skips it there. Without that carve-out, a snippet containing a
+* blank line splits into two paragraphs, neither of which is a complete fence, and both land as
+* escaped backtick text instead of the `<figure><pre><code>` an intact fence renders as.
+*
+* The fence grammar comes from `@memhtml/html` (`fenceOpeningOf`/`closesFence`) rather than a second
+* copy here. The splitter deciding "this is one block" and the template deciding "this is a fence"
+* must be the same judgment, or the doors drift the way the claim derivation once did.
+*/
+const paragraphsOf = (prose) => {
+	const parts = [[]];
+	let opening;
+	for (const line of prose.split("\n")) {
+		const current = parts.at(-1);
+		if (opening === void 0 && line.trim() === "") {
+			if (current.length > 0) parts.push([]);
+			continue;
+		}
+		current.push(line);
+		if (opening === void 0) opening = fenceOpeningOf(line);
+		else if (closesFence(line, opening)) opening = void 0;
+	}
+	return parts.map((lines) => lines.join("\n").trim()).filter((part) => part !== "");
+};
+/**
+* The claim: the first sentence of the prose.
+*
+* The first sentence is where a model puts the assertion. Taking the title instead would make every
+* gist a restatement of the filename, which is the one thing a Tier-1 disclosure line must not be.
+* Prose with no sentence terminator is its own claim in full. A fragment is still an assertion, and
+* rejecting it would reject the shortest legitimate memory there is.
+*/
+const claimFromProse = (prose) => {
+	const trimmed = prose.trim();
+	return (/^(.*?[.!?])(\s|$)/s.exec(trimmed)?.[1] ?? trimmed).trim();
+};
+/**
+* The prose after the claim, as paragraphs. Empty when the claim was the whole body.
+*
+* The first element becomes the claim paragraph's own tail rather than a second `<p>`, which is
+* `articleHtmlFor`'s contract in `@memhtml/html`'s template. A one-paragraph body therefore yields
+* exactly one `<p>` with the `<mark>` inside it, which is what constraint 1 requires.
+*/
+const proseTail = (prose) => {
+	const remainder = prose.trim().slice(claimFromProse(prose).length).trim();
+	return remainder === "" ? [] : paragraphsOf(remainder);
+};
+
+//#endregion
+//#region apps/cli/dist/apply.js
+/**
+* Every field a line may carry, mapped to the `WriteParams` field it becomes.
+*
+* A table rather than a hand-written decode, so the snake_case → camelCase rename is stated once and
+* the unknown-field check below is derived from it. The MCP tool's parameters use exactly these
+* snake_case names (`apps/mcp/src/tools.ts`), so an agent that learned the field names from one door
+* can write a JSONL file for the other without translating.
+*/
+const SCALAR_FIELDS = {
+	title: "title",
+	type: "memoryType",
+	body: "body",
+	article_html: "articleHtml",
+	path: "path",
+	workspace: "workspace",
+	importance: "importance",
+	confidence: "confidence",
+	session_id: "sessionId",
+	prompt_id: "promptId",
+	turn_uuid: "turnUuid",
+	status: "taskStatus",
+	due: "dueAt"
+};
+/** Fields that accept a string or an array of strings, and always become an array. */
+const LIST_FIELDS = {
+	tag: "tags",
+	tags: "tags",
+	entity: "entities",
+	entities: "entities"
+};
+/** `op` is the discriminator rather than a `WriteParams` field, so it is legal and never mapped. */
+const KNOWN_FIELDS = /* @__PURE__ */ new Set([
+	"op",
+	...Object.keys(SCALAR_FIELDS),
+	...Object.keys(LIST_FIELDS)
+]);
+
+//#endregion
+//#region apps/cli/dist/doctor.js
+/** The year a run's repairs partition archive lookups under: the current calendar year. */
+const currentYear = Effect.clockWith((clock) => Effect.map(clock.currentTimeMillis, (millis) => new Date(millis).getUTCFullYear()));
+/** Today as `YYYY-MM-DD`, through the Effect clock so a test can pin what "overdue" means. */
+const todayDate = Effect.clockWith((clock) => Effect.map(clock.currentTimeMillis, (millis) => new Date(millis).toISOString().slice(0, 10)));
+/** An ISO-8601 UTC second, for the `memhtml-updated` stamp a repair writes. */
+const nowSecond = Effect.clockWith((clock) => Effect.map(clock.currentTimeMillis, (millis) => `${new Date(millis).toISOString().slice(0, 19)}Z`));
+
+//#endregion
+//#region apps/cli/dist/run.js
+const KNOWN_FLAGS = /* @__PURE__ */ new Set([...GLOBAL_FLAGS.map((flag) => flag.name), ...COMMANDS.flatMap((command) => command.flags.map((flag) => flag.name))]);
+/**
+* The two-word command names, longest first.
+*
+* A subcommand is matched greedily so `index status` beats `index`, and the leftover tokens become
+* positionals. Matching the shorter name first would make `memhtml index status` a call to a
+* hypothetical `index` command with `status` as an argument, which is a wrong answer rather than an
+* error.
+*/
+const COMPOUND_NAMES = COMMAND_NAMES.filter((name) => name.includes(" ")).sort((left, right) => right.length - left.length);
+/** Today as `YYYY-MM-DD`, through the Effect clock so a test can pin the run date. */
+const today = Effect.clockWith((clock) => Effect.map(clock.currentTimeMillis, (millis) => new Date(millis).toISOString().slice(0, 10)));
+
+//#endregion
+//#region apps/mcp/src/failure.ts
+/**
+* The MCP wire failure: one error class, declared on every tool, whose `.message` IS the response an
+* agent reads.
+*
+* **Why a declared class at all.** `McpServer` has three catch branches for a failed `tools/call`
+* (`McpServer.ts:831-847`, effect 4.0.0-beta.102) and only ONE of them lets prose through. An
+* `AiError`, which is what this module replaced, takes branch 1 and is rewritten to "Tool execution
+* failed due to an internal server error" unless its reason is a parameter-validation error. A value
+* the tool's own `failureSchema` accepts takes branch 2, where `error instanceof Error ? error.message`
+* passes the text through verbatim. The schema declaration is therefore the whole
+* difference between an agent that can recover and an agent that reads a sentence with no content in
+* it. `Effect.tapCause(Effect.logError)` runs before all three branches, so stderr logging is
+* unaffected either way.
+*
+* **Why the message is composed at construction.** `McpServer` reads `.message` and nothing else.
+* `code` and `suggestions` are not on the wire as fields, because MCP's tool-error channel is one
+* text block. So the three parts are folded into the string HERE, once, and the structured fields stay
+* for tests and for any future surface that can carry them. A consumer that wanted the code back out
+* reads the prefix, which is why the code comes first and is followed by a colon: `ERR_*` is a stable
+* vocabulary and the prose after it is not.
+*
+* **Why `Schema.TaggedError` rather than a hand-written `Error` subclass.** `Schema.is(failureSchema)`
+* is the branch-2 predicate, so the value has to be something a schema accepts, and it has to be an
+* `Error` for `.message` to be read. `Schema.TaggedError` is the one construction that is both: an
+* instance is `instanceof Error`, `Schema.is` accepts it, and `Schema.is` REJECTS a plain `Error`,
+* which is what keeps a genuine defect on branch 3 where it belongs. All three of those are asserted
+* in `tests/failure.test.ts`, so the construction cannot be swapped for one that loses any of them.
+*/
+var ToolFailure = class extends Schema.TaggedError()("ToolFailure", {
+	/** The stable code, from the same `ERROR_CODES` vocabulary the CLI envelope publishes. */
+	code: Schema.String,
+	/** The composed wire text: code, reason, then suggestions. This is what the agent reads. */
+	message: Schema.String,
+	/** The suggestions, kept structured so a test can assert them without parsing prose. */
+	suggestions: Schema.Array(Schema.String)
+}) {};
+const isTagged = (value) => typeof value === "object" && value !== null && typeof value._tag === "string";
+const text = (value) => typeof value === "string" ? value : void 0;
+/**
+* What to do about a failure, phrased as calls this agent can actually make.
+*
+* The reader is an LLM mid-task holding fourteen tools and no shell. `suggestionsFor` in
+* `apps/cli/src/errors.ts:115-137` answers the same question for a human at a prompt and answers it in
+* `memhtml` commands and `git` invocations, every one of which is unreachable from here. A suggestion
+* an agent cannot execute costs more than none: it spends the model's attention on a plan that ends in
+* "I don't have a terminal", and the recovery that WAS available goes unmentioned. So this is a
+* deliberate parallel mapping rather than a reuse, and the rule it holds to is that every string names
+* a tool in the toolkit or an action inside the current call's own control.
+*
+* The path payloads are interpolated rather than left as `<path>` placeholders: the agent has to type
+* the argument, and a code that already knows the path and does not say it forces a `memory_list` the
+* response could have skipped.
+*
+* The FIRST suggestion is always the action, and any state the agent needs in order to trust that
+* action comes second. `toToolFailure` joins the list behind "Try: ", so a list that opened with
+* "nothing was written" would put a fact where the reader is looking for a verb.
+*
+* `DirtyTree`, `GitFailure` and `StorageFailure` share the same answer, and it states the ceiling:
+* an agent cannot commit, stash, or repair a database from a tool call. `memory_status` is
+* the one read that distinguishes "the repo is wedged" from "that one write raced", and escalation is
+* the correct terminal move rather than a retry loop.
+*/
+const mcpSuggestionsFor = (error) => {
+	if (!isTagged(error)) return [];
+	switch (error._tag) {
+		case "PathNotFound": return ["call memory_search with a query for what you were looking for", "call memory_list to page the corpus by type or workspace"];
+		case "WriteConflict": return [`call memory_read on ${text(error.path) ?? "that path"} to get the current content`, "re-apply your change to that content and retry the write"];
+		case "DuplicateContent": return [`call memory_read on ${text(error.existingPath) ?? "that path"} — your content already lives there`, "nothing was written and no commit was made, so there is nothing to clean up"];
+		case "InvalidMemory": return ["fix the violated constraint named above and call the same tool again", "nothing was written and no commit was made — the store refused at the render gate"];
+		case "ModelUnavailable": return ["retry — search degrades to the lexical floor without the embedder, so results are narrower but real", "call memory_status to see whether the embedder is up"];
+		case "EmbedModelMismatch": return ["keep working — memory_search still runs on the lexical, recency, and salience arms", "the vector arm stays unusable until an operator rebuilds the index"];
+		case "DirtyTree":
+		case "GitFailure":
+		case "StorageFailure": return ["call memory_status to see repo health: HEAD, dirty state, and index freshness", "report this to the operator if it persists — an agent cannot repair the repo from a tool call"];
+		case "DiscriminationFailed": return ["call memory_status to see when sleep last ran", "report this to the operator"];
+		default: return [];
+	}
+};
+/**
+* A reason ending in a sentence terminator, so the suggestions read as a second sentence.
+*
+* `messageFor` returns fragments without final punctuation because the CLI envelope carries the reason
+* in its own JSON field and the suggestions in another, so there is nothing to run together. Here the
+* three parts share one string, and "no memory at areas/x.html Try: call memory_search" is a sentence
+* an LLM has to re-parse.
+*/
+const sentence = (reason) => /[.!?]$/.test(reason) ? reason : `${reason}.`;
+/**
+* A typed domain failure as the wire failure.
+*
+* Total by construction, three times over: `codeFor` maps an unknown `_tag` to `ERR_UNKNOWN`,
+* `messageFor` maps it to a stated fallback, and `mcpSuggestionsFor` returns an empty array. So an
+* error class added upstream tomorrow reaches an agent as prose with a documented code rather than as
+* the internal-error string. That string is the failure mode this whole module exists to end, and it
+* would come straight back if the mapping could fall off the end.
+*
+* The reason text is `messageFor`'s and only `messageFor`'s: it excludes the driver's message, the
+* SQL, the git argv, and every memory body, because each error class dropped those at its adapter edge
+* so that a tool response could not carry corpus content. Enriching past it here would undo that at
+* the one boundary where the content leaves the process.
+*/
+const toToolFailure = (error) => {
+	/**
+	* An already-composed failure passes through UNCHANGED, and that branch is what lets a handler
+	* compose its own wire failure at all.
+	*
+	* `handled` in `handlers.ts` is `Effect.mapError(toToolFailure)` over every handler, so a handler that
+	* fails with a `ToolFailure` it built itself arrives here too. `batchAbortFailure` is that case,
+	* since it needs an op index no typed domain error carries. Without this branch it falls off the end
+	* of `codeFor`'s switch (its `_tag` is `"ToolFailure"`, in no error vocabulary) and is rewritten to
+	* `ERR_UNKNOWN: unexpected failure: ToolFailure`, the whole composed message replaced by its own
+	* class name. That is the masking this module exists to end, arriving from the inside. Caught by the
+	* batch abort tests; kept here rather than by exempting the batch handler from `handled`, since a
+	* handler outside the one error translation is a handler that can leak an untranslated failure.
+	*/
+	if (error instanceof ToolFailure) return error;
+	const code = codeFor(error);
+	const suggestions = mcpSuggestionsFor(error);
+	const reason = sentence(messageFor(error));
+	return new ToolFailure({
+		code,
+		suggestions,
+		message: suggestions.length === 0 ? `${code}: ${reason}` : `${code}: ${reason} Try: ${suggestions.join("; ")}`
+	});
+};
+/**
+* An atomic batch's abort as the wire failure, naming the op that caused it.
+*
+* **Why the error channel and not a success payload.** An atomic batch that aborted wrote nothing, made
+* no commit, and produced no path, so there is no result to return, and a success response carrying
+* `written: 0` is one an agent has to inspect to discover its call did nothing. Every other refusal on
+* this server is an error, so a batch that refused through the success channel would be the one tool
+* whose failures an agent could miss by not looking. `memory_write_batch`'s description promises exactly
+* this ("the first refused op aborts the whole call … and the failure names the offending op as
+* ops[N]"), and that promise is what this function makes true.
+*
+* **Why it is composed HERE rather than in the handler.** `failure.ts` is the single place the wire
+* failure is produced, and there are TWO atomic refusals that must be indistinguishable to a reader: the
+* handler's own per-op XOR check, and an op the store's render gate refused inside `batchWrite`. The
+* second arrives as a `BatchOpReport`, carrying a code and a reason STRING because `operations.ts`
+* already mapped the typed error and deliberately dropped it, so `toToolFailure` cannot be reached for
+* it. Two hand-composed messages would be two shapes for one outcome; one function is one shape.
+*
+* **Why the suggestions are the batch's own and not `mcpSuggestionsFor`'s.** The singular's advice for
+* `InvalidMemory` is "fix the violated constraint and call the same tool again", which is right and
+* incomplete here: the agent is holding N-1 ops that WOULD have landed, and the thing it most needs to
+* know is that `continue_on_error` exists. Both entries open with a verb, because the list is joined
+* behind "Try: ".
+*
+* The `code` is the op's own, carried through unchanged from `codeFor` so the batch and the singular
+* report one refusal under one code. An agent branching on `ERR_INVALID_MEMORY` must not have to know
+* which door produced it.
+*/
+const batchAbortFailure = (index, code, reason) => {
+	const suggestions = [`fix ops[${index}] and call memory_write_batch again`, "set continue_on_error to true to write the ops that would have succeeded"];
+	return new ToolFailure({
+		code,
+		suggestions,
+		message: `${code}: ops[${index}]: ${sentence(reason)} The batch is atomic, so nothing was written and no commit was made. Try: ${suggestions.join("; ")}`
+	});
+};
+
+//#endregion
+//#region apps/mcp/src/tools.ts
+/**
+* The fourteen tools: design.md §8 verbatim, plus `memory_write_batch` (spec 004 D7).
+*
+* **`parameters` is always `Schema.Struct`, never `Schema.Class`.** A client sends a plain object
+* literal, and a class schema's decode expects an instance. The failure is a decode error on every
+* call, at runtime, for every tool. This is the one trap the whole surface is arranged around.
+*
+* **Sleep is deliberately absent.** It is a cron/operator action producing a reviewable branch, not
+* something an agent fires mid-conversation: a sleep run rewrites confidence across the corpus,
+* archives memories, and creates a branch a human is expected to read. `memhtml sleep run` is the
+* entry point, and if the fleet ever wants one here it is `sleep_status` (read-only). The write
+* side stays behind an operator.
+*
+* Every `success` schema is also a `Schema.Struct`, so `tools/list` publishes a JSON Schema the
+* client can validate a response against rather than an opaque object.
+*
+* **Every tool declares `failure: ToolFailure`, and the omission is a silent wire bug.** A tool with
+* no declared failure schema gets `Schema.Never` (`Tool.ts:1265`), so `McpServer`'s declared-failure
+* predicate rejects everything and every failure, typed domain error included, is rewritten to
+* "Tool execution failed due to an internal server error" before it reaches the caller
+* (`McpServer.ts:831-847`). The declaration is what puts a tool's failures on the branch that passes
+* prose through; see `failure.ts` for the mechanism. `failureMode` is left at its `"error"` default
+* on purpose: the error CHANNEL is what `McpServer` catches, and `"return"` would instead fold the
+* failure into the success union, where the server would see a successful call carrying a failure
+* payload no MCP client knows to read.
+*/
+/** The eight types an agent may write. `arc` is system-written by the sleep cycle. */
+const WritableType = Schema.Literals(WRITABLE_MEMORY_TYPES);
+/** The nine MEMORY-class rels. A person or provenance rel cannot be named here. */
+const MemoryRelSchema = Schema.Literals(MEMORY_RELS);
+/**
+* A repo-root-relative path: `areas/oncall/rollback-order.html`.
+*
+* The git-tree form with no leading slash, which is `files.path`, and the ID of a memory. The
+* `<link href>` form in the HTML carries a leading slash and is converted at the store boundary, so
+* a tool never sees it.
+*/
+const MemoryPath = Schema.String;
+/**
+* `Schema.Finite`, not `Schema.Number`, for every numeric field.
+*
+* `Number` derives a JSON Schema with an `anyOf` carrying a STRING branch, because `Infinity` and
+* `NaN` are not JSON numbers and the codec represents them as strings. Probed on this beta,
+* `Schema.Number` derives `{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity",
+* "-Infinity","NaN"]}]}`. A client reading that sees a union where the tool wants a number. `Finite`
+* derives a clean `{"type":"number"}`.
+*/
+const Finite = Schema.Finite;
+/** A count: a non-negative quantity. */
+const Count = Schema.Int;
+/**
+* An optional parameter that a client may also send explicitly as `null`.
+*
+* A bare `Schema.optional(X)` is a WIRE BUG here, and it is the kind a byte-comparison fixture
+* cannot see: the derived JSON Schema publishes `{"anyOf":[{"type":"string"},{"type":"null"}]}` , telling
+* every client that `null` is acceptable, while the decoder rejects it with "Expected string |
+* undefined, got null" (both probed on effect 4.0.0-beta.102). So a client that read the schema and
+* did the obvious thing, sending `{"workspace": null}` for "no workspace", would get a decode error
+* on a call the published contract said was valid. Many clients serialize an absent optional exactly
+* that way.
+*
+* `optionalKey(NullOr(X))` makes the decoder accept all three forms a client can produce (absent,
+* a value, and `null`) and publishes the FLAT `{"anyOf":[{"type":"string"},{"type":"null"}]}`.
+* `optional` rather than `optionalKey` would derive a nested `anyOf` wrapping that union in a second
+* one, which is the same contract spelled in a way a client has to unwrap twice to read.
+*
+* `null` and absent both mean "not supplied", which is what the handlers normalize to `undefined`.
+*/
+const Optional = (schema) => Schema.optionalKey(Schema.NullOr(schema));
+/**
+* The services a tool handler may reach for, declared per tool.
+*
+* `Tool.make`'s `dependencies` is what moves a service from the handler's requirement set into the
+* TOOL's, so `kit.toLayer({…})` accepts a handler that yields `Store`, and the requirement then
+* surfaces on the layer where `layerApp` satisfies it. Without the declaration a handler that reads
+* a service is a type error, and the only ways out are casting the handler or building the services
+* inside it: the first loses the check that the app layer provides what the tools need, and the
+* second gives every tool call its own database connection.
+*
+* Each tool declares only what it actually uses, so a handler that grows a dependency has to say so,
+* which keeps `memory_search` provably unable to reach the store and write.
+*
+* A FUNCTION per set, not a shared constant: the option's type is a mutable array, so handing the
+* same array to fourteen tools would let one tool's construction mutate the dependency list of the
+* other thirteen.
+*/
+const READS = () => [DatabaseService];
+const WRITES = () => [
+	Store,
+	Indexer,
+	IndexRecorder,
+	ExtractorPort
+];
+const RETRIEVES = () => [Retrieval, DatabaseService];
+/**
+* The fields that author ONE memory, shared by `memory_write`'s parameters and `memory_write_batch`'s
+* op struct.
+*
+* D7 says the batch op is "the same fields as memory_write". Written twice, that is a claim two
+* literals make about each other and stop making the first time a field is added to one of them. An
+* agent that learned `tags` from `memory_write` and had it silently dropped by a batch op would get a
+* memory it could not find by the facet it filed it under. Shared, the widening is automatic and the
+* published schemas cannot disagree.
+*
+* A FUNCTION returning a fresh literal, matching `READS`/`WRITES` above: the field record is handed to
+* a schema constructor and nothing here should be able to observe another tool's construction.
+*/
+const writeFields = () => ({
+	title: Schema.String,
+	/**
+	* Prose. The first sentence becomes the `<mark>` claim and the rest becomes one `<p>` per blank-line
+	* paragraph. See `claimFromProse`/`proseTail` in `@memhtml/cli`'s `prose.ts`, the one copy this door and
+	* `memhtml apply` share. Optional because `article_html` is the other way to author the same article, and
+	* the handler refuses a call that names both or neither.
+	*/
+	body: Optional(Schema.String),
+	/** Pre-authored article markup, used verbatim in place of `body`. See the description's contract. */
+	article_html: Optional(Schema.String),
+	memory_type: WritableType,
+	path: Optional(MemoryPath),
+	workspace: Optional(Schema.String),
+	tags: Optional(Schema.Array(Schema.String)),
+	entities: Optional(Schema.Array(Schema.String)),
+	importance: Optional(Count),
+	confidence: Optional(Finite),
+	session_id: Optional(Schema.String),
+	prompt_id: Optional(Schema.String),
+	turn_uuid: Optional(Schema.String)
+});
+const MemoryWrite = Tool.make("memory_write", {
+	description: "Write one memory to the corpus. Returns the existing path with deduped=true when an active memory already holds this exact content. A duplicate creates no file and no commit. Supply EXACTLY ONE of `body` or `article_html`. Both or neither is refused. `article_html` is raw <article> inner markup used verbatim, and the caller owns the format: exactly one <mark>, inside the first <p> or the first <li>, and never inside <aside> or <details>; only elements from the closed vocabulary in docs/format.md; no class attribute, no style attribute, no <script>, no event handlers. The FIRST <time datetime=\"…\"> element becomes the memory's event time, which is what the recency arm ranks by, so an episodic memory about last week should carry last week's date, not today's. Markup that violates the format is refused before any file is written or committed. Code snippets: in `body` prose, a paragraph that is entirely a fenced code block (```ts … ```) becomes <figure><pre><code data-lang=\"ts\">, whitespace verbatim, and the language promotes to a `lang:ts` entity; a blank line inside the fence does not split it. In `article_html`, author the same markup yourself: data-lang, never class (forbidden) and never lang= (that names human languages). Call memory_write_batch ONCE rather than memory_write N times whenever this task will write more than about three memories: a batch stages every file, makes ONE commit, and reindexes ONCE, so it costs less than N calls and leaves a history a reader can follow. It returns one result per op in INPUT ORDER, each naming that op's index, its path, and whether it deduped. A batch is ATOMIC by default: the first refused op aborts the whole call, no file is written and no commit is made, and the failure names the offending op as ops[N]. Set continue_on_error to true for best-effort instead, and a refused op comes back as a failed result carrying its own code and reason while every surviving op lands in the one commit. A duplicate is never a failure: an op whose exact content is already stored returns ok with deduped=true and the existing path. Each op supplies EXACTLY ONE of body or article_html, the same rule memory_write follows.",
+	dependencies: WRITES(),
+	parameters: Schema.Struct(writeFields()),
+	failure: ToolFailure,
+	success: Schema.Struct({
+		path: MemoryPath,
+		created: Schema.Boolean,
+		deduped: Schema.Boolean,
+		existing_path: Schema.NullOr(MemoryPath)
+	})
+});
+/**
+* One op in a batch: a whole `memory_write` payload, with the tool name standing in for D4's `op`
+* discriminator.
+*
+* A nested `Schema.Struct`, which is what makes the array's `items` a published object schema with its
+* own `required`. Probed on effect 4.0.0-beta.102, `Schema.Array(Schema.Struct({…}))` derives the
+* struct INLINE under `items` rather than hoisting it into a `$defs` a client would have to resolve.
+* So `ops[].title` is as legible to a caller reading `tools/list` as `memory_write`'s own `title`, and
+* the `Optional` discipline carries in unchanged: an optional inside an op publishes the same FLAT
+* `{"anyOf":[{…},{"type":"null"}]}` and accepts absent, a value, or `null`.
+*/
+const BatchOp = Schema.Struct(writeFields());
+/** One op's outcome, mirroring `memhtml apply`'s own per-op payload field for field, in snake_case. */
+const BatchOpResult = Schema.Struct({
+	/** This op's position in the `ops` array the caller sent. Results come back in that order too. */
+	index: Count,
+	ok: Schema.Boolean,
+	/**
+	* Every field below is PRESENT and nullable rather than optional, for the reason `memory_write`'s
+	* `existing_path` is: a client reading an absent key cannot tell "this op did not dedupe" from "this
+	* server does not report dedupes", and an agent deciding whether to retry needs that distinction.
+	*/
+	path: Schema.NullOr(MemoryPath),
+	deduped: Schema.Boolean,
+	existing_path: Schema.NullOr(MemoryPath),
+	/** The stable `ERR_*` code for this op's refusal, null when it did not fail. */
+	code: Schema.NullOr(Schema.String),
+	error: Schema.NullOr(Schema.String),
+	/**
+	* True when this op was never attempted: an atomic abort reports every op other than the offending
+	* one as skipped, which is how a caller tells "refused" from "not reached".
+	*/
+	skipped: Schema.Boolean,
+	/**
+	* What this op's claim contradicts, when `detect_conflicts` was on and something matched. Null when
+	* the flag was off, when nothing matched, or when the claim states no frame shape.
+	*
+	* `Schema.NullOr(Schema.Struct(…))`, present like every field above rather than optional: a client
+	* reading an absent key cannot tell "this op conflicts with nothing" from "this server does not
+	* report conflicts", and the two lead to opposite decisions.
+	*
+	* ONE struct with both source fields nullable rather than a union of two, so a client reads `claim`
+	* unconditionally (that is the disagreement, and it is what the decision is made on) and then
+	* whichever of `path`/`batch_index` is non-null. A `Schema.Union` would publish two near-identical
+	* three-field shapes under an `anyOf` and force every consumer to discriminate before reading the
+	* field it wanted, which is the same trap the `body`/`article_html` XOR avoids by not being a union.
+	*/
+	conflict: Schema.NullOr(Schema.Struct({
+		/** The ACTIVE memory already holding this frame key. Null for an intra-batch match. */
+		path: Schema.NullOr(MemoryPath),
+		/**
+		* The EARLIER op in THIS call holding it. Null for a store match, and it has no path because
+		* that op's file does not exist yet. The batch has not been written when the assist runs.
+		*/
+		batch_index: Schema.NullOr(Count),
+		/** The other claim's own text. */
+		claim: Schema.String
+	})),
+	/**
+	* Set on a batch-internal LOSER under `consolidate: "last-wins"`: a later op with the same frame
+	* key replaced this op's value before anything was written, and the number is the caller-space
+	* index of the op whose position carries the surviving value. Null everywhere else, present like
+	* every field above so a client can tell "not consolidated" from "not reported".
+	*/
+	consolidated_into: Schema.NullOr(Count),
+	/**
+	* Set on a WINNER whose write superseded a live stored memory under `consolidate: "last-wins"`:
+	* the loser's ARCHIVE path, where its bytes now live. Null when nothing stored occupied the
+	* slot, and when the supersede degraded (the batch still wrote; the corpus is merely
+	* unconsolidated).
+	*/
+	superseded_path: Schema.NullOr(Schema.String)
+});
+const MemoryWriteBatch = Tool.make("memory_write_batch", {
+	description: "Write many memories in ONE commit: every op is validated first, every surviving file is staged, and the batch commits and reindexes exactly once. commit_sha is null when nothing was written: an all-deduped batch, or an aborted one. Supply EXACTLY ONE of `body` or `article_html`. Both or neither is refused. `article_html` is raw <article> inner markup used verbatim, and the caller owns the format: exactly one <mark>, inside the first <p> or the first <li>, and never inside <aside> or <details>; only elements from the closed vocabulary in docs/format.md; no class attribute, no style attribute, no <script>, no event handlers. The FIRST <time datetime=\"…\"> element becomes the memory's event time, which is what the recency arm ranks by, so an episodic memory about last week should carry last week's date, not today's. Markup that violates the format is refused before any file is written or committed. Code snippets: in `body` prose, a paragraph that is entirely a fenced code block (```ts … ```) becomes <figure><pre><code data-lang=\"ts\">, whitespace verbatim, and the language promotes to a `lang:ts` entity; a blank line inside the fence does not split it. In `article_html`, author the same markup yourself: data-lang, never class (forbidden) and never lang= (that names human languages). Call memory_write_batch ONCE rather than memory_write N times whenever this task will write more than about three memories: a batch stages every file, makes ONE commit, and reindexes ONCE, so it costs less than N calls and leaves a history a reader can follow. It returns one result per op in INPUT ORDER, each naming that op's index, its path, and whether it deduped. A batch is ATOMIC by default: the first refused op aborts the whole call, no file is written and no commit is made, and the failure names the offending op as ops[N]. Set continue_on_error to true for best-effort instead, and a refused op comes back as a failed result carrying its own code and reason while every surviving op lands in the one commit. A duplicate is never a failure: an op whose exact content is already stored returns ok with deduped=true and the existing path. Each op supplies EXACTLY ONE of body or article_html, the same rule memory_write follows. Set detect_conflicts to true and each per-op result gains a `conflict` field naming what that op's claim CONTRADICTS. This is not dedupe: dedupe catches an op whose content is IDENTICAL to something stored, while this catches an op that says something DIFFERENT about the same thing, the case dedupe is blind to, and the one that actually rots a corpus. The match is grammatical rather than semantic. A claim splits into a frame (the subject and relation up to its LAST of/is/in/to/by/as) and a value, and two claims conflict when they share a frame: 'The pool ceiling is 64' and 'The pool ceiling is 128' both key on 'the pool ceiling is'. conflict.path names an ACTIVE memory already holding that slot. conflict.batch_index names an EARLIER op in this same call, which no other tool can see because neither op is stored yet; it has no path for that reason. conflict.claim is the other claim's own text, so you can decide without a second call. conflict is null when nothing matched, when detect_conflicts was absent, when the claim states no frame shape (the rule refuses frames under three tokens and values over six, so short claims and claims trailed by a clause are deliberately unmatched rather than loosely matched), and always on an op that used article_html. The claim is inside your markup there and is not read until the store renders it. THE ASSIST NEVER CHANGES WHAT IS WRITTEN. An op carrying a conflict is written exactly as it would have been without the flag: nothing is archived, nothing is refused, later does not win, and the summary counts are unchanged. That is deliberate, not a limitation. Sometimes the contradiction IS the answer. A memory recording that a runbook step changed necessarily contradicts the memory stating the old step, and a system that resolved that for you would destroy the pair a reader needs in order to see the change at all. So YOU decide, per conflict: keep both (they are about different things, or both are true), call memory_correct on the named path instead (the new claim supersedes the old one, which stays readable under archive/), or drop the op. Archived memories never match, so a superseded claim stops contradicting the claim that superseded it. Set consolidate to \"last-wins\" and the batch RESOLVES frame-key matches instead of only reporting them: for ops sharing a claim slot (the same deterministic frame key the conflict rule uses), the LATER value wins. Exactly one file is written, at the FIRST index that claimed the slot, and every later restatement reports consolidated_into naming that slot instead of a path of its own. A stored ACTIVE memory occupying a surviving slot is archived with a supersedes link from the new file, its archive path reported on the winner as superseded_path. Off by default, and claims with no frame shape are never consolidated. The guards fail closed, so this only ever acts on claims the conflict rule would have matched.",
+	dependencies: WRITES(),
+	parameters: Schema.Struct({
+		ops: Schema.Array(BatchOp),
+		/** Best-effort mode: a refused op is reported and skipped, survivors land in the one commit. */
+		continue_on_error: Optional(Schema.Boolean),
+		/**
+		* Report each op's frame-matches as a per-op `conflict`. Propose-only: it changes nothing about what
+		* is written. `Optional` rather than defaulted-true because the assist costs one extra query per
+		* batch, and a caller that did not ask for the field would be paying for an answer it does not read.
+		*/
+		detect_conflicts: Optional(Schema.Boolean),
+		/**
+		* Opt-in deterministic last-wins consolidation over the conflict rule's own frame keys. A
+		* `Literals` of one value rather than a boolean, so the vocabulary can widen (a `first-wins`, a
+		* semantic mode) without a shipped `true` changing meaning under a caller.
+		*/
+		consolidate: Optional(Schema.Literals(["last-wins"])),
+		/**
+		* Batch-level provenance: the session this call is being made in. An op that names its own wins,
+		* because it is the more specific statement about where that one memory came from, which is what
+		* lets a batch replay writes from an earlier session without relabelling them.
+		*/
+		session_id: Optional(Schema.String),
+		prompt_id: Optional(Schema.String),
+		turn_uuid: Optional(Schema.String)
+	}),
+	failure: ToolFailure,
+	success: Schema.Struct({
+		results: Schema.Array(BatchOpResult),
+		/** Derived from `results` in one pass, so the counts cannot disagree with the array. */
+		summary: Schema.Struct({
+			total: Count,
+			written: Count,
+			deduped: Count,
+			failed: Count,
+			skipped: Count,
+			/** Batch-internal losers under `consolidate: "last-wins"`: neither written nor failed. */
+			consolidated: Count
+		}),
+		commit_sha: Schema.NullOr(Schema.String)
+	})
+});
+const MemoryRead = Tool.make("memory_read", {
+	description: "Read one memory in full: its head metadata, authored links, and complete article body. The only path to a <details> body, which recall never quotes. An explicit open of a named path COUNTS as salience. This is the read that moves the access plane, while a search or recall hit does not.",
+	/**
+	* `DatabaseService` is here because an explicit open bumps the access plane: `readMemory` reaches the
+	* state plane through `bumpAccess`, so the tool has to declare it or the handler is a type error. The
+	* widening is the salience rule made visible in the dependency set. `memory_search` still cannot
+	* reach it, which is what keeps a ranker's guess out of the plane.
+	*/
+	dependencies: [
+		Store,
+		IndexRecorder,
+		DatabaseService
+	],
+	parameters: Schema.Struct({
+		path: MemoryPath,
+		session_id: Optional(Schema.String)
+	}),
+	failure: ToolFailure,
+	success: Schema.Struct({
+		path: MemoryPath,
+		title: Schema.String,
+		body: Schema.String,
+		gist: Schema.String,
+		memory_type: Schema.String,
+		meta: Schema.Record(Schema.String, Schema.String),
+		links: Schema.Array(Schema.Struct({
+			rel: Schema.String,
+			href: Schema.String
+		})),
+		archived: Schema.Boolean,
+		warnings: Schema.Array(Schema.String)
+	})
+});
+const MemorySearch = Tool.make("memory_search", {
+	description: "Ranked search over the corpus: lexical, vector, recency, and salience arms fused with RRF, then diversified. Each hit carries a `snippet`: the text of the file's best-matching chunk for this query (its opening chunk when the vector arm did not fire), truncated with a trailing `…` when cut. `degraded` is true when the vector arm did not fire, so the result came from fewer signals. Each hit also carries `entities` in `type:name` form; pass one of those values back as `entity` to make the next call the second hop of a chain. That is two calls, not a guess about spelling. An `entity` scope that matches nothing returns NO hits and says so through `scope_empty`: this tool never widens a scope it could not satisfy. `as_of` is a point-in-time view: pass an ISO instant and the result is what was believed valid at that moment, including since-superseded memories (marked superseded_by). Returning a path changes nothing: a hit is this ranker's guess, so it never bumps salience. Call memory_read to open the one you chose, and memory_reinforce to record whether it was right.",
+	dependencies: RETRIEVES(),
+	parameters: Schema.Struct({
+		query: Schema.String,
+		limit: Optional(Count),
+		memory_types: Optional(Schema.Array(WritableType)),
+		workspace: Optional(Schema.String),
+		tags: Optional(Schema.Array(Schema.String)),
+		/**
+		* One entity reference in `type:name` form, the same spelling `memory_list` takes and the same
+		* spelling a hit's `entities` publishes, so a value read off a hit is a valid scope verbatim.
+		*/
+		entity: Optional(Schema.String),
+		include_archived: Optional(Schema.Boolean),
+		/**
+		* Point-in-time view: returns what was believed valid at this moment, including
+		* since-superseded memories (marked superseded_by). The window is
+		* `coalesce(valid_from, event_at, created_at) <= as_of < valid_until`. The supersede path
+		* stamps both ends, so history is read from the files rather than replayed from git.
+		*/
+		as_of: Optional(Schema.String)
+	}),
+	failure: ToolFailure,
+	success: Schema.Struct({
+		hits: Schema.Array(Schema.Struct({
+			path: MemoryPath,
+			title: Schema.String,
+			gist: Schema.String,
+			memory_type: Schema.String,
+			/** The fused RRF score. Unitless and comparable only within one result set. */
+			score: Finite,
+			confidence: Finite,
+			updated_at: Schema.String,
+			/**
+			* The best-matching chunk's text for THIS query (the vector arm's winning chunk, or the
+			* file's opening chunk on the degraded path), truncated with a trailing `…` when cut.
+			*/
+			snippet: Schema.String,
+			/**
+			* This memory's entity references in `type:name` form, sorted, possibly empty.
+			*
+			* The next hop's `entity` parameter, published in the form that parameter accepts: the whole
+			* point is that a caller chains by COPYING a value rather than by reconstructing one.
+			*/
+			entities: Schema.Array(Schema.String),
+			/**
+			* The path of the memory that superseded this one, or `null` when nothing has. Non-null
+			* only for an archived hit, which reaches a result through `as_of` or
+			* `include_archived`, so a point-in-time answer is legible as history. Present and
+			* nullable like `consolidated_into`: a client must be able to tell "not superseded" from
+			* "this build does not report supersession".
+			*/
+			superseded_by: Schema.NullOr(Schema.String)
+		})),
+		degraded: Schema.Boolean,
+		arms: Schema.Array(Schema.String),
+		/** The `entity` this search was scoped to, or `null` when it was not scoped by entity. */
+		entity_scope: Schema.NullOr(Schema.String),
+		/**
+		* True when a scope was named, it narrowed the query, and nothing survived it.
+		*
+		* A boolean in every case, following `degraded`: this is the field that makes an empty scoped
+		* result attributable to the scope, and it would be worth nothing if its absence had to be read
+		* as `false`.
+		*/
+		scope_empty: Schema.Boolean
+	})
+});
+const MemoryRecall = Tool.make("memory_recall", {
+	description: "A context pack under a character budget: full bodies for what fits, one index line each for what does not. Arcs are folded under their own envelope so a synthesis cannot crowd out the evidence behind it.",
+	dependencies: RETRIEVES(),
+	parameters: Schema.Struct({
+		query: Schema.String,
+		budget_chars: Optional(Count),
+		workspace: Optional(Schema.String)
+	}),
+	failure: ToolFailure,
+	success: Schema.Struct({
+		sections: Schema.Struct({
+			arcs: Schema.Array(Schema.Struct({
+				path: MemoryPath,
+				title: Schema.String,
+				gist: Schema.String,
+				body: Schema.String
+			})),
+			memories: Schema.Array(Schema.Struct({
+				path: MemoryPath,
+				title: Schema.String,
+				gist: Schema.String,
+				body: Schema.String
+			})),
+			/** What did not fit: claim plus path, for a deliberate drill-down. */
+			lateral: Schema.Array(Schema.Struct({
+				path: MemoryPath,
+				title: Schema.String,
+				gist: Schema.String
+			}))
+		}),
+		spent_chars: Count,
+		truncated: Schema.Boolean,
+		degraded: Schema.Boolean
+	})
+});
+const MemoryCorrect = Tool.make("memory_correct", {
+	description: "Supersede a memory: write the corrected version and archive the target in ONE commit, linked in both directions. Never edits in place. The superseded memory stays readable under archive/. Supply EXACTLY ONE of `body` or `article_html`. Both or neither is refused. `article_html` is raw <article> inner markup used verbatim, and the caller owns the format: exactly one <mark>, inside the first <p> or the first <li>, and never inside <aside> or <details>; only elements from the closed vocabulary in docs/format.md; no class attribute, no style attribute, no <script>, no event handlers. The FIRST <time datetime=\"…\"> element becomes the memory's event time, which is what the recency arm ranks by, so an episodic memory about last week should carry last week's date, not today's. Markup that violates the format is refused before any file is written or committed. Code snippets: in `body` prose, a paragraph that is entirely a fenced code block (```ts … ```) becomes <figure><pre><code data-lang=\"ts\">, whitespace verbatim, and the language promotes to a `lang:ts` entity; a blank line inside the fence does not split it. In `article_html`, author the same markup yourself: data-lang, never class (forbidden) and never lang= (that names human languages).",
+	dependencies: WRITES(),
+	parameters: Schema.Struct({
+		target_path: MemoryPath,
+		title: Schema.String,
+		/** The corrected prose; first sentence becomes the new `<mark>`. Exclusive with `article_html`. */
+		body: Optional(Schema.String),
+		/** Pre-authored markup for the superseding article, used verbatim. Exclusive with `body`. */
+		article_html: Optional(Schema.String),
+		reason: Schema.String,
+		session_id: Optional(Schema.String)
+	}),
+	failure: ToolFailure,
+	success: Schema.Struct({
+		path: MemoryPath,
+		superseded: Schema.Array(MemoryPath),
+		archived: Schema.Array(MemoryPath)
+	})
+});
+const MemoryLink = Tool.make("memory_link", {
+	description: "Assert an edge between two memories. Written into the source file's head, so it survives an index rebuild. Idempotent: re-linking the same pair commits nothing.",
+	dependencies: [Store, Indexer],
+	parameters: Schema.Struct({
+		src_path: MemoryPath,
+		rel: MemoryRelSchema,
+		dst_path: MemoryPath,
+		strength: Optional(Finite)
+	}),
+	failure: ToolFailure,
+	success: Schema.Struct({
+		ok: Schema.Boolean,
+		rel: Schema.String,
+		src_path: MemoryPath,
+		dst_path: MemoryPath
+	})
+});
+const MemoryNeighbors = Tool.make("memory_neighbors", {
+	description: "The memory graph around one path, to at most two hops, in both directions. Includes sleep-mined edges: lateral retrieval is what they are for.",
+	dependencies: READS(),
+	parameters: Schema.Struct({
+		path: MemoryPath,
+		depth: Optional(Count),
+		rels: Optional(Schema.Array(MemoryRelSchema))
+	}),
+	failure: ToolFailure,
+	success: Schema.Struct({
+		nodes: Schema.Array(Schema.Struct({
+			path: MemoryPath,
+			title: Schema.String,
+			/** 1-based distance from the centre: 1 or 2, never 0. */
+			hop: Count,
+			rel: Schema.String
+		})),
+		edges: Count
+	})
+});
+const MemoryArchive = Tool.make("memory_archive", {
+	description: "Soft-evict a memory: `git mv` into archive/<YYYY>/ with the archive stamps. Nothing is ever deleted, and `git log --follow` reads straight through.",
+	dependencies: [Store, Indexer],
+	parameters: Schema.Struct({
+		path: MemoryPath,
+		reason: Schema.String
+	}),
+	failure: ToolFailure,
+	success: Schema.Struct({
+		path: MemoryPath,
+		archive_path: MemoryPath
+	})
+});
+const MemoryReinforce = Tool.make("memory_reinforce", {
+	description: "Record that a memory helped or misled. Gated by a 900-second per-path cooldown, so a replayed query cannot inflate a memory's ranking; `cooled_down` lists the paths the cooldown held back.",
+	dependencies: READS(),
+	parameters: Schema.Struct({
+		paths: Schema.Array(MemoryPath),
+		signal: Schema.Literals(REINFORCE_SIGNALS)
+	}),
+	failure: ToolFailure,
+	success: Schema.Struct({
+		bumped: Schema.Array(MemoryPath),
+		cooled_down: Schema.Array(MemoryPath)
+	})
+});
+const MemoryList = Tool.make("memory_list", {
+	description: "Page through the corpus by facet. `next_cursor` is a keyset on the path, so a page stays correct even while a sleep cycle archives files.",
+	dependencies: READS(),
+	parameters: Schema.Struct({
+		memory_type: Optional(WritableType),
+		workspace: Optional(Schema.String),
+		tag: Optional(Schema.String),
+		entity: Optional(Schema.String),
+		para: Optional(Schema.Literals(PARA_BUCKETS)),
+		limit: Optional(Count),
+		cursor: Optional(Schema.String)
+	}),
+	failure: ToolFailure,
+	success: Schema.Struct({
+		files: Schema.Array(Schema.Struct({
+			path: MemoryPath,
+			title: Schema.String,
+			memory_type: Schema.String,
+			gist: Schema.String,
+			workspace: Schema.NullOr(Schema.String),
+			para: Schema.String,
+			confidence: Finite,
+			importance: Count,
+			archived: Schema.Boolean,
+			updated_at: Schema.String
+		})),
+		next_cursor: Schema.NullOr(Schema.String)
+	})
+});
+const TraceSearch = Tool.make("trace_search", {
+	description: "Find past Claude Code sessions by what was asked in them. A read-only index over transcript files: no session content is stored, only pointers and capped heads.",
+	dependencies: READS(),
+	parameters: Schema.Struct({
+		query: Schema.String,
+		cwd: Optional(Schema.String),
+		since: Optional(Schema.String),
+		limit: Optional(Count)
+	}),
+	failure: ToolFailure,
+	success: Schema.Struct({ sessions: Schema.Array(Schema.Struct({
+		session_id: Schema.String,
+		slug: Schema.String,
+		cwd: Schema.NullOr(Schema.String),
+		started_at: Schema.NullOr(Schema.String),
+		prompt_count: Count,
+		first_prompt: Schema.String,
+		ai_title: Schema.NullOr(Schema.String)
+	})) })
+});
+const TraceLinks = Tool.make("trace_links", {
+	description: "Which memories a session produced, or which sessions touched a memory. Needs a session_id or a path. Both absent is refused rather than returning every link ever recorded.",
+	dependencies: READS(),
+	parameters: Schema.Struct({
+		session_id: Optional(Schema.String),
+		path: Optional(MemoryPath)
+	}),
+	failure: ToolFailure,
+	success: Schema.Struct({ links: Schema.Array(Schema.Struct({
+		path: MemoryPath,
+		session_id: Schema.String,
+		prompt_id: Schema.NullOr(Schema.String),
+		turn_uuid: Schema.NullOr(Schema.String),
+		link_kind: Schema.String,
+		at: Schema.String
+	})) })
+});
+const MemoryStatus = Tool.make("memory_status", {
+	description: "Corpus health in one call: HEAD, dirty state, counts by type, edge totals, whether the index describes the current commit, and when sleep last ran.",
+	dependencies: [Store, DatabaseService],
+	/**
+	* `Tool.EmptyParams`, not `Schema.Struct({})`.
+	*
+	* Probed on effect 4.0.0-beta.102: an empty `Schema.Struct` derives
+	* `{"anyOf":[{"type":"object"},{"type":"array"}]}`, a union with an ARRAY branch, because a struct
+	* with no fields constrains nothing and the codec's encoded form admits both. A client reading that
+	* cannot tell it should send `{}`, and a strict one may refuse to call the tool at all.
+	* `Tool.EmptyParams` derives `{"type":"object","additionalProperties":false}`, which says exactly
+	* "an object, and no fields", the intent.
+	*/
+	parameters: Tool.EmptyParams,
+	failure: ToolFailure,
+	success: Schema.Struct({
+		head_sha: Schema.NullOr(Schema.String),
+		dirty: Schema.Boolean,
+		counts_by_type: Schema.Record(Schema.String, Count),
+		archived_count: Count,
+		edges: Count,
+		/** True when the index's watermark IS the current HEAD. A row count cannot answer this. */
+		index_fresh: Schema.Boolean,
+		embedder_up: Schema.Boolean,
+		last_sleep: Schema.NullOr(Schema.Struct({
+			run_id: Schema.String,
+			status: Schema.String,
+			started_at: Schema.String
+		}))
+	})
+});
+/**
+* The toolkit. Exactly fourteen: design.md §8's thirteen plus `memory_write_batch`.
+*
+* Order is the read order of the table in §8, which is also roughly the order an agent needs them:
+* write and read, then the three retrieval shapes, then the graph operations, then the trace plane,
+* then status.
+*
+* The batch sits SECOND, directly after `memory_write`, rather than appended at the end. `tools/list`
+* publishes this order and an agent reads it top-down, so the tool `memory_write`'s own description
+* points at is the very next entry. A pointer whose target is thirteen tools away is one an agent
+* reads after it has already decided how to write.
+*/
+const MemhtmlToolkit = Toolkit.make(MemoryWrite, MemoryWriteBatch, MemoryRead, MemorySearch, MemoryRecall, MemoryCorrect, MemoryLink, MemoryNeighbors, MemoryArchive, MemoryReinforce, MemoryList, TraceSearch, TraceLinks, MemoryStatus);
+/**
+* The tool names, derived from the toolkit rather than restated.
+*
+* Two lists would drift: a placeholder list that once said fourteen names and a toolkit that now
+* builds thirteen would leave a test asserting the list and proving nothing about the server.
+*/
+const TOOL_NAMES = Object.keys(MemhtmlToolkit.tools);
+
+//#endregion
+//#region apps/mcp/src/handlers.ts
+/**
+* Every handler's error translation, applied once.
+*
+* MCP has one error channel and it is prose, so a typed error's STRUCTURE cannot survive the
+* boundary. Everything a caller acts on can, folded into the one string the protocol carries:
+* `toToolFailure` composes the stable code, the reason with its actionable payload fields, and
+* suggestions phrased as tool calls this agent can make. Nothing leaks a driver message, a git argv,
+* or a memory body, because the reason is `messageFor`'s and each error class dropped those at its
+* adapter edge precisely so a tool response could not carry corpus content.
+*
+* This used to build an `AiError`, which was the bug. `McpServer` catches `AiError` FIRST and
+* rewrites it to a generic internal-error sentence unless its reason is a parameter-validation error
+* (`McpServer.ts:831-838`), so every typed failure this server produced reached its agent with the
+* content removed. A `ToolFailure` is what each tool's `failure:` schema declares, which puts it on the
+* branch that passes `.message` through verbatim. The two halves only work together: dropping the
+* declaration in `tools.ts` re-masks everything this function builds, and the wire test in
+* `tests-integration` is what holds that pair honest.
+*
+* The error type is now `ToolFailure` for every handler, and `kit.toLayer` checks it, so a handler
+* that failed with a raw domain error would be a compile error rather than a masked response. This is
+* the single place the wire failure is produced.
+*/
+const handled = (effect) => effect.pipe(Effect.mapError(toToolFailure));
+/**
+* The head metadata as a flat string record.
+*
+* Flattened rather than typed per key: the wire schema is `Record<string, string>` because the head's
+* optional metas are genuinely open at the edges. A format version can add `memhtml-*` names, and a
+* client that had to know the closed set would break on the first addition. Numbers are stringified
+* because that is what the `<meta content>` attribute holds; a consumer that wants the number reads
+* the typed field on `memory_search` or `memory_list` instead.
+*/
+const metaRecord = (doc) => {
+	const out = {};
+	for (const [key, value] of Object.entries(doc.metas)) {
+		if (value === void 0) continue;
+		out[key] = typeof value === "string" ? value : String(value);
+	}
+	for (const entity of doc.entities) out[`entity:${entity}`] = "true";
+	for (const tag of doc.tags) out[`tag:${tag}`] = "true";
+	return out;
+};
+/**
+* An explicit `null` as an absent value.
+*
+* The parameter schemas accept `null` as well as absence, and `Optional` in `tools.ts` says why: the
+* derived JSON Schema advertises `null`, and a client that reads the schema and sends
+* `{"workspace": null}` for "no workspace" is doing the documented thing. The operations layer speaks
+* `undefined` for "not supplied" because `exactOptionalPropertyTypes` distinguishes an absent key from
+* a present one, so the two vocabularies meet HERE, once, rather than at each of fourteen call sites.
+*/
+const opt = (value) => value ?? void 0;
+/** Absent optional array as an empty one, so a handler never passes `undefined` downstream. */
+const arr = (value) => value ?? [];
+const authored = (body, articleHtml) => {
+	const prose = opt(body);
+	const markup = opt(articleHtml);
+	const hasProse = prose !== void 0 && prose.trim() !== "";
+	const hasMarkup = markup !== void 0 && markup.trim() !== "";
+	if (hasProse === hasMarkup) return Effect.fail(InvalidMemory.make({ reason: `exactly one of body or article_html is required, and ${hasProse ? "both were supplied" : "neither was supplied"}` }));
+	return Effect.succeed(hasMarkup ? {
+		claim: "",
+		body: [],
+		articleHtml: markup
+	} : {
+		claim: claimFromProse(prose),
+		body: proseTail(prose),
+		articleHtml: void 0
+	});
+};
+/**
+* One op's wire-name-to-operation-name rename, given the article its XOR already resolved to.
+*
+* The same rename `memory_write`'s handler performs, over the same field list. The ops carry a whole
+* `memory_write` payload (D7), so a second spelling of this mapping would be the drift the shared
+* `writeFields` in `tools.ts` exists to make impossible on the schema side.
+*/
+const writeParamsOf = (op, article) => ({
+	title: op.title,
+	claim: article.claim,
+	body: article.body,
+	articleHtml: article.articleHtml,
+	memoryType: op.memory_type,
+	path: opt(op.path),
+	workspace: opt(op.workspace),
+	tags: arr(op.tags),
+	entities: arr(op.entities),
+	importance: opt(op.importance),
+	confidence: opt(op.confidence),
+	sessionId: opt(op.session_id),
+	promptId: opt(op.prompt_id),
+	turnUuid: opt(op.turn_uuid)
+});
+/**
+* An op's XOR refusal as that op's own report, through the SAME `codeFor`/`messageFor` pair
+* `operations.ts`'s `reportFailure` uses.
+*
+* Not a second mapping of the error: a per-op `code` is part of the batch payload's contract, and
+* `memhtml apply` and `memory_write_batch` reporting different codes for one refused op is exactly the
+* drift the shared-use-case rule exists to prevent. The XOR is the one refusal the operations layer
+* cannot produce, being a wire-vocabulary rule about two parameters that layer never sees, since
+* `WriteParams` takes an already-resolved `claim`/`body`/`articleHtml`. So this is the one place
+* a report is built outside `batchWrite`, and it is built with `batchWrite`'s own functions.
+*/
+const xorReport = (index, error) => ({
+	index,
+	ok: false,
+	code: codeFor(error),
+	error: messageFor(error)
+});
+/**
+* The first op that FAILED, as opposed to one that was skipped or deduped.
+*
+* `batchWrite`'s atomic abort reports the offending op with its code and every other op as `skipped`
+* (`operations.ts:545-548` for a decode refusal, `store.ts:693-705` for a render-gate one), so an
+* aborted batch is recognizable by exactly this: one report with `ok: false` and `skipped` unset. A
+* check on `summary.skipped > 0` alone would also match a batch that had nothing to abort.
+*/
+const firstFailure = (reports) => reports.find((report) => !report.ok && report.skipped !== true && report.code !== void 0);
+/** One op's report as the wire shape: every field present, absent ones as `null`. */
+const wireReport = (report) => ({
+	index: report.index,
+	ok: report.ok,
+	path: report.path ?? null,
+	deduped: report.deduped === true,
+	existing_path: report.existingPath ?? null,
+	code: report.code ?? null,
+	error: report.error ?? null,
+	skipped: report.skipped === true,
+	/**
+	* The conflict assist's finding, `batchIndex` renamed to `batch_index`. That rename is the whole of
+	* the handlers' remaining job, applied one level deeper than usual because this is the first nested
+	* struct on the batch's wire shape. `memhtml apply`'s own `opPayload` performs the same rename onto
+	* the same names, so the two doors' payloads stay byte-comparable.
+	*
+	* A conflict says nothing about `ok`, `path`, or `skipped`, and this function is where that is
+	* visible: nothing above changes when the field is populated.
+	*/
+	conflict: report.conflict === void 0 ? null : {
+		path: report.conflict.path,
+		batch_index: report.conflict.batchIndex,
+		claim: report.conflict.claim
+	},
+	consolidated_into: report.consolidatedInto ?? null,
+	superseded_path: report.supersededPath ?? null
+});
+/**
+* The batch's counts, over the merged report array.
+*
+* The same one-pass derivation `operations.ts`'s `summarize` performs, and it has to be re-derived here
+* rather than taken from `batchWrite` for one reason: in continue mode this handler's own XOR refusals
+* are reports `batchWrite` never saw, so its summary describes a SHORTER op list. Taking it would
+* publish `total` less than `results.length`, a summary a client cannot reconcile with the array it
+* came with. On the atomic path there are no such refusals and this returns `batchWrite`'s own numbers.
+*/
+const summarize = (results) => {
+	let written = 0;
+	let deduped = 0;
+	let failed = 0;
+	let skipped = 0;
+	let consolidated = 0;
+	for (const result of results) if (result.consolidatedInto !== void 0) consolidated += 1;
+	else if (result.skipped === true) skipped += 1;
+	else if (!result.ok) failed += 1;
+	else if (result.deduped === true) deduped += 1;
+	else written += 1;
+	return {
+		total: results.length,
+		written,
+		deduped,
+		failed,
+		skipped,
+		consolidated
+	};
+};
+/**
+* The handler layer for the toolkit.
+*
+* `kit.toLayer({ … })` is checked against the toolkit's own parameter and success schemas, so a
+* handler returning the wrong shape is a compile error rather than a decode failure on a live call.
+*/
+const ToolHandlers = MemhtmlToolkit.toLayer({
+	memory_write: (params) => handled(Effect.gen(function* () {
+		const article = yield* authored(params.body, params.article_html);
+		const result = yield* writeMemory({
+			title: params.title,
+			claim: article.claim,
+			body: article.body,
+			articleHtml: article.articleHtml,
+			memoryType: params.memory_type,
+			path: opt(params.path),
+			workspace: opt(params.workspace),
+			tags: arr(params.tags),
+			entities: arr(params.entities),
+			importance: opt(params.importance),
+			confidence: opt(params.confidence),
+			sessionId: opt(params.session_id),
+			promptId: opt(params.prompt_id),
+			turnUuid: opt(params.turn_uuid)
+		});
+		return {
+			path: result.path,
+			created: result.created,
+			deduped: result.deduped,
+			existing_path: result.existingPath ?? null
+		};
+	})),
+	/**
+	* The batch: resolve every op's XOR, call `batchWrite` ONCE, report every op in input order.
+	*
+	* **The XOR runs per op, up front, before `batchWrite` is called at all.** It is the wire boundary's
+	* only rule and it is a rule about two PARAMETERS. `WriteParams` takes an already-resolved
+	* `claim`/`body`/`articleHtml`, so an op that supplied both is a call the operations layer has no way
+	* to recognize. Resolving it here also means the store's phase-1 validation sees only ops that could
+	* possibly be written, which is what keeps "the atomic abort happens before any file exists" true of
+	* the XOR too.
+	*
+	* **Then the modes diverge, and each one matches `batchWrite`'s own semantics for the failure class
+	* it already handles**, a malformed `memory_type`, which is likewise a per-op decode refusal:
+	*
+	* - CONTINUE: each XOR refusal becomes that op's failed report, ONLY the survivors go to
+	*   `batchWrite`, and the survivors' reports are spliced back at their ORIGINAL indices. `originOf`
+	*   is what makes that possible: `batchWrite` indexes results in the array it was handed, so a
+	*   survivor at position 0 of a two-op call may be op 0 or op 1 of a three-op one, and reporting its
+	*   own index would shift every later op by the number of refusals before it. The result is a
+	*   SUCCESS: every op is present in `results`, in input order, which is the contract D3 states and
+	*   the only shape an agent can index by.
+	* - ATOMIC (the default): the first refused op aborts, and the abort reaches the agent through the
+	*   ERROR channel as `batchAbortFailure`. An XOR refusal short-circuits before `batchWrite` is
+	*   called at all, since an atomic batch with a refused op writes nothing by definition and the call
+	*   would be a round trip whose only outcome is the abort. A refusal `batchWrite` itself produced,
+	*   such as a malformed `memory_type` or an op the store's render gate refused, comes back as an
+	*   aborted RESULT, and is converted at the same seam.
+	*
+	* **That conversion is the one non-obvious thing here, and it was a real bug caught by a test.** An
+	* aborted `batchWrite` returns a well-formed result: every op reported, one of them failed, the rest
+	* `skipped`, `commitSha: null`. Returning it verbatim is a SUCCESS response for a call that wrote
+	* nothing, so the XOR path (an error) and the render-gate path (a success) would be two channels for
+	* one outcome, and `BATCH_GUIDANCE`'s promise that "the first refused op aborts the whole call … and
+	* the failure names the offending op" would be false for every refusal the handler did not itself
+	* detect. `firstFailure` finds the offending op in the returned reports and `batchAbortFailure`
+	* composes the one message both paths use.
+	*/
+	memory_write_batch: (params) => handled(Effect.gen(function* () {
+		const continueOnError = params.continue_on_error === true;
+		const reports = params.ops.map(() => void 0);
+		const survivors = [];
+		/** Survivor position in what `batchWrite` was handed → this caller's own op index. */
+		const originOf = [];
+		for (const [index, op] of params.ops.entries()) {
+			const article = yield* Effect.result(authored(op.body, op.article_html));
+			if (article._tag === "Failure") {
+				const report = xorReport(index, article.failure);
+				/**
+				* Composed rather than `Effect.fail(article.failure)`, which would reach the agent as the
+				* singular's own message: it names the rule but not WHICH of twenty ops broke it, and says
+				* nothing about `continue_on_error`.
+				*/
+				if (!continueOnError) return yield* Effect.fail(batchAbortFailure(index, report.code ?? "ERR_INVALID_MEMORY", report.error ?? ""));
+				reports[index] = report;
+				continue;
+			}
+			originOf.push(index);
+			survivors.push(writeParamsOf(op, article.success));
+		}
+		const batch = yield* batchWrite({
+			ops: survivors,
+			continueOnError,
+			/**
+			* The flag reaches `batchWrite` unchanged, which is the only correct place for the assist to
+			* live: `memhtml apply --detect-conflicts` gets the same findings from the same code, so the two
+			* doors cannot disagree about what a conflict is.
+			*
+			* The survivors-only consequence is real and it is right. An op this handler already refused
+			* for the XOR is not in `survivors`, so it gets no conflict report, and it also has no claim
+			* to derive one FROM: on the both-supplied path there is no way to tell which of the two the
+			* caller meant, and on the neither-supplied path there is no claim at all. A finding invented
+			* for such an op would name a slot the caller never asserted.
+			*/
+			detectConflicts: params.detect_conflicts === true,
+			...params.consolidate !== void 0 && params.consolidate !== null ? { consolidate: params.consolidate } : {},
+			sessionId: opt(params.session_id),
+			promptId: opt(params.prompt_id),
+			turnUuid: opt(params.turn_uuid)
+		});
+		if (!continueOnError) {
+			const failed = firstFailure(batch.results);
+			if (failed !== void 0) return yield* Effect.fail(batchAbortFailure(originOf[failed.index] ?? failed.index, failed.code ?? "ERR_INVALID_MEMORY", failed.error ?? ""));
+		}
+		/**
+		* Splice each survivor's report back at its ORIGINAL index, and translate the conflict's
+		* `batchIndex` through the SAME map, which is the non-obvious half.
+		*
+		* `batchWrite` saw only `survivors`, so an intra-batch conflict it found names a position in
+		* THAT array. In continue mode with an XOR-refused op before the conflicting pair, survivor 1
+		* is the caller's op 2, so reporting the raw number would name a different op than the one the
+		* assist actually matched, and it would name it plausibly enough that nobody would notice. The
+		* outer `index` has always needed this translation for exactly the same reason; the conflict is
+		* a second index in the same space and needs it too.
+		*
+		* `originOf[…] ?? conflict.batchIndex` mirrors the fallback three lines above rather than
+		* dropping the conflict: an untranslatable index is impossible here (every survivor has an
+		* origin, by construction of the loop that built both arrays), and if it somehow were not, a
+		* caller is better served by a suspicious number than by a finding silently deleted.
+		*/
+		for (const report of batch.results) {
+			const index = originOf[report.index];
+			if (index === void 0) continue;
+			const conflict = report.conflict;
+			const translated = conflict === void 0 || conflict.batchIndex === null ? {
+				...report,
+				index
+			} : {
+				...report,
+				index,
+				conflict: {
+					...conflict,
+					batchIndex: originOf[conflict.batchIndex] ?? conflict.batchIndex
+				}
+			};
+			reports[index] = translated.consolidatedInto === void 0 ? translated : {
+				...translated,
+				consolidatedInto: originOf[translated.consolidatedInto] ?? translated.consolidatedInto
+			};
+		}
+		/**
+		* An op with no report of its own was never reached. Unreachable on the atomic path, which has
+		* already failed by here, so this is continue mode's own case: `skipped`, the same word
+		* `batchWrite` uses, so the two doors describe one outcome in one vocabulary.
+		*/
+		const results = reports.map((report, index) => report ?? {
+			index,
+			ok: false,
+			skipped: true
+		});
+		return {
+			results: results.map(wireReport),
+			summary: summarize(results),
+			commit_sha: batch.commitSha
+		};
+	})),
+	memory_read: (params) => handled(Effect.gen(function* () {
+		const result = yield* readMemory(params.path, { sessionId: opt(params.session_id) });
+		return {
+			path: result.path,
+			title: result.doc.title,
+			body: result.doc.article.bodyText,
+			gist: result.doc.article.gist,
+			memory_type: result.doc.metas.memoryType,
+			meta: metaRecord(result.doc),
+			links: result.doc.links.map((link) => ({
+				rel: link.rel,
+				href: link.href
+			})),
+			archived: result.doc.metas.status === "archived",
+			warnings: result.doc.warnings
+		};
+	})),
+	memory_search: (params) => handled(Effect.gen(function* () {
+		const result = yield* searchMemories({
+			query: params.query,
+			limit: opt(params.limit),
+			memoryTypes: opt(params.memory_types),
+			workspace: opt(params.workspace),
+			tags: opt(params.tags),
+			entity: opt(params.entity),
+			includeArchived: opt(params.include_archived),
+			asOf: opt(params.as_of)
+		});
+		return {
+			hits: result.hits.map((hit) => ({
+				path: hit.path,
+				title: hit.title,
+				gist: hit.gist,
+				memory_type: hit.memoryType,
+				score: hit.score,
+				confidence: hit.confidence,
+				updated_at: hit.updatedAt,
+				snippet: hit.snippet,
+				entities: hit.entities,
+				superseded_by: hit.supersededBy
+			})),
+			degraded: result.degraded,
+			arms: result.arms,
+			entity_scope: result.entityScope,
+			scope_empty: result.scopeEmpty
+		};
+	})),
+	memory_recall: (params) => handled(Effect.gen(function* () {
+		const pack = yield* recallMemories({
+			query: params.query,
+			budgetChars: opt(params.budget_chars),
+			workspace: opt(params.workspace)
+		});
+		/**
+		* `lateral` is the union of both folds' index lines.
+		*
+		* It holds what did not fit the budget, surfaced with its claim and its path so an agent
+		* can drill down deliberately, and it is not a third retrieval arm. Dropping it would make
+		* a truncated pack indistinguishable from a small corpus.
+		*/
+		return {
+			sections: {
+				arcs: pack.arcs.disclosed.map((entry) => ({
+					path: entry.path,
+					title: entry.title,
+					gist: entry.gist,
+					body: entry.body
+				})),
+				memories: pack.memories.disclosed.map((entry) => ({
+					path: entry.path,
+					title: entry.title,
+					gist: entry.gist,
+					body: entry.body
+				})),
+				lateral: [...pack.arcs.indexLines, ...pack.memories.indexLines].map((line) => ({
+					path: line.path,
+					title: line.title,
+					gist: line.gist
+				}))
+			},
+			spent_chars: pack.spentChars,
+			truncated: pack.truncated,
+			degraded: pack.degraded
+		};
+	})),
+	memory_correct: (params) => handled(Effect.gen(function* () {
+		const article = yield* authored(params.body, params.article_html);
+		const result = yield* correctMemory({
+			targetPath: params.target_path,
+			title: params.title,
+			claim: article.claim,
+			body: article.body,
+			articleHtml: article.articleHtml,
+			reason: params.reason,
+			sessionId: opt(params.session_id)
+		});
+		/**
+		* `superseded` names the target's ARCHIVE path, which is where the file is once the commit
+		* lands, and it is what the new file's `memhtml-supersedes` link points at. Reporting the
+		* pre-archive path would hand back a path with no file behind it.
+		*/
+		return {
+			path: result.path,
+			superseded: [result.archivedPath],
+			archived: [result.archivedPath]
+		};
+	})),
+	memory_link: (params) => handled(Effect.gen(function* () {
+		const result = yield* linkMemories(params.src_path, params.rel, params.dst_path);
+		return {
+			ok: true,
+			rel: result.rel,
+			src_path: result.srcPath,
+			dst_path: result.dstPath
+		};
+	})),
+	memory_neighbors: (params) => handled(Effect.gen(function* () {
+		const result = yield* neighborsOf({
+			path: params.path,
+			depth: opt(params.depth),
+			rels: opt(params.rels)
+		});
+		return {
+			nodes: result.nodes,
+			edges: result.edges
+		};
+	})),
+	memory_archive: (params) => handled(Effect.gen(function* () {
+		const result = yield* archiveMemory(params.path, params.reason);
+		return {
+			path: result.path,
+			archive_path: result.archivePath
+		};
+	})),
+	memory_reinforce: (params) => handled(Effect.gen(function* () {
+		const result = yield* reinforceMemories(params.paths, params.signal);
+		return {
+			bumped: result.bumped,
+			cooled_down: result.cooledDown
+		};
+	})),
+	memory_list: (params) => handled(Effect.gen(function* () {
+		const result = yield* listMemories({
+			memoryType: opt(params.memory_type),
+			workspace: opt(params.workspace),
+			tag: opt(params.tag),
+			entity: opt(params.entity),
+			para: opt(params.para),
+			limit: opt(params.limit),
+			cursor: opt(params.cursor)
+		});
+		return {
+			files: result.files.map((file) => ({
+				path: file.path,
+				title: file.title,
+				memory_type: file.memoryType,
+				gist: file.gist,
+				workspace: file.workspace,
+				para: file.para,
+				confidence: file.confidence,
+				importance: file.importance,
+				archived: file.archived,
+				updated_at: file.updatedAt
+			})),
+			next_cursor: result.nextCursor
+		};
+	})),
+	trace_search: (params) => handled(Effect.gen(function* () {
+		return { sessions: (yield* searchTraces({
+			query: params.query,
+			cwd: opt(params.cwd),
+			since: opt(params.since),
+			limit: opt(params.limit)
+		})).sessions.map((session) => ({
+			session_id: session.sessionId,
+			slug: session.slug,
+			cwd: session.cwd,
+			started_at: session.startedAt,
+			prompt_count: session.promptCount,
+			first_prompt: session.firstPrompt,
+			ai_title: session.aiTitle
+		})) };
+	})),
+	trace_links: (params) => handled(Effect.gen(function* () {
+		return { links: (yield* traceLinks({
+			sessionId: opt(params.session_id),
+			path: opt(params.path)
+		})).links.map((link) => ({
+			path: link.path,
+			session_id: link.sessionId,
+			prompt_id: link.promptId,
+			turn_uuid: link.turnUuid,
+			link_kind: link.linkKind,
+			at: link.at
+		})) };
+	})),
+	memory_status: () => handled(Effect.gen(function* () {
+		const report = yield* statusReport();
+		return {
+			head_sha: report.headSha,
+			dirty: report.dirty,
+			counts_by_type: report.countsByType,
+			archived_count: report.archivedCount,
+			edges: report.edges,
+			index_fresh: report.indexFresh,
+			embedder_up: report.embedderUp,
+			last_sleep: report.lastSleep === null ? null : {
+				run_id: report.lastSleep.runId,
+				status: report.lastSleep.status,
+				started_at: report.lastSleep.startedAt
+			}
+		};
+	}))
+});
+
+//#endregion
+//#region apps/mcp/src/resources.ts
+/**
+* The two resources, design.md §8.
+*
+* A resource is for CITATION-grade drill-down: a client that got a path from `memory_search` can
+* fetch `memhtml://file/<path>` and show a human the file behind an answer, without spending a tool call
+* and without the tool response having had to carry the whole body.
+*
+* `McpSchema.param` names each template parameter, so `tools/list`'s sibling `resources/templates`
+* publishes `{path}` and `{run-id}` as named rather than positional holes.
+*/
+/** `memhtml://file/{path}`: one memory's rendered content. */
+const pathParam = McpSchema.param("path", Schema.String);
+/** `memhtml://sleep/{run-id}`: one sleep run's committed HTML report. */
+const runIdParam = McpSchema.param("run-id", Schema.String);
+/**
+* A memory file, by path.
+*
+* The BODY is returned, not the raw HTML file. A client asking a resource for a citation wants the
+* text a human reads; the markup is the storage format, and handing back a full document with a head
+* full of `memhtml-*` metas would spend a client's rendering budget on bookkeeping. The metadata is
+* available through `memory_read`, which is the tool for exactly that.
+*
+* A missing path fails the read rather than answering with an empty resource: a citation that
+* silently resolves to nothing is worse than one that says the file is gone.
+*
+* This read BUMPS salience, through the same `readMemory` the `memory_read` tool calls. The bump is
+* deliberate: the caller named one specific path, which is a chosen open. A client
+* fetching the file behind an answer is making the same statement an agent makes with `memory_read`,
+* and the plane should not be able to tell them apart.
+*/
+const FileResource = McpServer.resource`memhtml://file/${pathParam}`({
+	name: "Memory file",
+	description: "One memory's title, claim, and body text, by repo-root-relative path. For showing a human the file behind an answer.",
+	mimeType: "text/plain",
+	content: (_uri, path) => Effect.gen(function* () {
+		const result = yield* readMemory(path);
+		return [
+			`# ${result.doc.title}`,
+			"",
+			result.doc.article.gist,
+			"",
+			result.doc.article.bodyText
+		].join("\n");
+	}).pipe(Effect.orDie)
+});
+/**
+* A sleep run's report, by run id.
+*
+* The report is a COMMITTED file under `.memhtml/sleep/`, so this resource reads the tree rather than the
+* database: the report is the durable artifact of a run and the `sleep_runs` row is reporting
+* convenience. A run id arrives as `sleep/2026-08-02`, and the file is named for its last segment.
+*/
+const SleepResource = McpServer.resource`memhtml://sleep/${runIdParam}`({
+	name: "Sleep run report",
+	description: "One sleep run's committed HTML report: per-phase counts, commits, and what the run changed.",
+	mimeType: "text/html",
+	content: (_uri, runId) => Effect.gen(function* () {
+		const roots = yield* Roots;
+		const name = runId.split("/").at(-1) ?? runId;
+		const path = join(roots.memhtmlRoot, SLEEP_REPORTS_DIR, `${name}.html`);
+		return yield* Effect.tryPromise({
+			try: () => readFile(path, "utf8"),
+			catch: (cause) => cause
+		});
+	}).pipe(Effect.orDie)
+});
+/** Both resources as one layer, for the server to provide. */
+const Resources = Layer.mergeAll(FileResource, SleepResource);
+
+//#endregion
+//#region apps/mcp/src/server.ts
+const SERVER_NAME = "memhtml";
+const SERVER_VERSION = "0.1.0";
+/**
+* The server as one layer: fourteen tools, two resources, over the CLI's own `AppLive`.
+*
+* The same composition the CLI builds, deliberately. An MCP server with its own layer graph would be
+* a second set of answers to which database file, which git root, and which vector space. An agent
+* whose `memory_write` landed in one repo while its operator's `memhtml search` read another would
+* be very hard to diagnose from either side.
+*
+* **`Logger.LogToStderr` is required here.** Effect's default logger writes to stdout, and stdout
+* on this transport is the NDJSON-RPC stream, so one log line would corrupt the frame a client is
+* mid-parse on. The CLI sets the same reference for the same reason, one fd over.
+*
+* **There is no server-level `instructions` here, because effect provides no way to set one.** MCP
+* defines an `instructions` field on the initialize response for exactly the cross-tool guidance
+* this server wants to give (when to batch, the three doors, the commit duty), and effect does not
+* emit it. Verified against 4.0.0-beta.107 in the dependency's own declarations: `McpSchema`
+* DECLARES `instructions: optional(Schema.String)` on the initialize result, while `layerStdio`'s
+* options are `{name, version, protocols, extensions}`, so there is not even an argument to pass,
+* and the handler that builds the result supplies none.
+*
+* **TOOL DESCRIPTIONS are this server's only guidance channel.** That consequence is recorded here,
+* beside the field a maintainer would come looking for, rather than in a doc. It is why
+* `BATCH_GUIDANCE` and `ARTICLE_HTML_CONTRACT` in `tools.ts` are shared constants appended to every
+* description they apply to, and why they read as prose to an agent rather than as reference notes to a
+* maintainer. Do not patch the dependency; revisit this when effect wires the field, at which point the
+* duplicated prose can move up here.
+*/
+const layerServer = (repoOverride) => Layer.mergeAll(McpServer.toolkit(MemhtmlToolkit), Resources).pipe(Layer.provide(ToolHandlers), Layer.provide(McpServer.layerStdio({
+	name: SERVER_NAME,
+	version: SERVER_VERSION,
+	protocols: [McpProtocol.v2025_06_18]
+})), Layer.provide(layerApp(repoOverride)), Layer.provide(Layer.succeed(Logger.LogToStderr)(true)));
+
+//#endregion
+//#region apps/mcp/src/bin.ts
+/**
+* The stdio entry point. stdout belongs to the MCP framing from here on: every log in the graph is
+* already routed to stderr by `layerServer`, and nothing in this file writes.
+*
+* `Layer.launch` runs the server for the process's lifetime rather than building the layer and
+* returning. The transport IS the program, and a built-then-released layer would close stdin out
+* from under the client mid-session.
+*/
+Layer.launch(layerServer().pipe(Layer.provide(NodeStdio.layer))).pipe(NodeRuntime.runMain);
+
+//#endregion
+export {  };
+//# sourceMappingURL=memhtml-mcp.mjs.map