@wairon/cli 5.1.1-dev.11 → 5.1.1-dev.110

package/docs/design/supervisor-doctrine.md

@@ -0,0 +1,110 @@
+# Supervisor and Actor doctrine: supervision state, shared data, the lifecycle effect
+
+## The problem
+
+Two rules left the process layer without an honest shape.
+
+- Held state lives in a dedicated data component, but a Supervisor could not
+  depend on a Store, Registry, Repository, Index or Query at all
+  (`ARCHITECTURE_VIOLATION_SUPERVISOR_DEP`). A Supervisor's own bookkeeping —
+  restart counts, the set of live children, the brackets of the runs it starts —
+  had nowhere to live.
+- A component depending on a live Actor had to also depend on a Supervisor that
+  supervises it (`ACTOR_REACHED_WITHOUT_SUPERVISOR`). Real callers do not go
+  through the Supervisor: they look the Actor's live handle up by id in a
+  registry the Supervisor keeps. The remedy pushed a ceremonial edge instead of
+  the real lookup hop.
+
+## The rules
+
+1. **Supervision state.** A Supervisor may `owns` a Store or Registry that is its
+   own: one hop, private, read and written in full. It owns nothing else, and
+   nobody else depends on that state.
+2. **Shared data.** A Supervisor may call a data component it does not own only
+   through methods whose declared effect is `read` or `lifecycle`. A write goes
+   through a workflow: the Supervisor depends on the Orchestrator that does it.
+   Judged from the Supervisor's narrative call steps against the callee's
+   declared effect; a callee that declares no effect is refused too.
+3. **The lifecycle effect.** A third method effect, `lifecycle`: the method
+   creates, destroys, or (un)registers an entity's existence or membership and
+   never modifies its domain fields. It is closed under composition: a lifecycle
+   method calls only read and lifecycle methods besides construction and local
+   steps.
+4. **Supervised reach.** A component depending on a live Actor reaches it through
+   its supervision when it also depends on a Supervisor that supervises the
+   Actor, or on a Registry such a Supervisor maintains — by owning it, or by
+   calling it with lifecycle-effect methods.
+
+**Honest limit.** A `read` made on behalf of a request still passes. In practice
+the paired write is refused, which forces the marshalling workflow out, and the
+read moves with it.
+
+## Codes
+
+| Code | Severity | Rule | Reported on | Meaning |
+|---|---|---|---|---|
+| `SUPERVISOR_CONTAINMENT` | error | pattern-containment | the Supervisor | it owns something other than a Store or Registry |
+| `SUPERVISION_STATE_INTRUSION` | error | member-visibility | the intruder | "X depends on Y, which Supervisor Z owns as its supervision state" |
+| `SUPERVISOR_WRITE_SHORTCUT` | error | supervisor-shared-data (new) | the Supervisor's implementation | a call to a write-effect or untagged method on data it does not own |
+| `LIFECYCLE_CALLS_WRITE` | error | lifecycle-effect-closure (new) | the implementation | a lifecycle-effect method calls a write-effect method |
+| `ARCHITECTURE_VIOLATION_SUPERVISOR_DEP` | error | entrypoint-dependencies | the Supervisor | kept, narrowed: a Supervisor depending on a presentation block |
+| `ACTOR_REACHED_WITHOUT_SUPERVISOR` | error | entrypoint-dependencies | the caller | kept, widened: Registry reach counts; the remedy names the Registry, or says to model one |
+| `BLOCK_OWNS_MEMBERS` | error | pattern-membership | the block | kept: a Supervisor is exempt |
+| `SHARED_OWNED_MEMBER` | error | pattern-membership | the later claimant | kept: Supervisors claim like patterns |
+| `UNUSED_LINT_ALLOW` | warning | lint-allows | the allowing spec | kept: an allow naming an error now says an error cannot be allowed |
+
+The existing readers of `effect` read `lifecycle` as a mutation:
+`PORTAL_WRITE_SHORTCUT` refuses a Portal's direct lifecycle call as it refuses a
+write, and a durable Store needs a hydration read-back for its lifecycle methods
+as for its writes (`MISSING_HYDRATION`). The invariant registry still asks only
+write-effect methods to assert invariants, since a lifecycle method never
+modifies domain fields.
+
+Within the brief, three choices were made:
+
+- Exclusivity is its own code rather than a reworded `VISIBILITY_VIOLATION`:
+  the remedy differs (there is no facade to depend on instead; the state is
+  either shared data or reached through the Supervisor).
+- An owned Registry counts as maintained for supervised reach, as decided. A
+  caller depending on it is then still an intruder, so that shape reports
+  `SUPERVISION_STATE_INTRUSION` once and no actor finding: a lookup Registry
+  callers share is shared data the Supervisor keeps through lifecycle calls.
+- The lint-allow audit decides "error" from what the run saw on that spec (a
+  finding of the code landed there as an error) or, when nothing fired there,
+  from the code's resolved severity (project override, profile, default). The
+  validator now hands the rule context each code's default severity.
+
+## How the four motivating cases validate
+
+1. **An orchestrator calls an Actor whose handle it resolves through a router
+   that is really a Registry of live handles, mistyped as a Store.** Typed as a
+   Store, the caller reaches the Actor through no supervision and
+   `ACTOR_REACHED_WITHOUT_SUPERVISOR` fires on the caller. Retyped as a
+   Registry whose register/unregister methods are `lifecycle` and whose lookup
+   is `read`, with the Supervisor registering each started Actor through a
+   lifecycle call, the caller depending on that Registry and the Actor is
+   supervised reach, and the Supervisor's calls pass `SUPERVISOR_WRITE_SHORTCUT`.
+   A standalone Registry still needs a Store to write to
+   (`REGISTRY_WITHOUT_STORE`, a warning) — give the handles a Store, or wrap both
+   in a Repository the Supervisor keeps through lifecycle calls.
+2. **A component that spawns and owns Actors is typed Orchestrator but is a
+   fused Supervisor and workflow.** It depends on the Actor with no Supervisor
+   anywhere: `ACTOR_REACHED_WITHOUT_SUPERVISOR`, whose remedy says to give the
+   Actor a Supervisor that maintains a handle Registry. Split into a Supervisor
+   (spawns, restarts, registers handles) and a workflow (looks the Actor up in
+   that Registry), the tree validates.
+3. **A scheduler Supervisor reads guard state and brackets run lifetimes on a
+   shared repository.** The edge to the repository is no longer a finding. Its
+   calls — read the guard, open a run, count live runs, close the run — are
+   `read`, `lifecycle`, `read`, `lifecycle`: quiet. Tagging open or close as
+   `write`, or leaving them untagged, fires `SUPERVISOR_WRITE_SHORTCUT`; a
+   lifecycle open that also updates the run's fields fires
+   `LIFECYCLE_CALLS_WRITE` on the repository's implementation.
+4. **The same Supervisor reads and writes a shared object heap on behalf of a
+   call.** The read passes; the write fires `SUPERVISOR_WRITE_SHORTCUT`. Moving
+   the work into a marshalling Orchestrator the Supervisor calls — the read goes
+   with it — validates.
+
+All four, and a fire and a control for every new or changed code, are fixtures
+in `tests/rules-matrix/families/boundaries-supervision.fixtures.ts`; the
+lint-allow case is in `references-lint-allows.fixtures.ts`.

