@nanobpm/nano-workforce 0.85.3 → 0.86.0

package/app/agentic/vocab/publish.test.ts

@@ -0,0 +1,20 @@
+// Tests for the published vocab view (epic #152 / N1 #145). The endpoint contract promises a
+// deterministic, sorted `requirements` list so a worker sees a stable ordering regardless of the
+// resolver's internal role ordering.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { CREW_VOCAB_VERSION } from "./crew-vocab.ts";
+import { vocabRequirements, vocabView } from "./publish.ts";
+
+test("vocabRequirements are sorted by token (deterministic response order)", () => {
+  const tokens = vocabRequirements().map((r) => r.token);
+  const sorted = [...tokens].sort((a, b) => a.localeCompare(b));
+  assertEquals(tokens, sorted);
+});
+
+test("vocabView carries the crew-vocab version and the sorted requirements", () => {
+  const view = vocabView();
+  assertEquals(view.version, CREW_VOCAB_VERSION);
+  const tokens = view.requirements.map((r) => r.token);
+  assertEquals(tokens, [...tokens].sort((a, b) => a.localeCompare(b)));
+});

package/app/agentic/vocab/publish.ts

@@ -0,0 +1,38 @@
+// nano-workforce — the published vocab view (epic #152 / N1 #145, ADR 0059 revised).
+//
+// Projects the crew vocabulary artifact onto the `GET /agentic/vocab` contract: `{ networks,
+// requirements, version }`. `networks` is the raw artifact tree (authored in the `@nanobpm/agentic`
+// `VocabDocument` schema — a worker/tool consuming the endpoint gets the same document the resolver
+// was built from); `requirements` is the flattened per-token enrolment gate (each role's `requires`
+// predicates, seats and diversity flag) so a worker can see WHAT capability a token demands without
+// re-deriving the tree.
+import type { VocabRequirement, VocabView } from "../../../nano-generated/api-io.d.ts";
+import { CREW_VOCAB, CREW_VOCAB_VERSION, crewResolver } from "./crew-vocab.ts";
+
+/** The published, flattened enrolment requirements — one entry per crew-vocab leaf token, sorted. */
+export function vocabRequirements(): VocabRequirement[] {
+  return crewResolver()
+    .roles()
+    .map((role) => {
+      const requirement: VocabRequirement = {
+        token: role.token,
+        role: role.role,
+        requires: role.requires.map((predicate) => predicate.source),
+        seats: typeof role.seats === "number" ? role.seats : [...role.seats],
+        seatsDistinctFamily: role.seatsDistinctFamily,
+      };
+      if (role.network !== undefined) requirement.network = role.network;
+      if (role.weight !== undefined) requirement.weight = role.weight;
+      return requirement;
+    })
+    .sort((a, b) => a.token.localeCompare(b.token));
+}
+
+/** The full published vocab view for `GET /agentic/vocab`. */
+export function vocabView(): VocabView {
+  return {
+    version: CREW_VOCAB_VERSION,
+    networks: { ...CREW_VOCAB.networks },
+    requirements: vocabRequirements(),
+  };
+}

package/openapi.yaml

@@ -297,6 +297,278 @@ components:
             processed, so the cockpit can line each worker's terminal up with its process instance / plan (H6).
           items:
             $ref: "#/components/schemas/AgenticJobCorrelation"
