@wairon/cli 5.1.1-dev.105 → 5.1.1-dev.107

package/docs/cli.md

@@ -68,6 +68,15 @@ warnings as errors (notices are printed and counted, never fatal).
   member's own gate, and this project's externals composed against their live
   producers. `--no-recursive` runs this project's gate alone; `--family` runs
   the family run from a member.
+- **Where the network proofs run.** The proofs that need the whole family —
+  `ENTRY_UNPROVEN` (a `network` entry no modelled caller reaches), the gateway
+  rules for members, cross-project reach — are judged by the family run at the
+  **family root** (the project that declares the members). A member validated on
+  its own judges its own gate with its `network` entries counted as declared, and
+  says so in one line, so a green member run is never read as a proven one.
+  **In CI, run `wairon validate --ci` at the family root**; a member in its own
+  repository adds the root's run to its pipeline or relies on the root
+  repository's.
 - **Externals, compared live (advisory: the pin gates).** The gate judges each
   external against its pin. Then every external the run did not compose is
   compared with its **live** producer, offline, and printed in its own section:
@@ -88,6 +97,29 @@ warnings as errors (notices are printed and counted, never fatal).
   `METHOD_SOURCE_PATH_MISSING` (warning). `rules.conformance.requireCode: true`
   in `project.yaml` reports the two notices as errors, for a CI that must say
   every designed implementation has code.
+- **What the closing line says.** Plain `validate` passes with warnings and
+  says so — `Passed with N warning(s)` (`--ci` fails on them); `All checks
+  passed` means none. A tree holding no design yet (no L0, or an L0 with nothing
+  below it) says there is nothing to check.
+- **Unknown keys are reported.** A key a spec's schema does not know (an
+  `exports:` table in the L0 — the export table is `publicInterfaces`; a
+  misspelt field) is `UNKNOWN_SPEC_KEY`, and an unknown setting in
+  `.wai/project.yaml` is `UNKNOWN_CONFIG_KEY` (both warnings): the parse would
+  otherwise drop them without a word.
+- **Code that crosses the design.** A call through a constructor-injected
+  collaborator is collaboration whatever the import's form: when its type comes
+  from a component the caller never declared, even through `import type`, it is
+  `UNDECLARED_DEPENDENCY`; a Portal calling a write- or lifecycle-effect method
+  of a Repository, Index, Store or Registry that way is
+  `PORTAL_WRITE_SHORTCUT_IN_CODE` (error, the code twin of
+  `PORTAL_WRITE_SHORTCUT`); and a file importing a technology's package — a
+  package named by one of the technology's declared tokens (its name, or its
+  `matches`), never a guessed vendor list — outside the components that bind it
+  is `TECH_LEAKAGE_IN_CODE`. An Adapter's call step to a verb of a Portal that
+  declares an out-of-process transport (HTTP, gRPC, a database, a bus, a CLI…)
+  is the link the design models: it is never resolved to the remote Portal's
+  file, so it never reads as `CALL_ORIGIN_UNRESOLVED`; the call to the Adapter
+  stays checked.
 
 ### `wairon generate [--target <name>] [--domain <id>] [--domains <ids>] [--root] [--family] [--no-prune] [--global] [--dry-run]`
 Reconcile the generated guides, skills and context, and — only when the project
@@ -150,16 +182,32 @@ release and changes nothing: a lock never reaches below its project.)
 
 **Code linkage is not part of the approval.** The gate identity and the per-spec
 digests read each spec's **design**: where it is realized — `sourcePath`,
-`symbol`, `exportedVia`, `simPath`, `injectedParams`, conformance tiers, a mount's
-`via`, `externalLinks` — and the `createdAt`/`updatedAt` timestamps are left
+`symbol`, `exportedVia`, `simPath`, `injectedParams`, conformance tiers, a Portal's
+`router`, `externalLinks` — and the `createdAt`/`updatedAt` timestamps are left
 out (`specsReading: design`). Linking code to an approved design, or a change and
 its revert, never stales the lock; declare planned `sourcePath`s at design time.
 
-A **format-2** record (written before this reading) still passes `lock-check`
-while nothing it covered moved. `wairon doctor --fix` re-expresses it as format 3
-in place — keeping `lockedAt`, `lockedBy`, the results and the member pins, and
-recording `reexpressed: { at, fromAlgorithm, fromReading, by }`. A format-2 record
-that no longer matches reads stale once; one `wairon lock` clears it for good.
+**Readiness is not part of the approval either.** A spec's `status` (`draft`,
+`design`, `complete`) says how far authoring is, never what the design says, so
+it is left out of the design view: promoting a spec to `complete` after the lock
+never reopens it. A format-3 record taken while the view still carried `status`
+keeps passing when nothing but a status moved — it is judged in the reading it
+was taken in, each spec's approved status recovered from its digest — and
+`wairon doctor --fix` carries it into the current reading without a review.
+
+A **format-2** record (written before code linkage left the approval) still passes
+`lock-check` while nothing it covered moved. `wairon doctor --fix` re-expresses it
+as format 3 in place — before any other repair touches a spec — keeping
+`lockedAt`, `lockedBy`, the results and the member pins, and recording
+`reexpressed: { at, fromAlgorithm, fromReading, by }`. When no spec file moved
+but the record still does not match, what moved is the **gate** it was judged
+under — the design rules of a newer wairon release, the project's rule tuning,
+`composition`, the network declaration, consumed contracts or a member's
+approval — never your design: `lock-check` and `doctor` say exactly that, `doctor
+--fix` still carries the record into the design reading (its claim stays as
+certified, so it reads stale for that stated cause), and one `wairon lock`
+re-approves the unchanged design. A format-2 record whose specs moved reads stale
+once; one `wairon lock` clears it for good.
 
 It writes **nothing into your spec tree**. The approval is one sha256 per spec
 (over its design view) on `.wai/lock.json`, the record that was always committed — so your
