@inventarch/cli 3.1.0 → 3.1.1

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 (93) hide show
  1. package/README.md +221 -23
  2. package/SPEC.md +20 -20
  3. package/assets/base/df626d1dc4949649ba7203842b29b4f064e0552e8db8c2c41ff74b6462b81b75.ia.tgz +0 -0
  4. package/assets/base.json +3 -3
  5. package/assets/host/f91ffe4c2071b196e925e93507bd661b3e09f5dc75392f7d6453fdbec5e28d62.tgz +0 -0
  6. package/assets/host.json +3 -3
  7. package/assets/vocabulary.json +1 -1
  8. package/dist/author.d.ts.map +1 -1
  9. package/dist/author.js +6 -7
  10. package/dist/author.js.map +1 -1
  11. package/dist/briefing.d.ts +2 -2
  12. package/dist/briefing.d.ts.map +1 -1
  13. package/dist/capture.d.ts +2 -2
  14. package/dist/capture.js +7 -7
  15. package/dist/commands.d.ts +7 -7
  16. package/dist/commands.d.ts.map +1 -1
  17. package/dist/commands.js +26 -28
  18. package/dist/commands.js.map +1 -1
  19. package/dist/consumer.d.ts +24 -24
  20. package/dist/consumer.js +33 -33
  21. package/dist/consumer.js.map +1 -1
  22. package/dist/decline.js +1 -1
  23. package/dist/distribute.d.ts +13 -14
  24. package/dist/distribute.d.ts.map +1 -1
  25. package/dist/distribute.js +17 -17
  26. package/dist/distribute.js.map +1 -1
  27. package/dist/doctor-user.d.ts +1 -1
  28. package/dist/doctor-user.d.ts.map +1 -1
  29. package/dist/doctor-user.js +2 -2
  30. package/dist/doctor-user.js.map +1 -1
  31. package/dist/doctor.d.ts +1 -1
  32. package/dist/doctor.d.ts.map +1 -1
  33. package/dist/doctor.js +53 -54
  34. package/dist/doctor.js.map +1 -1
  35. package/dist/format.js +3 -3
  36. package/dist/format.js.map +1 -1
  37. package/dist/home-remedy.d.ts +1 -1
  38. package/dist/home-remedy.js +1 -1
  39. package/dist/host-projection.d.ts +38 -38
  40. package/dist/host-projection.d.ts.map +1 -1
  41. package/dist/host-projection.js +69 -70
  42. package/dist/host-projection.js.map +1 -1
  43. package/dist/host.d.ts +37 -38
  44. package/dist/host.d.ts.map +1 -1
  45. package/dist/host.js +54 -57
  46. package/dist/host.js.map +1 -1
  47. package/dist/init.d.ts +60 -56
  48. package/dist/init.d.ts.map +1 -1
  49. package/dist/init.js +98 -99
  50. package/dist/init.js.map +1 -1
  51. package/dist/main.js +4 -4
  52. package/dist/main.js.map +1 -1
  53. package/dist/next.js +15 -15
  54. package/dist/next.js.map +1 -1
  55. package/dist/operation-help.d.ts +3 -3
  56. package/dist/operation-help.d.ts.map +1 -1
  57. package/dist/operation-help.js +9 -9
  58. package/dist/operation-help.js.map +1 -1
  59. package/dist/pack.js +6 -6
  60. package/dist/position.d.ts.map +1 -1
  61. package/dist/position.js +10 -11
  62. package/dist/position.js.map +1 -1
  63. package/dist/preview.d.ts +4 -4
  64. package/dist/preview.d.ts.map +1 -1
  65. package/dist/preview.js +27 -28
  66. package/dist/preview.js.map +1 -1
  67. package/dist/profile.d.ts +23 -23
  68. package/dist/profile.d.ts.map +1 -1
  69. package/dist/profile.js +50 -51
  70. package/dist/profile.js.map +1 -1
  71. package/dist/project.d.ts +7 -8
  72. package/dist/project.d.ts.map +1 -1
  73. package/dist/project.js +24 -27
  74. package/dist/project.js.map +1 -1
  75. package/dist/read.d.ts +1 -1
  76. package/dist/read.d.ts.map +1 -1
  77. package/dist/read.js +4 -4
  78. package/dist/read.js.map +1 -1
  79. package/dist/render.d.ts +3 -3
  80. package/dist/render.js +3 -3
  81. package/dist/session.d.ts +9 -9
  82. package/dist/session.d.ts.map +1 -1
  83. package/dist/session.js +10 -10
  84. package/dist/session.js.map +1 -1
  85. package/dist/validate.d.ts +8 -8
  86. package/dist/validate.d.ts.map +1 -1
  87. package/dist/validate.js +34 -37
  88. package/dist/validate.js.map +1 -1
  89. package/dist/vocabulary.js +2 -2
  90. package/dist/vocabulary.js.map +1 -1
  91. package/package.json +6 -6
  92. package/assets/base/7db20e0dbbc2b88701ea24991886b4a8e08d419dda469cce5caff66911f81e4c.ia.tgz +0 -0
  93. package/assets/host/7e80bd7098018c1c13e3fae4cd363acfeffedccd5b6ec06c4952b62f449a4246.tgz +0 -0
