@inventarch/cli 3.0.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.
- package/README.md +221 -23
- package/SPEC.md +39 -18
- package/assets/base/df626d1dc4949649ba7203842b29b4f064e0552e8db8c2c41ff74b6462b81b75.ia.tgz +0 -0
- package/assets/base.json +3 -3
- package/assets/host/f91ffe4c2071b196e925e93507bd661b3e09f5dc75392f7d6453fdbec5e28d62.tgz +0 -0
- package/assets/host.json +4 -4
- package/assets/vocabulary.json +152 -1
- package/dist/author.d.ts.map +1 -1
- package/dist/author.js +6 -7
- package/dist/author.js.map +1 -1
- package/dist/briefing.d.ts +2 -2
- package/dist/briefing.d.ts.map +1 -1
- package/dist/capture.d.ts +2 -2
- package/dist/capture.js +7 -7
- package/dist/commands.d.ts +7 -7
- package/dist/commands.d.ts.map +1 -1
- package/dist/commands.js +69 -30
- package/dist/commands.js.map +1 -1
- package/dist/consumer.d.ts +29 -25
- package/dist/consumer.d.ts.map +1 -1
- package/dist/consumer.js +40 -35
- package/dist/consumer.js.map +1 -1
- package/dist/decline.js +1 -1
- package/dist/distribute.d.ts +13 -14
- package/dist/distribute.d.ts.map +1 -1
- package/dist/distribute.js +17 -17
- package/dist/distribute.js.map +1 -1
- package/dist/doctor-user.d.ts +1 -1
- package/dist/doctor-user.d.ts.map +1 -1
- package/dist/doctor-user.js +2 -2
- package/dist/doctor-user.js.map +1 -1
- package/dist/doctor.d.ts +1 -1
- package/dist/doctor.d.ts.map +1 -1
- package/dist/doctor.js +53 -54
- package/dist/doctor.js.map +1 -1
- package/dist/format.js +3 -3
- package/dist/format.js.map +1 -1
- package/dist/home-remedy.d.ts +1 -1
- package/dist/home-remedy.js +1 -1
- package/dist/host-projection.d.ts +41 -38
- package/dist/host-projection.d.ts.map +1 -1
- package/dist/host-projection.js +84 -71
- package/dist/host-projection.js.map +1 -1
- package/dist/host.d.ts +37 -38
- package/dist/host.d.ts.map +1 -1
- package/dist/host.js +54 -57
- package/dist/host.js.map +1 -1
- package/dist/init.d.ts +69 -58
- package/dist/init.d.ts.map +1 -1
- package/dist/init.js +166 -107
- package/dist/init.js.map +1 -1
- package/dist/main.js +4 -4
- package/dist/main.js.map +1 -1
- package/dist/next.js +15 -15
- package/dist/next.js.map +1 -1
- package/dist/operation-help.d.ts +3 -3
- package/dist/operation-help.d.ts.map +1 -1
- package/dist/operation-help.js +9 -9
- package/dist/operation-help.js.map +1 -1
- package/dist/pack.js +6 -6
- package/dist/plugin-product.d.ts +3 -0
- package/dist/plugin-product.d.ts.map +1 -0
- package/dist/plugin-product.js +154 -0
- package/dist/plugin-product.js.map +1 -0
- package/dist/plugin-sources.d.ts +16 -0
- package/dist/plugin-sources.d.ts.map +1 -0
- package/dist/plugin-sources.js +120 -0
- package/dist/plugin-sources.js.map +1 -0
- package/dist/position.d.ts.map +1 -1
- package/dist/position.js +10 -11
- package/dist/position.js.map +1 -1
- package/dist/preview.d.ts +4 -4
- package/dist/preview.d.ts.map +1 -1
- package/dist/preview.js +27 -28
- package/dist/preview.js.map +1 -1
- package/dist/profile.d.ts +23 -23
- package/dist/profile.d.ts.map +1 -1
- package/dist/profile.js +53 -54
- package/dist/profile.js.map +1 -1
- package/dist/project.d.ts +7 -8
- package/dist/project.d.ts.map +1 -1
- package/dist/project.js +38 -28
- package/dist/project.js.map +1 -1
- package/dist/read.d.ts +1 -1
- package/dist/read.d.ts.map +1 -1
- package/dist/read.js +4 -4
- package/dist/read.js.map +1 -1
- package/dist/render.d.ts +3 -3
- package/dist/render.js +3 -3
- package/dist/session.d.ts +9 -9
- package/dist/session.d.ts.map +1 -1
- package/dist/session.js +10 -10
- package/dist/session.js.map +1 -1
- package/dist/validate.d.ts +8 -8
- package/dist/validate.d.ts.map +1 -1
- package/dist/validate.js +34 -37
- package/dist/validate.js.map +1 -1
- package/dist/vocabulary.js +2 -2
- package/dist/vocabulary.js.map +1 -1
- package/package.json +6 -6
- package/assets/base/08eaab3e1a6215d78283b82a94a0228367ac7bd78d0a746c56db79c8d7546c3a.ia.tgz +0 -0
- package/assets/host/d7722e32fd0511df2a6dfdf2353e621fdff1cf559d5c8b7ac256c7eceac0452f.tgz +0 -0
package/SPEC.md
CHANGED
|
@@ -24,37 +24,58 @@ Owner migrations and grants are explicit source changes followed by `ia validate
|
|
|
24
24
|
|
|
25
25
|
| Command | Behavior |
|
|
26
26
|
| --- | --- |
|
|
27
|
-
| `init [directory]` | Preview a workspace, or create it with `--apply`; `--host none` omits host registration and `--id <provider/name>` sets the package id (default `local/<directory name>`). `--decline today` or `--decline forever` records that a repository should not be initialized, and `--forget-decline` removes that record. The target is positional, so `--root` is refused. The starter (2026-10-09, milestone position-packet task init-three-records; position-and-projection §3; plan amendments B7 and B13; decisions local-system-at-init and identity-namespace) is exactly three records at placement authored (band 100) in `.ia/src/workspace.ia`, each with only the fields its schema declares: `@workspace <name>` (`composition.systems` naming every system the bundled base installs, `composition.sources [".ia/src @authored"]`, `composition.steward @agent <name>`), its participant `@agent <name>` ("The IDE agent operating in the <name> workspace, any vendor.", `governance.applies []`) and `@mandate <name>-mandate` (`governance.requires "Claim no host permission or execution from this mandate."`, `authority.participant @agent <name>`, `authority.moves [Observation, Verification, Synthesis, Delegation, Execution]`, `authority.scope [@workspace <name>]`). The record names are the workspace's; the package id's provider never prefixes them. `.ia/.gitignore` holding `work/` and `distributions/` is written only where none exists; an existing one is left as it is and reported, never a conflict. No local `@system` and no `@distribution` are written, so the release descriptor names no `distribution`. `--system`, for a repository that will own vocabulary, also writes `.ia/src/systems/<name>/system.ia` (the 1.x `@system <name>`, requiring `agent-system`, `work-system` and `workspace-system`, and its `@agent <name>-steward`) and `.ia/src/systems/<name>/records/distribution.ia` (`@distribution <name>-distribution` with `distribution.records [@system <name>]`), and the descriptor names that distribution, read from the compiled graph, so `pack` releases the system folder; its `@workspace` composes the local system after the base's (2026-10-09, milestone position-packet task init-migrate-flag; position-and-projection §2 case 2), so `composition.systems` ends with `@system <name>` and the position packet renders a pointer line for it. The apply runs install, author (create-only: a starter file already present with the same bytes is skipped), admission (zero error findings, and each starter record compiled at its path), descriptor (the completion point), then two effects reported apart: capture, the `capture` verb's own write of `.ia/work/snapshot/current.json` through the database, and, only with `--host`, project, the `host <host> --apply` path, whose projection `applyHostProjection` writes. An interruption before the descriptor names the rerun of `init`, which skips completed steps. Past the descriptor an effect that fails or is interrupted leaves every earlier result in place and says so, opening its next action with the sentence saying the workspace is initialized: a capture that fails is refused as `capture` refuses it, with its code, location and repair, then `capture --root <root>`, and without `--host` an interruption there names `capture --root <root>`. With `--host` the project effect runs after a capture that failed too, because the packet reads the live revision rather than the capture (plan amendment B8), and that capture refusal then says the projection is written; an interruption before the capture, or a host step that refuses, names `host <host> --root <root> --apply` (or `ia host`'s own remedy, rooted), saying whether the capture was taken. With `--json` the plan lists the steps `install`, `author`, `admission`, `descriptor`, `capture` and, with `--host`, `project`, and the starter's `system`, `paths`, `records` (each as `@<word> <name>`) and `ignore` (`{path, status}`, `create` or `present`); `applied` adds `distribution` (null without `--system`), `authored` (the starter records' identities in file order: three, or six with `--system`), `ignore` (`written` or `present`) and `effects`, `{capture: {revision, records}, project: {host, files, receipt} | 'skipped'}`, where `files` are the receipt's files with their SHA-256 and `receipt` is its path. The human report says the same: the records authored, the ignore file, the capture's records and revision, and the projected files and receipt or that project was skipped. `--migrate` (2026-10-09, milestone position-packet task init-migrate-flag; plan amendments B7, B9 and B11; decision local-system-at-init) rewrites a workspace a 1.1.0 `init` wrote (1.0 and 1.1 write the same starter) into this starter, keeping its descriptor's id. It takes `--system`, `--apply`, `--json` and `--yes`; `--id`, `--host` and the decline options with it are usage (exit 2). A 1.1.0 starter is one folder in `.ia/src/systems/`, its local system `<name>`, holding only `system.ia`, with exactly `@system <name>`, which registers no word, and `@agent <name>-steward`, and `records/*.ia`, of which `records/workspace.ia` holds exactly `@workspace <name>` and `@distribution <name>-distribution`, the distribution `.ia/release.json` names. The three records use fields only the base this CLI bundles declares (`composition.sources`, `composition.steward` and the `@mandate`'s `authority`), so a workspace whose installed `inventarch/language` is another archive has it replaced, which needs a lock holding that one base alone. Plan and apply run one preflight before anything is written: any other shape, a nested folder or another file or record included, and a base to replace in a lock that holds anything else, is refused as `IA-CLI-CONFLICT` (exit 3) naming `init --help`; a workspace that does not admit is refused as `IA-CLI-CONFLICT` naming `validate --root <root>`; with a host's projection state present, a pending host journal is refused with the journal's code, located at it, naming its recovery on the distribution binary, then the rerun; and each destination that already exists (`.ia/src/workspace.ia`, or `.ia/src/<file>.ia` for a moved file), each record the workspace keeps that holds the word and name of a starter record the migration authors anew (`@agent <name>` or `@mandate <name>-mandate`, which would tie with it), located at that record's file, and each host whose projection state exists and whose guard retirement or file plan the planners refuse, such as a file without a marker at a target path, is a conflict. The plan lists the conflicts, the base install, every move, write and delete, the empty folders included, and each registered host's guard retirement and file actions, planned for the migrated records: every rendered file carries the workspace revision, which the migration changes, so none is `unchanged`. It is exit 0. `--apply` refuses a plan with conflicts and writes nothing: a destination or record collision as `IA-CLI-CONFLICT` naming `init <directory> --migrate`, whose plan lists each one; a projection conflict alone keeps the planner's code, located at its file, and names `host <host> --root <root>`, whose plan names each file it refuses. The apply first installs the bundled base where the plan says so, offline and as `init` installs it, while the records are still the 1.1.0 starter's, which the installer admits against it before activating it; an interruption there names the rerun of the migration, which installs the base again only if the bundled one is still not installed. It then moves every other `records/<file>.ia` byte for byte to `.ia/src/<file>.ia`, where its records keep their identities, since a record's word and not its folder decides its system; writes `.ia/src/workspace.ia` with the three starter records, keeping the 1.x `@workspace`'s name and `composition.systems` without the local system and adding `composition.sources` and `composition.steward`, and `.ia/.gitignore` where none exists; deletes `records/workspace.ia`, `system.ia` and the three folders they leave empty; and rewrites the descriptor without `distribution` and with the bundled base's dependency row, as `init` writes it, in place of the installed base's, keeping every other row. With `--system` it keeps `system.ia` as it is, writes `records/distribution.ia` as `init --system` does, rooted at `[@system <name>]`, composes the local system and keeps the descriptor's distribution, so `pack` still releases the folder; the descriptor is left byte for byte, whatever its formatting, when its base row is already the bundled base's. Admission then reads the starter identities and each moved file's, and the two effects follow: the capture, and for each host whose projection state exists its projection through `applyHostProjection`, which retires the 1.x steward guard and deletes the owned steward agent files. A file step that fails says which writes and deletes it made, the base install included, since nothing is rolled back, and names `validate --root <root>`, or, when the base install is all it made and the records are still the 1.1.0 starter's, the rerun of the migration; a migrated workspace that fails admission names `validate --root <root>` too, saying neither effect ran; an effect that fails or is interrupted leaves every earlier result in place, says so, and names its own command, `capture --root <root>` or `host <host> --root <root> --apply`. With `--json` the plan holds `migrate` (`1.1.0`), `id`, `name`, `system`, `base` (`{id, installed, bundled}`, each `{version, archive}`), `conflicts` (`{path, reason}`, with `host` and `code` for a projection), `steps` (`install` first only when the base is replaced), `moves` (`{from, to, identities}`), `writes`, `records`, `systems`, `removes` (`{path, identities}` in delete order, a folder as `<path>/` with no identities), `ignore`, `descriptor` (`{path, before, after, dependencies: {before, after}}`) and `hosts` (`{host, guard, files}`), and `applied` is `{status: 'migrated', id, base: 'installed' | 'present', distribution, authored, moved, removed, ignore, effects: {capture, project: [{host, files, receipt, guard, removed}]}}`, `removed` being the plan's `removes` paths. |
|
|
27
|
+
| `init [directory]` | Preview a workspace, or create it with `--apply`; `--host none` omits host registration and `--id <provider/name>` sets the package id (default `local/<directory name>`). `--from <plugin-directory>` lowers a Claude, Codex or Grok plugin into the new workspace as a kit, in place of `--system` (see [Host plugins](#host-plugins)). `--decline today` or `--decline forever` records that a repository should not be initialized, and `--forget-decline` removes that record. The target is positional, so `--root` is refused. The default starter (2026-10-09) is three records at placement authored (band 100) in `.ia/src/workspace.ia`, each with only the fields its schema declares: `@workspace <name>` (`composition.systems` naming every system the bundled base installs, `composition.sources [".ia/src @authored"]`, `composition.steward @agent <name>`), its participant `@agent <name>` ("The IDE agent operating in the <name> workspace, any vendor.", `governance.applies []`) and `@mandate <name>-mandate` (`governance.requires "Claim no host permission or execution from this mandate."`, `authority.participant @agent <name>`, `authority.moves [Observation, Verification, Synthesis, Delegation, Execution]`, `authority.scope [@workspace <name>]`). The record names are the workspace's; the package id's provider never prefixes them. With `--from` the starter is these three records plus the lowered kit: its `@system` and steward, its records, its resources and its assets, so it is no longer three records alone (see [Host plugins](#host-plugins)). `.ia/.gitignore` holding `work/` and `distributions/` is written only where none exists; an existing one is left as it is and reported, never a conflict. No local `@system` and no `@distribution` are written, so the release descriptor names no `distribution`. `--system`, for a repository that will own vocabulary, also writes `.ia/src/systems/<name>/system.ia` (the 1.x `@system <name>`, requiring `agent-system`, `work-system` and `workspace-system`, and its `@agent <name>-steward`) and `.ia/src/systems/<name>/records/distribution.ia` (`@distribution <name>-distribution` with `distribution.records [@system <name>]`), and the descriptor names that distribution, read from the compiled graph, so `pack` releases the system folder; its `@workspace` composes the local system after the base's (2026-10-09), so `composition.systems` ends with `@system <name>` and the position packet renders a pointer line for it. The apply runs install, author (create-only: a starter file already present with the same bytes is skipped), admission (zero error findings, and each starter record compiled at its path), descriptor (the completion point), then two effects reported apart: capture, the `capture` verb's own write of `.ia/work/snapshot/current.json` through the database, and, only with `--host`, project, the `host <host> --apply` path, whose projection `applyHostProjection` writes. An interruption before the descriptor names the rerun of `init`, which skips completed steps. Past the descriptor an effect that fails or is interrupted leaves every earlier result in place and says so, opening its next action with the sentence saying the workspace is initialized: a capture that fails is refused as `capture` refuses it, with its code, location and repair, then `capture --root <root>`, and without `--host` an interruption there names `capture --root <root>`. With `--host` the project effect runs after a capture that failed too, because the packet reads the live revision rather than the capture, and that capture refusal then says the projection is written; an interruption before the capture, or a host step that refuses, names `host <host> --root <root> --apply` (or `ia host`'s own remedy, rooted), saying whether the capture was taken. With `--json` the plan lists the steps `install`, `author`, `admission`, `descriptor`, `capture` and, with `--host`, `project`, and the starter's `system`, `paths`, `records` (each as `@<word> <name>`) and `ignore` (`{path, status}`, `create` or `present`); `applied` adds `distribution` (null without `--system`), `authored` (the starter records' identities in file order: three, six with `--system`, or three plus the lowered kit's with `--from`), `ignore` (`written` or `present`) and `effects`, `{capture: {revision, records}, project: {host, files, receipt} | 'skipped'}`, where `files` are the receipt's files with their SHA-256 and `receipt` is its path. The human report says the same: the records authored, the ignore file, the capture's records and revision, and the projected files and receipt or that project was skipped. `--migrate` (2026-10-09) rewrites a workspace a 1.1.0 `init` wrote (1.0 and 1.1 write the same starter) into this starter, keeping its descriptor's id. It takes `--system`, `--apply`, `--json` and `--yes`; `--id`, `--host` and the decline options with it are usage (exit 2). A 1.1.0 starter is one folder in `.ia/src/systems/`, its local system `<name>`, holding only `system.ia`, with exactly `@system <name>`, which registers no word, and `@agent <name>-steward`, and `records/*.ia`, of which `records/workspace.ia` holds exactly `@workspace <name>` and `@distribution <name>-distribution`, the distribution `.ia/release.json` names. The three records use fields only the base this CLI bundles declares (`composition.sources`, `composition.steward` and the `@mandate`'s `authority`), so a workspace whose installed `inventarch/language` is another archive has it replaced, which needs a lock holding that one base alone. Plan and apply run one preflight before anything is written: any other shape, a nested folder or another file or record included, and a base to replace in a lock that holds anything else, is refused as `IA-CLI-CONFLICT` (exit 3) naming `init --help`; a workspace that does not admit is refused as `IA-CLI-CONFLICT` naming `validate --root <root>`; with a host's projection state present, a pending host journal is refused with the journal's code, located at it, naming its recovery on the distribution binary, then the rerun; and each destination that already exists (`.ia/src/workspace.ia`, or `.ia/src/<file>.ia` for a moved file), each record the workspace keeps that holds the word and name of a starter record the migration authors anew (`@agent <name>` or `@mandate <name>-mandate`, which would tie with it), located at that record's file, and each host whose projection state exists and whose guard retirement or file plan the planners refuse, such as a file without a marker at a target path, is a conflict. The plan lists the conflicts, the base install, every move, write and delete, the empty folders included, and each registered host's guard retirement and file actions, planned for the migrated records: every rendered file carries the workspace revision, which the migration changes, so none is `unchanged`. It is exit 0. `--apply` refuses a plan with conflicts and writes nothing: a destination or record collision as `IA-CLI-CONFLICT` naming `init <directory> --migrate`, whose plan lists each one; a projection conflict alone keeps the planner's code, located at its file, and names `host <host> --root <root>`, whose plan names each file it refuses. The apply first installs the bundled base where the plan says so, offline and as `init` installs it, while the records are still the 1.1.0 starter's, which the installer admits against it before activating it; an interruption there names the rerun of the migration, which installs the base again only if the bundled one is still not installed. It then moves every other `records/<file>.ia` byte for byte to `.ia/src/<file>.ia`, where its records keep their identities, since a record's word and not its folder decides its system; writes `.ia/src/workspace.ia` with the three starter records, keeping the 1.x `@workspace`'s name and `composition.systems` without the local system and adding `composition.sources` and `composition.steward`, and `.ia/.gitignore` where none exists; deletes `records/workspace.ia`, `system.ia` and the three folders they leave empty; and rewrites the descriptor without `distribution` and with the bundled base's dependency row, as `init` writes it, in place of the installed base's, keeping every other row. With `--system` it keeps `system.ia` as it is, writes `records/distribution.ia` as `init --system` does, rooted at `[@system <name>]`, composes the local system and keeps the descriptor's distribution, so `pack` still releases the folder; the descriptor is left byte for byte, whatever its formatting, when its base row is already the bundled base's. Admission then reads the starter identities and each moved file's, and the two effects follow: the capture, and for each host whose projection state exists its projection through `applyHostProjection`, which retires the 1.x steward guard and deletes the owned steward agent files. A file step that fails says which writes and deletes it made, the base install included, since nothing is rolled back, and names `validate --root <root>`, or, when the base install is all it made and the records are still the 1.1.0 starter's, the rerun of the migration; a migrated workspace that fails admission names `validate --root <root>` too, saying neither effect ran; an effect that fails or is interrupted leaves every earlier result in place, says so, and names its own command, `capture --root <root>` or `host <host> --root <root> --apply`. With `--json` the plan holds `migrate` (`1.1.0`), `id`, `name`, `system`, `base` (`{id, installed, bundled}`, each `{version, archive}`), `conflicts` (`{path, reason}`, with `host` and `code` for a projection), `steps` (`install` first only when the base is replaced), `moves` (`{from, to, identities}`), `writes`, `records`, `systems`, `removes` (`{path, identities}` in delete order, a folder as `<path>/` with no identities), `ignore`, `descriptor` (`{path, before, after, dependencies: {before, after}}`) and `hosts` (`{host, guard, files}`), and `applied` is `{status: 'migrated', id, base: 'installed' | 'present', distribution, authored, moved, removed, ignore, effects: {capture, project: [{host, files, receipt, guard, removed}]}}`, `removed` being the plan's `removes` paths. |
|
|
28
28
|
| `validate [path...]` | Check the selected workspace records against language and declared contracts; report attributable diagnostics. A `composition.sources` entry that names no root, and a path selection that selects nothing, are each reported as an `IA-COMP-FIELD-VALUE` warning at the line that states it; admission does not change. These are the findings `ia-distribution validate` reports, from the same validation service. `--severity` sets the lowest severity reported and `--max-findings` the number rendered (default 50). Execution bindings and checks are reported as below; a revoked binding or check exits 1 without being a finding. |
|
|
29
|
-
| `preview <word> [<name> [<field>=<value>...]]` | Show what one edit of the workspace's own records would compile to, and write nothing (2026-10-11
|
|
30
|
-
| `author <word> <name> [<field>=<value>...] --digest <sha256>` | Write what the same `ia preview` form showed (2026-10-11
|
|
31
|
-
| `capture` | Admit the workspace and write its snapshot to `.ia/work/snapshot/current.json` in the `ia-snapshot-1` format: one JSON document with sorted keys and one final newline holding `format` (`ia-snapshot-1`), `language`, `kernelDigest`, `revision` (the full workspace revision), `authoredRevision` (the revision excluding runtime sources), `records` (the admitted records sorted by identity, each with its per-record `digest`), `membership` (one `{identity, root, band, digest}` capture membership row per record, sorted by identity), `diagnostics` (the admission findings and the warnings for declarations that declare nothing, below, ordered by path, line, code and message) and `counts` (`records`, `errors`, `warnings`, `notEvaluated`). Identical sources on one language version capture to identical bytes. The database writes the pair (db SPEC D08a), and every database handle seeds its previous snapshot from it, whatever its cache setting. `.ia/work/snapshot/previous.json` holds the most recent capture whose revision differs from the current one: a capture at a new revision renames the prior `current.json` there, byte for byte, and a capture at an unchanged revision keeps `previous.json` as it is while it holds a capture at another revision. With no readable prior capture (the first one, or a `current.json` that is not an `ia-snapshot-1` capture, which the capture names and replaces), a `previous.json` at another revision is kept as the most recent capture there is; a `previous.json` at the new revision, or one that is no capture, is removed once `current.json` is written. The new bytes are staged in a temporary file in the same directory before either file is replaced, a failed step undoes the ones before it so the pair stays as it was, and a `current.json` that already holds the capture's bytes is not rewritten. The capture writes only under `.ia/work/snapshot/`, creating it when needed, and never touches `.ia/src`. The snapshot is local working state that each clone captures for itself: `ia init` takes the first capture once it has initialized a workspace, so a snapshot exists from then on, and its `.ia/.gitignore`, written only where none exists, lists `work/`, which keeps the snapshot out of version control. Concurrent captures of one root are last-writer-wins. The effect is reported apart from validation: `records`, and how each record's digest compares with the prior capture's `current.json`, as `changed`, `unchanged`, `new` (no row in the prior capture) and `removed` (a row in the prior capture and none now), so `records` is `changed + unchanged + new` and two captures with no edit between them report 0 changed. The first capture has nothing to compare with, so every record is `new`. Admission findings in a source the workspace authors are written into the snapshot and counted, and never stop the write: a capture whose admission has errors still writes, marks its effect line with a warning symbol and exits 1, as `validate` does (warnings alone exit 0). Unresolved references, colliding identities, unconsented rows and every other registration or resolution finding (such as a keyword two adopted or installed systems both register) are such findings wherever they are. Two cases refuse before anything is written, so both files stay as they were
|
|
29
|
+
| `preview <word> [<name> [<field>=<value>...]]` | Show what one edit of the workspace's own records would compile to, and write nothing (2026-10-11; mode validate, move Verification). `ia preview <word> <name> [<field>=<value>...] [--at <path>]` drafts a new record (language `draftSource`, every value first judged by the strict `encodeValue`) and appends it to `--at` or `<first authored root>/<word>.ia`, the first root the repository's `@workspace` declares at authored placement inside `.ia/src`; `ia preview system <name>` is init's starter system at `.ia/src/systems/<name>/system.ia` and takes no field or `--at`; `--relate <owned> <spelling> <target>` adds one row to the record's `relationships` section; `--set <owned> <section.key>=<value>` sets one field, and `+=` adds one item to a list field, creating it when absent. A field is `<section>.<key>`, or a key one field of the schema alone has, and one given twice in either spelling is refused; the shell's split of a value is joined again with single spaces. Owned is a record at authored placement (band 100) whose file lies under an authored root of the repository's `@workspace`, inside `.ia/src` and outside the floor, named by canonical identity or `@word name`; `--at` is relative to the root and must lie under such a root, and is judged as the volume spells it: an existing part of it spelled otherwise (a case variant, an 8.3 short name) refuses, naming the volume's spelling, before the mandate profile or the ownership check reads it. The edit is language's (`appendRecord`, `addRelationship`, `setField`), spliced into the file as it is: other lines keep their bytes and line endings, a byte-order mark stays, and only the edited record is formatted. It compiles through db's draft overlay against one editor snapshot of the workspace and prints the record before and after, the base and candidate revisions, every record of the file with its digest before and after, the file's current sha256 (an absent file reads as empty), and the findings that count against the candidate: the edited or new record's own, and any the base does not hold, matched in the target file by code and record and elsewhere by code, path, line and message, so an error already in another record does not. The editor snapshot admits checks structurally, as `validate` admits them, and lists no evidence (2026-10-11; `AUTHORING` in `src/session.ts`): a `@check` naming one evaluator that is not built in is an owned record the edit forms can name and a new one drafts clean, a check naming none still counts against the candidate, and the base revision printed is the evidence-free one every strict reader reports. A record other than the target whose digest would change refuses the preview. `ia preview <word>` prints the word's lowering (kind, category, facets, primitive, move, artifact set), schema, default file and digest (for `system`, the per-system file), the consent rows that name it or that its own system's ledger can apply to it, and an example command. Exit 0 for a clean candidate and for word guidance, 1 for a candidate with errors. Refusals: a malformed form or an unknown relationship verb is usage (IA-CLI-USAGE, exit 2); an unknown word or field, a value of another type or carrying syntax, a field given twice, a duplicate row, item or record, a nested record, a system already in force (IA-CLI-EDIT-INVALID), no admitted record answering a name (IA-CLI-EDIT-MISSING), a record or path the workspace does not own (IA-CLI-EDIT-UNOWNED), a `@mandate` that binds the acting participant, before or after the edit (its participant is the actor, or it names none and its scope names the workspace or it claims paths), or whose authority the runtime cannot read, naming the governance position and saying a human or another participant makes that change (IA-CLI-EDIT-MANDATE; moves pool across the mandates that bind an actor), a row the two-sided consent rule refuses, naming the system whose ledger refuses it (IA-LANG-EDGE-UNCONSENTED), and the mandate profile's refusals (IA-RUNTIME-MANDATE-MOVE, -WORD, -ACTOR, and IA-RUNTIME-REQUEST-INVALID for a mandate authority the runtime cannot read) exit 1; another spelling of a path, an unsafe path (db's rule, and DEL, a C1 control, a line or paragraph separator or a bidirectional control, which the CLI refuses besides) or a link on the way (IA-DB-PATH-UNSAFE), an unreadable target (IA-DB-SOURCE-UNAVAILABLE), a target that changed while read (IA-DB-SOURCE-CHANGED), a path the draft overlay refuses (IA-DB-DRAFT-INVALID), and a workspace that does not open (as `ia validate` refuses it) exit 3. IA-CLI-EDIT-MANDATE retains its narrower preview rule. The writing command additionally reserves administrative words as described below; a preview is not authorization to write. A next command that would repeat a value holding shell syntax names the word's preview instead. |
|
|
30
|
+
| `author <word> <name> [<field>=<value>...] --digest <sha256>` | Write what the same `ia preview` form showed (2026-10-11; mode author, move Synthesis). Every preview form for a non-administrative record has an author form with the same arguments and `--digest <sha256>`, the target file's sha256 the preview printed (an absent file and an empty one read alike); the candidate is compiled again against one editor snapshot, opened as `preview` opens it (checks admitted structurally, no evidence listed), judged for the author mode, and written only when the file is still the one the digest names and the candidate is clean. The record written carries one attribution comment above it, `# authored-by @agent <participant> under @mandate <name> at <authored revision>`: the acting participant, the first governing mandate that binds it and grants Synthesis, and the workspace's authored revision (db `authoredRevision`) the candidate was compiled against; a second author replaces the comment rather than stacking one, and no capture membership records it. An existing file is read again through db's opened-handle reader just before the write and written by the distribution's `replace` (a temporary file and a rename, every component checked for links), keeping its permission bits; a new file by `createFile`, which refuses an entry that appeared since. `ia author` refuses administrative words as described below, including the system starter and its implicit agent. Every successful author names its next command (`ia validate`) judged by the profile that allowed it, as a refusal's next is: the governance position where the profile refuses that command, and a named actor carried as the participant it resolved. The output is the record written, the file's sha256 before and after, the authored revision and the revision of the workspace with what was written, the findings, and `ia validate` as the next command. Refusals are preview's for the same form, plus: a missing or malformed `--digest` (IA-CLI-USAGE, exit 2, naming the preview), judged after the profile and the candidate, so a mandate refusal comes first and the preview named is one the profile allows, else the governance position; a file that is not the one the digest names, or that changed, appeared or disappeared while authored (IA-CLI-EDIT-STALE, exit 1); a candidate with an error that counts against it (IA-CLI-EDIT-UNCLEAN, exit 1); a write the volume refuses (the distribution's IA-DIST code, or IA-CLI-FAILED for a raw volume error such as EPERM, exit 3, naming the repair and the preview). Each names the preview of the same form, and every refusal writes nothing. |
|
|
31
|
+
| `capture` | Admit the workspace and write its snapshot to `.ia/work/snapshot/current.json` in the `ia-snapshot-1` format: one JSON document with sorted keys and one final newline holding `format` (`ia-snapshot-1`), `language`, `kernelDigest`, `revision` (the full workspace revision), `authoredRevision` (the revision excluding runtime sources), `records` (the admitted records sorted by identity, each with its per-record `digest`), `membership` (one `{identity, root, band, digest}` capture membership row per record, sorted by identity), `diagnostics` (the admission findings and the warnings for declarations that declare nothing, below, ordered by path, line, code and message) and `counts` (`records`, `errors`, `warnings`, `notEvaluated`). Identical sources on one language version capture to identical bytes. The database writes the pair (db SPEC D08a), and every database handle seeds its previous snapshot from it, whatever its cache setting. `.ia/work/snapshot/previous.json` holds the most recent capture whose revision differs from the current one: a capture at a new revision renames the prior `current.json` there, byte for byte, and a capture at an unchanged revision keeps `previous.json` as it is while it holds a capture at another revision. With no readable prior capture (the first one, or a `current.json` that is not an `ia-snapshot-1` capture, which the capture names and replaces), a `previous.json` at another revision is kept as the most recent capture there is; a `previous.json` at the new revision, or one that is no capture, is removed once `current.json` is written. The new bytes are staged in a temporary file in the same directory before either file is replaced, a failed step undoes the ones before it so the pair stays as it was, and a `current.json` that already holds the capture's bytes is not rewritten. The capture writes only under `.ia/work/snapshot/`, creating it when needed, and never touches `.ia/src`. The snapshot is local working state that each clone captures for itself: `ia init` takes the first capture once it has initialized a workspace, so a snapshot exists from then on, and its `.ia/.gitignore`, written only where none exists, lists `work/`, which keeps the snapshot out of version control. Concurrent captures of one root are last-writer-wins. The effect is reported apart from validation: `records`, and how each record's digest compares with the prior capture's `current.json`, as `changed`, `unchanged`, `new` (no row in the prior capture) and `removed` (a row in the prior capture and none now), so `records` is `changed + unchanged + new` and two captures with no edit between them report 0 changed. The first capture has nothing to compare with, so every record is `new`. Admission findings in a source the workspace authors are written into the snapshot and counted, and never stop the write: a capture whose admission has errors still writes, marks its effect line with a warning symbol and exits 1, as `validate` does (warnings alone exit 0). Unresolved references, colliding identities, unconsented rows and every other registration or resolution finding (such as a keyword two adopted or installed systems both register) are such findings wherever they are. Two cases refuse before anything is written, so both files stay as they were: a floor or seed input (a source under `.ia/src/floor/`, an installed package's or an adopted mount's) that fails to parse, which is a syntax error the language's scanner or parser reports (such as `IA-LANG-HEADER-MALFORMED`), refuses with that finding's own code, located at it, exit 3, and names `ia validate`; a root whose own `.ia/src` declares no `@workspace`, admitted or refused, is no workspace to capture and refuses as `IA-DB-ROOT-INVALID` (exit 3), naming `ia init <root>`, or `ia validate` when its own sources have errors. A `composition.sources` entry that names no root, and a path selection that selects nothing (an absolute, `./` or `..` selection, below), are each written as an `IA-COMP-FIELD-VALUE` warning at the line that states it, as `validate` reports them; admission does not change. With `--json` the result is `{version: 1, snapshot, format, revision, digest, records, changed, unchanged, new, removed, prior, ignored, previous, rotated, admission}`: `snapshot` is the absolute path of `current.json` and `digest` the SHA-256 of its bytes; `prior` is the revision of the prior capture the counts compare with, or null; `ignored` says why an existing `current.json` was not taken as one, or is null; `previous` is `{path, revision}` of the retained `previous.json`, or null; `rotated` says whether this capture moved the prior `current.json` there; and `admission` is `{status, errors, warnings, notEvaluated}`. A link or junction on the snapshot path, an entry at `.ia/work` or `.ia/work/snapshot` that is not a directory, or an entry at either snapshot path that is not a regular file, refuses as `IA-DB-PATH-UNSAFE` (exit 3) before anything is written, located at the entry that is not a directory or not a regular file (a link or junction is named in the message, the refusal located at the snapshot directory), and names the repair and then `ia capture` for that root. A write the system refuses for a permission, a busy or read-only entry, or an entry of the wrong kind is `IA-CLI-FAILED` (exit 3), located at what to make writable and naming that and then `ia capture`; any other system error, such as a full disk or an I/O error, is not the path's to repair and takes the generic next below. On Windows a rename of, or onto, a read-only or open snapshot file names that file; otherwise, and on every platform for creating the staged file or the snapshot directory, it names the directory whose entries the write creates, renames or removes. `--preview` admits the workspace and refuses exactly as a capture does, both refusals above and the snapshot path checks included, then reports what the capture would write (db SPEC D08b) and writes nothing: it creates no directory, and `current.json` and `previous.json` keep their bytes and modification times, so the retained previous snapshot that readiness compares against is not rotated away. Its human output says it is a preview and that nothing has been written, prints the capture's counts, the snapshot's digest and size and the rotation the capture would make, names every changed, new and removed identity in full under a `Changed`, `New` or `Removed` heading (a heading with none is left out), each list sorted and each identity printed with each terminal control character (C0, DEL or C1) as visible escape text, never as the control (a removed identity is read from the `current.json` on disk; `--json` carries each as it is), and ends by naming `ia capture` with `--root` as given, or `ia validate` when admission has errors. Its exit class is the capture's: 1 when admission has errors, else 0. With `--json` it is the capture's result with `preview: true` after `version` and `identities` after `rotated`, `{version: 1, preview: true, snapshot, format, revision, digest, records, changed, unchanged, new, removed, prior, ignored, previous, rotated, identities, admission}`: the snapshot fields describe what the capture would write (`snapshot` and `digest` the file and the SHA-256 of the bytes it would hold, `previous` the `previous.json` it would retain, `rotated` whether it would move `current.json` there), and `identities` is `{changed, new, removed}`, the identities the three counts count, each sorted. A snapshot path refusal names the repair and then the same `ia capture --preview`; a preview writes nothing, so a system error it meets reading the pair is never named as a path to make writable and takes the generic next below. A capture without `--preview` writes and reports exactly as above, with no new key. |
|
|
32
32
|
| `compile` | Removed in 3.0. Every invocation, including `--help` and legacy options, refuses as `IA-CLI-USAGE` (exit 2) before workspace discovery or mandate evaluation and names the static `ia capture --help` command. It is absent from command help and the catalog, but its token remains core-reserved so an extension cannot revive it. Replace calls with `ia capture`; retain supported options and drop `--force`. The old `--out` and `--stdout` have no equivalent because capture writes a fixed snapshot. Published `@inventarch/cli/internal/compile` helper signatures remain available; the CLI no longer calls `runCompile`. |
|
|
33
33
|
| `format [path...]` | Check formatting by default; rewrite with `--write`. |
|
|
34
34
|
| `inspect [identity]` | Show a workspace overview, or a record named by its full `system/kind/facet/name` identity or by `--path <file>`, and its relationships from the graph directed view: Edges, the rows a record declares in the spelling its author wrote; Derived inverses, its counterparts' declarations read from its side in the kernel's spelling and labeled `derived`; and Field references, the typed field references it holds or is named by, labeled `derived`. Each edge row shows its direction, depth and `declared by source` or `declared by target`, its fragment on the record it addresses (beside a declared row's counterpart, as `at #<fragment>` on a derived one) and its condition as `when` terms, and a row past depth 1 names the nearer record whose view holds it. `--edges` (`in`, `out` or `both`; default `out`) selects the direction of edges and field references, and `--depth` (0 to 3; default 1) bounds the traversal; field references are listed at depth 1 only, and at depth 0, where nothing is read, each section says none is listed at that depth. With `--json`, each record carries its per-record `digest`, `edges` lists the walk's relationships, `referencedBy` (with `--edges in` or `both`) the inbound field references, and `directed` the listed rows with their `identity`, `depth`, `kind`, `derived`, `declaredOn` and spelling or field; depth 1 of `directed` is the record's own view, so it also lists a self-relation, which the walk and therefore `edges` omit. An identity or `--path` no admitted record answers refuses as `IA-DB-SOURCE-UNAVAILABLE` (exit 1) and names `ia validate` when admission refused that identity or a record of that source, else, for an identity, the inspection of the nearest admitted identity when one is near, else the overview. |
|
|
35
|
-
| `read <locator>` | Print the body behind a locator (
|
|
36
|
-
| `position` | Print the position body for a scope key
|
|
37
|
-
| `next` | Print one plan's delivery view (
|
|
38
|
-
| `project <claude\|codex>` |
|
|
35
|
+
| `read <locator>` | Print the body behind a locator (runtime SPEC, body reader): text and its digest, never a certification. A locator is a record's full `system/kind/facet/name` identity; that identity with `#<phase>/<Primitive>` for the text of the record's cells at that address (a playbook's step) or `#<REQ-ID>` for one requirement's text; or `<path>:<line>`, the last colon splitting the path from a positive line, for the innermost admitted record whose source span holds that line of a workspace source. A cell or requirement locator reads that text, never a document. Otherwise a record whose word carries a source locator, and which states it, reads the document it names: `work.source` on `@spec`, `@plan`, `@milestone`, `@task` and `@decision`, `reference.document` on `@authoring-guide` and `template.resource` on `@template`. The path is read relative to the tree holding the record's source: the workspace root for the workspace's own `.ia/src`, a package's or an installed store's directory, and for an adopted mount the directory `.ia/workspace.json` binds it to, whose documents its revision pin does not cover. It is read through the workspace file reader `capture` uses, which refuses a path through a link or junction, a missing, non-regular or hard-linked file, a name that is not portable and a file over 4 MiB. A source locator `<path>#<anchor>` on a markdown file (`.md` or `.markdown`, in any case) reads only the section from the ATX heading whose anchor is `<anchor>` to the next heading of the same or a higher level, headings in fenced code ignored. The anchor is GitHub's for a plain-text heading (a repeated heading takes `-1`, `-2` and so on in document order, and a leading byte order mark is not part of the first heading); underscore emphasis, entity and character references, inline HTML and reference links are not rendered first, so such a heading may have another anchor on GitHub, and setext headings and headings in list items or block quotes are not read. Any other record reads its own body: its `meaning.says` (a `@system`'s head `describes`; a `@schema`, which states neither, has an empty body). Sections, fields and relationships stay in `inspect`. The output names `record` or `document` with the document's path, the SHA-256 of the body's UTF-8 bytes and the line `body not certified by this read`, the identity, locator and path printed with each terminal control character as visible escape text, then prints the body as read, byte for byte, terminal control characters included: the body is the source's own text, which `--json` carries as JSON escapes it; with `--json` it is `{version: 1, locator, identity, kind, path, digest, body, certified: false}`, where `locator` is the locator as given, `kind` is `record` or `document`, `path` is present for a document only and `digest` is the full SHA-256. A read opens the workspace without the db cache and writes nothing. A malformed locator refuses with `IA-CLI-USAGE` (exit 2) before anything is read and names `ia read --help`. The other refusals carry the runtime's codes: a locator no admitted record answers is `IA-RUNTIME-READ-UNADMITTED` (exit 1). For an identity a source holds whose record admission refused it reads `in this workspace's sources, but admission refused it` and names `ia validate`; for one no source holds it reads `not in this workspace's sources` and names the read of the nearest admitted identity when one is near, as `ia inspect` names the inspection, else `ia inspect` for the overview; for a line it names what the file holds: a source whose records admission refused names `ia validate`, a source whose admitted records span other lines names `ia inspect --path <file>`, and a file with no record of the workspace's sources names the overview. A cell or requirement the record lacks is `IA-RUNTIME-READ-FRAGMENT` (exit 1), naming `ia inspect <identity>`; a document path that names no file or is outside the workspace or the record's tree, a URL, which a read never fetches, a file the reader refuses or cannot find, bytes that are not UTF-8, an anchor on a file that is not markdown and an anchor no heading has are `IA-RUNTIME-READ-UNREACHABLE` (exit 3), naming `ia inspect <identity>`, which locates the record whose locator needs the repair (and the file to restore, when there is one); and a record at runtime placement (band 0) is `IA-RUNTIME-READ-PLACEMENT` (exit 3) unless `--include-runtime` is given, naming the same read with that flag. The workspace session this release opens admits no source at runtime placement, so through `ia read` the flag changes nothing yet. The `<path>` of `<path>:<line>` is relative to the workspace root, as every source path the toolchain names is; an absolute path inside the root is read as the root-relative path it names, by the rule `position --seat` reads a location with (runtime `rootRelative`): an in-root name that only begins with `..`, such as `..cache`, is inside the root, and the root itself reads as `.`, the workspace root, which is a directory and no source; any other path names no admitted record. These refusals name the `ia inspect` and `ia validate` commands above, which locate the record or the finding, rather than `ia scope --seat <qname> --shape context`. |
|
|
36
|
+
| `position` | Print the position body for a scope key: the runtime's `position` through the whole-workspace scope (runtime SPEC R14 to R17), as the consumer verb beside the frozen `ia scope` route, never a machine route. The key is K = (seat, shape, phase, depth, budget, word), read from `--seat <id\|path>`, `--shape <H>`, `--phase <P>`, `--depth <d>`, `--budget <n>` and `--word <w>` only, so no request text reaches it: no flag is K0, the repository's `@workspace` at shape context, phase orient, depth 0 and budget 0, its pointers and tallies only; a key naming any part takes the runtime's defaults for the rest (context, the anchor phase of the shape's primitive, depth 1, budget 16). A `--seat` that spells a canonical `system/kind/facet/name` identity is that record; any other is a location, a workspace-relative path or an absolute one inside the root, read by the rule `read` reads a line locator's path with (the root itself is the workspace root), and `./` makes a path spelled as an identity a location. A depth or budget of digits is that number; the closed sets and caps are the runtime's. The output is the seat with the body's revision; the key used, the capture's freshness (`current`, `stale` or `no-capture`: a position needs no capture; `stale` names `ia capture`, with `--root` as given, as the command that captures this revision), the body's digest and its counts; the loaded records, the pointers and their tallies past 48, the rules and playbooks that apply by word (a field match, not a row) with their tallies, the playbook cells, the blocking rules reserved outside the budget, the mandates, the frontier tallies and the unknowns, each record with its word, owner system, band, hop, how it was first reached and its owner system's steward; and the two widening keys as commands with `--root` as given: `ia position` one hop deeper, every part spelled (absent at depth 2), and the re-seat template `ia position --seat <identity> …` at depth 1 and budget 16, for any pointer or applies-by-word entry. `--word` restricts what loads, the pointers, their tallies and the frontier to records of that word, and never the reserved rules, the applies-by-word section, its cells or the mandates (runtime SPEC R15 and R17), so a word hides no blocking rule. Every string of the human output, what a source authored included (a cell's text, a finding's message, identities and paths), is printed with each terminal control character (C0, DEL or C1) as visible escape text, never as the control, as `ia next` prints its report; colour adds only the renderer's own styling. With `--json` it is `{version: 1, ok: true, body, digest, hostNote}`, the Door's `position` result byte for byte. A position exits 0, opens the workspace without the db cache and writes nothing. The refusals carry the runtime's code, `IA-RUNTIME-REQUEST-INVALID`, and its message, and each names one command, with `--root` as given where that command takes one: a shape or phase outside its closed set, or a depth or budget outside its cap, is refused before the workspace is read, at exit 2, naming this call again with the closed set (`<context\|governance\|execution\|sequence\|learning>` or `<orient\|plan\|act\|learn>`) or the cap (2 or 64) in that part's place; a word the closure does not register (exit 1, the message listing those it does) names `ia vocabulary`, which opens no workspace and so takes no `--root`; and a seat the workspace does not admit, a path outside it and a seat at runtime placement (exit 1, located at the workspace with a seat identity as identity) name `ia position`, K0, except a runtime-placed seat that is the repository's own `@workspace`, which names `ia inspect`. |
|
|
37
|
+
| `next` | Print one plan's delivery view (runtime SPEC R18), computed per read and never stored. The plan is the one `--seat` names: a `@plan`, or the plan a `@milestone`'s `work.plan` names, or that of a `@task`'s `work.milestone`; without `--seat`, the only `@plan` the workspace authors (band 100). The view is the runtime's `deliveryView` through the whole-workspace scope (runtime SPEC R18): the plan, its revision and a summary of how many tasks have exit evidence and which is next; its milestones, each satisfied or not with the reason (its own exit evidence, or every task's) and its status as self-declared; its tasks in one prerequisites-first order (a task follows the tasks and milestones it and its milestone require, ties by milestone, then task), each with its verdict line, `exit evidence recorded (<observation>, evaluator <evaluator>[, self-attributed | , self-attribution unknown])`, `no declared blocker` or `blocked (<basis>; …)`, its `work.status` printed as self-declared and never a basis, one `requires` line per effective prerequisite with its basis, and its five state lines (intent, definition, realizable, realized, worked); the review items with their owner; and, when a task has no declared blocker, the command the view names for it, `ia position --seat <task> --shape sequence`, with `--root` as given. Exit evidence is a success `@observation` on the task whose `subject-revision` is its current digest; a task's own status is never evidence, so a plan whose tasks are `closed` with no observation prints each `status closed (self-declared)` and a task that requires one `blocked (task <t>: no exit evidence)`, which is the honest answer. A relation row that carries a condition, such as `requires @task guide when phase is act`, counts only where it holds at the coordinate the scope binds, decided as graph traversal decides it (runtime SPEC R18): the record that states the row decides its provenance and artifact-set terms, and a severity term only where its own severity decides it at every coordinate, while a term on an axis the scope binds no value for, the phase on the whole-workspace scope `ia next` reads and the severity on every scope, leaves the row conditional with an unknown basis, never met; a row whose condition fails is no row. The Door's `next` decides a phase term through a token bound to a phase. With `--json` it is `{version: 1, ok: true, view}`, `view` being the Door's `next` result byte for byte. A view exits 0, whatever its verdicts and review items. The workspace opens without the db cache and nothing is written. The refusals carry the runtime's codes and messages at exit 1, located at the workspace with the seat as identity, and each names one command with `--root` as given: IA-RUNTIME-NEXT-SEAT for a seat the workspace does not admit names `ia validate` for a record admission refused, else, as `ia inspect` names the nearest admitted identity, `ia next --seat <nearest>` for the nearest admitted `@plan`, `@milestone` or `@task` when one is near, else the view without a seat, and for a record that is no `@plan`, `@milestone` or `@task` names `ia position --seat <seat>`, as the runtime does; the view without a seat is `ia next` when the workspace authors one `@plan` at band 100, `ia next --seat <the first>` when it authors several, and with none what IA-RUNTIME-NEXT-NO-PLAN names without a seat; IA-RUNTIME-NEXT-NO-PLAN names `ia validate` when admission refused a `@plan` a source holds (without a seat, any `@plan`; with one, the `@milestone` a `@task` seat's `work.milestone` names, or the `@plan` that `work.plan` names on its milestone or on a `@milestone` seat), else, without a seat in a workspace that registers `@plan`, `ia preview plan` where the acting participant's profile allows Verification and `@plan` (else the governance position), else the records to author, then `ia next` again with the seat given; IA-RUNTIME-NEXT-AMBIGUOUS, the plans listed in the message, names `ia next --seat <the first>`; and IA-RUNTIME-NEXT-CYCLE, the require rows listed in the message and the refusal located at the first, names `ia position --seat <record> --shape sequence` at the record the runtime names, the cycle's first task by milestone then task, else the first milestone a row requires. `ia next --help`, which the runtime's IA-RUNTIME-NEXT-NO-PLAN names to Door and MCP callers, says under `--seat` which records make a plan. It is the Door's `next` operation as a consumer verb, never a machine route. |
|
|
38
|
+
| `project <claude\|codex>` | With `--product plugin`, render the host plugin a lowered workspace describes instead (see [Host plugins](#host-plugins)); without it, `--out`, `--check` and `--compare` are usage (`IA-CLI-USAGE`, exit 2), refused before anything is read and naming the `--product plugin --check` form. Otherwise, plan, or with `--apply` write, the workspace projection alone (2026-10-09; runtime SPEC R19 and R20): the position packet of the admitted records rendered by the host's adapter for the consumer target, the files the workspace projection below describes. It plans by default, as `host` does, and the plan writes nothing, the IA home included: the packet's entry count (runtime R19's `entryCount`, 37 on a fresh init) and digest, the file plan (`create`, `update`, `unchanged`, `remove` for an owned and marked 1.x steward file, `foreign` for any other `.claude/agents/*.md` file, left in place) and the steward-guard retirement (`guard: 'retire'`), planned by the same `projectionElement` as `host`'s projection element. `--apply` plans again (`replanProjection`, shared with `host --apply`) with the rendering its gated plan session made, writes it through `applyHostProjection`, and prints the receipt: its files with their SHA-256, the legacy files removed, the foreign files and the retirement. A file changed since the plan still refuses, but a source or mandate change made while the confirmation question waits is not picked up, and `ia doctor` then reports the projection outdated. It registers no MCP server and no hook, and needs no capture, because the packet reads the live revision. With `--json` it prints `{version: 1, command: 'project', root, host, apply, plan: {entries, packetDigest, files, guard, conflict}, applied?}`, `applied` being the receipt written; with a conflict `files` is empty and `guard` null, because the apply refuses it and so writes and retires nothing. A file without the generated marker at a path the adapter writes, an owned file or guard group changed by hand, or an ownership state that cannot be read makes a successful plan that names the file and its repair (`conflict: {code, path, reason}`), and `--apply` refuses it with that code, located at the file, before it asks anything or writes, naming the repair, then `ia project <host>`. A host other than `claude` or `codex` is `IA-CLI-USAGE` (exit 2) before anything is read, naming `ia project claude`, and a root without `.ia/release.json` is `IA-CLI-CONFLICT` naming `ia init` of the root as given. The `ia project`, `ia validate` and `ia init` commands a next action names carry the root as given; a pending host journal (`IA-DIST-RECOVERY-REQUIRED`, plan and apply) or a host lock held at apply (`IA-DIST-INSTALL-BUSY`) names its `ia-distribution` recovery with the resolved root, which `ia-distribution` requires to be absolute, as `host` does, and a workspace whose sources cannot be opened names the resolved root, as every workspace verb does. |
|
|
39
39
|
| `vocabulary [word]` | Read the catalogue shipped with the package, including schemas (`--schema`) and worked examples (`--example`); `--domain`, `--kind` and `--search` filter it. No workspace is opened, so `--root` is refused. |
|
|
40
40
|
|
|
41
41
|
Workspace discovery uses the nearest ancestor containing `.ia/src`, with `--root` selecting an explicit root where supported. Native syntax is `#! ia 1.0`. Initialization writes the three starter records, an ignore file and the release descriptor, installs the pinned bundled language base, `inventarch/language`, at the coordinated release artifact version, supplying the eleven public systems while retaining IA syntax 1.0, and captures the workspace; `--system` adds a consumer-local system and its distribution, and `--migrate` rewrites a 1.1.0 starter into this shape. A new consumer distribution starts at its own 0.1.0 version, independently of the CLI version.
|
|
42
42
|
|
|
43
|
+
## Host plugins
|
|
44
|
+
|
|
45
|
+
Host authoring (2026-10-14): a Claude, Codex or Grok plugin directory lowers into records, and a lowered workspace renders back into a plugin, with a check that the round trip is content-exact and a fixed point. The modules are workspace-runtime's `./internal/host-plugin` (inventory, frontmatter, lowering, manifests, comparison) and `./internal/generate`'s `renderPlugin` (workspace-runtime SPEC W05 and W06); `src/init.ts`, `src/plugin-sources.ts`, `src/plugin-product.ts` and `src/project.ts` hold the commands.
|
|
46
|
+
|
|
47
|
+
- `ia init [<directory>] --from <plugin-directory> [--id <provider/name>] [--apply] [--json] [--yes]` reads the plugin, relative to the directory the command runs in, and lowers it into the new workspace as a kit: the three starter records, then the system `<name>` (its `system.ia` requiring `agent-composition-system`, `agent-system`, `compliance-system`, `learning-system` and `workspace-system`, sorted, so authored trigger `@contract` and `@case` records and the `@observation` records of trigger evaluations can live beside the lowered ones, in the one system `--check` admits), `records/plugin.ia` (the product `@distribution`, one `@capability` per skill, and an `@agent`, a tools `@capability` and an `@agent-profile` per agent), every skill body, agent prompt and owned Markdown file byte for byte as a resource pinned in `.ia/authoring.resources.json`, every other file byte for byte as an asset under `assets/plugin/`, and `assets/lowering-map.json` (`ia.lowering-map.v1`) with `assets/MIGRATION.md` generated from it, giving every file and every frontmatter key one disposition. It plans by default and writes with `--apply`. `--from` conflicts with `--migrate`, `--adopt`, `--system` and the decline options. Lowering accepts only what `ia project --product plugin` writes back: an agent's `tools` must be one string whose `split(', ')` rejoins to exactly the original (a list, `Read,Grep` or a padded member is unresolved); each manifest must equal, by content, the manifest the renderer builds from the lowered product (`pluginManifest`), except that a Codex manifest may leave out the empty hook map; an explicit `disable-model-invocation: false` is unresolved, and its reason says to remove the key, because the renderer omits the default. The descriptor's `license` stays `UNLICENSED`, whatever the plugin's manifest states: the licence guard belongs to packing. The plan's apply command, the rerun an interruption names and the conflict refusal's next all carry `--from <plugin-directory>` as typed, so none of them initializes a plain starter instead. A target that is the plugin directory or lies inside it is refused before the plugin is read; a target that contains the plugin is legal.
|
|
48
|
+
- `ia project <claude|codex> --product plugin --out <directory> [--apply] [--json] [--yes]` renders the plugin into an absent or empty directory outside the workspace, create-only, after verifying each pinned resource; it plans by default. One plugin carries every host its product's `product.hosts` lists; the positional must still be `claude` or `codex`. Resources and assets are read only through real directories below the workspace root.
|
|
49
|
+
- `ia project <claude|codex> --product plugin --check [--compare <plugin-directory>] [--json]` renders in memory, compares each file with the original when `--compare` names it (identical, ruled by a named rule from `DIFF_RULES`, or drift, missing or extra), lowers the rendered plugin again and requires every lowered file, and nothing else under the plugin resources and assets, to match the workspace byte for byte (the fixed point). It writes nothing. `--compare` without `--check` is usage.
|
|
50
|
+
|
|
51
|
+
| Code | Exit | Meaning | Next |
|
|
52
|
+
| --- | --- | --- | --- |
|
|
53
|
+
| `IA-LOWER-UNRESOLVED` | 1 | `init --from`: the plugin holds a construct this version of ia cannot lower and render back exactly. The message counts them and lists the first 20; `details` lists every entry. Nothing is planned or written. | `ia init --help`, for what a plugin directory may hold. |
|
|
54
|
+
| `IA-PLUGIN-INPUT` | 1 | `init --from`: the plugin is not a directory, holds a link, a `.git` or `node_modules` entry in any letter case, a non-regular file or a manifest that is not a JSON object, or exceeds 1,000 files or 16 MiB; the workspace name is not a portable system name; or the target is the plugin directory or inside it. `project --product plugin`: the `--compare` directory does not exist or cannot be read as a plugin, or a resource or asset path has a link or junction on a segment below the workspace root. | For the target, choose a directory outside the plugin and run `ia init <directory> --from <plugin>`; otherwise `ia init --help`. For a `--compare` directory that does not exist, choose an existing plugin directory to compare with and run `ia project <host> --product plugin --check --compare <dir> --root <root>`; for any other `project` input, remove the entry or replace the link the message names, then run the same check, keeping `--compare` when it was given. |
|
|
55
|
+
| `IA-PLUGIN-PRODUCT` | 1 | `project --product plugin`: the workspace does not hold exactly one system under `.ia/src/systems` (`--check`), does not author exactly one product `@distribution`, its `product.hosts` names no host, its authoring manifest or release descriptor is missing or not JSON, a pinned or asset path escapes it, an output path is not portable, two sources render one path, or a skill or agent lacks exactly one inline body. Nothing is written. | `ia init --help`, to lower the plugin again from its source. |
|
|
56
|
+
| `IA-PROJECT-FEATURE` | 1 | `project --product plugin`: a record asks for what this version of ia does not render, such as a delegated skill or agent, or an agent profile whose capabilities allow no host tool. | `ia project <host> --product plugin --check --root <root>`. |
|
|
57
|
+
| `IA-RESOURCE-DIGEST` | 1 | `project --product plugin`: a pinned resource's size or SHA-256 differs from `.ia/authoring.resources.json`. Nothing is written. | `ia init --help`, to lower the plugin again from its source. |
|
|
58
|
+
| `IA-ROUNDTRIP-DRIFT` | 1 | `project --product plugin --check`: "N drifted, M fixed-point mismatches, K unresolved.", then the files and the unresolved entries, each list capped at 20; `details` holds the whole report (`compared`, `diffs`, `drift`, `fixedPoint`, `unresolved`). | Without `--json`, the same check with `--json` for the full report; with `--json`, the report is in `details`, and the same check without `--json` once each named file is corrected. |
|
|
59
|
+
| `IA-PLUGIN-OUT` | 1 | `project --product plugin --out`: the directory is a file, is not empty, or is the workspace, lies inside it (a name such as `..x` below the root is inside) or contains it. Containment is judged on the volume's own paths: the nearest existing ancestor of `--out` and the root are each resolved through links and junctions first, so an `--out` reached through a link into the workspace is inside it. Judged for the plan as well as the apply. | `ia project --help`, and an absent or empty directory outside the workspace. |
|
|
60
|
+
| `IA-CLI-USAGE` | 2 | `project`: `--out`, `--check` or `--compare` without `--product plugin`; with it, a host other than `claude` or `codex`, `--compare` without `--check`, or neither `--out` nor `--check`. Refused before anything is read. | The `--product plugin --check` form of the same command. |
|
|
61
|
+
|
|
62
|
+
`tests/host-plugin.test.ts` pins the invocation and product sections, lowering and rendering the public sample fixture (`tools/projections/fixtures/host-plugin/sample`) byte for byte, the check against it, an invariant over fixture variants (every variant that lowers with no unresolved entry checks to identical or ruled files only, and list-form tools, tools without spaces, an explicit default, a Codex interface without `displayName` and a Codex manifest without `interface` are refused at lowering), authored trigger `@contract`, `@case` and `@observation` records beside the lowered sample that admit and keep the check passing, and each refusal above.
|
|
63
|
+
|
|
43
64
|
## Distribution commands
|
|
44
65
|
|
|
45
|
-
`pack --descriptor <file>` writes a digest-named archive, by default under `.ia/work/dist`. A release descriptor, as the database decodes it, that names no `distribution`, which a default `init` writes
|
|
66
|
+
`pack --descriptor <file>` writes a digest-named archive, by default under `.ia/work/dist`. A release descriptor, as the database decodes it, that names no `distribution`, which a default `init` writes, is refused as `IA-CLI-CONFLICT` (exit 3), located at the descriptor, before the packer reads anything else, naming `ia vocabulary distribution`: a release needs a `@distribution` in a system folder whose identity the descriptor names, which `init --system` authors; a file that is no release descriptor is left to the packer's own refusal. `install`, `update` and `remove` preview a plan and apply it only with `--apply`; `--plan-out <file>` keeps the plan under `.ia/work/`. `restore --apply` reinstalls the locked generation from pinned archives; it has no preview, and `--allow-withdrawn` accepts a withdrawn release. Catalog, offline-cache and configured registry sources are explicit options. The native package IDs and versions in these commands are separate from npm package names and the CLI version.
|
|
46
67
|
|
|
47
|
-
`host <claude|codex|cursor>` previews a workspace registration and requires `--apply` to write it; `--remove` plans removal of the host set it owns. A workspace `--apply` writes the projection `ia project --apply` writes, so it is gated as the effect mode (Execution) by the acting participant's mandate profile before its confirmation, and takes `--actor <agent>`; its plan, `--remove` (which restores editing) and `--user` are not gated
|
|
68
|
+
`host <claude|codex|cursor>` previews a workspace registration and requires `--apply` to write it; `--remove` plans removal of the host set it owns. A workspace `--apply` writes the projection `ia project --apply` writes, so it is gated as the effect mode (Execution) by the acting participant's mandate profile before its confirmation, and takes `--actor <agent>`; its plan, `--remove` (which restores editing) and `--user` are not gated. For Claude, `--context <identity>` selects the lifecycle context element of a workspace registration, and `host claude --user` registers a user-level plugin that needs no workspace. `doctor` observes runtime, workspace, install and host state without repairing it or treating a written registration as an answering server; `--host` adds that host's session briefing and next actions. Unknown update or host observations stay unknown.
|
|
48
69
|
|
|
49
|
-
Installed implementations
|
|
70
|
+
Installed implementations: `host <claude|codex> --apply`, `init --host` included, reads the join receipts before it writes anything, refusing ones it cannot read with the repair of deleting them, and once every element is applied records the host's join from the committed registration and the catalog of the payload it names; a removal drops it. A failure while recording names the rerun that finishes the set, so an interrupted apply leaves no join or the previous one. `doctor` adds an `implementations` row for the catalog of the payload this installation pins (`ok` present, `warn` when it lists an unavailable or revoked operation, `info` when the payload carries none or is not materialized, `fail` when the payload fails verification), a `join-<host>` row per recorded join, compared through the trust `validate` binds with: `ok` when it names the catalog of the payload this installation pins in the IA home and the host's registration names exactly that payload, `warn` when drifted, when the registration names another release or another directory (or another spelling of it, which is never opened) or the host is not registered, `unknown` when that payload cannot be read or verified or the installation pins none, an `info` row for a registered host with no join and a `fail` row for receipts that cannot be read; one verification of each payload serves its host, catalog and join rows, and doctor writes nothing. Nothing in this release executes or serves an operation.
|
|
50
71
|
|
|
51
|
-
Execution bindings
|
|
72
|
+
Execution bindings: `validate` reports, from the same `WorkspaceSession.bindings(trust)` service `ia-distribution validate` reports, the catalog the workspace's host joined through this installation's own payload (`validationTrust`: the release its bundled host pin names, in the IA home `IA_HOME`/`IA_HOST_HOME` resolves; run from inside a payload, that payload; a registration of any other payload is unavailable with the repair `ia host <host> --apply`) and one result per `@execution-binding`: `bound`, `unavailable` (never a pass, and said so in the summary) or `revoked` (an error that fails the run). `--json` adds `bindings`; with no binding the human report is unchanged. Computing them writes nothing and executes nothing. Each binding is one entry: its identity, then its result and its reason on lines of their own. A run that fails only because a binding or check is revoked closes with the repair: deleting the payload that failed verification and re-applying the host that joined it, or replacing what the catalog revokes.
|
|
52
73
|
|
|
53
|
-
Checks and evidence
|
|
74
|
+
Checks and evidence: `validate` opens its session with structural check admission and reads no evidence, so its findings, counts, checks, exit and `revision` are the authored view's alone and `revision` is the one every other reader reports, with `authoredRevision` beside it in `--json`; a check naming an evaluator that is not built in is admitted, reported and bound rather than refused (every strict reader, which is every other reader but `preview` and `author`, counts it as an IA-COMP-CHECK-UNKNOWN error, so `ia host` and `ia project` refuse the workspace with IA-CLI-CONFLICT (exit 3) and `ia capture` still writes its snapshot with the finding recorded and exits 1; the summary says so, naming each such check so that refusal or finding has a place to land), and reports from the same `WorkspaceSession.checks(trust)` service `ia-distribution validate` reports a Checks section: the catalog source when a check needs one, one entry per check with its evaluator, `bound`, `unavailable` or `revoked`, its outcome (`pass`, `fail` or `not-evaluated`) and its reason, then the evidence it recorded. A not-evaluated check is never a pass and is counted in the summary; a revoked check is an error that exits 1, and the closing names the repair: removing or replacing a check that `validate`, `preview` and `author` admit but every strict reader counts as an error, before re-applying the host, or a check whose evaluator the catalog revokes. With admission refused nothing is recorded or pruned, and an older file it may not remove never refuses the run. `validate` trusts the payload its bundled pin names in the IA home, `ia-distribution validate` only the payload it runs from. It then records the bound checks that passed or failed through `recordValidation`, the one evidence write any command makes: `.ia/work/evidence/<authored revision>.ia`, runtime placement band 0, which moves `revision` but never the authored revision, the position packet or the host projection. `--json` adds `checks` and `evidence`; with no check the human report is unchanged. A directory it cannot write refuses as IA-DIST-EVIDENCE-UNWRITABLE (exit 3) with the repair, and a link, junction or file on the way as IA-DB-PATH-UNSAFE; nothing is read through one, and with nothing to record neither refuses. `doctor`, `capture --preview` and refused effects never create or prune evidence.
|
|
54
75
|
|
|
55
|
-
The workspace projection (2026-10-09
|
|
76
|
+
The workspace projection (2026-10-09) is the position packet of the workspace's admitted records (runtime SPEC R19), with the command catalog `packetCatalog` builds, rendered by the runtime's adapter for the consumer target (R20): `.claude/rules/ia-workspace.md` and `.claude/skills/ia-authoring/SKILL.md` for Claude, `AGENTS.md` and `.agents/skills/ia-authoring/SKILL.md` for Codex, each carrying `<!-- Generated by ia project; edit the cited native records. -->`. No per-system steward agent is rendered, and `ia host` plans the elements `mcp`, `context` and `projection`: it registers no steward guard, which with no steward subagent left would deny every edit under `.ia/src/systems/<name>/`; the guard it registers instead is one group per authored `@hook` (the generated set, below), which decides only the edits that hook selects. `applyHostProjection` in `src/host-projection.ts` is the only writer of projection files; `ia host --apply`, `ia host --remove --apply`, `ia project --apply`, the project effect of `ia init --host` and `ia init --migrate --apply`, and the install, update and remove refresh call it. It refuses while a host journal is pending, plans the guard retirement and the file plan before writing anything, then removes a steward-guard registration an earlier release made (its group in `.claude/settings.local.json` and `claude-guard-workspace.json`, through apps/distribution's guard registration) before any projection file changes, applies the files through apps/distribution, which deletes each 1.x steward file its state owns and marked (either 1.x marker is owned) and lists every other `.claude/agents/*.md` file `foreign`, left in place, and last writes the receipt `.ia/distributions/hosts/<host>-receipt.json` beside the projection state, having deleted the previous one under the host lock before any projection file changed, so an interrupted apply leaves no receipt: the adapter's receipt with `cli` (`@inventarch/cli@<version>`), `removed` (the legacy files deleted, each with its SHA-256), `foreign`, `guard` (`retired` or `none`) and `writtenAt`. A removal deletes the receipt. The plan's `projection` element lists the retirement as `guard: 'retire'` and each file action, `remove` and `foreign` included, and is an update when its files are unchanged but a retirement is planned or the receipt is missing; an applied `projection` element reports `guard: 'retired'` or `none`, and the human report says the guard was retired. An install, update or remove plan lists the registered hosts whose refresh retires a guard as `retire`, and its human plan, the summary an apply confirms, says so beside the refresh line with the note on what that leaves unblocked; after the apply it lists the hosts it retired a guard for as `retired`. A guard group changed by hand refuses, located at `.claude/settings.local.json`, naming its deletion, and an install refuses that before anything is acquired, as it refuses a hand-edited projection file. `doctor`'s projection rows read the receipt: a listed file missing (`warn`) or changed (`fail`), the receipt's packet digest against a fresh render (`outdated`, `warn`; a render that fails is `unknown`, naming `ia validate`), with none of these, one `ok` row saying the projection has no drift, and one `info` row listing the files the last apply removed and the foreign ones it left, which are not checked; a projection with no receipt, a 1.x registration or an interrupted apply included, is `unknown`, and `ia host <host> --apply` writes one; a receipt that cannot be read, is not exact UTF-8 or lacks a field doctor checks is a `fail` row at its path naming its deletion. A 1.x guard group changed by hand is reported with `ia host`'s repair: delete the group, then run `ia host claude --apply`. A projection `ia project` wrote without a host registration has the same rows, after the registered hosts' rows or, when none is registered, after the `Host` row, and each remedy, like an install, update or remove refusal for that projection, names `ia project <host> --apply` (`projectionRerun`), because `ia host` would also register an MCP server; the `--host` briefing reports such a host as not registered, never stale. The 1.x `ia host` marker and projection state stay readable, so an upgraded workspace's next apply replaces its files in place.
|
|
56
77
|
|
|
57
|
-
The generated set (2026-10-11
|
|
78
|
+
The generated set (2026-10-11): `renderProjectionFor` holds the packet and workspace-runtime's `generateHostSet`, computed once from the workspace's authored records: the generated agent files (Claude only) and skills after the packet's files, each with the packet marker; the `@hook` declarations (Claude only); and a receipt whose `files` list every file, `generated` each generated file with its record identity, word and SHA-256, `definitions` the `@operation` and `@harness` definitions (an operation's handler and validator ids copied as authored, never resolved or run), each harness's registrations, in the receipt an apply writes, being those that apply wrote and registered (a hook it registered no group for is left out), and `unsupported` each authored record the host does not take, with the reason (for Codex every agent profile and every hook). A generation refusal (workspace-runtime's `ProjectionError`) is a refusal with its own code, located at the workspace root, whose next action is to correct the record the message names and run `ia validate`. `applyHostProjection` applies exactly that set: it plans the guard retirement, the hook groups and the files before writing anything, then retires a 1.x steward guard, then registers or removes the hook groups through apps/distribution's hook registration (planned again after a retirement, which rewrote the settings the first plan read), then applies the files, then writes the receipt, whose `hooks` lists each owned group by identity with the tools its hook declares and the group's SHA-256, and `removedHooks` each group it removed, by identity and the digest the ownership state recorded for it; the pending receipt evidence written before the groups change carries the removals too (as `removedHooks`, only when there are any), so a rerun after an interrupted apply still lists them. The groups run the guard in the payload `ia host` (and `ia init --host`) materialized and verified; `ia project`, the install, update and remove refresh and a migration keep the groups an earlier `ia host` registration owns in step with the records against the payload that registration recorded, writing no group and never reading that payload while the owned hooks and selections are the declared ones (a change with that payload gone or changed refuses there, naming `ia host claude --apply`, which materializes one), and with no registration register none, listing each declared hook in `unsupported` as needing `ia host claude --apply`. Where `disableAllHooks: true` turns hooks off (`.claude/settings.local.json`, else `.claude/settings.json`), no group is written: a group already owned for a hook still declared stays registered and is listed only in `hooks`; an obsolete owned group is removed (planned against the payload an `ia host` apply materializes when that is the payload the kept groups were registered against, so its preview and apply agree), except that when that payload is gone and the apply does not materialize it, the group stays, listed in `unsupported` as kept (`HOOK_KEPT`) and never as registered, until hooks are back on or that payload is materialized again; a group changed or duplicated by hand refuses as it does with hooks on, and so does one deleted by hand whose hook is still declared, while a deleted group of a hook no longer declared loses its ownership in the next plan that runs, which, with the payload gone and not materialized, waits as the kept groups do, doctor reporting the group missing meanwhile; an identity both generation and the hook step report (an unsupported authored hook whose group is kept) is one `unsupported` row carrying both reasons; and a declared hook with no group is listed in `unsupported` naming that file, while the MCP entry, the packet, the agents and the skills apply as before. A generated skill refused at a folder that already holds the user's files is located at that folder, and the refusal names its repair (`folderRepair`): move the files out, or rename the `@playbook`, then rerun. A record renamed or deleted takes its obsolete agent file, skill or group away on the next apply; unrelated settings keys, groups and unmarked files are kept. A removal removes every owned group; it renders nothing and reads no record, so `ia host <host> --remove --apply` needs neither an admitting workspace nor records that open, which is why the guard names it to restore editing. Ownership stays in the projection state and the hook ownership state, never the receipt. The `projection` element of `ia host` and `ia project` lists each hook group's action (`create`, `update`, `unchanged` or `remove`) and each record not taken. `doctor` adds one row per owned hook group that drifted: `missing` (deleted by hand) or `modified` (changed or duplicated) is a `fail` whose remedy is `ia host claude --remove --apply`, after which `ia host claude --apply` registers the workspace's hooks again, since apply never puts back on its own a group the user took away; an apply or plan of `ia host` or `ia project` that finds such a group refuses, located at `.claude/settings.local.json`, naming the same recovery (`hookRepair`: delete a changed or duplicated group first, then `ia host claude --remove --apply`, then register again with `ia host`), and an unreadable hook ownership state names itself and the groups it owns before the rerun (`stateRepair`); an install, update or remove plans the refresh's files and hook step against the current render before its first install write (`preflightProjection`), and a migration checks the hook step before it plans (`preflightHooks`), so such a group, a recorded payload a change of hooks would need, or a generated skill refused at a populated folder of the user's refuses there with its repair rather than after the install commits (any other file refusal stays the refresh's, after the commit, naming the applied install), and the install preview lists the refresh's files from the current render, so a generated agent is never previewed as a 1.x removal; `foreign` is a `warn`, left in place; an authored hook the last apply could not register (its receipt `unsupported` row) is a `warn` saying it guards nothing, whose remedy is `ia host claude --apply`, or none where disableAllHooks turned hooks off, and a kept group (`HOOK_KEPT`) is a `warn` saying it stays in the settings though no registrable hook claims it, and that the next `ia host claude --apply` removes it once hooks are back on, or while they are off once it materializes the payload the group was registered against, with generation's own reason beside it when there is one and no remedy; and an `outdated` row when the generated rows differ from the receipt's, a receipt written before generation included. `tests/host-generated.test.ts` runs the journeys on the composition fixture over `ia init`: one apply writes the packet, one agent, one skill and one group, all in the receipt and owned, and a second changes no file, setting or state and writes the same receipt rows; the group run through the materialized launcher allows the steward's edit, refuses the reviewer subagent's and an unknown subagent's, leaves what the hook does not select undecided and refuses edits to IA's state for every tool; doctor's drift rows for a hand-edited skill and a group deleted by hand, and the remedy it names; renamed records removing the obsolete agent, skill and group, a gone hook's group refusing only its last registered selection until then, unrelated settings and unmarked files intact, and the receipt naming a narrowed hook's tools; a 1.x steward guard retired and the hook group registered in one apply, with a profile named after the 1.x steward file one update; Codex taking the packet and the skill and reporting the agent and the hook; and the mandate fallback rendered for the fixture profile once it names no mandate.
|
|
58
79
|
|
|
59
80
|
## Automation and limits
|
|
60
81
|
|
|
@@ -69,15 +90,15 @@ Commands that start another program (`git` for `init` and `doctor`, `claude` for
|
|
|
69
90
|
|
|
70
91
|
## Mandate authority
|
|
71
92
|
|
|
72
|
-
A `@mandate` may declare its authority as closed moves. Each mandate mode maps to one kernel move: read → Observation, validate → Verification, author → Synthesis, effect → Execution, re-seat → Delegation. The runtime publishes this table as `MODE_MOVES` beside `mandateRefusal`. The modes are not commands; a command's catalog row names its mode. `mandateRefusal` refuses a mode whose move the mandate does not list (`IA-RUNTIME-MANDATE-MOVE`) or a word the mandate excludes (`IA-RUNTIME-MANDATE-WORD`) and names `ia inspect <mandate> --edges both` as the next command. A mandate without `authority.moves` restricts no move, a declared list names at least one move, excluded words are refused whatever the moves, and a mandate adds closed restrictions only; it never grants host permissions. These commands are gated by the acting participant's mandate profile
|
|
93
|
+
A `@mandate` may declare its authority as closed moves. Each mandate mode maps to one kernel move: read → Observation, validate → Verification, author → Synthesis, effect → Execution, re-seat → Delegation. The runtime publishes this table as `MODE_MOVES` beside `mandateRefusal`. The modes are not commands; a command's catalog row names its mode. `mandateRefusal` refuses a mode whose move the mandate does not list (`IA-RUNTIME-MANDATE-MOVE`) or a word the mandate excludes (`IA-RUNTIME-MANDATE-WORD`) and names `ia inspect <mandate> --edges both` as the next command. A mandate without `authority.moves` restricts no move, a declared list names at least one move, excluded words are refused whatever the moves, and a mandate adds closed restrictions only; it never grants host permissions. These commands are gated by the acting participant's mandate profile: `ia read` and `ia next` (read, Observation), `ia validate` and `ia preview` (validate, Verification), `ia author` (author, Synthesis), and `ia capture`, `ia project` and a workspace `ia host <host> --apply` (effect, Execution); a capture or project plan is judged as the effect it plans, and a host plan, `--remove` or `--user` is not judged. `ia position` is not gated, and neither is any other command or surface: the Door's read, next and position operations (the MCP tools), the install, update and remove projection refresh, `ia-distribution validate`, `ia inspect` and the records route, `ia init`, and `ia host`'s plan, `--remove` and `--user`; a mandate restricts only the gated CLI commands. Each gated command takes `--actor <agent>`, a canonical identity, `@agent <name>` or a bare name, which must be an authored participant of the repository's `@workspace` (an authored `@agent` a mandate scoped to it names as its participant, or its `composition.steward` when that is an authored `@agent`: runtime `defaultActor`'s `actors`); without it the actor is the workspace's default (runtime `defaultActor`, the answer the edit guard reads too), where an installed steward counts for no one and the participants decide. Naming an actor is a local declaration, not authentication: it is accepted whether or not the workspace leaves the choice open (it resolves the choice a workspace with several participants and no steward leaves, and under a steward it acts as another of the workspace's actors), and then that participant's own mandates are judged, which may be looser or stricter than the default actor's; it never lifts a move or excluded word those mandates state. The governing mandates (runtime `governingMandates` for the workspace and, for preview and author, the target file's path) are judged by `profileRefusal` for the mode's move and, for preview and author only, the word; the refusal (`IA-RUNTIME-MANDATE-MOVE`, `-WORD` or `-ACTOR`, exit 1) names the governance position of the mandate concerned; an open actor choice, or a default actor no governing mandate binds, names the same command with `--actor` naming the first participant whose mandates allow it (an `ia author` form whose `--digest` is absent or malformed names its preview form instead, which prints the digest, and the participant must be allowed that preview too), else the workspace's governance position; an `--actor` that names no participant names the same command without it where the default actor may run it (for an `ia author` form without a usable `--digest`, its preview form, which the default actor must be allowed too), else the governance position, and only under an open choice the first allowed participant. An admitted governing mandate whose authority the runtime cannot read, such as one with a child under `authority.moves`, which admission accepts, refuses with `IA-RUNTIME-REQUEST-INVALID` located at it (`where` `{path, line, identity}`) and naming that mandate's governance position. While an authored `@mandate` fails admission (2026-10-12; runtime R23), a stated `authority.moves []` among them since compliance C05 refuses it, every gated mode fails closed, workspace-wide, whatever the actor, the path or the word: it refuses with `IA-RUNTIME-REQUEST-INVALID`, exit 1, a `where` of `{path, line, identity?}` at the first such record (its identity when admission or spec 3.1 names one), and a message naming the record and its admission finding and saying a hand edit corrects it, since `ia preview` and `ia author` cannot target a record admission refused. The same holds, with the same shape, while a record an admitted mandate depends on fails admission (runtime R23): a refused `@agent` a mandate's `authority.participant` or a workspace's `composition.steward` names, or a refused `@workspace` a mandate's `authority.scope` names; `where` then locates the refused record and the message names the mandate or workspace that depends on it, while a refused `@agent` or `@workspace` nothing names, or a reference no authored record answers, restricts as before. Its next command is the admission report, `ia report --root <root>`, the version 1 machine route, which no mandate gates and whose findings show the record's: it runs for the same actor in the same state (exit 1 for a failing report, the report on stdout, nothing on stderr), where `ia validate` is gated and `ia position --seat <mandate>` cannot seat at a record admission refused. That route opens its `--root` or the working directory, never an ancestor, so the command carries the invocation's `--root` as every next command repeats it, or, without one, the root spelled relative to the working directory, `.` or `..` segments only, inert by construction, printed only when that spelling, resolved against the working directory as the route resolves `--root` (lexically, then to its real path), reaches this same real root: the spelling relative to the working directory as given, which on win32 keeps a junction's spelling, is tried first, then the one relative to the working directory's real path, so a junction or directory symlink in the working directory's path names a root that runs; where neither does, the command is `ia report`, run from the workspace root, with no path printed, so neither a root's shell-active characters nor the `ia preview <word>` substitution for a non-inert value reach it. The runtime locates the record as data (`RuntimeError.where`) and marks the refusal's cause (`isAdmissionRefusal`), which the CLI branches on, so a refused authored mandate that shares its identity with an admitted one of another band names the report and the hand edit too; the CLI parses no message for either. Preview and author read the same check through their editor snapshot, so a refused mandate refuses them before any candidate is built, and a candidate that would leave a refused mandate stays unclean, as it was. `ia position`, `ia host <host> --remove --apply`, which still restores editing, `--user`, the Door and MCP reads, the install refresh, `ia-distribution`, `ia inspect` and `ia init` are unchanged. Once a command's profile allows it, a refusal it raises later names only a command the same actor may run there: a next command of a gated mode the profile refuses (its move, or the word of a preview or author form) becomes the governance position, and one the profile allows carries `--actor` when the command named its actor so; so `ia next` names `ia preview plan` only where the profile allows Verification and `@plan`. `ia position` is never gated, so a position a refusal names always runs, and the admission report a refused mandate's refusal names is a machine route no mandate gates. The next-command rule holds for the gated commands only: an ungated command's refusal may name a gated command, which is judged when it runs and then refuses with its own mandate refusal and next.
|
|
73
94
|
|
|
74
95
|
Attribution comment correction (2026-10-13): if a work file written by `ia author` later fails parsing, its genuine full-line `# authored-by` comment is not itself an authored mandate declaration (db D15). A valid participant remains readable and `ia validate` reports the actual parse error. This does not waive the workspace-wide admission gate for unidentified declarations or conflict markers, real refused mandates (including identity facets), or refused resolution dependencies. Three damaged files still fail the workspace closed though the comment is genuine, because db D15 still reads its `@mandate`: one that holds a bare CR anywhere, one where the comment stands inside `"""` prose (as after a `"""` no line closes), and one with no pragma where a byte-order mark precedes the comment on line 1. `tests/author.test.ts` creates an actual attributed edit, damages its work record, verifies reads write nothing and validation still reports the parse finding, then verifies a disguised mandate in that file still refuses.
|
|
75
96
|
|
|
76
|
-
The command table also holds the position packet's command catalog (runtime SPEC R19
|
|
97
|
+
The command table also holds the position packet's command catalog (runtime SPEC R19): `init`, `capture` and `project` (effect, Execution), `validate` and `preview` (validate, Verification), `author` (author, Synthesis), and `read`, `position` and `next` (read, Observation), nine rows, each carry their mode, its move, a one-line summary of their main refusal and the one command that refusal names, which `packetCatalog` in `@inventarch/cli/internal/commands` lists in table order for the runtime's `renderPacket`. The machine routes are no catalog rows. `ia host`, `ia project`, `ia init --host`, `ia doctor` and the install, update and remove refresh render the packet through `renderProjectionFor` (the workspace projection above); a catalog tag changes no help text. The capture catalog row covers only an uninitialized root with no authored `@workspace` and no source errors, and names `ia init <directory>`; an initialized root missing its authored workspace instead restores that source before `ia position`, and source errors name `ia validate`. Each row still describes one refusal and one next command.
|
|
77
98
|
|
|
78
99
|
## Path selections
|
|
79
100
|
|
|
80
|
-
A path selection is the text a record states to claim locations: `covers` on a `@mandate` (`authority.covers`), a `@law` or `@convention` (`subject.covers`), a `@spec` (`work.covers`) and a `@check` (`check.covers
|
|
101
|
+
A path selection is the text a record states to claim locations: `covers` on a `@mandate` (`authority.covers`), a `@law` or `@convention` (`subject.covers`), a `@spec` (`work.covers`) and a `@check` (`check.covers`), and `paths` on a `@hook`. A `@check`'s `check.scope` stays text that selects the verdicts the check binds to (the whole-workspace token `*`, a scope its evaluator reports, or prose) and is never a path selection, so it claims no location. These are the glob semantics every consumer of a location seat reads (db SPEC D02b). A selection is a workspace-relative path whose segments are separated by `/`, and a `\` reads as `/` in both the selection and the path matched. `**` as a whole segment matches any number of segments, none included; `*` matches any run of characters within one segment; `?` matches exactly one character; every other character matches itself, case-sensitively. A trailing `/` selects the directory and everything below it, so `docs/` and `docs/**` select `docs` and `docs/guide.md`; a selection without wildcards selects exactly that path. Braces, character classes, escapes and negation are not part of the dialect, and a leading dot is not special. An empty or absolute selection, or one with an empty, `.` or `..` segment, selects nothing, and nothing selects a path that is absolute or escapes the workspace. The graph package implements the dialect (`selects`, graph SPEC G06c), and the database resolves a path to the seat it is declared at and its claimants with it (`resolveSeat`, db SPEC D02b). No command in this release resolves a path to its seat; `read`'s `<path>:<line>` names the record that spans a line of an admitted source, not a seat.
|
|
81
102
|
|
|
82
103
|
Package tests cover parsing, JSON output, initialization and recovery, workspace inspection and formatting, distribution planning/application, host registration, installation and recovery, and the program lookup above. Repository qualification separately exercises built and installed artifacts. External registry publication and each host's own runtime behavior require separate evidence.
|
|
83
104
|
|
|
Binary file
|
package/assets/base.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"id": "inventarch/language",
|
|
3
|
-
"version": "3.
|
|
4
|
-
"archive": "
|
|
5
|
-
"manifest": "
|
|
3
|
+
"version": "3.1.1",
|
|
4
|
+
"archive": "df626d1dc4949649ba7203842b29b4f064e0552e8db8c2c41ff74b6462b81b75",
|
|
5
|
+
"manifest": "7b83fb727ab8706f7e4e9be2d61deceaa4161753b3634c38aa31ab13e4aff1f6"
|
|
6
6
|
}
|
|
Binary file
|
package/assets/host.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
|
-
"release": "
|
|
3
|
-
"archive": "
|
|
4
|
-
"files":
|
|
5
|
-
"bytes":
|
|
2
|
+
"release": "3ba053216d8dc4e9fc66ce4a3304b7ac69d26ad01a32554cb4c035791cb86232",
|
|
3
|
+
"archive": "f91ffe4c2071b196e925e93507bd661b3e09f5dc75392f7d6453fdbec5e28d62",
|
|
4
|
+
"files": 1600,
|
|
5
|
+
"bytes": 9428431
|
|
6
6
|
}
|