package/docs/design-export.md

@@ -0,0 +1,313 @@
+# The design export (`wairon-design`)
+
+The design export is one JSON document holding a project's whole design, resolved. It is meant
+for tools that work from a design: code generators, translators to other modelling languages,
+documentation sites and design diff tools. Such a tool reads the export instead of walking
+`.wai/specs`.
+
+- **Every element has a key, and every reference is a key.** A consumer never resolves a
+  name itself.
+- **Signatures are inlined.** A method that takes its signature from a source carries that
+  source's params and returns.
+- **Types are canonical.** Every type position is canonical text plus a parsed expression.
+- **Narratives are flat.** Each method body is a numbered step list, its targets resolved to
+  keys.
+
+The export is a projection. It holds no information the spec tree does not, and it is never
+read back into a tree.
+
+## Getting one
+
+| Where | How |
+|---|---|
+| CLI | `wairon export` prints the JSON to stdout, and nothing else. `wairon export --out design.json` writes the file and reports the path and the approval state. A project with member projects names them (on stderr without `--out`, when it holds no design of its own): they are dependencies, exported from their own roots. See [cli.md](cli.md#wairon-export---out-file). |
+| Library | `const { exportDesign } = require('@wairon/cli')` (or `import` from an ES module), then `exportDesign(outPath?, approval?)`, which returns the document and writes it when `outPath` is given. The package ships TypeScript declarations for the library entry (`dist/index.d.ts`, the `types` field), so `DesignExport` and `exportDesign` are typed. |
+| JSON Schema | `schemas/design-export-2.json`, shipped in the package (`require.resolve('@wairon/cli/schemas/design-export-2.json')`). It is a JSON Schema draft-07 document (it declares `$schema`) and carries no `$id`: reference it by its path in the package. It is generated from the zod schema in `src/models/design-export.ts` at build time, and a test fails if the two drift. |
+
+The CLI decides the approval verdict first, the same way `wairon lock-check` does (not strict),
+and stamps it. It also exports a tree that is not approved, stamped with its state.
+
+## Compatibility promise
+
+- **`format`** is always `"wairon-design"`.
+- **`formatVersion`** is `MAJOR.MINOR` and is currently `2.0`. 2.0 is the reachability
+  model's: `portalType` became `transport`, listener `mounts` are gone, a Portal may carry
+  the `invokedBy` entry its verbs inherit, and `invokedBy` kinds are `entry | runtime` with a
+  `scope`.
+  - **A minor version only adds.** It adds new fields, or new members of a closed set (a
+    `role`, an approval state). A consumer must **ignore fields it does not know**. A 1.x
+    document validates against `design-export-2.json`.
+  - **A major version breaks.** It removes or renames a field, or changes what one means. Every
+    major version is named in the CHANGELOG, and wairon emits one major version at a time.
+- **A design change is never a format change.** Two exports of different trees in the same
+  format differ only in content.
+- **`generator`** is the wairon version that wrote the document. It is for diagnostics only,
+  and consumers must not branch on it.
+
+## Determinism
+
+The same tree with the same approval verdict produces **byte-identical** JSON, whatever order the
+spec files sit in on disk.
+
+- **Object keys** are sorted (ordinal).
+- **Element lists** are sorted by key: `subsystems`, `components`, `interfaces`,
+  `implementations`, `types`, `dependencies` and each export table.
+- **Inner lists keep their declared order**, because that order is part of the design: params,
+  fields, enum values, narrative steps, lifecycle roots and `formerly`.
+- **The document has no timestamp.** Equal `source.stateId`s with equal approvals mean equal
+  documents, so a consumer can cache on `stateId`.
+- **`source.stateId` is a content id, not the lock's gate identity.** The two are different
+  digests by design, and never compare equal:
+  - `source.stateId` (`sha256:<digest>`) hashes the parsed spec tree the export was read
+    from, every spec the scan loads, timestamps left out and specs in id order. Snapshots and
+    archives carry the same id. It changes exactly when the specs change.
+  - The lock's `stateId` in `.wai/lock.json` (`sha256+content+doctrine+inputs+members:<digest>`)
+    is the gate identity. It hashes this project's own specs together with the governing
+    doctrine, the declared inputs, `composition` and each direct member's composition subject,
+    so it also moves when a rule, an input or a member's approval moves.
+
+  To relate an export to an approval, read `source.approval`: it is `locked` exactly when
+  that lock record covers this tree.
+
+## Keys
+
+| Element | Key |
+|---|---|
+| Subsystem, component, interface, implementation | its id |
+| Type | `subsystem::id` when a subsystem owns it, the bare id when it is system-level |
+| Contract method | `<interface key>.<name>` |
+| Type method | `<type key>.<name>` |
+| Field, param, enum value | its name, within its owner |
+| Narrative step | its `stepNumber`, within its method |
+| Anything in another project | `alias::publicName`: the alias this project declares the project under, and the public name that project's L0 exports it as |
+
+A type's key `subsystem::id` uses `::` as a **key separator** inside this document: its first
+segment is one of this document's own `subsystems` keys. A cross-project key's first segment is
+an alias from `dependencies` instead, so the two never collide. Signature text (a method's
+`signature` string) keeps the spec's own spelling, which writes a subsystem-owned type as
+`subsystem.id`; read the structured `params` and `returns`, not the signature text, when you
+need keys.
+
+A reference into another project is always written the way a consumer can resolve it: through
+the producer's **public** export table. It is never written with the loader's internal key, so
+the reference stays valid when the producer renames something behind an `as`. A reference that
+binds no exported name stays as written; the validator reports it.
+
+## The document
+
+### Top level (`design_export`)
+
+| Field | Meaning |
+|---|---|
+| `format`, `formatVersion`, `generator` | See [Compatibility promise](#compatibility-promise). |
+| `source` | Which tree the document was projected from, and the approval verdict over it. |
+| `project` | The L0 of the exported project. |
+| `dependencies` | The other projects this project depends on. They are listed, never inlined. |
+| `subsystems`, `components`, `interfaces`, `implementations`, `types` | The design itself, one list per level. |
+
+### `source` (`design_source`)
+
+| Field | Meaning |
+|---|---|
+| `projectId` | The project's effective id (its system name when it declares none). |
+| `stateId` | `sha256:<digest>`, the tree's content identity. It is the cache key. |
+| `approval` | `locked`, `stale`, `unlocked` or `unjudged`. |
+| `approved` | `true` exactly when `approval` is `locked`. |
+
+**What `approved` means.** It is the same verdict `wairon lock-check` and `wairon status` give:
+
+- The committed lock record is resolved against the gate identity. That identity is the parsed
+  own tree, its governing doctrine, its declared inputs, `composition`, and the approvals of its
+  direct members.
+- It is never a weaker per-spec digest comparison.
+- `stale` means a lock exists but the tree moved since. `unlocked` means no lock was ever
+  written.
+- `unjudged` means an in-process caller passed no verdict. It claims nothing either way.
+
+Validation findings are not part of the document. Run `wairon validate` for those.
+
+### `project` (`design_project`)
+
+`name`, `vision`, `boundaries` and `requirements` (as text), `targetLanguage`, and `exports`:
+the resolved L0 export table, as `design_export_entry` rows.
+
+### Export entries (`design_export_entry`)
+
+| Field | Meaning |
+|---|---|
+| `publicName` | The name consumers use. |
+| `targetKind` | `component`, `interface` or `type`. |
+| `target` | The canonical target's key. Every re-export has already been followed to that target. |
+| `audience`, `version`, `stability` | As declared. |
+
+### `dependencies` (`design_dependency`)
+
+| Field | Meaning |
+|---|---|
+| `alias` | The alias the project uses for the dependency. It is the prefix of every `alias::publicName` that points into it. |
+| `projectId` | The dependency's project id. |
+| `role` | `member` for a project this one contains (an in-tree subdirectory member, a sibling or git member, a legacy mount). `external` for a declared external. A part is not a dependency: its subsystems are this project's own. |
+| `digest` | The content digest pinned in `.wai/externals.lock.yaml`, when the dependency is pinned. It is absent when it is not pinned, or when the lock cannot be read. |
+| `uses` | The public names this project's references reach in the dependency, sorted. |
+
+### `subsystems` (`design_subsystem`)
+
+| Field | Meaning |
+|---|---|
+| `key`, `name`, `description`, `status`, `profile`, `targetLanguage` | As declared. |
+| `lifecycle` | The lifecycle roots: `{ phase, component, method }`. These are what the runtime invokes. |
+| `exports` | The resolved L1 export table. |
+| `trustedLinks` | The subsystem keys this subsystem holds a trusted link to. |
+| `ext` | Pack extension data. |
+
+### `components` (`design_component`)
+
+| Field | Meaning |
+|---|---|
+| `key`, `name`, `description`, `status`, `subsystem` | As declared. |
+| `stereotype`, `variant`, `dependencyClass`, `durability` | As declared. |
+| `transport`, `abi`, `invokedBy` | On a Portal: its transport, the `abi` of an `InProcess` Portal that declares one, and the entry its verbs inherit. |
+| `owns`, `dependsOn` | Keys. |
+| `emits`, `subscribesTo` | The topics the component publishes to and consumes from. |
+| `auth`, `basePath`, `dispatch` | A Portal's authentication, base path and dispatch table. Dispatch targets are keys. |
+| `patterns`, `externalLinks` | As declared. |
+| `formerly` | The rename trace. See [Renames](#renames-formerly). |
+| `ext` | Pack extension data. |
+
+### `interfaces` (`design_interface`) and methods (`design_method`)
+
+An interface carries `key`, `component`, `name`, `description`, `status`, `methods`, `formerly`
+and `ext`. Each method carries:
+
+| Field | Meaning |
+|---|---|
+| `key`, `name`, `description` | As declared. |
+| `params`, `returns` | Type refs. A method whose signature comes from a source has its source's params and returns inlined. |
+| `signature` | The derived signature text, for display only. |
+| `signatureType` | The key of the signature type the method takes its signature from, when it names one. A method source is inlined and never named here. |
+| `effect`, `guarantees`, `invokedBy` | As declared. |
+| `endpoint` | The endpoint as declared: `transport` plus that transport's address fields. |
+| `formerly`, `ext` | The method's rename trace (its former `<interface>.<name>` keys), and pack data. |
+
+A type's pure methods use the same shape.
+
+### Params, fields and type refs
+
+- **`design_param`**: `name`, `type`, `optional` and `description`. `optional` means the
+  param may be left out. "May be none" is part of the type, written as `T?`.
+- **`design_field`**: the same fields, plus `key` (`primary`, `unique` or `foreign`) and
+  `references`, which is a type key or `<type key>.<field>`.
+- **`design_type_ref`**:
+  - `text` is the canonical text in the neutral type grammar.
+  - `expression` is the parsed form. It is a tree of `{ form, name?, args }`, where `form` is
+    `primitive`, `named`, `list`, `set`, `map`, `optional`, `union`, `async` or `applied`.
+  - The `name` of every named member is the **key** of the type it names.
+  - When the grammar cannot read a position, `expression` is absent. The text is then opaque:
+    the export never invents a shape.
+
+### `implementations` (`design_implementation`) and bodies (`design_method_body`)
+
+An implementation carries:
+
+- `key`, `contract`, `component`, `name`, `description` and `status`;
+- `technologies`, by name;
+- `sourcePath`, `methods`, `formerly` and `ext`.
+
+Each method body carries:
+
+| Field | Meaning |
+|---|---|
+| `method` | The contract method's key. |
+| `detail` | `full`, `calls-only` or `intent`, after the stereotype default is applied. |
+| `intent` | The prose that stands in for steps, at `intent` detail. |
+| `calls` | The declared calls, as method keys. |
+| `narrative` | The flat step list as stored. A `call`, `register` or `dispatch` step's target, and a credential source, are keys. Flow steps jump by `stepNumber`. |
+
+### `types` (`design_type`)
+
+A type carries:
+
+- `key`, `kind`, `name`, `description` and `status`;
+- `fields` and its pure `methods`;
+- a signature type's `params` and `returns`;
+- an enum's `values`, in declared order;
+- a named scalar's `holds`;
+- `invariants`;
+- `componentClass`, a key;
+- `database`, `table` and `linkedEntity`;
+- `formerly` and `ext`.
+
+## What is left out, and why
+
+| Left out | Why |
+|---|---|
+| Lint allows, conformance tiers and finding declarations | They are gate configuration, not design. |
+| `symbol` and `exportedVia` | They bind to this repository's code. |
+| `simPath` | It names a test harness. |
+| `createdAt` and `updatedAt` | They would break determinism. |
+| A member project's specs | They are listed as a dependency. Export the member itself for its design. |
+
+Pack `ext` data is passed through untouched, under each pack's own key. It is the sanctioned
+extension channel.
+
+## Executable or library: the consumer decides
+
+The export has no `kind` that says "program" or "library". Whether a design ships as a
+service, a CLI, a library or a plugin is a packaging decision. The same architecture can be
+packaged in each of those ways, so wairon leaves the decision to the consumer, as it does with
+deployment. The export carries the facts a consumer needs to decide for its own target:
+
+- **Lifecycle roots** (`subsystems[].lifecycle`): what the runtime invokes, with the phase
+  (`init`, `shutdown`, `cyclic`, `interrupt` or `scheduled`).
+- **Transports and endpoints** (`components[].transport`, `interfaces[].methods[].endpoint`):
+  how callers reach each Portal. An `InProcess` Portal is a library and binds no endpoint;
+  its `abi` says how a foreign language links it.
+- **Entries** (`components[].invokedBy`, `interfaces[].methods[].invokedBy`): the verbs callers
+  outside the design reach, with their `scope`.
+- **The export table** (`project.exports`): what other projects link against.
+
+For example, one generator might emit a `main` that runs the `init` roots and serves the HTTP
+portals. Another might emit a library that publishes `project.exports`. Both are correct readings
+of the same export.
+
+## Renames: `formerly`
+
+Components, interfaces, implementations and types carry `formerly`: every key they held before,
+oldest first. Contract methods carry their former `<interface>.<name>` keys. The rename tools
+write these traces:
+
+| Tool | What it records |
+|---|---|
+| `sdd_rename_component` | The component, and its `i<id>` and `<id>_impl` |
+| `sdd_rename_method` | The method |
+| `sdd_move_methods` | Each method that moved |
+| `sdd_rename_type` | The type |
+
+**Retired names cannot be reused.**
+
+- A rename tool or a create that would give a new spec an id a trace holds is refused
+  (`id-retired`).
+- So is a new method under a name its own contract retired (`name-retired`).
+- A hand edit that reuses one is reported as `RENAME_TRACE_CONFLICT`.
+- Unsetting the trace releases the name. A consumer then sees a delete plus an add.
+
+**The consumer's algorithm.** This is how a generator keeps its user's wired code across
+renames:
+
+1. Keep the keys you generated from.
+2. For a key that is now missing, first resolve its **owner** (subsystem, component, interface
+   or type) through `formerly`. Then resolve the **member** by name, or through the member's own
+   `formerly`.
+3. A match is a rename. Anything left unmatched is a deletion. A key present now and absent
+   before is an addition.
+4. Traces accumulate, so this works across chains of renames, and across exports you skipped.
+
+**A published name survives an internal rename.** When a renamed component or type backed an
+export entry whose public name came from its id, the rename writes `as: <old name>` on that
+entry. Consumers' pins and `alias::publicName` references keep resolving. A renamed method that
+is published is reported, but not prevented: no mainstream export mechanism aliases a single
+member.
+
+**What escapes the trace.** Moving elements between projects (`wairon subsystem externalize`,
+`wairon member internalize`) is a delete in one project and an add in another. No
+single-project trace follows such a move. Renames made before traces existed left none behind.