package/dist/init.js CHANGED
@@ -7,50 +7,48 @@ import { canonical } from './plugin-sources.js';
7
7
  export { readBase, PIN_PATH, baseArchivePath, PACKAGE_ID } from './bundled-base.js';
8
8
  /**
9
9
  * `ia init`: docs/specs/consumer-cli-contract/README.md §2.1, implementing
10
- * docs/specs/workspace-initialization-apply/README.md (M5.2) to reach the end state
11
- * docs/specs/workspace-initialization/README.md (M5.1) fixes.
10
+ * docs/specs/workspace-initialization-apply/README.md (the apply spec) to reach the end state
11
+ * docs/specs/workspace-initialization/README.md (the initialization spec) fixes.
12
12
  *
13
- * Without `--apply` it prints the reviewable plan: the owned paths, the target's classification (M5.2 §4.1), the
14
- * conflicts detected now, the starter it would write, the bundled base pin and the steps. It exits 0 whether or not
13
+ * Without `--apply` it prints the reviewable plan: the owned paths, the target's classification (the apply spec §1),
14
+ * the conflicts detected now, the starter it would write, the bundled base pin and the steps. It exits 0 whether or not
15
15
  * conflicts were found, because reporting them is the command's job.
16
16
  *
17
- * Milestone position-packet task init-three-records (position-and-projection §3; plan amendments B7 and B13;
18
- * decisions local-system-at-init and identity-namespace): the starter is three authored records in
19
- * `.ia/src/workspace.ia` — the `@workspace`, its participant `@agent` and that participant's `@mandate` — and a
20
- * create-only `.ia/.gitignore`. No local `@system` and no `@distribution` are written unless `--system` asks for
21
- * them, inside `.ia/src/systems/<name>/`, where the packer finds a release's records; without them the release
22
- * descriptor names no distribution, so `ia pack` refuses until one is authored.
17
+ * SPEC `init`: the starter is three authored records in `.ia/src/workspace.ia` — the `@workspace`, its participant
18
+ * `@agent` and that participant's `@mandate` — and a create-only `.ia/.gitignore`. No local `@system` and no
19
+ * `@distribution` are written unless `--system` asks for them, inside `.ia/src/systems/<name>/`, where the packer
20
+ * finds a release's records; without them the release descriptor names no distribution, so `ia pack` refuses until
21
+ * one is authored.
23
22
  *
24
- * With `--apply` it runs the steps in order — verify the pin, install the bundled base unless it is already
25
- * installed as planned, author the starter create-only, admit and read the authored identities from the compiled
26
- * graph, write `.ia/release.json`, the completion point — through the shared install services and `createFile`.
27
- * No journal is written: a rerun derives from the workspace which steps are done (§4.2). No step performs a network
28
- * request. `<directory>` is the only way to name the target: this verb never performs root discovery, and `--root`
29
- * is refused by the grammar rather than silently ignored. Two effects follow the completion point and are reported
30
- * apart (design §3): the capture, through db's `writeCapture` as `ia capture` writes it, and, only with `--host`, the
31
- * projection. A later step that fails leaves every earlier result in place and says so, naming its own command.
23
+ * With `--apply` it runs the steps in order — verify the pin, install the bundled base unless it is already installed
24
+ * as planned, author the starter create-only, admit and read the authored identities from the compiled graph, write
25
+ * `.ia/release.json`, the completion point — through the shared install services and `createFile`. No journal is
26
+ * written: a rerun derives from the workspace which steps are done (the apply spec §5). No step performs a network
27
+ * request. `<directory>` is the only way to name the target: this verb never performs root discovery, and `--root` is
28
+ * refused by the grammar rather than silently ignored. Two effects follow the completion point and are reported apart:
29
+ * the capture, through db's `writeCapture` as `ia capture` writes it, and, only with `--host`, the projection. A later
30
+ * step that fails leaves every earlier result in place and says so, naming its own command.
32
31
  *
33
32
  * `--host claude` or `--host codex` (docs/specs/host-registration/README.md §4 "init --host") is the project effect:
34
33
  * once the workspace is initialized, after the capture, the `ia host <host> --apply` path runs under the question
35
- * already answered here, so it never asks a second one, and its projection is written by `applyHostProjection`, the
36
- * one writer of projection files. It reads the live revision rather than the capture (plan amendment B8), so a capture
37
- * that fails does not keep it from running; the capture's refusal then says the projection is written. The plan names
38
- * that step and writes nothing for it — the host plan needs `.ia/release.json`, which only the apply writes. A host
39
- * step that refuses leaves the workspace initialized: the refusal keeps the service's code, message and location, and
40
- * its next action names the rerun.
34
+ * already answered here, so it never asks a second one, and its projection is written by `applyHostProjection`, the one
35
+ * writer of projection files. It reads the live revision rather than the capture, so a capture that fails does not keep
36
+ * it from running; the capture's refusal then says the projection is written. The plan names that step and writes
37
+ * nothing for it — the host plan needs `.ia/release.json`, which only the apply writes. A host step that refuses leaves
38
+ * the workspace initialized: the refusal keeps the service's code, message and location, and its next action names the
39
+ * rerun.
41
40
  *
42
- * `--migrate` (milestone position-packet task init-migrate-flag; plan amendments B7, B9 and B11) takes a workspace a
43
- * 1.1.0 `ia init` wrote instead: one local system folder, `.ia/src/systems/<name>/`, whose `system.ia` holds exactly the
44
- * starter `@system <name>`, registering no word, and `@agent <name>-steward`, and whose `records/workspace.ia` holds
45
- * exactly `@workspace <name>` and `@distribution <name>-distribution`. It rewrites it into the three starter records:
46
- * each other record file moves from the folder's `records/` to `.ia/src/`, where a record's word, not its folder,
47
- * decides its system, so its identity is unchanged; the local system folder goes and the descriptor names no
48
- * distribution, unless `--system` keeps the `@system` and its steward and re-roots the `@distribution` at the system.
49
- * It plans by default, and plan and apply alike refuse a workspace of any other shape before anything is written. The
50
- * three records use fields only the base this CLI bundles declares, so the apply first installs that base where the
51
- * workspace has another, as `ia init` installs it; it then captures and re-projects each host whose projection the
52
- * workspace owns through `applyHostProjection`, which retires the 1.x steward guard and deletes the owned steward agent
53
- * files (`collectMigration`, `applyMigration`).
41
+ * `--migrate` takes a workspace a 1.1.0 `ia init` wrote instead: one local system folder, `.ia/src/systems/<name>/`,
42
+ * whose `system.ia` holds exactly the starter `@system <name>`, registering no word, and `@agent <name>-steward`, and
43
+ * whose `records/workspace.ia` holds exactly `@workspace <name>` and `@distribution <name>-distribution`. It rewrites
44
+ * it into the three starter records: each other record file moves from the folder's `records/` to `.ia/src/`, where a
45
+ * record's word, not its folder, decides its system, so its identity is unchanged; the local system folder goes and the
46
+ * descriptor names no distribution, unless `--system` keeps the `@system` and its steward and re-roots the
47
+ * `@distribution` at the system. It plans by default, and plan and apply alike refuse a workspace of any other shape
48
+ * before anything is written. The three records use fields only the base this CLI bundles declares, so the apply first
49
+ * installs that base where the workspace has another, as `ia init` installs it; it then captures and re-projects each
50
+ * host whose projection the workspace owns through `applyHostProjection`, which retires the 1.x steward guard and
51
+ * deletes the owned steward agent files (`collectMigration`, `applyMigration`).
54
52
  */
