@nanobpm/nano-workforce 0.85.3 → 0.87.0

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

@@ -0,0 +1,49 @@
+// Tests for the enrolment resolver (epic #152 / N1 #145). The server side of REGISTER → SERVE:
+// a declared capability resolves to a deterministic SERVE set, the vocab version, and a lease TTL.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { Capability } from "@nanobpm/agentic/protocol";
+import { CREW_VOCAB_VERSION } from "./crew-vocab.ts";
+import { DEFAULT_LEASE_TTL_MS, resolveEnrolment } from "./enrol.ts";
+
+const planner: Capability = { cognition: "planning", weight: 5, family: "frontier", host: "h1" };
+
+test("resolves a capability to its SERVE token set with the vocab version and a lease TTL", () => {
+  const result = resolveEnrolment(planner);
+  assert(result.serve.includes("planning.spar"));
+  assertEquals(result.demandVersion, CREW_VOCAB_VERSION);
+  // No presence registry is mounted in a unit test, so the lease falls back to the default TTL.
+  assertEquals(result.leaseTtl, DEFAULT_LEASE_TTL_MS);
+});
+
+test("the resolution is deterministic (idempotent per worker)", () => {
+  assertEquals(resolveEnrolment(planner).serve, resolveEnrolment(planner).serve);
+});
+
+test("roles provenance carries the SERVE tokens with their diversity flag", () => {
+  const result = resolveEnrolment(planner);
+  const spar = result.roles.find((r) => r.token === "planning.spar");
+  assert(spar !== undefined);
+  assertEquals(spar.seatsDistinctFamily, true);
+  // Every SERVE token has a matching role entry.
+  assertEquals(
+    [...result.serve].sort(),
+    result.roles.map((r) => r.token).sort(),
+  );
+});
+
+test("a capability that fills no role gets an empty SERVE set", () => {
+  const result = resolveEnrolment({ cognition: "unknown" });
+  assertEquals(result.serve, []);
+  assertEquals(result.roles, []);
+});
+
+test("serve is sorted and de-duplicated, and roles are sorted by token", () => {
+  const result = resolveEnrolment(planner);
+  assertEquals([...result.serve], [...result.serve].sort((a, b) => a.localeCompare(b)));
+  assertEquals(new Set(result.serve).size, result.serve.length);
+  assertEquals(
+    result.roles.map((r) => r.token),
+    result.roles.map((r) => r.token).sort((a, b) => a.localeCompare(b)),
+  );
+});

package/app/agentic/vocab/enrol.ts

@@ -0,0 +1,74 @@
+// nano-workforce — the enrolment resolver (epic #152 / N1 #145, ADR 0059 revised).
+//
+// The server side of the REGISTER → SERVE handshake, over the ADR 0059 REST door `POST
+// /agentic/enrol`: 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. Resolution is a pure fold over the crew vocab (`@nanobpm/agentic/vocab`), so it
+// is DETERMINISTIC and idempotent per (app, worker): the same capability always yields the same
+// SERVE (ADR 0059 revised — enrolment is per-worker; a machine may run several differently-capable
+// workers, each enrolling on its own).
+//
+// This is the HTTP half of the handshake (the ADR 0059 endpoint contract). The live WS SERVE stream
+// rides the agentic channel's `register` family, which the H1 presence slice owns; this resolver is
+// the shared, connection-agnostic core both can call.
+
+import type { Capability } from "@nanobpm/agentic/protocol";
+import type { Resolution } from "@nanobpm/agentic/vocab";
+import { currentPresenceRegistry } from "../families/presence.family.ts";
+import { CREW_VOCAB_VERSION, crewResolver } from "./crew-vocab.ts";
+
+/**
+ * The default liveness lease TTL (ms) handed back on enrol when no live presence registry is mounted
+ * to source the real TTL from. A worker refreshes its lease with a heartbeat inside this window.
+ */
+export const DEFAULT_LEASE_TTL_MS = 30_000;
+
+/** One matched role in an enrolment resolution — provenance for the worker and the cockpit. */
+export interface EnrolledRole {
+  /** The leaf routing token the role resolves to. */
+  readonly token: string;
+  /** The role's cognition weight, if declared. */
+  readonly weight?: number;
+  /** Whether the role opted into strict distinct-family seating (diversity SLO). */
+  readonly seatsDistinctFamily: boolean;
+}
+
+/** The result of enrolling a declared capability against the crew vocab. */
+export interface EnrolmentResult {
+  /** The SERVE token set — sorted, de-duplicated leaf tokens the worker may serve. */
+  readonly serve: readonly string[];
+  /** The matched roles (sorted by token) the SERVE tokens came from. */
+  readonly roles: readonly EnrolledRole[];
+  /** The crew-vocab version the capability was resolved against. */
+  readonly demandVersion: number;
+  /** The liveness lease TTL in ms the worker must heartbeat within. */
+  readonly leaseTtl: number;
+}
+
+/** The current liveness lease TTL — the live presence TTL when mounted, else {@link DEFAULT_LEASE_TTL_MS}. */
+export function leaseTtlMs(): number {
+  return currentPresenceRegistry()?.ttlMs ?? DEFAULT_LEASE_TTL_MS;
+}
+
+/**
+ * Resolve a declared enrolment capability to its SERVE set. Pure and deterministic: the same
+ * capability always yields the same result, so enrol is idempotent per worker.
+ */
+export function resolveEnrolment(capability: Capability): EnrolmentResult {
+  const resolver = crewResolver();
+  const resolution: Resolution = resolver.resolve(capability);
+  const roles: EnrolledRole[] = resolution.roles
+    .map((role) => {
+      const out: EnrolledRole = { token: role.token, seatsDistinctFamily: role.seatsDistinctFamily };
+      if (role.weight !== undefined) return { ...out, weight: role.weight };
+      return out;
+    })
+    .sort((a, b) => a.token.localeCompare(b.token));
+  const serve = [...new Set(resolution.tokens)].sort((a, b) => a.localeCompare(b));
+  return {
+    serve,
+    roles,
+    demandVersion: CREW_VOCAB_VERSION,
+    leaseTtl: leaseTtlMs(),
+  };
+}

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;
+  }
+});