memhtml 0.1.0

package/migrations/0008_tasks.sql

@@ -0,0 +1,214 @@
+-- `task` becomes the tenth `memory_type`, `task` the fourth `edge_class`, and `files` gains the two
+-- columns a task carries. Recreate-and-copy, because SQLite cannot ALTER a CHECK constraint and both
+-- tables carry one. Every existing row passes the WIDENED CHECKs, so the copies are lossless.
+--
+-- ── The children are snapshotted, and that is the load-bearing part of this file ──────────────────
+--
+-- Probed 2026-08-12 on node 24.19.0: `DROP TABLE files` DELETES every row of every child table
+-- (`file_tags`, `file_entities`, `file_facets`, `file_citations`, `chunks`, and `embeddings` behind
+-- `chunks`) via `ON DELETE CASCADE`, including inside the one `immediate` transaction the migration
+-- runner wraps this file in, which does NOT protect them. A migration that merely copied `files` would
+-- therefore report success and silently destroy every embedding in the database: thousands of Bedrock
+-- calls for text that never changed, plus the whole edge set.
+--
+-- `PRAGMA foreign_keys = OFF` around the drop is no escape, and the probe above measured that too: the
+-- pragma is a NO-OP inside a transaction, exactly as SQLite documents it, so the cascade fires anyway
+-- and a file that relied on the pragma would be silent data loss with no error anywhere. (Outside a
+-- transaction the pragma does suppress the cascade, which is not where a migration runs.)
+-- The snapshot does not depend on foreign-key state at all: each child's rows are copied out, the
+-- cascade fires against an empty-of-consequence table, and the rows are copied back under the new
+-- parent. Verified after the fact: `PRAGMA foreign_key_check` is empty, `foreign_keys` is still ON,
+-- an orphan child insert is still refused, and `ON UPDATE CASCADE` still carries a chunk through an
+-- archive rename.
+--
+-- `files_fts` IS dropped explicitly. It is a separate virtual table, so `DROP TABLE files` does not
+-- take it, and an external-content FTS5 table left pointing at a dropped content table is a stale
+-- index that answers MATCH from rows the corpus no longer has. Its triggers need no drop. A trigger
+-- belongs to the table it is defined ON, so `DROP TABLE files` takes all three. Both are recreated
+-- from 0003_fts.sql's definitions at the end of this file, over the finished table.
+
+CREATE TABLE files_next (
+  path            TEXT PRIMARY KEY,
+  blob_sha        TEXT NOT NULL,
+  content_hash    TEXT NOT NULL,
+  -- Widened by exactly one value. `task` is a memory TYPE rather than a second axis: three
+  -- overlapping type vocabularies is what made the predecessor memory system's classification unanswerable, so a
+  -- task's different treatment is stated by the filters that read this column (default-excluded
+  -- from retrieval scope, skipped by every sleep phase) and never by a parallel `kind`.
+  memory_type     TEXT NOT NULL CHECK (memory_type IN (
+                    'episodic','semantic','procedural','agent_insight',
+                    'user_preference','error_pattern','verdict','precedent','arc','task')),
+  title           TEXT NOT NULL,
+  body_text       TEXT NOT NULL,
+  gist            TEXT NOT NULL DEFAULT '',
+  fts_text        TEXT NOT NULL DEFAULT '',
+  disclosure_text TEXT NOT NULL DEFAULT '',
+  para            TEXT NOT NULL CHECK (para IN ('projects','areas','resources','archive')),
+  workspace       TEXT,
+  confidence      REAL    NOT NULL DEFAULT 1.0 CHECK (confidence BETWEEN 0 AND 1),
+  importance      INTEGER NOT NULL DEFAULT 5 CHECK (importance BETWEEN 1 AND 10),
+  archived        INTEGER NOT NULL DEFAULT 0 CHECK (archived IN (0,1)),
+  origin_path     TEXT,
+  word_count      INTEGER NOT NULL DEFAULT 0,
+  created_at      TEXT NOT NULL,
+  updated_at      TEXT NOT NULL,
+  event_at        TEXT,
+  archived_at     TEXT,
+  valid_from      TEXT,
+  valid_until     TEXT,
+  reprieves       INTEGER NOT NULL DEFAULT 0 CHECK (reprieves >= 0),
+  needs_revision  INTEGER NOT NULL DEFAULT 0 CHECK (needs_revision IN (0,1)),
+  author          TEXT NOT NULL DEFAULT 'agent',
+  session_id      TEXT,
+  prompt_id       TEXT,
+  turn_uuid       TEXT,
+  indexed_at      TEXT NOT NULL,
+  -- A task's lifecycle position, from `memhtml-task-status`. NULL on every non-task, which the CHECK
+  -- admits: an IN-list CHECK passes NULL (probed), so one column serves both cases without a
+  -- type-conditional constraint the ten-value vocabulary would have to restate.
+  --
+  -- A SEPARATE axis from `archived`. `done` is stamped here AND the file is archived by the same
+  -- `git mv` every eviction uses, so every path that switches on active/archived keeps its meaning.
+  task_status     TEXT CHECK (task_status IN ('todo','doing','blocked','done')),
+  -- When a task is due, from `memhtml-due`. An ISO date or datetime, compared and ordered AS A STRING
+  -- exactly as `event_at` is. @memhtml/html refuses a value that does not sort alongside the others,
+  -- which is what makes `due_at < ?` an overdue query rather than a per-row parse.
+  due_at          TEXT
+);
+
+INSERT INTO files_next
+  SELECT path, blob_sha, content_hash, memory_type, title, body_text, gist, fts_text,
+         disclosure_text, para, workspace, confidence, importance, archived, origin_path,
+         word_count, created_at, updated_at, event_at, archived_at, valid_from, valid_until,
+         reprieves, needs_revision, author, session_id, prompt_id, turn_uuid, indexed_at,
+         NULL, NULL
+  FROM files;
+
+CREATE TABLE file_tags_snap      AS SELECT * FROM file_tags;
+CREATE TABLE file_entities_snap  AS SELECT * FROM file_entities;
+CREATE TABLE file_facets_snap    AS SELECT * FROM file_facets;
+CREATE TABLE file_citations_snap AS SELECT * FROM file_citations;
+CREATE TABLE chunks_snap         AS SELECT * FROM chunks;
+-- `embeddings` hangs off `chunks`, not off `files`, so it is lost one cascade further down. The
+-- vector BLOB survives `CREATE TABLE … AS SELECT` at full length (probed: 8 bytes in, 8 out).
+CREATE TABLE embeddings_snap     AS SELECT * FROM embeddings;
+
+DROP TABLE files_fts;
+DROP TABLE files;
+ALTER TABLE files_next RENAME TO files;
+
+-- Parent first, then `chunks`, then `embeddings` behind it: the restore is FK-valid at every step
+-- rather than relying on the constraints being off.
+INSERT INTO file_tags      SELECT * FROM file_tags_snap;
+INSERT INTO file_entities  SELECT * FROM file_entities_snap;
+INSERT INTO file_facets    SELECT * FROM file_facets_snap;
+INSERT INTO file_citations SELECT * FROM file_citations_snap;
+INSERT INTO chunks         SELECT * FROM chunks_snap;
+INSERT INTO embeddings     SELECT * FROM embeddings_snap;
+
+DROP TABLE file_tags_snap;
+DROP TABLE file_entities_snap;
+DROP TABLE file_facets_snap;
+DROP TABLE file_citations_snap;
+DROP TABLE chunks_snap;
+DROP TABLE embeddings_snap;
+
+-- Every index the old `files` carried, recreated. A dropped table takes its indexes with it, so an
+-- index missing from this list is an index the database silently no longer has.
+--
+-- The dedup index gains `AND memory_type <> 'task'`. Two open tasks with identical bodies are
+-- legitimately distinct work items ("review the deploy runbook" twice is two things to do), while
+-- two identical active MEMORIES are one fact stored twice, which is what this index exists to
+-- refuse. `dedupeLookup` (`traces-persist.ts` `activePathForHash`) carries the same exclusion, so
+-- the write path's question and the database's answer agree by construction rather than by
+-- discipline. Probed: two identical-hash open tasks are admitted, two identical-hash memories are
+-- still refused, and a memory may share a hash with an open task without colliding.
+CREATE UNIQUE INDEX files_content_hash_active ON files (content_hash)
+  WHERE archived = 0 AND memory_type <> 'task';
+CREATE INDEX files_type_active   ON files (memory_type) WHERE archived = 0;
+CREATE INDEX files_workspace     ON files (workspace)   WHERE archived = 0;
+CREATE INDEX files_para          ON files (para);
+CREATE INDEX files_updated       ON files (updated_at)  WHERE archived = 0;
+CREATE INDEX files_event         ON files (event_at)    WHERE event_at IS NOT NULL;
+CREATE INDEX files_session       ON files (session_id)  WHERE session_id IS NOT NULL;
+CREATE INDEX files_ttl           ON files (valid_until) WHERE valid_until IS NOT NULL AND archived = 0;
+CREATE INDEX files_blob          ON files (blob_sha);
+
+-- The task list's own index. `memhtml task list` reads by status over live tasks and nothing else, and
+-- the partial predicate keeps the index the size of the open work rather than of the corpus.
+CREATE INDEX files_task_status ON files (task_status)
+  WHERE memory_type = 'task' AND archived = 0;
+
+-- The lexical index and its triggers, rebuilt over the finished table. These must stay identical to
+-- 0003_fts.sql: two definitions of one index that drifted would make a fresh store and a migrated one
+-- rank differently, which no test comparing a store to itself would catch.
+CREATE VIRTUAL TABLE files_fts USING fts5(
+  fts_text,
+  content='files',
+  content_rowid='rowid'
+);
+
+-- The content table already holds every row, so the index is built in one pass here rather than
+-- accumulated through the triggers.
+INSERT INTO files_fts(files_fts) VALUES ('rebuild');
+
+CREATE TRIGGER files_fts_insert AFTER INSERT ON files BEGIN
+  INSERT INTO files_fts(rowid, fts_text) VALUES (new.rowid, new.fts_text);
+END;
+
+CREATE TRIGGER files_fts_delete AFTER DELETE ON files BEGIN
+  INSERT INTO files_fts(files_fts, rowid, fts_text) VALUES ('delete', old.rowid, old.fts_text);
+END;
+
+CREATE TRIGGER files_fts_update AFTER UPDATE OF fts_text ON files BEGIN
+  INSERT INTO files_fts(files_fts, rowid, fts_text) VALUES ('delete', old.rowid, old.fts_text);
+  INSERT INTO files_fts(rowid, fts_text) VALUES (new.rowid, new.fts_text);
+END;
+
+-- ── edges: the fourth class ──────────────────────────────────────────────────────────────────────
+--
+-- Nothing references `edges`, so a plain recreate-and-copy loses nothing. Its rows all carry one of
+-- the three existing classes and pass the widened CHECK unchanged.
+
+CREATE TABLE edges_next (
+  src_path     TEXT NOT NULL,
+  rel          TEXT NOT NULL,
+  dst_path     TEXT NOT NULL,
+  -- The four classes do not mix. A person or TASK edge is structurally incapable of entering
+  -- PageRank, MMR, or the retention bridge count, because every memory-graph query filters on this
+  -- column and the CHECKs below refuse a rel from another class. Task topology is working state: a
+  -- `blocks` edge reaching PageRank would let an agent's to-do list reweight the retention of its
+  -- knowledge.
+  edge_class   TEXT NOT NULL DEFAULT 'memory'
+               CHECK (edge_class IN ('memory','person','provenance','task')),
+  derived      INTEGER NOT NULL DEFAULT 0 CHECK (derived IN (0,1)),
+  strength     REAL NOT NULL DEFAULT 1.0 CHECK (strength BETWEEN 0 AND 1),
+  provenance   TEXT NOT NULL DEFAULT 'authored'
+               CHECK (provenance IN ('authored','sleep','import')),
+  sleep_run    TEXT,
+  src_hash     TEXT,
+  dst_hash     TEXT,
+  created_at   TEXT NOT NULL,
+  PRIMARY KEY (src_path, rel, dst_path),
+  CHECK (src_path <> dst_path),
+  CHECK (edge_class <> 'memory' OR rel IN (
+    'supersedes','contradicts','caused_by','leads_to','part_of',
+    'relates_to','example_of','supports','laterally_related')),
+  CHECK (edge_class <> 'person'  OR rel IN ('about_person','authored_by')),
+  CHECK (edge_class <> 'provenance' OR rel IN ('from_session')),
+  CHECK (edge_class <> 'task' OR rel IN ('blocks','subtask_of')),
+  CHECK (derived = 0 OR provenance = 'sleep')
+);
+
+INSERT INTO edges_next
+  SELECT src_path, rel, dst_path, edge_class, derived, strength, provenance, sleep_run,
+         src_hash, dst_hash, created_at
+  FROM edges;
+
+DROP TABLE edges;
+ALTER TABLE edges_next RENAME TO edges;
+
+CREATE INDEX edges_src ON edges (src_path, edge_class) WHERE derived = 0;
+CREATE INDEX edges_dst ON edges (dst_path, edge_class) WHERE derived = 0;
+CREATE INDEX edges_rel ON edges (rel, edge_class);
+CREATE INDEX edges_derived ON edges (derived, rel);

