@mcp-com-ai/hapi 1.0.2-beta.260914 → 1.2.0

package/dist/skills/hapi-apps-dump/SKILL.md

@@ -130,11 +130,11 @@ object shape, and its own `description` states how many entries the array
 actually needs — read that placeholder's text before replacing it, since the
 count is stricter than it looks:
 
-- **`test_cases`** — needs **at least 5** entries (the published
-  `chatgpt-app-submission.v1.json` schema's `minItems: 5`). Prompts a real
-  user might give that *should* result in one or more of this app's tools
-  being called, with a plausible expected result. Prefer prompts that
-  exercise different tools, not five variations of the same one.
+- **`test_cases`** — needs **at least 3 and up to 5** entries (the published
+  `chatgpt-app-submission.v1.json` schema's `minItems: 3` and `maxItems: 5` ).
+  Prompts a real user might give that *should* result in one or more of this
+  app's tools being called, with a plausible expected result. Prefer prompts
+  that exercise different tools, not five variations of the same one.
 - **`negative_test_cases`** — needs **exactly 3** entries. The published
   schema only declares `minItems: 3` (no maximum), but OpenAI's actual
   submission form has been observed rejecting a count other than exactly 3

package/dist/skills/hapi-federated-apis/SKILL.md

@@ -0,0 +1,452 @@
+---
+name: hapi-federated-apis
+description: Build a runnable multi-domain HAPI project from two or more valid OpenAPI 3.x contracts, with an Arazzo 1.1 composition, deterministic HAPI Capability Graph planning, local Controller/Service implementations, and repeatable MCP/HTTP demos. Use whenever a user asks to compose, federate, orchestrate, coordinate, or demonstrate multiple APIs/services as one HAPI MCP experience; create Arazzo workflows over several contracts; or build a state-aware multi-step Capability Graph demo. Use this skill even when the request merely says “combine these APIs into HAPI,” “make a multi-service MCP server,” or “create a workflow project.”
+license: MIT
+compatibility: Requires Bun, HAPI CLI with OpenAPI, Arazzo, and Capability Graph plugins, and valid OpenAPI 3.x source contracts. HAPI `init` additionally requires a local writable HAPI home.
+metadata:
+  author: mcp.com.ai agent-skills
+  version: "1.4.0"
+allowed-tools: Bash(hapi:*) Bash(bun:*) Bash(curl:*) Read Write
+---
+
+# Build a composed HAPI Capability Graph project
+
+Use this skill to turn several API domains into a demonstrable HAPI project
+without pretending that a collection of contracts is already a distributed
+runtime graph. The useful outcome is a working local system: source APIs,
+Arazzo workflows, explicit business-state planning, a testable MCP surface,
+and a clear map of what remains future product work.
+
+## Start with the correct mental model
+
+There are two different things people call “federation.” Keep them separate:
+
+1. **Composition available now:** several OpenAPI contracts are referenced by
+   an Arazzo workflow. Arazzo can execute the resolved workflow steps as one
+   MCP tool.
+2. **One-document graph compatibility available now:** generate a composed
+   OpenAPI façade that represents the same operations for the current
+   single-document Capability Graph runtime.
+3. **Runtime graph federation not available by implication:** independent
+   graph identities, source conflict resolution, cross-document authorization,
+   persistent graph stores, and distributed state are separate work. Never
+   market a façade or Arazzo source list as this capability.
+
+Call the generated single-document input a **composed façade** or **Plan B**,
+not “graph federation.” Put that statement in the contract and project docs.
+
+## Preconditions
+
+Collect these before writing code:
+
+- Two or more valid OpenAPI 3.x source paths or URLs. Preserve source language
+  and do not overwrite originals unless the user explicitly requests it.
+- A business narrative: actors, desired outcomes, known choices, mutations,
+  confirmation needs, and at least one realistic interruption or failure.
+- Whether sources already have usable `servers` URLs. For a local demo, use
+  loopback server URLs and synthetic data only.
+- A target project directory. Default to a new sibling project, never alter
+  HAPI OSS or Enterprise packages to make a demo work.
+
+If source contracts are invalid, stop and report the validator output. Repair
+the source as a distinct task before composing it. Do not invent operations,
+security, or business policy to force a connected graph.
+
+## Choose the project layout
+
+Use a layout that makes inputs, generated artifacts, implementation, and
+evidence easy to inspect:
+
+```text
+<project>/
+  contracts/
+    flights.openapi.yaml             # source contract example
+    hotels.openapi.yaml
+    transfers.openapi.yaml
+    trip-composed.openapi.yaml       # generated Plan B façade
+  arazzo/
+    trip.arazzo.yaml                 # Plan A composition
+  specs/
+    <project-name>.yaml              # local cache for hapi init
+  src/<project-name>/
+    Controller.ts                    # generated then completed entry points
+    <Domain>Service.ts               # business logic
+    Store.ts                          # deterministic demo state when local
+  scripts/
+    generate-composed.ts
+    check-contract-parity.ts
+    review.ts
+  test/
+  docs/
+  <project-name>.http
+```
+
+For a self-contained local HAPI project, set `HAPI_HOME` to `<project>`.
+HAPI then uses `<project>/specs`, `<project>/src`, and `<project>/config`,
+instead of a developer's global `~/.hapi` directory.
+
+## Use the installed `hapi` command first
+
+All normal setup, generation, review, OpenAPI serving, and Arazzo serving
+commands in this skill use the installed `hapi` binary. Do not make a user run
+`bun packages/cli/src/bin.ts`, depend on a checkout layout, or need HAPI source
+code merely to run their generated project.
+
+Before generating the project, verify the installed plugins and flags:
+
+```bash
+hapi --version
+hapi plugins list
+hapi serve --help
+```
+
+Keep regular scripts portable, for example:
+
+```json
+{
+  "scripts": {
+    "serve": "HAPI_HOME=$PWD hapi serve demo --specs ./contracts/composed.openapi.yaml --mcp --capability-graph --capability-planning --dev --port 3100",
+    "serve:workflows": "HAPI_HOME=$PWD hapi arazzo serve ./arazzo/workflows.arazzo.yaml --mcp --port 3101"
+  }
+}
+```
+
+An opt-in development script can add `--capability-trace` only when the
+installed `hapi serve --help` advertises it. If it is unavailable, explain that
+an HAPI update is required for traces; do not replace normal project scripts
+with source-tree commands. The offline graph/Arazzo review and ordinary MCP
+demo must still run on the installed command.
+
+## Step 1: inventory the domains before modelling a workflow
+
+Read every relevant operation, parameter, schema, response, server, security
+definition, and existing OpenAPI Link. Create a compact inventory:
+
+| Domain | Discovery / selection | Mutations | Irreversible or confirmed actions |
+| --- | --- | --- | --- |
+| Flights | list, inspect, select | book, modify | cancel |
+| Hotels | list, inspect, select | book, modify | cancel |
+| Transfers | list, inspect, select | book | cancel |
+
+This makes missing seams visible. For example, a workflow cannot safely book a
+transfer that has no source operation or a meaningful verified selection.
+
+Treat an empty **selection** cell as a blocker whenever the same row has a
+mutation that needs a choice. Either add the selection operation to the source
+contract (as a separate, explicit repair task) or record the choice as a
+client-verified fact. A domain with a search and a booking but no selection
+compiles cleanly and still cannot be planned.
+
+Also list, per domain, each declared response that forces a new decision, such
+as a booking `409` with `unavailable: true`. These are the demo's re-plan
+triggers. Declare each one on the source contract's response with
+`x-hapi-outcome` (for example, produces `hotel.unavailable` and removes
+`hotel.selected`), and make the façade parity check compare outcomes as well
+as `x-hapi-planning`.
+
+Keep Controller methods thin. Put deterministic sample inventory, state
+transitions, and failure fixtures in Services. A local demo must not use real
+accounts, payments, customer data, or vendor credentials.
+
+## Step 2: create accurate HCG metadata on source operations
+
+Use `x-hapi-capability`, `x-hapi-intent`, `x-hapi-effects`,
+`x-hapi-prerequisites`, and `x-hapi-planning` only when each statement is
+true. The HCG enrichment skill is the specialist companion when the source
+metadata itself needs deeper authoring.
+
+```yaml
+x-hapi-capability:
+  - Travel/Flights/Booking
+x-hapi-intent:
+  use-when:
+    - The traveller has selected a flight and wants to book it.
+  avoid-when:
+    - The flight is only a search result or the traveller has not approved it.
+x-hapi-effects:
+  mode: create # read | create | update | delete | action
+  side-effecting: true
+  destructive: false
+  idempotent: false
+  requires-confirmation: true
+x-hapi-prerequisites:
+  - Verified traveller identity
+  - Explicit flight selection
+x-hapi-planning:
+  requires:
+    - predicate: traveller.identity.verified
+    - predicate: flight.selected
+  produces:
+    - predicate: flight.booked
+  cost: 1
+```
+
+Facts are business state, not commands, unverified fields, or intention:
+
+- Good: `traveller.identity.verified`, `flight.selected`, `hotel.booked`.
+- Bad: `bookHotel`, `user.wants.trip`, `date.2026-10-10` before verification.
+
+A search can produce `hotels.consulted`; it must not produce
+`hotel.selected` unless the API actually performs that selection. A choice
+made outside the API belongs in the client's verified initial facts. This
+boundary is how a plan tells an MCP client exactly what it must clarify.
+
+Use `requires`, `produces`, `removes`, and a finite nonnegative `cost`. A
+cancellation, for example, produces `flight.cancelled` and removes
+`flight.booked`. Do not infer planning transitions from prose, HTTP method,
+classifier output, or a speculative OpenAPI Link.
+
+Cross-domain `requires` need a real business rule. `bookHotel` requiring
+`flight.booked` means no traveller can book a hotel alone. Write such rules in
+`docs/FACTS.md` or remove them.
+
+Never add an OpenAPI Link that maps a search result into a selection input. A
+selection is the person's decision, and the plan must pause to ask for it.
+
+## Step 3: make Plan A Arazzo composition work first
+
+Create an Arazzo 1.1 document with one relative `sourceDescription` per source
+contract. Reference operations by their stable operation IDs and map each
+input, output, and success condition completely.
+
+```yaml
+arazzo: 1.1.0
+info: { title: Trip workflows, version: 1.0.0 }
+sourceDescriptions:
+  - name: flights
+    url: ../contracts/flights.openapi.yaml
+    type: openapi
+  - name: hotels
+    url: ../contracts/hotels.openapi.yaml
+    type: openapi
+workflows:
+  - workflowId: bookTrip
+    summary: Book a selected flight and hotel
+    inputs:
+      type: object
+      required: [flightId, hotelId, travellerId]
+      properties:
+        flightId: { type: string }
+        hotelId: { type: string }
+        travellerId: { type: string }
+    steps:
+      - stepId: bookFlight
+        operationId: $sourceDescriptions.flights.bookFlight
+        requestBody:
+          contentType: application/json
+          payload: { flightId: $inputs.flightId, travellerId: $inputs.travellerId }
+        successCriteria: [{ condition: $statusCode == 200 }]
+```
+
+Give a workflow `x-hapi-planning` only when its resolved steps make one stable,
+atomic business transition. Derive its metadata from the steps it calls:
+
+- `requires` covers every step operation's requirement that no earlier step
+  produces. A `bookTrip` workflow that books a transfer requires
+  `transfer.selected`.
+- `produces` includes each domain fact the steps produce, such as
+  `flight.booked`, `hotel.booked` and `transfer.booked`, alongside any
+  aggregate such as `trip.booked`. Otherwise modify and cancel goals become
+  unplannable after the workflow runs.
+- `removes` includes every fact a step removes.
+
+Write a parity check that compares each planning-eligible workflow against its
+steps' operation metadata, the same way the façade parity check compares
+operations. A workflow with nested workflows or dynamic
+success/failure branches must not become planning-eligible merely to make a
+diagram look more complete. Failure and compensation are not automatically
+provided by Arazzo or Capability Planning.
+
+Validate before continuing:
+
+```bash
+hapi arazzo validate ./arazzo/trip.arazzo.yaml
+```
+
+## Step 4: generate a checked Plan B composed façade
+
+Current Capability Graph compilation consumes one OpenAPI document per runtime.
+Generate one façade from the source contracts; do not hand-maintain a second
+copy. The generator should:
+
+1. Merge paths only after checking globally unique operation IDs.
+2. Merge or safely namespace component names.
+3. Preserve each operation's HCG metadata and request/response contract.
+4. Add only project-owned aggregate routes, such as a synthetic itinerary, in
+   a clearly separate generator section.
+5. Mark `info.x-hapi-demo-composition.not-runtime-federation: true`.
+
+Create a parity check that fails if a source operation is missing, duplicated,
+or has different `x-hapi-planning` metadata in the façade. Then compile it:
+
+```bash
+hapi graph compile ./contracts/trip-composed.openapi.yaml --out artifacts/trip.graph.json
+hapi graph inspect artifacts/trip.graph.json
+```
+
+## Step 5: review state behaviour before running mutations
+
+First close the fact vocabulary. Every required fact must be produced by some
+transition or be a documented client-verified fact, and every outcome must be
+reachable. Run the audit on the compiled façade:
+
+```bash
+hapi graph audit artifacts/trip.graph.json
+```
+
+Declare client-established facts such as identity with root-level
+`x-hapi-client-facts` in each source contract that requires them, and have the
+façade generator merge them without duplicates.
+
+It exits 1 on an orphan requirement or an unreachable outcome, so wire it into
+the project's review script. When the installed CLI predates `graph audit`,
+probe for it and fall back to the bundled script:
+
+```bash
+bun <skill-dir>/scripts/audit-planning-facts.ts artifacts/trip.graph.json \
+  --verified traveller.identity.verified --simulate
+```
+
+`hapi arazzo validate` also warns when a workflow's planning metadata disagrees
+with its steps. Run it with `--strict` in the review script so those warnings
+fail the review. A `clarification-required` result with
+`missing-planning-facts`, `max-depth-exceeded` and zero steps almost always
+means an orphan requirement. Record any intentionally unreachable outcome in
+`docs/FACTS.md` with the reason.
+
+Then run four planning cases for each important goal:
+
+```bash
+# Goal is already true.
+hapi graph simulate artifacts/trip.graph.json \
+  --initial-fact trip.booked --goal-fact trip.booked
+
+# Missing verified choice or confirmation must remain clarification-required.
+hapi graph simulate artifacts/trip.graph.json \
+  --initial-fact traveller.identity.verified --goal-fact trip.booked
+
+# A permitted, gate-satisfied path is planned deterministically.
+hapi graph simulate artifacts/trip.graph.json \
+  --initial-fact traveller.identity.verified \
+  --initial-fact flight.selected \
+  --initial-fact hotel.selected \
+  --goal-fact trip.booked --satisfied-gate mutation-confirmation
+```
+
+Generate a Business State Flow and a goal-specific Plan Trace. Facts are not
+formal UML states: the planner state is a set of facts. The HTML is local,
+read-only inspection output; it never holds credentials, invokes an API, or
+executes a plan.
+
+```bash
+hapi graph visualize artifacts/trip.graph.json \
+  --initial-fact traveller.identity.verified \
+  --goal-fact trip.booked \
+  --out artifacts/trip-state-flow.html
+```
+
+For a presentation, add `--initial-view flow-cards`. The artifact then opens
+on step cards with confirmation waits, required inputs and "Otherwise" lines
+for declared response outcomes, followed by any gap cards. Declared client
+facts are used automatically.
+
+## Step 6: initialize and implement the local HAPI backend
+
+Cache the composed façade at `specs/<project-name>.yaml`, then run:
+
+```bash
+HAPI_HOME=$PWD hapi openapi init <project-name>
+```
+
+Retain the generated `src/<project-name>/Controller.ts` as the entry-point
+layer. Complete its methods so they delegate to Services; never replace it
+with a parallel ad-hoc server. Make seed state resettable and deterministic.
+
+For an all-local setup, source contracts use the backend's loopback `servers`
+URL. Start the OpenAPI backend without `--url` or `--headless`:
+
+```bash
+HAPI_HOME=$PWD hapi serve <project-name> \
+  --specs ./contracts/trip-composed.openapi.yaml \
+  --mcp --capability-graph --capability-planning --dev --port 3100
+```
+
+Start the workflow MCP surface separately, usually on port 3101. It uses the
+source contracts' declared loopback server and needs no URL override:
+
+```bash
+HAPI_HOME=$PWD hapi arazzo serve ./arazzo/trip.arazzo.yaml --mcp --port 3101
+```
+
+If the active CLI supports it, use `--capability-trace` only with graph mode
+and development mode. Treat `[HCG_TRACE]` as redacted development evidence,
+not a business audit log. It must not contain raw query text, fact values,
+arguments, responses, credentials, principal data, or confirmations.
+
+## Step 7: demonstrate the client-led loop accurately
+
+The portable decision-authority loop is:
+
+1. `capability_context` receives a natural-language request and returns a
+   bounded declared vocabulary of candidate goals, relations, gates, and tools.
+2. The client chooses a declared goal. Context does not establish truth.
+3. `capability_plan` receives that goal and **only verified** initial facts.
+4. A `clarification-required` result tells the client what must be verified or
+   confirmed next; gather it conversationally or through a client capability.
+5. The client invokes a permitted direct tool or an Arazzo workflow.
+6. Observe the result, retain only verified state, and re-plan.
+
+In default `decision` authority, HAPI does not call the next tool for the
+client. `capability_plan` is read-only and never grants authorization.
+
+Guarded execution is optional and needs `--runtime-authority guarded`, an
+exact plan, current revalidation, and a trusted externally issued confirmation
+receipt for mutations. Do not add a fake in-process verifier just to make a
+demo look autonomous. TypeSafe/Jev classification, when licensed, only ranks
+an already authorized shortlist; it cannot establish business facts, approve,
+or execute a plan.
+
+## Test like a reviewer, not just a developer
+
+Create a `.http` collection and a repeatable script. Cover:
+
+- `tools/list`, `capability_context`, and `capability_plan` requests.
+- Discovery that produces consultation but not selection.
+- Missing fact / missing confirmation clarification.
+- A valid book, modify, and cancel flow.
+- A deterministic failure (for example unavailable inventory), an explicit new
+  user choice, and a re-plan. Assert no fabricated booking fact or automatic
+  continuation. Cover every re-plan trigger from the Step 1 inventory.
+- `hapi graph audit` (or the fallback script with `--simulate`) and `hapi arazzo validate`
+  without planning warnings, or with each exception documented.
+- Arazzo source validation and one successful multi-step workflow run.
+- Contract parity, graph compile/inspect/simulate/visualize, direct Service
+  tests, and trace-redaction checks.
+
+Do not put secrets, real customers, payment details, or production inventory
+in examples, logs, fixtures, screenshots, or generated HTML.
+
+## Deliverables and handoff
+
+Finish with:
+
+1. Source contract paths, the Arazzo document, and generated façade path.
+2. Project-local setup/start/stop commands and ports.
+3. HCG fact vocabulary and the distinction between declared vocabulary and
+   verified state.
+4. Test commands/results, graph fingerprint, and a link to the visualization.
+5. The fact audit output: client-verified facts, outcomes, and the
+   reachability sweep.
+6. Re-plan triggers: each failure response, its declared `x-hapi-outcome`,
+   and the question asked next.
+7. An explicit current-versus-future matrix covering true federation,
+   persistence, elicitation, autonomous cross-turn orchestration,
+   compensation, resumable execution, and event or schedule triggers. HCG
+   plans toward a goal. Webhooks and callbacks can be described with
+   `x-hapi-event`, but HAPI never receives them, and AsyncAPI messages and
+   time are not modelled, so never fake those with invented facts.
+
+If a user asks only to enrich existing contracts, use the narrower
+`jev-mcp-capability-graph` skill instead. If they want a single API turned into
+an MCP server, use `swagger-to-mcp`. Use this skill when several domains must
+be composed into a runnable project and demo.

package/dist/skills/hapi-federated-apis/scripts/audit-planning-facts.ts

@@ -0,0 +1,127 @@
+#!/usr/bin/env bun
+/**
+ * Audit the planning fact vocabulary of a compiled HAPI Capability Graph.
+ *
+ * Reports:
+ *  - orphan requirements: facts some transition requires but no transition
+ *    produces and the author has not declared as client-verified;
+ *  - outcomes: business facts produced but never required (candidate goals);
+ *  - operations without a planning transition;
+ *  - with --simulate, a reachability sweep that runs `hapi graph simulate`
+ *    for every outcome with all planning operations eligible and all
+ *    non-authorization gates satisfied. Any non-`planned` result is a gap.
+ *
+ * Usage:
+ *   bun audit-planning-facts.ts <graph.json> [--verified <predicate>]... [--simulate]
+ *
+ * Exit code 1 when an orphan requirement or unreachable outcome is found.
+ * Read-only: never calls an upstream API.
+ */
+
+type Fact = { predicate: string; value?: unknown };
+type Gate = { code: string; kind: string };
+type Transition = {
+  id: string;
+  requires: Fact[];
+  produces: Fact[];
+  removes: Fact[];
+  gates?: Gate[];
+  target: { id: string; kind: string };
+};
+type Graph = {
+  operations: Array<{ id: string }>;
+  planning?: { transitions: Transition[] };
+};
+
+const TECHNICAL = /^operation\..+\.completed$/;
+const factKey = (fact: Fact) =>
+  fact.value === undefined ? fact.predicate : `${fact.predicate}=${JSON.stringify(fact.value)}`;
+
+function parseArgs(argv: string[]) {
+  const verified = new Set<string>();
+  let graphPath: string | undefined;
+  let simulate = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--verified") verified.add(argv[++i] ?? "");
+    else if (arg === "--simulate") simulate = true;
+    else graphPath ??= arg;
+  }
+  if (!graphPath) {
+    console.error("Usage: bun audit-planning-facts.ts <graph.json> [--verified <predicate>]... [--simulate]");
+    process.exit(2);
+  }
+  return { graphPath, verified, simulate };
+}
+
+function indexFacts(transitions: Transition[]) {
+  const requiredBy = new Map<string, string[]>();
+  const producedBy = new Map<string, string[]>();
+  const add = (map: Map<string, string[]>, key: string, id: string) =>
+    map.set(key, [...(map.get(key) ?? []), id]);
+  for (const t of transitions) {
+    for (const f of t.requires) add(requiredBy, factKey(f), t.target.id);
+    for (const f of t.produces) if (!TECHNICAL.test(f.predicate)) add(producedBy, factKey(f), t.target.id);
+  }
+  return { requiredBy, producedBy };
+}
+
+/** A consultation nothing requires usually means a missing selection step. */
+function deadEndHint(key: string) {
+  return /\.consulted$/.test(key) ? "  ⚠ dead-end consultation: is a selection operation missing?" : "";
+}
+
+async function simulateOutcome(graphPath: string, goal: string, verified: string[], ops: string[], gates: string[]) {
+  const args = ["graph", "simulate", graphPath, "--goal-fact", goal];
+  for (const f of verified) args.push("--initial-fact", f);
+  for (const o of ops) args.push("--eligible-operation", o);
+  for (const g of gates) args.push("--satisfied-gate", g);
+  const proc = Bun.spawn(["hapi", ...args], { stdout: "pipe", stderr: "pipe" });
+  const out = (await new Response(proc.stdout).text()) + (await new Response(proc.stderr).text());
+  await proc.exited;
+  const outcome = out.match(/Outcome:\s*(\S+)/)?.[1] ?? "error";
+  const diagnostics = out.match(/Diagnostics:\s*(.+)/)?.[1]?.trim() ?? "-";
+  return { outcome, diagnostics };
+}
+
+async function main() {
+  const { graphPath, verified, simulate } = parseArgs(process.argv.slice(2));
+  const graph = (await Bun.file(graphPath).json()) as Graph;
+  const transitions = graph.planning?.transitions ?? [];
+  const { requiredBy, producedBy } = indexFacts(transitions);
+  let failed = false;
+
+  const orphans = [...requiredBy.keys()].filter((k) => !producedBy.has(k) && !verified.has(k)).sort();
+  const declaredVerified = [...verified].filter((k) => requiredBy.has(k)).sort();
+  const outcomes = [...producedBy.keys()].filter((k) => !requiredBy.has(k)).sort();
+  const planned = new Set(transitions.filter((t) => t.target.kind === "operation").map((t) => t.target.id));
+  const unplanned = graph.operations.map((o) => o.id).filter((id) => !planned.has(id)).sort();
+
+  console.log(`Transitions: ${transitions.length}`);
+  console.log("\nOrphan requirements (required, never produced, not declared client-verified):");
+  if (orphans.length === 0) console.log("  none");
+  for (const k of orphans) {
+    failed = true;
+    console.log(`  ✗ ${k}  required by ${requiredBy.get(k)!.join(", ")}`);
+  }
+  console.log("\nDeclared client-verified facts:");
+  console.log(declaredVerified.length ? declaredVerified.map((k) => `  • ${k}`).join("\n") : "  none");
+  console.log("\nOutcomes (produced, never required; candidate goals):");
+  console.log(outcomes.length ? outcomes.map((k) => `  • ${k}  by ${producedBy.get(k)!.join(", ")}${deadEndHint(k)}`).join("\n") : "  none");
+  console.log("\nOperations without a planning transition (discovery-only):");
+  console.log(unplanned.length ? unplanned.map((id) => `  • ${id}`).join("\n") : "  none");
+
+  if (simulate) {
+    const gates = [...new Set(transitions.flatMap((t) => (t.gates ?? []).filter((g) => g.kind !== "authorization").map((g) => g.code)))].sort();
+    console.log(`\nReachability sweep from {${declaredVerified.join(", ")}} with gates satisfied: ${gates.join(", ") || "-"}`);
+    for (const goal of outcomes) {
+      const result = await simulateOutcome(graphPath, goal, declaredVerified, [...planned].sort(), gates);
+      const ok = result.outcome === "planned" || result.outcome === "complete";
+      if (!ok) failed = true;
+      console.log(`  ${ok ? "✓" : "✗"} ${goal}: ${result.outcome}${ok ? "" : `  (${result.diagnostics})`}`);
+    }
+  }
+  process.exit(failed ? 1 : 0);
+}
+
+await main();