@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/src/runtime/packages/state.js

@@ -0,0 +1,164 @@
+'use strict';
+
+/**
+ * The DoFlow-written package state file (122 IC-009, PN-1): `~/.doflow/packages/state.json`, atomic writes,
+ * owner-only mode 0600. It holds narrowing facts only (`revoked`, `suspended`, `audit`, `removed`), never a
+ * widening one. A missing file is empty state; a malformed one counts as every package revoked (`unreadable`).
+ * The writers read, change and rewrite the file: a caller that writes takes the scope's `run.lock` first (IC-007).
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { atomicJsonWrite } = require('../../state/index.js');
+
+const STATE_VERSION = 1;
+const AUDIT_MAX = 64;
+const TOP_KEYS = ['state', 'revoked', 'suspended', 'audit', 'removed'];
+const DIGEST = /^[0-9a-f]{64}$/;
+
+const isObject = (value     )          => value !== null && typeof value === 'object' && !Array.isArray(value);
+const isText = (value     )          => typeof value === 'string' && value !== '';
+const isTime = (value     )          => isText(value) && !Number.isNaN(Date.parse(value));
+
+const SHAPES                                         = {
+  revoked: (r) => isObject(r) && isText(r.package) && DIGEST.test(r.contentDigest) && isTime(r.at),
+  suspended: (s) => isObject(s) && isText(s.package) && isText(s.reason) && isTime(s.since) && typeof s.projected === 'boolean',
+  audit: (a) => isObject(a) && isTime(a.at) && isText(a.verb) && isText(a.package) && isText(a.result),
+  removed: (r) => isObject(r) && isText(r.package) && Array.isArray(r.qualifiedIds) && r.qualifiedIds.every(isText) && isTime(r.at),
+};
+
+const emptyState = ()      => ({ state: STATE_VERSION, revoked: [], suspended: [], audit: [], removed: [] });
+
+/** `~/.doflow/packages/state.json` (home from `homeDir`, else `os.homedir()`). */
+const statePath = (homeDir         )         => path.join(homeDir ?? os.homedir(), '.doflow', 'packages', 'state.json');
+
+function stateProblem(value     )                {
+  if (!isObject(value)) return 'not a JSON object';
+  if (Object.keys(value).some((key) => !TOP_KEYS.includes(key))) return 'unknown key';
+  if (value.state !== STATE_VERSION) return 'unsupported state version';
+  for (const [key, valid] of Object.entries(SHAPES)) {
+    if (value[key] !== undefined && !(Array.isArray(value[key]) && value[key].every(valid))) return `bad ${key}`;
+  }
+  return null;
+}
+
+/**
+ * Read the state. Returns `{ path, exists, unreadable, state, findings }`. A missing file: empty `state`, no
+ * finding. A malformed file: `unreadable` true, empty `state` and one `state-unreadable` finding; callers treat
+ * `unreadable` as every package revoked (`grantRevoked`). Never throws.
+ */
+function readState({ homeDir, fsImpl = fs }      = {})      {
+  const file = statePath(homeDir);
+  const result      = { path: file, exists: false, unreadable: false, state: emptyState(), findings: [] };
+  let text        ;
+  try {
+    text = String(fsImpl.readFileSync(file, 'utf8'));
+    result.exists = true;
+  } catch (error     ) {
+    if (error?.code === 'ENOENT') return result;
+    text = '';
+    result.exists = true;
+  }
+  let problem               ;
+  let parsed     ;
+  try { parsed = JSON.parse(text); problem = stateProblem(parsed); } catch { problem = 'not valid JSON'; }
+  if (problem !== null) {
+    result.unreadable = true;
+    result.findings.push({ package: null, field: 'state.json', code: 'state-unreadable', severity: 'error',
+      message: `the package state file is unreadable (${problem}); every package counts as revoked until verify --repair`, allowed: 'a state.json DoFlow wrote' });
+    return result;
+  }
+  result.state = { ...emptyState(), ...parsed, audit: (parsed.audit ?? []).slice(-AUDIT_MAX) };
+  return result;
+}
+
+/** Write the state atomically with mode 0600 (the temp file is created 0600 and renamed over the target). */
+function writeState(state     , { homeDir, fsImpl = fs }      = {})         {
+  // The file is created 0600: `atomicJsonWrite` (the declared writer) gets an fs whose file writes carry that mode.
+  const owned = new Proxy(fsImpl, {
+    get: (target     , name        ) => (name === 'writeFileSync'
+      ? (file        , data        , options     ) => target[name](file, data, { ...options, mode: 0o600 })
+      : (typeof target[name] === 'function' ? target[name].bind(target) : target[name])),
+  });
+  return atomicJsonWrite(statePath(homeDir), { ...state, audit: state.audit.slice(-AUDIT_MAX) }, { fsImpl: owned });
+}
+
+/** Read, apply `change` to the state, write. A malformed file is replaced only through `repairState`, so this refuses it. */
+function update(options     , change                      )      {
+  const read = readState(options);
+  if (read.unreadable) throw new Error('the package state file is unreadable; run verify --repair first');
+  change(read.state);
+  writeState(read.state, options);
+  return read.state;
+}
+
+/** Revoke trust for `packageId` at `contentDigest`: a trust grant counts only when its `at` is later than `at`. */
+function recordRevocation(options     , { packageId, contentDigest, at = new Date().toISOString() }     )      {
+  return update(options, (state) => {
+    state.revoked = state.revoked.filter((r     ) => !(r.package === packageId && r.contentDigest === contentDigest));
+    state.revoked.push({ package: packageId, contentDigest, at });
+  });
+}
+
+/** The last detected suspension for `packageId` (one per package); `projected` says its files are still on disk. */
+function recordSuspension(options     , { packageId, reason, projected = false, since = new Date().toISOString() }     )      {
+  return update(options, (state) => {
+    state.suspended = state.suspended.filter((s     ) => s.package !== packageId);
+    state.suspended.push({ package: packageId, reason, since, projected });
+  });
+}
+
+/** Drop the suspension record of `packageId` (it is intact again). */
+function clearSuspension(options     , { packageId }     )      {
+  return update(options, (state) => { state.suspended = state.suspended.filter((s     ) => s.package !== packageId); });
+}
+
+/** PN-1 tombstone: `remove` names the package's worker qualified ids; one entry per package, the latest. */
+function recordTombstone(options     , { packageId, qualifiedIds, at = new Date().toISOString() }     )      {
+  return update(options, (state) => {
+    state.removed = state.removed.filter((r     ) => r.package !== packageId);
+    state.removed.push({ package: packageId, qualifiedIds: [...qualifiedIds], at });
+  });
+}
+
+/** Append one package verb result; only the latest 64 entries are kept, newest last. */
+function appendAudit(options     , { verb, packageId, result, at = new Date().toISOString() }     )      {
+  return update(options, (state) => { state.audit.push({ at, verb, package: packageId, result }); });
+}
+
+/**
+ * `verify --repair` (IC-009): rewrite the state with one revocation per grant line present now (`grantEntries` is
+ * `readGrants(...).entries`; a line with a package and a content digest names its revocation), `at` the repair
+ * time. Suspensions, tombstones and audit are dropped with the unreadable file. Repair never widens: every
+ * grant read before `at` stays void until the person adds a line printed after it. A `fetch` line names no
+ * package, so it has no revocation record to hold; it widens network access only, and its result still needs trust.
+ */
+function repairState(options     , { grantEntries = [], at = new Date().toISOString() }      = {})      {
+  const state = emptyState();
+  for (const entry of grantEntries) {
+    if (!isText(entry?.package) || !DIGEST.test(entry?.contentDigest)) continue;
+    if (!state.revoked.some((r     ) => r.package === entry.package && r.contentDigest === entry.contentDigest)) {
+      state.revoked.push({ package: entry.package, contentDigest: entry.contentDigest, at });
+    }
+  }
+  state.audit.push({ at, verb: 'verify --repair', package: '*', result: `ok: ${state.revoked.length} revoked` });
+  writeState(state, options);
+  return state;
+}
+
+/**
+ * Whether a `trust` or `exempt` grant is revoked by `read` (a `readState` result): always when the state is
+ * unreadable; else when a revocation names the same package and content digest and the grant's `at` is not
+ * later than the revocation's.
+ */
+function grantRevoked(read     , grant     )          {
+  if (read.unreadable) return true;
+  return read.state.revoked.some((r     ) => r.package === grant.package && r.contentDigest === grant.contentDigest
+    && !(Date.parse(grant.at) > Date.parse(r.at)));
+}
+
+module.exports = {
+  statePath, readState, writeState, recordRevocation, recordSuspension, clearSuspension, recordTombstone,
+  appendAudit, repairState, grantRevoked, AUDIT_MAX,
+};