package/migrations/0009_frame_key.sql

@@ -0,0 +1,54 @@
+-- `files` gains `frame_key`: the claim's SLOT, derived from its gist at projection time by
+-- `@memhtml/domain`'s `frameKeyOf`. Two active memories sharing a frame key state the same relation with
+-- (possibly) different values, which is what makes a contradiction findable by one indexed lookup
+-- instead of an O(corpus) scan or an LLM pass over every pair.
+--
+-- ── ADDITIVE, unlike 0008 ────────────────────────────────────────────────────────────────────────
+--
+-- `ALTER TABLE … ADD COLUMN` plus one index, and deliberately NOT the recreate-and-copy 0008 used.
+-- That pattern was forced by a CHECK-constraint edit (SQLite cannot ALTER a CHECK) and it carried
+-- real risk: `DROP TABLE files` cascades to every child down to `embeddings`, so 0008 had to snapshot
+-- and restore six tables to avoid re-paying Bedrock for the whole corpus. A nullable column with no
+-- constraint needs none of that. Copying 0008's shape here would take on all of its danger to buy
+-- nothing, and this file must not be read as evidence that recreate-and-copy is the house style.
+--
+-- ── NOT UNIQUE, and that is the design, not an omission ──────────────────────────────────────────
+--
+-- Multiple ACTIVE rows may share a frame key, today and permanently. Two memories claiming different
+-- values for one slot are exactly what the conflict assist exists to REPORT, so a unique index would
+-- refuse the write that produces the signal. The corpus would stay clean by never recording the
+-- disagreement, and the assist would have nothing to find. The eval's gold on MAB Conflict_Resolution
+-- IS the contradiction pair. The assist reports; it never blocks.
+--
+-- ── The index predicate mirrors the lookup's ─────────────────────────────────────────────────────
+--
+-- `archived = 0 AND memory_type <> 'task' AND frame_key IS NOT NULL`, matching `activeFramesFor`
+-- (`traces-persist.ts`) clause for clause, on the same reasoning `files_content_hash_active` and
+-- `activePathForHash` share: the query is the question and the index is the answer, so a predicate on
+-- one and not the other is a lookup that scans instead of seeks, silently and only under load.
+--
+--   * `archived = 0`: an evicted memory is not a live claim, so it cannot contradict one.
+--   * `memory_type <> 'task'`: the same carve-out `files_content_hash_active` carries. Two open
+--     tasks phrased alike are two real work items ("the owner of the deploy runbook is Priya" as a
+--     to-do, twice), not a contradiction to report.
+--   * `frame_key IS NOT NULL`: most gists have no frame shape (the guards fail closed), so this
+--     keeps the index the size of the KEYED rows rather than of the corpus.
+--
+-- ── Existing rows arrive NULL, and self-heal ─────────────────────────────────────────────────────
+--
+-- `ADD COLUMN` gives every existing row NULL, and this migration does NOT backfill. It cannot: the
+-- key derives from the gist through TypeScript, and SQL cannot call `frameKeyOf`. A SQL
+-- reimplementation of the regex would be a second copy of a measured heuristic, free to drift from
+-- the one the eval validated.
+--
+-- No backfill is needed, because `index.db` is a disposable projection of the git tree. `memhtml index
+-- rebuild` recomputes every row from the files and every `frame_key` lands populated; short of that,
+-- each file's next update rewrites its own row through the projection's upsert. So the column fills
+-- in on the next rebuild or the next touch, and until then a NULL simply means "not yet keyed". The
+-- assist finds fewer conflicts, never wrong ones, because the lookup requires a non-NULL match on
+-- both sides.
+
+ALTER TABLE files ADD COLUMN frame_key TEXT;
+
+CREATE INDEX files_frame_key_active ON files (frame_key)
+  WHERE archived = 0 AND memory_type <> 'task' AND frame_key IS NOT NULL;