55
53
  import { readMigrationJournal, beginMigrationJournal, applyMigrationFiles, finishMigrationJournal, completeMigrationProjection, reopenMigrationProjection, } from './migration-journal.js';
56
54
  import { spawnSync } from 'node:child_process';
@@ -77,8 +75,9 @@ import { findProgram, programEnv, programHome } from './program.js';
77
75
  import { codeOf, openSession } from './session.js';
78
76
  import { atom, blockSymbolWidth, document, entry, fieldRows, headerLine, quote, safeRootAdvice, sectionLabel, truncateDigest, words, } from './render.js';
79
77
  /**
80
- * Relative to the `@inventarch/cli` package root, as `assets/vocabulary.json` is (vocabulary.ts CATALOGUE_PATH). The base
81
- * package's id is read from this pin and appears nowhere in this source: M5.1 §3.2 makes the pin the only authority.
78
+ * Relative to the `@inventarch/cli` package root, as `assets/vocabulary.json` is (vocabulary.ts CATALOGUE_PATH). The
79
+ * base package's id is read from this pin and appears nowhere in this source: the pin is the only authority for those
80
+ * bytes.
82
81
  */
83
82
  export const DESCRIPTOR_PATH = '.ia/release.json';
84
83
  export const STARTER_VERSION = '0.1.0';
@@ -86,10 +85,10 @@ export const STARTER_VERSION = '0.1.0';
86
85
  export const INSTALL_LOCK = '.ia/distributions/install-lock.json';
87
86
  const cachePath = (digest) => `.ia/distributions/cache/${digest}.ia.tgz`;
88
87
  const systemFolder = (name) => `.ia/src/systems/${name}`;
89
- /** Plan amendment C20: where `ia author system <name>` writes a local system, as `ia init --system` does. */
88
+ /** Where `ia author system <name>` writes a local system, as `ia init --system` does. */
90
89
  export const systemPath = (name) => `${systemFolder(name)}/system.ia`;
91
90
  const distributionPath = (name) => `${systemFolder(name)}/records/distribution.ia`;
92
- /** Position-and-projection §3: the one file the three starter records share, at the root of the authored source. */
91
+ /** SPEC `init`: the one file the three starter records share, at the root of the authored source. */
93
92
  export const WORKSPACE_PATH = '.ia/src/workspace.ia';