package/src/runtime/packages/store.js

@@ -0,0 +1,449 @@
+'use strict';
+
+/**
+ * Plans, the package store and the apply step (122 IC-006, IC-007, IC-012 `add` and `update` for a local
+ * source, IC-024 storage). A plan is a file under `~/.doflow/packages/plans/` that changes no record and
+ * activates nothing; applying one takes the global scope's `run.lock`, re-snapshots the source, recomputes both
+ * digests, stages a copy, re-hashes it, renames it into `store/<id>/<contentDigest first 16 hex>/`, writes the
+ * `.installed-from.json` marker beside the tree and writes the lock row last. A failure after the rename removes
+ * the entry before the lock is touched. Nothing here writes the person grant file.
+ *
+ * The plan's `projection` (IC-006) names, per harness of the global lock's `targets`, the skills and agents the
+ * package would project there and the listing bytes they add to that harness's always-loaded context; the
+ * projection itself is the lifecycle's (IC-017, `src/lifecycle/index.js`), which asks `projectionReach` here which
+ * harness can take which point. Remote plans retain a fetched snapshot and apply it without fetching again.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+const { isPackageId, projectedName } = require('../../helper/package-ids.js');
+const { checkPackage, MANIFEST_FILE } = require('./manifest.js');
+const { loadPoints } = require('./points.js');
+const { walkTree, digestFiles, canonicalJson } = require('./digest.js');
+const { hostVersion } = require('./view.js');
+const { readLock, writeLock, defaultLock, lockPackages } = require('../../state/lockfile.js');
+const { atomicJsonWrite } = require('../../state/index.js');
+const { acquireRunLock } = require('../../state/run-lock.js');
+const { pinSource, fetchSource } = require('./source.js');
+const { pinnedSourceFindings } = require('./index-file.js');
+
+const PLAN_VERSION = 1;
+const PLAN_ID = /^[0-9a-f]{16}$/;
+const DIGEST = /^[0-9a-f]{64}$/;
+const MARKER_SUFFIX = '.installed-from.json';
+const TIER_ORDER = ['inert', 'instruction', 'executable'];
+
+const sha256 = (data        )         => crypto.createHash('sha256').update(data).digest('hex');
+const isObject = (value     )          => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** `~/.doflow/packages` and its parts for a home directory. */
+function packagePaths(homeDir        )                                                                  {
+  const base = path.join(homeDir, '.doflow', 'packages');
+  return { base, plans: path.join(base, 'plans'), store: path.join(base, 'store'), fetched: path.join(base, 'fetched') };
+}
+
+function finding(field        , code        , message        , allowed     , pkg                = null)      {
+  return { package: pkg, field, code, severity: 'error', message, allowed };
+}
+
+/** The ISO 8601 UTC time of a grant line: whole seconds, as IC-008 prints it. */
+const grantTime = (when        )         => new Date(when).toISOString().replace(/\.\d+Z$/, 'Z');
+
+/**
+ * Check a local package directory and describe what it would add. `{ ok: false, findings }` when the checker
+ * reports an error; otherwise the manifest, both digests, the inventory (`point`, `qualifiedId`, `tier`, sorted)
+ * and the trust policy version the digests were taken under.
+ */
+function analyze(dir        , { repoRoot = REPO_ROOT, fsImpl = fs }      = {})      {
+  const loaded = loadPoints({ repoRoot });
+  const checked = checkPackage(dir, { repoRoot, hostVersion: hostVersion(repoRoot), bundled: [], fsImpl, ...(loaded.ok ? { pointsRegistry: loaded.registry } : {}) });
+  if (!checked.ok) return { ok: false, findings: checked.findings };
+  const manifest = JSON.parse(String(fsImpl.readFileSync(path.join(dir, MANIFEST_FILE), 'utf8')));
+  const tiers                         = Object.fromEntries(loaded.registry.points.map((p     ) => [p.id, p.tier]));
+  const inventory = (manifest.contributions ?? [])
+    .map((c     ) => ({ point: c.point, qualifiedId: `${manifest.id}.${c.id}`, tier: tiers[c.point] }))
+    .sort((a     , b     ) => (a.point < b.point ? -1 : a.point > b.point ? 1 : a.qualifiedId < b.qualifiedId ? -1 : a.qualifiedId > b.qualifiedId ? 1 : 0));
+  const programs = [...(manifest.programs ?? [])].sort((a     , b     ) => (String(a.id) < String(b.id) ? -1 : String(a.id) > String(b.id) ? 1 : 0));
+  return {
+    ok: true, findings: checked.findings, manifest, inventory, programs, contentDigest: checked.contentDigest, capabilityDigest: checked.capabilityDigest,
+    trustPolicyVersion: loaded.registry.trustPolicyVersion, limits: loaded.registry.limits,
+  };
+}
+
+// ── projection reach and the plan's `projection` (IC-017, IC-006) ───────────────────────────────────
+
+/** The built-in asset whose per-harness projection (renderer, transform, layout, destination) a package
+ * contribution of each instruction point borrows, so it lands where and how DoFlow's own skills and agents do. */
+const BORROWED_ASSET                         = { skill: 'skills.doflow', agent: 'agents.shared' };
+const CAPABILITY                         = { skill: 'skills', agent: 'agents' };
+const INSTRUCTION_POINTS = Object.keys(BORROWED_ASSET);
+
+/**
+ * Whether `harnessId` can take a package contribution of `point` (IC-017 harness reach): `{ ok: true, projection,
+ * nativeDir }` with the borrowed asset's projection for that harness, else `{ ok: false, reason }`. The capability
+ * is the harness's `skills` or `agents` capability in `harnesses.json`; `unavailable` is the gap NFR-003 names.
+ */
+function projectionReach(registry     , harnessId        , point        )      {
+  const harness = registry.harnesses.find((h     ) => h.id === harnessId);
+  if (!harness) return { ok: false, reason: 'it is not a harness this DoFlow knows' };
+  const name = CAPABILITY[point];
+  if (!name) return { ok: false, reason: `${point} is not an instruction point` };
+  const capability = harness.capabilities?.[name];
+  if (!capability || capability.status === 'unavailable') return { ok: false, reason: `its ${name} capability is unavailable` };
+  const asset = registry.assets.find((a     ) => a.id === BORROWED_ASSET[point]);
+  const projection = asset?.projection?.[harnessId];
+  if (!projection) return { ok: false, reason: `DoFlow projects no ${name} into it (capability ${capability.status})` };
+  return { ok: true, projection, nativeDir: asset.nativeDir?.[harnessId] ?? '' };
+}
+
+/** The `name: value` pairs of a Markdown file's frontmatter, quotes stripped; empty when there is none. */
+function frontmatterValues(text        )                         {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  const values                         = {};
+  for (const line of match ? match[1].split(/\r?\n/) : []) {
+    const item = /^([A-Za-z][A-Za-z0-9_-]*):[ \t]*(.*)$/.exec(line);
+    if (item) values[item[1]] = item[2].trim().replace(/^"(.*)"$/, '$1');
+  }
+  return values;
+}
+
+/** The bytes a contribution adds to a harness's always-loaded listing: its name and description, plus a skill's
+ * `when_to_use` (what G22 counts for DoFlow's own skills). 0 when the file cannot be read. */
+function listingBytes(file        , fsImpl     )         {
+  try {
+    const values = frontmatterValues(String(fsImpl.readFileSync(file, 'utf8')));
+    return ['name', 'description', 'when_to_use'].reduce((sum, key) => sum + Buffer.byteLength(values[key] ?? '', 'utf8'), 0);
+  } catch { return 0; }
+}
+
+/** The instruction contributions of a manifest: `{ point, qualifiedId, name, path }`, `path` relative to the package root. */
+function instructionEntries(manifest     )        {
+  return (Array.isArray(manifest?.contributions) ? manifest.contributions : [])
+    .filter((c     ) => c && INSTRUCTION_POINTS.includes(c.point) && c.version === 1 && typeof c.id === 'string' && typeof (c.point === 'skill' ? c.dir : c.file) === 'string')
+    .map((c     ) => ({ point: c.point, qualifiedId: `${manifest.id}.${c.id}`, name: projectedName(`${manifest.id}.${c.id}`) ?? `${manifest.id}-${c.id}`, path: c.point === 'skill' ? c.dir : c.file }));
+}
+
+/**
+ * The plan's `projection` (IC-006): per harness of the global lock's `targets`, the projected names by point and
+ * the listing bytes they add there; a contribution the harness cannot take is named under `unreachable` and in
+ * `warnings`. `{}` for a package with no skill or agent, or when no harness is installed at global scope.
+ */
+function projectionPreview(dir        , manifest     , lock     , { repoRoot = REPO_ROOT, registry, fsImpl = fs }      = {})                                                          {
+  const entries = instructionEntries(manifest);
+  const harnesses = (lock?.targets ?? []).map((t     ) => t?.harness).filter((h     ) => typeof h === 'string');
+  const projection                      = {};
+  const warnings           = [];
+  if (entries.length === 0 || harnesses.length === 0) return { projection, warnings };
+  const reg = registry ?? require('../../registry/index.js').loadRegistry({ repoRoot });
+  for (const harness of harnesses) {
+    const row      = { listingBytes: 0 };
+    for (const entry of entries) {
+      const reach = projectionReach(reg, harness, entry.point);
+      if (!reach.ok) {
+        (row.unreachable ??= []).push(entry.name);
+        warnings.push(`${harness} cannot take ${entry.point} ${entry.qualifiedId}: ${reach.reason}`);
+        continue;
+      }
+      (row[entry.point] ??= []).push(entry.name);
+      row.listingBytes += listingBytes(path.join(dir, ...entry.path.split('/'), ...(entry.point === 'skill' ? ['SKILL.md'] : [])), fsImpl);
+    }
+    projection[harness] = row;
+  }
+  return { projection, warnings };
+}
+
+/** The highest tier in an inventory (`inert` for none). */
+const tierMax = (inventory       )         => inventory.reduce((top        , c     ) => (TIER_ORDER.indexOf(c.tier) > TIER_ORDER.indexOf(top) ? c.tier : top), 'inert');
+
+/**
+ * The plan id: the first 16 hex of sha256(content NUL capability NUL canonical source) (IC-006). The storage
+ * engine reads a name that starts with 13 decimal digits as a millisecond timestamp, which would let the
+ * plans store prune a fresh plan at once (about 1 id in 450), so such a candidate is rerolled by hashing
+ * the same text with `NUL <n>` appended, n = 1, 2, ... The result stays 16 hex and is still a function of the
+ * inputs. `hash` is a test seam.
+ */
+function planIdFor(text        , hash                           = sha256)         {
+  for (let n = 0; ; n += 1) {
+    const candidate = hash(n === 0 ? text : `${text}\0${n}`).slice(0, 16);
+    if (!/^[0-9]{13}/.test(candidate)) return candidate;
+  }
+}
+
+/**
+ * Check a directory and write its plan. Local calls write only the plan. Remote calls supply a pinnedSource
+ * and move their checked staging tree into fetched/<planId> before publishing the plan.
+ */
+function planPackage({ action, source, id, pinnedSource, expected, homeDir = os.homedir(), repoRoot = REPO_ROOT, now = Date.now(), hash, registry, fsImpl = fs }     )      {
+  if (pinnedSource) {
+    const findings = pinnedSourceFindings(pinnedSource);
+    if (findings.length) return { ok: false, findings };
+  }
+  const lock = readLock({ scope: 'global', homeDir }, { fsImpl });
+  const rows = lockPackages(lock);
+  let sourcePath = source;
+  if (action === 'update') {
+    const row = rows.find((r     ) => r.id === id);
+    if (!row) return { ok: false, findings: [finding('id', 'bad-id', `no package with id '${id}' is recorded`, 'the id of a recorded package', id)] };
+    if (row.source?.type !== 'local') return { ok: false, findings: [finding('source', 'bad-type', `package '${id}' has a remote source; remove it and use add --source or add --index with a new spec`, 'a local source for update, or a new add after remove', id)] };
+    sourcePath = row.source.path;
+  }
+  const analysis = analyze(sourcePath, { repoRoot, fsImpl });
+  if (!analysis.ok) return { ok: false, findings: analysis.findings };
+  const { manifest } = analysis;
+  if (expected && (manifest.id !== expected.id || manifest.version !== expected.version)) {
+    return { ok: false, findings: [finding('source', 'bad-id', `fetched package ${manifest.id} ${manifest.version} does not match index selection ${expected.id} ${expected.version}`, expected)] };
+  }
+  if (action === 'add' && rows.some((r     ) => r.id === manifest.id)) {
+    return { ok: false, findings: [finding('id', 'collision-package', `package '${manifest.id}' is already recorded; use update`, 'an id no recorded package uses', manifest.id)] };
+  }
+  if (action === 'update' && manifest.id !== id) {
+    return { ok: false, findings: [finding('id', 'bad-id', `the manifest at ${sourcePath} names '${manifest.id}', not '${id}'`, id, id)] };
+  }
+  const source_ = pinnedSource ?? { type: 'local', path: sourcePath };
+  const planId = planIdFor(`${analysis.contentDigest}\0${analysis.capabilityDigest}\0${canonicalJson(source_)}`, hash);
+  const grantLines                         = {};
+  if (tierMax(analysis.inventory) !== 'inert') {
+    grantLines.trust = JSON.stringify({
+      grant: 'trust', package: manifest.id, version: manifest.version, contentDigest: analysis.contentDigest,
+      capabilityDigest: analysis.capabilityDigest, policy: analysis.trustPolicyVersion, at: grantTime(now),
+    });
+  }
+  const preview = projectionPreview(sourcePath, manifest, lock, { repoRoot, registry, fsImpl });
+  const plan = {
+    plan: PLAN_VERSION, planId, createdAt: new Date(now).toISOString(), action, source: source_,
+    package: { id: manifest.id, version: manifest.version, doflow: manifest.doflow },
+    contentDigest: analysis.contentDigest, capabilityDigest: analysis.capabilityDigest, trustPolicyVersion: analysis.trustPolicyVersion,
+    inventory: analysis.inventory, programs: analysis.programs, projection: preview.projection, findings: analysis.findings, grantLines,
+  };
+  const paths = packagePaths(homeDir);
+  const planFile = path.join(paths.plans, `${planId}.json`);
+  if (pinnedSource) {
+    const snapshot = path.join(paths.fetched, planId);
+    fsImpl.mkdirSync(paths.fetched, { recursive: true });
+    if (fsImpl.existsSync(snapshot)) {
+      if (digestOf(snapshot, analysis.limits, fsImpl) !== analysis.contentDigest) {
+        return { ok: false, findings: [finding('contentDigest', 'digest-mismatch', `retained snapshot for plan ${planId} has changed`, analysis.contentDigest, manifest.id)] };
+      }
+    } else {
+      fsImpl.renameSync(sourcePath, snapshot);
+    }
+    fsImpl.utimesSync(snapshot, new Date(now), new Date(now));
+  }
+  atomicJsonWrite(planFile, plan, { fsImpl });
+  return { ok: true, plan, planFile, tierMax: tierMax(analysis.inventory), projectionWarnings: preview.warnings, instructions: instructionEntries(manifest).length };
+}
+
+/** Pin, fetch and retain a checked remote tree. The command has already checked the fetch grant. */
+function planRemote({ source, pinned, expected, homeDir = os.homedir(), repoRoot = REPO_ROOT, env = process.env, now = Date.now(), registry, fsImpl = fs }     )      {
+  if (!pinned) {
+    const pin = pinSource(source, { env });
+    if (!pin.ok) return { ok: false, findings: [pin.finding] };
+    pinned = pin.pinned;
+  }
+  const findings = pinnedSourceFindings(pinned);
+  if (findings.length) return { ok: false, findings };
+  const loaded = loadPoints({ repoRoot });
+  if (!loaded.ok) return { ok: false, findings: [finding('points', 'state-unreadable', loaded.errors.join('; '), 'a valid point registry')] };
+  const staging = path.join(packagePaths(homeDir).fetched, `.staging-${crypto.randomBytes(8).toString('hex')}`);
+  fsImpl.mkdirSync(path.dirname(staging), { recursive: true });
+  fsImpl.mkdirSync(staging);
+  try {
+    const fetched = fetchSource(pinned, { stagingDir: staging, env, limits: loaded.registry.limits });
+    if (!fetched.ok) return fetched;
+    const tree = path.join(staging, 'tree');
+    fsImpl.mkdirSync(tree);
+    for (const file of fetched.files) {
+      const target = path.join(tree, ...file.path.split('/'));
+      fsImpl.mkdirSync(path.dirname(target), { recursive: true });
+      fsImpl.writeFileSync(target, file.data);
+      fsImpl.chmodSync(target, file.mode);
+    }
+    return planPackage({ action: 'add', source: tree, pinnedSource: pinned, expected, homeDir, repoRoot, now, registry, fsImpl });
+  } finally {
+    fsImpl.rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+/** A plan file's content when it is the IC-006 shape with a local or pinned remote source, else a finding. */
+function readPlan(planId        , homeDir        , fsImpl     )      {
+  const planFile = path.join(packagePaths(homeDir).plans, `${planId}.json`);
+  let text        ;
+  try { text = String(fsImpl.readFileSync(planFile, 'utf8')); } catch (error     ) {
+    if (error?.code === 'ENOENT') return { finding: finding('plan', 'file-missing', `no plan ${planId}; a plan is kept for 24 hours`, 'a plan id printed by add or update') };
+    return { finding: finding('plan', 'state-unreadable', `plan ${planId} cannot be read: ${error?.message}`, 'a readable plan file') };
+  }
+  let plan     ;
+  try { plan = JSON.parse(text); } catch { plan = null; }
+  const ok = isObject(plan) && plan.plan === PLAN_VERSION && plan.planId === planId && (plan.action === 'add' || plan.action === 'update')
+    && isObject(plan.source) && ((plan.source.type === 'local' && typeof plan.source.path === 'string' && path.isAbsolute(plan.source.path))
+      || (plan.action === 'add' && pinnedSourceFindings(plan.source).length === 0))
+    && isObject(plan.package) && isPackageId(plan.package.id) && DIGEST.test(plan.contentDigest) && DIGEST.test(plan.capabilityDigest);
+  if (!ok) return { finding: finding('plan', 'state-unreadable', `plan ${planId} is not a plan this DoFlow wrote`, 'a plan written by package add or update') };
+  return { plan };
+}
+
+/** Copy the regular files of `files` under `dest`, normalising the mode to the execute bit alone. */
+function copyFiles(files       , dest        , fsImpl     )       {
+  for (const file of files) {
+    const target = path.join(dest, ...file.rel.split('/'));
+    fsImpl.mkdirSync(path.dirname(target), { recursive: true });
+    fsImpl.copyFileSync(file.abs, target);
+    fsImpl.chmodSync(target, file.exec ? 0o755 : 0o644);
+  }
+}
+
+/** The IC-005 content digest of a directory, or null when its tree breaks a tree rule. */
+function digestOf(dir        , limits     , fsImpl     )                {
+  const walked = walkTree(dir, limits, { fsImpl });
+  return walked.findings.length > 0 ? null : digestFiles(walked.files, fsImpl);
+}
+
+/** Remove a store entry's tree and marker, and the id directory when that leaves it empty. Never throws. */
+function removeEntry(idDir        , digest16        , fsImpl     )          {
+  try {
+    fsImpl.rmSync(path.join(idDir, digest16), { recursive: true, force: true });
+    fsImpl.rmSync(path.join(idDir, `${digest16}${MARKER_SUFFIX}`), { force: true });
+    if (fsImpl.readdirSync(idDir).length === 0) fsImpl.rmdirSync(idDir);
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * Storage upkeep for the package stores. `upkeepAfterVerb` visits the state and config roots only (its
+ * `MOMENT_ROOTS`), so the declared rows `packages-plans` and `packages-staging` carry no moment and the plans
+ * (24 hours) and stale staging directories under `~/.doflow/packages` are pruned here, by the engine, whenever
+ * a plan is applied. It honours the prune setting and `DOFLOW_UPKEEP=off`, and never throws.
+ */
+function pruneStale({ homeDir, env, now, fsImpl }     )       {
+  if (env.DOFLOW_UPKEEP === 'off') return;
+  try {
+    const { loadStorageRegistry } = require('../storage/registry.js');
+    const { resolveRoots, readPruneSetting } = require('../storage/roots.js');
+    const { runPass } = require('../storage/engine.js');
+    const registry = loadStorageRegistry({ repoRoot: REPO_ROOT });
+    const roots = resolveRoots({ registry, global: true, env: { ...env, HOME: homeDir } });
+    const { setting } = readPruneSetting({ roots, rootId: 'user-doflow', fsImpl });
+    runPass({ registry, roots, stores: ['packages-plans', 'packages-staging', 'packages-fetched', 'packages-fetch-staging'], mode: 'prune', setting: { 'user-doflow': setting }, now, env, fsImpl });
+    if (setting === 'on') {
+      const paths = packagePaths(homeDir);
+      if (fsImpl.existsSync(paths.fetched)) {
+        for (const name of fsImpl.readdirSync(paths.fetched)) {
+          if (PLAN_ID.test(name) && !fsImpl.existsSync(path.join(paths.plans, `${name}.json`))) {
+            fsImpl.rmSync(path.join(paths.fetched, name), { recursive: true, force: true });
+          }
+        }
+      }
+    }
+  } catch { /* upkeep must never affect the apply */ }
+}
+
+/**
+ * Apply a plan (`add --plan` or `update --plan`). `action` names the verb the caller ran: a plan of the other
+ * kind is refused. Returns `{ ok: true, ... }` or `{ ok: false, findings }` (a refusal writes no store entry and
+ * leaves the lock byte-identical); an unexpected failure throws after the entry it made is removed and the run
+ * lock released. `hooks` are test seams: `afterCopy(stagingDir)` runs after the copy and before the re-hash,
+ * `afterRename(entryDir)` runs right after the rename.
+ */
+function applyPlan({ planId, action = null, homeDir = os.homedir(), repoRoot = REPO_ROOT, env = process.env, now = Date.now(), hooks = {}, fsImpl = fs }     )      {
+  const read = readPlan(planId, homeDir, fsImpl);
+  if (read.finding) return { ok: false, findings: [read.finding] };
+  const { plan } = read;
+  if (action !== null && plan.action !== action) {
+    return { ok: false, findings: [finding('action', 'bad-type', `plan ${planId} is ${plan.action === 'add' ? 'an add' : 'an update'} plan`, `a plan made by ${action}`, plan.package.id)] };
+  }
+  const hold = acquireRunLock({ scopeRoot: homeDir, scope: 'global', command: `package ${plan.action}` });
+  try {
+    pruneStale({ homeDir, env, now, fsImpl });
+    return applyLocked({ plan, homeDir, repoRoot, now, hooks, fsImpl });
+  } finally {
+    hold.release();
+  }
+}
+
+function applyLocked({ plan, homeDir, repoRoot, now, hooks, fsImpl }     )      {
+  const id = plan.package.id;
+  const lock = readLock({ scope: 'global', homeDir }, { fsImpl });
+  const rows = lockPackages(lock);
+  const previous = rows.find((r     ) => r.id === id) ?? null;
+  if (plan.action === 'add' && previous) {
+    return { ok: false, findings: [finding('id', 'collision-package', `package '${id}' is already recorded; use update`, 'an id no recorded package uses', id)] };
+  }
+  if (plan.action === 'update' && !previous) {
+    return { ok: false, findings: [finding('id', 'bad-id', `no package with id '${id}' is recorded`, 'the id of a recorded package', id)] };
+  }
+  const remote = plan.source.type !== 'local';
+  const sourceDir = remote ? path.join(packagePaths(homeDir).fetched, plan.planId) : plan.source.path;
+  if (remote) {
+    const loaded = loadPoints({ repoRoot });
+    if (!loaded.ok) return { ok: false, findings: [finding('points', 'state-unreadable', loaded.errors.join('; '), 'a valid point registry', id)] };
+    if (digestOf(sourceDir, loaded.registry.limits, fsImpl) !== plan.contentDigest) {
+      return { ok: false, findings: [finding('contentDigest', 'digest-mismatch', `fetched snapshot for plan ${plan.planId} is missing or changed; plan again`, plan.contentDigest, id)] };
+    }
+  }
+  const analysis = analyze(sourceDir, { repoRoot, fsImpl });
+  if (!analysis.ok) return { ok: false, findings: analysis.findings };
+  const changed = [
+    ['contentDigest', analysis.contentDigest, plan.contentDigest], ['capabilityDigest', analysis.capabilityDigest, plan.capabilityDigest],
+    ['id', analysis.manifest.id, id],
+  ].filter(([, now_, planned]) => now_ !== planned);
+  if (changed.length > 0) {
+    return { ok: false, findings: changed.map(([field]) => finding(field, 'digest-mismatch', `${field} of ${sourceDir} differs from plan ${plan.planId}; plan again`, `the ${field} the plan recorded`, id)) };
+  }
+
+  const { store } = packagePaths(homeDir);
+  const digest16 = plan.contentDigest.slice(0, 16);
+  const staging = path.join(store, `.staging-${plan.planId}`);
+  const idDir = path.join(store, id);
+  const entry = path.join(idDir, digest16);
+  fsImpl.mkdirSync(store, { recursive: true });
+  fsImpl.rmSync(staging, { recursive: true, force: true });
+  const mismatch = (message        ) => {
+    fsImpl.rmSync(staging, { recursive: true, force: true });
+    return { ok: false, findings: [finding('contentDigest', 'digest-mismatch', message, `the contentDigest the plan recorded`, id)] };
+  };
+  try {
+    const source = walkTree(sourceDir, analysis.limits, { fsImpl });
+    if (source.findings.length > 0) return mismatch(`${sourceDir} no longer passes the tree rules (${source.findings.map((f     ) => f.code).join(', ')}); plan again`);
+    copyFiles(source.files, staging, fsImpl);
+    if (typeof hooks.afterCopy === 'function') hooks.afterCopy(staging);
+    if (digestOf(staging, analysis.limits, fsImpl) !== plan.contentDigest) return mismatch(`the staged copy of ${sourceDir} differs from plan ${plan.planId}; plan again`);
+
+    fsImpl.mkdirSync(idDir, { recursive: true });
+    let created = false;
+    if (fsImpl.existsSync(entry)) {
+      // A leftover of an interrupted run, or an update that changed capabilities only: reuse it when it holds the planned bytes.
+      fsImpl.rmSync(staging, { recursive: true, force: true });
+      if (digestOf(entry, analysis.limits, fsImpl) !== plan.contentDigest) {
+        return { ok: false, findings: [finding('store', 'integrity-mismatch', `the store entry for ${id} ${digest16} does not hold the planned bytes`, 'an intact store entry', id)] };
+      }
+    } else {
+      fsImpl.renameSync(staging, entry);
+      created = true;
+    }
+    const row = {
+      id, version: analysis.manifest.version, source: plan.source, contentDigest: plan.contentDigest, capabilityDigest: plan.capabilityDigest,
+      enabled: previous ? previous.enabled : false, addedAt: previous ? previous.addedAt : new Date(now).toISOString(),
+    };
+    try {
+      if (typeof hooks.afterRename === 'function') hooks.afterRename(entry);
+      atomicJsonWrite(`${entry}${MARKER_SUFFIX}`, {
+        marker: 1, planId: plan.planId, action: plan.action, source: plan.source, contentDigest: plan.contentDigest,
+        capabilityDigest: plan.capabilityDigest, installedAt: new Date(now).toISOString(),
+      }, { fsImpl });
+      writeLock({ scope: 'global', homeDir }, { ...(lock ?? defaultLock({ scope: 'global', scopeRoot: homeDir })), packages: [...rows.filter((r     ) => r.id !== id), row] }, { fsImpl });
+    } catch (error) {
+      if (created) removeEntry(idDir, digest16, fsImpl);
+      throw error;
+    }
+    const oldDigest16 = previous ? previous.contentDigest.slice(0, 16) : null;
+    const leftover = oldDigest16 !== null && oldDigest16 !== digest16 && !removeEntry(idDir, oldDigest16, fsImpl);
+    return { ok: true, action: plan.action, id, version: row.version, enabled: row.enabled, storeDir: entry, contentDigest: row.contentDigest, capabilityDigest: row.capabilityDigest, leftover };
+  } finally {
+    fsImpl.rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+module.exports = { planIdFor, planPackage, planRemote, applyPlan, packagePaths, removeEntry, projectionReach, instructionEntries, PLAN_ID, MARKER_SUFFIX };