@@ -276,6 +324,7 @@ With inputs (all optional):
       working-directory: packages/api   # where the .wai/ tree lives (default: .)
       wairon-version: '6.0.0'           # version or npm dist-tag, 6.0.0 or later (default: latest)
       strict: true                      # fail when nothing was approved — use it once you have locked (default: false)
+      validate: true                    # also run `wairon validate --ci` there (default: true)
       node-version: '20'                # (default: '20')
       runs-on: ubuntu-latest            # (default: ubuntu-latest)
 ```
@@ -289,6 +338,11 @@ releases, and the default `latest` moves.
 On a `pull_request` event the default checkout is the merge commit, so what the
 gate judges is literally the design that would land.
 
+After the approval check the job runs `wairon validate --ci` in the same
+directory (`validate: false` turns it off). Point `working-directory` at the
+**family root** — the project that declares the members — so that run is the
+family run, which judges the network proofs no member's own gate can.
+
 **A failing job does not block a merge on its own.** A workflow can only fail;
 making a failing job stop a merge is a branch-protection / ruleset setting on
 your repository ("Require status checks to pass" → add this job). No workflow
@@ -304,7 +358,8 @@ machine-wide MCP config) also needs `--global`; each file it replaces is backed
 up beside itself. `--report <section>` prints one section's report and writes
 nothing: `chaining` (the member/reference migration plan) or
 `composed-validation` (what the family run changes about each member's
-findings); it never combines with `--fix`.
+findings) or `reachability` (the reachability migration's plan); it never
+combines with `--fix`.
 
 Among its spec repairs, `--fix` rewrites every stored type position that is an
 alias of its canonical spelling (`string[]` becomes `list<string>`, `boolean`
@@ -316,9 +371,28 @@ literal union, a union mixing in a primitive, a `number` with no proposal) is
 listed with its replacement for an author. Plain `wairon doctor` prints the same
 plan without writing it.
 
-`--fix` also re-expresses a format-2 lock record that still provably covers the
-tree as format 3 (see `wairon lock`), keeping who approved it and when; when it
-no longer covers the tree, doctor says that one `wairon lock` is needed.
+**The reachability migration.** `--fix` also moves the tree onto the
+reachability model: `portalType` becomes `transport` (`HTTP_API` → `HTTP`, a
+`Custom` Portal that binds no wire address → `InProcess`), a listener's `mounts`
+become a Portal-level entry on each mounted Portal and its implementation's
+`router` (the mount's `via`), `invokedBy: external` becomes `entry` on a Portal
+verb and `runtime` elsewhere, an authored export `type` that agrees with the derived kind is dropped,
+in-process `Custom` endpoint addresses are removed, and allows of retired codes
+are dropped or renamed. It never invents design: a Portal that was neither a
+listener nor mounted gets no entry, and a `sibling-subsystem` caller, an export
+type that disagrees, an endpoint outside every old prefix and a router already
+set otherwise are listed for an author. Plain `wairon doctor` prints the plan;
+`--report reachability` lists every rewrite and every form left for an author.
+The design changes, so one `wairon lock` follows. After it, declare the entries
+the migration cannot know — a CLI, a stdio tool surface (`JSONRPC`), a library
+(`InProcess`) — and model a caller or remove each verb still reported unreached.
+
+`--fix` also re-expresses an earlier lock record — format 2, or format 3 taken
+while `status` was still in the approval — in the current reading, first, before
+any repair touches a spec (see `wairon lock`), keeping who approved it and when.
+A format-2 record over a tree no file of which moved is carried into the design
+reading even when the gate it was judged under moved; doctor then says the cause
+(the gate, not the design) and that one `wairon lock` re-approves it.
 
 ### `wairon list` (alias `ls`) / `wairon show <id>`
 List, or show full details of, the agents resolved from the spec tree
@@ -512,6 +586,42 @@ promise and how a consumer follows renames).
 - A tree without an L0 is refused. The JSON Schema ships in the package as
   `schemas/design-export-1.json`, and the library twin is `exportDesign()`.
 
+### `wairon type rename-field <type> <field> <new-name>`
+Renames a field of a type and respells every reference to it — each foreign
+key `references: <type>.<field>` naming it, the type's own included. The field
+keeps its place, type and description; its old name joins the field's rename
+trace (`previousNames`), which `wairon export` shows as `formerly`, so a
+consumer holding the old name reads a rename, not a removal and an addition.
+Traces and prose are never rewritten. It refuses, writing nothing, a type or
+field that does not exist, a name that is not an identifier, and a name another
+field of the type holds or retired. The MCP twin is `sdd_rename_field`. As with
+any design edit, the next `wairon lock` approves it.
+
+### `wairon network flows|policy|diagram|check|why|declare|undeclare`
+Networking derived from the design: the reach the validator already models
+(modelled calls, Portal entries and their scopes, declared networks and their
+gateways), never addresses. Run at the family root.
+
+- `flows [--format json|csv|markdown] [--out <file>]` prints the allowed-flows
+  matrix, narrowed to the modelled callers wherever the family proves a
+  `network` entry.
+- `policy --bindings <file> [--out <file>]` generates Kubernetes
+  `NetworkPolicy` from the matrix and a bindings file you keep outside
+  `.wai/`. Names it cannot bind are listed, never guessed.
+- `diagram [--out <file>]` prints a Mermaid flowchart of the networks as
+  trust boundaries, with the gateways, outside and the flows.
+- `check --observed <file> [--bindings <file>]` compares observed live flows
+  (CSV or JSON) with the matrix. It exits 1 on an unexpected flow or an
+  unknown verb.
+- `why <from> <to>` prints the modelled chain behind one flow. It exits 1
+  when nothing allows it.
+- `declare [--description <text>]` writes the project's `network` declaration
+  into `.wai/project.yaml`; `undeclare` removes it (the assistant's twin is
+  `sdd_set_network`). It changes which rules fire: validate, then re-lock.
+
+[Derived networking](network.md) describes every output, the bindings file
+and the observed-flow format.
+
 ---
 
 ## Members
@@ -557,6 +667,60 @@ then move the pin with `wairon member update`. An uncached git part offline is
 declared `externals`, the name a public name in that project's L0 export table.
 An id without `::` is local — a part's subsystems included.
 
+**Authoring the L0 export table.** What another project may reference is the
+project's **L0 export table**: the `publicInterfaces` list of the L0 spec
+(`.wai/specs/.index.yaml`). It is authored in two steps, both through the MCP
+tools (an assistant runs them; a human may edit the YAML the same way):
+
+1. Each subsystem publishes its own surface — its inbound Portal, and the types
+   it shares — with `sdd_set_public_interfaces` (an L1 `publicInterfaces`).
+2. The L0 **re-exports** from those subsystems with `sdd_update_spec` on kind
+   `system`, delta `publicInterfaces`. Each entry names a subsystem in `from`;
+   `from` alone re-exports everything it publishes, `component` (optionally
+   narrowed with `interface`) or `typeDef` picks one item, `as` renames it
+   (the public name consumers write after `alias::`), `role: implement` marks
+   an extension point consumers implement, and `audience` decides who may see
+   it (below).
+
+```yaml
+# .wai/specs/.index.yaml (excerpt)
+publicInterfaces:
+  - from: distance            # everything the distance subsystem publishes
+  - from: tiles
+    component: tile_portal
+    as: tiles                 # consumers write geo::tiles
+    audience: external
+  - from: shared
+    typeDef: coordinate       # a shared type, as geo::coordinate
+```
+
+The key is `publicInterfaces` — an `exports:` (or any other key the schema does
+not know) is reported as `UNKNOWN_SPEC_KEY`, never silently ignored, and an
+unknown setting in `.wai/project.yaml` as `UNKNOWN_CONFIG_KEY`. A reference to a
+name the producer does not export is `EXTERNAL_NOT_EXPORTED`.
+
+**Export audiences.** Each L0 entry carries an `audience` (default `instance`)
+that decides who may see the public name. Narrowest first:
+
+| Audience | Who sees it |
+|----------|-------------|
+| `project` | Only this project's family: its members, its parent and their siblings. |
+| `department` | The family, and — on a hosted instance — the projects of the owning department. A local sibling checkout or git consumer does **not** see it. |
+| `instance` | The default. Any project on the instance, and any local consumer by path or git. |
+| `partner` | Also consumers outside the instance that a partner grant admits. |
+| `external` | Publicly consumable. |
+
+A consumer is read at one audience: a family project at `project`, so it sees
+everything; a path, git or hosted consumer outside the family at `instance`, so
+it sees `instance`, `partner` and `external` entries only. A name exported to a
+narrower audience is refused by `externals add` (and `externals use`), naming
+the export's audience, the consumer's and this ranking. Because a project cannot
+tell from its own tree whether its consumers are hosted department units,
+`validate` notes every `department` export (`EXPORT_AUDIENCE_NARROW`, a
+notice): widen it to `instance` when a sibling checkout or a git consumer uses
+it, or keep it and allow the notice. A re-export can narrow an audience, never
+widen it (`EXPORT_WIDENS_AUDIENCE`).
+
 | Command | Description |
 |---------|-------------|
 | `wairon member add <alias> <source> [--project] [--description <text>]` | Create a member at `<source>` (`path`, `../path` or `git-url[#commit]`) and declare it by the shorthand. A **part** by default: a specs folder (and, outside this project, its `partOf`). With `--project` a project: its `project.yaml` declaring `<alias>` as its id and its L0, each only when absent. A git member is never scaffolded: it is pinned at the commit given, else the default branch head, and its content decides what it is |
@@ -686,7 +850,7 @@ The local server offers 38 tools:
 | Reading and checking | `sdd_get_spec`, `sdd_get_status`, `sdd_validate_tree` |
 | Renames and moves (in this tree) | `sdd_rename_component`, `sdd_rename_method`, `sdd_rename_type`, `sdd_move_methods` |
 | Members and family migrations (each takes `dryRun`) | `sdd_add_member`, `sdd_move_member`, `sdd_externalize_subsystem`, `sdd_promote_member`, `sdd_demote_member`, `sdd_internalize_member`, `sdd_attach_member`, `sdd_detach_member`, `sdd_adopt_member`, `sdd_rename_project`, `sdd_rename_member_alias` |
-| Externals | `sdd_add_external`, `sdd_pin_externals`, `sdd_get_externals_status` |
+| Externals | `sdd_add_external`, `sdd_update_external`, `sdd_remove_external`, `sdd_pin_externals`, `sdd_get_externals_status` |
 | Packs | `sdd_pack_impact` |
 | Delegation | `sdd_get_agent_brief` (the live brief for one agent; also served as the `wairon-agent://` resource) |
 
@@ -762,7 +926,7 @@ principal.
 | `wairon host permission set --user <userId> --capability <cap> [--value yes\|approval\|no\|inherit] [--project <id> [--subsystem <id>] \| --unit <unitId> \| --instance]` | Set one assignment. Capabilities: `project:read`, `project:create`, `project:write`, `project:admin`, `approval:decide`. The scope defaults to the instance |
 | `wairon host permission list [--user <userId>] [scope flags]` / `remove --id <assignmentId>` | List or remove assignments |
 | `wairon host key mint --project <id\|*> --owner <userId> [--label <label>]` | Mint an API key acting as the owner's live permissions (plaintext shown once). The project must exist (`*` aside); a token naming a project covers its members. Without `--owner` (the legacy `--role editor\|admin` mint) the key resolves to **zero** permissions and the command warns |
-| `wairon host doctor [--fix]` | Inspect the data dir and, with `--fix`, migrate it: roll back a transaction a crash left unfinished there, apply the permission-model migration, then register every hosted family's members as records of their own (no grant written — access is inherited through the parent chain — and every member-qualified key entry rewritten to a record id), all or nothing, audited |
+| `wairon host doctor [--fix]` | Inspect the data dir and, with `--fix`, migrate it: roll back a transaction a crash left unfinished there, apply the permission-model migration, migrate every hosted project's spec tree onto the reachability model (each rewritten project is audited as `migration.reachability` and owes one re-lock by its approvers; the server never does this on its own when it binds a project, because the rewrite moves the approved design and a read-only request must not write), then register every hosted family's members as records of their own (no grant written — access is inherited through the parent chain — and every member-qualified key entry rewritten to a record id), all or nothing, audited |
 | `wairon host key list [--project <id>]` | List API keys |
 | `wairon host key revoke --id <id>` | Revoke a key |
 | `wairon host lock --project <id>` | The same lock flow as `wairon lock` (design gate, `members`, `code` beside the claim, format 3) against the hosted project |
@@ -797,10 +961,13 @@ return the impact of every pack they applied in their results.
 
 | Command | Description |
 |---------|-------------|
-| `wairon externals add <alias> [<source>] [--project <id>] [--ref <ref>] [--dir <dir>] [--use a,b\|'*'] [--description <text>] [--no-pin] [--dry-run] [--json]` | Declare one external in `.wai/project.yaml`. The source is the location grammar members use: `../sibling`, `hosted:<id>`, `<git url>` or `<git url>#<commit>` (the commit is the ref the pin follows, fixed there); omit it when the family provides the producer. It is checked against the producer it reaches: one answering to another id, or not exporting a `use` name to this project, takes the declaration back out and names the id or the closest exported names. Pins by default; a producer that cannot be read leaves it declared and unpinned, saying why. A refusal is one sentence naming the accepted form, and exits 1 |
-| `wairon externals pin [alias…] [--json]` | Pin declared externals into `.wai/externals/<alias>.yaml` and `.wai/externals.lock.yaml`; exits 1 when an alias could not be pinned (unresolved or unreachable — its previous pin stays) |
-| `wairon externals status [--json]` | Each pin compared with its live producer per used member — `unchanged`, `changed`, `renamed` (with the new name), `removed`, `unlocked`, `unavailable` — and each external's health (`incompatible`, `not compared`, `drifted`, `ok`). Git producers are fetched. The opt-in **live** gate: exits 1 when any external is incompatible, 2 when nothing is incompatible but something could not be compared (never a pass), 0 otherwise |
-| `wairon externals list [--json]` | The declared externals, how each resolves and what is pinned; a malformed declaration is listed with its problem, never hidden |
+| `wairon externals add <alias> [<source>] [--project <id>] [--ref <ref>] [--dir <dir>] [--use a,b\|'*'] [--description <text>] [--no-pin] [--dry-run] [--json]` | Declare one external in `.wai/project.yaml`. The source is the location grammar members use: `../sibling`, `hosted:<id>`, `<git url>` or `<git url>#<commit>` (the commit is the ref the pin follows, fixed there); omit it when the family provides the producer. Text that is no location (braces, quotes, whitespace) is refused. The declaration is checked against the producer it reaches **before** anything is written — `--dry-run` included: one answering to another id, or not exporting a `use` name to this project, is refused naming the id, the closest exported names, or the narrower audience the name is exported to (see Export audiences). Pins by default; a producer that cannot be read leaves it declared and unpinned, saying why, and exits 2 (nothing was pinned). A refusal is one sentence naming the accepted form, and exits 1 |
+| `wairon externals use <alias> [--add a,b\|'*'] [--remove c] [--dry-run] [--json]` | Change one declared external's `use` imports, so the specs may name the producer's public names bare (e.g. so an `implements` of the producer's trait spells its types as the producer does — though `alias::name` and the bare imported name compare as one type either way). An added name the producer does not export to this project is refused. The pin is untouched. Exits 1 on a refusal |
+| `wairon externals remove <alias> [--dry-run] [--json]` | Remove one external: its declaration and its pin (`.wai/externals/<alias>.yaml` and its lock entry) together. An orphaned pin — one whose declaration was deleted by hand, which `externals list` shows — is removed too. Exits 1 when the alias is neither declared nor pinned |
+| `wairon externals consumers [--json]` | From a producer's root: the family projects in reach that consume it — each with the alias and section it declares it under and the public names its specs use — so a producer sees who breaks before it changes its surface. A sibling checkout, git or hosted consumer outside the family declares its dependency on its own side and is not visible here |
+| `wairon externals pin [alias…] [--json]` | Pin declared externals into `.wai/externals/<alias>.yaml` and `.wai/externals.lock.yaml`. The snapshot is rewritten whenever anything it carries moved — not only the signatures the digest covers: a producer that added `abi: c`, changed a transport or a role, or recorded a rename is refreshed by a re-pin. Exits 1 when an alias could not be pinned (unresolved or unreachable — its previous pin stays) |
+| `wairon externals status [--json]` | Each pin compared with its live producer per used member — `unchanged`, `changed`, `renamed` (with the new name), `removed`, `unlocked`, `unavailable` — and each external's health (`incompatible`, `not compared`, `drifted`, `ok`); a pinned snapshot that no longer carries what the producer says (a stale `abi`, transport or role) is `drifted`, never `ok`, and names the stale facts. A use the lock does not hold is still compared with the live producer: gone from it, it is `removed` or `renamed`. Git producers are fetched. The opt-in **live** gate: exits 1 when any external is incompatible, 2 when nothing is incompatible but something could not be compared (never a pass), 0 otherwise |
+| `wairon externals list [--json]` | The declared externals, how each resolves and what is pinned; a malformed declaration, and an orphaned pin whose declaration is gone, are listed with their problem, never hidden |
 | `wairon surface export \| import \| list [--audience <level>] [--format native\|openapi] [--portal <id>] [--out <path>] [--source <path>]` | Exchange a public surface document: export this project's (native snapshot or one OpenAPI document per portal), import one, or list them |
 | `wairon produce <notion\|miro> [--page <id>] [--token <token>]` | Project the local spec tree to Notion or Miro (the token comes from `--token`, the environment, else a prompt; nothing is stored) |
 

package/docs/design-export.md

@@ -22,7 +22,7 @@ read back into a tree.
 |---|---|
 | 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-1.json`, shipped in the package (`require.resolve('@wairon/cli/schemas/design-export-1.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. |
+| 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.
@@ -30,10 +30,13 @@ and stamps it. It also exports a tree that is not approved, stamped with its sta
 ## Compatibility promise
 
 - **`format`** is always `"wairon-design"`.
-- **`formatVersion`** is `MAJOR.MINOR` and is currently `1.0`.
+- **`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-1.json`.
+    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
@@ -162,11 +165,11 @@ the resolved L0 export table, as `design_export_entry` rows.
 | Field | Meaning |
 |---|---|
 | `key`, `name`, `description`, `status`, `subsystem` | As declared. |
-| `stereotype`, `variant`, `dependencyClass`, `durability`, `portalType` | 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. |
-| `mounts` | A listener's mounts. Each portal is a key. |
 | `patterns`, `externalLinks` | As declared. |
 | `formerly` | The rename trace. See [Renames](#renames-formerly). |
 | `ext` | Pack extension data. |
@@ -256,9 +259,11 @@ deployment. The export carries the facts a consumer needs to decide for its own
 
 - **Lifecycle roots** (`subsystems[].lifecycle`): what the runtime invokes, with the phase
   (`init`, `shutdown`, `cyclic`, `interrupt` or `scheduled`).
-- **Endpoints and transports** (`interfaces[].methods[].endpoint`, `components[].portalType`):
-  calls that arrive from outside the process. A `Custom` endpoint can be an in-process binding.
-- **Listener mounts** (`components[].mounts`): which listener serves which portal.
+- **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

package/docs/network.md

@@ -0,0 +1,104 @@
+# Derived networking: `wairon network`
+
+wairon derives a system's network from its design. The inputs are the calls you model, the entries you declare on Portals (`invokedBy: {kind: entry, scope: outside | network}`), the networks your projects declare (`network` in `.wai/project.yaml`, written by `wairon network declare [--description <text>]` — `undeclare` removes it — or by the assistant's `sdd_set_network` tool) and the gateways on them (`variant: gateway`). From these it answers who may talk to whom, and on what grounds.
+
+**The gate comes first.** Every network command reads the design as the validator judges it. A flow an error sits on (`GATEWAY_BYPASSED`, ...) is **refused**: the matrix marks its row `REFUSED` with the findings, a policy never admits it (and `policy` exits 1, naming it at the head of the file), `why` answers that the gate refuses it, and `check` files an observed flow that only a refused flow would allow as disallowed. A warning (`ENTRY_UNPROVEN`, ...) only marks its row. Each command prints the findings it was judged against.
+
+Specs never hold an address, a port, a namespace or a label. Those deployment facts come from a **bindings file** that the team keeps outside `.wai/` and passes when generating policy. The design stays logical, and the deployment stays yours.
+
+Every command runs at the project you are in. At a project that declares members, the commands cover its whole family; `--no-recursive` limits them to that project alone. Run them at the family root: only the family run can narrow a `network` entry to the callers it really has.
+
+## The outputs, and what each is for
+
+| Command | Output | What a team does with it |
+|---|---|---|
+| `wairon network flows [--format json\|csv\|markdown] [--out <file>]` | The **allowed-flows matrix**: one row per flow (from, to, transport, binding, networks crossed, gateway, evidence) | Review it in pull requests as the authoritative "who talks to whom". A design change that adds a dependency shows up as a new row before any code or firewall change exists. The CSV suits spreadsheets and audits, and the Markdown suits review comments. |
+| `wairon network policy --bindings <file> [--out <file>]` | **Kubernetes `NetworkPolicy`** YAML: one ingress policy per called workload | Commit it to the deployment repository and diff it in CI. A design change becomes a policy diff that the security reviewer reads in the same PR. A design that fails the gate exits 1: the refused flows are left out and named at the head of the file. |
+| `wairon network diagram [--out <file>]` | A **Mermaid** flowchart: declared networks as nested boundaries, gateways on them, an `outside` node, and flows aggregated per workload pair | Use it as the data-flow diagram with trust boundaries that threat modelling starts from: each boundary an edge crosses is a place to ask the STRIDE questions. It also works for onboarding and on architecture pages. The hosted canvas draws the same picture in its **Network** view (`/canvas/<project>/network`; the system spec's `diagram.defaultView: network` opens the canvas there). |
+| `wairon network check --observed <file> [--bindings <file>]` | **Unexpected** flows (seen, but nothing allows the pair), **disallowed** flows (a verb the destination declares, but not allowed from that source, or only by a flow the gate refuses), **unknown verbs** (an allowed pair, but a method and path no contract of the destination declares) and **unexercised** flows (allowed, never seen) | Audit a live system against its design. Exits 1 on anything unexpected, disallowed or unknown, so it can gate a pipeline. Unexercised flows are review items, such as dead dependencies or rules to tighten, and never fail the command. |
+| `wairon network why <from> <to>` | The modelled chain behind a flow: the entry or call step, each network entered, the gateway, and the verb with its binding | Answer a firewall change request or an incident question ("why does checkout talk to payments?") from the design, in one command. Exits 1 when nothing allows the flow, and names what does reach the target instead; says so when the gate refuses the flow, when a name is unknown (a typo, not a refusal), and — exiting 0 — when the callee is reached in-process, which is never a network flow. |
+| `wairon network declare [--description <text>]` / `undeclare` | Writes (or removes) `network` in `.wai/project.yaml` | Declare the boundary without a hand edit. It changes which rules fire, so validate, then re-lock. |
+
+The MCP server offers the same reads to an assistant while it designs: `sdd_get_network_flows` (optionally `to: <project | portal | portal.verb>`) and `sdd_explain_flow` (`from`, `to`), and the declaration as `sdd_set_network` (`declared`, `description`). The hosted server serves the view model at `GET /web/projects/network?projectId=…`.
+
+### What becomes a flow
+
+- Only **network transports** produce flows: HTTP, gRPC, GraphQL, MessageBus and Custom. In-process libraries, CLI commands, IPC and JSON-RPC over stdio never do.
+- A **modelled call** into a network verb from another subsystem or project is a flow from the calling component. It names the networks it enters and the gateway it passes.
+- A verb's **binding** is the path a cluster sees: an HTTP endpoint is joined under its Portal's `basePath` (`basePath: /v1` and `POST /orders` bind `POST /v1/orders`), so L7 checks match real paths.
+- An **Adapter's transport** is its target Portal's: the Adapter calls the Portal's verbs over it. An Adapter may state one (`sdd_add_component` fills it in from the Portal its `dependsOn` names); a stated transport that disagrees with the target's is `ADAPTER_TRANSPORT_MISMATCH`, so changing a Portal's transport shows its impact on every Adapter that calls it.
+- An **`outside` entry** is a flow from outside the verb's innermost network. For an outermost network that is the world (`outside`); for a nested network it is the next network out (`network:<parent>`). Scopes are relative.
+- A **`network` entry** is a flow from anywhere inside the network. At the family root, when modelled callers prove the entry, the blanket row is replaced by those callers. The matrix is therefore least-privilege by construction: "the network may reach this" becomes "these two Adapters reach this".
+
+### Naming parties
+
+`from`, `to`, the observed-flow names and the binding keys all use design names:
+
+- `outside`.
+- `network` or `network:<id>`, meaning anywhere inside a declared network. A network's id is the key of the project that declares it; plain `network` is the family root's.
+- A project key such as `orders`.
+- A subsystem, as `project::subsystem` or bare for the root's own.
+- A component, as `project::component` or bare for the root's own.
+- On the receiving end, also `project::portal.verb`.
+
+Each party has a **default workload name**: a member's project key, or for the root project's own components their subsystem — also when the root's component reaches into another project: the caller is named by its workload (its subsystem, the pod it runs in), with the component kept for the evidence, so a bindings file written per service keeps covering it after a callee is promoted.
+
+## The bindings file
+
+YAML, kept wherever your deployment config lives (never in `.wai/`):
+
+```yaml
+workloads:
+  orders:                          # a project
+    selector: { app.kubernetes.io/name: orders }
+    namespace: shop
+    port: 8080                     # the port its Portals listen on (optional)
+  platform::api_gateway:           # a Portal: more specific than its project
+    selector: { app.kubernetes.io/name: edge }
+    namespace: edge
+    port: 8443
+  edge:                            # a subsystem of the root project
+    selector: { app.kubernetes.io/name: edge }
+  network:                         # "anywhere in the root network": a label every member pod carries
+    selector: { platform.example/member: "true" }
+outside:                           # what "outside" means for a policy
+  - 0.0.0.0/0
+```
+
+- `workloads` maps a design name to a `selector` (labels, required and non-empty), a `namespace` (optional) and a `port` (optional, 1–65535). The most specific key a party has wins, in the order component, subsystem, project, default workload name.
+- `outside` lists the CIDR blocks admitted for callers from outside, for example the internet, a load balancer range or an intranet. Without it, nothing from outside is admitted.
+- A source in another namespace gets a `namespaceSelector` on `kubernetes.io/metadata.name`. A network-wide source bound without a namespace matches in any namespace (`namespaceSelector: {}`).
+
+**Nothing is guessed.** A design name the bindings do not map is selected by the placeholder label `wairon.dev/workload: <name>`, which matches no pod until you bind it or label one. It is listed in the document and on stderr, and at the top of the output under `# UNBOUND:`. MessageBus flows travel through the broker rather than pod to pod, so they are listed as `# NOT EXPRESSED` instead of opening ingress. Default deny is implied: each policy selects its workload and admits only what the design allows.
+
+## The observed-flow format
+
+Export observed flows from whatever sees them: a service-mesh telemetry export, an eBPF flow log (Cilium/Hubble, Retina), or VPC flow logs once your tooling has mapped addresses to workloads. wairon never sees an IP address. Name each end by a design name, or by a label value that one of your bindings' selectors carries (pass `--bindings` so it can be mapped back).
+
+CSV with a header row; `source` and `destination` are required, the rest optional:
+
+```csv
+source,destination,transport,method,path,count
+outside,edge,HTTP,GET,/api/orders,120
+edge,orders,HTTP,POST,/orders,40
+orders,billing,HTTP,POST,/charges,38
+```
+
+Or JSON with the same fields, as a list or as `{ "flows": [...] }`:
+
+```json
+[{ "source": "orders", "destination": "billing", "method": "POST", "path": "/charges", "count": 38 }]
+```
+
+- A row without `method` and `path` is an L4 observation: it exercises every allowed flow between the pair.
+- A row with both is checked at L7 against the verbs' bindings. `{id}` and `:id` path segments match any value, and gRPC paths (`/pkg.Service/Method`) match the `service/method` binding.
+- A malformed row (no source or destination, or a non-integer count) is refused with its row number, and nothing is half-read.
+
+## A typical loop
+
+```sh
+wairon network flows --format markdown --out docs/flows.md             # review in the PR
+wairon network policy --bindings ../deploy/bindings.yaml --out ../deploy/netpol.yaml
+wairon network check --observed hubble-export.csv --bindings ../deploy/bindings.yaml
+wairon network why shop::checkout_adapter payments::payments_api.charge
+```

package/docs/standards/architecture.md

@@ -299,7 +299,9 @@ The **Adapter** is the single boundary to the outside world, in two shapes:
 
 **Inbound vs outbound:** the **Portal** is *our* front door (others call us); the
 **Adapter** is *our* client to external systems (we call/connect out, including
-publishing). They are different roles, not duplicates.
+publishing). They are different roles, not duplicates. One edge needs no
+Adapter: a call into another project's **library** (an `InProcess` Portal) is
+made directly, from any component (§9, *Libraries are called directly*).
 
 **Emission has no special block, and is optional.** Events are a pattern for
 **decoupled reactions** — used when a producer should not know its consumers.
@@ -513,6 +515,10 @@ Repository whose Store it reads (`UNOWNED_QUERY`).
 > checks are Orchestrators it depends on — typically read logic that gathers the
 > caller's grants and pure logic that rules on them — never members it owns. A
 > Portal with no ingress checks needs no variant.
+>
+> Inside a declared **network**, the gateway is also the only Portal that may be
+> entered from outside it, and the only one a modelled call from outside may land
+> on (`GATEWAY_BYPASSED`; §9, *Networks and gateways*).
 
 The variant carries the implementation guidance (§8). The Gateway *pattern*
 (`Portal + ingress Orchestrator + interceptor Specialists`) is retired
@@ -631,17 +637,94 @@ may — a dependency from any other subsystem is `CROSS_SUBSYSTEM_UNLISTED_CONSU
 (an error). When several entries publish the same component, each naming
 consumers, the union of their lists is the whole set.
 
-### Listeners mount Portals
-A Portal's routes are its methods' endpoint bindings; the **listener** that
-hands the Portal its requests declares that with **`mounts`** on its own L2
-spec — each mount names the `portal`, the path `prefixes` it routes there, and
-optionally `via`, the router entry the Portal's file exports for it. An HTTP
-Portal that no listener mounts, and that declares no `mounts` itself (which
-marks it as a listener, even with `mounts: []`), is `UNMOUNTED_PORTAL`: nothing
-would ever reach it. `mounts: []` is honest only on a Portal that IS the whole
-HTTP server and serves just its own routes; a service with several HTTP
-Portals has one listener that mounts each of them. A prefix matches whole path segments (`/web` covers
-`/web/admin`, not `/webhooks`). Only HTTP endpoints are judged.
+### Transports: how callers reach a Portal
+A Portal states its **`transport`**, one vocabulary shared with its endpoint
+bindings: **network** (`HTTP`, `gRPC`, `GraphQL`, `MessageBus`, and `Custom` as
+the escape hatch), **local** (`CLI`, `IPC`, `NamedPipe`, and `JSONRPC` for
+JSON-RPC over stdio — a language server, a stdio MCP tool surface) or
+**`InProcess`**: a library, whose verbs are its contract methods and bind no
+endpoint. A Portal has one transport, one `auth` and one entry posture; a surface
+that needs two is two Portals. JSON-RPC over HTTP is an `HTTP` verb with a
+dispatch table. Which process hosts which Portal is implementation: the Portal's
+L4 **`router`** names the router entry its own file exports, through which
+whatever serves it hands it requests (route coverage reads the routes there).
+
+### Entries: every verb is reached
+Every Portal verb must be **reached**. Either a modelled caller reaches it — a
+`call` step along a `dependsOn` edge, `alias::portal.verb` across projects, a
+`dispatch` table, a `register` step — or the verb is an **entry**: callers
+outside the design reach it over the Portal's transport. A Portal is not reached
+merely by existing, so one nothing calls and nothing enters is
+`UNUSED_COMPONENT` / `UNUSED_METHOD`, with both remedies named.
+
+- Declare an entry with `invokedBy: { kind: entry, caller: "…" }` — on the
+  Portal (every verb inherits it) or on one verb. The `caller` says who, as
+  reviewable prose (browsers of the shop, the operator's terminal, an AI tool
+  over stdio, the applications that link the crate).
+- `kind: runtime` is for the process's own runtime invoking a method — a
+  composition root, a timer, a signal, a framework callback — on any component.
+- **Never invent an entry to silence a finding.** An entry says real callers
+  exist outside the design. When the caller is inside the design, model the
+  call; when there is none, remove the verb.
+- An `Observer`'s subscriptions and the subsystem `lifecycle` roots reach their
+  methods as before, and a contract that `implements` an imported extension
+  point is reached by its producer.
+
+### Networks and gateways
+A project may declare **`network`** in `.wai/project.yaml` (`true`, or
+`{ description }`): it and every member below it sit inside that network.
+Networks nest, one level per declaring project; parts cannot declare one.
+
+- An entry's **`scope`** is relative: `outside` (the default: callers from
+  outside the innermost network containing the Portal) or `network` (sibling
+  services inside it). A scope on a local or in-process verb means nothing
+  (`ENTRY_SCOPE_NOT_NETWORK`).
+- **Gateways.** Inside a declared network, only a Portal with the `gateway`
+  variant may be entered from `outside`, and a modelled call crossing into a
+  network must land on its gateway (`GATEWAY_BYPASSED`, an error). Traffic from
+  the outermost network to the innermost passes one gateway per level.
+- **Proof.** A `network` entry claims sibling callers, so the family run at the
+  root proves each one has a modelled caller inside its boundary
+  (`ENTRY_UNPROVEN`). A member validated alone counts it as declared.
+- **Audience is a different axis.** An export's `audience` says who may design
+  against a contract; scope says who can reach a verb at runtime. They meet in
+  one place: a network verb exported beyond the project must be the outermost
+  gateway, entered from `outside` (`EXPORT_BEYOND_NETWORK`).
+- A project that declares no network never sees any of this: its entries are
+  `outside` and any Portal may take them. Addresses never appear in specs —
+  `wairon network` derives flows, policy and diagrams from this reach.
+
+### Libraries are called directly
+A library — a crate, a package, a jar, or an FFI/DLL surface — is a project whose
+Portals are `InProcess`. Another project calls its exported verbs **directly**,
+from any component: `alias::portal` in `dependsOn` and `alias::portal.verb` in a
+`call` step. No client Adapter is required (`CROSS_SUBSYSTEM_NON_ADAPTER` and
+`ARCHITECTURE_VIOLATION_PORTAL_DEP` exempt exactly this edge). Two checks take
+the Adapter's place:
+
+- **Purity** (`LIBRARY_CALL_IMPURE`): `pure` logic may call only library verbs
+  declared `effect: none`, and `read` logic also `effect: read`; a verb that does
+  I/O or writes (`io`, `write`, `lifecycle`), or declares no effect, is for
+  workflows.
+- **The language bridge** (`LANGUAGE_BRIDGE_MISSING`): an `InProcess` Portal
+  with no `abi` is a native API in its project's `targetLanguage`. Called from
+  another language it needs `abi: c` (a C-ABI shared library, DLL or FFI) or
+  `abi: wasm`, or a network Portal in front.
+
+Within one project nothing changes: a sibling subsystem's Portal is reached
+through a client Adapter or a `trustedLink`. Wrapping a volatile third-party
+API in an Adapter of your own — an anti-corruption layer that absorbs upstream
+contract changes — remains a recommended pattern; it is never enforced.
+
+### Extension points: contracts consumers implement
+A producer that *calls* a contract its consumers *supply* — a trait, a
+callback, a webhook — exports it with **`role: implement`** (typically the
+Adapter holding the port). A consumer's L3 interface declares
+**`implements: alias::name`** and states every method of it with the same
+signature (`IMPLEMENTS_MISMATCH` otherwise); those methods count as reached,
+because the producer calls them. In-process, the consumer registers its
+implementation with a `register` step; over a network, the implementing
+component is a Portal the producer calls through an Adapter.
 
 ### Forwarding a contract: `signatureFrom`
 A method that takes its params and returns from somewhere else names the source
@@ -951,3 +1034,9 @@ tell apart components that share a noun, and it matches the block:
 14. A gateway is a Portal with the `gateway` variant. Variants load built-in →
     global → project and carry guidance, not rules. `Specialist` and `Gateway` are
     retired (`STEREOTYPE_RETIRED`) until migrated.
+15. Every Portal verb is reached: by a modelled caller, or as a declared entry
+    (`invokedBy: { kind: entry }`) whose callers are outside the design — never an
+    entry invented to silence a finding. A Portal states one `transport`; entries
+    are scoped `outside | network` by the networks projects declare, and inside a
+    network only a gateway is entered from outside. A library (`InProcess`) of
+    another project is called directly, checked for purity and language bridge.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wairon/cli",
-  "version": "5.1.1-dev.105",
+  "version": "5.1.1-dev.107",
   "description": "SYW Waffle AIron — CLI for managing AI coding agent topology across projects",
   "keywords": [
     "ai",