@awebai/oats 0.25.0 → 0.25.1

package/lib/remote.mjs

@@ -31,6 +31,26 @@
  * ssh ALWAYS in BatchMode — `-o BatchMode=yes` is appended to the operator's own
  * GIT_SSH_COMMAND / core.sshCommand (or to plain `ssh`). Timeout 30 s per call.
  *
+ * KEY vs URL (post-0.25.0 fix M2): the canonical KEY (`<host>/<path>`, lowercase
+ * host, no scheme, no `.git`) is the identity everywhere — the same repo written
+ * as `git@host:org/repo.git`, `ssh://git@host/org/repo`, `https://host/org/repo`
+ * or `git:host/org/repo` is ONE key and ONE cache repo. The FETCH URL honours the
+ * form written: an ssh form (`git@…`, `ssh://…`) is fetched over ssh exactly as
+ * written, so the operator's ssh access (keys, agent, config) is what is used;
+ * an `https://` form is fetched over https; the bare `git:host/path` scheme
+ * defaults to https and fetches over ssh (`git@host:path.git`) when
+ * `remoteOptions.transport === "ssh"`. Nothing compares URLs; everything compares
+ * keys.
+ *
+ * COMMIT vs TAG OID (post-0.25.0 fix M4): an `at` naming an annotated tag's own
+ * OID is accepted, but the commit recorded (observeRemote result, error details,
+ * cache pin) is ALWAYS the peeled commit (`rev-parse <oid>^{commit}`).
+ *
+ * TIMEOUT vs OVERFLOW (post-0.25.0 fix L4): `error.timedOut` is set only for the
+ * timeout kill; a `maxBuffer` overflow (`ERR_CHILD_PROCESS_STDIO_MAXBUFFER`) is
+ * `error.overflowed`. A listing failure git does not explain is never a raw
+ * Node error escaping this module: it is E_REMOTE_UNREADABLE { reason: "unknown" }.
+ *
  * TREE SAFETY: every entry name git reports is validated BEFORE anything touches
  * the disk. A component that is empty, `.`, `..`, `.git` (any case) or contains
  * `\` / NUL is E_REMOTE_TREE_UNSAFE { why: "path" } — a crafted tree object can
@@ -44,9 +64,9 @@
  * fetch that loses an on-disk `.lock` race to another process is retried.
  *
  * CACHE PIN vs OBJECTS: the pin ref is the fast-path marker, but a wiped or
- * pruned object store is detected (`cat-file -e <oid>^{commit}`) and refetched;
+ * pruned object store is detected (`rev-parse <oid>^{commit}`) and refetched;
  * the pin never turns a stale cache into a claim about the remote. The object
- * must be a COMMIT: a tag or `at` naming a tree/blob is E_REMOTE_UNREADABLE.
+ * must PEEL to a COMMIT: `at` naming a tree/blob (or a tag of one) is E_REMOTE_UNREADABLE.
  *
  * CONTENT DIGEST (canonical framing, shared by fetchRemoteTree and contentDigest):
  *   sha256 over the concatenation, for every REGULAR FILE sorted by relpath
@@ -99,11 +119,26 @@ function repoPathSegments(rawPath, text) {
   return parts.join("/");
 }
 
-function hostedRef(host, rawPath, text) {
+const TRANSPORTS = new Set(["https", "ssh"]);
+
+/**
+ * A hosted ref. `fetchUrl` is the url the FORM WRITTEN asks for (null → derive from
+ * `transport`): ssh forms are kept verbatim (the operator's ssh access is what must be
+ * used), https forms are canonicalised, and the bare `git:` scheme follows `transport`.
+ */
+function hostedRef(host, rawPath, text, { fetchUrl = null, transport = "https" } = {}) {
   const h = host.toLowerCase();
   if (!/^[a-z0-9.-]+$/.test(h)) throw fail("E_REPO_REF", `repository reference has an invalid host: ${text}`, { ref: text, host });
   const path = repoPathSegments(rawPath, text);
-  return Object.freeze({ host: h, path, url: `https://${h}/${path}.git`, key: `${h}/${path}` });
+  const url = fetchUrl ?? (transport === "ssh" ? `git@${h}:${path}.git` : `https://${h}/${path}.git`);
+  return Object.freeze({ host: h, path, url, key: `${h}/${path}` });
+}
+
+function transportOf(options) {
+  const t = options?.transport;
+  if (t === undefined || t === null) return "https";
+  if (!TRANSPORTS.has(t)) throw fail("E_REPO_REF", `remoteOptions.transport must be "https" or "ssh", got ${JSON.stringify(t)}`, { transport: t });
+  return t;
 }
 
 function localRef(absPath) {
@@ -113,11 +148,16 @@ function localRef(absPath) {
 
 /**
  * "git:github.com/org/repo(.git)" | "https://github.com/org/repo(.git)" | "git@github.com:org/repo(.git)"
- * | "/abs/path/to/bare.git" | "file:///abs/path" → { host, path, url, key } | throws E_REPO_REF.
+ * | "ssh://[user@]github.com[:port]/org/repo(.git)" | "/abs/path/to/bare.git" | "file:///abs/path"
+ * → { host, path, url, key } | throws E_REPO_REF.
+ * `key` ("<host>/<path>") is the identity: every form of one repo gives the same key.
+ * `url` is what git fetches: ssh forms verbatim, https canonical, the bare `git:` scheme
+ * per `options.transport` ("https" default | "ssh" → `git@<host>:<path>.git`).
  * Already-parsed refs (objects with key+url) pass through once re-validated: the
  * object's `url` must itself parse to the same `key` (no smuggled `ext::` urls or `../` keys).
  */
-export function parseRepoRef(text) {
+export function parseRepoRef(text, options = undefined) {
+  const transport = transportOf(options);
   if (text && typeof text === "object" && typeof text.key === "string" && typeof text.url === "string") {
     const again = parseRepoRef(text.url);
     if (again.key !== text.key) throw fail("E_REPO_REF", `repository reference object is inconsistent: key ${text.key} does not match url ${text.url}`, { ref: text.key, url: text.url });
@@ -126,9 +166,11 @@ export function parseRepoRef(text) {
   if (typeof text !== "string" || !text.trim()) throw fail("E_REPO_REF", "repository reference must be a non-empty string", { ref: text });
   const ref = text.trim();
   let m;
-  if ((m = /^git:([^/:@\s]+)\/(.+)$/.exec(ref))) return hostedRef(m[1], m[2], ref);
+  if ((m = /^git:([^/:@\s]+)\/(.+)$/.exec(ref))) return hostedRef(m[1], m[2], ref, { transport });
   if ((m = /^https?:\/\/([^/@\s]+)\/(.+)$/.exec(ref))) return hostedRef(m[1], m[2], ref);
-  if ((m = /^git@([^:/\s]+):(.+)$/.exec(ref))) return hostedRef(m[1], m[2], ref);
+  // ssh forms: the url is kept AS WRITTEN (user, port, host case) — it is the operator's access.
+  if ((m = /^git@([^:/\s]+):(.+)$/.exec(ref))) return hostedRef(m[1], m[2], ref, { fetchUrl: ref });
+  if ((m = /^ssh:\/\/(?:[^@/\s]+@)?([^/:@\s]+)(?::\d+)?\/(.+)$/.exec(ref))) return hostedRef(m[1], m[2], ref, { fetchUrl: ref });
   if (/^file:\/\//.test(ref)) {
     try { return localRef(fileURLToPath(ref)); } catch { throw fail("E_REPO_REF", `invalid file URL: ${ref}`, { ref }); }
   }
@@ -167,14 +209,20 @@ function gitEnv() {
 }
 
 /** Default exec dependency: runs `git <args>`; resolves { stdout, stderr } (Buffers);
- * rejects with { code, signal, killed, stderr, stdout }. Injectable via options.exec. */
+ * rejects with { code, signal, killed, stderr, stdout, timedOut, overflowed }.
+ *   timedOut   — the `timeout` kill (Node reports killed=true + our killSignal, no error.code);
+ *   overflowed — stdout/stderr exceeded `maxBuffer` (Node also kills the child, but sets
+ *                error.code = ERR_CHILD_PROCESS_STDIO_MAXBUFFER): NOT a timeout.
+ * Injectable via options.exec. */
 export function runGit(args, { cwd, maxBuffer = 16 * 1024 * 1024, timeout = GIT_TIMEOUT_MS } = {}) {
   return new Promise((resolvePromise, reject) => {
     execFile("git", args, { cwd, env: gitEnv(), timeout, maxBuffer, shell: false, encoding: "buffer", killSignal: "SIGKILL" },
       (error, stdout, stderr) => {
         if (error) {
           error.stdout = stdout; error.stderr = stderr;
-          error.timedOut = error.killed === true || error.signal === "SIGKILL";
+          error.overflowed = error.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"
+            || (Buffer.isBuffer(stdout) && stdout.length >= maxBuffer);
+          error.timedOut = !error.overflowed && (error.killed === true || error.signal === "SIGKILL");
           reject(error);
         } else resolvePromise({ stdout, stderr });
       });
@@ -186,14 +234,22 @@ function stderrText(error) {
   return Buffer.isBuffer(s) ? s.toString("utf8") : typeof s === "string" ? s : String(error?.message ?? "");
 }
 
-/** Classify a failed network git call into the contract's four reasons. */
+/** Classify a failed network git call into the contract's four reasons. A `maxBuffer`
+ * overflow is never a timeout (the child is killed in both cases; only the timeout kill
+ * counts) — it falls through to the stderr text, else "network". */
 export function classifyRemoteFailure(error) {
+  if (error?.overflowed === true || error?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") return classifyText(error) ?? "network";
   if (error?.timedOut || error?.signal === "SIGKILL" || error?.signal === "SIGTERM") return "timeout";
+  return classifyText(error) ?? "network";
+}
+
+/** The stderr-text half of classifyRemoteFailure; null when the text says nothing recognisable. */
+function classifyText(error) {
   const text = stderrText(error).toLowerCase();
   if (/authentication failed|could not read username|could not read password|permission denied|publickey|403|forbidden|terminal prompts disabled|invalid username or password|access denied|unauthori[sz]ed/.test(text)) return "auth";
   if (/repository not found|repository '.*' not found|not found|does not appear to be a git repository|no such file or directory|not our ref|unadvertised object|couldn't find remote ref|remote ref .* not found|not a valid object name|not a tree object|bad object|is not a valid revision|no such ref/.test(text)) return "not-found";
   if (/could not resolve host|connection refused|connection timed out|network is unreachable|unable to access|early eof|remote end hung up|connection reset|ssl|tls|unable to connect/.test(text)) return "network";
-  return "network";
+  return null;
 }
 
 function unreadable(ref, error, extra = {}) {
@@ -243,23 +299,34 @@ async function cacheRepo(ref, options) {
 
 function pinRef(oid) { return `refs/oats/commits/${oid}`; }
 
-/** Is <oid> present in the cache AND a commit? (`cat-file -e <oid>^{commit}` fails on a
- * missing object, a pruned store, or a tag/tree/blob.) */
-async function hasCommit(repo, oid) {
-  return repo.local(["cat-file", "-e", `${oid}^{commit}`]).then(() => true, () => false);
+/** The COMMIT <oid> peels to, when <oid> is present in the cache and is a commit or an
+ * annotated tag chain ending in one; null on a missing object, a pruned store, or a
+ * tag/tree/blob that does not peel to a commit. (`rev-parse <oid>^{commit}` peels.) */
+async function peelCommit(repo, oid) {
+  try {
+    const out = (await repo.local(["rev-parse", "--verify", "-q", `${oid}^{commit}`])).stdout.toString("utf8").trim();
+    return OID_RE.test(out) ? out : null;
+  } catch { return null; }
 }
 
 async function objectType(repo, oid) {
   try { return (await repo.local(["cat-file", "-t", oid])).stdout.toString("utf8").trim(); } catch { return null; }
 }
 
-/** Ensure <oid> (a full COMMIT OID) and all its trees/blobs are present in the cache. */
+/**
+ * Ensure <oid> (a full OID of a COMMIT, or of an annotated TAG that peels to one) and all
+ * its trees/blobs are present in the cache. → { repo, commit } where `commit` is the PEELED
+ * commit: a tag OID given as `at` is accepted, but the commit recorded everywhere is the
+ * commit it points to (fix M4). The pin is on the peeled commit; a tag object gets its own
+ * `refs/oats/tags/<oid>` pin so gc cannot break the chain either.
+ */
 async function ensureCommit(ref, oid, options) {
   const root = options.cacheDir ?? defaultCacheRoot();
   const dir = join(root, createHash("sha256").update(ref.key).digest("hex"));
   return withCacheLock(dir, async () => {
     const repo = await cacheRepo(ref, options);
-    if (await hasCommit(repo, oid)) return repo; // pinned AND present AND a commit
+    const cached = await peelCommit(repo, oid);
+    if (cached) return { repo, commit: cached }; // pinned AND present AND (peels to) a commit
     let lastError;
     for (let attempt = 0; attempt < 3; attempt++) {
       try {
@@ -273,12 +340,14 @@ async function ensureCommit(ref, oid, options) {
       }
     }
     if (lastError) throw unreadable(ref, lastError, { commit: oid });
-    if (!(await hasCommit(repo, oid))) {
+    const commit = await peelCommit(repo, oid);
+    if (!commit) {
       const type = await objectType(repo, oid);
       throw fail("E_REMOTE_UNREADABLE", `${oid} in ${ref.url} is ${type ? `a ${type}` : "missing"}, not a commit`, { url: ref.url, key: ref.key, reason: "not-found", commit: oid, type });
     }
-    await repo.local(["update-ref", pinRef(oid), oid]);
-    return repo;
+    await repo.local(["update-ref", pinRef(commit), commit]);
+    if (commit !== oid) await repo.local(["update-ref", `refs/oats/tags/${oid}`, oid]);
+    return { repo, commit };
   });
 }
 
@@ -324,12 +393,13 @@ function resolveAt(parsed, at) {
  * Never half-succeeds; never prompts. A full OID already in the cache costs no network call.
  */
 export async function observeRemote(refText, { at, ...options } = {}) {
-  const ref = parseRepoRef(refText);
+  const ref = parseRepoRef(refText, options);
   const exec = options.exec ?? runGit;
   if (at !== undefined && at !== null && typeof at !== "string") throw fail("E_REPO_REF", "at must be a string (full OID, tag or branch name)", { at });
   if (typeof at === "string" && OID_RE.test(at)) {
-    await ensureCommit(ref, at, options);
-    return { key: ref.key, url: ref.url, commit: at, ref: null, observedAt: new Date().toISOString() };
+    // A tag OID is accepted here; the commit recorded is the one it peels to (M4).
+    const { commit } = await ensureCommit(ref, at, options);
+    return { key: ref.key, url: ref.url, commit, ref: null, observedAt: new Date().toISOString() };
   }
   const wantHead = at === undefined || at === null || at === "" || at === "HEAD";
   if (!wantHead && AT_BAD_RE.test(at)) throw fail("E_REPO_REF", `at must be a full OID or a plain tag/branch name, got ${JSON.stringify(at)}`, { at });
@@ -343,8 +413,8 @@ export async function observeRemote(refText, { at, ...options } = {}) {
   const hit = resolveAt(parsed, at);
   if (!hit) throw fail("E_REMOTE_UNREADABLE", `remote ${ref.url} has no ref matching ${at ?? "HEAD"}`, { url: ref.url, key: ref.key, reason: "not-found", at: at ?? null });
   if (!OID_RE.test(hit.commit)) throw fail("E_REMOTE_UNREADABLE", `remote ${ref.url} returned a non-OID for ${at ?? "HEAD"}`, { url: ref.url, key: ref.key, reason: "not-found", at: at ?? null });
-  await ensureCommit(ref, hit.commit, options);
-  return { key: ref.key, url: ref.url, commit: hit.commit, ref: hit.ref, observedAt: new Date().toISOString() };
+  const { commit } = await ensureCommit(ref, hit.commit, options);
+  return { key: ref.key, url: ref.url, commit, ref: hit.ref, observedAt: new Date().toISOString() };
 }
 
 // ---------------------------------------------------------------------------
@@ -398,23 +468,29 @@ function assertNoCollisions(entries, ref, commit, prefix) {
   }
 }
 
-/** `git ls-tree -l -z [flags] <spec> [-- <path>]`; null when <spec> names no tree. */
-async function lsTree(repo, spec, { flags = [], path } = {}) {
+/** `git ls-tree -l -z [flags] <spec> [-- <path>]`; null when <spec> names no tree.
+ * Any other failure is E_REMOTE_UNREADABLE (reason "timeout" for the timeout kill, else
+ * "unknown") — never a raw Node/git error: enumerateRepo turns E_REMOTE_* into a problem
+ * row and would otherwise abort the whole discovery on one unexplained listing (L4). */
+async function lsTree(repo, spec, { flags = [], path, ref, commit } = {}) {
   try {
     const args = ["ls-tree", "-l", "-z", ...flags, spec];
     if (path !== undefined) args.push("--", path);
     const out = await repo.local(args, { maxBuffer: 64 * 1024 * 1024 });
     return parseLsTree(out.stdout);
   } catch (error) {
+    if (typeof error?.code === "string" && error.code.startsWith("E_")) throw error; // already an oats error
     const text = stderrText(error).toLowerCase();
     if (/not a tree object|not a valid object name|does not exist|bad object|fatal: not a tree|path .* does not exist|exists on disk, but not in/.test(text)) return null;
-    throw error;
+    const reason = error?.timedOut ? "timeout" : "unknown";
+    const why = error?.overflowed ? "listing exceeded the output budget" : (text.trim().split("\n")[0] || error?.code || error?.message || "git ls-tree failed");
+    throw fail("E_REMOTE_UNREADABLE", `cannot list ${spec}${path !== undefined ? ` -- ${path}` : ""} in ${ref?.key ?? repo.dir} (${reason}: ${why})`, { url: ref?.url ?? null, key: ref?.key ?? null, reason, commit: commit ?? null, spec, path: path ?? null, cause: error?.code ?? null, overflowed: error?.overflowed === true });
   }
 }
 
 /** Return the single ls-tree entry for <commit>:<path>, or null when absent. */
-async function entryAt(repo, commit, path) {
-  const entries = await lsTree(repo, commit, { path });
+async function entryAt(repo, commit, path, ref) {
+  const entries = await lsTree(repo, commit, { path, ref, commit });
   if (!entries) return null;
   return entries.find((e) => e.path === path) ?? null;
 }
@@ -423,12 +499,12 @@ async function entryAt(repo, commit, path) {
  * → { bytes, size } | E_REMOTE_UNREADABLE | E_REMOTE_PATH_MISSING { path } | E_REMOTE_FILE_OVERSIZE { path, size, budget }
  * A symlink at <path> is refused (E_REMOTE_TREE_UNSAFE { path, why: "symlink" }); a directory → E_REMOTE_PATH_MISSING.
  */
-export async function readRemoteFile(refText, commit, path, options = {}) {
-  const ref = parseRepoRef(refText);
-  requireCommit(commit);
+export async function readRemoteFile(refText, commitArg, path, options = {}) {
+  const ref = parseRepoRef(refText, options);
+  requireCommit(commitArg);
   const rel = normalizeTreePath(path, { allowRoot: false });
-  const repo = await ensureCommit(ref, commit, options);
-  const entry = await entryAt(repo, commit, rel);
+  const { repo, commit } = await ensureCommit(ref, commitArg, options);
+  const entry = await entryAt(repo, commit, rel, ref);
   if (!entry || entry.type !== "blob") throw fail("E_REMOTE_PATH_MISSING", `${rel} is not a file in ${ref.key}@${commit.slice(0, 12)}`, { path: rel, key: ref.key, commit });
   if (entry.mode === "120000") throw fail("E_REMOTE_TREE_UNSAFE", `${rel} is a symlink`, { path: rel, why: "symlink", key: ref.key, commit });
   if (entry.size > FILE_BUDGET) throw fail("E_REMOTE_FILE_OVERSIZE", `${rel} is ${entry.size} bytes (budget ${FILE_BUDGET})`, { path: rel, size: entry.size, budget: FILE_BUDGET, key: ref.key, commit });
@@ -442,23 +518,26 @@ export async function readRemoteFile(refText, commit, path, options = {}) {
  * → [{ path, type: "blob"|"tree", size? }] relative to <dir>, depth-bounded (depth 1 = direct children).
  * Missing dir → []. Symlinks are reported as type "symlink" so callers can skip them.
  */
-export async function listRemoteTree(refText, commit, dir, { depth = 2, ...options } = {}) {
-  const ref = parseRepoRef(refText);
-  requireCommit(commit);
+export async function listRemoteTree(refText, commitArg, dir, { depth = 2, ...options } = {}) {
+  const ref = parseRepoRef(refText, options);
+  requireCommit(commitArg);
   if (!Number.isInteger(depth) || depth < 1) throw fail("E_REPO_REF", "depth must be a positive integer", { depth });
   const rel = normalizeTreePath(dir, { allowRoot: true });
-  const repo = await ensureCommit(ref, commit, options);
+  const { repo, commit } = await ensureCommit(ref, commitArg, options);
   const spec = rel ? `${commit}:${rel}` : commit;
   if (rel) {
-    const entry = await entryAt(repo, commit, rel);
+    const entry = await entryAt(repo, commit, rel, ref);
     if (!entry || entry.type !== "tree") return [];
   }
-  const entries = await lsTree(repo, spec, { flags: ["-r", "-t"] });
+  const entries = await lsTree(repo, spec, { flags: ["-r", "-t"], ref, commit });
   if (!entries) return [];
   const result = [];
   for (const e of entries) {
-    assertSafeEntryPath(e.path, ref, commit, rel ? `${rel}/${e.path}` : e.path);
+    // Depth first, THEN the name check (L3): a hostile or merely odd name BELOW the
+    // requested depth is not part of this listing and must not blank it; a bad name AT
+    // a kept depth is still refused.
     if (e.path.split("/").length > depth) continue;
+    assertSafeEntryPath(e.path, ref, commit, rel ? `${rel}/${e.path}` : e.path);
     if (e.type === "commit") continue; // submodule gitlinks are not part of the observable tree
     const type = e.mode === "120000" ? "symlink" : e.type;
     const row = { path: e.path, type };
@@ -549,22 +628,22 @@ export function contentDigest(dir, { allowSymlinks = null } = {}) {
  * Regular files and dirs only: symlinks/submodules → E_REMOTE_TREE_UNSAFE { path, why }, total > 64 MiB → why "oversize".
  * Missing <dir> → E_REMOTE_PATH_MISSING. → { files, bytes, digest }. Atomic: staging dir + rename, nothing left on failure.
  */
-export async function fetchRemoteTree(refText, commit, dir, destDir, options = {}) {
-  const ref = parseRepoRef(refText);
-  requireCommit(commit);
+export async function fetchRemoteTree(refText, commitArg, dir, destDir, options = {}) {
+  const ref = parseRepoRef(refText, options);
+  requireCommit(commitArg);
   const rel = normalizeTreePath(dir, { allowRoot: true });
   if (typeof destDir !== "string" || !isAbsolute(destDir)) throw fail("E_REPO_REF", "destDir must be an absolute path", { destDir });
   const dest = resolve(destDir);
   let destStat = null;
   try { destStat = lstatSync(dest); } catch {}
   if (destStat) throw fail("E_REMOTE_TREE_UNSAFE", `${dest} already exists${destStat.isSymbolicLink() ? " (a symlink)" : ""}`, { path: dest, why: "exists" });
-  const repo = await ensureCommit(ref, commit, options);
+  const { repo, commit } = await ensureCommit(ref, commitArg, options);
   const spec = rel ? `${commit}:${rel}` : commit;
   if (rel) {
-    const entry = await entryAt(repo, commit, rel);
+    const entry = await entryAt(repo, commit, rel, ref);
     if (!entry || entry.type !== "tree") throw fail("E_REMOTE_PATH_MISSING", `${rel} is not a directory in ${ref.key}@${commit.slice(0, 12)}`, { path: rel, key: ref.key, commit });
   }
-  const entries = await lsTree(repo, spec, { flags: ["-r", "-t"] });
+  const entries = await lsTree(repo, spec, { flags: ["-r", "-t"], ref, commit });
   if (!entries) throw fail("E_REMOTE_PATH_MISSING", `${rel || "."} is missing in ${ref.key}@${commit.slice(0, 12)}`, { path: rel, key: ref.key, commit });
   // Inspect everything BEFORE writing anything: names, modes, types, sizes, collisions.
   let total = 0;

package/lib/resolve.mjs

@@ -27,6 +27,22 @@
  *   ⊕ workspace.defaults.capabilities ⊕ workspace.defaults.byTeam[soul.team].capabilities
  *   ⊕ soul.capabilities
  *
+ * Slot `none` (contract §3, post-0.25.0 rule): a soul's `<slot>: none` EMPTIES the slot — it drops the
+ * workspace's `defaults.<slot>` AND any capability of that layer the workspace defaults contributed
+ * (`defaults.capabilities`, `defaults.byTeam[team]`). A layer-bearing capability the SOUL ITSELF declares
+ * next to `none` is contradictory and stays E_SLOT_CONFLICT { reason: "none" } (spell `<cap>: off` to
+ * remove a default explicitly; drop the soul's own line to fill the slot).
+ *
+ * Package modules are gated twice (decision 8): the lock must carry an approval AND the approval must
+ * describe the package tree at the locked commit — `executablesDigestAt(...)` (the same computation
+ * `oats sync` approved) must equal `approved.executables`, else E_PACKAGE_UNAPPROVED
+ * { reason: "digest-mismatch", approved, executables }. An edited lock never runs unapproved hooks.
+ *
+ * Revision (decision 14 + preview): `declRevision` fingerprints the declarations (soul identity, modules
+ * with their commits/versions/manifests, slots, skills, injects); `payloadRevision` fingerprints the merged
+ * provider payloads; `revision` = hash(declRevision, payloadRevision) so a spawn decision still binds to
+ * everything, while a preview can say WHAT changed since the previous instance (declarations | payload | both).
+ *
  * Payloads (decision 14), later wins on scalars/arrays, objects deep-merge:
  *   workspace.messaging (messaging slot only) ⊕ soul.<slot> ⊕ local.settings[cap] ⊕ spawn.providers[cap]
  *
@@ -39,7 +55,7 @@ import { createHash } from "node:crypto";
 import { posix } from "node:path";
 import { oatsError as baseOatsError } from "./errors.mjs";
 import * as defaultRemote from "./remote.mjs";
-import { bindRemote, packageProviding, readPackageManifests, validateLock } from "./packages.mjs";
+import { bindRemote, executablesDigestAt, packageProviding, readPackageManifests, validateLock } from "./packages.mjs";
 
 export const RESOLUTION_API = 1;
 export const SLOTS = Object.freeze(["knowledge", "messaging", "tasks"]);
@@ -329,11 +345,37 @@ function lookupPackage(lock, name, via, soul) {
   const providing = packageProviding(lock, name);
   if (!providing) throw fail("E_PACKAGE_MISSING", `${name}: no locked package provides it — add the package to packages: and run \`oats sync\``, { ...where, locked: Object.keys(lock.packages).sort() });
   if (!providing.entry.approved || !isObject(providing.entry.approved) || typeof providing.entry.approved.executables !== "string" || !/^sha256-[0-9a-f]{64}$/.test(providing.entry.approved.executables)) {
-    throw fail("E_PACKAGE_UNAPPROVED", `${name}: package ${providing.id} v${providing.entry.version} (${short(providing.entry.commit)}) is not approved — review its executables and approve once per version`, { ...where, id: providing.id, version: providing.entry.version, commit: providing.entry.commit });
+    throw fail("E_PACKAGE_UNAPPROVED", `${name}: package ${providing.id} v${providing.entry.version} (${short(providing.entry.commit)}) is not approved — review its executables and approve once per version`, { ...where, id: providing.id, version: providing.entry.version, commit: providing.entry.commit, reason: "unapproved" });
   }
   return providing;
 }
 
+/**
+ * The approval must describe THIS tree (decision 8: the lock carries the approval next to the commit it
+ * approved). Recompute the executables digest over the package tree at entry.commit — the very computation
+ * `oats sync` approved — and require equality with approved.executables. A lock edited to another commit
+ * (same id/version, approval copied along) fails here: E_PACKAGE_UNAPPROVED { reason: "digest-mismatch" }
+ * naming both digests and the executables that would have run. Cached per (remote, repo, commit, path).
+ */
+async function assertApprovalDescribesTree({ remote, remoteOptions, ref, id, entry, name, via, soul }) {
+  const where = { capability: name, from: "package", soul: soul.name, via, id, version: entry.version, commit: entry.commit, path: entry.path };
+  let computed;
+  try { computed = await executablesDigestAt(remote, ref, entry.commit, entry.path, Array.isArray(entry.capabilities) ? entry.capabilities : null, { remoteOptions }); }
+  catch (e) {
+    if (e?.code === "E_PACKAGE_INTEGRITY" && (e.details ?? e.provenance)?.why === "capabilities") {
+      const d = e.details ?? e.provenance;
+      throw fail("E_PACKAGE_INTEGRITY", `${name}: the lock says package ${id} v${entry.version} provides [${d.locked.join(", ")}], but ${entry.path}/oats-package.json at ${short(entry.commit)} declares [${d.listed.join(", ")}]`, { ...where, why: "capabilities", listed: d.listed, locked: d.locked });
+    }
+    throw e;
+  }
+  if (computed.digest !== entry.approved.executables) {
+    throw fail("E_PACKAGE_UNAPPROVED",
+      `${name}: package ${id} v${entry.version} @ ${short(entry.commit)}: the recorded approval ${entry.approved.executables} does not describe this tree's executables (${computed.digest}) — the lock was edited or the approval copied from another commit; run \`oats sync\` and approve what it shows`,
+      { ...where, reason: "digest-mismatch", approved: entry.approved.executables, executables: computed.digest, targets: computed.executables.map((x) => `${x.capability}: ${x.kind} ${x.name} → ${x.target}`) });
+  }
+  return computed;
+}
+
 /** The repo ref a locked package is read from: the lock's recorded url, else the catalog's url for catalog ids, else the key for git refs. */
 export function packageRef(id, entry, catalog, remote) {
   const cat = isObject(catalog) ? (isObject(catalog.packages) && !("url" in catalog.packages) ? catalog.packages : catalog) : {};
@@ -421,6 +463,7 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
   }
   if (!isObject(spawn)) throw new TypeError("resolveSoul: spawn must be an object");
   if (lock !== null && lock !== undefined) validateLock(lock); // E_LOCK_SCHEMA: a lock passed in memory meets the same bar as one read from disk
+  const rawRemote = injected ?? defaultRemote; // identity for the per-process digest cache (bound copies are per call)
   const remote = remoteOf({ remote: injected, remoteOptions });
   const workspace = isObject(discovery?.workspace) ? discovery.workspace : null;
   assertSoulDiscovered(discovery, soulEntry);
@@ -436,27 +479,38 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
   const modules = [];
   const skills = [];
   const injects = [];
+  // Slot `none` (L1 rule): a layer-bearing capability the WORKSPACE DEFAULTS contributed for a slot the soul
+  // empties is dropped here, before any lookup — the soul asked for no <slot> and never named it. A layer
+  // is known only from the manifest, so a member capability is peeked at in discovery and a package one at
+  // its lock entry's manifest; a soul-declared one is never dropped (it is a conflict, judged below).
+  const emptied = new Set(SLOTS.filter((slot) => definition[slot] === "none"));
   for (const { name, from, via } of declared) {
     let module;
     if (from === "package") {
       const { id, entry } = lookupPackage(lock, name, via, soul);
       const ref = packageRef(id, entry, catalog, remote);
       const details = { capability: name, id, version: entry.version, commit: entry.commit, path: entry.path };
+      // M3: the approval must describe the tree at entry.commit (the digest `oats sync` approved), else refuse.
+      await assertApprovalDescribesTree({ remote: rawRemote, remoteOptions, ref, id, entry, name, via, soul });
       const { capabilities } = await readPackageManifests(remote, ref, entry.commit, entry.path, details);
       const cap = capabilities.find((c) => c.name === name);
       if (!cap) throw fail("E_PACKAGE_INTEGRITY", `${name}: the lock says package ${id} v${entry.version} provides it, but ${entry.path}/oats-package.json at ${short(entry.commit)} does not`, { ...details, listed: capabilities.map((c) => c.name) });
+      const layer = layerOf(cap.manifest);
+      if (layer && emptied.has(layer) && via !== "soul") continue;
       module = {
         name, from: { kind: "package", package: id, version: entry.version, commit: entry.commit, integrity: entry.integrity, repoKey: remote.parseRepoRef(ref).key },
-        manifest: clone(cap.manifest), layer: layerOf(cap.manifest), private: cap.manifest.private === true, dir: cap.dir,
+        manifest: clone(cap.manifest), layer, private: cap.manifest.private === true, dir: cap.dir,
       };
       const missing = (raw, why, text) => fail("E_PACKAGE_MANIFEST", `${name} (package ${id} v${entry.version}) ${text}`, { ...details, skill: raw, why });
       skills.push(...await enumerateSkills({ remote, ref, commit: entry.commit, dir: cap.dir, manifest: cap.manifest, moduleName: name, missing }));
     } else {
       const { row, cap } = lookupMember(discovery, soul, name, from, via, lock);
+      const layer = layerOf(cap.manifest);
+      if (layer && emptied.has(layer) && via !== "soul") continue;
       const ref = memberRef(discovery, remote, cap.repoKey);
       module = {
         name, from: { kind: "member", repoKey: cap.repoKey, commit: cap.commit ?? row.commit },
-        manifest: clone(cap.manifest), layer: layerOf(cap.manifest), private: cap.private === true, dir: cap.path,
+        manifest: clone(cap.manifest), layer, private: cap.private === true, dir: cap.path,
       };
       const missing = (raw, why, text) => fail("E_CAPABILITY_MISSING", `${name} (${cap.repoKey}@${short(module.from.commit)}) ${text}`, { capability: name, repoKey: cap.repoKey, commit: module.from.commit, skill: raw, why });
       skills.push(...await enumerateSkills({ remote, ref, commit: module.from.commit, dir: cap.path, manifest: cap.manifest, listing: cap.listing, moduleName: name, missing }));
@@ -469,7 +523,10 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
     modules.push(module);
   }
 
-  // Slots (decision: a resolved capability whose manifest has layer X fills slot X; two → conflict; soul `none` empties).
+  // Slots: a resolved capability whose manifest has layer X fills slot X; two → conflict. A soul `none` has
+  // already emptied the slot of every workspace-default contribution (above); what remains under `none` is
+  // the soul's own contradiction → E_SLOT_CONFLICT { reason: "none" } — judged FIRST, so it is never reported
+  // as a two-module clash.
   const slots = { knowledge: null, messaging: null, tasks: null };
   const viaOf = new Map(declared.map((d) => [d.name, d.via]));
   for (const m of modules) {
@@ -480,8 +537,8 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
       throw fail("E_SLOT_CONFLICT", `slot ${slotDefault}: defaults.${slotDefault} names ${m.name}, whose manifest declares layer ${m.layer ? show(m.layer) : "none"} — a slot default must be a ${slotDefault}-layer capability`, { slot: slotDefault, modules: [m.name], soul: soul.name, reason: "layer-mismatch", layer: m.layer });
     }
     if (!m.layer) continue;
+    if (emptied.has(m.layer)) throw fail("E_SLOT_CONFLICT", `slot ${m.layer}: the soul says ${m.layer}: none but itself names ${m.name}, which declares layer ${m.layer} — drop one of the two (a workspace default of that layer would have been dropped by none; this one is the soul's own)`, { slot: m.layer, modules: [m.name], soul: soul.name, reason: "none", via });
     if (slots[m.layer]) throw fail("E_SLOT_CONFLICT", `slot ${m.layer}: both ${slots[m.layer]} and ${m.name} declare layer ${m.layer}; a soul fills each slot with at most one capability`, { slot: m.layer, modules: [slots[m.layer], m.name], soul: soul.name });
-    if (definition[m.layer] === "none") throw fail("E_SLOT_CONFLICT", `slot ${m.layer}: the soul says ${m.layer}: none but names ${m.name}, which declares layer ${m.layer}`, { slot: m.layer, modules: [m.name], soul: soul.name, reason: "none" });
     slots[m.layer] = m.name;
   }
 
@@ -544,8 +601,13 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
   modules.sort((a, b) => byCodepoint(a.name, b.name));
   skills.sort((a, b) => byCodepoint(a.module, b.module) || byCodepoint(a.name, b.name));
   injects.sort((a, b) => byCodepoint(a.module, b.module));
-  const body = { resolutionApi: RESOLUTION_API, soul, modules, slots, payloads, skills, injects };
-  return deepFreeze({ ...body, revision: revisionOf(body) });
+  // L6: two fingerprints — declarations (what is composed, at which commits/versions) and payload (the merged
+  // provider settings) — so a preview can say what changed; `revision` binds both, exactly as before.
+  const decl = { resolutionApi: RESOLUTION_API, soul, modules, slots, skills, injects };
+  const declRevision = revisionOf(decl);
+  const payloadRevision = revisionOf(payloads);
+  const revision = revisionOf({ declRevision, payloadRevision });
+  return deepFreeze({ ...decl, payloads, declRevision, payloadRevision, revision });
 }
 
 function layerOf(manifest) {

package/lib/workspace.mjs

@@ -159,10 +159,28 @@ export function validateAgainst(schema, value, { root = schema, path = "" } = {}
 /* ───────────────────────────── domain rules ───────────────────────────── */
 
 const ABSOLUTE_PATH = /^(?:\/|\\\\|[A-Za-z]:[\\/])/;
-function* strings(value, path = "") {
-  if (typeof value === "string") yield [path, value];
-  else if (Array.isArray(value)) for (let i = 0; i < value.length; i++) yield* strings(value[i], `${path}/${i}`);
-  else if (isObject(value)) for (const [k, v] of Object.entries(value)) yield* strings(v, `${path}/${pointerKey(k)}`);
+/** The workspace file's REF/PATH fields — the only values the absolute-path refusal applies to (contract §2,
+ * Phase B: "absolute paths" means bare filesystem paths as VALUES that stand for a repo or a path inside one;
+ * host state belongs in oats-local.yaml). Free text (`teams.*.description`) and the opaque provider payload
+ * (`messaging`, incl. `byTeam.*`) are never scanned: a description may mention `/srv`, a provider may
+ * legitimately carry a socket path or a URL, and neither is a place the kernel resolves.
+ * → [[path, value]] for members[], packages.*, stores.*, external[].source|soul, defaults.<slot|capabilities>.*.from,
+ *   defaults.byTeam.*.capabilities.*.from */
+function* refFields(value) {
+  if (Array.isArray(value.members)) for (let i = 0; i < value.members.length; i++) if (typeof value.members[i] === "string") yield [`/members/${i}`, value.members[i]];
+  if (isObject(value.packages)) for (const [id, v] of Object.entries(value.packages)) if (typeof v === "string") yield [`/packages/${pointerKey(id)}`, v];
+  if (isObject(value.stores)) for (const [name, v] of Object.entries(value.stores)) if (typeof v === "string") yield [`/stores/${pointerKey(name)}`, v];
+  if (Array.isArray(value.external)) for (let i = 0; i < value.external.length; i++) {
+    const entry = value.external[i];
+    if (!isObject(entry)) continue;
+    for (const f of ["source", "soul"]) if (typeof entry[f] === "string") yield [`/external/${i}/${f}`, entry[f]];
+  }
+  if (isObject(value.defaults)) {
+    const d = value.defaults;
+    const froms = function* (caps, path) { if (isObject(caps)) for (const [name, choice] of Object.entries(caps)) if (isObject(choice) && typeof choice.from === "string") yield [`${path}/${pointerKey(name)}/from`, choice.from]; };
+    for (const slot of ["knowledge", "messaging", "tasks", "capabilities"]) yield* froms(d[slot], `/defaults/${slot}`);
+    if (isObject(d.byTeam)) for (const [label, team] of Object.entries(d.byTeam)) yield* froms(team?.capabilities, `/defaults/byTeam/${pointerKey(label)}/capabilities`);
+  }
 }
 function refKey(remote, ref) {
   return remote.parseRepoRef(ref).key;
@@ -182,8 +200,9 @@ export function validateWorkspace(value, { remote = defaultRemote } = {}) {
   const problems = validateAgainst(schemaFor("workspace"), value);
   if (!isObject(value)) return problems;
   if (value.schemaVersion !== 2) return problems;
-  for (const [path, s] of strings(value)) {
-    if (ABSOLUTE_PATH.test(s)) problems.push({ path, message: `absolute paths are refused in the workspace file (${show(s)}); host paths belong in oats-local.yaml` });
+  // Absolute-path refusal applies to REF/PATH fields only (L2): never to descriptions or the provider payload.
+  for (const [path, s] of refFields(value)) {
+    if (ABSOLUTE_PATH.test(s)) problems.push({ path, message: `absolute paths are refused in the workspace file (${show(s)}); host paths belong in oats-local.yaml (a local remote is a repo ref: file:///… or git:/abs/bare.git@<ref>)` });
   }
   // packages: exactly two value forms (contract §2 non-collapse rule) — a catalog version or git:<repo>@<ref>.
   if (isObject(value.packages)) for (const [id, v] of Object.entries(value.packages)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",