@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/runtime/packages/tar.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Read an in-memory ustar or pax archive under the IC-005 limits while reading it.
+ * Link entries are refused as `symlink`. This module writes nothing and spawns nothing.
+ */
+
+const zlib = require('node:zlib');
+const { SEGMENT, SEGMENT_GRAMMAR } = require('./digest.js');
+
+function readTar(input     , { limits, stripPrefix, packageId = null }     )      {
+  const findings        = [];
+  const files        = [];
+  const seen = new Set        ();
+  const add = (field        , code        , message        , allowed     )      => {
+    findings.push({ package: packageId, field, code, severity: 'error', message, allowed });
+    return { ok: false, findings };
+  };
+  let data = input;
+  if (data[0] === 0x1f && data[1] === 0x8b) {
+    try { data = zlib.gunzipSync(data, { maxOutputLength: limits.bytes + (limits.files + 64) * 1024 }); }
+    catch { return add('tree', 'too-large', 'the compressed archive exceeds the bounded tar size', `at most ${limits.bytes} bytes plus archive headers`); }
+  }
+  const text = (buf     )         => buf.toString('utf8').replace(/\0.*$/su, '');
+  const octal = (buf     )         => {
+    const value = text(buf).trim();
+    return value ? parseInt(value, 8) : 0;
+  };
+  const blocks = Math.floor(data.length / 512);
+  let index = 0;
+  let total = 0;
+  let count = 0;
+  let pax      = null;
+  while (index < blocks) {
+    const h = data.subarray(index * 512, (index + 1) * 512);
+    if (h.every((v        ) => v === 0)) break;
+    const magic = h.subarray(257, 263).toString('binary');
+    if (magic !== 'ustar\0' && magic !== 'ustar ') return add('tree', 'bad-type', 'tar header is not ustar or pax', 'ustar or pax archive headers');
+    const expected = octal(h.subarray(148, 156));
+    let sum = 0;
+    for (let j = 0; j < 512; j++) sum += j >= 148 && j < 156 ? 32 : h[j];
+    if (sum !== expected) return add('tree', 'bad-type', 'tar header checksum does not match', 'a valid tar header checksum');
+    const size = octal(h.subarray(124, 136));
+    const type = h[156] === 0 ? '0' : String.fromCharCode(h[156]);
+    index++;
+    if (!Number.isSafeInteger(size) || size < 0 || index * 512 + size > data.length) return add('tree', 'bad-type', 'tar entry is truncated or has an invalid size', 'a complete tar entry');
+    const payloadStart = index * 512;
+    const payloadEnd = payloadStart + size;
+    const payload = data.subarray(payloadStart, payloadEnd);
+    index += Math.ceil(size / 512);
+    if (type === 'g') continue;
+    if (type === 'x') {
+      pax = {};
+      const raw = payload.toString('utf8');
+      let at = 0;
+      while (at < raw.length) {
+        const space = raw.indexOf(' ', at);
+        const n = Number(raw.slice(at, space));
+        if (space < 0 || !Number.isInteger(n) || n <= 0 || at + n > raw.length) return add('tree', 'bad-type', 'pax header is malformed', 'valid pax path and size records');
+        const row = raw.slice(space + 1, at + n).replace(/\n$/u, '');
+        const eq = row.indexOf('=');
+        if (eq > 0) pax[row.slice(0, eq)] = row.slice(eq + 1);
+        at += n;
+      }
+      continue;
+    }
+    let name = pax?.path ?? text(h.subarray(0, 100));
+    const prefix = text(h.subarray(345, 500));
+    if (!pax?.path && prefix) name = `${prefix}/${name}`;
+    const actualSize = pax?.size === undefined ? size : Number(pax.size);
+    pax = null;
+    if (type === '1' || type === '2') return add(`tree.${name}`, 'symlink', `${name} is a symbolic link`, 'regular files and directories only');
+    if (type === '3' || type === '4' || type === '6') return add(`tree.${name}`, 'special-file', `${name} is a device, socket or FIFO`, 'regular files and directories only');
+    if (type !== '0' && type !== '5') return add(`tree.${name}`, 'bad-type', `unsupported tar entry type '${type}'`, 'regular files and directories only');
+    if (type === '5') continue;
+    name = name.replace(/^\.\//u, '');
+    if (name.startsWith('/') || name.split('/').includes('..')) return add(`tree.${name}`, 'path-escapes-root', `${name} leaves the package root`, 'a path inside the package root');
+    if (stripPrefix) {
+      if (!name.startsWith(stripPrefix)) return add(`tree.${name}`, 'path-escapes-root', `${name} is outside ${stripPrefix}`, `a path inside ${stripPrefix}`);
+      name = name.slice(stripPrefix.length);
+    }
+    const segments = name.split('/');
+    if (segments.some((s        ) => !SEGMENT.test(s))) return add(`tree.${name}`, 'bad-type', `${name}: a segment breaks the path grammar`, SEGMENT_GRAMMAR);
+    if (name.length > limits.pathLength) return add(`tree.${name}`, 'too-large', `${name} is ${name.length} characters long`, `a relative path of at most ${limits.pathLength} characters`);
+    if (!Number.isSafeInteger(actualSize) || actualSize < 0 || actualSize !== size) return add(`tree.${name}`, 'bad-type', 'pax size does not match the tar entry', 'a complete tar entry');
+    if (actualSize > limits.fileBytes) return add(`tree.${name}`, 'too-large', `${name} is ${actualSize} bytes`, `at most ${limits.fileBytes} bytes per file`);
+    if (count >= limits.files) return add('tree', 'too-many-files', `the package holds more than ${limits.files} files`, `at most ${limits.files} files`);
+    if (total + actualSize > limits.bytes) return add('tree', 'too-large', `the package holds more than ${limits.bytes} bytes`, `at most ${limits.bytes} bytes in total`);
+    if (seen.has(name)) return add(`tree.${name}`, 'bad-type', `${name} appears twice in the archive`, 'each file path at most once');
+    total += actualSize;
+    count++;
+    seen.add(name);
+    const mode = octal(h.subarray(100, 108));
+    files.push({ path: name, mode: (mode & 0o111) !== 0 ? 0o755 : 0o644, data: payload });
+  }
+  const 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;
+  };
+  files.sort((a     , b     ) => compareBytes(a.path, b.path));
+  return { ok: true, files };
+}
+
+module.exports = { readTar };