+    VocabRequirement:
+      type: object
+      description: One crew-vocab leaf token's flattened enrolment gate — the capability `requires`
+        predicates, seat sizing, and diversity flag a worker sees without re-deriving the tree.
+      required:
+        - token
+        - role
+        - requires
+        - seats
+        - seatsDistinctFamily
+      properties:
+        token:
+          type: string
+          description: The leaf routing token (`network[.subnetwork…].role`, or a bare role).
+        network:
+          type: string
+          description: The network segment, absent for a bare role.
+        role:
+          type: string
+          description: The role segment.
+        weight:
+          type: number
+          description: The role's cognition weight, if declared.
+        requires:
+          type: array
+          description: The enrolment `requires` predicates (source form, e.g. `cognition=planning`).
+          items:
+            type: string
+        seats:
+          description: Either a seat count (integer ≥ 0) or the explicit named-seat list.
+          oneOf:
+            - type: integer
+              minimum: 0
+            - type: array
+              items:
+                type: string
+        seatsDistinctFamily:
+          type: boolean
+          description: When true, seats must be filled by distinct families (the diversity SLO opt-in).
+    VocabView:
+      type: object
+      description: The published crew vocabulary artifact — the ONE capability→token map (ADR 0059).
+      required:
+        - version
+        - networks
+        - requirements
+      properties:
+        version:
+          type: integer
+          description: The crew-vocab artifact version.
+        networks:
+          type: object
+          additionalProperties: true
+          description: The raw networks/roles tree, in the `@nanobpm/agentic` VocabDocument schema.
+        requirements:
+          type: array
+          description: The flattened per-token enrolment requirements, sorted by token.
+          items:
+            $ref: "#/components/schemas/VocabRequirement"
+    Capability:
+      type: object
+      description: A worker's declared enrolment capability. NEVER a routing token — it gates enrolment.
+      properties:
+        cognition:
+          type: string
+          description: The worker's cognition class (e.g. planning / implementation / qa / ci / decide).
+        weight:
+          type: number
+          description: The cognition weight (the one numeric capability field).
+        family:
+          type: string
+          description: The model family (the diversity-SLO seat filler, e.g. frontier / kimi / qwen).
+        host:
+          type: string
+          description: Where the worker runs.
+    EnrolRequest:
+      type: object
+      description: A worker's enrol request — its declared capability (ADR 0059 revised, per-worker).
+      required:
+        - capability
+      properties:
+        capability:
+          $ref: "#/components/schemas/Capability"
+        host:
+          type: string
+          description: Where the worker runs. Folded into `capability.host` when the latter is absent.
+        instance:
+          type: string
+          description: The worker instance id, echoed back for provenance (optional).
+    EnrolledRole:
+      type: object
+      description: One matched role in an enrolment resolution — provenance for the resolved SERVE set.
+      required:
+        - token
+        - seatsDistinctFamily
+      properties:
+        token:
+          type: string
+        weight:
+          type: number
+        seatsDistinctFamily:
+          type: boolean
+    EnrolResult:
+      type: object
+      description: The resolved SERVE set for an enrolled capability (ADR 0059 REGISTER→SERVE).
+      required:
+        - serve
+        - roles
+        - demandVersion
+        - leaseTtl
+      properties:
+        instance:
+          type: string
+          description: The worker instance id, echoed from the request when supplied.
+        serve:
+          type: array
+          description: The SERVE token set — sorted, de-duplicated leaf tokens the worker may serve.
+          items:
+            type: string
+        roles:
+          type: array
+          description: The matched roles (sorted by token) the SERVE tokens came from.
+          items:
+            $ref: "#/components/schemas/EnrolledRole"
+        demandVersion:
+          type: integer
+          description: The crew-vocab version the capability was resolved against.
+        leaseTtl:
+          type: integer
+          description: The liveness lease TTL in ms — the worker must heartbeat within this window.
+    TokenDemand:
+      type: object
+      description: One demanded routing token and the live supply against it.
+      required:
+        - token
+        - supply
+        - instances
+        - satisfied
+      properties:
+        token:
+          type: string
+          description: The demanded routing token (a deployed `taskDefinition` leaf's type).
+        supply:
+          type: integer
+          description: How many registered workers currently serve this token.
+        instances:
+          type: array
+          description: The instances serving it, sorted.
+          items:
+            type: string
+        satisfied:
+          type: boolean
+          description: False when no registered worker serves it — a missing agent type.
+    NetworkDemand:
+      type: object
+      description: The demand×supply picture for one network prefix.
+      required:
+        - network
+        - tokens
+        - missing
+      properties:
+        network:
+          type: string
+          description: The network prefix bucket (the `network` segment, or a bare token's own name).
+        tokens:
+          type: array
+          description: Every demanded token in the bucket, sorted by token.
+          items:
+            $ref: "#/components/schemas/TokenDemand"
+        missing:
+          type: array
+          description: The demanded tokens in this bucket with zero supply, sorted.
+          items:
+            type: string
+    SeatAssignment:
+      type: object
+      description: One seat of a role filled by a worker of a given family.
+      required:
+        - seat
+        - family
+      properties:
+        seat:
+          type: string
+        family:
+          type: string
+        instance:
+          type: string
+    RoleDiversity:
+      type: object
+      description: The diversity grade for a single role.
+      required:
+        - token
+        - seatsDistinctFamily
+        - assignments
+        - collidingFamilies
+        - status
+      properties:
+        token:
+          type: string
+        seatsDistinctFamily:
+          type: boolean
+        assignments:
+          type: array
+          items:
+            $ref: "#/components/schemas/SeatAssignment"
+        collidingFamilies:
+          type: array
+          items:
+            type: string
+        status:
+          type: string
+          enum: [green, amber, red]
+    DiversityReport:
+      type: object
+      description: The diversity SLO over the correlated live registry (ADR 0056 §10).
+      required:
+        - status
+        - roles
+      properties:
+        status:
+          type: string
+          enum: [green, amber, red]
+          description: The worst grade across all roles (red > amber > green).
+        roles:
+          type: array
+          description: Per-role grades, sorted by token.
+          items:
+            $ref: "#/components/schemas/RoleDiversity"
+    RegistryReport:
+      type: object
+      description: The demand×supply report — deployed demand diffed against live supply, per network,
+        with missing-agent-type reds and the diversity SLO (enrolment epic 152 slice N1).
+      required:
+        - version
+        - generatedAt
+        - demandUnavailable
+        - networks
+        - missing
+        - nonAgentic
+        - diversity
+        - status
+      properties:
+        version:
+          type: integer
+          description: The crew-vocab version the report was resolved against.
+        generatedAt:
+          type: string
+          description: When the report was computed, ISO-8601.
+        demandUnavailable:
+          type: boolean
+          description: True when the deployed demand could not be read from the engine (supply-only report).
+        networks:
+          type: array
+          description: Per-network demand×supply, sorted by network.
+          items:
+            $ref: "#/components/schemas/NetworkDemand"
+        missing:
+          type: array
+          description: Every missing agent type across all networks, sorted and de-duplicated.
+          items:
+            type: string
+        nonAgentic:
+          type: array
+          description: Deployed taskDefinition types that are NOT valid routing tokens (ordinary C8 jobs).
+          items:
+            type: string
+        diversity:
+          $ref: "#/components/schemas/DiversityReport"
+        status:
+          type: string
+          enum: [green, amber, red]
+          description: The overall SLO — worst of the missing-agent signal and the diversity SLO.
     AgenticTranscript:
       type: object
       description: One captured agent session's transcript metadata (H3/#146 transcript store). A durable
@@ -1077,6 +1349,84 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /agentic/vocab:
+    get:
+      operationId: getAgenticVocab
+      summary: The crew vocabulary artifact (enrolment epic 152 slice N1) — the ONE capability→token map a
+        worker resolves its SERVE set against. Returns the networks/roles tree plus the flattened
+        per-token enrolment requirements and the artifact version. Read-only; advisory.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The published vocab view.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/VocabView"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+  /agentic/enrol:
+    post:
+      operationId: enrolAgenticWorker
+      summary: Resolve a worker's declared enrolment capability to its SERVE token set (ADR 0059 revised
+        REGISTER→SERVE, per-worker). Returns the SERVE leaf tokens, the vocab version resolved against,
+        and the liveness lease TTL. Pure/deterministic — idempotent per (app, worker).
+      security:
+        - hookSecret: []
+        - {}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/EnrolRequest"
+      responses:
+        "200":
+          description: The resolved SERVE set for the declared capability.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EnrolResult"
+        "400":
+          description: A malformed enrol body (missing/invalid capability).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+  /agentic/registry:
+    get:
+      operationId: getAgenticRegistry
+      summary: The demand×supply report (enrolment epic 152 slice N1) — deployed demand (the models'
+        taskDefinition leaves) diffed against live supply (the presence registry resolved through the
+        crew vocab), per network, with missing-agent-type reds and the diversity SLO. Read-only; advisory.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The demand×supply report.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RegistryReport"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /agentic/transcripts:
     get:
       operationId: listAgenticTranscripts

package/operations/enrolAgenticWorker.test.ts

@@ -0,0 +1,89 @@
+// Tests for POST /app/api/agentic/enrol → operation `enrolAgenticWorker` (epic #152 / N1 #145).
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import handler from "./enrolAgenticWorker.ts";
+
+const app = { log: noopLog() } as unknown as AppApi;
+
+function input(body: unknown, headers: Record<string, string> = {}) {
+  return {
+    req: { method: "POST", path: "/app/api/agentic/enrol", query: new URLSearchParams(), headers: new Headers(headers), text: async () => JSON.stringify(body) } as any,
+    params: {},
+    query: {},
+    body: body as any,
+  };
+}
+
+test("resolves a declared capability to its SERVE set", async () => {
+  const res = (await handler(input({ capability: { cognition: "planning", weight: 5, family: "frontier" }, instance: "w1" }), app)) as any;
+  assertEquals(res.status, 200);
+  assert(res.body.serve.includes("planning.spar"));
+  assertEquals(res.body.instance, "w1");
+  assert(typeof res.body.demandVersion === "number");
+  assert(typeof res.body.leaseTtl === "number");
+});
+
+test("folds a top-level host into the capability when the capability has none", async () => {
+  const res = (await handler(input({ capability: { cognition: "ci" }, host: "runner-box" }), app)) as any;
+  assertEquals(res.status, 200);
+  // ci.runner has no host requires gate, so the fold does not change the SERVE set — assert it resolves.
+  assert(res.body.serve.includes("ci.runner"));
+});
+
+test("rejects a body with no capability as 400", async () => {
+  const res = (await handler(input({ host: "x" }), app)) as any;
+  assertEquals(res.status, 400);
+});
+
+test("rejects an array body or array capability as 400", async () => {
+  const arrayBody = (await handler(input([]), app)) as any;
+  assertEquals(arrayBody.status, 400);
+  const arrayCapability = (await handler(input({ capability: [] }), app)) as any;
+  assertEquals(arrayCapability.status, 400);
+});
+
+test("rejects non-string optional fields (host / capability.host / instance) as 400", async () => {
+  const badHost = (await handler(input({ capability: { cognition: "ci" }, host: 42 }), app)) as any;
+  assertEquals(badHost.status, 400);
+  const badCapHost = (await handler(input({ capability: { cognition: "ci", host: { nested: true } } }), app)) as any;
+  assertEquals(badCapHost.status, 400);
+  const badInstance = (await handler(input({ capability: { cognition: "ci" }, instance: 7 }), app)) as any;
+  assertEquals(badInstance.status, 400);
+});
+
+test("rejects malformed capability fields (non-string cognition/family, non-number weight) as 400", async () => {
+  const badCognition = (await handler(input({ capability: { cognition: 7 } }), app)) as any;
+  assertEquals(badCognition.status, 400);
+  const badFamily = (await handler(input({ capability: { cognition: "ci", family: ["frontier"] } }), app)) as any;
+  assertEquals(badFamily.status, 400);
+  const badWeight = (await handler(input({ capability: { cognition: "planning", weight: "5" } }), app)) as any;
+  assertEquals(badWeight.status, 400);
+});
+
+test("rejects non-finite capability.weight (NaN/Infinity) as 400", async () => {
+  const nanWeight = (await handler(input({ capability: { cognition: "planning", weight: Number.NaN } }), app)) as any;
+  assertEquals(nanWeight.status, 400);
+  const infWeight = (await handler(input({ capability: { cognition: "planning", weight: Number.POSITIVE_INFINITY } }), app)) as any;
+  assertEquals(infWeight.status, 400);
+});
+
+test("enforces the shared secret when NANO_PR_WEBHOOK_SECRET is set", async () => {
+  // The module captures the secret at load, so re-import a cache-busted copy with the env var set to
+  // exercise the guarded 401 path and the authorized 200 path.
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    const mod = await import(`./enrolAgenticWorker.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const bad = (await guarded(input({ capability: { cognition: "decide" } }), app)) as any;
+    assertEquals(bad.status, 401);
+    const ok = (await guarded(input({ capability: { cognition: "decide" } }, { "x-hook-secret": "s3cr3t" }), app)) as any;
+    assertEquals(ok.status, 200);
+    assert(ok.body.serve.includes("decide"));
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/enrolAgenticWorker.ts

@@ -0,0 +1,91 @@
+// POST /app/api/agentic/enrol → operationId `enrolAgenticWorker` (enrolment epic #152 / N1 #145, ADR
+// 0059 revised). The server side of REGISTER → SERVE, per-worker: a worker declares its enrolment
+// `capability` (cognition / weight / family / host) and gets back the SERVE token set it may serve,
+// the vocab version it was resolved against, and the liveness lease TTL. Pure/deterministic — the
+// same capability always yields the same SERVE, so enrol is idempotent per (app, worker).
+//
+// The ADR 0059 body is `{ capability, host }`; `host` is folded into `capability.host` when the
+// latter is absent (a worker may declare its host either way). Advisory — this resolves and reports,
+// it never places work.
+//
+// The optional shared-secret guard stays HERE (the runtime does not enforce OpenAPI `security`): when
+// NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header. Unset → open.
+import type { Capability } from "@nanobpm/agentic/protocol";
+import { resolveEnrolment } from "../app/agentic/vocab/enrol.ts";
+import { envVar } from "../app/version.ts";
+import type { EnrolResult } from "../nano-generated/api-io.d.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("enrolAgenticWorker", ({ req, body }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("enrolAgenticWorker rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  // The runtime validates a well-formed body against openapi.yaml, but a directly-invoked delegate
+  // (or a missing body) leaves `body` undefined — guard so that becomes a 400, not a 500.
+  if (
+    !body ||
+    typeof body !== "object" ||
+    Array.isArray(body) ||
+    typeof body.capability !== "object" ||
+    body.capability === null ||
+    Array.isArray(body.capability)
+  ) {
+    app.log.warn("enrolAgenticWorker rejected: missing/invalid capability");
+    return { status: 400, body: { error: "a `capability` object is required" } };
+  }
+  // A directly-invoked delegate bypasses the OpenAPI runtime validation, so the optional fields this
+  // operation folds into the capability / echoes back / hands to the resolver can arrive with the
+  // wrong type. Reject that as a 400 rather than passing a malformed Capability into the resolver
+  // (unexpected behavior), emitting a non-string `instance` (500), or matching `requires` predicates
+  // against a non-string cognition/family or non-number weight. Validate every scalar Capability
+  // field (openapi.yaml `Capability`: cognition/family/host strings, weight a number) when present.
+  const optionalStrings: Array<[string, unknown]> = [
+    ["host", body.host],
+    ["capability.host", body.capability.host],
+    ["capability.cognition", body.capability.cognition],
+    ["capability.family", body.capability.family],
+    ["instance", body.instance],
+  ];
+  for (const [name, value] of optionalStrings) {
+    if (value !== undefined && typeof value !== "string") {
+      app.log.warn("enrolAgenticWorker rejected: non-string optional field", { field: name });
+      return { status: 400, body: { error: `\`${name}\` must be a string when provided` } };
+    }
+  }
+  if (
+    body.capability.weight !== undefined &&
+    (typeof body.capability.weight !== "number" || !Number.isFinite(body.capability.weight))
+  ) {
+    app.log.warn("enrolAgenticWorker rejected: non-finite capability.weight");
+    return {
+      status: 400,
+      body: { error: "`capability.weight` must be a finite number when provided" },
+    };
+  }
+
+  // Fold a top-level `host` into the capability when the capability didn't carry its own — a worker
+  // may declare its host either on the capability or beside it (ADR 0059 `{ capability, host }`).
+  const capability: Capability =
+    body.host !== undefined && body.capability.host === undefined
+      ? { ...body.capability, host: body.host }
+      : body.capability;
+
+  const resolved = resolveEnrolment(capability);
+  const result: EnrolResult = {
+    serve: [...resolved.serve],
+    roles: resolved.roles.map((role) => {
+      const out: EnrolResult["roles"][number] = { token: role.token, seatsDistinctFamily: role.seatsDistinctFamily };
+      if (role.weight !== undefined) out.weight = role.weight;
+      return out;
+    }),
+    demandVersion: resolved.demandVersion,
+    leaseTtl: resolved.leaseTtl,
+  };
+  if (body.instance !== undefined) result.instance = body.instance;
+
+  app.log.info("agentic enrol resolved", { instance: body.instance, serve: result.serve, family: capability.family });
+  return { status: 200, body: result };
+});

