memhtml 0.6.0 → 0.7.0

package/dist/memhtml-mcp.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { $ as STATE_DB_PATH, A as IndexRecorder, B as IndexGit, C as ModelClient, D as EmbeddingsLive, E as Embeddings, F as makeRetrieval, G as MIGRATIONS_DIR, H as sanitizeFtsQuery, I as reinforce, J as Store, K as STATE_MIGRATIONS_DIR, L as Indexer, O as EMBED_DIM, P as Retrieval, Q as SLEEP_REPORTS_DIR, R as makeIndexer, T as wrapAsData, U as DatabaseService, V as makeGitPort, W as makeDatabase, X as makeStore, Y as expandRoot, Z as INDEX_DB_PATH, at as makeGit, dt as fenceOpeningOf, ft as REINFORCE_SIGNALS, i as makeSleep, it as Git, j as makeIndexRecorder, k as EMBED_WATERMARK, l as DETECTION_PREFIX, lt as isValidDatetime, pt as frameKeyOf, r as Sleep, ut as closesFence, w as ModelClientLive, y as SLEEP_PHASES, z as readIndexState } from "./dist-CHoz5uHd.mjs";
-import { $ as TASK_RELS, Dt as isTaskStatus, Et as WRITABLE_MEMORY_TYPES, G as InvalidMemory, Q as MEMORY_RELS, R as hasConsolidatorCredentials, St as PARA_BUCKETS, Y as StorageFailure, a as makeConsolidator, et as isEdgeRel, mt as normalizePath, q as ModelUnavailable, tt as relClassFor, wt as TASK_STATUSES } from "./dist-BCsav-EP.mjs";
+import { $ as expandRoot, A as EMBED_DIM, B as reinforce, D as wrapAsData, E as ModelClientLive, G as makeGitPort, H as makeIndexer, I as Retrieval, J as makeDatabase, K as sanitizeFtsQuery, L as makeRetrieval, M as IndexRecorder, N as makeIndexRecorder, O as Embeddings, Q as Store, R as facetConditions, T as ModelClient, U as readIndexState, V as Indexer, W as IndexGit, X as STATE_MIGRATIONS_DIR, Y as MIGRATIONS_DIR, _t as REINFORCE_SIGNALS, b as SLEEP_PHASES, ct as Git, et as makeStore, ft as parseMemory, gt as fenceOpeningOf, ht as closesFence, i as makeSleep, j as EMBED_WATERMARK, k as EmbeddingsLive, lt as makeGit, mt as isValidDatetime, nt as SLEEP_REPORTS_DIR, q as DatabaseService, r as Sleep, rt as STATE_DB_PATH, s as reportFilename, st as readFileOrNull, tt as INDEX_DB_PATH, u as DETECTION_PREFIX, vt as frameKeyOf, z as parseFacetFilters } from "./dist-D1wH0oJ0.mjs";
+import { It as WRITABLE_MEMORY_TYPES, Lt as isTaskStatus, Mt as PARA_BUCKETS, Pt as TASK_STATUSES, W as hasConsolidatorCredentials, ct as TASK_RELS, et as InvalidMemory, i as makeConsolidator, it as StorageFailure, lt as isEdgeRel, nt as ModelUnavailable, st as MEMORY_RELS, ut as relClassFor, wt as normalizePath, xt as isValidMemoryPath } from "./dist-DHFdTnlp.mjs";
 import { createRequire } from "node:module";
 import { Config, Context, Effect, Layer, Logger, Schema } from "effect";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
@@ -11,74 +11,6 @@ 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 model-calling 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 every model-calling sleep phase report `no model bound` and stay `ok`, so a credential-free run is honest rather than red. `entity-resolution` still runs its deterministic normalization and character-overlap passes; the others do nothing.",
-		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 behavior.",
-		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
@@ -242,6 +174,81 @@ const fetchMantleTransport = (region, token) => ({ post: async (body, signal) =>
 	return JSON.parse(text);
 } });
 
+//#endregion
+//#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 model-calling 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 every model-calling sleep phase report `no model bound` and stay `ok`, so a credential-free run is honest rather than red. `entity-resolution` still runs its deterministic normalization and character-overlap passes; the others do nothing.",
+		fallback: "on"
+	},
+	{
+		name: "MEMHTML_EXTRACT_ENTITIES",
+		/**
+		* The model id is interpolated from `extraction.ts`, never spelled here. That constant is the
+		* one the transport calls and the one the strict output schema beside it is tested against, so a
+		* second spelling in this row is a manifest that can name a model the code does not call. The
+		* lane is also not `@memhtml/llm`'s: the extractor speaks the Bedrock mantle Responses API, which
+		* is why this id is absent from `ModelKey`.
+		*/
+		description: `\`on\` adds one \`${EXTRACTION_MODEL_ID}\` 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 behavior.",
+		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/api-layer.js
 const Roots = Context.Service("memhtml/Roots");
@@ -393,22 +400,21 @@ const ConsolidatorPortService = Context.Service("memhtml/ConsolidatorPort");
 *
 * The check cannot be skipped in favor 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`).
+* until the first request (the contract suite in `apps/consolidator/src/contract.ts` pins this).
 *
 * **`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
+* effect's default provider snapshots `process.env` at module load, so 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
+* **It 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).
+* (`apps/consolidator/src/client.ts`, `manifestFor`).
 * 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
@@ -516,6 +522,7 @@ const codeFor = (error) => {
 		case "DuplicateContent": return "ERR_DUPLICATE_CONTENT";
 		case "ModelUnavailable": return "ERR_MODEL_UNAVAILABLE";
 		case "EmbedModelMismatch": return "ERR_EMBED_MODEL_MISMATCH";
+		case "IndexStale": return "ERR_INDEX_STALE";
 		case "DiscriminationFailed": return "ERR_DISCRIMINATION_FAILED";
 		default: return "ERR_UNKNOWN";
 	}
@@ -541,6 +548,7 @@ const messageFor = (error) => {
 		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 "IndexStale": return `the index is stale: ${text$1(error.reason) ?? "it does not describe the current commit"}`;
 		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}`;
