@codai/axiom-mcp 2.0.0 → 2.1.0

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { GuardOptions } from "@codai/axiom-checks";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import "@modelcontextprotocol/sdk/types.js";
 //#region src/jsonschema.d.ts
-export declare const SCHEMA_KINDS: readonly ["Plan", "Manifest", "ManifestBundle", "CheckReport", "ApplyResult", "Profile", "Journal"];
+export declare const SCHEMA_KINDS: readonly ["Plan", "Manifest", "ManifestBundle", "CheckReport", "ApplyResult", "Profile", "Journal", "RepoSnapshot"];
 type SchemaKind = (typeof SCHEMA_KINDS)[number];
 export declare function isSchemaKind(v: unknown): v is SchemaKind;
 /** Draft 2020-12 JSON Schema, byte-identical to `packages/schema/schemas/<kind>.schema.json`. */

package/dist/index.js

@@ -1,14 +1,17 @@
 import { createRequire } from "node:module";
-import { ApplyResultSchema, AxiomError, CheckReportSchema, DigestRefSchema, ErrorCodeSchema, JournalPhaseSchema, JournalSchema, ManifestBodySchema, ManifestBundleSchema, PlanSchema, ProfileSchema } from "@codai/axiom-schema";
+import { ApplyResultSchema, AxiomError, CheckReportSchema, DigestRefSchema, ErrorCodeSchema, JournalPhaseSchema, JournalSchema, ManifestBodySchema, ManifestBundleSchema, PlanSchema, ProfileSchema, RepoSnapshotSchema, TrustStateSchema, TrustStoreSchema, compareUtf8, isValidRelPath } from "@codai/axiom-schema";
 import { z } from "zod";
-import { realpath } from "node:fs";
-import { access, constants, mkdir, readFile, readdir, rename, stat, writeFile } from "node:fs/promises";
+import { createReadStream, realpath } from "node:fs";
+import { access, chmod, constants, lstat, mkdir, opendir, readFile, readdir, realpath as realpath$1, rename, stat, writeFile } from "node:fs/promises";
 import * as path from "node:path";
 import { promisify } from "node:util";
-import { loadProfile, runChecks } from "@codai/axiom-checks";
+import { TRUST_FILE_DEFAULT, TRUST_STATE_FILE, loadProfile, runChecks, verifyBundleSignatures } from "@codai/axiom-checks";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { webEmitter } from "@codai/axiom-emitters-web";
+import { compilePlan, createEmitterRegistry, diffManifests, verifyBundle } from "@codai/axiom-plan";
 import { appliedPath, apply, rollback } from "@codai/axiom-apply";
-import { compilePlan, diffManifests, verifyBundle } from "@codai/axiom-plan";
+import { canonicalDigestRef } from "@codai/axiom-canon";
+import { createHash } from "node:crypto";
 //#region src/jsonschema.ts
 const SCHEMA_KINDS = [
 	"Plan",
@@ -17,7 +20,8 @@ const SCHEMA_KINDS = [
 	"CheckReport",
 	"ApplyResult",
 	"Profile",
-	"Journal"
+	"Journal",
+	"RepoSnapshot"
 ];
 const BY_KIND = {
 	Plan: PlanSchema,
@@ -26,7 +30,8 @@ const BY_KIND = {
 	CheckReport: CheckReportSchema,
 	ApplyResult: ApplyResultSchema,
 	Profile: ProfileSchema,
-	Journal: JournalSchema
+	Journal: JournalSchema,
+	RepoSnapshot: RepoSnapshotSchema
 };
 function isSchemaKind(v) {
 	return typeof v === "string" && SCHEMA_KINDS.includes(v);
@@ -162,6 +167,25 @@ async function resolveRoot(policy, requested) {
 	} });
 }
 //#endregion
