@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/runtime/packages/contributions.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * The contribution seam (122 IC-013). A point's owner calls `contributionsFor(point, version)` inside its own
+ * loader (`loadProtocols` for the preset points); there is no shared loader for all registries. It returns the
+ * entries of `active` packages only, each one through the point's validator, in ascending `qualifiedId` order.
+ * A reserved point, an undeclared point or an unsupported version is a programming error and throws; a package
+ * fault never does (FR-009): the entry is left out and, when the caller passes `problems`, named there.
+ *
+ * First-party entries are trusted at runtime and verified at release (IC-015), so they go through the validator
+ * in core mode, which reads only the registries under `core/registry/`; the package-mode extras (read-only
+ * agents, comparability) are checked by guard G68. A third-party entry goes through `judgePackagePreset`, the
+ * package-mode validator `check` runs too (IC-014), so the two cannot disagree; its qualified id is
+ * `<package>.<local id>` (IC-003) and it is `firstParty: false`. Each package is judged alone: a fault in one
+ * leaves the others' entries in (FR-009).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+const { packageView } = require('./view.js');
+const { loadPoints, POINT_VALIDATORS } = require('./points.js');
+const { MANIFEST_FILE, judgePackagePreset, coreAgents } = require('./manifest.js');
+const { loadCoreProtocols, lensIds } = require('../review/protocols.js');
+
+const PRESET_KIND                         = { 'review-preset': 'review', 'debate-preset': 'debate' };
+
+/**
+ * `Array<{ qualifiedId, localId, packageId, firstParty, data, dir, provenance: { contentDigest, source } }>`.
+ * Options: `view` (a package view; default: the view of `repoRoot`, built with `homeDir`, `env`, `projectRoot` and
+ * `tmpDir` when given), `repoRoot`, `fsImpl`, `protocols` (the core registry, to skip a re-read), `problems` (an
+ * array that collects one message per left-out entry).
+ */
+function contributionsFor(pointId        , pointVersion        , { view, repoRoot = REPO_ROOT, fsImpl = fs, protocols, problems, homeDir, env, projectRoot, tmpDir }      = {})        {
+  const loaded = loadPoints({ repoRoot, fsImpl });
+  if (!loaded.ok) return []; // no point registry, no package: the view reports it
+  const point = loaded.registry.points.find((p     ) => p.id === pointId);
+  if (!point) throw new Error(`contributionsFor: point '${pointId}' is not declared`);
+  if (point.status !== 'open') throw new Error(`contributionsFor: point '${pointId}' is ${point.status} and opens with ${point.opensWith}`);
+  if (!point.versions.includes(pointVersion)) throw new Error(`contributionsFor: point '${pointId}' has no version ${pointVersion} (supported: ${point.versions.join(', ')})`);
+
+  const skip = (qualified        , why        )       => { problems?.push(`${pointId} contribution '${qualified}' is left out: ${why}`); };
+  const validator = POINT_VALIDATORS[point.validator];
+  let context      = null;
+  let core      = null;
+  const coreRegistry = ()      => {
+    core ??= protocols ? { ok: true, registry: protocols } : loadCoreProtocols({ repoRoot, fsImpl });
+    return core;
+  };
+  const out        = [];
+  for (const pkg of (view ?? packageView({ repoRoot, fsImpl, homeDir, env, projectRoot, tmpDir })).packages) {
+    if (pkg.state !== 'active' || !pkg.storeDir) continue;
+    let entries       ;
+    try {
+      entries = JSON.parse(fsImpl.readFileSync(path.join(pkg.storeDir, MANIFEST_FILE), 'utf8')).contributions;
+    } catch (error     ) {
+      problems?.push(`package ${pkg.id} is left out: ${MANIFEST_FILE} cannot be read (${error.message})`);
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.point !== pointId || entry.version !== pointVersion) continue;
+      const qualified         = pkg.firstParty ? entry.id /* the first-party package keeps bare built-in ids (IC-003) */ : `${pkg.id}.${entry.id}`;
+      if (point.entry !== 'file' || typeof entry.file !== 'string') { skip(qualified, 'not a file entry'); continue; }
+      const file = path.resolve(pkg.storeDir, entry.file);
+      if (!file.startsWith(path.resolve(pkg.storeDir) + path.sep)) { skip(qualified, `${entry.file} leaves the package`); continue; }
+      let data     ;
+      try {
+        data = JSON.parse(fsImpl.readFileSync(file, 'utf8'));
+      } catch (error     ) {
+        skip(qualified, `${entry.file} cannot be read as JSON (${error.message})`);
+        continue;
+      }
+      if (PRESET_KIND[pointId] && !coreRegistry().ok) { skip(qualified, 'the core protocol registry is unusable'); continue; }
+      if (pkg.firstParty) {
+        context ??= { lensIds: lensIds(core.registry), hardRoundCap: core.registry.hardRoundCap };
+        const errors           = validator(entry.id, data, context);
+        if (errors.length > 0) { skip(qualified, errors.join('; ')); continue; }
+      } else if (PRESET_KIND[pointId]) {
+        const judged = judgePackagePreset(point.validator, entry.id, data, { protocols: core.registry, agents: coreAgents(repoRoot, fsImpl) });
+        const errors = [...(judged.depth ? [`presets.${entry.id}.depth is not allowed in a package preset`] : []), ...judged.errors];
+        if (errors.length === 0 && !judged.comparable) errors.push(`${qualified} dominates no core ${judged.kind} preset`);
+        if (errors.length > 0) { skip(qualified, errors.join('; ')); continue; }
+      } else {
+        const errors           = validator(entry.id, data, { packageId: pkg.id });
+        if (errors.length > 0) { skip(qualified, errors.join('; ')); continue; }
+      }
+      out.push({
+        qualifiedId: qualified, localId: entry.id, packageId: pkg.id, firstParty: pkg.firstParty, data, dir: null,
+        provenance: { contentDigest: pkg.contentDigest, source: pkg.source },
+      });
+    }
+  }
+  return out.sort((a, b) => (a.qualifiedId < b.qualifiedId ? -1 : a.qualifiedId > b.qualifiedId ? 1 : 0));
+}
+
+/**
+ * The preset ids the bundled packages contribute, by kind, for `validateProtocols` (an `order` entry may name
+ * one without `presets` holding it). Read from the manifests whatever their state, so an incompatible package
+ * still names its ids; `opaque` is true when some bundled package names none (point registry or manifest
+ * unreadable), because then an unresolved `order` id may be one of its own.
+ */
+function firstPartyPresets({ repoRoot = REPO_ROOT, fsImpl = fs, view }      = {})                                                          {
+  const result = { review: []            , debate: []            , opaque: false };
+  const packages = (view ?? packageView({ repoRoot, fsImpl })).packages;
+  if (packages.length === 0 && !loadPoints({ repoRoot, fsImpl }).ok) result.opaque = true;
+  for (const pkg of packages) {
+    for (const c of pkg.contributions) {
+      const kind = PRESET_KIND[c.point];
+      if (kind) (result       )[kind].push(c.qualifiedId);
+    }
+    if (pkg.contributions.length === 0) result.opaque = true;
+  }
+  return result;
+}
+
+module.exports = { contributionsFor, firstPartyPresets };