package/operations/getAgenticRegistry.test.ts

@@ -0,0 +1,53 @@
+// Tests for GET /app/api/agentic/registry → operation `getAgenticRegistry` (epic #152 / N1 #145).
+//
+// The report's computation is exercised exhaustively over injected demand/supply in
+// `app/agentic/vocab/demand-report.test.ts`. Here we assert the operation returns a 200 with a
+// well-formed report shape. The demand read degrades gracefully (no engine → supply-only), so the
+// assertions tolerate `demandUnavailable` being either true or false — no live-engine dependency.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import handler from "./getAgenticRegistry.ts";
+
+const app = { log: noopLog() } as unknown as AppApi;
+
+function input(headers: Record<string, string> = {}) {
+  return {
+    req: { method: "GET", path: "/app/api/agentic/registry", query: new URLSearchParams(), headers: new Headers(headers), text: async () => "" } as any,
+    params: {},
+    query: {},
+    body: undefined,
+  };
+}
+
+test("returns 200 with a well-formed demand×supply report", async () => {
+  const res = (await handler(input(), app)) as any;
+  assertEquals(res.status, 200);
+  assert(typeof res.body.version === "number");
+  assert(["green", "amber", "red"].includes(res.body.status));
+  assert(Array.isArray(res.body.networks));
+  assert(Array.isArray(res.body.missing));
+  assert(Array.isArray(res.body.nonAgentic));
+  assert(typeof res.body.demandUnavailable === "boolean");
+  assert(["green", "amber", "red"].includes(res.body.diversity.status));
+});
+
+test("shared-secret guard rejects a missing secret when configured", async () => {
+  // The delegate captures the secret at import time, so re-import a cache-busted copy with the env
+  // var set to exercise the guarded 401 path and the authorized 200 path.
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    const mod = await import(`./getAgenticRegistry.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const bad = (await guarded(input(), app)) as any;
+    assertEquals(bad.status, 401);
+    const ok = (await guarded(input({ "x-hook-secret": "s3cr3t" }), app)) as any;
+    assertEquals(ok.status, 200);
+    assert(typeof ok.body.version === "number");
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/getAgenticRegistry.ts

@@ -0,0 +1,25 @@
+// GET /app/api/agentic/registry → operationId `getAgenticRegistry` (enrolment epic #152 / N1 #145, ADR
+// 0056 §8–10, ADR 0059 revised). The demand×supply report: the deployed models' demand (their
+// `taskDefinition` leaves, read from the engine over the C8 v2 REST API) diffed against live supply
+// (the H1 presence registry resolved through the crew vocab), per network, with the missing-agent-type
+// reds and the diversity SLO. Read-only and advisory; it NEVER gates control flow.
+//
+// The engine demand read degrades gracefully: if the engine is unreachable the report is computed
+// supply-only with `demandUnavailable: true` (never a hard 5xx — the report is advisory).
+//
+// The optional shared-secret guard stays HERE (the runtime does not enforce OpenAPI `security`): when
+// NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header. Unset → open.
+import { computeRegistryReport, toWireReport } from "../app/agentic/vocab/demand-report.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("getAgenticRegistry", async ({ req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("getAgenticRegistry rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const report = await computeRegistryReport(app.log);
+  return { status: 200, body: toWireReport(report) };
+});