@inventarch/cli 3.8.0 → 3.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -2
- package/SPEC.md +7 -5
- package/assets/base/969a1cf9091534f9194c8584c0e45c92449f2e24849db1431841ef73df52b888.ia.tgz +0 -0
- package/assets/base/c7f34843359616b7e9c4677d773fea80c8d3fd22f3bb05e29b12a2d66a97e367.ia.tgz +0 -0
- package/assets/base.json +3 -3
- package/assets/bases.json +12 -0
- package/assets/host/db9ff5f8d179d5ae713562ebd2b564178893c925743b4ec49a8f8a3e06b44625.tgz +0 -0
- package/assets/host.json +4 -4
- package/assets/language-compat.json +1 -1
- package/assets/vocabulary.json +27 -1
- package/dist/commands.d.ts.map +1 -1
- package/dist/commands.js +41 -12
- package/dist/commands.js.map +1 -1
- package/dist/console/run.d.ts.map +1 -1
- package/dist/console/run.js +5 -2
- package/dist/console/run.js.map +1 -1
- package/dist/distribute.d.ts +2 -1
- package/dist/distribute.d.ts.map +1 -1
- package/dist/distribute.js +65 -10
- package/dist/distribute.js.map +1 -1
- package/dist/doctor-authority.d.ts.map +1 -1
- package/dist/doctor-authority.js +1 -0
- package/dist/doctor-authority.js.map +1 -1
- package/dist/doctor-user.d.ts.map +1 -1
- package/dist/doctor-user.js +11 -6
- package/dist/doctor-user.js.map +1 -1
- package/dist/doctor.js +3 -3
- package/dist/doctor.js.map +1 -1
- package/dist/handoff.d.ts +3 -2
- package/dist/handoff.d.ts.map +1 -1
- package/dist/handoff.js +5 -2
- package/dist/handoff.js.map +1 -1
- package/dist/host-projection.d.ts +11 -2
- package/dist/host-projection.d.ts.map +1 -1
- package/dist/host-projection.js +114 -5
- package/dist/host-projection.js.map +1 -1
- package/dist/host.d.ts.map +1 -1
- package/dist/host.js +18 -7
- package/dist/host.js.map +1 -1
- package/dist/init.d.ts +11 -7
- package/dist/init.d.ts.map +1 -1
- package/dist/init.js +25 -5
- package/dist/init.js.map +1 -1
- package/dist/kits-package.d.ts +12 -1
- package/dist/kits-package.d.ts.map +1 -1
- package/dist/kits-package.js +99 -3
- package/dist/kits-package.js.map +1 -1
- package/dist/plugin-product.d.ts.map +1 -1
- package/dist/plugin-product.js +12 -7
- package/dist/plugin-product.js.map +1 -1
- package/dist/preview.d.ts.map +1 -1
- package/dist/preview.js +55 -26
- package/dist/preview.js.map +1 -1
- package/dist/profile.d.ts +6 -0
- package/dist/profile.d.ts.map +1 -1
- package/dist/profile.js +138 -74
- package/dist/profile.js.map +1 -1
- package/dist/user-host.d.ts.map +1 -1
- package/dist/user-host.js +2 -0
- package/dist/user-host.js.map +1 -1
- package/dist/validate.d.ts.map +1 -1
- package/dist/validate.js +1 -0
- package/dist/validate.js.map +1 -1
- package/package.json +7 -7
- package/assets/host/a6774998d18a78fc4d0d2d261db93aa76b25cc97e324823a7883597a94ccb91c.tgz +0 -0
package/README.md
CHANGED
|
@@ -61,7 +61,7 @@ Automation should read the exit value together with the diagnostic code:
|
|
|
61
61
|
|
|
62
62
|
| Command | What it does |
|
|
63
63
|
| --- | --- |
|
|
64
|
-
| `ia init [<directory>]` | Plans a workspace. `--apply` installs the bundled `inventarch/language` base, writes `.ia/src/workspace.ia` with three starter records (a `@workspace`, its participant `@agent` and that agent's `@mandate`), `.ia/.gitignore` and `.ia/release.json`, then captures. `--host claude` or `--host codex` also registers that host, as `ia host --apply` does. `--system` adds a local `@system
|
|
64
|
+
| `ia init [<directory>]` | Plans a workspace. `--apply` installs the bundled `inventarch/language` base, writes `.ia/src/workspace.ia` with three starter records (a `@workspace`, its participant `@agent` and that agent's `@mandate`), `.ia/.gitignore` and `.ia/release.json`, then captures. `--host claude` or `--host codex` also registers that host, as `ia host --apply` does. `--system` adds a local `@system`, its steward and stewardship mandate, and `@distribution` so `ia pack` can release it. `--from <plugin-directory>` lowers a Claude, Codex or Grok plugin into the new workspace as a kit instead (see [host plugins](#-host-plugins)). `--migrate` moves a workspace an IA 1.0 or 1.1 `init` created to this layout. |
|
|
65
65
|
| `ia preview` | Shows what one new record, one field (`--set`) or one relationship (`--relate`) would compile to: the record before and after, the findings it adds and the target file's `sha256`. `ia preview <word>` prints a word's schema, default file and permitted relationships. It writes nothing. |
|
|
66
66
|
| `ia author` | Writes what the same preview showed. It takes the preview's arguments plus `--digest <sha256>`, writes only while the file still has that digest and the candidate is clean, and adds one `# authored-by` line naming the participant and mandate above the record. |
|
|
67
67
|
| `ia validate [<path>...]` | Admits the workspace and reports findings, with `--severity` and `--max-findings`. `--verify-conformance` also verifies COMP-KERNEL and COMP-FIXTURES in-process; add the opt-in `--require-verified` to exit 1 unless both are verified passes. It can record the checks that passed or failed as evidence under `.ia/work/evidence/`. |
|
|
@@ -168,9 +168,10 @@ The example with `--compare` prints `Round trip: content-exact and a fixed point
|
|
|
168
168
|
| `ia pack --descriptor <file>` | Builds a digest-named archive, by default under `.ia/work/dist`. A descriptor that names no distribution, as a default `init` writes, is refused; `ia init --system` authors one. |
|
|
169
169
|
| `ia install <id>[@<range>]...` | Plans an installation, kits included, from a registry, a `--catalog` or the `--offline` cache. |
|
|
170
170
|
| `ia install --package <name>[@<version>]` | Plans installing an npm package of IA kit archives, such as `@inventarch/public-kits`: one entry in `.ia/distributions.lock.json` with its version, npm integrity and each kit's archive and manifest digests, and the kits installed as ordinary releases. npm is transport only; `ia restore` refetches the archives by digest, offline from npm's cache. |
|
|
171
|
+
| `ia install --hosted <id>@<version> --archive <sha256> --manifest <sha256>...` | Plans recording hosted kit pins with their archive and manifest SHA-256 digests in `.ia/distributions.lock.json` without local archive bytes; `ia restore` and `ia validate` succeed offline. |
|
|
171
172
|
| `ia adopt <id>[@version]` | Plans a source-only workspace adoption: pinned source mounted at band 50, then a capture and a refresh of registered projections. `ia init --adopt` adopts at initialization. |
|
|
172
173
|
| `ia update <id>` | Plans a version change for one direct request, `--to <range>`. |
|
|
173
|
-
| `ia remove <id>` | Plans the removal of one direct request. |
|
|
174
|
+
| `ia remove <id>` | Plans the removal of one direct request or hosted kit pin. |
|
|
174
175
|
| `ia restore --apply` | Reinstalls the locked generation from its pinned archives. Any published language base the CLI carries restores exactly, and restore never rewrites the lock; a base it cannot reach refuses and names `ia update inventarch/language`. |
|
|
175
176
|
| `ia floor [--verify] [--json]` | Reports the minimum `inventarch/language` base the workspace's records need, the feature that sets it, and whether the declared range is `ok`, `range-too-high`, `range-too-low` or `no-floor`. `--verify` proves it by validating on each carried base. Exit 1 for `range-too-low`, `no-floor` or a verified error. |
|
|
176
177
|
| `ia recover [installation\|host\|guard\|lifecycle] --root <directory>` | Finishes or rolls back an interrupted installation or host transaction. |
|
package/SPEC.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @inventarch/cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Scoped and shared authored-root ownership (issues #194 and #285): `ia preview` and `ia author` judge each target path at the authored (`band === 100`) `@workspace` that owns the longest declared root containing the path (matching `ia position --seat` / runtime `seatedWorkspace`), rather than only at the repository's root `@workspace`. When `--at` is omitted on a new record or word preview, the default file remains `<first authored root>/<word>.ia` of the repository's root `@workspace`. When an explicit `--at` path or an existing record (`--set` / `--relate`) lies under a nested or sibling authored `@workspace`'s root (such as `.ia/src/scopes/<dept> @authored`), the profile resolves actor eligibility and governing mandates at that owning `@workspace`, and ownership succeeds when the longest containing root is declared at `@authored` placement. When several authored workspaces declare that identical longest root (db D02b `shared`), identity ordering does not change ownership, every authored declarer must declare it at `@authored` placement (so an `@adopted` declaration never borrows another declarer's `@authored`), and at a shared root a mandate governs only when its `authority.scope` names every declarer or its `authority.covers` selects the path. A containing ancestor cannot override a more-specific non-authored (`@adopted`) root. Actor eligibility, digest checks and administrative guards still apply, and pathless follow-up advice (`ia validate` after a department `ia author`) is judged at the repository's root `@workspace`. `tests/preview.test.ts` and `tests/author.test.ts` exercise department workspace seating, shared-root boundaries and mandate isolation.
|
|
4
4
|
|
|
5
5
|
Root containment and co-declaration use the exact canonical spelling admitted by native membership, including letter case on every platform. A case-insensitive filesystem does not turn a differently spelled root declaration into shared ownership. Filesystem alias guards and the floor exclusion remain separate protections.
|
|
6
6
|
|
|
@@ -28,9 +28,9 @@ Owner migrations and grants are explicit source changes followed by `ia validate
|
|
|
28
28
|
|
|
29
29
|
| Command | Behavior |
|
|
30
30
|
| --- | --- |
|
|
31
|
-
| `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 other than canon findings, `IA-COMP-CANON-*`, which `ia validate` alone gates, 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, canon findings aside, 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, `ia recover host`, `guard` or `lifecycle` with `--root <root>`, 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, as are edited starter or distribution text and a kept record that refers to a local identity the migration deletes (see [Migration recovery and portability](#migration-recovery-and-portability)). 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, as [Migration recovery and portability](#migration-recovery-and-portability) qualifies; 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 or is interrupted says that the migration is recorded in `.ia/migration.json` and that nothing was rolled back, and names the rerun of the migration, which resumes from the journal; a migrated workspace that fails admission names `validate --root <root>`, saying neither effect ran; an effect that fails or is interrupted leaves every earlier result in place, says so, and names the rerun of the migration, with host transaction recovery first when one is pending. 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. |
|
|
31
|
+
| `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` (`@system <name>`, requiring `agent-system`, `work-system` and `workspace-system`, paired uniformly with its `@agent <name>-steward` and `@mandate <name>-stewardship`, which covers the system folder alone, `.ia/src/systems/<name>/`, and states no `authority.scope`, so the steward's mandate governs no sibling system and not `.ia/src/workspace.ia`) 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 other than canon findings, `IA-COMP-CANON-*`, which `ia validate` alone gates, 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, seven 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, canon findings aside, 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, `ia recover host`, `guard` or `lifecycle` with `--root <root>`, 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, as are edited starter or distribution text and a kept record that refers to a local identity the migration deletes (see [Migration recovery and portability](#migration-recovery-and-portability)). 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, as [Migration recovery and portability](#migration-recovery-and-portability) qualifies; 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 or is interrupted says that the migration is recorded in `.ia/migration.json` and that nothing was rolled back, and names the rerun of the migration, which resumes from the journal; a migrated workspace that fails admission names `validate --root <root>`, saying neither effect ran; an effect that fails or is interrupted leaves every earlier result in place, says so, and names the rerun of the migration, with host transaction recovery first when one is pending. 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. |
|
|
32
32
|
| `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). `--verify-conformance` verifies COMP-KERNEL and COMP-FIXTURES in-process, as below. Execution bindings and checks are reported as below; a revoked binding or check exits 1 without being a finding. |
|
|
33
|
-
| `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
|
|
33
|
+
| `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 an authored `@workspace` (band 100), inside `.ia/src` and outside the floor (the longest declared root holding the file, declared at `@authored` placement by the owning `@workspace`, which `requireProfile` seats at: 2026-11-18, inventarch/ia#285; under a root several authored workspaces declare, db D02b `shared`, every authored declarer must declare it at `@authored` placement, whatever order their identities sort in: 2026-11-04, inventarch/ia#194), 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. |
|
|
34
34
|
| `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. |
|
|
35
35
|
| `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. |
|
|
36
36
|
| `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`. |
|
|
@@ -49,7 +49,7 @@ Workspace discovery uses the nearest ancestor containing `.ia/src`, with `--root
|
|
|
49
49
|
|
|
50
50
|
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.
|
|
51
51
|
|
|
52
|
-
- `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.
|
|
52
|
+
- `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` until workspace-runtime's `WRITE_PLAIN_NAMES` flips, then `lowering-map` at `formatVersion` 1) 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.
|
|
53
53
|
- `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.
|
|
54
54
|
- `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.
|
|
55
55
|
|
|
@@ -88,7 +88,7 @@ The generated set (2026-10-11): `renderProjectionFor` holds the packet and works
|
|
|
88
88
|
|
|
89
89
|
`--help` and per-command help describe the accepted argument grammar. Consumer `--json` output is a single structured value without interactive prompts; applying without a terminal or with `--json` requires `--yes`. `--no-color` (or `NO_COLOR`), `--color`, `--ascii` and `--quiet` adjust human-readable output. Validation errors exit 1 (warnings alone exit 0), usage failures exit 2, unavailable inputs and local operational refusals exit 3, a remote registry or archive that `install`, `update` or `restore` cannot reach or read exits 4 (`IA-DIST-ARTIFACT-UNAVAILABLE`, or a remote `IA-DIST-LIMIT-EXCEEDED`), and interruption exits 130. Automation should inspect the structured diagnostic code and exit value together.
|
|
90
90
|
|
|
91
|
-
A command typed into an `ia` is handed to the workspace's own installed `@inventarch/cli` before it is parsed (consumer-cli-contract §1.2). `IA_NO_HANDOFF=1` turns hand-off off, so the `ia` that was typed answers, and the session hook sets it for every child it starts. `IA_HANDOFF_FROM` is set only by a copy that hands off, to its package root's real path, and any non-empty value stops the receiving copy from handing off again.
|
|
91
|
+
A command typed into an `ia` is handed to the workspace's own installed `@inventarch/cli` before it is parsed (consumer-cli-contract §1.2); bare `ia`, `--user`, `doctor --host`, `workspaces` (user state, no workspace opened) and an extension's command token are answered by the running copy. `IA_NO_HANDOFF=1` turns hand-off off, so the `ia` that was typed answers, and the session hook sets it for every child it starts. `IA_HANDOFF_FROM` is set only by a copy that hands off, to its package root's real path, and any non-empty value stops the receiving copy from handing off again.
|
|
92
92
|
|
|
93
93
|
Every consumer refusal names one next command. With `--json` a refusal is `{version: 1, ok: false, code, message, exit, where, next}` and `next` is always a non-empty string; human output prints the same text on the `→` line, where the command it quotes is never broken across lines and runs past the line width when it must. The text quotes exactly one command and spells no other command or option outside it. That command is `ia …`, except that a recovery or a directory registry repair names `ia-distribution …`, the binary of `@inventarch/distribution`; a global install of `@inventarch/cli` does not put that binary on `PATH`, so such a command runs only where `@inventarch/distribution` is installed as well. The command carries the values this invocation supplied that it needs, such as the root (`ia init`'s `<directory>` included), the host, the package ids, the registry or catalog source, the descriptor or `--force`, so it runs from the directory the refused command ran in. Except where an unknown or interrupted command keeps the invocation as typed (below), a command that reruns the refused one repeats no output flag such as `--json` or `--quiet`, and one that runs the refused `ia install` or `ia update` again names its plan, without `--apply`: the plan applies nothing, although acquiring may fill the archive cache and `--plan-out` writes the plan file. A rerun of `ia restore`, which has no preview, carries `--apply --yes`; the rerun after deleting a cached archive drops `--offline`, so the archive is fetched again. A placeholder such as `<directory>`, `<path>`, `<file>` or `<url|dir>` stands only for the value the user has to correct or supply. A manual step the CLI cannot take, such as deleting or moving a named file, replacing a link under `.ia/src`, mapping a provider in `.ia/registries.json` or setting `IA_HOME`, may come first, and an explanation may follow. An unknown command names the nearest one with the rest of the invocation as typed, keeping only `--root` and `--params` for a machine operation. A workspace whose sources cannot be read (a link or alias under `.ia/src`, a source that changed during the read) names that repair and then `ia validate` with that root, which confirms the workspace opens. A service refusal that carries no next action of its own names the refused command's `--help` for a usage error, `ia validate` for a record finding (`IA-COMP-*`, `IA-GRAPH-*`, `IA-LANG-*`) and `ia doctor` for any other code, each with the root the invocation gave: its `--root`, or `ia init`'s `<directory>`. An interrupted command (`IA-CLI-INTERRUPTED`, exit 130) carries `next` in its JSON object and on its one stderr line: the rerun that finishes work already written, or otherwise the same invocation as typed, with any `--apply`, `--yes` and `--json` it was given. A file the invocation named that is not there (a `--descriptor`, `--catalog` or `--requests` file) names the same command with that one value as `<file>`. The machine protocol below is unchanged; its failures are the door's own one-line JSON and carry no `next`, so "every refusal names one next command" holds for the consumer commands. `@inventarch/cli/internal/consumer` keeps its 1.x forms: the `Refusal` constructor's `where` and `next` default to null, `refusalOf(error)` without the refused invocation returns a null `next` as before, and `renderRefusal` gives a refusal without a next action the fallback above, so `--json` `next` is always a string; every construction site in this CLI names its next action, which its tests enforce. `PlanRequest.reruns` in `@inventarch/cli/internal/distribute` is optional, and without it a plan's remedies are spelled from the request.
|
|
94
94
|
|
|
@@ -161,6 +161,8 @@ Committed bootstrap (2026-10-30): `ia host <claude|codex|copilot> --commit [--re
|
|
|
161
161
|
|
|
162
162
|
npm packages of kits (2026-10-31, contract C7b, ia-kb `dec-133`): `install --package <name>[@<version>]` (`src/kits-package.ts`, the Execution-gated `install` route, excluding positionals, `--requests`, `--registry` and `--catalog`) records one `package` entry in `.ia/distributions.lock.json` (db lock engine 0.1.2) and installs the kits it carries as ordinary releases. `npm view <name>@<version> --json` (`latest` by default) gives the exact version, `dist.integrity` and `ia.kits` (`{id, version, archive, manifest}`); the tarball is read from npm's content-addressed cache, `<npm cache>/_cacache/content-v2/sha512/<h[0:2]>/<h[2:4]>/<h[4:]>` with `h` the hex of the integrity's SHA-512 and `<npm cache>` `npm_config_cache`, else `npm config get cache`, else npm's default, and must hash to the integrity; when it is not there and the run is not `--offline`, `npm cache add <name>@<version>` puts it there. Each kit's `archives/<archive>.ia.tgz` is verified against its archive and manifest digests, id and version and cached in the workspace; the entry records the manifest's dependency ids; the plan is the installer's (`install`, or `update` with a lock). `--offline` installs only the version the lock records. `restore` first refetches a package entry's archives the workspace cache lacks the same way, offline from npm's cache. An unavailable package refuses `IA-CLI-KITS-PACKAGE-UNAVAILABLE`, an offline miss `IA-DIST-RESTORE-REQUIRED`, a tarball that does not hash to its integrity `IA-DIST-INTEGRITY-MISMATCH`. `IA_NPM` names a Node script run instead of `npm`, for tests only (`tests/fake-npm.mjs`). `host --commit` writes only the instruction block and the door entry, as before. `tests/install-package.test.ts` installs and restores the stand-in package in `tests/fixtures/kits-package`, whose archive `generate.mjs` packs with `ia pack`.
|
|
163
163
|
|
|
164
|
+
Hosted kit lock pins: `install --hosted <id>@<version> --archive <sha256> --manifest <sha256>...` (`src/kits-package.ts` and `src/distribute.ts`, repeatable, excluding positionals, `--package`, `--requests`, `--registry` and `--catalog`) validates `<id>`, canonical SemVer `<version>` (build metadata included) and 64-character lowercase SHA-256 `archive` and `manifest` digests at usage class (`IA-CLI-USAGE`, exit 2) and records `{ kind: "hosted", id, version, hosted: true, archive, manifest }` entries in `.ia/distributions.lock.json` under distribution engine `^0.1.3` without fetching or caching any archive bytes. Change rows report the pinned `archive` SHA-256 and `origin: "hosted"`. `update <id>` on a hosted pin refuses `IA-DIST-INPUT-INVALID` (exit 3) naming `ia install --hosted <id>@<version> --archive <sha256> --manifest <sha256>`. `doctor` includes hosted pins in its `kits` count as managed remotely rather than reporting `no kits installed`. `remove <id>` removes a `hosted` entry as well as a direct request, returning the lock's engine marker to `^0.1.2` when only `package` entries remain or `0.1.1` when no entries remain. `restore` (online and `--offline`) and `validate` succeed without local tarball bytes for hosted entries.
|
|
165
|
+
|
|
164
166
|
Required verification (2026-10-31, contract C7): `validate --verify-conformance --require-verified` exits 1 unless COMP-KERNEL and COMP-FIXTURES are both verified passes (`unverifiedConformance`: `basis: 'verified'` and outcome `pass`), adds `requireVerified: {satisfied, unverified}` to `--json` and one line to the human report. `--require-verified` without `--verify-conformance` is usage (exit 2). Without the flag the report and exit are unchanged.
|
|
165
167
|
|
|
166
168
|
C′ skills (2026-10-30): the generated set's skills are workspace-runtime's capability skills, one per invocable `@capability`, never one per `@playbook`; a skill refused at a folder that holds the user's files names renaming the `@capability` that renders it. The receipt check accepts the generated words `agent-profile`, `capability` and `playbook`. `tests/host-generated.test.ts` and `tests/host-projection.test.ts` make the composition fixture's capability invocable under the playbook's name, so its one skill keeps its path.
|
|
Binary file
|
|
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.4.0",
|
|
4
|
+
"archive": "c7f34843359616b7e9c4677d773fea80c8d3fd22f3bb05e29b12a2d66a97e367",
|
|
5
|
+
"manifest": "8e90731ed1d7a5e11fede4a0de97a8ba649f34a5c8c57b7fa1c673a10ca1602f"
|
|
6
6
|
}
|
package/assets/bases.json
CHANGED
|
@@ -40,5 +40,17 @@
|
|
|
40
40
|
"version": "3.3.0",
|
|
41
41
|
"archive": "3ada760ec07848770957538a8562ec94c6f3a9ceb6f1e29d2739b217f9234728",
|
|
42
42
|
"manifest": "133e0ec85c27c457ba088623c2f753cb7618d531d1412fa957ad6c6ee7b700ee"
|
|
43
|
+
},
|
|
44
|
+
{
|
|
45
|
+
"id": "inventarch/language",
|
|
46
|
+
"version": "3.3.1",
|
|
47
|
+
"archive": "969a1cf9091534f9194c8584c0e45c92449f2e24849db1431841ef73df52b888",
|
|
48
|
+
"manifest": "396de8862c6620d1e93f090917ea60bf3a8f0dfcb0dd3f943fe7df619c1eec6f"
|
|
49
|
+
},
|
|
50
|
+
{
|
|
51
|
+
"id": "inventarch/language",
|
|
52
|
+
"version": "3.4.0",
|
|
53
|
+
"archive": "c7f34843359616b7e9c4677d773fea80c8d3fd22f3bb05e29b12a2d66a97e367",
|
|
54
|
+
"manifest": "8e90731ed1d7a5e11fede4a0de97a8ba649f34a5c8c57b7fa1c673a10ca1602f"
|
|
43
55
|
}
|
|
44
56
|
]
|
|
Binary file
|
package/assets/host.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
|
-
"release": "
|
|
3
|
-
"archive": "
|
|
4
|
-
"files":
|
|
5
|
-
"bytes":
|
|
2
|
+
"release": "c9491f3d608f0c5d2b1369a9192949791eab7e48e4c437d32237aef1b97cf232",
|
|
3
|
+
"archive": "db9ff5f8d179d5ae713562ebd2b564178893c925743b4ec49a8f8a3e06b44625",
|
|
4
|
+
"files": 1887,
|
|
5
|
+
"bytes": 12800050
|
|
6
6
|
}
|