package/src/runtime/packages/view.js

@@ -0,0 +1,406 @@
+'use strict';
+
+/**
+ * The package view (122 IC-010): the effective state of every package, read-only, with no network, no
+ * harness and no model call. It holds the bundled first-party packages (those listed in
+ * `contribution-points.json` `bundled`) and the third-party packages the global lock records
+ * (`~/.doflow/doflow.lock` `packages`, stored at `~/.doflow/packages/store/<id>/<contentDigest first 16 hex>/`).
+ *
+ * A third-party package takes the first state that applies, in this order: `incompatible` (the manifest, a
+ * contribution or the IC-005 tree fails the checker against the running core, or the host is outside its `doflow`
+ * range with no matching `exempt` grant), `suspended` (the store entry or its manifest is missing, or the tree
+ * re-hashes to another content digest: `content-changed`), `disabled` (the lock bit is false), `needs-trust` (the tier
+ * is above inert and no valid `trust` grant exists), else `active`. Only an ENABLED entry is walked and re-hashed
+ * (the IC-005 caps apply to that walk). A DISABLED entry is read no further than its manifest, which is
+ * checked lexically (no contribution file, no tree walk, no digest), so a byte flip in a disabled entry shows once
+ * it is enabled. With no third-party row nothing under the store, the grants file or `state.json` is read. The grants
+ * (`readGrants`, IC-008) and revocations (`readState`, IC-009) are read once per build, only when a third-party row
+ * exists; they and the lock are read and never written.
+ *
+ * The memo is keyed on everything the view reads: the runtime root, the home (lock, store, state), the config home
+ * (grants), the project root and the temp dir (where the grants file may lie). A caller that injects `fsImpl`
+ * bypasses it. `resetPackageView` clears it for tests.
+ *
+ * The resolved `packages.disabled` setting (IC-011) is applied last, over the memoised states: a listed id is `disabled`
+ * with reason `disabled-by-<layer>`, and an invalid value disables every non-bundled package with `settings-invalid`
+ * (PN-7, fail closed). The bundled package can be disabled by the person like any other. A caller passes
+ * `settingsView['packages.disabled']` (`{ value, layer, state?, byId? }`); with none, the project settings of the working
+ * directory are read, unless `fsImpl` is injected, which keeps the view hermetic.
+ *
+ * A bundled package is `active` unless its directory or manifest is missing or invalid, then `incompatible`
+ * with IC-004 reason codes; a lock row with source `bundled` and `enabled: false` disables it. It is trusted at
+ * runtime and verified at release (IC-015): only the manifest's shape
+ * and lexical paths are checked here (no contribution file is read, nothing under `core/shared` is needed), and
+ * its tree is never re-hashed (guard G68 checks the registry digest); `contentDigest` is the registry's value.
+ * The projected runtime ships no `package.json`, so the host version of a bundled package then falls back to the
+ * package's own manifest `version` (PN-8 keeps the two equal); a readable `package.json` that differs still
+ * makes it `host-incompatible`. Each package is judged alone, so a fault in one never changes
+ * another and the view itself never throws (FR-009).
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+const { parseSemVer } = require('../../helper/semver.js');
+const { configHome } = require('../config-home.js');
+const { readLock, lockPackages } = require('../../state/lockfile.js');
+const { loadPoints, pointRows } = require('./points.js');
+const { checkManifest, checkPackage, MANIFEST_FILE } = require('./manifest.js');
+const { readGrants, detectedProjectRoot } = require('./grants.js');
+const { readState, grantRevoked } = require('./state.js');
+const { loadCoreProtocols } = require('../review/protocols.js');
+
+const TIER_ORDER = ['inert', 'instruction', 'executable'];
+const memo = new Map             ();
+const fullMemo = new Map             ();
+// Building a third-party view loads the core protocol registry, whose validation asks for the first-party preset ids
+// (`firstPartyPresets`), which asks for this view. A call made while one is being built gets the bundled-only view,
+// which is all that question needs.
+let building = 0;
+
+/**
+ * The running DoFlow version. A checkout or the npm package has `<repoRoot>/package.json`, read first. A projected
+ * runtime (`<scope root>/.doflow/runtime`) ships none, but the install recorded the version in the lock it wrote beside
+ * it, so `<scope root>/.doflow/doflow.lock` `sourceVersion` (set from the installing DoFlow's package.json) is read
+ * instead, only for that layout and only when it is semver. The lock is parsed directly: `readLock` validates the whole
+ * document and throws, where one field is all this needs. Anything else is null, which the checker reports as
+ * host-incompatible (fail closed).
+ */
+function hostVersion(repoRoot        )                {
+  try { return JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')).version || null; } catch { /* no package.json: try the lock */ }
+  const parent = path.dirname(path.resolve(repoRoot));
+  if (path.basename(path.resolve(repoRoot)) !== 'runtime' || path.basename(parent) !== '.doflow') return null;
+  try {
+    const version = JSON.parse(fs.readFileSync(path.join(parent, 'doflow.lock'), 'utf8')).sourceVersion;
+    return typeof version === 'string' && parseSemVer(version) ? version : null;
+  } catch { return null; }
+}
+
+function finding(pkg               , field        , code        , message        , allowed     )      {
+  return { package: pkg, field, code, severity: 'error', message, allowed };
+}
+
+/** True when `target` is `root` itself or inside it. */
+const within = (root        , target        )          => {
+  const rel = path.relative(root, target);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+};
+
+/** Resolve a bundled `dir` inside the runtime root; `{ error }` is the finding when it is missing or leaves the root. */
+function bundledDir(repoRoot        , entry     , fsImpl     )                                {
+  const abs = path.resolve(repoRoot, entry.dir);
+  const escapes = finding(entry.id, 'dir', 'path-escapes-root', `bundled dir '${entry.dir}' leaves the runtime root`, 'a directory inside the runtime root');
+  if (!within(path.resolve(repoRoot), abs)) return { error: escapes };
+  try {
+    if (!fsImpl.statSync(abs).isDirectory()) return { error: finding(entry.id, 'dir', 'file-missing', `bundled dir '${entry.dir}' is not a directory`, 'a package directory') };
+    if (!within(fsImpl.realpathSync(repoRoot), fsImpl.realpathSync(abs))) return { error: escapes };
+  } catch {
+    return { error: finding(entry.id, 'dir', 'file-missing', `bundled dir '${entry.dir}' does not exist`, 'a package directory') };
+  }
+  return { dir: abs };
+}
+
+/** The contributions a manifest names, as view rows (`active: false` until the state is known). `qualify` gives the qualified id. */
+function contributionList(manifest     , tiers                        , qualify                    )        {
+  const list = Array.isArray(manifest?.contributions) ? manifest.contributions : [];
+  return list.filter((c     ) => c && typeof c === 'object' && typeof c.point === 'string' && typeof c.id === 'string').map((c     ) => ({
+    point: c.point, version: c.version, qualifiedId: qualify(c), tier: tiers[c.point] ?? null, active: false,
+  }));
+}
+
+/** The highest tier among view contribution rows; null when none has a known tier. */
+function tierMaxOf(contributions       )                {
+  const ranks = contributions.map((c     ) => TIER_ORDER.indexOf(c.tier)).filter((r        ) => r >= 0);
+  return ranks.length > 0 ? TIER_ORDER[Math.max(...ranks)] : null;
+}
+
+/** The state of one bundled package. Never throws. */
+function bundledState(entry     , ctx     )                                  {
+  const { repoRoot, fsImpl, pointsRegistry, host, bundledIds } = ctx;
+  const tiers                         = Object.fromEntries(pointsRegistry.points.map((p     ) => [p.id, p.tier]));
+  const state      = {
+    id: entry.id, version: null, source: { type: 'bundled' }, firstParty: true, tierMax: null, enabled: true,
+    state: 'active', reasons: [], contributions: [], grant: { trust: true, exempt: false },
+    contentDigest: entry.contentDigest, capabilityDigest: null, storeDir: null,
+  };
+  let findings        = [];
+  try {
+    const located = bundledDir(repoRoot, entry, fsImpl);
+    if (located.error) findings = [located.error];
+    else {
+      state.storeDir = located.dir;
+      let text                = null;
+      try { text = fsImpl.readFileSync(path.join(located.dir          , MANIFEST_FILE), 'utf8'); } catch { /* reported below */ }
+      if (text === null) {
+        findings = [finding(entry.id, MANIFEST_FILE, 'file-missing', `${MANIFEST_FILE} is missing`, `a ${MANIFEST_FILE} at the package root`)];
+      } else {
+        let manifest      = null;
+        try { manifest = JSON.parse(text); } catch { /* the checker reports it */ }
+        const hostFor = host ?? (typeof manifest?.version === 'string' ? manifest.version : null);
+        // `protocols` is unused for a bundled entry without `root`; passing it stops the checker from loading the
+        // merged registry, which would build this view again.
+        findings = checkManifest(text, { pointsRegistry, hostVersion: hostFor, bundled: bundledIds, repoRoot, fsImpl, protocols: { presets: {} } })
+          .map((f     ) => ({ ...f, package: f.package ?? entry.id }));
+        if (manifest && typeof manifest === 'object') {
+          if (typeof manifest.version === 'string') state.version = manifest.version;
+          if (manifest.id !== entry.id) {
+            findings.push(finding(entry.id, 'id', 'bad-id', `manifest id ${JSON.stringify(manifest.id)} differs from the bundled id '${entry.id}'`, entry.id));
+          }
+          state.contributions = contributionList(manifest, tiers, (c     ) => c.id /* IC-003: the first-party package keeps bare built-in ids */);
+          state.tierMax = tierMaxOf(state.contributions);
+        }
+      }
+    }
+  } catch (error     ) {
+    findings = [finding(entry.id, 'dir', 'state-unreadable', `cannot evaluate the bundled package: ${error?.message || String(error)}`, 'a readable package directory')];
+  }
+  const errors = findings.filter((f) => f.severity === 'error');
+  if (errors.length > 0) {
+    state.state = 'incompatible';
+    state.reasons = [...new Set        (errors.map((f) => f.code))];
+  }
+  for (const c of state.contributions) c.active = state.state === 'active';
+  return { state, findings };
+}
+
+/** Why a `trust` grant does not hold for `state`, or null when one does. The first that applies: unreadable, missing, content, policy, capabilities, revoked. */
+function trustReason(state     , ctx     )                {
+  const { grants, stateRead, pointsRegistry } = ctx;
+  if (stateRead.unreadable || grants.findings.some((f     ) => f.code === 'state-unreadable')) return 'state-unreadable';
+  // Lines for one version with other digests coexist (IC-008 duplicate key): judge the one whose digests match, else
+  // the one with the matching content digest, else any (each of those reads content-changed).
+  const lines = grants.grants.filter((g     ) => g.grant === 'trust' && g.package === state.id && g.version === state.version);
+  const grant = lines.find((g     ) => g.contentDigest === state.contentDigest && g.capabilityDigest === state.capabilityDigest)
+    ?? lines.find((g     ) => g.contentDigest === state.contentDigest) ?? lines[0];
+  if (!grant) return 'grant-missing';
+  if (grant.contentDigest !== state.contentDigest) return 'content-changed';
+  if (grant.policy < pointsRegistry.trustPolicyVersion) return 'policy-changed';
+  if (grant.capabilityDigest !== state.capabilityDigest) return 'capabilities-changed';
+  if (grantRevoked(stateRead, grant)) return 'revoked';
+  return null;
+}
+
+/** The valid `exempt` grant for exactly this package version, content digest and host version (IC-008), or null. */
+function exemptGrantFor(row     , ctx     )      {
+  if (!ctx.host) return null;
+  return ctx.grants.grants.find((g     ) => g.grant === 'exempt' && g.acceptRisk === true && g.package === row.id && g.version === row.version
+    && g.contentDigest === row.contentDigest && g.host === ctx.host && !grantRevoked(ctx.stateRead, g)) ?? null;
+}
+
+/** The state of one third-party package (a lock row). Never throws. */
+function thirdPartyState(row     , ctx     )                                  {
+  const { fsImpl, pointsRegistry } = ctx;
+  const storeDir = path.join(ctx.storeRoot, row.id, row.contentDigest.slice(0, 16));
+  const state      = {
+    id: row.id, version: row.version, source: row.source, firstParty: false, tierMax: null, enabled: row.enabled,
+    state: 'active', reasons: [], contributions: [], grant: { trust: false, exempt: false },
+    contentDigest: row.contentDigest, capabilityDigest: row.capabilityDigest, storeDir,
+  };
+  let findings        = [];
+  const settle = (name        , reasons          ) => {
+    state.state = name;
+    state.reasons = reasons;
+    for (const c of state.contributions) c.active = name === 'active';
+    return { state, findings };
+  };
+  try {
+    let text                = null;
+    try { text = String(fsImpl.readFileSync(path.join(storeDir, MANIFEST_FILE), 'utf8')); } catch { /* the store entry is missing */ }
+    if (text === null) {
+      findings = [finding(row.id, `store/${row.id}/${row.contentDigest.slice(0, 16)}`, 'file-missing', `the store entry for ${row.id} has no ${MANIFEST_FILE}`, 'an intact store entry')];
+      return settle('suspended', ['content-changed']);
+    }
+    let manifest      = null;
+    try { manifest = JSON.parse(text); } catch { /* the checker reports it */ }
+    const tiers                         = Object.fromEntries(pointsRegistry.points.map((p     ) => [p.id, p.tier]));
+    if (manifest && typeof manifest === 'object') {
+      state.contributions = contributionList(manifest, tiers, (c     ) => `${row.id}.${c.id}`);
+      state.tierMax = tierMaxOf(state.contributions);
+    }
+
+    const exempt = exemptGrantFor(row, ctx);
+    const options = { pointsRegistry, hostVersion: ctx.host, bundled: [], repoRoot: ctx.repoRoot, fsImpl, protocols: ctx.protocols, hostExempt: exempt !== null };
+    let checked      = null;
+    if (row.enabled) {
+      checked = checkPackage(storeDir, options);
+      findings = checked.findings;
+    } else {
+      findings = checkManifest(text, options); // no `root`: the manifest alone, lexically; nothing else under the entry is read
+    }
+    findings = findings.map((f     ) => ({ ...f, package: f.package ?? row.id }));
+    if (manifest && typeof manifest === 'object' && manifest.id !== row.id) {
+      findings.push(finding(row.id, 'id', 'bad-id', `manifest id ${JSON.stringify(manifest.id)} differs from the recorded id '${row.id}'`, row.id));
+    }
+    const errors = findings.filter((f     ) => f.severity === 'error');
+    if (errors.length > 0) return settle('incompatible', [...new Set        (errors.map((f     ) => f.code))]);
+    state.grant.exempt = findings.some((f     ) => f.code === 'host-incompatible' && f.severity === 'warning');
+
+    if (checked && checked.contentDigest !== row.contentDigest) {
+      findings.push(finding(row.id, 'contentDigest', 'digest-mismatch', `the store entry for ${row.id} hashes to ${checked.contentDigest}, not the recorded ${row.contentDigest}`, 'the recorded content digest'));
+      return settle('suspended', ['content-changed']);
+    }
+    if (checked) state.capabilityDigest = checked.capabilityDigest;
+    if (!row.enabled) return settle('disabled', ['disabled-by-lock']);
+    if (state.tierMax !== 'inert' && state.tierMax !== null) {
+      const reason = trustReason(state, ctx);
+      if (reason !== null) return settle('needs-trust', [reason]);
+      state.grant.trust = true;
+    }
+    return settle('active', []);
+  } catch (error     ) {
+    findings = [finding(row.id, 'store', 'state-unreadable', `cannot evaluate the package: ${error?.message || String(error)}`, 'a readable store entry')];
+    return settle('incompatible', ['state-unreadable']);
+  }
+}
+
+/**
+ * The bundled view plus the third-party packages of the global lock. Returns `bundled` itself when the lock holds
+ * nothing that changes it. An unreadable lock adds one `state-unreadable` finding and no package.
+ */
+function withLock(bundled                                                     , o     )                                                                                                                             {
+  let rows       ;
+  try {
+    rows = lockPackages(readLock({ scope: 'global', homeDir: o.home }, { fsImpl: o.fsImpl }));
+  } catch (error     ) {
+    return { ...bundled, findings: [...bundled.findings, finding(null, 'doflow.lock', 'state-unreadable', error?.message || String(error), 'a readable doflow.lock')] };
+  }
+  let packages = bundled.packages.map((pkg     ) => {
+    const row = rows.find((r     ) => r.id === pkg.id && r.source?.type === 'bundled');
+    if (!row || row.enabled || pkg.state !== 'active') return pkg;
+    return { ...pkg, enabled: false, state: 'disabled', reasons: ['disabled-by-lock'], contributions: pkg.contributions.map((c     ) => ({ ...c, active: false })) };
+  });
+  const thirdParty = rows.filter((r     ) => r.source?.type !== 'bundled');
+  if (thirdParty.length === 0) return packages.some((p     , i        ) => p !== bundled.packages[i]) ? { ...bundled, packages } : bundled;
+
+  const loaded = loadPoints({ repoRoot: o.repoRoot, fsImpl: o.fsImpl });
+  if (!loaded.ok) return { ...bundled, packages };
+  const core = loadCoreProtocols({ repoRoot: o.repoRoot, fsImpl: o.fsImpl });
+  const grants = readGrants({ env: o.env, fsImpl: o.fsImpl, projectRoot: o.projectRoot, ...(o.tmpDir === undefined ? {} : { tmpDir: o.tmpDir }) });
+  const stateRead = readState({ homeDir: o.home, fsImpl: o.fsImpl });
+  const ctx = {
+    repoRoot: o.repoRoot, fsImpl: o.fsImpl, pointsRegistry: loaded.registry, host: hostVersion(o.repoRoot), grants, stateRead,
+    protocols: core.ok ? core.registry : undefined, storeRoot: path.join(o.home, '.doflow', 'packages', 'store'),
+  };
+  const bundledIds = new Set        (bundled.packages.map((p     ) => p.id));
+  const findings = [...bundled.findings, ...grants.findings, ...stateRead.findings];
+  for (const row of thirdParty) {
+    if (bundledIds.has(row.id)) {
+      findings.push(finding(row.id, 'id', 'collision-package', `the lock records '${row.id}' from a ${row.source?.type} source, but that id belongs to a bundled package`, 'an id no bundled package uses'));
+      continue;
+    }
+    const one = thirdPartyState(row, ctx);
+    packages = [...packages, one.state];
+    findings.push(...one.findings);
+  }
+  return { packages, points: bundled.points, findings, stateRead, grants, homeDir: o.home, env: o.env, tmpDir: o.tmpDir };
+}
+
+const DISABLED_KEY = 'packages.disabled';
+
+/**
+ * The `packages.disabled` entry of the project settings of the working directory, in the shape a caller injects.
+ * `byId` names the lowest layer that listed each id. A registry or settings fault is an invalid value: fail closed.
+ * The settings are read as a view of this one key (`only`): a full load validates every key of a layer file, and the
+ * `review.preset` and `debate.preset` value lists hold the presets of active packages (IC-014), which is this view
+ * again. The key's own list (`packages.ids`) reads the lock alone, so this read never re-enters the view.
+ */
+function resolvedDisabledEntry(env     )      {
+  try {
+    const resolution = require('../settings/resolve.js').loadSettings({ projectRoot: process.cwd(), env: env ?? process.env, only: [DISABLED_KEY] }).get(DISABLED_KEY);
+    const byId                         = {};
+    for (const c of resolution.candidates) {
+      if (c.status !== 'decided' || !Array.isArray(c.value)) continue;
+      for (const id of c.value) byId[id] ??= c.layer;
+    }
+    return { value: resolution.value, layer: resolution.origin.layer, state: resolution.state, byId };
+  } catch {
+    return { value: null, layer: 'default', state: 'invalid' };
+  }
+}
+
+/**
+ * The packages with the `packages.disabled` entry applied (IC-010 state 3). Only a package that would be `active` or
+ * `needs-trust` changes: `incompatible` and `suspended` outrank `disabled`. Returns `packages` itself when nothing changes.
+ */
+function applySettingsDisable(packages       , entry     )        {
+  if (!entry) return packages;
+  const invalid = entry.state === 'invalid';
+  const listed = new Set        (!invalid && Array.isArray(entry.value) ? entry.value : []);
+  const reasonFor = (pkg     )                => {
+    if (invalid) return pkg.source?.type === 'bundled' ? null : 'settings-invalid';
+    return listed.has(pkg.id) ? `disabled-by-${entry.byId?.[pkg.id] ?? entry.layer}` : null;
+  };
+  let changed = false;
+  const out = packages.map((pkg     ) => {
+    const reason = pkg.state === 'active' || pkg.state === 'needs-trust' ? reasonFor(pkg) : null;
+    if (reason === null) return pkg;
+    changed = true;
+    return { ...pkg, state: 'disabled', reasons: [reason], contributions: pkg.contributions.map((c     ) => ({ ...c, active: false })) };
+  });
+  return changed ? out : packages;
+}
+
+/**
+ * `{ packages, points, findings }`. `repoRoot`, `fsImpl`, `homeDir` (the account home, default: `HOME` of `env`, else
+ * `os.homedir()`), `projectRoot` (default: the project detected from the working directory, `detectedProjectRoot`;
+ * `null` means no project) and `tmpDir` (default: the system temp directory; both only decide whether the grants file
+ * counts, IC-008) are for tests and the verbs; an injected `fsImpl` bypasses
+ * the memo. A point registry that cannot be read leaves no package to find: `packages` and `points` are empty and the
+ * one finding is `state-unreadable` on `points`.
+ */
+function packageView({ settingsView, env, fsImpl = fs, repoRoot = REPO_ROOT, homeDir, projectRoot, tmpDir }                                                                                                                                                = {})                                                                                                                             {
+  const base = fullView({ repoRoot, fsImpl, env, homeDir, projectRoot, tmpDir });
+  const entry = settingsView ? settingsView[DISABLED_KEY] : fsImpl === fs ? resolvedDisabledEntry(env) : undefined;
+  const packages = applySettingsDisable(base.packages, entry);
+  return packages === base.packages ? base : { ...base, packages };
+}
+
+/** The states before `packages.disabled` is applied: the bundled view plus the lock's third-party packages, memoised on everything they read. */
+function fullView(o     )                                                                                                                             {
+  const bundled = baseView(o.repoRoot, o.fsImpl);
+  if (building > 0 || bundled.points.length === 0) return bundled;
+  const environment = o.env ?? process.env;
+  const home = o.homeDir ?? (typeof environment.HOME === 'string' && path.isAbsolute(environment.HOME) ? environment.HOME : os.homedir());
+  const projectRoot = o.projectRoot === undefined ? detectedProjectRoot({ homeDir: home, fsImpl: o.fsImpl })
+    : o.projectRoot === null ? null : path.resolve(o.projectRoot);
+  const key = JSON.stringify([path.resolve(o.repoRoot), path.resolve(home), configHome(environment).dir, projectRoot, o.tmpDir ?? null]);
+  if (o.fsImpl === fs && fullMemo.has(key)) return fullMemo.get(key);
+  building += 1;
+  let result                                                                                                                            ;
+  try {
+    result = withLock(bundled, { ...o, env: environment, home, projectRoot });
+  } finally {
+    building -= 1;
+  }
+  if (o.fsImpl === fs) fullMemo.set(key, result);
+  return result;
+}
+
+/** The states before any setting is applied; memoised per runtime root for the real file system. */
+function baseView(repoRoot        , fsImpl     )                                                      {
+  const key = path.resolve(repoRoot);
+  if (fsImpl === fs && memo.has(key)) return memo.get(key);
+  const loaded = loadPoints({ repoRoot, fsImpl });
+  let result                                                                                                                            ;
+  if (!loaded.ok) {
+    result = { packages: [], points: [], findings: [finding(null, 'points', 'state-unreadable', loaded.errors.join('; '), 'a readable point registry')] };
+  } else {
+    const pointsRegistry = loaded.registry;
+    const ctx = { repoRoot, fsImpl, pointsRegistry, host: hostVersion(repoRoot), bundledIds: pointsRegistry.bundled.map((b     ) => b.id) };
+    const packages        = [];
+    const findings        = [];
+    for (const entry of pointsRegistry.bundled) {
+      const one = bundledState(entry, ctx);
+      packages.push(one.state);
+      findings.push(...one.findings);
+    }
+    result = { packages, points: pointRows(pointsRegistry), findings };
+  }
+  if (fsImpl === fs) memo.set(key, result);
+  return result;
+}
+
+function resetPackageView()       { memo.clear(); fullMemo.clear(); }
+
+module.exports = { packageView, resetPackageView, hostVersion, applySettingsDisable };

package/src/runtime/plan-check.js

@@ -0,0 +1,59 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * `plan-check <plan path> [--json]` (feature 115, IC-001): the plan judgement `planVerdict` makes,
+ * printed, plus row 134's content findings (`plan-content.ts`), each with a `path:line`. Read-only:
+ * it reads the plan and the requirement beside it and writes nothing. Exit 0 ok, 1 problems, 2
+ * usage or an unreadable file; the exit and `ok` are the task-graph verdict alone, so plan-check,
+ * task-attempt and the roadmap facts still agree about a plan's task graph.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { planVerdict } = require('./task-graph.js');
+const { planFindings } = require('./plan-content.js');
+const { finishRuntime } = require('./cli-result.js');
+
+const TEXT_MAX = 200;
+const ALLOWED_FLAGS = new Set(['--json']);
+
+function refuse(error        , message        , json         )         {
+  if (json) console.log(JSON.stringify({ ok: false, error, message }));
+  else console.error(`doflow plan-check: ${error}: ${message}`);
+  return finishRuntime(2);
+}
+
+function describe(file        , verdict     , findings       )         {
+  const warned = verdict.warnings.length ? `; warnings: ${verdict.warnings.join('; ')}` : '';
+  const found = findings.length ? `; findings: ${findings.map((f     ) => `${f.rule} ${f.path}:${f.line}`).join(', ')}` : '';
+  const parts = verdict.problems.map((problem     ) => (problem.ids.length ? `${problem.kind} ${problem.ids.join(',')}` : problem.kind));
+  const line = verdict.ok
+    ? `plan-check: ${file}: ok, ${verdict.tasks} tasks${warned}${found}`
+    : `plan-check: ${file}: ${verdict.problems.length} problem(s): ${parts.join('; ')}${warned}${found}`;
+  return line.length > TEXT_MAX ? `${line.slice(0, TEXT_MAX - 3)}...` : line;
+}
+
+function handlePlanCheckCommand({ positional = [], extraFlags = [], flagsGiven, json = false, cwd = process.cwd() }      = {})         {
+  const flags = flagsGiven || extraFlags;
+  const badFlag = flags.find((f        ) => !ALLOWED_FLAGS.has(f.split('=')[0]));
+  if (badFlag) return refuse('usage', `unknown flag '${badFlag}'; usage: plan-check <plan path> [--json]`, json);
+  if (positional.length === 0) return refuse('usage', 'a plan path is required; usage: plan-check <plan path> [--json]', json);
+  if (positional.length > 1) return refuse('usage', `exactly one plan path is accepted, got ${positional.length}; usage: plan-check <plan path> [--json]`, json);
+  const file = positional[0];
+  let text        ;
+  const planAbs = path.resolve(cwd, file);
+  try {
+    text = fs.readFileSync(planAbs, 'utf8');
+  } catch (error     ) {
+    return refuse('plan-unreadable', `cannot read '${file}': ${error.code || error.message}`, json);
+  }
+  const verdict = planVerdict(text);
+  const findings = planFindings({ planAbs, text, displayPath: file, cwd });
+  if (json) console.log(JSON.stringify({ ...verdict, findings, file }));
+  else console.log(describe(file, verdict, findings));
+  return finishRuntime(verdict.ok ? 0 : 1);
+}
+
+module.exports = { handlePlanCheckCommand };