simt-dev 0.7.0 → 0.8.0

package/src/ledger/index.mjs

@@ -6,11 +6,9 @@
 // no longer proves anything about what is on disk now.
 
 import { createHash } from 'node:crypto';
-import { execFile } from 'node:child_process';
-import { appendFile, mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { appendFile, copyFile, mkdir, mkdtemp, open, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { promisify } from 'node:util';
+import { join, resolve } from 'node:path';
 
 import {
   errorSignature,
@@ -19,11 +17,11 @@ import {
   recordFailThenFix,
 } from '../memory/lessons.mjs';
 import { TREE_EXCLUDES, localRel, readStateFile } from '../state.mjs';
+import { appendEvent } from '../state/events.mjs';
+import { LEDGER_FILE_LEGACY, LEDGER_FILE_REL } from '../name.mjs';
+import { git, gitText } from '../sys/git.mjs';
 
-const exec = promisify(execFile);
-
-export const LEDGER_FILE = localRel('ledger.jsonl');
-const LEDGER_FILE_LEGACY = '.simt/ledger.jsonl';
+export const LEDGER_FILE = localRel(LEDGER_FILE_REL);
 
 /** Phrases that claim a run happened. `unverified` and `not verified` are removed
  *  first, because both contain the word and neither is a claim. Trailers
@@ -33,6 +31,33 @@ const CLAIM =
   /\btests?\s+pass(?:ed|ing)?\b|\btest\s+suite\s+(?:is\s+)?green\b|\bsuite\s+is\s+green\b|\bnpm\s+test\s+pass(?:es|ed)?\b|\bverified\b/i;
 const TRAILER = /^(signed-off-by|co-authored-by|reviewed-by|acked-by|tested-by|fixes|closes)\s*:/i;
 
+/**
+ * Copy the repository's real index into a private one, and answer its path or null.
+ *
+ * The private index exists so `git add -A` cannot stage the author's work. Building it from
+ * nothing meant every path was hashed on every gate run, commit-msg check, `evidence` call
+ * and `pr-body`: on a 20k-file tree that is the whole cost of the command (Q75). Seeding it
+ * from the index git already maintains turns the hash into a no-op for every unchanged
+ * path, and the `add -A` afterwards only has the worktree diff left to do.
+ *
+ * A repository with no index yet (a fresh `git init`) is not an error: there is nothing to
+ * copy, and the add builds it from empty exactly as before.
+ *
+ * @param {string} root
+ * @param {string} target the private index file to populate
+ * @returns {Promise<string|null>} the source index, or null when there is none
+ */
+export async function seedIndex(root, target) {
+  try {
+    const stdout = await gitText(root, ['rev-parse', '--git-path', 'index']);
+    const from = resolve(root, stdout ?? '');
+    await copyFile(from, target);
+    return from;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The tree of everything in the worktree, without staging any of it.
  *
@@ -44,19 +69,46 @@ export async function treeId(root) {
   const index = join(dir, 'index');
   const env = { ...process.env, GIT_INDEX_FILE: index };
   try {
+    // Seed before the add: the add then only hashes what actually changed (Q75).
+    await seedIndex(root, index);
     // Machine-local state is a record of the tree, so it cannot be part of the
     // tree it names. `git add -A` would take it once the file exists, and the
     // line would prove a tree that stopped existing when the line was written
     // (review 0003 Q19).
-    const excludes = TREE_EXCLUDES.map((p) => `:(exclude)${p}`);
-    await exec('git', ['add', '-A', '--', '.', ...excludes], { cwd: root, env });
-    const { stdout } = await exec('git', ['write-tree'], { cwd: root, env });
-    return stdout.trim();
+    //
+    // Where .gitignore already keeps a path out of the index, the pathspec
+    // would name an ignored path, and `git add` refuses it ("use -f") - and -f
+    // would force the very state back into the tree. The excludes therefore
+    // carry only the paths git does not already ignore.
+    const ignored = await ignoredSet(root, TREE_EXCLUDES);
+    const excludes = TREE_EXCLUDES.filter((p) => !ignored.has(p)).map((p) => `:(exclude)${p}`);
+    await git(root, ['add', '-A', '--', '.', ...excludes], { env });
+    return await gitText(root, ['write-tree'], { env });
   } finally {
     await rm(dir, { recursive: true, force: true });
   }
 }
 
+/**
+ * The paths git already ignores, so the exclude pathspecs do not name them.
+ * A repository with no .gitignore ignores nothing, and every exclude ships
+ * exactly as before.
+ *
+ * @param {string} root
+ * @param {string[]} paths
+ * @returns {Promise<Set<string>>}
+ */
+async function ignoredSet(root, paths) {
+  try {
+    const stdout = await git(root, ['check-ignore', ...paths]);
+    return new Set(String(stdout).split('\n').filter(Boolean));
+  } catch {
+    // `check-ignore` exits 1 when nothing is ignored - the common case, not an
+    // error. Failing to the full exclude list is the pre-filter behaviour.
+    return new Set();
+  }
+}
+
 /**
  * Append one run. The output itself is not stored: the digest is enough to notice a
  * change, and a ledger that kept logs would keep whatever the command printed.
@@ -66,8 +118,7 @@ export async function treeId(root) {
  *  Null when git cannot answer; the caller then falls back to the worktree tree. */
 export async function indexTreeId(root) {
   try {
-    const { stdout } = await exec('git', ['write-tree'], { cwd: root });
-    const tree = String(stdout ?? '').trim();
+    const tree = await gitText(root, ['write-tree']);
     return /^[0-9a-f]{40}$/.test(tree) ? tree : null;
   } catch {
     return null;
@@ -87,8 +138,10 @@ export async function recordRun(root, { cmd, exit, ms, output, gate = null, kind
     ...(typeof gate === 'string' ? { gate } : {}),
     ...(typeof kind === 'string' ? { kind } : {}),
     cmd,
+    command: cmd,
     exit,
     ms,
+    wallMs: ms,
     outputDigest: `sha256-${createHash('sha256').update(output).digest('hex')}`,
     summary: summarise(output, exit),
     ...(exit !== 0
@@ -100,6 +153,14 @@ export async function recordRun(root, { cmd, exit, ms, output, gate = null, kind
   };
   await mkdir(join(root, '.simt', 'local'), { recursive: true });
   await appendFile(join(root, LEDGER_FILE), `${JSON.stringify(line)}\n`);
+  // The same record in the log every other store writes to (Q73): a tailing consumer has
+  // one file to follow, and a ledger line lost to rotation is still recoverable here.
+  await appendEvent(root, {
+    kind: 'gate.finished',
+    tree: worktreeTree,
+    subject: typeof cmd === 'string' ? cmd : null,
+    data: { ...(gate === null ? {} : { gate }), ...(kind === null ? {} : { kind }), line },
+  });
 
   if (exit === 0 && typeof cmd === 'string') {
     let pendingFail = null;
@@ -116,9 +177,84 @@ export async function recordRun(root, { cmd, exit, ms, output, gate = null, kind
     }
   }
 
+  await rotateLedger(root).catch(() => {});
   return line;
 }
 
+/**
+ * Read only the end of the ledger.
+ *
+ * `recordRun` and every evidence check read the whole file, and the file grows without a
+ * bound: a repository that runs a suite a hundred times a day pays for a year of lines on
+ * every commit (Q75). A tail read answers the only question those callers ask - what
+ * happened recently on which trees - in bounded time.
+ *
+ * The first line of the slice is dropped unless the slice starts at byte 0, because a byte
+ * offset lands mid-line and half a JSON object is not evidence.
+ */
+export async function readLedgerTail(root, { entries = 200, bytes = 128 * 1024 } = {}) {
+  const path = join(root, LEDGER_FILE);
+  let text = '';
+  let partial = false;
+  try {
+    const st = await stat(path);
+    const start = Math.max(0, st.size - bytes);
+    partial = start > 0;
+    const handle = await open(path, 'r');
+    try {
+      const buffer = Buffer.alloc(st.size - start);
+      await handle.read(buffer, 0, buffer.length, start);
+      text = buffer.toString('utf8');
+    } finally {
+      await handle.close();
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return { entries: [], errors: [], partial: false };
+  }
+  const lines = text.split('\n').filter((line) => line.trim() !== '');
+  if (partial && lines.length > 0) lines.shift();
+  const parsed = [];
+  const errors = [];
+  for (const raw of lines) {
+    try {
+      const line = JSON.parse(raw);
+      if (typeof line.tree === 'string' && typeof line.exit === 'number') parsed.push(line);
+      else errors.push('a line has no tree or exit');
+    } catch (error) {
+      errors.push(`a line does not parse (${error.message})`);
+    }
+  }
+  return { entries: parsed.slice(-entries), errors, partial };
+}
+
+/**
+ * Keep the ledger bounded: past `maxLines`, the older half moves to `<ledger>.1`.
+ *
+ * Rotation rather than deletion because the ledger is evidence: an archived line is still
+ * readable, and the event log holds the same record independently (Q73). Keeping half
+ * rather than `maxLines` means rotation happens every `maxLines/2` appends instead of on
+ * every one.
+ */
+export async function rotateLedger(root, { maxLines = 5000 } = {}) {
+  const path = join(root, LEDGER_FILE);
+  let text;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return { rotated: false };
+    throw error;
+  }
+  const lines = text.split('\n').filter((line) => line.trim() !== '');
+  if (lines.length <= maxLines) return { rotated: false };
+  const keep = Math.max(1, Math.floor(maxLines / 2));
+  const archived = lines.slice(0, lines.length - keep);
+  const kept = lines.slice(lines.length - keep);
+  await writeFile(join(root, `${LEDGER_FILE}.1`), `${archived.join('\n')}\n`, 'utf8');
+  await writeFile(path, `${kept.join('\n')}\n`, 'utf8');
+  return { rotated: true, archived: archived.length, kept: kept.length };
+}
+
 /** Every well-formed line. A line that does not parse is returned as an error so a
  *  damaged ledger cannot look empty. */
 export async function readLedger(root) {

package/src/local/client.mjs

@@ -18,14 +18,12 @@ function guardEndpoint(endpoint, { allowRemote = false } = {}) {
   if (!endpoint || typeof endpoint !== 'object') {
     return { ok: false, error: 'local model endpoint is not configured', refusedRemote: false };
   }
+  // `url` and `model` are validated once, where the config is read
+  // (`local/config.mjs`): an endpoint that reaches this function has both. What is left
+  // here is the one rule the config cannot enforce - a loopback-only default - and that
+  // is why this function still exists (review 0003 Q83).
   const rawUrl = typeof endpoint.url === 'string' ? endpoint.url.trim() : '';
-  if (!rawUrl) {
-    return { ok: false, error: 'local model endpoint is missing `url`', refusedRemote: false };
-  }
   const model = typeof endpoint.model === 'string' ? endpoint.model.trim() : '';
-  if (!model) {
-    return { ok: false, error: 'local model endpoint is missing `model`', refusedRemote: false };
-  }
   const apiKey = typeof endpoint.apiKey === 'string' && endpoint.apiKey.length > 0 ? endpoint.apiKey : null;
   const loopback = isLoopbackUrl(rawUrl);
   if (!loopback && !allowRemote) {

package/src/locate.mjs

@@ -35,23 +35,47 @@ export function renderLocator(command, { subject = CLI, remedy = `REMEDY run: np
   const D = '$';
   return `# ${D}${BIN_ENV} must name ONE program: an executable on PATH, or a .mjs entry
 # point to hand to node. It cannot be a command line, because there is no safe way
-# to split one in sh without eval, and a value with a space is refused rather than
-# half-executed - running from a source checkout is normal for anyone working on
-# this project itself, so this path has to work with no install step.
+# to split one in sh without eval, and a value with a space that names no file is
+# refused rather than half-executed - running from a source checkout is normal for
+# anyone working on this project itself, so this path has to work with no install step.
+#
+# Every .mjs entry point goes through run_node, which checks for node first: a GUI
+# client's PATH often carries none (nvm is sourced only in an interactive shell), and
+# exec node there fails with 127 and no explanation of what to install.
+run_node() {
+  if ! command -v node >/dev/null 2>&1; then
+    echo "${CLI}: cannot find node to run ${D}1." >&2
+    echo "  the hook runs a .mjs entry point through node; install Node >= 22.20.0," >&2
+    echo "  or set ${BIN_ENV} to an executable ${CLI}" >&2
+    exit 1
+  fi
+  entry="${D}1"
+  shift
+  exec node "${D}entry" "${D}@"
+}
+
 run_simt_dev() {
   case "${D}1" in
     *' '*)
+      # A space is ambiguous as text and unambiguous as a file: a value that names
+      # something on disk is a path in a directory with a space, and runs as one.
+      if [ -f "${D}1" ]; then
+        case "${D}1" in
+          *.mjs)
+            run_node "${D}@"
+            ;;
+          *)
+            exec "${D}@"
+            ;;
+        esac
+      fi
       echo "${CLI}: ${D}${BIN_ENV} names a command line, not a program." >&2
       echo "  set it to a single executable or a .mjs path, e.g." >&2
       echo "    ${BIN_ENV}=/path/to/checkout/${BIN_REL}" >&2
       exit 1
       ;;
     *.mjs)
-      # shift first: "${D}@" still holds ${D}1, which would pass the program path to
-      # itself as the first argument.
-      program="${D}1"
-      shift
-      exec node "${D}program" "${D}@"
+      run_node "${D}@"
       ;;
     *)
       exec "${D}1" "${D}@"
@@ -64,7 +88,7 @@ if [ -n "${D}{${BIN_ENV}:-}" ]; then
 fi
 
 if [ -f "${D}ROOT/node_modules/${PACKAGE_NAME}/${BIN_REL}" ]; then
-  exec node "${D}ROOT/node_modules/${PACKAGE_NAME}/${BIN_REL}" ${command}
+  run_node "${D}ROOT/node_modules/${PACKAGE_NAME}/${BIN_REL}" ${command}
 fi
 
 # The binary this repository downloaded for itself: the pinned bytes, no node.

package/src/manifest/schema.mjs

@@ -0,0 +1,213 @@
+// The manifest's own schema: one table of the keys this file may carry, and one
+// loader that says what is wrong with the file rather than throwing or guessing.
+//
+// The manifest was read in 29 places, each doing a bare `JSON.parse` and then
+// reaching for the key it wanted. That is three answers to "what is this repo" -
+// the parse, the key access, and whatever default the caller invented - and a
+// manifest with `"mode": "kernal"` reached the projection as a mode it had never
+// heard of. A typo in one key silently changed behaviour, because nothing in the
+// tool had ever said what the keys are (review 0003 Q69).
+//
+// Every shape below was read off the manifest this repository carries, not from
+// memory: the first draft of this table called `limits.fileLines` a positive integer
+// and `surfaces` an object, and both are wrong in the only file the tool has to hand.
+// `test/manifest-schema.test.mjs` holds the table to that file, which is the check
+// that would have caught it.
+//
+// `owner` is the reason a key is in this table at all. A `tool` key is written by
+// this binary and a repository editing it is fighting the writer; a `repo` key is
+// the repository's own declaration and this tool only reads it. The distinction is
+// already load-bearing (`GENERATED_KEYS`, `init` keeping `limits`), and stating it
+// here is what keeps the two from drifting apart.
+
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
+
+/** Absent means 1: the field arrived after the file did, and every file predates it. */
+const MANIFEST_VERSION = 1;
+
+/**
+ * The manifest a repository has, which is not necessarily the one this tool would write.
+ *
+ * The file was renamed from `simt-dev.json` to `simt.json`. Every read site used to say
+ * `join(root, MANIFEST_FILE)` and would have reported an adopted repository as unadopted the
+ * day the constant moved - and "no manifest" means "never adopted", which is the answer
+ * that offers to re-adopt a repo that is already done. Fourteen repositories carry the
+ * old name on disk.
+ *
+ * So the old name is read as a fallback and the new one is written. `writeManifest`
+ * renames rather than creating a second file, which is how the window closes: the first
+ * `simt init` or `simt sync` in an adopted repo retires the old name by moving it.
+ */
+export async function manifestPath(root) {
+  const next = join(root, MANIFEST_FILE);
+  if (existsSync(next)) return next;
+  const previous = join(root, MANIFEST_LEGACY);
+  return existsSync(previous) ? previous : next;
+}
+
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === 'string');
+const isPositiveInt = (value) => Number.isInteger(value) && value > 0;
+
+/**
+ * The keys a manifest may carry.
+ *
+ * `check` returns a sentence naming what is wrong, or null. It returns a sentence
+ * rather than a boolean because the reader of a problem is a person looking at a file
+ * they edited by hand, and "invalid" tells them nothing they did not know.
+ */
+export const KEYS = [
+  { key: '$comment', owner: 'tool', generated: true, since: '0.7.0', check: (v) => (typeof v === 'string' || isStringList(v) ? null : '$comment must be a string or a list of strings') },
+  { key: 'id', owner: 'tool', since: '0.7.0', check: (v) => (typeof v === 'string' && v.length > 0 ? null : 'id must be a non-empty string') },
+  { key: 'version', owner: 'tool', since: '0.9.0', check: (v) => (Number.isInteger(v) && v >= 1 ? null : 'version must be an integer of at least 1') },
+  { key: 'stack', owner: 'tool', since: '0.7.0', check: (v) => (isStringList(v) ? null : 'stack must be a list of profile ids') },
+  { key: 'limits', owner: 'repo', since: '0.7.0', check: (v) => (isObject(v) ? null : 'limits must be an object') },
+  // {warn, error, excludeTextFiles, exclude} - ADR-005's two tiers plus the paths a
+  // repository opts out of, all of which the repository owns and `init` keeps.
+  { key: 'limits.fileLines', owner: 'repo', since: '0.7.0', check: (v) => (isObject(v) && isPositiveInt(v.warn) && isPositiveInt(v.error) && v.error >= v.warn ? null : 'limits.fileLines must be {warn, error} with error >= warn') },
+  { key: 'limits.coverage', owner: 'repo', since: '0.7.0', check: (v) => (v === null || (typeof v === 'number' && v >= 0 && v <= 100) ? null : 'limits.coverage must be null or a percentage') },
+  { key: 'gates', owner: 'repo', since: '0.7.0', check: (v) => (isObject(v) ? null : 'gates must be an object of gate name to command') },
+  { key: 'localSkills', owner: 'repo', since: '0.7.0', check: (v) => (isStringList(v) ? null : 'localSkills must be a list of skill ids') },
+  { key: 'profiles', owner: 'repo', since: '0.8.0', check: (v) => (isStringList(v) ? null : 'profiles must be a list of profile ids') },
+  { key: 'substitutions', owner: 'repo', since: '0.8.0', check: (v) => (isObject(v) ? null : 'substitutions must be an object keyed by rule id') },
+  { key: 'packs', owner: 'repo', since: '0.8.0', check: (v) => (Array.isArray(v) ? null : 'packs must be a list') },
+  // A workspace declaration is a path relative to the repository; `workspace.mjs`
+  // refuses to walk one that resolves outside, so the type is the whole check.
+  { key: 'workspace', owner: 'repo', since: '0.7.0', check: (v) => (typeof v === 'string' ? null : 'workspace must be a path string') },
+  { key: 'decisions', owner: 'repo', since: '0.8.0', check: (v) => (isObject(v) ? null : 'decisions must be an object') },
+  { key: 'budget', owner: 'repo', since: '0.8.0', check: (v) => (isObject(v) ? null : 'budget must be an object') },
+  { key: 'budget.bytes', owner: 'repo', since: '0.8.0', check: (v) => (isPositiveInt(v) ? null : 'budget.bytes must be a positive integer') },
+  { key: 'mode', owner: 'repo', since: '0.8.0', check: (v) => (v === 'full' || v === 'kernel' ? null : 'mode must be "full" or "kernel", not ' + JSON.stringify(v)) },
+  { key: 'shared', owner: 'repo', since: '0.8.0', check: (v) => (isObject(v) ? null : 'shared must be an object') },
+  // The overlay `plan/template.mjs` compiles over the default tracker body; an array
+  // would be accepted by an object-typed read and then produce an empty template.
+  { key: 'plans', owner: 'repo', since: '0.7.0', check: (v) => (isObject(v) ? null : 'plans must be an object overlay') },
+  // Null and absent both mean "the global standard applies" (manifestDrift's own
+  // rule), and a list is what `init` writes. An object here is a shape nothing has
+  // ever produced, so accepting it would be the validator blessing a typo.
+  { key: 'surfaces', owner: 'repo', since: '0.8.0', check: (v) => (v === null || isStringList(v) ? null : 'surfaces must be null or a list of surface ids') },
+  { key: 'projection', owner: 'tool', generated: true, since: '0.7.0', check: (v) => (isObject(v) ? null : 'projection must be an object') },
+];
+
+const KNOWABLE = new Set(KEYS.map((entry) => entry.key));
+
+/** The keys this tool writes, derived from the table: the `generated` marks above. */
+export const GENERATED_KEYS_OF = new Set(KEYS.filter((entry) => entry.generated === true).map((entry) => entry.key));
+
+
+/**
+ * Namespaces a consumer registered against this table.
+ *
+ * A namespace is a sub-object of the manifest that another part of the tool owns -
+ * plan 0004's `work` is the first. It registers its keys here rather than editing the
+ * table, so adding one touches two files and no reader has to learn a second shape
+ * (review 0003 Q69).
+ */
+const NAMESPACES = new Map();
+
+/**
+ * Declare the keys of one namespace. Registered keys are checked exactly like top-level
+ * ones; a namespace nobody registered is left alone, because an unknown key has never
+ * been an error in this file.
+ *
+ * @param {string} name the manifest key that carries the namespace
+ * @param {{key: string, since?: string, check: (value: unknown) => string|null}[]} keys
+ * @returns {number} how many keys the namespace declares
+ */
+export function registerNamespace(name, keys) {
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+    throw new Error('namespace "' + name + '" must be lower-case words joined by hyphens');
+  }
+  if (KNOWABLE.has(name)) throw new Error('namespace "' + name + '" is already a manifest key');
+  if (NAMESPACES.has(name)) throw new Error('namespace "' + name + '" is already registered');
+  if (!Array.isArray(keys) || keys.length === 0) {
+    throw new Error('namespace "' + name + '" must register at least one key');
+  }
+  for (const entry of keys) {
+    if (typeof entry?.key !== 'string' || !/^[a-z][a-z0-9]*$/.test(entry.key)) {
+      throw new Error('namespace "' + name + '" keys must be lower-case single words');
+    }
+    if (typeof entry.check !== 'function') {
+      throw new Error('namespace "' + name + '" key "' + entry.key + '" has no check');
+    }
+  }
+  NAMESPACES.set(name, keys.map((entry) => ({ owner: 'repo', since: '0.9.0', ...entry })));
+  return keys.length;
+}
+
+/** The namespaces a consumer declared, for a reader that needs the whole set. */
+export function registeredNamespaces() {
+  return [...NAMESPACES.keys()].sort();
+}
+
+/**
+ * What is wrong with one parsed manifest.
+ *
+ * An unknown key is not a problem. A repository that keeps its own note in this file
+ * is doing the thing the file's own comment invites, and a validator that refused it
+ * would be the tool insisting its schema is the whole of a file it calls the
+ * repository's. Only a KNOWN key with an impossible value is reported.
+ */
+export function manifestProblems(manifest) {
+  const problems = [];
+  for (const { key, check } of KEYS) {
+    const [head, tail] = key.includes('.') ? key.split('.') : [key, null];
+    if (!(head in manifest)) continue;
+    if (tail !== null && (!isObject(manifest[head]) || !(tail in manifest[head]))) continue;
+    const value = tail === null ? manifest[head] : manifest[head][tail];
+    if (value === undefined) continue;
+    const problem = check(value);
+    if (problem !== null) problems.push(problem);
+  }
+  for (const [name, keys] of NAMESPACES) {
+    const value = manifest[name];
+    if (!isObject(value)) continue;
+    for (const entry of keys) {
+      if (!(entry.key in value) || value[entry.key] === undefined) continue;
+      const problem = entry.check(value[entry.key]);
+      if (problem !== null) problems.push(name + '.' + entry.key + ': ' + problem);
+    }
+  }
+  return problems;
+}
+
+/**
+ * The manifest a repository has, with its problems named.
+ *
+ * `manifest` is null when there is no file and when the file does not parse, because
+ * a caller that receives a half-read object cannot tell which it has - and the one
+ * caller that did (`fingerprint`) returned `{error}` in place of a manifest, so a
+ * broken file looked like a declaration of a key called `error` (review 0003 Q69).
+ * `exists` and `problems` are what tell the two apart, and neither is optional.
+ *
+ * @returns {Promise<{manifest: object|null, exists: boolean, version: number, problems: string[], path: string}>}
+ */
+export async function loadManifest(root) {
+  const path = await manifestPath(root);
+  let text;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch {
+    return { manifest: null, exists: false, version: MANIFEST_VERSION, problems: [], path };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    return { manifest: null, exists: true, version: MANIFEST_VERSION, problems: [`unparseable: ${error.message}`], path };
+  }
+  if (!isObject(parsed)) {
+    return { manifest: null, exists: true, version: MANIFEST_VERSION, problems: ['not a JSON object'], path };
+  }
+  return {
+    manifest: parsed,
+    exists: true,
+    version: Number.isInteger(parsed.version) ? parsed.version : MANIFEST_VERSION,
+    problems: manifestProblems(parsed),
+    path,
+  };
+}

package/src/mcp/paginate.mjs

@@ -0,0 +1,33 @@
+// One page of a list result, and the cursor that asks for the next one.
+//
+// MCP lets a server answer a list method in pages, and a client that ignores `nextCursor`
+// must still see a usable first page. This server has never paginated, which was fine
+// while every list fit in one reply and stops being fine the moment a workspace brings
+// dozens of repositories into `resources/list`: a client that renders what it is given
+// then silently shows a subset of the estate (review 0003 Q66).
+//
+// The cursor is the offset, rendered as a string. The specification calls it opaque, and
+// the client must not parse it, but it has to be stable across calls: an index into a list
+// that is rebuilt in a deterministic order is, and a hash of the last item's name is not -
+// two items can share one.
+
+/** How many entries one reply carries. */
+export const PAGE_SIZE = 50;
+
+/**
+ * The page a cursor asks for, or `null` when the cursor is not one this server issued.
+ *
+ * A cursor outside the list is not clamped to the last page: a client that walked past the
+ * end has a stale cursor, and silently repeating the tail hides that the list changed
+ * under it.
+ */
+export function paginate(items, cursor, size = PAGE_SIZE) {
+  const text = cursor === undefined || cursor === null || cursor === '' ? '0' : String(cursor);
+  // Only the shape this server writes: a decimal offset. `Number` accepts '0x10' and ' ',
+  // and accepting a cursor nobody issued is how pagination silently repeats or skips.
+  if (!/^\d+$/.test(text)) return null;
+  const start = Number(text);
+  const page = items.slice(start, start + size);
+  const next = start + size < items.length ? String(start + size) : null;
+  return { items: page, nextCursor: next };
+}

package/src/mcp/resources.mjs

@@ -199,15 +199,9 @@ export async function readResource(uri, root = process.cwd()) {
     const [rules, mdc] = await Promise.all([loadRules(null), loadMdcRules()]);
     const rule = [...rules, ...mdc].find((candidate) => candidate.id === parsed.id);
     if (rule === undefined) return null;
-    const text = `${frontmatterOf(rule)}\n${rule.body ?? ''}`.trim();
-    return {
-      uri,
-      mimeType: 'text/markdown',
-      text,
-      // The body a tool returns is redacted for the same reason: a reader outside this
-      // estate is told what the rule says and not which directory here it is filed in.
-      bytes: Buffer.byteLength(text),
-    };
+    // The body a tool returns is redacted for the same reason: a reader outside this
+    // estate is told what the rule says and not which directory here it is filed in.
+    return { uri, mimeType: 'text/markdown', text: `${frontmatterOf(rule)}\n${rule.body ?? ''}`.trim() };
   }
 
   // `loadDecisions` reads the index, not the records: it reports status, currency and
@@ -218,7 +212,10 @@ export async function readResource(uri, root = process.cwd()) {
   if (decision === undefined) return null;
   const raw = await readFile(join(DECISIONS_DIR, decision.file), 'utf8');
   const text = redactInternalPaths(redactEstate(raw)).trim();
-  return { uri, mimeType: 'text/markdown', text, bytes: Buffer.byteLength(text) };
+  // `bytes` is not a `ResourceContents` field: a client validating the result against
+  // the specification sees an unexpected property, and the length is `text.length` away
+  // (Q56).
+  return { uri, mimeType: 'text/markdown', text };
 }
 
 function frontmatterOf(rule) {