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

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:
@@ -150,8 +159,8 @@ 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.
 
@@ -276,6 +285,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 +299,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 +319,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,6 +332,22 @@ 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.
 
+**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 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.
@@ -512,6 +544,28 @@ 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 network flows|policy|diagram|check|why`
+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.
+
+[Derived networking](network.md) describes every output, the bindings file
+and the observed-flow format.
+
 ---
 
 ## Members
@@ -762,7 +816,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 |

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,99 @@
+# 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: true` in `.wai/project.yaml`) and the gateways on them (`variant: gateway`). From these it answers who may talk to whom, and on what grounds.
+
+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. |
+| `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 them), **unknown verbs** (an allowed pair, but a method and path no contract declares) and **unexercised** flows (allowed, never seen) | Audit a live system against its design. Exits 1 on anything unexpected 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. |
+
+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`). 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.
+- 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. When the root's component reaches into another project, the caller is named by its component.
+
+## 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.106",
   "description": "SYW Waffle AIron — CLI for managing AI coding agent topology across projects",
   "keywords": [
     "ai",

package/schemas/{design-export-1.json → design-export-2.json}

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "wairon design export, format 1.x",
+  "title": "wairon design export, format 2.x",
   "description": "One project's whole design, resolved (format `wairon-design`). A MINOR formatVersion only adds a field or a member of a closed set, and consumers ignore what they do not know; a MAJOR removes, renames or changes a meaning and is named in the CHANGELOG. Generated from the zod schema in src/models/design-export.ts — never edit by hand.",
   "$ref": "#/definitions/DesignExport",
   "definitions": {
@@ -94,6 +94,12 @@
                   },
                   "stability": {
                     "type": "string"
+                  },
+                  "type": {
+                    "type": "string"
+                  },
+                  "role": {
+                    "type": "string"
                   }
                 },
                 "required": [
@@ -268,9 +274,38 @@
               "durability": {
                 "type": "string"
               },
-              "portalType": {
+              "transport": {
                 "type": "string"
               },
+              "abi": {
+                "type": "string"
+              },
+              "invokedBy": {
+                "type": "object",
+                "properties": {
+                  "kind": {
+                    "type": "string",
+                    "enum": [
+                      "entry",
+                      "runtime"
+                    ]
+                  },
+                  "caller": {
+                    "type": "string"
+                  },
+                  "scope": {
+                    "type": "string",
+                    "enum": [
+                      "outside",
+                      "network"
+                    ]
+                  }
+                },
+                "required": [
+                  "kind"
+                ],
+                "additionalProperties": true
+              },
               "owns": {
                 "type": "array",
                 "items": {
@@ -437,31 +472,6 @@
                   "additionalProperties": true
                 }
               },
-              "mounts": {
-                "type": "array",
-                "items": {
-                  "type": "object",
-                  "properties": {
-                    "portal": {
-                      "type": "string"
-                    },
-                    "prefixes": {
-                      "type": "array",
-                      "items": {
-                        "type": "string"
-                      }
-                    },
-                    "via": {
-                      "type": "string"
-                    }
-                  },
-                  "required": [
-                    "portal",
-                    "prefixes"
-                  ],
-                  "additionalProperties": true
-                }
-              },
               "patterns": {
                 "type": "array",
                 "items": {
@@ -528,7 +538,6 @@
               "emits",
               "subscribesTo",
               "dispatch",
-              "mounts",
               "patterns",
               "externalLinks",
               "formerly"
@@ -658,24 +667,7 @@
                       }
                     },
                     "invokedBy": {
-                      "type": "object",
-                      "properties": {
-                        "kind": {
-                          "type": "string",
-                          "enum": [
-                            "runtime",
-                            "external",
-                            "sibling-subsystem"
-                          ]
-                        },
-                        "caller": {
-                          "type": "string"
-                        }
-                      },
-                      "required": [
-                        "kind"
-                      ],
-                      "additionalProperties": true
+                      "$ref": "#/definitions/DesignExport/properties/components/items/properties/invokedBy"
                     },
                     "endpoint": {
                       "type": "object",