@inventarch/cli 1.2.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/README.md +20 -5
  2. package/SPEC.md +86 -11
  3. package/assets/base/08eaab3e1a6215d78283b82a94a0228367ac7bd78d0a746c56db79c8d7546c3a.ia.tgz +0 -0
  4. package/assets/base.json +3 -3
  5. package/assets/host/d7722e32fd0511df2a6dfdf2353e621fdff1cf559d5c8b7ac256c7eceac0452f.tgz +0 -0
  6. package/assets/host.json +4 -4
  7. package/assets/vocabulary.json +11 -3
  8. package/dist/adopt.d.ts +8 -0
  9. package/dist/adopt.d.ts.map +1 -0
  10. package/dist/adopt.js +60 -0
  11. package/dist/adopt.js.map +1 -0
  12. package/dist/author.d.ts +32 -0
  13. package/dist/author.d.ts.map +1 -0
  14. package/dist/author.js +226 -0
  15. package/dist/author.js.map +1 -0
  16. package/dist/briefing.d.ts +2 -0
  17. package/dist/briefing.d.ts.map +1 -1
  18. package/dist/briefing.js +15 -3
  19. package/dist/briefing.js.map +1 -1
  20. package/dist/bundled-base.d.ts +18 -0
  21. package/dist/bundled-base.d.ts.map +1 -0
  22. package/dist/bundled-base.js +44 -0
  23. package/dist/bundled-base.js.map +1 -0
  24. package/dist/capture.d.ts +41 -6
  25. package/dist/capture.d.ts.map +1 -1
  26. package/dist/capture.js +132 -43
  27. package/dist/capture.js.map +1 -1
  28. package/dist/commands.d.ts +30 -8
  29. package/dist/commands.d.ts.map +1 -1
  30. package/dist/commands.js +287 -35
  31. package/dist/commands.js.map +1 -1
  32. package/dist/compile.d.ts +3 -4
  33. package/dist/compile.d.ts.map +1 -1
  34. package/dist/compile.js +28 -72
  35. package/dist/compile.js.map +1 -1
  36. package/dist/consumer.d.ts +11 -2
  37. package/dist/consumer.d.ts.map +1 -1
  38. package/dist/consumer.js +103 -20
  39. package/dist/consumer.js.map +1 -1
  40. package/dist/distribute.d.ts +30 -8
  41. package/dist/distribute.d.ts.map +1 -1
  42. package/dist/distribute.js +112 -60
  43. package/dist/distribute.js.map +1 -1
  44. package/dist/doctor-authority.d.ts +3 -0
  45. package/dist/doctor-authority.d.ts.map +1 -0
  46. package/dist/doctor-authority.js +65 -0
  47. package/dist/doctor-authority.js.map +1 -0
  48. package/dist/doctor-mounts.d.ts +4 -0
  49. package/dist/doctor-mounts.d.ts.map +1 -0
  50. package/dist/doctor-mounts.js +32 -0
  51. package/dist/doctor-mounts.js.map +1 -0
  52. package/dist/doctor.d.ts.map +1 -1
  53. package/dist/doctor.js +327 -79
  54. package/dist/doctor.js.map +1 -1
  55. package/dist/format.d.ts.map +1 -1
  56. package/dist/format.js +2 -1
  57. package/dist/format.js.map +1 -1
  58. package/dist/host-projection.d.ts +131 -6
  59. package/dist/host-projection.d.ts.map +1 -1
  60. package/dist/host-projection.js +663 -42
  61. package/dist/host-projection.js.map +1 -1
  62. package/dist/host.d.ts +154 -32
  63. package/dist/host.d.ts.map +1 -1
  64. package/dist/host.js +393 -142
  65. package/dist/host.js.map +1 -1
  66. package/dist/init.d.ts +296 -38
  67. package/dist/init.d.ts.map +1 -1
  68. package/dist/init.js +1303 -203
  69. package/dist/init.js.map +1 -1
  70. package/dist/main.d.ts +1 -6
  71. package/dist/main.d.ts.map +1 -1
  72. package/dist/main.js +4 -7
  73. package/dist/main.js.map +1 -1
  74. package/dist/migration-journal.d.ts +35 -0
  75. package/dist/migration-journal.d.ts.map +1 -0
  76. package/dist/migration-journal.js +205 -0
  77. package/dist/migration-journal.js.map +1 -0
  78. package/dist/next.d.ts +21 -0
  79. package/dist/next.d.ts.map +1 -0
  80. package/dist/next.js +216 -0
  81. package/dist/next.js.map +1 -0
  82. package/dist/operation-help.d.ts.map +1 -1
  83. package/dist/operation-help.js +15 -4
  84. package/dist/operation-help.js.map +1 -1
  85. package/dist/pack.d.ts.map +1 -1
  86. package/dist/pack.js +24 -2
  87. package/dist/pack.js.map +1 -1
  88. package/dist/position.d.ts +22 -0
  89. package/dist/position.d.ts.map +1 -0
  90. package/dist/position.js +244 -0
  91. package/dist/position.js.map +1 -0
  92. package/dist/preview.d.ts +145 -0
  93. package/dist/preview.d.ts.map +1 -0
  94. package/dist/preview.js +962 -0
  95. package/dist/preview.js.map +1 -0
  96. package/dist/profile.d.ts +118 -0
  97. package/dist/profile.d.ts.map +1 -0
  98. package/dist/profile.js +362 -0
  99. package/dist/profile.js.map +1 -0
  100. package/dist/project.d.ts +45 -0
  101. package/dist/project.d.ts.map +1 -0
  102. package/dist/project.js +263 -0
  103. package/dist/project.js.map +1 -0
  104. package/dist/read.d.ts +12 -2
  105. package/dist/read.d.ts.map +1 -1
  106. package/dist/read.js +32 -18
  107. package/dist/read.js.map +1 -1
  108. package/dist/render.d.ts +24 -2
  109. package/dist/render.d.ts.map +1 -1
  110. package/dist/render.js +171 -4
  111. package/dist/render.js.map +1 -1
  112. package/dist/session.d.ts +39 -12
  113. package/dist/session.d.ts.map +1 -1
  114. package/dist/session.js +55 -11
  115. package/dist/session.js.map +1 -1
  116. package/dist/user-host.d.ts +3 -3
  117. package/dist/user-host.js +10 -10
  118. package/dist/user-host.js.map +1 -1
  119. package/dist/validate.d.ts +28 -16
  120. package/dist/validate.d.ts.map +1 -1
  121. package/dist/validate.js +245 -23
  122. package/dist/validate.js.map +1 -1
  123. package/package.json +6 -6
  124. package/assets/base/0305ca741b1dfec97ff35fbeb36d4a66a0c9c0614b730fe14fcdac0f1565e28a.ia.tgz +0 -0
  125. package/assets/host/c5fb2bfbba619cbd558ecc1e94dd2c16e37aa8599b4e423f1f59ed01f2074e03.tgz +0 -0