package/migrations/0010_trace_consolidations.sql

@@ -0,0 +1,45 @@
+-- The trace-consolidation watermark: which sessions the sleep cycle has already distilled.
+--
+-- ── Run state, not an index projection ───────────────────────────────────────────────────────────
+--
+-- The same category as `sleep_runs`/`sleep_phases` (0006), and NOT the category of `files` or
+-- `chunks`. A projection row is a pure function of the git tree and is deleted and recomputed by
+-- every `memhtml index rebuild`; this row records that a MODEL CALL happened, which no tree can restate.
+--
+-- It therefore survives a rebuild, and by construction rather than by exemption: `rebuild` empties
+-- exactly `MEMORY_TABLES` (`packages/index/src/schema-const.ts:48-57`, applied at
+-- `packages/index/src/indexer.ts:408`) and never drops or recreates the database file, so a table
+-- absent from that list is untouched. Verified the same way `sleep_runs` is.
+--
+-- If the file itself is ever deleted, every watermark goes with it and the next cycle reconsolidates
+-- the sessions it can still see. That is wasteful (it re-pays Opus for transcripts already read)
+-- and it is SAFE, which is the ordering that matters: the phase writes memories through the same
+-- reviewable-commit discipline as every other sleep mutation, so a duplicate candidate is a commit a
+-- reviewer declines, never a corruption. Nothing here is load-bearing for correctness.
+--
+-- ── One row per session, and no foreign key ──────────────────────────────────────────────────────
+--
+-- `session_id` is the primary key because "has this session been consolidated" is a per-session
+-- question with one answer; a second consolidation of one session overwrites its row and moves
+-- `run_id`, which is what makes a reconsolidation after a lost database file idempotent in shape.
+--
+-- No `REFERENCES traces (session_id)`, for the reason `memory_session_links` states in 0005: the
+-- trace plane is a rebuildable index over `~/.claude/projects`, so a session's `traces` row can be
+-- rebuilt away (its transcript rotated, its directory pruned) while the fact that the cycle already
+-- read it stays true. A foreign key would delete the watermark and invite a re-read of a file that
+-- may no longer exist.
+
+CREATE TABLE trace_consolidations (
+  session_id      TEXT PRIMARY KEY,
+  -- The sleep run that distilled it, e.g. `sleep/2026-08-08`. Reporting and provenance only:
+  -- nothing reads this to decide anything, the same posture 0006's tables carry.
+  run_id          TEXT NOT NULL,
+  -- The run's own instant, not a clock read at insert time: a phase derives every stamp from the
+  -- injected run date (`packages/sleep/src/env.ts:60-67`), so two runs of one date agree here.
+  consolidated_at TEXT NOT NULL
+);
+
+-- The unconsolidated-session query is an anti-join FROM `traces`, so it seeks this table by its
+-- primary key and needs no second index. `consolidated_at` is ordered only in a report, over a table
+-- whose row count is bounded by the number of sessions ever consolidated.
+CREATE INDEX trace_consolidations_run ON trace_consolidations (run_id);

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "memhtml",
+  "version": "0.1.0",
+  "description": "An agent's long-term memory: one fact per semantic HTML file in git, four-arm retrieval, and a nightly sleep cycle.",
+  "keywords": [
+    "memory",
+    "agent",
+    "mcp",
+    "retrieval",
+    "sqlite",
+    "git",
+    "semantic-html",
+    "cli"
+  ],
+  "homepage": "https://github.com/memhtml/memhtml",
+  "bugs": {
+    "url": "https://github.com/memhtml/memhtml/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/memhtml/memhtml.git"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "memhtml": "./dist/memhtml.mjs",
+    "memhtml-mcp": "./dist/memhtml-mcp.mjs"
+  },
+  "files": [
+    "dist",
+    "migrations",
+    "state-migrations",
+    "guest",
+    "agent",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@ai-sdk/amazon-bedrock": "5.0.53",
+    "@aws-sdk/client-bedrock-runtime": "3.1108.0",
+    "@aws/bedrock-token-generator": "1.1.0",
+    "@effect/platform-node": "4.0.0-beta.107",
+    "ai": "7.0.61",
+    "effect": "4.0.0-beta.107",
+    "eve": "0.33.0",
+    "highlight.js": "11.11.2",
+    "just-bash": "3.2.0",
+    "node-html-parser": "9.0.1",
+    "parse5": "8.0.1",
+    "zod": "4.4.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agent-build.ts

@@ -0,0 +1,280 @@
+import { spawn } from "node:child_process"
+import { existsSync } from "node:fs"
+import { cp, mkdir, readdir, readFile, symlink, writeFile } from "node:fs/promises"
+import { createRequire } from "node:module"
+import { homedir } from "node:os"
+import { dirname, join, resolve } from "node:path"
+import { Effect } from "effect"
+
+import { ConsolidatorUnavailable } from "./contract.js"
+
+/**
+ * Where `eve build` may run, which is not always where this package is installed.
+ *
+ * eve is filesystem-first: `eve build` compiles `agent/` — and the `../../src/*.ts` it reaches — into
+ * `.output/`, and `eve start` serves that directory. In a checkout that is `pnpm build:agent` writing
+ * into the package itself, and it works.
+ *
+ * From an INSTALLED package it does not, and the failure is worse than an error: the build succeeds and
+ * the server it produces cannot boot. Measured 2026-08-17 against an npm-installed tarball —
+ * `eve build` exited 0, then `eve start` exited 13 on `Detected unsettled top-level await ... await
+ * workflowWorld.start?.()`. The discriminator is the tree's LOCATION, not its contents: nitro
+ * externalizes any module resolved from inside `node_modules`, so an installed `@memhtml/consolidator`
+ * became a traced lib chunk (`server/index.mjs` 17.3 kB beside a 4.73 MB `_libs/@memhtml/…` chunk),
+ * while the same sources built from a checkout were inlined (`index.mjs` 317 kB) and answered
+ * `/eve/v1/health` with `{"ok":true,"status":"ready"}` in ~2s.
+ *
+ * So the agent tree is COPIED out to a cache directory and built there, where nothing above it is
+ * named `node_modules` and nitro inlines it. Shipping a prebuilt `.output/` in the tarball is the other
+ * candidate and is refused: the build traces native binaries into it
+ * (`server/node_modules/node-liblzma/build/Release/node_lzma.node`) and eve says so itself — "Ensure
+ * your production environment matches the builder OS and architecture (linux-x64)". A published
+ * artifact cannot carry one platform's binaries.
+ */
+
+/**
+ * eve's CLI entry point, or `null` when eve does not resolve from here.
+ *
+ * Spawned as `process.execPath <path>` rather than through a package manager, because a consumer who
+ * installed this package has whatever manager they used and need not have any particular one on PATH.
+ * `apps/cli/src/serve.ts` spawns the MCP server the same way, for the same reason.
+ *
+ * Resolution goes through the MANIFEST, not the bin. `resolve("eve/bin/eve.js")` raises
+ * `ERR_PACKAGE_PATH_NOT_EXPORTED`: eve's `exports` map declares no `./bin/*` subpath, so node refuses
+ * the deep path even though the file is there (probed against eve 0.33.0). `./package.json` IS
+ * exported, and the `bin` field beside it names the entry point.
+ */
+export const eveBinPath = (): string | null => {
+  const require = createRequire(import.meta.url)
+  let manifestPath: string
+  try {
+    manifestPath = require.resolve("eve/package.json")
+  } catch {
+    return null
+  }
+  const { bin } = require(manifestPath) as { readonly bin?: Record<string, string> | string }
+  const entry = typeof bin === "string" ? bin : bin?.eve
+  return entry === undefined ? null : resolve(dirname(manifestPath), entry)
+}
+
+/** Per-version, so an upgrade builds fresh instead of serving the previous release's output. */
+const cacheRootFor = (version: string): string =>
+  join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "memhtml", "eve", version)
+
+/** A bare specifier's package name: two segments when scoped, one otherwise. */
+const packageOf = (specifier: string): string => {
+  const parts = specifier.split("/")
+  return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : (parts[0] ?? specifier)
+}
+
+/**
+ * Every package the staged tree imports, read from the tree rather than from a manifest.
+ *
+ * A manifest looks like the obvious source and is the wrong one twice over. The published package is
+ * assembled with its `@memhtml/*` edges resolved as siblings and its `dependencies` field deliberately
+ * empty — declaring them inside a bundled manifest makes npm create phantom empty directories in the
+ * vendored subtree, which poisons resolution for every sibling (probed 2026-08-17: an empty
+ * `memhtml/node_modules/effect` made `import "effect"` fail from every vendored package). And the
+ * agent tree's real requirement is what it IMPORTS, which is a subset a manifest cannot narrow to.
+ *
+ * So the specifiers are read off the files eve is about to compile. Relative imports resolve inside the
+ * staged tree and `node:` builtins need nothing, so neither is linked.
+ */
+const importedPackages = async (roots: ReadonlyArray<string>): Promise<ReadonlyArray<string>> => {
+  const found = new Set<string>()
+  const pattern = /(?:from|import|require)\s*\(?\s*["']([^"']+)["']/g
+  for (const root of roots) {
+    for (const file of await sourceFiles(root)) {
+      const text = await readFile(file, "utf8")
+      for (const [, specifier] of text.matchAll(pattern)) {
+        if (specifier === undefined) continue
+        if (specifier.startsWith(".") || specifier.startsWith("/")) continue
+        if (specifier.startsWith("node:")) continue
+        found.add(packageOf(specifier))
+      }
+    }
+  }
+  return [...found].sort()
+}
+
+/** Every `.ts` file under a directory, at any depth. */
+const sourceFiles = async (root: string): Promise<ReadonlyArray<string>> => {
+  if (!existsSync(root)) return []
+  const out: string[] = []
+  for (const entry of await readdir(root, { withFileTypes: true, recursive: true })) {
+    if (entry.isFile() && entry.name.endsWith(".ts")) out.push(join(entry.parentPath, entry.name))
+  }
+  return out
+}
+
+const packageVersion = async (packageRoot: string): Promise<string> => {
+  const manifest = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8")) as {
+    readonly version?: string
+  }
+  return manifest.version ?? "0.0.0"
+}
+
+/**
+ * Where a dependency's directory actually is, found the way node finds it.
+ *
+ * `require.resolve("<name>/package.json")` is the obvious route and is not enough: an `exports` map
+ * that does not list `./package.json` makes node refuse the subpath, and two of this package's own
+ * dependencies are like that — `@memhtml/contracts` and `just-bash` both answer
+ * `ERR_PACKAGE_PATH_NOT_EXPORTED` (probed 2026-08-17). Walking the ancestors' `node_modules` asks the
+ * filesystem instead of the resolver, so an exports map cannot hide a directory that is plainly there.
+ *
+ * The walk covers every layout this ships into: pnpm's per-package symlink farm, npm's hoisted
+ * top-level tree, and the vendored single-package tarball, where `@memhtml/*` sit one `node_modules`
+ * in and the externals one further up.
+ */
+const dependencyDir = (fromDir: string, name: string): string | null => {
+  let at = fromDir
+  for (;;) {
+    const candidate = join(at, "node_modules", name)
+    if (existsSync(join(candidate, "package.json"))) return candidate
+    const up = dirname(at)
+    if (up === at) return null
+    at = up
+  }
+}
+
+/**
+ * Link every package the staged tree imports into the cache directory.
+ *
+ * A cache directory under `~/.cache` has no ancestor holding this package's dependencies — which is
+ * the entire point of building outside `node_modules` — so node's upward walk from there finds nothing.
+ * One symlink per imported package reproduces the module graph the installed package already has,
+ * resolved from `packageRoot` because that is where the real tree is.
+ */
+const linkDependencies = async (input: {
+  readonly packageRoot: string
+  readonly cacheRoot: string
+}): Promise<void> => {
+  const { packageRoot, cacheRoot } = input
+  const names = await importedPackages([join(cacheRoot, "agent"), join(cacheRoot, "src")])
+  for (const name of names) {
+    const from = dependencyDir(packageRoot, name)
+    // A package that is not on disk is the build's problem to report, not this step's: eve names the
+    // unresolved import, which is a better message than anything guessable here.
+    if (from === null) continue
+    const to = join(cacheRoot, "node_modules", name)
+    if (existsSync(to)) continue
+    await mkdir(dirname(to), { recursive: true })
+    await symlink(from, to, "dir")
+  }
+}
+
+/**
+ * Copy the buildable tree into `cacheRoot`, ready for `eve build`.
+ *
+ * Exported because this is the half a reader can get subtly wrong and the half that needs no 17 MB
+ * build to check: `agent/` reaches `../../src/*.js`, so the two directories travel TOGETHER and at
+ * their original depth. Flattening them, or staging `agent/` alone, produces the
+ * `UNRESOLVED_IMPORT` that a missing `src/` in the tarball already produced once.
+ */
+export const stageAgentTree = async (input: {
+  readonly packageRoot: string
+  readonly cacheRoot: string
+  readonly version: string
+}): Promise<void> => {
+  const { packageRoot, cacheRoot, version } = input
+  await mkdir(cacheRoot, { recursive: true })
+  await cp(join(packageRoot, "agent"), join(cacheRoot, "agent"), { recursive: true })
+  await cp(join(packageRoot, "src"), join(cacheRoot, "src"), { recursive: true })
+  await writeFile(
+    join(cacheRoot, "package.json"),
+    `${JSON.stringify(
+      { name: "memhtml-consolidator-agent", version, private: true, type: "module" },
+      null,
+      2
+    )}\n`
+  )
+  await linkDependencies({ packageRoot, cacheRoot })
+}
+
+const runEveBuild = (input: {
+  readonly eveBin: string
+  readonly cwd: string
+}): Effect.Effect<void, ConsolidatorUnavailable> =>
+  Effect.callback<void, ConsolidatorUnavailable>((resume) => {
+    const child = spawn(process.execPath, [input.eveBin, "build"], {
+      cwd: input.cwd,
+      stdio: ["ignore", "ignore", "pipe"]
+    })
+    let stderr = ""
+    child.stderr.setEncoding("utf8")
+    child.stderr.on("data", (chunk: string) => {
+      stderr += chunk
+    })
+    child.once("error", (cause) => {
+      resume(
+        Effect.fail(
+          ConsolidatorUnavailable.make({ reason: `could not spawn eve build: ${String(cause)}` })
+        )
+      )
+    })
+    child.once("exit", (code) => {
+      resume(
+        code === 0
+          ? Effect.void
+          : Effect.fail(
+              ConsolidatorUnavailable.make({
+                reason: `eve build exited with code ${String(code)} in ${input.cwd}. ${stderr.slice(-400)}`
+              })
+            )
+      )
+    })
+    return Effect.sync(() => {
+      child.kill("SIGKILL")
+    })
+  })
+
+/**
+ * The directory `eve start` will be run in, building the agent first when nothing has.
+ *
+ * Order is deliberate. An explicit `appRoot` is an operator's choice and is never second-guessed. A
+ * package that already holds `.output/` is a checkout where `build:agent` has run, and reusing it keeps
+ * development behaviour byte-identical. Only the remaining case — an installed package with no output —
+ * materializes the cache directory, and it costs one ~17 MB build per version rather than one per run.
+ */
+export const resolveAgentAppRoot = (input: {
+  readonly packageRoot: string
+  readonly configured?: string | undefined
+  readonly eveBin: string
+}): Effect.Effect<string, ConsolidatorUnavailable> =>
+  Effect.gen(function* () {
+    const { packageRoot, configured, eveBin } = input
+    if (configured !== undefined) return configured
+    if (existsSync(join(packageRoot, ".output"))) return packageRoot
+
+    const version = yield* Effect.tryPromise({
+      try: () => packageVersion(packageRoot),
+      catch: (cause) =>
+        ConsolidatorUnavailable.make({
+          reason: `could not read the consolidator's version: ${String(cause)}`
+        })
+    })
+    const cacheRoot = cacheRootFor(version)
+    if (existsSync(join(cacheRoot, ".output"))) return cacheRoot
+
+    yield* Effect.logInfo(`building the consolidator agent into ${cacheRoot} (once per version)`)
+    yield* Effect.tryPromise({
+      try: () => stageAgentTree({ packageRoot, cacheRoot, version }),
+      catch: (cause) =>
+        ConsolidatorUnavailable.make({
+          reason: `could not stage the consolidator agent in ${cacheRoot}: ${String(cause)}`
+        })
+    })
+
+    yield* runEveBuild({ eveBin, cwd: cacheRoot })
+
+    if (!existsSync(join(cacheRoot, ".output"))) {
+      return yield* Effect.fail(
+        ConsolidatorUnavailable.make({ reason: `eve build wrote no .output/ in ${cacheRoot}` })
+      )
+    }
+    return cacheRoot
+  })
+
+/** Exported for the tests that assert the location, which is the part a reader can get wrong. */
+export const agentCacheRootFor = (version: string): string => resolve(cacheRootFor(version))