+//#region src/emitters.ts
+/** Template emitters available to `axiom_plan_compile` / `axiom compile` (D-13: optional sugar). */
+const EMITTERS = createEmitterRegistry([webEmitter]);
+/** Flat, sorted `emitter@version: template — description` rows for the CLI and the resource. */
+function emitterCatalogue(registry = EMITTERS) {
+	const rows = [];
+	for (const id of registry.list()) {
+		const e = registry.get(id);
+		if (e === void 0) continue;
+		for (const template of Object.keys(e.templates).sort()) rows.push({
+			emitter: e.id,
+			version: e.version,
+			template,
+			description: e.templates[template]?.description ?? ""
+		});
+	}
+	return rows;
+}
+//#endregion
 //#region src/store.ts
 /** `<root>/.axiom/manifests/<hex>.json` and `<root>/.axiom/reports/<hex>.json`. */
 function manifestsDir(root) {
@@ -179,13 +203,13 @@ function toDigestRef(shaOrRef) {
 	if (!parsed.success) throw new AxiomError("ERR_NOT_FOUND", `not a sha256 digest: ${shaOrRef}`);
 	return parsed.data;
 }
-async function writeJsonAtomic(file, value) {
+async function writeJsonAtomic$1(file, value) {
 	await mkdir(path.dirname(file), { recursive: true });
 	const tmp = `${file}.tmp-${process.pid}`;
 	await writeFile(tmp, JSON.stringify(value), "utf8");
 	await rename(tmp, file);
 }
-async function readJsonOrUndefined(file) {
+async function readJsonOrUndefined$1(file) {
 	try {
 		return JSON.parse(await readFile(file, "utf8"));
 	} catch (err) {
@@ -195,30 +219,30 @@ async function readJsonOrUndefined(file) {
 }
 async function saveManifest(root, bundle) {
 	const file = path.join(manifestsDir(root), `${hexOf(bundle.manifestDigest)}.json`);
-	await writeJsonAtomic(file, bundle);
+	await writeJsonAtomic$1(file, bundle);
 	return file;
 }
 async function saveReport(root, report) {
 	const file = path.join(reportsDir(root), `${hexOf(report.manifestDigest)}.json`);
-	await writeJsonAtomic(file, report);
+	await writeJsonAtomic$1(file, report);
 	return file;
 }
 /** Search every root (allowlisted + seen) for a stored bundle. */
 async function loadManifest(roots, ref) {
 	for (const root of roots) {
-		const raw = await readJsonOrUndefined(path.join(manifestsDir(root), `${hexOf(ref)}.json`));
+		const raw = await readJsonOrUndefined$1(path.join(manifestsDir(root), `${hexOf(ref)}.json`));
 		if (raw !== void 0) return ManifestBundleSchema.parse(raw);
 	}
 }
 async function loadReport(roots, ref) {
 	for (const root of roots) {
-		const raw = await readJsonOrUndefined(path.join(reportsDir(root), `${hexOf(ref)}.json`));
+		const raw = await readJsonOrUndefined$1(path.join(reportsDir(root), `${hexOf(ref)}.json`));
 		if (raw !== void 0) return CheckReportSchema.parse(raw);
 	}
 }
 async function loadApplied(roots, ref) {
 	for (const root of roots) {
-		const raw = await readJsonOrUndefined(appliedPath(root, ref));
+		const raw = await readJsonOrUndefined$1(appliedPath(root, ref));
 		if (raw !== void 0) return ApplyResultSchema.parse(raw);
 	}
 }
@@ -242,6 +266,293 @@ async function listStored(roots, sub) {
 	return out;
 }
 //#endregion
+//#region src/keys.ts
+/**
+* Key material and trust-store I/O for the CLI/MCP layer (D-16).
+*
+* Private keys are read ONLY from `AXIOM_SIGNING_KEY` (base64 PKCS#8 or raw seed) or
+* `--key-file <path>`; they are never written to stdout and never stored under a root.
+*/
+function trustFilePath(root, rel = TRUST_FILE_DEFAULT) {
+	return path.join(root, ...rel.split("/"));
+}
+function trustStatePath(root) {
+	return path.join(root, ...TRUST_STATE_FILE.split("/"));
+}
+async function writeJsonAtomic(file, value, mode) {
+	await mkdir(path.dirname(file), { recursive: true });
+	const tmp = `${file}.tmp-${process.pid}`;
+	await writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, {
+		encoding: "utf8",
+		mode
+	});
+	if (mode !== void 0) await chmod(tmp, mode).catch(() => void 0);
+	await rename(tmp, file);
+}
+async function readJsonOrUndefined(file) {
+	try {
+		return JSON.parse(await readFile(file, "utf8"));
+	} catch (err) {
+		if (err.code === "ENOENT") return void 0;
+		throw err;
+	}
+}
+/** Verify a bundle's detached signatures against the root's trust store; `undefined` when no store. */
+async function verifyBundleAgainstRoot(root, bundle, rel = TRUST_FILE_DEFAULT) {
+	const store = await loadTrustStore(root, rel);
+	if (store === void 0) return void 0;
+	const v = verifyBundleSignatures(bundle, store, bundle.manifest.counter);
+	return {
+		trustFile: rel,
+		keyids: v.keyids,
+		findings: v.findings.map((f) => ({
+			id: f.id,
+			message: f.message
+		})),
+		ok: v.keyids.length > 0 && v.findings.length === 0
+	};
+}
+async function loadTrustStore(root, rel = TRUST_FILE_DEFAULT) {
+	const raw = await readJsonOrUndefined(trustFilePath(root, rel));
+	if (raw === void 0) return void 0;
+	const parsed = TrustStoreSchema.safeParse(raw);
+	if (!parsed.success) throw new AxiomError("ERR_INVALID_PROFILE", `trust store ${rel} is invalid`, { details: { issues: parsed.error.issues.slice(0, 10).map((i) => i.message) } });
+	return parsed.data;
+}
+async function loadTrustState(root) {
+	const raw = await readJsonOrUndefined(trustStatePath(root));
+	if (raw === void 0) return void 0;
+	const parsed = TrustStateSchema.safeParse(raw);
+	if (!parsed.success) throw new AxiomError("ERR_JOURNAL_CORRUPT", `${TRUST_STATE_FILE} is invalid`);
+	return parsed.data;
+}
+/**
+* Advance `lastCounter` to `bundle.manifest.counter` after a successful apply.
+* Monotonic: never moves backwards; a no-op when the bundle has no counter.
+* Write-temp + rename so a crash leaves either the old or the new state.
+*/
+async function advanceTrustState(root, bundle) {
+	const counter = bundle.manifest.counter;
+	if (counter === void 0) return void 0;
+	const cur = await loadTrustState(root);
+	if (cur !== void 0 && cur.lastCounter >= counter) return cur;
+	const next = {
+		version: 1,
+		lastCounter: counter,
+		manifestDigest: bundle.manifestDigest
+	};
+	await writeJsonAtomic(trustStatePath(root), next);
+	return next;
+}
+/** Does the resolved profile (plus plan checks) enable antiRollback on requireSigned? */
+function profileWantsAntiRollback(checks) {
+	return checks.some((c) => c.predicate === "manifest.requireSigned" && typeof c.params === "object" && c.params !== null && c.params.antiRollback === true);
+}
+//#endregion
+//#region src/snapshot.ts
+/**
+* `axiom_repo_snapshot` — deterministic, content-addressed inventory of a root (S-304).
+*
+* Successor of the v1 reverse-IR, which guessed "service types" from directory names and
+* hashed nothing. A RepoSnapshot records what is actually there — relative path, size,
+* sha256, mode, kind — sorted by `compareUtf8`, with no timestamps and no absolute paths, so
+* the same tree yields the same `snapshotDigest` on every machine (invariant 1). Agents use
+* it to build Plans against real pre-image digests and to diff two states of a tree.
+*
+* Read-only: never follows symlinks, never leaves the root, never spawns a process.
+*/
+const SNAPSHOT_MAX_FILES_DEFAULT = 2e4;
+const SNAPSHOT_MAX_FILES_CAP = 5e4;
+const SNAPSHOT_MAX_BYTES_DEFAULT = 67108864;
+/** Never inventoried, whatever `.gitignore` says. */
+const ALWAYS_SKIP = /* @__PURE__ */ new Set([".git", ".axiom"]);
+function globToRegExp(glob) {
+	let re = "^";
+	for (let i = 0; i < glob.length; i++) {
+		const c = glob[i];
+		if (c === "*") {
+			if (glob[i + 1] === "*") {
+				i++;
+				if (glob[i + 1] === "/") {
+					i++;
+					re += "(?:.*/)?";
+				} else re += ".*";
+			} else re += "[^/]*";
+		} else if (c === "?") re += "[^/]";
+		else re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+	}
+	return new RegExp(`${re}$`);
+}
+function matcherOf(globs, whenEmpty) {
+	if (globs === void 0 || globs.length === 0) return () => whenEmpty;
+	const res = globs.map(globToRegExp);
+	return (rel) => res.some((r) => r.test(rel));
+}
+/** A glob must itself be a contained relative path once wildcards are removed (`..` → rejected). */
+function validateGlob(g, label) {
+	const probe = g.replace(/\*+/g, "x").replace(/\?/g, "x").replace(/\/+$/, "");
+	if (probe.length === 0 || !isValidRelPath(probe)) throw new AxiomError("ERR_CONTAINMENT", `${label} glob must be a contained relative path: ${g}`, { details: { glob: g } });
+}
+/** Root `.gitignore` → matchers, same rough translation the repo facts use (negations dropped). */
+async function gitignoreMatcher(root) {
+	let text;
+	try {
+		text = await readFile(path.join(root, ".gitignore"), "utf8");
+	} catch {
+		return () => false;
+	}
+	const globs = [];
+	for (const raw of text.split(/\r?\n/)) {
+		const l = raw.trim();
+		if (l.length === 0 || l.startsWith("#") || l.startsWith("!")) continue;
+		let pat = l.startsWith("/") ? l.slice(1) : l.includes("/") ? l : `**/${l}`;
+		if (pat.endsWith("/")) pat = pat.slice(0, -1);
+		globs.push(pat, `${pat}/**`);
+	}
+	return matcherOf(globs, false);
+}
+function sha256File(abs) {
+	return new Promise((resolve, reject) => {
+		const h = createHash("sha256");
+		createReadStream(abs).on("data", (chunk) => h.update(chunk)).on("error", reject).on("end", () => resolve(h.digest("hex")));
+	});
+}
+function modeOf(mode) {
+	return process.platform !== "win32" && (mode & 64) !== 0 ? "0755" : "0644";
+}
+/**
+* Inventory `rootReal` (already realpath'd and authorised by the caller).
+* The walk visits entries in `compareUtf8` order of their relative path (directories keyed with
+* a trailing `/`), which is exactly the final sort order — so a truncated `files` is the first
+* N paths of the full sorted inventory, deterministically.
+*/
+async function snapshotRoot(root, opts = {}) {
+	if (opts.followSymlinks === true) throw new AxiomError("ERR_UNSUPPORTED_OP", "followSymlinks is not supported (symlinks are recorded, never followed)");
+	const rootReal = await realpath$1(root);
+	const maxFiles = Math.min(opts.maxFiles ?? 2e4, SNAPSHOT_MAX_FILES_CAP);
+	const maxBytes = opts.maxBytes ?? 67108864;
+	if (maxFiles < 1 || maxBytes < 0) throw new AxiomError("ERR_INVALID_PLAN", "maxFiles must be ≥ 1 and maxBytes ≥ 0", { details: {
+		maxFiles,
+		maxBytes
+	} });
+	for (const g of opts.include ?? []) validateGlob(g, "include");
+	for (const g of opts.exclude ?? []) validateGlob(g, "exclude");
+	const include = matcherOf(opts.include, true);
+	const exclude = matcherOf(opts.exclude, false);
+	const ignored = opts.respectGitignore === false ? () => false : await gitignoreMatcher(rootReal);
+	const withDigest = opts.withContentDigest !== false;
+	const files = [];
+	let bytes = 0;
+	let truncated = false;
+	const visit = async (dirAbs, dirRel) => {
+		let entries;
+		try {
+			const dir = await opendir(dirAbs);
+			entries = [];
+			for await (const e of dir) entries.push(e);
+		} catch {
+			return;
+		}
+		const sortKey = (d) => d.isDirectory() ? `${d.name}/` : d.name;
+		entries.sort((a, b) => compareUtf8(sortKey(a), sortKey(b)));
+		for (const e of entries) {
+			if (truncated) return;
+			const rel = dirRel === "" ? e.name : `${dirRel}/${e.name}`;
+			if (!isValidRelPath(rel)) continue;
+			if (e.isDirectory()) {
+				if (ALWAYS_SKIP.has(e.name) || ignored(rel) || exclude(rel)) continue;
+				await visit(path.join(dirAbs, e.name), rel);
+				continue;
+			}
+			if (ignored(rel) || !include(rel) || exclude(rel)) continue;
+			const abs = path.join(dirAbs, e.name);
+			let entry;
+			if (e.isSymbolicLink()) entry = await symlinkEntry(rootReal, abs, rel, withDigest);
+			else if (e.isFile()) entry = await fileEntry(abs, rel, withDigest);
+			if (entry === void 0) continue;
+			if (files.length >= maxFiles || bytes + entry.bytes > maxBytes) {
+				truncated = true;
+				return;
+			}
+			files.push(entry);
+			bytes += entry.bytes;
+		}
+	};
+	await visit(rootReal, "");
+	files.sort((a, b) => compareUtf8(a.path, b.path));
+	const body = {
+		files,
+		truncated,
+		counts: {
+			files: files.length,
+			bytes
+		}
+	};
+	return {
+		apiVersion: "axiom.dev/v2",
+		kind: "RepoSnapshot",
+		root: { kind: "relative" },
+		snapshotDigest: canonicalDigestRef(body),
+		body
+	};
+}
+async function fileEntry(abs, rel, withDigest) {
+	let st;
+	try {
+		st = await lstat(abs);
+	} catch {
+		return;
+	}
+	if (!st.isFile()) return void 0;
+	const entry = {
+		path: rel,
+		bytes: st.size,
+		mode: modeOf(st.mode),
+		kind: "file"
+	};
+	if (withDigest) try {
+		entry.sha256 = await sha256File(abs);
+	} catch {
+		return;
+	}
+	return entry;
+}
+/**
+* A symlink is recorded as `kind: "symlink"`. Its target is hashed only when it resolves to a
+* regular file *inside* the root; anything else (outside, dangling, directory) gets
+* `bytes: 0` and no digest — the link is inventoried, its target is not disclosed.
+*/
+async function symlinkEntry(rootReal, abs, rel, withDigest) {
+	const entry = {
+		path: rel,
+		bytes: 0,
+		mode: "0644",
+		kind: "symlink"
+	};
+	let target;
+	try {
+		target = await realpath$1(abs);
+	} catch {
+		return entry;
+	}
+	if (!isSameOrInside(rootReal, target)) return entry;
+	let st;
+	try {
+		st = await lstat(target);
+	} catch {
+		return entry;
+	}
+	if (!st.isFile()) return entry;
+	entry.bytes = st.size;
+	entry.mode = modeOf(st.mode);
+	if (withDigest) try {
+		entry.sha256 = await sha256File(target);
+	} catch {
+		entry.bytes = 0;
+	}
+	return entry;
+}
+//#endregion
 //#region src/tools.ts
 /** Hard cap on any single `bundle`/`plan` argument, measured as UTF-8 JSON bytes (§(f) payload size). */
 const BUNDLE_BYTES_MAX = 4194304;
@@ -353,7 +664,18 @@ const ManifestVerifyOutput = z.object({
 		code: ErrorCodeSchema,
 		message: z.string(),
 		path: z.string().optional()
-	}))
+	})),
+	/** Present only when a root with `.axiom/trust/keys.json` was available (D-16). */
+	signatures: z.object({
+		trustFile: z.string(),
+		/** Trusted keyids whose signature verified over this manifest. */
+		keyids: z.array(z.string()),
+		findings: z.array(z.object({
+			id: z.string(),
+			message: z.string()
+		})),
+		ok: z.boolean()
+	}).optional()
 });
 const RollbackOutput = z.object({
 	manifestDigest: DigestRefSchema,
@@ -417,7 +739,10 @@ const TOOL_DEFS = [
 				})
 			};
 			try {
-				const { bundle } = await compilePlan(parsed.data, { store: "inline" });
+				const { bundle } = await compilePlan(parsed.data, {
+					store: "inline",
+					emitters: EMITTERS
+				});
 				return {
 					ok: true,
 					planDigest: bundle.manifest.planDigest,
@@ -440,7 +765,7 @@ const TOOL_DEFS = [
 	defineTool({
 		name: "axiom_plan_compile",
 		title: "Compile a Plan into a ManifestBundle",
-		description: "Compile a Plan into a content-addressed ManifestBundle (sorted artifacts, sha256 digests, in-toto planDigest). `store: cas` writes blobs under <root>/.axiom/cas instead of inlining them. When a root is given the bundle is stored under <root>/.axiom/manifests/<hex>.json so later tools can reference it by digest.",
+		description: "Compile a Plan into a content-addressed ManifestBundle (sorted artifacts, sha256 digests, in-toto planDigest). `store: cas` writes blobs under <root>/.axiom/cas instead of inlining them. When a root is given the bundle is stored under <root>/.axiom/manifests/<hex>.json so later tools can reference it by digest. `template` sources are rendered by the built-in `web` emitter (see `axiom emitters`); its version is recorded in toolchain.emitters.",
 		inputSchema: {
 			plan: LooseObject.describe("Plan document"),
 			store: z.enum(["inline", "cas"]).optional().describe("Blob transport; default inline"),
@@ -451,7 +776,10 @@ const TOOL_DEFS = [
 		async handler(ctx, { plan, store, root }) {
 			guardPayloadSize("plan", plan);
 			const rootReal = root !== void 0 || store === "cas" ? (await resolveRoot(ctx.policy, root)).rootReal : void 0;
-			const opts = { store: store ?? "inline" };
+			const opts = {
+				store: store ?? "inline",
+				emitters: EMITTERS
+			};
 			if (rootReal !== void 0) opts.root = rootReal;
 			const { bundle } = await compilePlan(plan, opts);
 			if (rootReal !== void 0) {
@@ -476,11 +804,14 @@ const TOOL_DEFS = [
 	defineTool({
 		name: "axiom_manifest_verify",
 		title: "Verify a ManifestBundle",
-		description: "Structural and content-address verification: schema, recomputed manifestDigest, every inline blob hashes to its key, attestation subject matches. Never writes.",
-		inputSchema: { bundle: LooseObject.describe("ManifestBundle") },
+		description: "Structural and content-address verification: schema, recomputed manifestDigest, every inline blob hashes to its key, attestation subject matches. When a root with .axiom/trust/keys.json is available, detached DSSE signatures are verified and the trusted keyids are reported under `signatures`. Never writes.",
+		inputSchema: {
+			bundle: LooseObject.describe("ManifestBundle"),
+			root: RootArg
+		},
 		outputSchema: ManifestVerifyOutput,
 		annotations: READ,
-		async handler(_ctx, { bundle }) {
+		async handler(ctx, { bundle, root }) {
 			guardPayloadSize("bundle", bundle);
 			const r = verifyBundle(bundle);
 			const out = {
@@ -491,12 +822,25 @@ const TOOL_DEFS = [
 				errors: r.errors
 			};
 			if (r.manifestDigest !== void 0) out.manifestDigest = r.manifestDigest;
+			if (r.ok) {
+				const rootReal = await optionalRoot(ctx, root);
+				if (rootReal !== void 0) {
+					const sig = await verifyBundleAgainstRoot(rootReal, parseBundle(bundle));
+					if (sig !== void 0) {
+						out.signatures = sig;
+						out.signed = sig.keyids.length > 0;
+						if (!sig.ok) out.ok = false;
+					}
+				}
+			}
 			return out;
 		},
 		summarize: (o) => ({
 			ok: o.ok,
 			manifestDigest: o.manifestDigest,
 			canonical: o.canonical,
+			signed: o.signed,
+			keyids: o.signatures?.keyids,
 			missing: o.missing.length,
 			errors: o.errors.slice(0, 20)
 		})
@@ -562,6 +906,7 @@ const TOOL_DEFS = [
 				manifestDigest: parsed.manifestDigest
 			} });
 			const { rootReal } = await resolveRoot(ctx.policy, root);
+			const profileDoc = await profileFor(ctx, parsed, profile, rootReal);
 			const result = await apply({
 				bundle: parsed,
 				root: rootReal,
@@ -575,6 +920,7 @@ const TOOL_DEFS = [
 				await saveManifest(rootReal, parsed);
 				ctx.seenRoots.add(rootReal);
 			}
+			if (result.status === "applied" && profileWantsAntiRollback([...profileDoc.checks, ...parsed.manifest.checks])) await advanceTrustState(rootReal, parsed);
 			ctx.log.info("apply", {
 				manifestDigest: parsed.manifestDigest,
 				status: result.status,
@@ -677,6 +1023,46 @@ const TOOL_DEFS = [
 			return { roots };
 		},
 		summarize: (o) => o
+	}),
+	defineTool({
+		name: "axiom_repo_snapshot",
+		title: "Snapshot a root",
+		description: "Deterministic, content-addressed inventory of a root: every regular file (and symlink) as { path, bytes, sha256, mode, kind }, sorted by code point, with snapshotDigest = sha256(JCS(body)). No timestamps, no absolute paths — the same tree gives the same digest on every machine. Honours the root .gitignore, always skips .git/ and .axiom/, never follows symlinks, never leaves the root. Use it to build Plans against real pre-image digests, or diff two snapshots with `axiom snapshot-diff`.",
+		inputSchema: {
+			root: RootArg,
+			include: z.array(z.string().min(1)).optional().describe("Relative globs (*, **, ?) to keep; default everything"),
+			exclude: z.array(z.string().min(1)).optional().describe("Relative globs to drop"),
+			maxFiles: z.int().min(1).max(SNAPSHOT_MAX_FILES_CAP).default(SNAPSHOT_MAX_FILES_DEFAULT).describe(`Stop after this many files (cap ${SNAPSHOT_MAX_FILES_CAP}); sets truncated`),
+			maxBytes: z.int().nonnegative().default(SNAPSHOT_MAX_BYTES_DEFAULT).describe("Stop once the summed size would exceed this; sets truncated"),
+			followSymlinks: z.literal(false).default(false).describe("Always false; symlinks are recorded, never followed"),
+			respectGitignore: z.boolean().default(true),
+			withContentDigest: z.boolean().default(true).describe("false → sizes only, no sha256")
+		},
+		outputSchema: RepoSnapshotSchema,
+		annotations: READ,
+		async handler(ctx, input) {
+			const { rootReal } = await resolveRoot(ctx.policy, input.root);
+			const opts = {
+				maxFiles: input.maxFiles,
+				maxBytes: input.maxBytes,
+				respectGitignore: input.respectGitignore,
+				withContentDigest: input.withContentDigest
+			};
+			if (input.include !== void 0) opts.include = input.include;
+			if (input.exclude !== void 0) opts.exclude = input.exclude;
+			const snap = await snapshotRoot(rootReal, opts);
+			ctx.log.debug("snapshot", {
+				root: rootReal,
+				files: snap.body.counts.files
+			});
+			return snap;
+		},
+		summarize: (o) => ({
+			snapshotDigest: o.snapshotDigest,
+			counts: o.body.counts,
+			truncated: o.body.truncated,
+			paths: o.body.files.slice(0, 20).map((f) => f.path)
+		})
 	})
 ];
 async function resolveBundleOrRef(ctx, v, label) {
@@ -875,6 +1261,10 @@ function createServer(policy, opts = {}) {
 			text: JSON.stringify(jsonSchemaFor(k), null, 2)
 		}] };
 	});
+	server.registerResource("emitters", "axiom://emitters", {
+		title: "Template emitters available to axiom_plan_compile",
+		mimeType: "application/json"
+	}, async (uri) => json(uri.href, emitterCatalogue()));
 	log.info("server created", {
 		name: SERVER_NAME,
 		version: SERVER_VERSION,