package/dist/doctor.js CHANGED
@@ -11,14 +11,24 @@
11
11
  * payload pin: `registered` is `ok` and its detail says "written; not observed answering", because doctor never
12
12
  * starts a server and a written registration is not a server that answered; `stale` is `fail`, so doctor exits 1
13
13
  * (REQ-HRC-5), and its detail names each reason and the repair that works for it; no host state at all is `info`.
14
- * Projection drift is one row per managed file. An installation that carries no host payload is a note, not a crash:
14
+ * Projection drift is read from the receipt the projection apply wrote (B12, milestone position-packet): one row per
15
+ * listed file that is missing or changed, one when the records render another packet, one `ok` row when it found none of
16
+ * these, and one listing the legacy files it removed and the foreign ones it left. A projection `ia project` wrote
17
+ * without a host registration is read the same way, its remedies naming `ia project <host> --apply` as the install
18
+ * refresh's do (`projectionRerun`, task ia-project-verb), and it leaves the host unregistered in the briefing. An
19
+ * installation that carries no host payload is a note, not a crash:
15
20
  * the release comparison is skipped and the row says so. Observation is total — a malformed state file is a `fail`
16
21
  * row, never an exception — and nothing here writes, the host home included. Repairs are worded by `ia host`'s own
17
- * `stateRepair` and `modifiedRepair`, so the two verbs cannot disagree, and every `ia host` command printed carries
18
- * `--root` when doctor was given one.
22
+ * `stateRepair` and `modifiedRepair`, so the two verbs cannot disagree, and every `ia host` or `ia project` command
23
+ * printed carries `--root` when doctor was given one.
24
+ *
25
+ * Milestone generation-binding (plan amendments C16 and C24, design item 9) adds an `implementations` row for the
26
+ * installed-implementation catalog of the payload this installation pins, read through its release pins and checked
27
+ * against the handler bytes the payload ships, and a `join-<host>` row per join receipt `ia host` recorded, compared
28
+ * with the catalog of the payload that host's registration names. Both only read; no handler is imported or run.
19
29
  *
20
30
  * The support row compares an observed platform and version against the declaration at
21
- * docs/reports/open-source-v1/2026-09-30/decisions.md:13. It says "matches the declared target", never "qualified", because
31
+ * docs/specs/host-registration/README.md §7. It says "matches the declared target", never "qualified", because
22
32
  * that declaration says the minimum must be validated before being advertised. A platform outside it is `warn`,
23
33
  * never `fail`, and the word "unsupported" is not used about it.
24
34
  *
@@ -41,24 +51,27 @@
41
51
  import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
42
52
  import { homedir } from 'node:os';
43
53
  import { isAbsolute, join, relative, resolve, sep } from 'node:path';
44
- import { WORKSPACE_PROJECTION_MARKER } from '@inventarch/compliance';
45
54
  // `within` judges nesting on disk, so a home or cache spelled in another case or normalization is still where it is (#315).
46
55
  import { pathKey, within } from '@inventarch/db';
47
56
  import { decodeDistributionJson, INSTALL_PATHS } from '@inventarch/db/distribution';
48
- import { verifyHostCache } from '@inventarch/distribution/host';
49
57
  import { hostPayloadPath, legacyHostHome } from '@inventarch/distribution/host-home';
50
58
  import { resolveIaHome } from '@inventarch/distribution/ia-home';
59
+ import { INSTALLED_IMPLEMENTATIONS, JOINS, readInstalledImplementations, readJoins, registrationUntrusted, trustedPayload, } from '@inventarch/distribution/implementations';
60
+ import { hostVerifier } from '@inventarch/distribution/host-observe';
51
61
  import { observeProjection } from '@inventarch/distribution/projection';
62
+ import { observeHookRegistration } from '@inventarch/distribution/guard-registration';
52
63
  import { registryChooser, registryLocation } from '@inventarch/distribution/registry';
53
- import { readInstalledState, readWorkspaceLock, validateWorkspace } from '@inventarch/distribution/services';
64
+ import { readInstalledState, readWorkspaceFile, readWorkspaceLock, sha256, validateWorkspace, } from '@inventarch/distribution/services';
65
+ import { PACKET_MARKER } from '@inventarch/runtime';
54
66
  import { brief } from './briefing.js';
55
67
  import { discoverRoot, iaHomeOf } from './consumer.js';
56
68
  import { UNMAPPED } from './distribute.js';
57
69
  import { userRows } from './doctor-user.js';
58
- import { renderProjectionFor } from './host-projection.js';
59
- import { HOST_LOCK, HOSTS_AREA, JOURNALS, MCP_PATH, modifiedRepair, pinnedRelease, projectionRepair, recoverCommand, refusedPath, rootedNext, SETTINGS, STATE, stateRepair, } from './host.js';
70
+ import { sourceProtectionCheck } from './doctor-authority.js';
71
+ import { HOOK_KEPT, planRetirement, readReceipt, renderProjectionFor } from './host-projection.js';
72
+ import { HOST_LOCK, HOSTS_AREA, JOURNALS, MCP_PATH, modifiedRepair, pinnedRelease, projectedHosts, projectionFailure, projectionRepair, projectionRerun, recoverCommand, rootedNext, SETTINGS, STATE, stateRepair, } from './host.js';
60
73
  import { codeOf } from './session.js';