94
93
  /** Create-only: the local working state each clone makes for itself, never the authored records or the lock. */
95
94
  export const IGNORE_PATH = '.ia/.gitignore';
@@ -211,10 +210,10 @@ const NAME = /^[a-z][a-z0-9-]*$/;
211
210
  const NAME_LIMIT = 64;
212
211
  /** A local system name `ia init --system` and `ia author system` accept: the id rule and the system-name ceiling. */
213
212
  export const isSystemName = (name) => NAME.test(name) && name.length <= NAME_LIMIT;
214
- /** M5.2 §4.3: `createFile`'s temporary name, `<target>.<randomUUID()>.tmp` (apps/distribution/src/files.ts:76). */
213
+ /** `createFile`'s temporary name, `<target>.<randomUUID()>.tmp` (apps/distribution/src/files.ts:76). */
215
214
  export const LEFTOVER = /^(system\.ia|workspace\.ia|distribution\.ia|release\.json|\.gitignore)\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp$/;
216
215
  /** The installation, not the target, is at fault; `ia doctor` names the channel a reinstall goes through. */
217
- /** M5.1 §2.1's paths: the authored source, the ignore file, the descriptor, the install state and the capture. */
216
+ /** The paths init owns: the authored source, the ignore file, the descriptor, the install state and the capture. */
218
217
  export function ownedPaths(name, system = false) {
219
218
  return [
220
219
  { path: '.ia/src/', purpose: 'authored records' },
@@ -228,7 +227,7 @@ export function ownedPaths(name, system = false) {
228
227
  }
229
228
  /**
230
229
  * §2.1: an existing directory, or a single new segment under an existing directory. Anything else is usage. `rerun`
231
- * spells the refused invocation for another target (design row 27); `runInit` keeps every other argument it was given.
230
+ * spells the refused invocation for another target; `runInit` keeps every other argument it was given.
232
231
  */
233
232
  export function resolveTarget(cwd, supplied, rerun = (target) => `ia init ${quote(target)}`) {
234
233
  const target = supplied === undefined ? resolve(cwd) : isAbsolute(supplied) ? resolve(supplied) : resolve(cwd, supplied);
@@ -254,12 +253,12 @@ const writable = (path) => {
254
253
  }
255
254
  };
256
255
  /**
257
- * M5.1 §3.2 and §5: read the pin and verify the bytes against it, never falling back to another file. A missing
258
- * archive is read as no bytes, so the archive verifier's own refusal reports it; a pin that cannot be read at all
259
- * has no digest to verify against and is the CLI's own failure. Either way the next action says the installation is
260
- * damaged, because nothing the user did to the target can cause it.
256
+ * Read the pin and verify the bytes against it, never falling back to another file. A missing archive is read as no
257
+ * bytes, so the archive verifier's own refusal reports it; a pin that cannot be read at all has no digest to verify
258
+ * against and is the CLI's own failure. Either way the next action says the installation is damaged, because nothing
259
+ * the user did to the target can cause it.
261
260
  */
262
- /** M5.1 §2.3's normalization: lowercase, every run outside `[a-z0-9-]` becomes `-`, no leading or trailing `-`. */
261
+ /** The name's normalization: lowercase, every run outside `[a-z0-9-]` becomes `-`, no leading or trailing `-`. */
263
262
  export const normalizeName = (directory) => {
264
263
  const normalized = directory.toLowerCase().replace(/[^a-z0-9-]+/g, '-');
265
264
  let start = 0, end = normalized.length;
@@ -270,7 +269,7 @@ export const normalizeName = (directory) => {
270
269
  end--;
271
270
  return normalized.slice(start, end);
272
271
  };
273
- /** M5.1 §2.3: valid only if the name, the full id and the public-system rule all hold. Nothing is invented. */
272
+ /** Valid only if the name, the full id and the public-system rule all hold. Nothing is invented. */
274
273
  export function starterIdentity(root, supplied, systems) {
275
274
  const name = supplied === undefined ? normalizeName(basename(root)) : supplied.slice(supplied.indexOf('/') + 1);
276
275
  const id = supplied ?? `local/${name}`;
@@ -285,10 +284,9 @@ export function starterIdentity(root, supplied, systems) {
285
284
  return { name, id, conflict: null };
286
285
  }
287
286
  /**
288
- * `--system`'s local system, the 1.x starter system unchanged (M5.1 §2.2, verbatim in shape): the steward needs
289
- * `agent-system`, and `governance` is required. `work-system` is required so the system folder can hold `@plan`,
290
- * `@milestone`, `@task` and `@decision` records with no edit: a system may use only words owned by systems it directly
291
- * requires (operator decision, 2026-09-25).
287
+ * `--system`'s local system, the 1.x starter system unchanged (verbatim in shape): the steward needs `agent-system`,
288
+ * and `governance` is required. `work-system` is required so the system folder can hold `@plan`, `@milestone`, `@task`
289
+ * and `@decision` records with no edit: a system may use only words owned by systems it directly requires.
292
290
  */
293
291
  export function starterSystem(name) {
294
292
  return [
@@ -314,11 +312,11 @@ export function starterSystem(name) {
314
312
  ].join('\n');
315
313
  }
316
314
  /**
317
- * Position-and-projection §3's three records, at placement authored (band 100), with only the fields their schemas
318
- * declare (plan amendment B13). The `@workspace` composes every installed system, so nothing installed is unreachable
319
- * (M5.1 §2.2), declares the authored root its records are captured under and names the participant as its steward.
320
- * The participant `@agent` implies no host permission, and its `@mandate` grants it closed moves over that workspace;
321
- * the mandate's one prose clause claims nothing. Every name is the workspace's (decision identity-namespace).
315
+ * SPEC `init`'s three records, at placement authored (band 100), with only the fields their schemas declare. The
316
+ * `@workspace` composes every installed system, so nothing installed is unreachable, declares the authored root its
317
+ * records are captured under and names the participant as its steward. The participant `@agent` implies no host
318
+ * permission, and its `@mandate` grants it closed moves over that workspace; the mandate's one prose clause claims
319
+ * nothing. Every name is the workspace's.
322
320
  */
323
321
  export function starterRecords(name, systems, sources = []) {
324
322
  return [
@@ -354,7 +352,7 @@ export function starterRecords(name, systems, sources = []) {
354
352
  ].join('\n');
355
353
  }
356
354
  /**
357
- * `--system`'s release root (position-and-projection §2 case 3: a distribution's roots are system registrations). It
355
+ * `--system`'s release root (a distribution's roots are system registrations). It
358
356
  * sits in the system folder, so the closure from it stays inside folders the packer can release
359
357
  * (apps/distribution/src/snapshot.ts, "Release roots must belong to native system folders").
360
358
  */
@@ -373,8 +371,8 @@ export function starterDistribution(name) {
373
371
  }
374
372
  /**
375
373
  * The authored files in the order the author step writes them, and the records they hold, in file order. With
376
- * `--system` the `@workspace` composes the local system after `systems` (position-and-projection §2 case 2: a
377
- * repository that owns vocabulary composes its own system), so the packet renders a pointer line for it.
374
+ * `--system` the `@workspace` composes the local system after `systems` (a repository that owns vocabulary composes
375
+ * its own system), so the packet renders a pointer line for it.
378
376
  */
379
377
  export function starterFiles(name, systems, system, sources = []) {
380
378
  return {
@@ -439,10 +437,10 @@ const canonicalHttps = (value) => {
439
437
  };
440
438
  const LOCAL = { repository: null, commit: null, recipe: 'ustar-v1', epoch: 0 };
441
439
  /**
442
- * M5.1 §2.3. Sourced only from a Git checkout with a commit and an HTTPS remote: `origin` when it exists, else the
443
- * first remote Git lists. The remote's configured URL is read as written, so an SSH remote is "no HTTPS remote" and
444
- * is never rewritten into a guessed HTTPS one; a URL carrying credentials is refused the same way rather than copied
445
- * into a file meant to be committed.
440
+ * The descriptor's provenance. Sourced only from a Git checkout with a commit and an HTTPS remote: `origin` when it
441
+ * exists, else the first remote Git lists. The remote's configured URL is read as written, so an SSH remote is "no
442
+ * HTTPS remote" and is never rewritten into a guessed HTTPS one; a URL carrying credentials is refused the same way
443
+ * rather than copied into a file meant to be committed.
446
444
  */
447
445
  export function readProvenance(git) {
448
446
  const local = (missing) => ({ source: LOCAL, missing });
@@ -481,8 +479,8 @@ const baseDependencies = (base) => [
481
479
  { id: base.pin.id, range: `^${base.pin.version}`, systems: base.systems },
482
480
  ];
483
481
  /**
484
- * M5.1 §2.3's table. With `--system`, `distribution` stays null until the compiled record is read (§3.1 step 6);
485
- * without it, `undefined` leaves the key out, because a default starter authors no `@distribution` (plan amendment B7).
482
+ * The release descriptor init writes. With `--system`, `distribution` stays null until admission reads the compiled
483
+ * record; without it, `undefined` leaves the key out, because a default starter authors no `@distribution`.
486
484
  */
487
485
  export function starterDescriptor(id, name, base, provenance, distribution, assets = []) {
488
486
  return {
@@ -501,7 +499,7 @@ export function starterDescriptor(id, name, base, provenance, distribution, asse
501
499
  }
502
500
  /** Two-space JSON with a final newline; `decodeReleaseDescriptor` requires the dependency rows sorted, as they are. */
503
501
  export const descriptorText = (descriptor) => JSON.stringify(descriptor, null, 2) + '\n';
504
- /** M5.2 §4.1: exactly the one request and the one package the pin describes. */
502
+ /** Exactly the one request and the one package the pin describes. */
505
503
  export const locksBase = (lock, pin) => lock !== undefined &&
506
504
  lock.requests.length === 1 &&
507
505
  lock.requests[0].id === pin.id &&
@@ -563,8 +561,9 @@ function lowerFrom(from, root, name, lower) {
563
561
  return plan;
564
562
  }
565
563
  /**
566
- * M5.2 §4.1. The starter bytes compared are what this invocation would write for its resolved id: they depend only
567
- * on the name, `--system` and the bundled manifest, so they are recomputed on every run instead of being journaled.
564
+ * The plan: the target's classification, its conflicts and the steps. The starter bytes compared are what this
565
+ * invocation would write for its resolved id: they depend only on the name, `--system` and the bundled manifest, so
566
+ * they are recomputed on every run instead of being journaled.
568
567
  */
569
568
  export function collectInit(request) {
570
569
  const { root, host } = request;
@@ -607,7 +606,7 @@ export function collectInit(request) {
607
606
  }
608
607
  : starterFiles(name, base.systems, system, sources);
609
608
  const assets = lowered?.assets ?? [];
610
- // M5.2 §4.3: a temporary file `createFile` left beside one of this initialization's own targets.
609
+ // A temporary file `createFile` left beside one of this initialization's own targets.
611
610
  const targets = new Set([...files.map((file) => file.path), IGNORE_PATH, DESCRIPTOR_PATH]);
612
611
  // `.<uuid>.tmp` is 41 characters: the dot, a 36-character UUID and `.tmp`.
613
612
  const leftover = (path) => LEFTOVER.test(basename(path)) && targets.has(path.slice(0, -41));
@@ -615,11 +614,11 @@ export function collectInit(request) {
615
614
  const written = new Set();
616
615
  let lock = false, installed = false;
617
616
  if (present) {
618
- // readInstalledState refuses while `.ia/distributions/pending.json` exists, which is M5.2 §4.1's
619
- // recovery-required: an interrupted apply must be recovered before anything reasons about this workspace.
620
- // Its rows are held back so the plan lists authored source, then the lock, then install state, as M4 did.
617
+ // readInstalledState refuses while `.ia/distributions/pending.json` exists, which is recovery-required: an
618
+ // interrupted apply must be recovered before anything reasons about this workspace. Its rows are held back so the
619
+ // plan lists authored source, then the lock, then install state, as before.
621
620
  const installation = [];
622
- // M5.2 §4.1: a held or abandoned install lock is recovery-required too. A process killed inside
621
+ // A held or abandoned install lock is recovery-required too. A process killed inside
623
622
  // applyInstallation skips the `finally` that releases it (apps/distribution/src/install.ts:67-97), before
624
623
  // `pending` exists and after it is removed. `ia recover installation` clears a dead holder's lock and refuses a
625
624
  // live one (`acquire(root, true)`, install.ts:71), so it is the remedy whether or not a journal exists; the
@@ -678,7 +677,7 @@ export function collectInit(request) {
678
677
  reason: 'A lock already names direct requests and resolved versions',
679
678
  });
680
679
  conflicts.push(...installation);
681
- // M5.2 §4.1: a completed initialization is a conflict, because the starter now belongs to the user (band 100).
680
+ // A completed initialization is a conflict, because the starter now belongs to the user (band 100).
682
681
  if (existsSync(resolve(root, DESCRIPTOR_PATH)))
683
682
  conflicts.push({ path: DESCRIPTOR_PATH, reason: 'The target is already initialized' });
684
683
  }
@@ -736,20 +735,20 @@ export function collectInit(request) {
736
735
  /**
737
736
  * The sentence the next action of a step that fails or is interrupted once the descriptor is written opens with:
738
737
  * initialization is complete, so running `ia init` again refuses the target, and each effect is finished by its own
739
- * command (design §3). The project effect's also says whether the capture before it was taken.
738
+ * command. The project effect's also says whether the capture before it was taken.
740
739
  */
741
740
  const INITIALIZED = 'The workspace is initialized.';
742
741
  const CAPTURED = 'The workspace is initialized and captured.';
743
742
  const UNCAPTURED = 'The workspace is initialized but not captured.';
744
743
  /**
745
- * M5.2 §3.1's steps, in position-and-projection §3's order. Each step before the descriptor either completes or leaves
746
- * a state `collectInit` classifies as resumable or recovery-required. The signal is observed at step boundaries (§5):
747
- * before the first write it is the plain interruption and the target is byte-identical; after one, the interruption
748
- * names the rerun that finishes. Two effects follow the completion point, each reported apart, and each that fails or
749
- * is interrupted leaves the workspace initialized and names its own command: the capture, `ia capture`, and, only when
744
+ * The apply's steps, in SPEC `init`'s order. Each step before the descriptor either completes or leaves a state
745
+ * `collectInit` classifies as resumable or recovery-required. The signal is observed at step boundaries (§5): before
746
+ * the first write it is the plain interruption and the target is byte-identical; after one, the interruption names the
747
+ * rerun that finishes. Two effects follow the completion point, each reported apart, and each that fails or is
748
+ * interrupted leaves the workspace initialized and names its own command: the capture, `ia capture`, and, only when
750
749
  * `options.project` is given (`--host`), the project effect, `ia host`. The project effect reads the live revision,
751
- * never the capture (plan amendment B8), so it runs after a capture that failed too, and that failure is then refused
752
- * with the capture's own repair, after a sentence saying the projection is written.
750
+ * never the capture, so it runs after a capture that failed too, and that failure is then refused with the capture's
751
+ * own repair, after a sentence saying the projection is written.
753
752
  */
754
753
  export async function applyInit(view, options) {
755
754
  const { root, starter } = view;
@@ -790,11 +789,11 @@ export async function applyInit(view, options) {
790
789
  if (ignore === 'written')
791
790
  createFile(root, IGNORE_PATH, Buffer.from(IGNORE_TEXT));
792
791
  boundary('author');
793
- // Step 5, admission: the identities are read from the compiled graph, never string-constructed (M5.1 §2.3).
792
+ // Step 5, admission: the identities are read from the compiled graph, never string-constructed.
794
793
  const { compiled } = admitStarter(root, starter.records, 'initialized', '');
795
794
  const authored = compiled.map((record) => record.identity), distribution = compiled.find((record) => record.discriminator === 'distribution')?.identity ?? null;
796
795
  boundary('admission');
797
- // Step 6, the completion point (§4.1). A default starter's descriptor names no distribution (plan amendment B7).
796
+ // Step 6, the completion point (the apply spec §5). A default starter's descriptor names no distribution.
798
797
  createFile(root, DESCRIPTOR_PATH, Buffer.from(descriptorText(starterDescriptor(id, name, base, starter.provenance, distribution ?? undefined, starter.assets))));
799
798
  checkpoint('init:descriptor');
800
799
  const installed = readInstalledState({ root });
@@ -837,8 +836,8 @@ export async function applyInit(view, options) {
837
836
  };
838
837
  }
839
838
  /**
840
- * M5.1 §4's three calls, offline, resolved the way `ia install` resolves (distribute.ts collectPlan): the bundled base
841
- * is cached, resolved from that one archive and installed as the workspace's one request, by `ia init` into a new
839
+ * The installer's three calls, offline, resolved the way `ia install` resolves (distribute.ts collectPlan): the bundled
840
+ * base is cached, resolved from that one archive and installed as the workspace's one request, by `ia init` into a new
842
841
  * workspace and by `ia init --migrate` in place of a 1.x base. A signal during it is `resume`.
843
842
  */
844
843
  async function installBase(root, base, operation, options, resume) {
@@ -869,7 +868,7 @@ async function installBase(root, base, operation, options, resume) {
869
868
  const conflictMessage = (conflicts, blocked) => conflicts.length === 1
870
869
  ? `${conflicts[0].reason}: ${conflicts[0].path}`
871
870
  : `${conflicts.length} conflicts block ${blocked}: ${conflicts.map((row) => `${row.path} (${row.reason})`).join('; ')}`;
872
- /** M5.2 §4.1: every conflict is listed; `--apply` refuses at class 3 and writes nothing. */
871
+ /** Every conflict is listed; `--apply` refuses at class 3 and writes nothing. */
873
872
  function initializedNext(view) {
874
873
  if (!view.conflicts.some((row) => row.path === DESCRIPTOR_PATH && row.reason === 'The target is already initialized'))
875
874
  return null;
@@ -964,7 +963,7 @@ const stepRows = (view, symbol, caps) => [
964
963
  const provenanceText = (provenance) => provenance.missing === null
965
964
  ? `${provenance.source.repository} at ${provenance.source.commit.slice(0, 12)}`
966
965
  : `Unpublished local; ${MISSING[provenance.missing]}`;
967
- /** M5.1 §7 item 4: the starter row carries the real contents rather than the plan task that specified them. */
966
+ /** The starter rows name the records, release and provenance this initialization would write. */
968
967
  const starterRows = (view, caps) => {
969
968
  const { starter } = view, pin = starter.base;
970
969
  const rows = starter.name === null || starter.id === null
@@ -1104,7 +1103,7 @@ export function renderApplied(view, applied, caps) {
1104
1103
  words(`${applied.resumed ? 'Finished initializing' : 'Initialized'} ${applied.id}; release descriptor ${DESCRIPTOR_PATH}.`),
1105
1104
  words(`Installed generation ${truncateDigest(applied.generation, caps.ascii)}, counter ${applied.counter}.`),
1106
1105
  ], { depth: 1, symbol: 'success' }, caps),
1107
- // Position-and-projection §3: the records authored, then each effect, reported apart.
1106
+ // SPEC `init`: the records authored, then each effect, reported apart.
1108
1107
  authoredEntry(applied, caps),
1109
1108
  capturedEntry(applied.effects.capture, caps),
1110
1109
  applied.effects.project === 'skipped'
@@ -1159,8 +1158,8 @@ export async function runInit(context) {
1159
1158
  return await initialize(context, root, id);
1160
1159
  }
1161
1160
  catch (error) {
1162
- // Design row 27: this verb's target is `<directory>`, which `--root` cannot carry, so a service refusal with no
1163
- // remedy of its own is given the fallback for that directory rather than for the cwd, which may not be it.
1161
+ // This verb's target is `<directory>`, which `--root` cannot carry, so a service refusal with no remedy of its own
1162
+ // is given the fallback for that directory rather than for the cwd, which may not be it.
1164
1163
  if (error instanceof Refusal || error instanceof Interrupted || error instanceof UsageError || host.signal?.aborted)
1165
1164
  throw error;
1166
1165
  throw refusalOf(error, { command: 'init', root });
@@ -1213,7 +1212,7 @@ async function initialize(context, root, id) {
1213
1212
  // §2.8 rule 3, as `ia install` asks it: parsing already refused every `--apply` whose question cannot be answered.
1214
1213
  if (!args.flag('yes') && !(await confirm(host.interaction, renderInitSummary(view, caps), CONFIRMATION)))
1215
1214
  return { exitCode: 0, stdout: renderDeclined(view, caps, args.positionals[0], host), stderr: '' };
1216
- // The project effect, last (position-and-projection §3): the `ia host` path, whose apply writes the receipt.
1215
+ // The project effect, last (SPEC `init`): the `ia host` path, whose apply writes the receipt.
1217
1216
  const project = selected === 'none' ? undefined : (done) => registerHost(context, selected, root, done);
1218
1217
  try {
1219
1218
  return rendered(await applyInit(view, { packageRoot: host.packageRoot, signal: host.signal, project }));
@@ -1243,14 +1242,14 @@ function registerHost(context, selected, root, done) {
1243
1242
  const host = `ia host ${selected} --root ${quote(root)} --apply`;
1244
1243
  const finish = `Run "${host}" to finish host registration.`, recover = `Run "${host}" for the recovery it names, then run it again to finish host registration.`;
1245
1244
  const composed = (next) => `${done} ${next === null ? finish : next.endsWith(THEN_RERUN) ? recover : rootedNext(next, selected, root)}`;
1246
- // M5.2 §5: a signal observed after the last init write interrupts a command that has written, so it names the rerun.
1245
+ // A signal observed after the last init write interrupts a command that has written, so it names the rerun.
1247
1246
  if (context.host.signal?.aborted)
1248
1247
  throw new Interrupted(composed(null));
1249
1248
  const command = findCommand('host');
1250
1249
  const args = parseArguments([selected, '--root', root, '--apply', '--yes'], command.grammar);
1251
1250
  try {
1252
1251
  const applied = applyHostSet(collectHost({ ...context, command, args }), context.host.packageRoot, context.host.signal);
1253
- // A host apply that returns has projected, and `applyHostProjection` wrote the receipt (B12) before it returned.
1252
+ // A host apply that returns has projected, and `applyHostProjection` wrote the receipt before it returned.
1254
1253
  const receipt = readReceipt(root, selected);
1255
1254
  return { effect: { host: selected, files: receipt.files, receipt: STATE.receipt(selected) }, host: applied };
1256
1255
  }
@@ -1504,7 +1503,7 @@ export function collectMigration(request) {
1504
1503
  for (const host of projected)
1505
1504
  try {
1506
1505
  const guard = planRetirement(root, host) === null ? 'none' : 'retire';
1507
- // The hook step the projection effect runs (review finding H-R3), found before the migration plans its writes.
1506
+ // The hook step the projection effect runs, found before the migration plans its writes.
1508
1507
  preflightHooks(root, host);
1509
1508
  hosts.push({ host, guard, files: migratedFiles(root, host) });
1510
1509
  }
@@ -1600,7 +1599,7 @@ const MIGRATED_CAPTURED = 'The workspace is migrated and captured.';
1600
1599
  const MIGRATED_UNCAPTURED = 'The workspace is migrated but not captured.';
1601
1600
  /**
1602
1601
  * The admission step `ia init` and `ia init --migrate` share: zero error findings, then each planned starter record as
1603
- * the compiled graph holds it at its path, never string-constructed (M5.1 §2.3), with every record the graph holds.
1602
+ * the compiled graph holds it at its path, never string-constructed, with every record the graph holds.
1604
1603
  * `done` opens each refusal's next action with what the command completed before it, if anything.
1605
1604
  */
1606
1605
  function admitStarter(root, planned, what, done) {
@@ -2014,7 +2013,7 @@ async function migrate(context, root) {
2014
2013
  /**
2015
2014
  * A finished git run's answer, or null when git is not really there: it could not start, or it is the macOS stub
2016
2015
  * `/usr/bin/git`, which only asks for the Xcode Command Line Tools and fails; reading that as "not a Git checkout" would
2017
- * send the user after the wrong fix (#323).
2016
+ * send the user after the wrong fix (crowncodes/ia#323).
2018
2017
  */
2019
2018
  export function gitAnswer(result) {
2020
2019
  if (result.error !== undefined)