@@ -633,20 +641,20 @@ const recordLink = (path, linkKind, provenance, at) => Effect.gen(function* () {
 /**
 * Bring the index up to the commit a write just made.
 *
-* `indexer.update()` rather than `indexPaths([…])`, and the difference changes behavior twice:
+* The whole COMMIT, never a list of paths the caller happens to know about, and two properties of the
+* index rest on that:
 *
-* 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.
+* 1. **A rename is only expressible as a diff.** Every correction and every archive is a `git mv`.
+*    `update()` reads `diff --name-status -M`, sees the `R`, and re-points the row, which keeps the
+*    embedding. Indexing the destination alone leaves the source row live: the archived memory stays
+*    in `memhtml list`, `files` carries a row the tree does not have, and the chunk rows the move
+*    exists to preserve end up duplicated under two paths.
+* 2. **The watermark is what makes freshness answerable.** `update()` records
+*    `index_state.head_sha`, and without it `memhtml status` reports `index_fresh: false` forever
+*    while `index update` re-derives 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
+* very first write there is no watermark row 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* () {
@@ -657,8 +665,8 @@ const reindex = () => Effect.gen(function* () {
 *
 * 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.
+* and drift the first time a field is added. 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
@@ -679,6 +687,7 @@ const toWriteInput = (params, at) => Effect.gen(function* () {
 			body: params.body,
 			articleHtml: params.articleHtml,
 			path: params.path,
+			strictPath: params.strictPath,
 			workspace: params.workspace,
 			tags: params.tags,
 			entities: params.entities,
@@ -1268,13 +1277,116 @@ const reinforceMemories = (paths, signal) => Effect.gen(function* () {
 	};
 });
 /**
+* The ceiling on nodes per neighborhood, and the default when a caller names none.
+*
+* A caller-supplied `limit` is clamped into `1..NEIGHBORS_LIMIT`, which is the shape both sibling
+* reads have (`memory_list` `Math.min(500, …)`, `trace_search` `Math.min(200, …)`). A clamp with no
+* flag behind it is a ceiling a caller can neither ask for nor lower.
+*/
+const NEIGHBORS_LIMIT = 200;
+/**
+* Edge rows the statement may RETURN before it stops.
+*
+* **This bounds the answer, not the join.** Measured 2026-08-25 on node 24.19.0 against the shipped
+* schema: `EXPLAIN QUERY PLAN` on {@link neighborsQuery}'s depth-2 statement yields `MERGE
+* (UNION ALL)` with `USE TEMP B-TREE FOR ORDER BY` on every arm, so SQLite enumerates the union and
+* sorts the whole row set in a temp b-tree BEFORE the `LIMIT` takes its prefix. A hub of degree
+* 150/300/450 generates 22.5k/90k/202k rows either way, and the limited statement runs in
+* 47/92/155 ms against 66/253/591 ms unlimited — so the cap buys real time and memory downstream of
+* the sort while the join's work and the temp b-tree still grow with the center's degree squared.
+*
+* What the cap does bound: the rows that cross into JS, the fold below, and the size of one answer.
+* A neighborhood that reaches it is truncated rather than exhaustive, and `scanSaturated` says so
+* instead of leaving the caller to infer it — raising a caller's `limit` cannot recover an edge the
+* walk never returned.
+*
+* Bounding each arm before the union WOULD bound the join, and is not done: an arm-level `LIMIT`
+* takes an arbitrary prefix of one direction's edges, so the hop-1 nodes that survive decide which
+* hop-2 nodes exist at all, and the answer would change with the planner's row order rather than
+* only shrink.
+*/
+const NEIGHBORS_SCAN_LIMIT = 1e4;
+/**
+* The neighborhood walk as one statement plus its bind list.
+*
+* Exported so a cost assertion can `EXPLAIN QUERY PLAN` the string this function actually issues.
+* A plan asserted against a copy pasted into a test explains the copy, and the two drift the first
+* time an arm moves.
+*
+* Hop 1 is the center's own edges, either direction. Hop 2 walks one further from each hop-1 node and
+* excludes the center, so a two-cycle does not report the center as its own neighbor at distance 2.
+* Each arm carries the edge's own endpoints (`a`, `b`) so an edge can be counted as an edge, not
+* inferred from a node count.
+*
+* The join onto `files` is an inner join, so an edge pointing at a path the tree does not hold
+* contributes nothing. A dangling href is `memhtml doctor`'s finding rather than a titleless node.
+*
+* The rel list binds once per occurrence of the filter, in textual order: hop 1 uses it twice, hop 2
+* uses it four more times. Getting this count wrong is a bind mismatch rather than a wrong answer, so
+* it fails loudly.
+*/
+const neighborsQuery = (input) => {
+	const { center, depth, rels } = input;
+	const relFilter = rels.length > 0 ? ` AND e.rel IN (${rels.map(() => "?").join(", ")})` : "";
+	const relFilter2 = rels.length > 0 ? ` AND e2.rel IN (${rels.map(() => "?").join(", ")})` : "";
+	const hopOne = `
+      SELECT e.dst_path AS path, e.rel AS rel, e.derived AS derived, 1 AS hop,
+             e.src_path AS a, e.dst_path AS b
+      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,
+             e.src_path AS a, e.dst_path AS b
+      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,
+             e2.src_path AS a, e2.dst_path AS b
+      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,
+             e2.src_path AS a, e2.dst_path AS b
+      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}`;
+	return {
+		sql: `SELECT w.path AS path, f.title AS title, w.rel AS rel, w.derived AS derived,
+              w.hop AS hop, w.a AS a, w.b AS b
+       FROM (${depth === 1 ? hopOne : `${hopOne}\n      UNION ALL${hopTwo}`}) w
+       JOIN files f ON f.path = w.path
+       ORDER BY w.hop ASC, w.path ASC
+       LIMIT ${NEIGHBORS_SCAN_LIMIT}`,
+		params: [center, ...depth === 1 ? [...rels, ...rels] : [
+			...rels,
+			...rels,
+			...rels,
+			...rels,
+			...rels,
+			...rels
+		]]
+	};
+};
+/**
 * 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.
+* mined by the sleep cycle and can be dense.
+*
+* **Every arm is index-probed, in both directions, through `edges_src` and `edges_dst`.** Measured
+* 2026-08-26 on node 24.19.0 with no `ANALYZE`, and locked by the plan assertion in
+* `apps/cli/tests/e2e.test.ts`: each arm is a `SEARCH` binding two columns,
+* `(src_path=? AND edge_class=?)` or `(dst_path=? AND edge_class=?)`. Neither index carries a
+* predicate (`0011_edge_indexes.sql`), which is what makes them reachable from here at all — this walk
+* selects `e.derived` and filters only on `edge_class`, so a `WHERE derived = 0` index could not be a
+* candidate, and the reverse arms would fall back to a full scan of `edges` per arm. The row set is
+* still degree², which is what `NEIGHBORS_SCAN_LIMIT` bounds; what the indexes bound is the work spent
+* finding it.
 *
 * **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
@@ -1291,58 +1403,257 @@ const neighborsOf = (params) => Effect.gen(function* () {
 	const db = yield* DatabaseService;
 	const center = normalizePath(params.path);
 	const depth = Math.min(2, Math.max(1, Math.trunc(params.depth ?? 1)));
+	const limit = Math.min(200, Math.max(1, Math.trunc(params.limit ?? 200)));
 	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 center's own edges, either direction. Hop 2 walks one further from each hop-1
-	* node and excludes the center, so a two-cycle does not report the center as its own neighbor
-	* at distance 2.
+	* Edge rows, hop-1 first, folded per path below rather than `GROUP BY` in SQL. A `GROUP BY`
+	* with `min(hop)` and `min(rel)` aggregates the two columns independently, so a node reachable
+	* as `supersedes` at hop 1 and `contradicts` at hop 2 would report `(hop 1, contradicts)`, a
+	* pairing no edge holds. The fold keeps the rel of an edge AT the minimal hop.
 	*/
-	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`, [center, ...depth === 1 ? [...rels, ...rels] : [
-		...rels,
-		...rels,
-		...rels,
-		...rels,
-		...rels,
-		...rels
-	]])).map((row) => ({
-		path: row.path,
-		title: row.title,
-		hop: row.hop,
-		rel: row.rel
-	}));
+	const statement = neighborsQuery({
+		center,
+		depth,
+		rels
+	});
+	const rows = yield* db.all(statement.sql, statement.params);
+	/**
+	* One node per path at its minimal hop: a node reachable both directly and via a detour is a
+	* 1-hop neighbor, and reporting it twice would let one memory occupy two slots in a bounded
+	* answer. The rows arrive hop-first, so a path's first row IS an edge at its minimal hop and
+	* its rel is kept verbatim. `derived` is the max over every edge reaching the node, so one
+	* sleep-mined route marks the node as carrying a mined suspicion even when an authored edge
+	* also reaches it. `edges` counts distinct edges the walk enumerated, which is what the MCP
+	* schema's `edges` field claims to be.
+	*
+	* A path the clamp turns away is still counted, in `nodesDropped`, and its edges still count
+	* toward `edges`: the two numbers live in different coordinate spaces on purpose, and an `edges`
+	* total that quietly excluded a dropped path's edges would agree with `nodes` while describing
+	* a walk that never happened.
+	*/
+	const byPath = /* @__PURE__ */ new Map();
+	const edgeKeys = /* @__PURE__ */ new Set();
+	const dropped = /* @__PURE__ */ new Set();
+	for (const row of rows) {
+		edgeKeys.add(JSON.stringify([
+			row.a,
+			row.rel,
+			row.b
+		]));
+		const existing = byPath.get(row.path);
+		if (existing === void 0) {
+			if (byPath.size < limit) byPath.set(row.path, {
+				title: row.title,
+				hop: row.hop,
+				rel: row.rel,
+				derived: row.derived === 1
+			});
+			else dropped.add(row.path);
+		} else if (row.derived === 1) byPath.set(row.path, {
+			...existing,
+			derived: true
+		});
+	}
 	return {
 		center,
 		depth,
-		nodes,
-		edges: nodes.length
+		/** The node ceiling this answer was built under, after clamping the caller's ask. */
+		limit,
+		nodes: [...byPath.entries()].map(([path, node]) => ({
+			path,
+			title: node.title,
+			hop: node.hop,
+			rel: node.rel,
+			derived: node.derived
+		})),
+		edges: edgeKeys.size,
+		/**
+		* Distinct paths the walk reached and `limit` turned away. `0` means `nodes` holds every path
+		* the walk found, so a caller can tell a saturated neighborhood from a complete one. Raising
+		* `limit` toward {@link NEIGHBORS_LIMIT} returns them.
+		*/
+		nodesDropped: dropped.size,
+		/**
+		* True when the walk returned {@link NEIGHBORS_SCAN_LIMIT} rows, so edges past the cap were
+		* never enumerated and no `limit` recovers them. Distinct from `nodesDropped`, which a bigger
+		* `limit` fixes.
+		*/
+		scanSaturated: rows.length >= NEIGHBORS_SCAN_LIMIT
+	};
+});
+/**
+* Steps the forward walk takes before it stops and says which bound stopped it.
+*
+* A chain this long is a corpus that has corrected one fact sixteen times, which the walk answers
+* with `hop_limit` rather than by paying an unbounded number of statements for a read a caller
+* expects to be cheap. It is not the cycle guard: {@link resolveMemory} carries a visited set, so a
+* loop is reported as a loop at the hop that closes it, however short.
+*/
+const RESOLVE_MAX_HOPS = 16;
+/**
+* Why the forward walk stopped, and therefore what `path` is.
+*
+* A closed vocabulary, and the reason it is five values rather than a boolean: only the first means
+* "cite this". Collapsing the other four into "not found" would make an evicted memory, an
+* unindexed path, and a corpus defect one answer, and a caller acting on any of them needs a
+* different next move.
+*
+* - `live` — nothing supersedes `path` and it is active. The resolution a citation wants.
+* - `archived` — `path` is in the archive and nothing supersedes it, so the memory was EVICTED
+*   rather than corrected. `git log --follow` on `path` reads through its whole life.
+* - `unindexed` — the index holds no such path and no archive mapping onto it. Either the path was
+*   never a memory here, or the index does not yet describe the commit that holds it; `indexedCommit`
+*   is which commit it does describe.
+* - `cycle` — the walk returned to a path it had already visited. `steps` shows the loop closing, and
+*   `path` is a member of it rather than a resolution. Two memories each claiming to supersede the
+*   other is an authoring defect, not a state this walk can resolve.
+* - `hop_limit` — the chain is longer than {@link RESOLVE_MAX_HOPS}, so `path` is where the walk
+*   stopped and NOT the end of the chain. Resolving `path` again continues from there.
+*
+* An array rather than a bare union, so `memory_resolve` publishes the five values as a JSON Schema
+* enum from this one declaration and a client can branch exhaustively.
+*/
+const RESOLVE_STOP_REASONS = [
+	"live",
+	"archived",
+	"unindexed",
+	"cycle",
+	"hop_limit"
+];
+/**
+* The two mechanisms that move a memory, as a closed vocabulary.
+*
+* There is no third: a memory's path changes because a correction superseded it or because a `git mv`
+* archived it, and nothing else in the system renames a file.
+*/
+const RESOLVE_STEP_VIA = ["supersedes", "archive_move"];
+/**
+* The three statements the walk issues, as literals a plan assertion can EXPLAIN.
+*
+* Exported for {@link neighborsQuery}'s reason: a cost contract can only be asserted at the planner,
+* and a test that EXPLAINed a pasted copy would explain the copy. Each one binds exactly one
+* parameter, so a test can run them as written.
+*
+* `successor` names `edge_class` even though `rel = 'supersedes'` implies it under `edges`' CHECK
+* constraints. That is a planner constraint, not a filter: measured 2026-08-26 on node 24's
+* `node:sqlite` with no `ANALYZE`, `dst_path = ? AND rel = ? AND derived = 0` alone plans as `SEARCH
+* edges USING INDEX edges_derived (derived=? AND rel=?)` — every authored correction in the corpus,
+* per hop — while naming the class binds two columns of `edges_dst` and the same statement probes.
+* The rel and `derived = 0` are still the CORRECTNESS half: `derived = 0` is the same authored-only
+* rule `SearchHit.supersededBy` reads, so `search` and this walk cannot disagree about who superseded
+* what, and a sleep-mined suspicion can never redirect a citation.
+*
+* `archived` is the archive mapping read backwards, served by `files_origin`
+* (`0012_origin_path.sql`). `ORDER BY archived_at DESC` decides the case a UNIQUE index would have
+* had to refuse: one path evicted, rewritten, and evicted again carries two archive rows, and the
+* NEWEST is the occupant a citation of that path most recently named. A row with no `memhtml-archived`
+* stamp sorts last, since SQLite puts NULLs last under DESC.
+*/
+const resolveQueries = {
+	successor: `SELECT e.src_path AS path FROM edges e
+     WHERE e.dst_path = ? AND e.edge_class = 'memory' AND e.rel = 'supersedes' AND e.derived = 0
+     ORDER BY e.created_at DESC, e.src_path ASC LIMIT 1`,
+	archived: `SELECT f.path AS path FROM files f
+     WHERE f.origin_path = ? ORDER BY f.archived_at DESC, f.path DESC LIMIT 1`,
+	file: "SELECT f.archived AS archived, f.title AS title FROM files f WHERE f.path = ?"
+};
+/**
+* The live path a possibly-moved path names now, by walking `supersedes` forward.
+*
+* **A path IS the id of a memory** (`packages/contracts/src/types.ts`, `MemoryPath`), and it is
+* derived from the title through `slugify`, so a re-consolidation that rewords a title lands the
+* corrected fact at a DIFFERENT path while `correctMemory` `git mv`s the original into
+* `archive/<YYYY>/`. An external receipt holding the old path therefore dead-ends at a path the tree
+* no longer holds — through no fault of the receipt. This read is how such a receipt is repaired
+* without a second identifier: the corpus already records both mechanisms that move a memory, and
+* nothing here is minted.
+*
+* **Two mechanisms, and a path absent from `files` is looked up by the archive mapping ALONE.** A
+* correction stamps its `supersedes` link toward the target's ARCHIVE path
+* (`packages/store/src/store.ts`, `correctMemory`), so the pre-archive path has no inbound edge at
+* all and only `origin_path` knows where its bytes went. An inbound `supersedes` edge over a path the
+* tree does not hold is a DANGLING edge — `memhtml doctor`'s finding — and following one would
+* resolve a citation through an assertion about a file nothing can read. Conversely a path that IS in
+* `files` is never redirected by the archive mapping, even when an older eviction of the same path
+* left a row behind: the live file at that path is the answer, and the redirect would replace it with
+* a historical one.
+*
+* **Every node in the chain is named by the path that holds it NOW.** A `supersedes` link is an
+* element inside a file, so archiving that file carries the link with it: after a second correction the
+* edge points from the archived middle memory, not from the path the middle was live at. A three-step
+* chain over two corrections therefore reads `cited → archive(cited) → archive(middle) → live`, and the
+* middle's own live-at-the-time path appears nowhere in it. The tree is the system of record, and this
+* walk reports where each memory is rather than where it was.
+*
+* **`hops: 0` with `stopReason: "live"` does not mean the bytes are unchanged.** A correction whose
+* title is unchanged lands at the SAME path, so the path is live and its content is a different fact.
+* That grain is what the pinned citation URI is for; this read answers where to look, not what was
+* there.
+*
+* Statement count is `1..2` per hop and the walk is bounded twice — by a visited set and by
+* {@link RESOLVE_MAX_HOPS} — so a corpus defect costs a bounded read and is reported rather than
+* hung. A recursive CTE would do it in one statement and could not report WHICH mechanism took each
+* hop, which is the half a receipt is audited on.
+*/
+const resolveMemory = (path) => Effect.gen(function* () {
+	const db = yield* DatabaseService;
+	const requested = normalizePath(path);
+	const state = yield* readIndexState(db);
+	const steps = [];
+	const visited = /* @__PURE__ */ new Set([requested]);
+	/** Titles of every indexed path the walk touched, so the answer carries one without a re-read. */
+	const titles = /* @__PURE__ */ new Map();
+	let at = requested;
+	let stopReason = "unindexed";
+	for (;;) {
+		const row = yield* db.get(resolveQueries.file, [at]);
+		if (row !== void 0) titles.set(at, row.title);
+		const hop = row === void 0 ? {
+			found: yield* db.get(resolveQueries.archived, [at]),
+			via: "archive_move"
+		} : {
+			found: yield* db.get(resolveQueries.successor, [at]),
+			via: "supersedes"
+		};
+		if (hop.found === void 0) {
+			if (row === void 0) stopReason = "unindexed";
+			else stopReason = row.archived === 1 ? "archived" : "live";
+			break;
+		}
+		/**
+		* The bound is checked BEFORE the step is taken, so `steps.length` is exactly
+		* {@link RESOLVE_MAX_HOPS} when it fires and `path` is a real path the walk stood on. Taking the
+		* step first would report a hop past a bound the answer claims to respect.
+		*/
+		if (steps.length >= 16) {
+			stopReason = "hop_limit";
+			break;
+		}
+		steps.push({
+			from: at,
+			to: hop.found.path,
+			via: hop.via
+		});
+		at = hop.found.path;
+		/**
+		* The repeat IS recorded as a step before the walk stops, so `steps` shows the loop closing and
+		* a reader can name both ends of it. A cycle detected and then hidden would leave the caller
+		* with a `path` it cannot account for.
+		*/
+		if (visited.has(at)) {
+			stopReason = "cycle";
+			break;
+		}
+		visited.add(at);
+	}
+	return {
+		requested,
+		path: at,
+		hops: steps.length,
+		steps,
+		stopReason,
+		title: titles.get(at) ?? null,
+		indexedCommit: state?.head_sha ?? null
 	};
 });
 /**
@@ -1376,9 +1687,20 @@ const listMemories = (params) => Effect.gen(function* () {
 		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);
+		conditions.push("EXISTS (SELECT 1 FROM file_entities e WHERE e.path = f.path AND lower(e.entity_type || ':' || e.entity_name) = lower(?))");
+		values.push(params.entity.trim());
 	}
+	/**
+	* The facet axis, from `@memhtml/index`'s builder rather than a second copy of the grouping.
+	*
+	* The listing binds anonymous `?` in textual order, so the placeholder callback pushes onto
+	* `values` and returns the marker. That is the same contract the numbered form has: whatever the
+	* builder emits, the values it pushed are in the order the statement reads them.
+	*/
+	for (const condition of facetConditions(params.facets ?? [], "f", (value) => {
+		values.push(value);
+		return "?";
+	})) conditions.push(condition);
 	if (params.cursor !== void 0 && params.cursor !== "") {
 		conditions.push("f.path > ?");
 		values.push(normalizePath(params.cursor));
@@ -1484,6 +1806,12 @@ const searchTraces = (params) => Effect.gen(function* () {
 	};
 });
 /**
+* Rows one `trace links` answer may carry. Every sibling read clamps (`memory_list` 500,
+* `trace_search` 200), and a long-lived session accretes links without bound, so an unclamped
+* answer grows forever. Newest first, so the truncation costs the oldest links.
+*/
+const TRACE_LINKS_LIMIT = 500;
+/**
 * The memory-session links, from either side.
 *
 * Both parameters absent is a refusal rather than an unbounded scan of every link ever recorded. A
@@ -1507,7 +1835,8 @@ const traceLinks = (params) => Effect.gen(function* () {
 	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) => ({
+       ORDER BY l.at DESC, l.path ASC
+       LIMIT ${TRACE_LINKS_LIMIT}`, values)).map((row) => ({
 		path: row.path,
 		sessionId: row.session_id,
 		promptId: row.prompt_id,
@@ -1572,27 +1901,46 @@ const countRows = (db, sql) => db.all(sql).pipe(Effect.map((rows) => Object.from
 
 //#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 command accepts. Listed once so the manifest cannot drift from behavior.
+*
+* There is no `--json` flag: the typed JSON envelope is the only output the binary has, on every
+* command, so a flag for it would be parsed, advertised, and read by nothing. Logs go to stderr.
+*/
+const GLOBAL_FLAGS = [{
+	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: ""
+}];
+/**
+* The `--strict-path` help.
+*
+* It states the DEFAULT as well as the opt-in, because the default is the surprising half: a caller
+* reaching for this flag is a caller who just discovered that a malformed `--path` was re-derived, and
+* the help has to confirm that reading rather than leave it inferred. The refusal's code is named too,
+* since a caller branches on `code` and never on the prose.
+*/
+const STRICT_PATH_FLAG = "Refuse an unusable --path instead of letting the placement rule decide. By default a --path that is not a usable memory path is re-derived, so the memory lands somewhere you did not name and the response reports that other path as a success. With this flag the write is REFUSED with ERR_INVALID_MEMORY naming the clause the path broke, and nothing is written, staged, or committed. It governs the path you NAMED: with no --path there is nothing to be strict about and the flag changes nothing, while an EMPTY or blank --path is named rather than absent and is refused — that is what your own path template renders when it produced nothing. An OCCUPIED path is refused with ERR_WRITE_CONFLICT with or without it.";
+/**
+* The `--facet` help, shared by every command that scopes on one.
+*
+* The composition rule is IN the help because it is a semantic contract rather than a convenience: a
+* caller who read `--facet a=1 --facet b=2` as "either" would act on a superset, and one who read
+* `--facet a=1 --facet a=2` as "both" would act on an empty result. Neither mistake is visible in
+* the rows that come back.
+*
+* The unitless clause is there for the same reason. `file_facets.numeric_value` exists, and offering
+* a numeric comparison over it would be offering an inequality on an unlabelled number — the unit
+* lives in the human phrasing beside the value, so the caller owns it, and it owns it by matching the
+* text the corpus holds.
+*/
+const FACET_FLAG = "Restrict to memories carrying a `<dl>` facet, as name=value; the value may contain `=`, the name may not. Repeatable, and the composition is fixed: values under the SAME name broaden (--facet doc-type=runbook --facet doc-type=guide is either), DIFFERENT names narrow (--facet doc-type=runbook --facet tier=1 is both). This is the extension axis: memhtml's element and meta vocabularies are closed, so a consumer's own document kinds, states, and tiers live in `<dt>`/`<dd>` pairs and are queried here. The match is on the facet's TEXT with no case folding, so write the halves you mean to query. The stored form is the element's text content, which the parser collapses whitespace runs in and trims — so `<dd>runbook  rollback</dd>` is stored and queried single-spaced. There is no numeric comparison: a `<data value>` is indexed UNITLESS because the unit lives in the prose beside it, so the caller owns the unit and matches the text it wrote.";
 /** Flags every retrieval command shares, so `search` and `recall` cannot scope differently. */
 const SCOPE_FLAGS = [
 	{
@@ -1618,6 +1966,12 @@ const SCOPE_FLAGS = [
 		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: "facet",
+		type: "string",
+		description: FACET_FLAG,
+		repeatable: true
+	},
 	{
 		name: "include-archived",
 		type: "boolean",
@@ -1692,7 +2046,13 @@ const COMMANDS = [
 			{
 				name: "path",
 				type: "string",
-				description: "An explicit path override. Ignored when it is not a valid memory path."
+				description: "An explicit path override. One that is not a usable memory path (rooted in a PARA bucket, ending in .html, no `.` or `..` segment) is IGNORED and the placement rule decides instead, so a malformed override lands the memory somewhere you did not name — pass --strict-path to have it refused instead. One a file ALREADY occupies is REFUSED with ERR_WRITE_CONFLICT and nothing is written or committed: this corpus overwrites nothing, and an explicit path gets no `-2` suffix because you named one path. To replace what a memory says, use `memhtml correct <path>`."
+			},
+			{
+				name: "strict-path",
+				type: "boolean",
+				description: STRICT_PATH_FLAG,
+				default: false
 			},
 			{
 				name: "workspace",
@@ -1746,7 +2106,7 @@ const COMMANDS = [
 			{
 				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."
+				description: "The JSONL file to read. One complete JSON object per line. Omit it, pass `--file -`, or pass a positional `-` to read the stream from stdin; stdin beside a real --file is refused."
 			},
 			{
 				name: "continue-on-error",
@@ -1792,11 +2152,31 @@ const COMMANDS = [
 			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."
-		}],
+		/**
+		* The whole provenance triple, because the `read` arm stamps the whole triple.
+		* `memory_session_links` carries `prompt_id` and `turn_uuid` beside `session_id`, so a command
+		* that declared only the session would record a coarser link for a read than the write path
+		* records for the same turn, and one triple could not be threaded through a write-then-read
+		* flow. MCP's `memory_read` narrows to `session_id`; this surface is the one an agent threads a
+		* triple through.
+		*/
+		flags: [
+			{
+				name: "session-id",
+				type: "string",
+				description: "Records a `read` session link, so provenance is queryable both ways."
+			},
+			{
+				name: "prompt-id",
+				type: "string",
+				description: "The prompt within that session."
+			},
+			{
+				name: "turn-uuid",
+				type: "string",
+				description: "The turn within that session."
+			}
+		],
 		responseTypes: ["memory.detail"]
 	},
 	{
@@ -1877,6 +2257,16 @@ const COMMANDS = [
 				name: "session-id",
 				type: "string",
 				description: "Records a `corrected` session 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.corrected"]
@@ -1909,22 +2299,42 @@ const COMMANDS = [
 		summary: "The memory graph around one path, to a fixed depth of at most two hops.",
 		args: [{
 			name: "path",
-			description: "The center of the neighborhood.",
+			description: "The center of the neighborhood.",
+			required: true
+		}],
+		flags: [
+			{
+				name: "depth",
+				type: "int",
+				description: "1 or 2. Never more.",
+				default: 1
+			},
+			{
+				name: "limit",
+				type: "int",
+				description: "Distinct nodes to return, clamped to 200. `nodesDropped` counts the paths the walk reached and this limit turned away, and `scanSaturated` says the walk stopped at its own 10000-row cap, which no limit recovers.",
+				default: 200
+			},
+			{
+				name: "rel",
+				type: "string",
+				description: "Restrict to these rels. Repeatable.",
+				values: MEMORY_RELS,
+				repeatable: true
+			}
+		],
+		responseTypes: ["memory.neighbors"]
+	},
+	{
+		name: "resolve",
+		summary: "Follow a possibly-moved path forward to the memory that carries the fact now.",
+		args: [{
+			name: "path",
+			description: "The path a receipt, citation, or older answer recorded.",
 			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"]
+		flags: [],
+		responseTypes: ["memory.resolved"]
 	},
 	{
 		name: "archive",
@@ -1948,7 +2358,8 @@ const COMMANDS = [
 		args: [{
 			name: "path",
 			description: "A memory path. Repeat the argument for more.",
-			required: true
+			required: true,
+			repeatable: true
 		}],
 		flags: [{
 			name: "signal",
@@ -1961,7 +2372,7 @@ const COMMANDS = [
 	},
 	{
 		name: "list",
-		summary: "Page through the corpus by type, workspace, tag, entity, or PARA bucket.",
+		summary: "Page through the corpus by type, workspace, tag, entity, facet, or PARA bucket.",
 		args: [],
 		flags: [
 			{
@@ -1985,6 +2396,12 @@ const COMMANDS = [
 				type: "string",
 				description: "One `type:name` entity reference."
 			},
+			{
+				name: "facet",
+				type: "string",
+				description: FACET_FLAG,
+				repeatable: true
+			},
 			{
 				name: "para",
 				type: "string",
@@ -2016,6 +2433,31 @@ const COMMANDS = [
 		],
 		responseTypes: ["memory.list"]
 	},
+	{
+		name: "entity activity",
+		summary: "Every entity with its file count and its last activity, newest first. Report only.",
+		args: [],
+		flags: [
+			{
+				name: "type",
+				type: "string",
+				description: "Restrict to one entity type, e.g. `service`. The half before the colon in a `type:name` reference."
+			},
+			{
+				name: "limit",
+				type: "int",
+				description: "Rows to return, 1 to 500. An ask outside that is clamped into it rather than refused, and `limit` echoes the bound the answer was built under. `entityCount` is the total matching the scope, so a clamped answer is visible.",
+				default: 50
+			},
+			{
+				name: "include-archived",
+				type: "boolean",
+				description: "Aggregate archived memories too. Excluded by default: eviction is a `git mv`, so an archived memory still exists and would otherwise keep an entity looking active.",
+				default: false
+			}
+		],
+		responseTypes: ["entity.activity"]
+	},
 	(
 	/**
 	* The task family: CRUDL over the 10th memory type, without retrieval.
@@ -2245,12 +2687,13 @@ const COMMANDS = [
 	{
 		name: "sleep run",
 		/**
-		* The count is DERIVED from `SLEEP_PHASES`, not typed. Both strings used to spell `15` by hand,
-		* and adding a sixteenth phase left `AGENTS.md` and `memhtml manifest` asserting a number the list
-		* beside them contradicted — visible only because the doc drift gate compares generated bytes, and
-		* only for the one of the two that also prints the names.
+		* Both counts are `SLEEP_PHASES.length`, never typed. A phase added to that list moves this
+		* summary and the `--phases` description below together, so neither can assert a number the list
+		* printed beside it contradicts. A hand-typed count is not symmetrically caught: the doc drift
+		* gate compares generated bytes, so it fails only on the string that also prints the names, and a
+		* stale number in the other one ships.
 		*/
-		summary: `The nightly curation cycle: ${SLEEP_PHASES.length} phases, each an isolated commit on a review branch.`,
+		summary: `The curation cycle: ${SLEEP_PHASES.length} phases, each an isolated commit on a review branch.`,
 		args: [],
 		flags: [
 			{
@@ -2272,7 +2715,7 @@ const COMMANDS = [
 			{
 				name: "deep",
 				type: "boolean",
-				description: "The deep-sleep cycle: mine a lower grouping band, group by shared entity, re-file inbox singletons, and iterate compress until a pass folds nothing. Reaches the inbox tail the nightly community gate cannot; costs more model calls. Same branch, review, and merge gate as a nightly run.",
+				description: "The deep-sleep cycle: mine a lower grouping band, group by shared entity, re-file inbox singletons, and iterate compress until a pass folds nothing. Reaches the inbox tail the default community gate cannot; costs more model calls. Same branch, review, and merge gate as a run without this flag.",
 				default: false
 			},
 			{
@@ -2333,6 +2776,13 @@ const COMMANDS = [
 		flags: [],
 		responseTypes: ["sleep.report"]
 	},
+	{
+		name: "sleep plan",
+		summary: "Would a run change anything? Read the signals from index counts, running no phase.",
+		args: [],
+		flags: [],
+		responseTypes: ["sleep.plan"]
+	},
 	{
 		name: "status",
 		summary: "Corpus health: HEAD, dirty state, counts by type, edges, index freshness.",
@@ -2376,6 +2826,11 @@ const COMMANDS = [
 				type: "int",
 				description: "The fixture corpus seed. A failing run is reproducible from this number."
 			},
+			{
+				name: "now",
+				type: "int",
+				description: "The run instant the fixture corpus anchors its stamps behind, UTC milliseconds since the epoch. The other half of reproducing a failing run: the corpus is a function of (seed, now), and the recency arm ranks on those stamps. Defaults to the clock, and rides back in the report."
+			},
 			{
 				name: "size",
 				type: "int",
@@ -2436,7 +2891,7 @@ const COMMANDS = [
 			{
 				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`."
+				description: "The script to run, as a path on the HOST. Omit it, pass `--file -`, or pass a positional `-` to read the script from stdin. Mutually exclusive with `--script`."
 			},
 			{
 				name: "script",
@@ -2489,7 +2944,7 @@ const COMMANDS = [
 	},
 	{
 		name: "serve mcp",
-		summary: "Run the `memhtml-mcp` stdio server: 14 tools and 2 resources over this same repo.",
+		summary: "Run the `memhtml-mcp` stdio server: 15 tools and 3 resources over this same repo.",
 		args: [],
 		flags: [],
 		responseTypes: ["serve.exit"]
@@ -2524,12 +2979,12 @@ const GUIDE = [
 	},
 	{
 		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."
+		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 the same tools and 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. `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.`
+${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\`, \`strict_path\`, \`workspace\`, \`tag\`, \`entity\`, \`importance\`, \`confidence\`, \`status\`, \`due\`, \`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",
@@ -2541,7 +2996,7 @@ ${GUIDE_OP_EXAMPLE}\n\`op\` is \`write\` (the only verb in the vocabulary today)
 	},
 	{
 		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."
+		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` 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);
@@ -2552,22 +3007,22 @@ const GUIDE_TOPICS = GUIDE.map((block) => block.topic);
 * 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.
+* `<mark>` claim plus one `<p>` per paragraph. Turning the first into the second is a text
+* heuristic, and it must have exactly one copy: `apps/mcp` and `apps/cli` both import this module,
+* because a sentence-splitting rule maintained per door lets `memhtml apply` and
+* `memory_write_batch` derive different claims from the same body, making the gist of a memory
+* 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.
+* The derivation is defense in depth: `@memhtml/html` constraint 1 rejects an empty `<mark>`
+* outright, so a door that skipped this would be stopped by the store's render gate rather than
+* landing a file with an empty `files.gist`. What this module carries 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
@@ -2650,11 +3105,20 @@ const LIST_FIELDS = {
 	entity: "entities",
 	entities: "entities"
 };
+/**
+* Fields that must be a JSON boolean.
+*
+* Its own table because {@link SCALAR_FIELDS}' decode refuses anything that is not a string, and a
+* boolean spelled `"true"` is a different value from `true` on this wire. A caller that sent the
+* string would otherwise get a strict-path ask that reads as satisfied and behaves as absent.
+*/
+const BOOLEAN_FIELDS = { strict_path: "strictPath" };
 /** `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)
+	...Object.keys(LIST_FIELDS),
+	...Object.keys(BOOLEAN_FIELDS)
 ]);
 
 //#endregion
@@ -2670,6 +3134,25 @@ const nowSecond = Effect.clockWith((clock) => Effect.map(clock.currentTimeMillis
 //#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))]);
 /**
+* Every flag name the spec table declares, mapped to the type it declares.
+*
+* **Only a `string` or `int` flag consumes the next argv token as its value**, and the two kinds it
+* excludes are excluded for different reasons:
+*
+* - A `boolean` flag takes `--flag`, `--flag=value`, or `--no-flag`, so the token after it stays
+*   positional and can be the command: `memhtml --dense list` is the `list` command, not an empty
+*   command carrying `dense: "list"`.
+* - A flag the table does not declare has no type to consult, and eating the token would swallow the
+*   command name — `memhtml --nope list` would answer the manifest at exit 0 instead of refusing an
+*   unknown flag. Leaving the token positional lets the command reach {@link validate}, which is
+*   where an unknown flag becomes exit 2.
+*
+* The map is name-keyed across every command even though validation is per-command, because the
+* parser runs before the command is known. That is sound only while one name carries ONE type
+* everywhere, which is a property of the table `cli.test.ts` enforces rather than a hope.
+*/
+const FLAG_TYPES = new Map([...GLOBAL_FLAGS, ...COMMANDS.flatMap((command) => command.flags)].map((flag) => [flag.name, flag.type]));
+/**
 * The two-word command names, longest first.
 *
 * A subcommand is matched greedily so `index status` beats `index`, and the leftover tokens become
@@ -2687,15 +3170,16 @@ const today = Effect.clockWith((clock) => Effect.map(clock.currentTimeMillis, (m
 * 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 a declared class at all.** `McpServer`'s registration of a toolkit tool wraps the handler in
+* ONE `Effect.catch` with three branches (effect 4.0.0-rc.109), and only one of them lets prose
+* through. An `AiError` takes branch 1 and is rewritten to `INTERNAL_TOOL_ERROR_MESSAGE`, "Tool
+* execution failed due to an internal server error", unless its reason is
+* `ToolParameterValidationError`. A value the tool's own `failureSchema` accepts takes branch 2,
+* where `error instanceof Error ? error.message` passes the text through verbatim. Anything else
+* takes branch 3 and is rewritten. 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
@@ -2724,7 +3208,7 @@ 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
+* The reader is an LLM mid-task holding fifteen 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
@@ -2748,7 +3232,11 @@ const text = (value) => typeof value === "string" ? value : void 0;
 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 "PathNotFound": return [
+			"call memory_resolve on the path you cited — a correction or an eviction may have moved it",
+			"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"];
@@ -2771,6 +3259,17 @@ const mcpSuggestionsFor = (error) => {
 */
 const sentence = (reason) => /[.!?]$/.test(reason) ? reason : `${reason}.`;
 /**
+* The three parts as the one string the protocol carries: code, then reason, then suggestions.
+*
+* One function so the shape is one shape. Every caller here folds the same three parts, and the
+* `ERR_*` prefix followed by a colon is what lets a consumer read the code back out of prose.
+*/
+const compose = (code, reason, suggestions) => new ToolFailure({
+	code,
+	suggestions,
+	message: suggestions.length === 0 ? `${code}: ${sentence(reason)}` : `${code}: ${sentence(reason)} Try: ${suggestions.join("; ")}`
+});
+/**
 * A typed domain failure as the wire failure.
 *
 * Total by construction, three times over: `codeFor` maps an unknown `_tag` to `ERR_UNKNOWN`,
@@ -2799,14 +3298,41 @@ const toToolFailure = (error) => {
 	* 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("; ")}`
-	});
+	return compose(codeFor(error), messageFor(error), mcpSuggestionsFor(error));
+};
+/**
+* A refusal the RESOURCE surface owns, composed into the same wire failure a tool call produces.
+*
+* Three refusals belong to that surface and to no use case: a URI outside the published template, a
+* run id with no committed report behind it, and a defect at the boundary. None is a typed error a
+* use case raised, so `toToolFailure` has nothing to translate, and each is composed here for the
+* reason `batchAbortFailure` is — the message shape is one shape, and a second hand-written copy of
+* it drifts the first time the format moves.
+*
+* The reason and the suggestions come from the caller because a resource read's recovery depends on
+* WHICH resource refused, while `mcpSuggestionsFor` answers a different question (what to do about a
+* given error tag). The rule they hold to is the same one: every string names a tool in the toolkit
+* or an action inside the caller's own control.
+*/
+const resourceFailure = (code, reason, suggestions) => compose(code, reason, suggestions);
+/**
+* A failure as the JSON-RPC error the RESOURCE surface has, carrying the tool surface's own prose.
+*
+* `resources/read` has no per-resource failure schema to declare, so a failed read reaches the client
+* as a JSON-RPC error object whose `message` is the only field an agent reads. `toToolFailure`
+* composes that string — same code vocabulary, same reason discipline, same executable suggestions —
+* and this function decides only which error class carries it: `InvalidParams` when the URI names
+* something that is not there, which is the code `McpServer.findResource` itself returns for a URI no
+* template matched, and `InternalError` for every other failure.
+*
+* Nothing here reads the cause's own text. `Effect.orDie` on a resource handler is what puts
+* `Cause.prettyErrors(cause)[0].message` on the wire, and that message carries the ABSOLUTE
+* filesystem path the read was attempted at, plus the stack that reached it. A resource is the one
+* surface with no tool-response envelope to hide behind, so the sanitizing has to happen here.
+*/
+const toResourceFailure = (error) => {
+	const failure = toToolFailure(error);
+	return failure.code === "ERR_PATH_NOT_FOUND" ? new McpSchema.InvalidParams({ message: failure.message }) : new McpSchema.InternalError({ message: failure.message });
 };
 /**
 * An atomic batch's abort as the wire failure, naming the op that caused it.
@@ -2845,10 +3371,292 @@ const batchAbortFailure = (index, code, reason) => {
 	});
 };
 
+//#endregion
+//#region apps/mcp/src/resources.ts
+/**
+* The three resources: design.md §8's two, plus one version-pinned citation grain.
+*
+* 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.
+*
+* `memhtml://file/{path}` and `memhtml://at/{commit}/{path}` are the same read at two grains, and the
+* difference is whether the answer can move. A path is the id of a memory and a correction rewrites
+* what lives at it, so a receipt citing a path alone cites whatever is there when someone follows it.
+* The pinned form names a commit as well, and a commit sha is immutable, so the bytes behind that URI
+* are the bytes the receipt was written against. This is a grain only a git-native store can offer, and
+* `memory_resolve` is the other half: one URI says what was true, the other says where the fact went.
+*/
+/** The URI scheme every resource publishes under, matching `SERVER_NAME`. */
+const SCHEME = "memhtml";
+/**
+* The router pattern that matches one resource's URIs, and why it is spelled this way.
+*
+* `McpServer` matches a `resources/read` URI with find-my-way (`effect/unstable/http/FindMyWay`,
+* effect 4.0.0-rc.109), and two of that router's rules decide this string:
+*
+* - A single `:` opens a NAMED PARAMETER, and `::` is the escape for a literal colon. The scheme's
+*   colon therefore has to be doubled; left single, `memhtml:` registers a parameter named `""`.
+* - A named parameter's value ENDS AT THE NEXT `/`, so `:path` matches exactly one segment and cannot
+*   reach `areas/oncall/x.html`. Every memory path has at least two segments and an archived one has
+*   at least four, so a single-segment route leaves the resource unreachable in normal use. `*` is the
+*   rest parameter, the only construct that matches across `/`, and the router requires it to be the
+*   LAST character of the pattern.
+*
+* The captured value does not arrive through the parameter array. `McpServer` folds a matched route's
+* parameters into a POSITIONAL array by `Number(name)`, and the rest parameter's name is `*`, so
+* `Number("*")` is `NaN` and the slot is never filled. The handler therefore reads its one parameter
+* out of the URI, which the match always carries — see {@link capturedOf}.
+*/
+const routerPathFor = (section) => `${SCHEME}:://${section}/*`;
+/** The literal head of every URI a section serves, up to and including its parameter's slash. */
+const prefixOf = (section) => `${SCHEME}://${section}/`;
+/**
+* The part of a URI after `memhtml://<section>/`, percent-escapes decoded, or a refusal.
+*
+* ONE decode covers both spellings a client can send. `areas/oncall/x.html` passes through unchanged,
+* and `areas%2Foncall%2Fx.html` decodes to the same string, so a client that escaped the separators
+* and a client that did not name the same resource.
+*
+* The prefix has to be present VERBATIM. The router tolerates repeated slashes and this does not, so
+* `memhtml:///file/x.html` matches the route and is then refused here, rather than sliced at an offset
+* a character away from the one that matched.
+*
+* The `decodeURIComponent` guard is a boundary rather than a branch the route can reach today: the
+* router decodes a whole URI before it matches anything, so `%zz` matches nothing and never arrives.
+* An undecodable value that did arrive is a URI this server cannot read rather than a file that is
+* missing, and it is refused with the URI echoed back for the caller to compare against what it sent.
+*/
+const capturedOf = (uri, section, refuse) => {
+	const prefix = prefixOf(section);
+	if (!uri.startsWith(prefix)) return Effect.fail(refuse(uri));
+	try {
+		return Effect.succeed(decodeURIComponent(uri.slice(prefix.length)));
+	} catch {
+		return Effect.fail(refuse(uri));
+	}
+};
+/**
+* One resource template, registered on the server.
+*
+* `McpServer.addResourceTemplate` rather than the `McpServer.resource` tagged template, because the
+* tagged template compiles its parameters to named router parameters and those stop at a `/` — see
+* {@link routerPathFor}. Registering the route directly is what lets one published template serve a
+* path of any depth.
+*
+* **Every failure is sanitized here, and the handler never dies.** A defect becomes a stated refusal
+* through `catchDefect` and a typed failure becomes one through `toResourceFailure`, both AFTER
+* `tapCause` has put the real cause on stderr, where an operator reads it. An `Effect.orDie` in its
+* place hands the client `Cause.prettyErrors(cause)[0].message`: an absolute filesystem path for a
+* missing sleep report, and a `PathNotFound` stripped of its `ERR_*` code and its suggestions.
+*
+* `Layer.provide(McpServer.layer)` mirrors what `McpServer.resource` does with the same static layer
+* reference, so the registry this writes into is the one `layerStdio` serves from: a layer is
+* memoized per build, so naming it here twice is naming it once.
+*/
+const templateLayer = (spec) => Layer.effectDiscard(Effect.gen(function* () {
+	const registry = yield* McpServer.McpServer;
+	const services = yield* Effect.context();
+	yield* registry.addResourceTemplate({
+		template: new McpSchema.ResourceTemplate({
+			uriTemplate: spec.uriTemplate,
+			name: spec.name,
+			description: spec.description,
+			mimeType: spec.mimeType
+		}),
+		routerPath: routerPathFor(spec.section),
+		annotations: Context.empty(),
+		completions: {},
+		handle: (uri) => capturedOf(uri, spec.section, spec.refuse).pipe(Effect.flatMap((captured) => spec.read(uri, captured)), Effect.map((text) => ({ contents: [{
+			uri,
+			mimeType: spec.mimeType,
+			text
+		}] })), Effect.tapCause(Effect.logError), Effect.catchDefect(() => Effect.fail(resourceFailure("ERR_UNKNOWN", "the server could not read that resource", ["retry the read once", "report this to the operator if it persists — the server's own log carries the detail"]))), Effect.mapError(toResourceFailure), Effect.provideContext(services))
+	});
+})).pipe(Layer.provide(McpServer.McpServer.layer));
+/** `memhtml://file/{path}`: nothing readable behind this URI. */
+const fileRefusal = (uri) => resourceFailure("ERR_PATH_NOT_FOUND", `nothing to read at ${uri}`, [
+	`re-request it as ${prefixOf("file")}<repo-root-relative path>, the form resources/templates publishes`,
+	"call memory_resolve on that path — a correction or an eviction may have moved the memory, and both are recorded",
+	"call memory_search or memory_list for a path this corpus holds"
+]);
+/**
+* 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.
+*
+* **`isValidMemoryPath` gates the path before the store sees it, and that is containment rather than
+* validation.** The rest parameter accepts `/`, so it also accepts `../../etc/passwd`, and the store's
+* reader joins a repo-relative path onto the git root without a traversal check of its own. The gate
+* refuses any path carrying a `.` or `..` segment, any path outside the four PARA buckets, and
+* anything not ending in `.html`, which is every memory path and nothing else.
+*/
+const FileResource = templateLayer({
+	section: "file",
+	uriTemplate: "memhtml://file/{path}",
+	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",
+	refuse: fileRefusal,
+	read: (uri, captured) => Effect.gen(function* () {
+		if (!isValidMemoryPath(captured)) return yield* Effect.fail(fileRefusal(uri));
+		const result = yield* readMemory(normalizePath(captured));
+		return [
+			`# ${result.doc.title}`,
+			"",
+			result.doc.article.gist,
+			"",
+			result.doc.article.bodyText
+		].join("\n");
+	})
+});
+/** `memhtml://sleep/{run-id}`: no committed report behind this URI. */
+const sleepRefusal = (uri) => resourceFailure("ERR_PATH_NOT_FOUND", `no sleep report at ${uri}`, ["call memory_status to read the id and the status of the last sleep run", "report this to the operator if memory_status names this run — its report never committed"]);
+/**
+* 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.
+*
+* **The filename comes from `reportFilename`, the function the sleep phase writes it with.** A run id
+* is `sleep/<YYYY-MM-DD>` and a `/` is not legal in a filename, so the producer folds the separator to
+* a hyphen and the file is `sleep-2026-08-02.html`. Deriving that here a second time is the
+* consumer-side reimplementation of a producer's naming rule that this repo forbids; importing it
+* means the two cannot disagree. It also contains the read for free, since folding every `/` leaves a
+* caller no way to name a directory.
+*
+* The run id is taken VERBATIM, in the `sleep/<date>` spelling `memory_status.last_sleep.run_id`
+* publishes, so the value a client copies out of a status call is the value this resource takes.
+*/
+const SleepResource = templateLayer({
+	section: "sleep",
+	uriTemplate: "memhtml://sleep/{run-id}",
+	name: "Sleep run report",
+	description: "One sleep run's committed HTML report: per-phase counts, commits, and what the run changed.",
+	mimeType: "text/html",
+	refuse: sleepRefusal,
+	read: (uri, runId) => Effect.gen(function* () {
+		const roots = yield* Roots;
+		const html = yield* readFileOrNull(join(roots.memhtmlRoot, SLEEP_REPORTS_DIR, reportFilename(runId)));
+		return html === null ? yield* Effect.fail(sleepRefusal(uri)) : html;
+	})
+});
+/**
+* A commit sha, and nothing that can move.
+*
+* Seven to sixty-four lowercase hex characters: git's own abbreviation floor through the width of
+* SHA-256. `HEAD`, a branch name, and a tag are all REFUSED, and that refusal is the whole point of
+* this resource — a URI whose target can move is not a citation, and `memhtml://at/main/x.html` would
+* read as a pin while resolving to different bytes next week. A caller wanting the current bytes has
+* `memhtml://file/{path}`, which says so in its own name.
+*
+* It is also the containment on the argv: `lsTreeR` passes this value to `git ls-tree` as a positional,
+* and a value starting with `-` would be read as an option. Hex cannot.
+*/
+const COMMIT_SHA = /^[0-9a-f]{7,64}$/;
+/** `memhtml://at/{commit}/{path}`: no such path in that commit, or no such commit here. */
+const pinnedRefusal = (uri) => resourceFailure("ERR_PATH_NOT_FOUND", `nothing to read at ${uri}`, [
+	`re-request it as ${prefixOf("at")}<commit-sha>/<repo-root-relative path>, the form resources/templates publishes`,
+	"call memory_resolve for the path this memory occupies now, and read `indexed_commit` for a sha this repository holds",
+	"a branch name or HEAD is refused on purpose: a citation names bytes that cannot move"
+]);
+/**
+* One memory's text AS OF a commit: a citation that cannot move.
+*
+* **Two segments after the section, split at the FIRST `/`.** The rest parameter captures
+* `<commit>/<path>` as one string, and the commit half cannot contain a slash while the path half must,
+* so the first separator is the only place the split can be. The published template names both holes,
+* which is what makes this route multi-segment BY CONSTRUCTION: `{path}` alone is at least two segments
+* for every memory and at least four for an archived one.
+*
+* **The bytes come out of git, not off disk.** `lsTreeR` resolves `<path>` in `<commit>`'s tree to a
+* blob sha and `catFileBatch` reads that object, so a path corrected, archived, or evicted since is
+* still readable at the commit that held it. Reading the worktree instead would answer with today's
+* file under yesterday's URI, which is the exact failure the pin exists to prevent.
+*
+* **The same text shape `memhtml://file/{path}` returns**, parsed from the historical bytes rather
+* than re-derived: title, claim, body. A client renders either grain the same way, and the only
+* difference between the two answers is which commit produced it.
+*
+* **This read does NOT bump salience, where `memhtml://file/{path}` does.** Salience counts a chosen
+* open of a memory, and `state.access` is keyed on PATH with no notion of a commit
+* (`packages/index/state-migrations/S0001_access.sql`), so a bump here would credit whatever occupies
+* that path today for a read of a version it may not even contain. Verifying a receipt is auditing, not
+* choosing, and rewarding audit traffic would let a heavily-cited-then-corrected memory outrank the
+* fact that replaced it. It is also why this resource declares `Store` and not `IndexRecorder`: the
+* dependency set makes the refusal structural.
+*
+* `isValidMemoryPath` gates the path for `FileResource`'s reason — the rest parameter accepts `/`, so
+* it accepts `../../etc/passwd`, and `git ls-tree` would happily resolve a path outside the four PARA
+* buckets if the tree held one.
+*
+* A `GitFailure` becomes this resource's own refusal rather than an `ERR_GIT`: from the client's side,
+* an unknown commit and a path absent from a known commit are one answer, "this URI names nothing
+* here", and the real cause is on stderr where an operator reads it. Nothing else in the read can fail
+* that way, since the path is gated and the blob is named by the tree itself.
+*/
+const PinnedResource = templateLayer({
+	section: "at",
+	uriTemplate: "memhtml://at/{commit}/{path}",
+	name: "Memory file at a commit",
+	description: "One memory's title, claim, and body text as of a specific commit sha. For a citation whose bytes cannot move: the path may since have been corrected, archived, or evicted. A branch name or HEAD is refused.",
+	mimeType: "text/plain",
+	refuse: pinnedRefusal,
+	read: (uri, captured) => Effect.gen(function* () {
+		const at = captured.indexOf("/");
+		if (at <= 0) return yield* Effect.fail(pinnedRefusal(uri));
+		const commit = captured.slice(0, at);
+		const path = captured.slice(at + 1);
+		if (!COMMIT_SHA.test(commit) || !isValidMemoryPath(path)) return yield* Effect.fail(pinnedRefusal(uri));
+		const store = yield* Store;
+		const normalized = normalizePath(path);
+		const blob = (yield* store.git.lsTreeR(commit, [normalized]).pipe(Effect.tapError(Effect.logError), Effect.catchTag("GitFailure", () => Effect.fail(pinnedRefusal(uri))))).find((entry) => entry.path === normalized && entry.objectType === "blob");
+		if (blob === void 0) return yield* Effect.fail(pinnedRefusal(uri));
+		const body = (yield* store.git.catFileBatch([blob.sha]).pipe(Effect.tapError(Effect.logError), Effect.catchTag("GitFailure", () => Effect.fail(pinnedRefusal(uri))))).get(blob.sha);
+		if (body === void 0) return yield* Effect.fail(pinnedRefusal(uri));
+		const doc = yield* parseMemory(new TextDecoder().decode(body));
+		return [
+			`# ${doc.title}`,
+			"",
+			doc.article.gist,
+			"",
+			doc.article.bodyText
+		].join("\n");
+	})
+});
+/**
+* The URI that pins one memory at one commit, for a producer of a receipt.
+*
+* Exported so `memory_resolve` can publish a citation the caller pastes rather than assembles. The
+* spelling of a URI belongs to the surface that routes it, and a handler composing `memhtml://at/…`
+* out of its own string literals would be a second declaration of this template — the same
+* consumer-side reimplementation of a producer's naming rule that `reportFilename` exists to prevent
+* one resource over.
+*
+* The path is NOT percent-encoded. `capturedOf` decodes once, so a raw path and an escaped one name
+* the same resource, and the raw form is the one the published template shows.
+*/
+const pinnedUri = (commit, path) => `${prefixOf("at")}${commit}/${normalizePath(path)}`;
+/** Every resource as one layer, for the server to provide. */
+const Resources = Layer.mergeAll(FileResource, SleepResource, PinnedResource);
+
 //#endregion
 //#region apps/mcp/src/tools.ts
 /**
-* The fourteen tools: design.md §8 verbatim, plus `memory_write_batch` (spec 004 D7).
+* The fifteen tools: design.md §8 verbatim, plus `memory_write_batch` (spec 004 D7) and
+* `memory_resolve`.
 *
 * **`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
@@ -2857,21 +3665,29 @@ const batchAbortFailure = (index, code, reason) => {
 * **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.
+* entry point. A read-only `sleep_status` is the only shape this surface could ever take for it; 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.
 *
+* **A `description` has to FOLD to a string by AST**, so it is built from string literals, `+`, and
+* identifiers declared in this file — never a template literal with a substitution and never an
+* imported value. The docs site reads each description straight out of this source
+* (`foldString` in `apps/docs/src/loaders/repo-sources.ts`) so the reference page and the published
+* bytes are the same string; an expression it cannot fold throws at that build instead of rendering
+* a paraphrase. A number that must not drift from a constant is asserted in `tests/tools.test.ts`
+* against the constant, which is the check a literal cannot make for itself.
+*
 * **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.
+* no declared failure schema gets `Schema.Never` (`Tool.make`'s `options?.failure ?? Schema.Never`,
+* effect 4.0.0-rc.109), so `McpServer`'s `isDeclaredFailure` predicate rejects everything and every
+* failure, typed domain error included, is rewritten to `INTERNAL_TOOL_ERROR_MESSAGE`, "Tool
+* execution failed due to an internal server error", before it reaches the caller. 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);
@@ -2889,10 +3705,10 @@ 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"}`.
+* `NaN` are not JSON numbers and the codec represents them as strings. Probed on effect
+* 4.0.0-rc.109, `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. */
@@ -2903,7 +3719,7 @@ const Count = Schema.Int;
 * 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
+* undefined, got null" (both probed on effect 4.0.0-rc.109). 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.
@@ -2930,8 +3746,8 @@ const Optional = (schema) => Schema.optionalKey(Schema.NullOr(schema));
 * 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.
+* same array to fifteen tools would let one tool's construction mutate the dependency list of the
+* other fourteen.
 */
 const READS = () => [DatabaseService];
 const WRITES = () => [
@@ -2966,7 +3782,19 @@ const writeFields = () => ({
 	/** Pre-authored article markup, used verbatim in place of `body`. See the description's contract. */
 	article_html: Optional(Schema.String),
 	memory_type: WritableType,
+	/**
+	* An explicit placement override. Unusable values are re-derived and occupied ones are refused;
+	* `PATH_OVERRIDE_CONTRACT` states both branches in the description, which is where a caller reads
+	* them. The refusal is `@memhtml/store`'s `freePathFor`, so this door and `memhtml apply` share it.
+	*/
 	path: Optional(MemoryPath),
+	/**
+	* Refuse an unusable `path` instead of re-deriving one. Opt-in, because the lenient branch is what
+	* ships and what callers depend on; `PATH_OVERRIDE_CONTRACT` states both branches in the
+	* description, which is where a caller reads them. The refusal is `@memhtml/store`'s
+	* `strictPathRefusal`, so this door, `memhtml write`, and `memhtml apply` share it.
+	*/
+	strict_path: Optional(Schema.Boolean),
 	workspace: Optional(Schema.String),
 	tags: Optional(Schema.Array(Schema.String)),
 	entities: Optional(Schema.Array(Schema.String)),
@@ -2977,7 +3805,7 @@ const writeFields = () => ({
 	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.",
+	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). `path` is optional and rarely worth sending: without it the placement rule picks the directory from the memory's type, workspace, and entities, and the title becomes the filename. A `path` that is not a usable memory path (rooted in a PARA bucket, ending in .html, no . or .. segment) is IGNORED, and the placement rule decides instead — so a malformed override lands the memory somewhere you did not name. Send strict_path: true to have that REFUSED instead, with ERR_INVALID_MEMORY naming the clause the path broke and nothing written, staged, or committed; it governs the path you named, so with no `path` it changes nothing. Reach for it when you place documents at paths you compute, where a silent re-derivation makes a write look like it landed where you asked. A `path` that a file ALREADY occupies is REFUSED with ERR_WRITE_CONFLICT, and nothing is written or committed: this corpus overwrites nothing, and an explicit path gets no -2 suffix because you named one path. To replace what a memory says, call memory_correct on it — that archives the file it supersedes in the same commit and leaves it readable under archive/. 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,
@@ -2993,7 +3821,7 @@ const MemoryWrite = Tool.make("memory_write", {
 * 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
+* own `required`. Probed on effect 4.0.0-rc.109, `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
@@ -3062,7 +3890,7 @@ const BatchOpResult = Schema.Struct({
 	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.",
+	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). `path` is optional and rarely worth sending: without it the placement rule picks the directory from the memory's type, workspace, and entities, and the title becomes the filename. A `path` that is not a usable memory path (rooted in a PARA bucket, ending in .html, no . or .. segment) is IGNORED, and the placement rule decides instead — so a malformed override lands the memory somewhere you did not name. Send strict_path: true to have that REFUSED instead, with ERR_INVALID_MEMORY naming the clause the path broke and nothing written, staged, or committed; it governs the path you named, so with no `path` it changes nothing. Reach for it when you place documents at paths you compute, where a silent re-derivation makes a write look like it landed where you asked. A `path` that a file ALREADY occupies is REFUSED with ERR_WRITE_CONFLICT, and nothing is written or committed: this corpus overwrites nothing, and an explicit path gets no -2 suffix because you named one path. To replace what a memory says, call memory_correct on it — that archives the file it supersedes in the same commit and leaves it readable under archive/. 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),
@@ -3139,7 +3967,7 @@ const MemoryRead = Tool.make("memory_read", {
 	})
 });
 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.",
+	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. `facets` narrows by the corpus's own <dl> facets, each entry spelled name=value (the value may contain =, the name may not). THE COMPOSITION IS FIXED: values under the SAME name broaden, so [\"doc-type=runbook\",\"doc-type=guide\"] is either; DIFFERENT names narrow, so [\"doc-type=runbook\",\"tier=1\"] is both. This is the extension axis. memhtml's element and meta vocabularies are closed, so your own document kinds, states, and tiers belong in <dt>/<dd> pairs inside the article, and this is how you query them back. The match is on the facet's TEXT with no case folding, so write the halves you mean to query. The stored form is the element's text content, which the parser collapses whitespace runs in and trims, so <dd>runbook  rollback</dd> is stored and queried single-spaced. There is no numeric comparison and that is deliberate: a <data value> is indexed UNITLESS, because the unit lives in the prose beside it, so you own the unit and match the text you wrote.",
 	dependencies: RETRIEVES(),
 	parameters: Schema.Struct({
 		query: Schema.String,
@@ -3152,6 +3980,11 @@ const MemorySearch = Tool.make("memory_search", {
 		* spelling a hit's `entities` publishes, so a value read off a hit is a valid scope verbatim.
 		*/
 		entity: Optional(Schema.String),
+		/**
+		* `<dl>` facet predicates as `name=value` strings. AND across distinct names, OR within one name;
+		* the description carries the rule, because that is what a caller reads.
+		*/
+		facets: Optional(Schema.Array(Schema.String)),
 		include_archived: Optional(Schema.Boolean),
 		/**
 		* Point-in-time view: returns what was believed valid at this moment, including
@@ -3280,12 +4113,20 @@ const MemoryLink = Tool.make("memory_link", {
 	})
 });
 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.",
+	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, and each node's `derived` says which kind of edge reached it. `nodes` holds at most 200 distinct paths, each at its minimal hop. `limit` chooses that ceiling and an ask outside 1..200 is clamped into it rather than refused, the same shape `memory_list` and `trace_search` have; `node_limit` echoes the bound the answer was built under. `edges` counts something DIFFERENT and is not a node count: it is the distinct edges the walk enumerated, including edges to paths the node clamp dropped, so it can exceed what the returned nodes account for. TWO markers report truncation, because they need different answers: `dropped_node_count` is the paths the walk reached and `limit` turned away, which a larger `limit` returns, while `scan_saturated` is the walk stopping at its own 10000-edge-row cap, which no `limit` recovers — narrow that one with `rels` or `depth: 1` instead.",
 	dependencies: READS(),
 	parameters: Schema.Struct({
 		path: MemoryPath,
 		depth: Optional(Count),
-		rels: Optional(Schema.Array(MemoryRelSchema))
+		rels: Optional(Schema.Array(MemoryRelSchema)),
+		/**
+		* Distinct paths `nodes` may hold, 1 to {@link NEIGHBORS_LIMIT}, defaulting to the ceiling.
+		*
+		* Clamped rather than refused, because a caller asking for more than the ceiling wants the
+		* ceiling — `memory_list`'s 500 and `trace_search`'s 200 are the same shape. The value the server
+		* actually used comes back as `node_limit`, so a clamped ask is visible rather than silent.
+		*/
+		limit: Optional(Count)
 	}),
 	failure: ToolFailure,
 	success: Schema.Struct({
@@ -3294,9 +4135,117 @@ const MemoryNeighbors = Tool.make("memory_neighbors", {
 			title: Schema.String,
 			/** 1-based distance from the center: 1 or 2, never 0. */
 			hop: Count,
-			rel: Schema.String
+			rel: Schema.String,
+			/**
+			* True when a SLEEP-MINED edge reaches this node, false when only authored `<link>` edges do.
+			*
+			* The max over every edge that reached the node, not the `rel` field's companion: a node an
+			* authored edge and a mined edge both reach is `derived: true`, because the question a caller
+			* asks of this field is "may this connection be a machine's suspicion", and one mined route is
+			* enough for the answer to be yes.
+			*
+			* Published because the description advertises mined edges as the point of the tool, and
+			* without this field a caller cannot tell a suspicion from an assertion — which is exactly the
+			* distinction it needs in order to decide how much to trust a lateral hop.
+			*/
+			derived: Schema.Boolean
+		})),
+		/**
+		* DISTINCT edges the walk enumerated, keyed on `(src, rel, dst)`, over both hops and both
+		* directions. Scope: this one call's walk, not the corpus — `memory_status.edges` is the corpus
+		* total and the two are different coordinate spaces.
+		*
+		* It is NOT `nodes.length` and must not be read as one: two memories joined by two rels are one
+		* node and two edges, and an edge landing on a path the node clamp dropped is counted here and
+		* absent there. Bounded by the walk's own 10000-row scan cap, which `scan_saturated` reports.
+		*/
+		edges: Count,
+		/**
+		* The node ceiling this answer was built under: the SERVER's clamp of the caller's `limit` into
+		* `1..200` ({@link NEIGHBORS_LIMIT}), not the raw ask, so a client that sent 10000 reads back 200
+		* and knows the answer is a ceiling rather than a corpus fact. A quantity of distinct paths, scoped
+		* to this one call.
+		*
+		* `node_limit` and not `limit`, because this answer carries TWO bounds and they are not
+		* interchangeable: this one governs `nodes`, and the walk's own 10000-edge-row cap governs
+		* everything, which is what `scan_saturated` reports.
+		*/
+		node_limit: Count,
+		/**
+		* Distinct paths the walk reached and `node_limit` turned away, filled by the server.
+		*
+		* A COUNT of paths absent from `nodes`, scoped to this call, so `nodes.length +
+		* dropped_node_count` is every path the walk found. `0` means `nodes` holds all of them, which is
+		* how a client tells a complete neighborhood from a clamped one. A larger `limit`, up to
+		* {@link NEIGHBORS_LIMIT}, returns them.
+		*
+		* `_count` because it is a quantity, and this repo's four numeric suffixes are not
+		* interchangeable — an `_offset`, a `_seq`, and an `_index` are all different things. `edges`
+		* keeps its bare name because it is already a published field a client branches on.
+		*/
+		dropped_node_count: Count,
+		/**
+		* True when the walk stopped at its own 10000-edge-row cap, so edges past the cap were never
+		* enumerated and NO `limit` recovers them — the truncation `dropped_node_count` cannot describe.
+		* Narrow the walk with `rels` or `depth: 1` to get an exhaustive answer.
+		*
+		* A plain boolean, never a null union: an absent or null marker cannot be told from a server that
+		* does not report saturation, and this is the field that says whether `nodes` and `edges` describe
+		* the whole neighborhood.
+		*/
+		scan_saturated: Schema.Boolean
+	})
+});
+const MemoryResolve = Tool.make("memory_resolve", {
+	description: "Follow a path an older answer, receipt, or external citation recorded FORWARD to the memory that carries the fact now. A path is the id of a memory and it is derived from the title, so a correction that rewords the title moves the file: the cited path stops resolving through no fault of the citation. `stop_reason` is what decides whether the answer is citable, and only `live` means yes. `archived` is a memory that was EVICTED rather than corrected, so nothing supersedes it and citing it as current would be wrong. `unindexed` is no such path here, which may also mean the index does not yet describe the commit that holds it — `indexed_commit` says which commit it does describe. `cycle` and `hop_limit` are the two abnormal endings: a cycle is two memories each claiming to supersede the other, an authoring defect, and `hop_limit` means `path` is where the walk stopped rather than the end of the chain, so resolving it again continues. `steps` names the mechanism of every hop, `supersedes` for an authored link and `archive_move` for a `git mv` into the archive, and each node is named by the path that holds it NOW. `hops: 0` with `stop_reason: live` does NOT mean the bytes are unchanged: a correction whose title did not change lands at the same path. Read `pinned_uri` for the grain that answers that — it is a resource URI naming these bytes at a commit, so it cannot move, where memhtml://file/<path> always returns whatever is at the path today.",
+	dependencies: READS(),
+	parameters: Schema.Struct({ path: MemoryPath }),
+	failure: ToolFailure,
+	success: Schema.Struct({
+		/** The path asked about, normalized, so an answer can be matched back to the receipt. */
+		requested: MemoryPath,
+		/** Where the walk ended. What that MEANS is `stop_reason`'s, not this field's. */
+		path: MemoryPath,
+		/** Hops taken, equal to `steps.length`. A quantity, `0` when the path needed no walk. */
+		hops: Count,
+		steps: Schema.Array(Schema.Struct({
+			from: MemoryPath,
+			to: MemoryPath,
+			/**
+			* Which mechanism moved the memory, from the closed vocabulary the operation declares.
+			*
+			* Published as an enum rather than a string so a client can branch exhaustively: the two are
+			* different claims. `supersedes` is an authored `<link>` inside a file, which survives a
+			* rebuilt index; `archive_move` is a `git mv` recorded by the path itself.
+			*/
+			via: Schema.Literals(RESOLVE_STEP_VIA)
 		})),
-		edges: Count
+		/** Why the walk stopped, from the five values the operation declares. Only `live` is citable. */
+		stop_reason: Schema.Literals(RESOLVE_STOP_REASONS),
+		/** The title at `path`, or null when the index holds no row for it. */
+		title: Schema.NullOr(Schema.String),
+		/**
+		* The commit the INDEX describes, or null before the first rebuild and during one.
+		*
+		* This whole answer is a statement about that commit rather than about HEAD, since the index is a
+		* projection of git. `memory_status.index_fresh` says whether the two agree.
+		*/
+		indexed_commit: Schema.NullOr(Schema.String),
+		/**
+		* A `resources/read` URI pinning `path` at `indexed_commit`, or null when reading it would fail.
+		*
+		* Two conditions make it null, and both are the same rule: this field is a URI the same server
+		* answers. There is no commit to pin to before the first rebuild, and `unindexed` is the one
+		* `stop_reason` whose `path` the indexed commit does not hold — pinning it would publish a
+		* citation `resources/read` refuses with `ERR_PATH_NOT_FOUND`, which a receipt would store as a
+		* permanently dead link. The other four stop reasons all end on a path the index holds a row for.
+		*
+		* Composed by the server rather than by the client, because the URI's spelling belongs to the
+		* resource that routes it. A caller writing a receipt stores this string: the path half can be
+		* corrected, archived, or evicted afterwards and the URI still returns the bytes the receipt was
+		* written against.
+		*/
+		pinned_uri: Schema.NullOr(Schema.String)
 	})
 });
 const MemoryArchive = Tool.make("memory_archive", {
@@ -3326,13 +4275,15 @@ const MemoryReinforce = Tool.make("memory_reinforce", {
 	})
 });
 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.",
+	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. `facets` narrows by the corpus's own <dl> facets, each entry spelled name=value (the value may contain =, the name may not). THE COMPOSITION IS FIXED: values under the SAME name broaden, so [\"doc-type=runbook\",\"doc-type=guide\"] is either; DIFFERENT names narrow, so [\"doc-type=runbook\",\"tier=1\"] is both. This is the extension axis. memhtml's element and meta vocabularies are closed, so your own document kinds, states, and tiers belong in <dt>/<dd> pairs inside the article, and this is how you query them back. The match is on the facet's TEXT with no case folding, so write the halves you mean to query. The stored form is the element's text content, which the parser collapses whitespace runs in and trims, so <dd>runbook  rollback</dd> is stored and queried single-spaced. There is no numeric comparison and that is deliberate: a <data value> is indexed UNITLESS, because the unit lives in the prose beside it, so you own the unit and match the text you wrote.",
 	dependencies: READS(),
 	parameters: Schema.Struct({
 		memory_type: Optional(WritableType),
 		workspace: Optional(Schema.String),
 		tag: Optional(Schema.String),
 		entity: Optional(Schema.String),
+		/** `<dl>` facet predicates as `name=value` strings, composing exactly as `memory_search`'s do. */
+		facets: Optional(Schema.Array(Schema.String)),
 		para: Optional(Schema.Literals(PARA_BUCKETS)),
 		limit: Optional(Count),
 		cursor: Optional(Schema.String)
@@ -3397,7 +4348,7 @@ const MemoryStatus = Tool.make("memory_status", {
 	/**
 	* `Tool.EmptyParams`, not `Schema.Struct({})`.
 	*
-	* Probed on effect 4.0.0-beta.102: an empty `Schema.Struct` derives
+	* Probed on effect 4.0.0-rc.109: 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.
@@ -3423,7 +4374,8 @@ const MemoryStatus = Tool.make("memory_status", {
 	})
 });
 /**
-* The toolkit. Exactly fourteen: design.md §8's thirteen plus `memory_write_batch`.
+* The toolkit. Exactly fifteen: design.md §8's thirteen, plus `memory_write_batch` and
+* `memory_resolve`.
 *
 * 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,
@@ -3434,12 +4386,12 @@ const MemoryStatus = Tool.make("memory_status", {
 * 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);
+const MemhtmlToolkit = Toolkit.make(MemoryWrite, MemoryWriteBatch, MemoryRead, MemorySearch, MemoryRecall, MemoryCorrect, MemoryLink, MemoryNeighbors, MemoryResolve, 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.
+* Two lists would drift: a placeholder list that once said fifteen names and a toolkit that now
+* builds fourteen would leave a test asserting the list and proving nothing about the server.
 */
 const TOOL_NAMES = Object.keys(MemhtmlToolkit.tools);
 
@@ -3455,17 +4407,17 @@ const TOOL_NAMES = Object.keys(MemhtmlToolkit.tools);
 * 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.
+* **It has to be a `ToolFailure` and not an `AiError`.** `McpServer` catches an `AiError` FIRST and
+* rewrites it to a generic internal-error sentence unless its reason is `ToolParameterValidationError`
+* (effect 4.0.0-rc.109), so a typed failure delivered that way reaches 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 `ToolFailure` for every handler and `kit.toLayer` checks it, so a handler that
+* failed with a raw domain error is a compile error rather than a masked response. `failure.ts` is the
+* single place the wire failure is produced.
 */
 const handled = (effect) => effect.pipe(Effect.mapError(toToolFailure));
 /**
@@ -3494,7 +4446,7 @@ const metaRecord = (doc) => {
 * 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.
+* a present one, so the two vocabularies meet HERE, once, rather than at each of fifteen call sites.
 */
 const opt = (value) => value ?? void 0;
 /** Absent optional array as an empty one, so a handler never passes `undefined` downstream. */
@@ -3529,6 +4481,7 @@ const writeParamsOf = (op, article) => ({
 	articleHtml: article.articleHtml,
 	memoryType: op.memory_type,
 	path: opt(op.path),
+	strictPath: opt(op.strict_path),
 	workspace: opt(op.workspace),
 	tags: arr(op.tags),
 	entities: arr(op.entities),
@@ -3636,6 +4589,7 @@ const ToolHandlers = MemhtmlToolkit.toLayer({
 			articleHtml: article.articleHtml,
 			memoryType: params.memory_type,
 			path: opt(params.path),
+			strictPath: opt(params.strict_path),
 			workspace: opt(params.workspace),
 			tags: arr(params.tags),
 			entities: arr(params.entities),
@@ -3811,6 +4765,7 @@ const ToolHandlers = MemhtmlToolkit.toLayer({
 			workspace: opt(params.workspace),
 			tags: opt(params.tags),
 			entity: opt(params.entity),
+			facets: parseFacetFilters(arr(params.facets)),
 			includeArchived: opt(params.include_archived),
 			asOf: opt(params.as_of)
 		});
@@ -3906,11 +4861,52 @@ const ToolHandlers = MemhtmlToolkit.toLayer({
 		const result = yield* neighborsOf({
 			path: params.path,
 			depth: opt(params.depth),
-			rels: opt(params.rels)
+			rels: opt(params.rels),
+			limit: opt(params.limit)
 		});
+		/**
+		* Both truncation markers cross the boundary, and the rename is the only work here.
+		*
+		* The operation reports the clamped ceiling as `limit` and this surface publishes it as
+		* `node_limit`, because a tool response that spelled it `limit` would put the caller's ask and
+		* the walk's 10000-edge-row cap under one word. Dropping either marker would leave a clamped
+		* neighborhood indistinguishable from a complete one, which is the whole reason the operation
+		* counts them.
+		*/
 		return {
 			nodes: result.nodes,
-			edges: result.edges
+			edges: result.edges,
+			node_limit: result.limit,
+			dropped_node_count: result.nodesDropped,
+			scan_saturated: result.scanSaturated
+		};
+	})),
+	memory_resolve: (params) => handled(Effect.gen(function* () {
+		const result = yield* resolveMemory(params.path);
+		/**
+		* `pinned_uri` is composed HERE and nowhere else, from `pinnedUri`, the function the resource
+		* that routes that URI exports.
+		*
+		* The operation cannot build it: `@memhtml/cli` knows nothing about the MCP scheme, and a
+		* resolution is a fact about the corpus rather than about a transport. Composing it from
+		* literals in this file would be a second declaration of the published template — the
+		* consumer-side reimplementation of a producer's naming rule this repo has paid for.
+		*
+		* It is withheld in two cases and they are one rule: a URI this server would refuse is not a
+		* citation. There is no commit to pin to before the first rebuild, and `unindexed` is the one
+		* stop reason whose `path` the indexed commit does not hold, so pinning it would hand a client
+		* a receipt that reads `ERR_PATH_NOT_FOUND` forever. Every other stop reason ends on a path the
+		* index holds a row for.
+		*/
+		return {
+			requested: result.requested,
+			path: result.path,
+			hops: result.hops,
+			steps: result.steps,
+			stop_reason: result.stopReason,
+			title: result.title,
+			indexed_commit: result.indexedCommit,
+			pinned_uri: result.indexedCommit === null || result.stopReason === "unindexed" ? null : pinnedUri(result.indexedCommit, result.path)
 		};
 	})),
 	memory_archive: (params) => handled(Effect.gen(function* () {
@@ -3933,6 +4929,7 @@ const ToolHandlers = MemhtmlToolkit.toLayer({
 			workspace: opt(params.workspace),
 			tag: opt(params.tag),
 			entity: opt(params.entity),
+			facets: parseFacetFilters(arr(params.facets)),
 			para: opt(params.para),
 			limit: opt(params.limit),
 			cursor: opt(params.cursor)
@@ -4001,83 +4998,12 @@ const ToolHandlers = MemhtmlToolkit.toLayer({
 	}))
 });
 
-//#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.6.0";
+const SERVER_VERSION = "0.7.0";
 /**
-* The server as one layer: fourteen tools, two resources, over the CLI's own `AppLive`.
+* The server as one layer: fifteen tools, three 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
@@ -4091,8 +5017,8 @@ const SERVER_VERSION = "0.6.0";
 * **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
+* emit it. Verified against effect 4.0.0-rc.109 in the dependency's own declarations: `McpSchema`
+* DECLARES `instructions: optional(Schema.String)` on `InitializeResult`, 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.
 *