package/src/runtime/packages/digest.js

@@ -0,0 +1,132 @@
+'use strict';
+
+/**
+ * Package tree rules and digests (122 IC-005). `walkTree` applies the tree rules and returns IC-004 findings
+ * beside the regular files it saw; `contentDigest` hashes a clean tree; `capabilityDigest` hashes what the
+ * manifest lets the package do. Nothing here writes. Per-file hashing is sha256 hex of the bytes, as in
+ * `src/adapters/copy-tree.js`; that module is not required here because it pulls in the adapter layer.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const SEGMENT = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
+const SEGMENT_GRAMMAR = '^[A-Za-z0-9_][A-Za-z0-9._-]*$ (no leading dot)';
+const CONTENT_HEADER = 'doflow-package-content-v1\n';
+const CAPABILITY_HEADER = 'doflow-package-capability-v1\n';
+
+const sha256 = (data     )         => crypto.createHash('sha256').update(data).digest('hex');
+
+                                                                          
+
+/** Key-sorted JSON, the canonical form of `fingerprint` in `src/state/index.js`. */
+function canonicalJson(value     )         {
+  const stable = (v     )      => {
+    if (Array.isArray(v)) return v.map(stable);
+    if (!v || typeof v !== 'object') return v;
+    return Object.fromEntries(Object.keys(v).sort().map((key) => [key, stable(v[key])]));
+  };
+  return JSON.stringify(stable(value));
+}
+
+function compareBytes(a        , b        )         {
+  const x = Buffer.from(a);
+  const y = Buffer.from(b);
+  for (let i = 0; i < Math.min(x.length, y.length); i++) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
+  return x.length === y.length ? 0 : x.length < y.length ? -1 : 1;
+}
+
+/**
+ * Walk `root` under the IC-005 tree rules. Never throws on content: a rule break is a finding, and a symlink
+ * or special file is reported and not entered. `files` lists the regular files in ascending bytewise order of
+ * their POSIX relative path. `limits` is `{ files, bytes, fileBytes, pathLength }`.
+ */
+function walkTree(root        , limits     , { packageId = null, fsImpl = fs }      = {})                                         {
+  const findings        = [];
+  const files             = [];
+  const add = (field        , code        , message        , allowed     ) =>
+    findings.push({ package: packageId, field, code, severity: 'error', message, allowed });
+  let total = 0;
+  let stop = false;
+
+  const visit = (dir        , relDir        )       => {
+    let entries       ;
+    try {
+      entries = fsImpl.readdirSync(dir, { withFileTypes: true });
+    } catch (error     ) {
+      add(`tree.${relDir || '.'}`, 'file-missing', `cannot read directory: ${error.message}`, 'a readable directory');
+      return;
+    }
+    entries.sort((a, b) => compareBytes(a.name, b.name));
+    for (const entry of entries) {
+      if (stop) return;
+      const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+      const field = `tree.${rel}`;
+      if (entry.isSymbolicLink()) { add(field, 'symlink', `${rel} is a symbolic link`, 'regular files and directories only'); continue; }
+      if (!entry.isFile() && !entry.isDirectory()) {
+        add(field, 'special-file', `${rel} is a device, socket or FIFO`, 'regular files and directories only');
+        continue;
+      }
+      if (!SEGMENT.test(entry.name)) {
+        add(field, 'bad-type', `${rel}: segment '${entry.name}' breaks the path grammar`, SEGMENT_GRAMMAR);
+        continue;
+      }
+      if (rel.length > limits.pathLength) {
+        add(field, 'too-large', `${rel} is ${rel.length} characters long`, `a relative path of at most ${limits.pathLength} characters`);
+        continue;
+      }
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) { visit(abs, rel); continue; }
+      if (files.length >= limits.files) {
+        add('tree', 'too-many-files', `the package holds more than ${limits.files} files`, `at most ${limits.files} files`);
+        stop = true;
+        return;
+      }
+      const stat = fsImpl.lstatSync(abs);
+      if (stat.size > limits.fileBytes) {
+        add(field, 'too-large', `${rel} is ${stat.size} bytes`, `at most ${limits.fileBytes} bytes per file`);
+      }
+      total += stat.size;
+      files.push({ rel, abs, size: stat.size, exec: (stat.mode & 0o111) !== 0 });
+    }
+  };
+  visit(root, '');
+  if (total > limits.bytes) add('tree', 'too-large', `the package holds ${total} bytes`, `at most ${limits.bytes} bytes in total`);
+  files.sort((a, b) => compareBytes(a.rel, b.rel));
+  return { files, findings };
+}
+
+/** Content digest of a walked file list (IC-005): header, then `<path>\0<x>\0<sha256>\n` per file in bytewise path order. */
+function digestFiles(files            , fsImpl      = fs)         {
+  const hash = crypto.createHash('sha256').update(CONTENT_HEADER);
+  for (const file of [...files].sort((a, b) => compareBytes(a.rel, b.rel))) {
+    hash.update(`${file.rel}\0${file.exec ? '1' : '0'}\0${sha256(fsImpl.readFileSync(file.abs))}\n`);
+  }
+  return hash.digest('hex');
+}
+
+/** `contentDigest(dir)`: the IC-005 digest of a package directory. Throws when the tree breaks a tree rule. */
+function contentDigest(dir        , { limits = { files: 512, bytes: 4194304, fileBytes: 262144, pathLength: 200 }, fsImpl = fs }      = {})         {
+  const { files, findings } = walkTree(dir, limits, { fsImpl });
+  if (findings.length > 0) throw new Error(`cannot digest ${dir}: ${findings.map((f) => `${f.code} ${f.field}`).join(', ')}`);
+  return digestFiles(files, fsImpl);
+}
+
+/**
+ * Capability digest (IC-005): what the manifest lets the package do. `tiers` maps a point id to its tier. A
+ * contribution's `qualifiedId` is always `<package id>.<local id>`; `programs` are passed through sorted by id
+ * (the IC-018 normalization arrives with the first executable point).
+ */
+function capabilityDigest(manifest     , { trustPolicyVersion, tiers }                                                               )         {
+  const contributions = (manifest.contributions ?? []).map((c     ) => ({
+    point: c.point, version: c.version, qualifiedId: `${manifest.id}.${c.id}`, tier: tiers[c.point] ?? null,
+  })).sort((a     , b     ) => compareBytes(a.point, b.point) || compareBytes(a.qualifiedId, b.qualifiedId));
+  const programs = [...(manifest.programs ?? [])].sort((a     , b     ) => compareBytes(String(a.id), String(b.id)));
+  const body = canonicalJson({
+    trustPolicyVersion, id: manifest.id, version: manifest.version, doflow: manifest.doflow, contributions, programs,
+  });
+  return sha256(CAPABILITY_HEADER + body);
+}
+
+module.exports = { walkTree, digestFiles, contentDigest, capabilityDigest, canonicalJson, SEGMENT, SEGMENT_GRAMMAR };