61
- import { atom, document, entry, fieldRows, sectionLabel, words } from './render.js';
74
+ import { atom, document, entry, fieldRows, safeRootAdvice, sectionLabel, words } from './render.js';
62
75
  /** decisions.md:13. Linux and Windows on x64 and macOS on arm64, on Node 22 with 22.22.0 the initial minimum; pnpm is contributor-only. */
63
76
  export const SUPPORTED_TARGETS = [
64
77
  { platform: 'linux', arch: 'x64' },
@@ -171,7 +184,7 @@ const installation = (id, title, status, detail, remedy) => ({
171
184
  });
172
185
  const commandsFor = (root) => {
173
186
  const prose = (host, text) => (root === undefined ? text : rootedNext(text, host, root));
174
- return { prose, apply: (host) => prose(host, `"ia host ${host} --apply"`).slice(1, -1) };
187
+ return { prose, apply: (host, command = `ia host ${host} --apply`) => prose(host, `"${command}"`).slice(1, -1) };
175
188
  };
176
189
  /**
177
190
  * §3.3: the payload this installation pins, and whether the host home holds it. Cheap on purpose — one stat and
@@ -228,17 +241,16 @@ function parses(root, path) {
228
241
  }
229
242
  }
230
243
  /**
231
- * `launcher-unverified` covers two different facts, told apart here by verifying once more: a payload that fails
232
- * verification, and one that verifies as another release than the state recorded. Only a stale row pays for it.
244
+ * `launcher-unverified` covers two different facts: a payload that fails verification, and one that verifies as another
245
+ * release than the state recorded. `verify` is the report's one shared verification (`hostVerifier`, a memo), so it
246
+ * answers exactly what observation saw without scanning the payload again (review finding B2-N9): its failure, or the
247
+ * release it verified as, which observation found differs from the recorded one.
233
248
  */
234
- function unverified(cache, recorded) {
249
+ function unverified(cache, recorded, verify) {
235
250
  if (cache === null)
236
251
  return 'the payload fails verification';
237
252
  try {
238
- const found = verifyHostCache(cache).release;
239
- return found === recorded
240
- ? `the payload at ${cache} did not verify when observed`
241
- : `the payload at ${cache} verifies, but as release ${short(found)} rather than the recorded ${short(recorded)}`;
253
+ return `the payload at ${cache} verifies, but as release ${short(verify(cache).release)} rather than the recorded ${short(recorded)}`;
242
254
  }
243
255
  catch (error) {
244
256
  return `the payload at ${cache} fails verification (${codeOf(error, 'unreadable')})`;
@@ -260,7 +272,7 @@ function unreadableStates(observed) {
260
272
  }
261
273
  /**
262
274
  * The repair a stale host needs before `ia host <host> --apply` can succeed, worded as `ia host` words it
263
- * (`stateRepair`, `modifiedRepair`), or '' when the remedy alone converges.
275
+ * (`stateRepair`, `modifiedRepair`, `projectionRepair`), or '' when the remedy alone converges.
264
276
  */
265
277
  function repairOf(root, observed) {
266
278
  const host = observed.host, apply = `ia host ${host} --apply`;
@@ -284,10 +296,14 @@ function repairOf(root, observed) {
284
296
  ...(observed.reasons.includes('mcp-modified') ? ['mcp'] : []),
285
297
  ...(observed.reasons.includes('guard-modified') ? ['hooks'] : []),
286
298
  ];
287
- return modified.length === 0 ? '' : modifiedRepair(host, modified);
299
+ // B11: the remedy retires the guard, so a guard group changed by hand alone is deleted first, as `ia host` names it;
300
+ // an MCP entry changed by hand still needs the removal and a new registration.
301
+ if (modified.length === 0)
302
+ return '';
303
+ return modified.includes('mcp') ? modifiedRepair(host, modified) : projectionRepair(host, SETTINGS, apply);
288
304
  }
289
305
  /** A stale host: each reason as a fact, then the repair that works first, where the remedy alone would refuse. */
290
- function staleDetail(root, observed, pinned) {
306
+ function staleDetail(root, observed, pinned, verify) {
291
307
  const facts = observed.reasons.map((reason) => {
292
308
  switch (reason) {
293
309
  case 'release':
@@ -295,13 +311,13 @@ function staleDetail(root, observed, pinned) {
295
311
  case 'launcher-missing':
296
312
  return `launcher ${observed.launcher} is missing`;
297
313
  case 'launcher-unverified':
298
- return unverified(observed.cache, observed.release);
314
+ return unverified(observed.cache, observed.release, verify);
299
315
  case 'mcp-modified':
300
316
  return `${MCP_PATH[observed.host]} does not hold the ia-workspace entry ia host writes for this registration`;
301
317
  case 'guard-modified':
302
- return `${SETTINGS} does not hold the IA guard group ia host writes for this registration`;
318
+ return `${SETTINGS} does not hold the IA guard group an earlier ia host wrote for this registration`;
303
319
  case 'guard-form':
304
- return `${SETTINGS} holds the IA guard group in a form ia host no longer writes; re-applying rewrites it`;
320
+ return `${SETTINGS} holds the IA guard group in a form ia host no longer writes; re-applying retires it`;
305
321
  case 'node-missing':
306
322
  return 'the Node executable the registration runs no longer exists; the remedy records the running one';
307
323
  case 'guard-release':
@@ -315,74 +331,151 @@ function staleDetail(root, observed, pinned) {
315
331
  const repair = repairOf(root, observed);
316
332
  return `stale (${observed.reasons.join(', ')}): ${facts.join('; ')}.${repair === '' ? '' : ` ${repair}`}`;
317
333
  }
318
- function hostRow(root, observed, pinned, commands) {
334
+ function hostRow(root, observed, pinned, commands, verify) {
319
335
  const host = observed.host;
320
336
  // Written is all doctor can know: it never starts a server, so it never says one answered (spec §7).
321
337
  if (observed.status === 'registered')
322
338
  return installation(`host-${host}`, `Host ${host}`, 'ok', `registered (${observed.elements.join(', ')}); written; not observed answering; cache ${observed.cache}`, null);
323
- const detail = commands.prose(host, staleDetail(root, observed, pinned));
339
+ const detail = commands.prose(host, staleDetail(root, observed, pinned, verify));
324
340
  return installation(`host-${host}`, `Host ${host}`, 'fail', detail, commands.apply(host));
325
341
  }
342
+ /** Generation's own reason beside a kept group's (review finding F3), as a trailing clause, or nothing. */
343
+ const keptBeside = (reason) => {
344
+ const other = reason
345
+ .split('; ')
346
+ .filter((part) => part !== HOOK_KEPT)
347
+ .join('; ');
348
+ return other === '' ? '' : ` (${other})`;
349
+ };
326
350
  /**
327
- * Spec §7: one row per managed file that drifted. `changed` (a hand edit) and `unmanaged` (a file without the marker
328
- * where the projection writes) make apply refuse, so they fail and name the same repair `ia host` does; `missing`
329
- * and `outdated` are what the next apply rewrites; `unowned` is a marked file this workspace's state does not list.
351
+ * Spec §7 and B12: the projection rows for one host that owns a projection, read from the receipt
352
+ * `applyHostProjection` wrote. Each file it lists is compared with the disk: `missing` is what the next apply writes
353
+ * again, `changed` (a hand edit) makes apply refuse, so it fails and names the repair `ia host` does. The receipt's
354
+ * packet digest is compared with a fresh render: another packet is `outdated`, and a render that fails is `unknown`.
355
+ * With none of these, one `ok` row says the projection has no drift (task ia-project-verb). The legacy files it
356
+ * removed and the foreign files it left are listed in one info row and never checked. No receipt — a projection
357
+ * written by a 1.x release, or a receipt deleted — is `unknown`, and the remedy writes one. The ownership state and
358
+ * the files it lists are read as `ia host` reads them first, so a file apply would refuse to read is a fail row here
359
+ * too. Every remedy names `projectionRerun`'s apply, as the install refresh does: `ia host <host> --apply` for a
360
+ * registered host, `ia project <host> --apply` for a projection without a registration. Never throws: a failure to
361
+ * observe is itself a row.
330
362
  */
331
- function driftRow(host, drift, artifacts, commands) {
332
- const id = `projection-${host}:${drift.path}`, title = `Projection ${host}`, apply = commands.apply(host), unlisted = `${drift.path} unowned: marked but not listed in this workspace's projection state`;
333
- switch (drift.drift) {
334
- case 'changed':
335
- return installation(id, title, 'fail', `${drift.path} changed since ia host wrote it; move or delete it, then run the remedy`, apply);
336
- case 'unmanaged':
337
- return installation(id, title, 'fail', `${drift.path} unmanaged: it lacks the ia host marker where the projection writes; move or delete it, then run the remedy`, apply);
338
- case 'missing':
339
- return installation(id, title, 'warn', `${drift.path} missing; the remedy writes it again`, apply);
340
- case 'outdated':
341
- return installation(id, title, 'warn', `${drift.path} outdated: the current records render it differently`, apply);
342
- case 'unowned':
343
- // A marked file the projection would write is adopted by the next apply; any other one ia host never touches.
344
- if (artifacts === null)
345
- return installation(id, title, 'warn', unlisted, null);
346
- return artifacts.some((artifact) => artifact.path === drift.path)
347
- ? installation(id, title, 'warn', `${unlisted}; the remedy adopts it`, apply)
348
- : installation(id, title, 'warn', `${unlisted}; ia host leaves it untouched, so delete it if nothing uses it`, null);
349
- }
350
- }
351
- /** The projection rows for one host that owns a projection. Never throws: a failure to observe is itself a row. */
352
363
  function projectionRows(root, host, commands) {
353
- const title = `Projection ${host}`, checks = [];
354
- let artifacts = null;
364
+ const title = `Projection ${host}`, checks = [], rerun = projectionRerun(root, host), apply = commands.apply(host, rerun);
365
+ // A file the mechanism cannot read: the ownership state, a managed file, or the receipt, located at that file.
366
+ const unreadable = (error, fallback) => {
367
+ const failure = projectionFailure(error, root, host, rerun);
368
+ const path = failure.where?.path ?? fallback, repair = failure.next ?? projectionRepair(host, path, rerun, codeOf(error, ''));
369
+ const detail = commands.prose(host, `${path} cannot be read (${codeOf(error, 'an unexpected error')}). ${repair}`);
370
+ return installation(path === STATE.projection(host) ? `projection-${host}` : `projection-${host}:${path}`, title, 'fail', detail, apply);
371
+ };
372
+ let observedDrift, hookDrift;
355
373
  try {
356
- artifacts = renderProjectionFor(root, host);
374
+ planRetirement(root, host);
375
+ observedDrift = observeProjection({ root, host, artifacts: null, marker: PACKET_MARKER });
376
+ // The hook groups the workspace owns (milestone generation-binding, C9): read-only, as the planner reads them.
377
+ hookDrift = host === 'claude' ? observeHookRegistration(root) : [];
357
378
  }
358
379
  catch (error) {
359
- // Without a rendering, hand edits and missing files are still observed; only `outdated` cannot be.
360
- const why = codeOf(error, 'the projection could not be rendered');
361
- const detail = `Not compared with the current records; ${why}`;
362
- checks.push(installation(`projection-${host}-render`, title, 'unknown', detail, 'ia validate'));
380
+ return [unreadable(error, STATE.projection(host))];
363
381
  }
382
+ let receipt;
364
383
  try {
365
- for (const drift of observeProjection({ root, host, artifacts, marker: WORKSPACE_PROJECTION_MARKER }))
366
- checks.push(driftRow(host, drift, artifacts, commands));
384
+ receipt = readReceipt(root, host);
367
385
  }
368
386
  catch (error) {
369
- // The mechanism locates the failure at the file it could not read: the ownership state, or a managed file.
370
- const state = STATE.projection(host), path = refusedPath(error) ?? state, repair = projectionRepair(host, path, `ia host ${host} --apply`);
371
- const detail = commands.prose(host, `${path} cannot be read (${codeOf(error, 'an unexpected error')}). ${repair}`);
372
- checks.push(installation(path === state ? `projection-${host}` : `projection-${host}:${path}`, title, 'fail', detail, commands.apply(host)));
387
+ return [unreadable(error, STATE.receipt(host))];
373
388
  }
389
+ if (receipt === null) {
390
+ const changed = observedDrift.filter((row) => row.drift === 'changed');
391
+ return [
392
+ ...changed.map(({ path }) => installation(`projection-${host}:${path}`, title, 'fail', `${path} changed since the projection apply wrote it; move or delete it, then run the remedy`, apply)),
393
+ installation(`projection-${host}`, title, 'unknown', `No receipt at ${STATE.receipt(host)}: this projection was written before receipts, or its receipt was deleted${changed.length ? '; repair the changed files before writing a receipt' : '; the remedy writes one'}`, apply),
394
+ ];
395
+ }
396
+ for (const file of receipt.files) {
397
+ const id = `projection-${host}:${file.path}`;
398
+ let digest;
399
+ try {
400
+ digest = existsSync(resolve(root, file.path)) ? sha256(readWorkspaceFile({ root, path: file.path })) : null;
401
+ }
402
+ catch (error) {
403
+ checks.push(unreadable(error, file.path));
404
+ continue;
405
+ }
406
+ if (digest === null)
407
+ checks.push(installation(id, title, 'warn', `${file.path} missing; the remedy writes it again`, apply));
408
+ else if (digest !== file.sha256)
409
+ checks.push(installation(id, title, 'fail', `${file.path} changed since the projection apply wrote it; move or delete it, then run the remedy`, apply));
410
+ }
411
+ // A group deleted, changed or duplicated by hand is one apply refuses to put back on its own (guard review finding
412
+ // G-N2): the remedy removes the registration, and the next apply registers the workspace's hooks again.
413
+ const reregister = commands.apply(host, `ia host ${host} --remove --apply`), again = `"ia host ${host} --apply" then registers the workspace's hooks again`;
414
+ for (const { hook, drift } of hookDrift)
415
+ checks.push(drift === 'foreign'
416
+ ? installation(`projection-${host}-hook:${hook}`, title, 'warn', `${SETTINGS} holds a guard hook group for ${hook}, which this workspace's registration does not own; it is left in place and may still enforce protection. Explicit host removal refuses until you delete only this unowned group manually, preserving every other group and setting.`, null)
417
+ : installation(`projection-${host}-hook:${hook}`, title, 'fail', commands.prose(host, drift === 'missing'
418
+ ? `the hook group for ${hook} was deleted from ${SETTINGS}, which apply does not put back on its own; the remedy removes the registration, and ${again}`
419
+ : `the hook group for ${hook} in ${SETTINGS} changed since it was registered, or appears twice; delete only that group, then run the remedy, which removes the registration, and ${again}`), reregister));
420
+ // An authored @hook the last apply could not register guards nothing (review finding H-N4): `ia host` registers it, or,
421
+ // where disableAllHooks turned hooks off, nothing does until that setting changes.
422
+ // A kept group is the other way round (review finding N2): an obsolete group that still guards, until hooks are back on
423
+ // or the payload it was registered against is materialized again; no command is sure to remove it.
424
+ for (const row of receipt.unsupported ?? [])
425
+ if (row.word === 'hook')
426
+ checks.push(row.reason.includes(HOOK_KEPT)
427
+ ? installation(`projection-${host}-hook:${row.identity}`, title, 'warn', commands.prose(host, `the hook group for ${row.identity} stays in ${SETTINGS} though no registrable hook claims it any more: the next "ia host ${host} --apply" removes it once hooks are back on, or while they are off once it materializes the payload the group was registered against${keptBeside(row.reason)}`), null)
428
+ : installation(`projection-${host}-hook:${row.identity}`, title, 'warn', commands.prose(host, `the authored @hook ${row.identity} guards nothing: ${row.reason}`), row.reason.includes('disableAllHooks') ? null : commands.apply(host, `ia host ${host} --apply`)));
429
+ try {
430
+ const rendered = renderProjectionFor(root, host), current = rendered.receipt.packetDigest;
431
+ if (current !== receipt.packetDigest)
432
+ checks.push(installation(`projection-${host}-packet`, title, 'warn', `outdated: the current records render packet ${short(current)}; the receipt names ${short(receipt.packetDigest)}`, apply));
433
+ // The generated files the records render now against the ones the receipt lists; a receipt from before authored
434
+ // generation lists none, so it is outdated where the records generate any, never an error.
435
+ const rows = (list) => JSON.stringify((list ?? []).map(({ identity, path, sha256 }) => [identity, path, sha256]));
436
+ if (rows(rendered.receipt.generated) !== rows(receipt.generated))
437
+ checks.push(installation(`projection-${host}-generated`, title, 'warn', receipt.generated === undefined
438
+ ? `outdated: the receipt predates authored generation, and the records render ${rendered.receipt.generated?.length ?? 0} generated files`
439
+ : `outdated: the records render other generated files (${rendered.receipt.generated?.length ?? 0}) than the ${receipt.generated.length} the receipt lists`, apply));
440
+ }
441
+ catch (error) {
442
+ // Without a rendering, hand edits and missing files are still observed; only `outdated` cannot be.
443
+ const why = codeOf(error, 'the projection could not be rendered');
444
+ checks.push(installation(`projection-${host}-render`, title, 'unknown', `Not compared with the current records; ${why}`, 'ia validate'));
445
+ }
446
+ if (checks.length === 0)
447
+ checks.push(installation(`projection-${host}`, title, 'ok', `No drift: the ${receipt.files.length} files ${STATE.receipt(host)} lists are as written, and the records render the packet it names (${short(receipt.packetDigest)})`, null));
448
+ const left = [
449
+ ...(receipt.removed.length === 0 ? [] : [`removed ${receipt.removed.map((file) => file.path).join(', ')}`]),
450
+ ...(receipt.foreign.length === 0 ? [] : [`foreign, left in place: ${receipt.foreign.join(', ')}`]),
451
+ ];
452
+ if (left.length > 0)
453
+ checks.push(installation(`projection-${host}-receipt`, title, 'info', `The last apply ${left.join('; ')}; listed, not checked`, null));
374
454
  return checks;
375
455
  }
376
- /** Spec §7's rows for a workspace whose installed state could be read. */
377
- function hostRows(root, observed, pinned, commands) {
456
+ /**
457
+ * Spec §7's rows for a workspace whose installed state could be read. A host `ia project` projected without a
458
+ * registration owns a projection state (`projectedHosts`) but no registration, which `observeHosts` does not report,
459
+ * so its projection rows follow the registered hosts' rows, or the `Host` row when none is registered.
460
+ */
461
+ function hostRows(root, observed, pinned, commands, verify) {
462
+ const projected = projectedHosts(root)
463
+ .filter((host) => !observed.some((row) => row.host === host))
464
+ .flatMap((host) => projectionRows(root, host, commands));
378
465
  if (observed.length === 0) {
379
466
  const none = 'No host registered; run "ia host claude" or "ia host codex" to plan one';
380
- return [installation('host', 'Host', 'info', commands.prose('codex', commands.prose('claude', none)), null)];
467
+ return [
468
+ installation('host', 'Host', 'info', commands.prose('codex', commands.prose('claude', none)), null),
469
+ ...projected,
470
+ ];
381
471
  }
382
- return observed.flatMap((host) => [
383
- hostRow(root, host, pinned, commands),
384
- ...(host.elements.includes('projection') ? projectionRows(root, host.host, commands) : []),
385
- ]);
472
+ return [
473
+ ...observed.flatMap((host) => [
474
+ hostRow(root, host, pinned, commands, verify),
475
+ ...(host.elements.includes('projection') ? projectionRows(root, host.host, commands) : []),
476
+ ]),
477
+ ...projected,
478
+ ];
386
479
  }
387
480
  /**
388
481
  * Host plugin distribution spec §3 and §7.3 `ia-home` warn: a registration made before the IA home moved still pins
@@ -405,6 +498,140 @@ function movedRows(request, observed, commands) {
405
498
  installation(`ia-home-moved-${host.host}`, 'IA home moved', 'warn', `Host ${host.host} pins its payload under ${host.cache}, outside the IA home ${home}${inside(legacy, host.cache) ? ' (the M5.3 per-OS location)' : ''}`, commands.apply(host.host)),
406
499
  ]);
407
500
  }
501
+ /**
502
+ * Reads each payload's catalog once per report: the catalog row and a join row usually name the same payload, and the
503
+ * payload is verified through `verify`, the one verification the host rows share (review finding B-N7).
504
+ */
505
+ function catalogReader(verify) {
506
+ const seen = new Map();
507
+ return (directory, release) => {
508
+ const key = `${release}\u0000${directory}`;
509
+ let read = seen.get(key);
510
+ if (read === undefined) {
511
+ try {
512
+ read = { ok: true, value: readInstalledImplementations(directory, release, verify) };
513
+ }
514
+ catch (error) {
515
+ read = { ok: false, error };
516
+ }
517
+ seen.set(key, read);
518
+ }
519
+ return read;
520
+ };
521
+ }
522
+ const refusalText = (error) => `${codeOf(error, 'IA-CLI-FAILED')}: ${error instanceof Error ? error.message : String(error)}`;
523
+ /** A present catalog's operations in words: each with its handler and shipped bytes, or why it is unavailable or revoked. */
524
+ function operationFacts(catalog) {
525
+ if (catalog.operations.length === 0)
526
+ return 'no installed operations';
527
+ return catalog.operations
528
+ .map((operation) => operation.status === 'available'
529
+ ? `${operation.id} available (handler ${operation.handler}, shipped bytes ${short(operation.digest)})`
530
+ : `${operation.id} ${operation.status} (${operation.reason})`)
531
+ .join('; ');
532
+ }
533
+ /**
534
+ * C16 and C24: the installed-implementation catalog of the payload this installation pins, as the IA home holds it.
535
+ * Present is `ok`, or `warn` when it lists an operation unavailable or revoked; a payload that carries no catalog (one built
536
+ * before the catalog existed) is an `info` note, and so is one not materialized yet. A payload that fails host
537
+ * verification (a file its inventory does not list, a missing or changed one, a link), or a catalog whose pins disagree
538
+ * with it, is `fail`, as its host row is: the payload is damaged, and its repair deletes the payload directory so the
539
+ * remedy materializes it again. Never throws, and only reads: no handler is imported or run.
540
+ */
541
+ function catalogRow(request, pinned, read, observed, commands) {
542
+ const id = 'implementations', title = 'Implementations';
543
+ if (pinned.release === null)
544
+ return installation(id, title, 'info', 'Not checked; this installation carries no host payload', null);
545
+ let home;
546
+ try {
547
+ home = resolveIaHome(request.env, request.home ?? homedir()).home;
548
+ }
549
+ catch (error) {
550
+ return installation(id, title, 'unknown', `Not checked; ${codeOf(error, 'the IA home could not be resolved')}`, null);
551
+ }
552
+ const payload = hostPayloadPath(home, pinned.release);
553
+ if (!directory(payload))
554
+ return installation(id, title, 'info', `Release ${short(pinned.release)} is not materialized; ia host materializes it, with its installed-implementation catalog, on apply`, null);
555
+ const result = read(payload, pinned.release);
556
+ if (!result.ok) {
557
+ const host = observed[0]?.host ?? 'claude';
558
+ return installation(id, title, 'fail', commands.prose(host, `${INSTALLED_IMPLEMENTATIONS} in ${payload} fails verification (${refusalText(result.error)}). Delete ${payload}, then run "ia host ${host} --apply" to materialize it again.`), commands.apply(host));
559
+ }
560
+ const catalog = result.value;
561
+ if (catalog.status === 'unavailable')
562
+ return installation(id, title, 'info', `Unavailable in release ${short(pinned.release)}: ${catalog.reason}`, null);
563
+ const degraded = catalog.operations.some((operation) => operation.status !== 'available');
564
+ return installation(id, title, degraded ? 'warn' : 'ok', `Catalog ${short(catalog.digest)} in release ${short(catalog.release)} (${catalog.version}): ${operationFacts(catalog)}; ` +
565
+ `${catalog.evaluators.entries.length} installed evaluators beside the built-ins; listed, nothing run`, null);
566
+ }
567
+ /**
568
+ * The trust `ia validate` binds a join through (review finding B2-RC1): the payload this installation pins, in the IA home
569
+ * the request resolves; null when it pins none or the home cannot be resolved.
570
+ */
571
+ function doctorTrust(request, pinned) {
572
+ if (pinned.release === null)
573
+ return null;
574
+ try {
575
+ return { home: resolveIaHome(request.env, request.home ?? homedir()).home, release: pinned.release };
576
+ }
577
+ catch {
578
+ return null;
579
+ }
580
+ }
581
+ /**
582
+ * Design item 9: one row per consumer join `.ia/distributions/hosts/joins.json` records, compared with the catalog of the
583
+ * payload this installation pins, as `ia validate` binds through it (review finding B2-RC1): a registration of another
584
+ * release or naming another directory, or another spelling of it, is `warn` with the apply that registers this
585
+ * installation's payload, and nothing it names is opened. `ok` (present) when the join names that catalog, digest and release;
586
+ * `warn` (drifted) when it names another, when that payload carries none, or when the consumer is not registered, each
587
+ * naming the apply that records or drops the join; `unknown` when the registration or its catalog cannot be read, which
588
+ * the host row reports. A registered host with no join is an `info` row (unavailable) naming the apply that records
589
+ * one. Receipts that cannot be read are `fail`, repaired by deleting them. Never throws, and only reads.
590
+ */
591
+ function joinRows(root, observed, read, commands, trust) {
592
+ const trusted = trust === null ? null : trustedPayload(trust);
593
+ let joins;
594
+ try {
595
+ joins = readJoins(root) ?? [];
596
+ }
597
+ catch (error) {
598
+ const host = observed[0]?.host ?? 'claude';
599
+ return [
600
+ installation('joins', 'Joins', 'fail', commands.prose(host, `${JOINS} cannot be read (${refusalText(error)}). Delete ${JOINS}, then run "ia host ${host} --apply".`), commands.apply(host)),
601
+ ];
602
+ }
603
+ const rows = joins.map((join) => {
604
+ const id = `join-${join.consumer}`, title = `Join ${join.consumer}`, joined = `${join.implementation} ${join.version} (catalog ${short(join.digest)}, release ${short(join.release)}) at consumer revision ${short(join.consumerRevision)}`;
605
+ const host = observed.find((row) => row.host === join.consumer);
606
+ if (host === undefined) {
607
+ const remove = `ia host ${join.consumer} --remove --apply`;
608
+ return installation(id, title, 'warn', commands.prose(join.consumer, `drifted: joined ${joined}, but host ${join.consumer} is not registered; "${remove}" drops the join`), commands.apply(join.consumer, remove));
609
+ }
610
+ if (host.cache === null || host.release === null)
611
+ return installation(id, title, 'unknown', `Not compared; joined ${joined}; the registration cannot be read`, null);
612
+ if (trusted === null)
613
+ return installation(id, title, 'unknown', `Not compared; joined ${joined}; this installation pins no host payload, so it trusts no registration`, null);
614
+ const untrusted = registrationUntrusted(trusted, host.host, { cache: host.cache, release: host.release }, null);
615
+ if (untrusted !== null)
616
+ return installation(id, title, 'warn', `drifted: joined ${joined}; ${untrusted}`, commands.apply(join.consumer));
617
+ const result = read(trusted.payload, trusted.release);
618
+ if (!result.ok)
619
+ return installation(id, title, 'unknown', `Not compared; joined ${joined}; the registered payload's catalog cannot be verified (${codeOf(result.error, 'unreadable')})`, null);
620
+ const current = result.value;
621
+ const drift = current.status === 'unavailable'
622
+ ? `the registered payload carries none: ${current.reason}`
623
+ : current.digest !== join.digest || current.release !== join.release
624
+ ? `the registered payload carries catalog ${short(current.digest)} in release ${short(current.release)}`
625
+ : null;
626
+ return drift === null
627
+ ? installation(id, title, 'ok', `present: joined ${joined}, the catalog the registered payload carries`, null)
628
+ : installation(id, title, 'warn', `drifted: joined ${joined}; ${drift}`, commands.apply(join.consumer));
629
+ });
630
+ for (const host of observed)
631
+ if (!joins.some((join) => join.consumer === host.host))
632
+ rows.push(installation(`join-${host.host}`, `Join ${host.host}`, 'info', `unavailable: no join recorded for host ${host.host}; the remedy records one when its payload carries a catalog`, commands.apply(host.host)));
633
+ return rows;
634
+ }
408
635
  // ---- Registry rows: registry spec §4 ---------------------------------------------------------------------------
409
636
  /**
410
637
  * One row per provider the lock names, in provider order. One chooser serves the report, as for any command that
@@ -457,6 +684,7 @@ function portableLock(root) {
457
684
  return undefined;
458
685
  }
459
686
  }
687
+ import { sourceBindingRows } from './doctor-mounts.js';
460
688
  export function collectDoctor(request) {
461
689
  const checks = [...environment(request)];
462
690
  const supplied = request.root === undefined
@@ -480,8 +708,12 @@ export function collectDoctor(request) {
480
708
  : `${supplied} is not an existing directory`,
481
709
  remedy: usable ? null : 'ia init',
482
710
  });
711
+ if (usable)
712
+ checks.push(...sourceBindingRows(root));
483
713
  const pending = usable && existsSync(resolve(root, INSTALL_PATHS.pending));
484
714
  const pinned = pinnedRelease(request.packageRoot);
715
+ // One verification per payload directory for the whole report: host, catalog and join rows share it (B-N7).
716
+ const verify = hostVerifier();
485
717
  // The observed hosts, or the code that kept the installed state from being read; undefined until it is read.
486
718
  let observed;
487
719
  const unchecked = (id, section, title, why) => ({
@@ -521,6 +753,10 @@ export function collectDoctor(request) {
521
753
  });
522
754
  }
523
755
  }
756
+ if (usable && !pending)
757
+ checks.push(sourceProtectionCheck(root));
758
+ else
759
+ checks.push(unchecked('source-protection', 'Workspace', 'Source protection', pending ? 'installation recovery is required first' : 'no workspace'));
524
760
  if (!usable) {
525
761
  for (const [id, title] of [
526
762
  ['generation', 'Generation'],
@@ -536,7 +772,7 @@ export function collectDoctor(request) {
536
772
  else {
537
773
  try {
538
774
  // Spec §7: hosts are observed against this installation's pin; without one, the release comparison is skipped.
539
- const installed = readInstalledState({ root, hosts: true, hostRelease: pinned.release });
775
+ const installed = readInstalledState({ root, hosts: true, hostRelease: pinned.release, verify });
540
776
  observed = installed.hosts ?? [];
541
777
  checks.push({
542
778
  id: 'generation',
@@ -557,7 +793,7 @@ export function collectDoctor(request) {
557
793
  title: 'Generation',
558
794
  status: 'unknown',
559
795
  detail: `Not checked; ${observed}`,
560
- remedy: `ia-distribution recover --root ${root}`,
796
+ remedy: recoverCommand('recover', root),
561
797
  });
562
798
  }
563
799
  // Registry spec §4: after the generation row, the registry each provider in the workspace's lock routes to. An
@@ -572,7 +808,7 @@ export function collectDoctor(request) {
572
808
  title: 'Pending state',
573
809
  status: pending ? 'fail' : 'ok',
574
810
  detail: pending ? `${INSTALL_PATHS.pending} exists; an apply was interrupted` : 'No interrupted transaction',
575
- remedy: pending ? `ia-distribution recover --root ${root}` : null,
811
+ remedy: pending ? recoverCommand('recover', root) : null,
576
812
  });
577
813
  const held = existsSync(resolve(root, INSTALL_LOCK));
578
814
  checks.push({
@@ -581,7 +817,7 @@ export function collectDoctor(request) {
581
817
  title: 'Install lock',
582
818
  status: held ? 'warn' : 'info',
583
819
  detail: held ? `${INSTALL_LOCK} is held by another installer or was left behind` : 'Not held',
584
- remedy: held ? `ia-distribution recover --root ${root}` : null,
820
+ remedy: held ? recoverCommand('recover', root) : null,
585
821
  });
586
822
  const cache = resolve(root, CACHE);
587
823
  const archives = directory(cache) ? readdirSync(cache).filter((name) => ARCHIVE.test(name)).length : 0;
@@ -601,8 +837,10 @@ export function collectDoctor(request) {
601
837
  checks.push(unchecked('host', 'Installation', 'Host', 'installation recovery is required first'));
602
838
  else if (observed === undefined || typeof observed === 'string')
603
839
  checks.push(unchecked('host', 'Installation', 'Host', observed ?? 'the installed state was not read'));
604
- else
605
- checks.push(payloadRow(request, pinned), ...hostTransactionRows(root), ...hostRows(root, observed, pinned, commandsFor(supplied)), ...movedRows(request, observed, commandsFor(supplied)));
840
+ else {
841
+ const read = catalogReader(verify);
842
+ checks.push(payloadRow(request, pinned), catalogRow(request, pinned, read, observed, commandsFor(supplied)), ...hostTransactionRows(root), ...hostRows(root, observed, pinned, commandsFor(supplied), verify), ...joinRows(root, observed, read, commandsFor(supplied), doctorTrust(request, pinned)), ...movedRows(request, observed, commandsFor(supplied)));
843
+ }
606
844
  // Host plugin distribution spec §7.3 and §8.2: rows that exist with or without a workspace, and the briefing. One
607
845
  // report has one root. Without --root it was discovered upward from the cwd, which is how the §8.1 hook runs doctor.
608
846
  // A supplied --root is literal, as for every other verb: it is a workspace only when it holds .ia/src itself. When it
@@ -631,16 +869,26 @@ export function collectDoctor(request) {
631
869
  channel: request.channel,
632
870
  });
633
871
  checks.push(...user.checks);
872
+ for (let index = 0; index < checks.length; index += 1) {
873
+ const check = checks[index];
874
+ checks[index] = {
875
+ ...check,
876
+ detail: safeRootAdvice(check.detail, [root, supplied, request.root], request),
877
+ remedy: check.remedy === null ? null : safeRootAdvice(check.remedy, [root, supplied, request.root], request),
878
+ };
879
+ }
634
880
  const briefing = request.host === undefined
635
881
  ? undefined
636
- : briefingFor(request.host, checks, user, { root: workspaceRoot, supplied, enclosing: enclosing ?? null }, version);
882
+ : briefingFor(request.host, checks, user, { root: workspaceRoot, supplied, enclosing: enclosing ?? null, advice: request }, version);
637
883
  return { checks, counts: count(checks), ...(briefing === undefined ? {} : { briefing }) };
638
884
  }
639
885
  /**
640
886
  * §8.2's host state from the rows already collected. `unknown` when the host set was not observed — an interrupted
641
887
  * installation, or installed state that could not be read — so the briefing never calls a host missing that doctor did
642
888
  * not look at. Stale covers the host row itself, a payload pinned outside the IA home (§3 names re-applying as its
643
- * remedy) and any failing projection row, which `ia host <host> --apply` also repairs.
889
+ * remedy) and any failing projection row of a registered host, which `ia host <host> --apply` also repairs. A
890
+ * projection `ia project` wrote without a registration is no registration to call stale: the host stays `absent`, and
891
+ * its failing rows name their own repair, `ia project <host> --apply` (task ia-project-verb).
644
892
  */
645
893
  function hostState(host, checks) {
646
894
  const pending = checks.find((check) => check.id === 'pending');
@@ -654,7 +902,7 @@ function hostState(host, checks) {
654
902
  const hostCheck = checks.find((check) => check.id === `host-${host}`);
655
903
  const failing = checks.filter((check) => (check.id === `host-${host}` && check.status !== 'ok') ||
656
904
  check.id === `ia-home-moved-${host}` ||
657
- (check.id.startsWith(`projection-${host}`) && check.status === 'fail'));
905
+ (hostCheck !== undefined && check.id.startsWith(`projection-${host}`) && check.status === 'fail'));
658
906
  if (failing.length > 0)
659
907
  return { status: 'stale', detail: failing.map((check) => check.detail).join('; '), recovery: null };
660
908
  return { status: hostCheck === undefined ? 'absent' : 'registered', detail: null, recovery: null };