package/src/runtime/packages/fetch.js

@@ -0,0 +1,182 @@
+'use strict';
+
+/**
+ * Pin and fetch IC-022 git sources by commit and npm sources by exact version plus SHA-512
+ * integrity using argv arrays with `shell: false`. Git hooks are off, `protocol.file.allow=never`,
+ * and `GIT_TERMINAL_PROMPT=0`. npm pack always receives `--ignore-scripts`; UNVERIFIED: whether
+ * `npm pack` of a registry spec runs lifecycle scripts. Fetching uses no checkout or submodules;
+ * DoFlow writes no file and tools write only inside the caller's empty staging directory.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+const { loadPoints } = require('./points.js');
+const { readTar } = require('./tar.js');
+const { parseSemVer, compareSemVer } = require('../../helper/semver.js');
+const INTEGRITY = /^sha512-[A-Za-z0-9+/]+={0,2}$/u;
+// The location and repository variables of `git rev-parse --local-env-vars` (git 2.50), plus GIT_ALLOW_PROTOCOL,
+// which overrides `-c protocol.file.allow=never`. Hardcoded so no git process is spawned to compute it.
+// GIT_CONFIG, GIT_CONFIG_PARAMETERS and GIT_CONFIG_COUNT (with its KEY_n/VALUE_n pairs) are left out on purpose:
+// CI injects auth headers and `insteadOf` rewrites for private package hosts through them, and the `-c` guard
+// below still wins over them.
+const GIT_LOCATION_KEYS = Object.freeze([
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_OBJECT_DIRECTORY', 'GIT_DIR', 'GIT_WORK_TREE', 'GIT_IMPLICIT_WORK_TREE',
+  'GIT_GRAFT_FILE', 'GIT_INDEX_FILE', 'GIT_NO_REPLACE_OBJECTS', 'GIT_REPLACE_REF_BASE', 'GIT_PREFIX',
+  'GIT_SHALLOW_FILE', 'GIT_COMMON_DIR', 'GIT_ALLOW_PROTOCOL',
+]);
+
+function limits()      {
+  const loaded = loadPoints();
+  if (!loaded.ok) throw new Error(loaded.errors.join('; '));
+  return loaded.registry.limits;
+}
+
+function finding(code        , message        )      {
+  return { package: null, field: 'source', code, severity: 'error', message, allowed: 'a fetchable pinned git or npm source' };
+}
+
+function runGit(args          , { env, timeoutMs = 120000, cwd, maxBytes }     )      {
+  const gitEnv = { ...env };
+  for (const key of GIT_LOCATION_KEYS) delete gitEnv[key];
+  return spawnSync('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'protocol.file.allow=never', ...args], {
+    shell: false, cwd, env: { ...gitEnv, GIT_TERMINAL_PROMPT: '0' }, encoding: 'buffer',
+    timeout: timeoutMs, maxBuffer: 2 * maxBytes + 1048576,
+  });
+}
+
+function reason(result     , command = 'git')         {
+  const stderr = result?.stderr ? result.stderr.toString('utf8').split(/\r?\n/u)[0].slice(0, 200) : '';
+  return stderr || result?.error?.message?.slice(0, 200) || `${command} command failed`;
+}
+
+function runNpm(args          , { env, timeoutMs = 120000, maxBytes }     )      {
+  return spawnSync('npm', args, {
+    shell: false, env, encoding: 'buffer', timeout: timeoutMs, maxBuffer: 2 * maxBytes + 1048576,
+  });
+}
+
+function pinGit(source     , { env, timeoutMs }     )      {
+  const maxBytes = limits().bytes;
+  if (/^[0-9a-fA-F]{40}$/u.test(source.ref)) {
+    const pinned = { type: 'git', url: source.url, commit: source.ref, ...(source.path === undefined ? {} : { path: source.path }) };
+    return { ok: true, pinned };
+  }
+  const result = runGit(['ls-remote', source.url, source.ref], { env, timeoutMs, maxBytes });
+  if (result.status !== 0) return { ok: false, finding: finding('source-unpinned', reason(result)) };
+  const rows = result.stdout.toString('utf8').split(/\r?\n/u).map((line        ) => line.split('\t'));
+  const refs = [
+    `refs/tags/${source.ref}^{}`, `refs/tags/${source.ref}`, `refs/heads/${source.ref}`, source.ref,
+  ];
+  for (const ref of refs) {
+    const row = rows.find((parts          ) => parts[1] === ref && /^[0-9a-fA-F]{40}$/u.test(parts[0]));
+    if (row) return { ok: true, pinned: { type: 'git', url: source.url, commit: row[0], ...(source.path === undefined ? {} : { path: source.path }) } };
+  }
+  return { ok: false, finding: finding('source-unpinned', `ref ${source.ref} not found`) };
+}
+
+function fetchGit(pinned     , { stagingDir, env, limits: treeLimits, timeoutMs }     )      {
+  const fail = (message        )      => ({ ok: false, findings: [finding('source-unpinned', message)] });
+  if (!/^[0-9a-fA-F]{40}$/u.test(pinned?.commit ?? '')) {
+    return { ok: false, findings: [finding('bad-type', 'pinned git commit must be 40 hexadecimal characters')] };
+  }
+  try {
+    if (!fs.statSync(stagingDir).isDirectory() || fs.readdirSync(stagingDir).length !== 0) {
+      return { ok: false, findings: [finding('bad-type', 'staging directory must exist and be empty')] };
+    }
+  } catch { return { ok: false, findings: [finding('bad-type', 'staging directory must exist and be empty')] }; }
+  const maxBytes = treeLimits.bytes;
+  for (const args of [
+    ['init', '-q'], ['remote', 'add', 'origin', pinned.url], ['fetch', '--depth', '1', '--no-tags', 'origin', pinned.commit],
+  ]) {
+    const result = runGit(args, { env, timeoutMs, cwd: stagingDir, maxBytes });
+    if (result.status !== 0) return fail(reason(result));
+  }
+  const args = ['archive', '--format=tar', pinned.commit, ...(pinned.path ? [pinned.path] : [])];
+  const result = runGit(args, { env, timeoutMs, cwd: stagingDir, maxBytes });
+  if (result.status !== 0) return fail(reason(result));
+  const archive = readTar(result.stdout, { limits: treeLimits, stripPrefix: pinned.path ? `${pinned.path}/` : undefined });
+  if (!archive.ok) return { ok: false, findings: archive.findings };
+  return { ok: true, pinned, files: archive.files };
+}
+
+function pinNpm(source     , { env, timeoutMs }     )      {
+  const maxBytes = limits().bytes;
+  const result = runNpm(['view', `${source.name}@${source.version}`, 'version', 'dist.integrity', '--json'], {
+    env, timeoutMs, maxBytes,
+  });
+  if (result.status !== 0) return { ok: false, finding: finding('source-unpinned', reason(result, 'npm')) };
+
+  let response     ;
+  try { response = JSON.parse(result.stdout.toString('utf8')); }
+  catch { return { ok: false, finding: finding('source-unpinned', 'npm view answered no valid version and integrity') }; }
+  const entries = Array.isArray(response) ? response : [response];
+  const versions = entries.filter((entry     ) => typeof entry?.version === 'string' && parseSemVer(entry.version) !== null);
+  if (versions.length === 0) {
+    return { ok: false, finding: finding('source-unpinned', `no version of ${source.name} matches ${source.version}`) };
+  }
+  const valid = versions.filter((entry     ) => typeof entry['dist.integrity'] === 'string' && INTEGRITY.test(entry['dist.integrity']));
+  if (valid.length === 0) {
+    return { ok: false, finding: finding('source-unpinned', 'npm view answered no valid version and integrity') };
+  }
+  let selected = valid[0];
+  for (const entry of valid.slice(1)) {
+    if (compareSemVer(entry.version, selected.version) > 0) selected = entry;
+  }
+  return {
+    ok: true,
+    pinned: { type: 'npm', name: source.name, version: selected.version, integrity: selected['dist.integrity'] },
+  };
+}
+
+function fetchNpm(pinned     , { stagingDir, env, limits: treeLimits, timeoutMs }     )      {
+  const fail = (code        , message        )      => ({ ok: false, findings: [finding(code, message)] });
+  if (pinned?.type !== 'npm' || typeof pinned?.name !== 'string'
+    || !/^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/u.test(pinned.name)) {
+    return fail('bad-type', 'pinned npm package name is invalid');
+  }
+  if (typeof pinned.version !== 'string' || parseSemVer(pinned.version) === null) {
+    return fail('bad-type', 'pinned npm version must be an exact semver');
+  }
+  if (typeof pinned.integrity !== 'string' || !INTEGRITY.test(pinned.integrity)) {
+    return fail('bad-type', 'pinned npm integrity must be a sha512 value');
+  }
+  try {
+    if (!fs.statSync(stagingDir).isDirectory() || fs.readdirSync(stagingDir).length !== 0) {
+      return fail('bad-type', 'staging directory must exist and be empty');
+    }
+  } catch { return fail('bad-type', 'staging directory must exist and be empty'); }
+
+  const result = runNpm([
+    'pack', `${pinned.name}@${pinned.version}`, '--ignore-scripts', '--json', '--pack-destination', stagingDir,
+  ], { env, timeoutMs, maxBytes: treeLimits.bytes });
+  if (result.status !== 0) return fail('source-unpinned', reason(result, 'npm'));
+
+  let packed     ;
+  try { packed = JSON.parse(result.stdout.toString('utf8')); }
+  catch { return fail('source-unpinned', 'npm pack did not return valid JSON'); }
+  const filename = Array.isArray(packed) ? packed[0]?.filename : undefined;
+  if (typeof filename !== 'string' || filename.length === 0) {
+    return fail('source-unpinned', 'npm pack did not return a tarball filename');
+  }
+  const tarball = path.join(stagingDir, path.basename(filename));
+  let stat     ;
+  try { stat = fs.statSync(tarball); }
+  catch { return fail('source-unpinned', 'npm pack tarball is missing'); }
+  if (!stat.isFile()) return fail('source-unpinned', 'npm pack tarball is not a file');
+  if (stat.size > treeLimits.bytes + (treeLimits.files + 64) * 1024) {
+    return fail('too-large', 'npm pack tarball exceeds the bounded archive size');
+  }
+
+  const bytes = fs.readFileSync(tarball);
+  const integrity = `sha512-${crypto.createHash('sha512').update(bytes).digest('base64')}`;
+  if (integrity !== pinned.integrity) {
+    return fail('integrity-mismatch', `npm tarball integrity ${integrity} does not match pinned integrity ${pinned.integrity}`);
+  }
+  const archive = readTar(bytes, { limits: treeLimits, stripPrefix: 'package/' });
+  if (!archive.ok) return { ok: false, findings: archive.findings };
+  return { ok: true, pinned, files: archive.files };
+}
+
+module.exports = { pinGit, fetchGit, pinNpm, fetchNpm };

package/src/runtime/packages/grants.js

@@ -0,0 +1,192 @@
+'use strict';
+
+/**
+ * The person grant file reader (122 IC-008). `<configHome>/packages/grants.jsonl` is written only by a
+ * person; this module reads it and never writes, renames or deletes it (a grep test in
+ * test/runtime/package-grants.test.js holds every `src/` file to that).
+ *
+ * `readGrants` returns the file path and mtime, one `entries` row per well-formed line with its state, the
+ * `grants` that count right now, and IC-004 findings. Void rules: an unreadable file, a line over 2 KiB, more
+ * than 1000 lines, a malformed line, an unknown key or kind, or a duplicate key (`duplicateKey`: a trust line's grant,
+ * package, version, contentDigest, capabilityDigest and policy; an exempt line's grant, package, version and
+ * contentDigest; a fetch grant's source) voids every grant (`state-unreadable`, naming the line
+ * number and never its text). A file whose realpath lies in the detected project root (`detectedProjectRoot`,
+ * never the working directory itself), a `.doflow/state/dispatch-worktrees/` directory or the system temp directory is ignored (`grant-invalid`, reason
+ * `grants-file-location`). No file means no grants and no finding.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { configHome } = require('../config-home.js');
+const { parseSemVer } = require('../../helper/semver.js');
+const { isPackageId, isQualifiedId } = require('../../helper/package-ids.js');
+const { duplicateKeys } = require('../review/protocols.js');
+
+const GRANTS_FILE = path.join('packages', 'grants.jsonl');
+const LINE_MAX_BYTES = 2048;
+const LINES_MAX = 1000;
+const REBIND_MAX = 64;
+
+const DIGEST = /^[0-9a-f]{64}$/;
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+const KEYS = new Map                                                    ([
+  ['trust', { required: ['grant', 'package', 'version', 'contentDigest', 'capabilityDigest', 'policy', 'at'], optional: ['rebind'] }],
+  ['exempt', { required: ['grant', 'package', 'version', 'contentDigest', 'host', 'acceptRisk', 'at'], optional: [] }],
+  ['fetch', { required: ['grant', 'source', 'at'], optional: [] }],
+]);
+
+const isObject = (value     )          => value !== null && typeof value === 'object' && !Array.isArray(value);
+const isText = (value     )          => typeof value === 'string' && value !== '' && value.length <= 512;
+const isTime = (value     )          => typeof value === 'string' && ISO_UTC.test(value) && !Number.isNaN(Date.parse(value));
+const isVersion = (value     )          => typeof value === 'string' && parseSemVer(value) !== null;
+
+function finding(code        , field        , message        , allowed        , reason         )      {
+  return { package: null, field, code, severity: 'error', message, allowed, ...(reason ? { reason } : {}) };
+}
+
+/** The source of a `fetch` grant, as written: git `{type,url,ref,path?}` or npm `{type,name,version}`. */
+function sourceProblem(source     )                {
+  if (!isObject(source)) return 'source must be an object';
+  const keys = Object.keys(source).sort().join(',');
+  if (source.type === 'git') {
+    if (keys !== 'ref,type,url' && keys !== 'path,ref,type,url') return 'git source keys';
+    return isText(source.url) && isText(source.ref) && (source.path === undefined || isText(source.path)) ? null : 'git source values';
+  }
+  if (source.type === 'npm') {
+    if (keys !== 'name,type,version') return 'npm source keys';
+    return isText(source.name) && isText(source.version) ? null : 'npm source values';
+  }
+  return 'source type';
+}
+
+/** Why a parsed line is not a grant of its kind, or null. The reason never quotes the line. */
+function lineProblem(grant     )                {
+  if (!isObject(grant)) return 'not a JSON object';
+  const spec = KEYS.get(grant.grant);
+  if (!spec) return 'unknown kind';
+  const allowed = new Set([...spec.required, ...spec.optional]);
+  if (Object.keys(grant).some((key) => !allowed.has(key))) return 'unknown key';
+  if (spec.required.some((key) => !Object.hasOwn(grant, key))) return 'missing key';
+  if (!isTime(grant.at)) return 'bad at';
+  if (grant.grant === 'fetch') return sourceProblem(grant.source) ? 'bad source' : null;
+  if (!isPackageId(grant.package) || !isVersion(grant.version) || !DIGEST.test(grant.contentDigest)) return 'bad package, version or digest';
+  if (grant.grant === 'exempt') return isVersion(grant.host) && grant.acceptRisk === true ? null : 'bad host or acceptRisk';
+  if (!DIGEST.test(grant.capabilityDigest) || !Number.isInteger(grant.policy) || grant.policy < 1) return 'bad capabilityDigest or policy';
+  if (Object.hasOwn(grant, 'rebind')
+    && !(Array.isArray(grant.rebind) && grant.rebind.length <= REBIND_MAX && grant.rebind.every(isQualifiedId))) return 'bad rebind';
+  return null;
+}
+
+/**
+ * The duplicate key of IC-008 (FU-gjgp06, FU-92eftv): (grant, package, version, contentDigest, capabilityDigest, policy)
+ * for trust, (grant, package, version, contentDigest) for exempt, and a fetch grant's source as written. Lines for one
+ * package version with other digests or another policy coexist, so a re-trust after an edit or a policy bump is an
+ * append; a line with an existing key is a replacement of that line (the package verbs say which).
+ */
+const duplicateKey = (grant     )         => {
+  if (grant.grant === 'fetch') return `fetch ${JSON.stringify(Object.keys(grant.source).sort().map((key) => [key, grant.source[key]]))}`;
+  const key = `${grant.grant} ${grant.package} ${grant.version} ${grant.contentDigest}`;
+  return grant.grant === 'trust' ? `${key} ${grant.capabilityDigest} ${grant.policy}` : key;
+};
+
+const realOf = (fsImpl     , file        )         => {
+  try { return (fsImpl.realpathSync.native ?? fsImpl.realpathSync)(file); } catch { return path.resolve(file); }
+};
+const within = (child        , parent        )          => {
+  const rel = path.relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+};
+
+/** True when `path.join(dir, name)` exists and, with `directory`, is a directory. Never throws. */
+const holds = (fsImpl     , dir        , name        , directory         )          => {
+  try { const stat = fsImpl.statSync(path.join(dir, name)); return !directory || stat.isDirectory(); } catch { return false; }
+};
+
+/**
+ * The detected project root (IC-008 as amended by FU-t622ad; IC-025 reuses it): from `cwd` upward, the nearest
+ * directory, `cwd` included, that holds `.git` (a directory, or the file of a linked worktree) or a `.doflow/`
+ * directory. The account home `homeDir` and every ancestor of it end the walk, because the home is the global scope,
+ * not a project. Returns that directory's real path, or null when there is no project. Spawns no process.
+ */
+function detectedProjectRoot({ cwd = process.cwd(), homeDir = os.homedir(), fsImpl = fs }                                                          = {})                {
+  const home = homeDir ? realOf(fsImpl, homeDir) : null;
+  for (let dir = realOf(fsImpl, cwd); ; dir = path.dirname(dir)) {
+    if (home !== null && within(home, dir)) return null; // the home or an ancestor of it: so is every parent
+    if (holds(fsImpl, dir, '.git', false) || holds(fsImpl, dir, '.doflow', true)) return dir;
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+/** `grants-file-location` (IC-008): the realpath is in the project root (none when null), a dispatch worktree or the temp dir. */
+function badLocation(real        , projectRoot               , tmpDir        , fsImpl     )          {
+  const marker = `${path.sep}.doflow${path.sep}state${path.sep}dispatch-worktrees${path.sep}`;
+  return (projectRoot !== null && within(real, realOf(fsImpl, projectRoot))) || within(real, realOf(fsImpl, tmpDir)) || `${real}${path.sep}`.includes(marker);
+}
+
+/**
+ * Read the grant file. Options: `env` (for the config home, and its `HOME` for the account home), `fsImpl`,
+ * `projectRoot` (default: `detectedProjectRoot` from the working directory; `null` means no project, so only the
+ * dispatch-worktree and temp-dir rules apply), `tmpDir` (default `os.tmpdir()`; an injected seam for tests). Never throws.
+ * Returns `{ path, noConfigHome, exists, mtime, entries, grants, findings }`: `path` is null with no config home
+ * (no grant can exist); `mtime` is an ISO string or null; `entries` holds each well-formed line as
+ * `{ line, raw, state: 'valid'|'void'|'ignored', reason?, ...fields }`; `grants` are the `valid` entries.
+ */
+function readGrants({ env = process.env, fsImpl = fs, projectRoot, tmpDir = os.tmpdir() }      = {})      {
+  const dir = configHome(env).dir;
+  const result      = { path: null, noConfigHome: dir === null, exists: false, mtime: null, entries: [], grants: [], findings: [] };
+  if (dir === null) return result;
+  const file = path.join(dir, GRANTS_FILE);
+  result.path = file;
+  const unreadable = (message        )      => {
+    result.findings.push(finding('state-unreadable', 'grants.jsonl', message, 'a grants file of at most 1000 lines of at most 2 KiB, one closed-key JSON object each'));
+    for (const entry of result.entries) { entry.state = 'void'; entry.reason = 'state-unreadable'; }
+    result.grants = [];
+    return result;
+  };
+  let text        ;
+  try {
+    const stat = fsImpl.statSync(file);
+    result.exists = true;
+    result.mtime = new Date(stat.mtimeMs ?? stat.mtime).toISOString();
+    if (stat.size > LINES_MAX * (LINE_MAX_BYTES + 2)) return unreadable(`the grants file is larger than ${LINES_MAX} lines of ${LINE_MAX_BYTES} bytes`);
+    text = String(fsImpl.readFileSync(file, 'utf8'));
+  } catch (error     ) {
+    if (error?.code === 'ENOENT' && !result.exists) return result; // no file: no grants, no error
+    return unreadable('the grants file could not be read');
+  }
+
+  const lines = text.split('\n');
+  if (lines[lines.length - 1] === '') lines.pop();
+  let problem                = lines.length > LINES_MAX ? `line ${LINES_MAX + 1} is past the ${LINES_MAX}-line limit` : null;
+  const seen = new Set        ();
+  for (let i = 0; i < Math.min(lines.length, LINES_MAX) && problem === null; i++) {
+    const raw = lines[i].trim();
+    const number = i + 1;
+    if (Buffer.byteLength(lines[i]) > LINE_MAX_BYTES) { problem = `line ${number} is longer than ${LINE_MAX_BYTES} bytes`; break; }
+    if (raw === '' || raw.startsWith('#')) continue;
+    let grant     ;
+    try { grant = duplicateKeys(raw).length ? undefined : JSON.parse(raw); } catch { grant = undefined; }
+    const why = grant === undefined ? 'not valid JSON' : lineProblem(grant);
+    if (why) { problem = `line ${number} is not a valid grant (${why})`; break; }
+    const key = duplicateKey(grant);
+    const what = grant.grant === 'fetch' ? 'source' : grant.grant === 'trust' ? '(grant, package, version, contentDigest, capabilityDigest, policy)' : '(grant, package, version, contentDigest)';
+    if (seen.has(key)) { problem = `line ${number} repeats the ${what} of an earlier line`; break; }
+    seen.add(key);
+    result.entries.push({ line: number, raw, state: 'valid', ...grant });
+  }
+  const root = projectRoot !== undefined ? projectRoot
+    : detectedProjectRoot({ homeDir: typeof env.HOME === 'string' && path.isAbsolute(env.HOME) ? env.HOME : os.homedir(), fsImpl });
+  const misplaced = badLocation(realOf(fsImpl, file), root, tmpDir, fsImpl);
+  if (problem !== null && !misplaced) return unreadable(problem);
+  if (misplaced) {
+    for (const entry of result.entries) { entry.state = 'ignored'; entry.reason = 'grants-file-location'; }
+    result.findings.push(finding('grant-invalid', 'grants.jsonl', 'the grants file lies inside the project root, a dispatch worktree or the system temp directory, so every grant in it is ignored',
+      'a grants file outside the project and the temp directory (set XDG_CONFIG_HOME to a path in your own home)', 'grants-file-location'));
+    return result;
+  }
+  result.grants = result.entries;
+  return result;
+}
+
+module.exports = { readGrants, detectedProjectRoot, duplicateKey, GRANTS_FILE, LINE_MAX_BYTES, LINES_MAX };