@nanobpm/nano-workforce 0.65.0 → 0.66.0

package/AGENTS.md

@@ -142,13 +142,25 @@ instead of rediscovering them:
   per-child isolation in the testkit). Only vars read by an in-subprocess gateway
   need this — output-only vars (e.g. `summary`, `pr`) are fine.
 
-## Data envelopes are scalar-only
-
-`nano:dataEnvelope` shapes support only **scalar** `nano:extend` types
-(`string`, `integer`, `datetime`, `boolean`) — **not arrays**. When a message
-must carry a list (e.g. failing check names), join it to a scalar (e.g.
-`\n`-separated) in the publisher before it crosses the envelope, and split it on
-the far side if needed.
+## Data envelopes: message payloads are scalar-only; worker I/O shapes support arrays
+
+Two different `nano:dataEnvelope` uses have different rules — don't conflate them:
+
+- **Message payloads are scalar-only.** A `nano:dataEnvelope` that crosses the
+  engine's message correlation supports only **scalar** `nano:extend` types
+  (`string`, `integer`, `datetime`, `boolean`) — **not arrays**. When a message
+  must carry a list (e.g. failing check names), join it to a scalar (e.g.
+  `\n`-separated) in the publisher before it crosses the envelope, and split it on
+  the far side if needed.
+- **Worker job-I/O shapes support `list="true"` arrays.** A service task's
+  `io.nanobpm.dataEnvelope.in`/`.out` shape is codegen/typing-only (no runtime
+  filtering), so `nano:extend … list="true"` (scalar arrays, e.g. `dependsOn`)
+  and `nano:reference … list="true"` (object arrays) are supported end-to-end and
+  derive to `T[]` in the generated types (per #211 — e.g.
+  `RecordPlanIn.tasks: RecordPlanTask[]`, `RecordWaveIn.waveResults`). Prefer
+  deriving a worker's array inputs from the model this way over a hand-typed
+  `interface In`; don't "fix" a modelled `list="true"` array back to a joined
+  scalar.
 
 ## Urban page runtime: rendering primitives are not JS-truthy
 

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.66.0](https://github.com/nanobpm/nano-workforce/compare/v0.65.0...v0.66.0) (2026-08-14)
+
+
+### Features
+
+* derive record-plan/record-wave/record-trial-merge array inputs from the model ([#212](https://github.com/nanobpm/nano-workforce/issues/212)) ([95f1694](https://github.com/nanobpm/nano-workforce/commit/95f16944918b99107e784eed5ab69a5962365ec4)), closes [#211](https://github.com/nanobpm/nano-workforce/issues/211) [#211](https://github.com/nanobpm/nano-workforce/issues/211) [#211](https://github.com/nanobpm/nano-workforce/issues/211) [#211](https://github.com/nanobpm/nano-workforce/issues/211)
+
 # [0.65.0](https://github.com/nanobpm/nano-workforce/compare/v0.64.0...v0.65.0) (2026-08-13)
 
 

package/SPEC.md

@@ -488,9 +488,18 @@ Start(issue) → plan → record-plan → implement (parallel MI) → record-res
   it raises a non-retryable `NO_WORK_DISPATCHED` incident instead of completing
   green — a no-op run must not masquerade as success (issue #86).
 
-**Payloads are untyped** (no `nano:shapes`/`io.nanobpm.dataEnvelope`): the vocab is
-scalar-only and cannot express the `tasks`/`results` lists, so the workers self-type
-`job.variables` inline (like `finalize`). `urban gen` still emits the four task types.
+**App-worker payloads are typed from the model.** Each `pr.*` service task
+(`record-plan`, `record-wave`, `record-trial-merge`, `select-wave`,
+`record-plan-review`, `resolve-trial-attention`, `record-results`, …) carries an
+`io.nanobpm.dataEnvelope.in` shape whose `nano:shapes` express the `tasks`/`results`
+lists directly: worker job-I/O envelopes support `list="true"` arrays — both
+`nano:extend … list="true"` scalar arrays (e.g. `dependsOn`, `conflicts`) and
+`nano:reference … list="true"` object arrays (e.g. `RecordPlanIn.tasks`,
+`RecordWaveIn.waveResults`) — which derive to `T[]` in the generated task types
+(per #211). This job-I/O shape is codegen/typing-only (no runtime filtering); the
+`scalar-only` constraint applies only to **message payload** envelopes that cross
+correlation at runtime, not to these worker in/out shapes. The **agent** tasks
+(`senior:*`) still self-type `job.variables` inline (like `finalize`).
 
 **Domain model** (`db/migrations/004_planning.sql`): `plans` (one row per issue) +
 `plan_tasks` (one row per slice, tracking its `status`/`pr_key`/`summary`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.65.0",
+  "version": "0.66.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/resources/processes/plan-fanout.bpmn

@@ -12,6 +12,55 @@
           <nano:extend name="repo" type="string" />
           <nano:extend name="baseBranch" type="string" />
         </nano:shape>
+        <nano:shape id="RecordPlanTask" name="Record plan — raw planner task">
+          <nano:extend name="id" type="string" optional="true" />
+          <nano:extend name="title" type="string" optional="true" />
+          <nano:extend name="prompt" type="string" optional="true" />
+          <nano:extend name="dependsOn" type="string" list="true" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordPlanIn" name="Record plan — input">
+          <nano:extend name="planKey" type="string" />
+          <nano:reference name="tasks" ref="RecordPlanTask" list="true" />
+          <nano:extend name="note" type="string" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordWaveTaskRef" name="Record wave — task ref">
+          <nano:extend name="id" type="string" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordWaveDelta" name="Record wave — task delta">
+          <nano:extend name="contractChange" type="string" optional="true" />
+          <nano:extend name="newlyTouches" type="string" list="true" optional="true" />
+          <nano:extend name="affectsTasks" type="string" list="true" optional="true" />
+          <nano:extend name="constraint" type="string" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordWaveResult" name="Record wave — agent result">
+          <nano:extend name="status" type="string" optional="true" />
+          <nano:extend name="summary" type="string" optional="true" />
+          <nano:extend name="pr" type="string" optional="true" />
+          <nano:extend name="delta" type="RecordWaveDelta" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordWaveIn" name="Record wave — input">
+          <nano:extend name="planKey" type="string" />
+          <nano:extend name="currentWave" type="integer" />
+          <nano:extend name="waveCount" type="integer" />
+          <nano:reference name="waveTasks" ref="RecordWaveTaskRef" list="true" />
+          <nano:reference name="waveResults" ref="RecordWaveResult" list="true" />
+        </nano:shape>
+        <nano:shape id="RecordTrialMergeHead" name="Record trial merge — open head">
+          <nano:extend name="repo" type="string" />
+          <nano:extend name="prNumber" type="integer" />
+          <nano:extend name="headRef" type="string" optional="true" />
+          <nano:extend name="headSha" type="string" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordTrialMergeIn" name="Record trial merge — input">
+          <nano:extend name="planKey" type="string" />
+          <nano:extend name="currentWave" type="integer" optional="true" />
+          <nano:extend name="trialMergeWave" type="integer" optional="true" />
+          <nano:reference name="waveOpenHeads" ref="RecordTrialMergeHead" list="true" />
+          <nano:extend name="result" type="string" optional="true" />
+          <nano:extend name="conflicts" type="string" list="true" optional="true" />
+          <nano:extend name="failing" type="string" list="true" optional="true" />
+          <nano:extend name="summary" type="string" optional="true" />
+        </nano:shape>
         <nano:shape id="RecordPlanReviewIn" name="Record plan review — input">
           <nano:extend name="planKey" type="string" />
           <nano:extend name="approved" type="boolean" optional="true" />
@@ -68,6 +117,9 @@
     <bpmn:serviceTask id="record-plan" name="Record plan &#38; levelize">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.record-plan" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RecordPlanIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_toRecordPlan</bpmn:incoming>
       <bpmn:outgoing>f_toReviewPlan</bpmn:outgoing>
@@ -215,6 +267,9 @@
     <bpmn:serviceTask id="record-wave" name="Record wave &#38; hand off">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.record-wave" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RecordWaveIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_toRecordWave</bpmn:incoming>
       <bpmn:outgoing>f_toTrialNeeded</bpmn:outgoing>
@@ -246,6 +301,9 @@
     <bpmn:serviceTask id="record-trial-merge" name="Record trial merge">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.record-trial-merge" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RecordTrialMergeIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_toRecordTrialMerge</bpmn:incoming>
       <bpmn:outgoing>f_toGwTrial</bpmn:outgoing>

package/workers/record-plan/worker.ts

@@ -18,21 +18,12 @@
 import type { AppJobHandler } from "@nanobpm/urban";
 import { planTaskDeps, planTasks } from "../../app/plan.ts";
 import { computeWaves, WaveError, type WaveTask } from "../../app/waves.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface RawTask {
-  id?: unknown;
-  title?: unknown;
-  prompt?: unknown;
-  dependsOn?: unknown;
-}
-// NOTE (issue #211): this worker reads an ARRAY input (`tasks: RawTask[]`), which the scalar-only
-// `nano:dataEnvelope` cannot express, so it keeps a hand-written `interface In` pending a decision
-// on extending the envelope schema to arrays. See the PR body's "array inputs" escalation.
-interface In extends Record<string, unknown> {
-  planKey: string;
-  tasks?: RawTask[];
-  note?: string;
-}
+// Input typed off the model data envelope (`RecordPlanIn` in plan-fanout.bpmn) — ADR 0040. The
+// `tasks[]` array field is a `nano:reference` to the `RecordPlanTask` shape (`list="true"`), so it
+// resolves to `RecordPlanTask[]` with no hand-written interface.
+type In = WorkerInputs["pr.record-plan"];
 interface NormalTask {
   id: string;
   title: string;

package/workers/record-trial-merge/worker.ts

@@ -8,21 +8,13 @@ import {
   trialMergeDecision,
   trialMergeTaskId,
 } from "../../app/trialMerge.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-// NOTE (issue #211): this worker reads ARRAY inputs (`waveOpenHeads`, `conflicts`, `failing`), which
-// the scalar-only `nano:dataEnvelope` cannot express, so it keeps a hand-written `interface In`
-// pending a decision on extending the envelope schema to arrays. See the PR body's "array inputs"
-// escalation.
-interface In extends Record<string, unknown> {
-  planKey: string;
-  currentWave?: unknown;
-  trialMergeWave?: unknown;
-  waveOpenHeads?: unknown;
-  result?: unknown;
-  conflicts?: unknown;
-  failing?: unknown;
-  summary?: unknown;
-}
+// Input typed off the model data envelope (`RecordTrialMergeIn` in plan-fanout.bpmn) — ADR 0040.
+// The `waveOpenHeads[]` array field is a `nano:reference` to the `RecordTrialMergeHead` shape, and
+// `conflicts[]` / `failing[]` are scalar `list="true"` extends, so all three resolve from the model
+// with no hand-written interface.
+type In = WorkerInputs["pr.record-trial-merge"];
 interface Out extends Record<string, unknown> {
   trialMergeRed: boolean;
   question?: string;

package/workers/record-wave/worker.ts

@@ -28,26 +28,13 @@ import {
 import { parsePr, submitPr } from "../../app/service.ts";
 import { parseTaskDelta, readTaskDeltas, recordTaskDelta } from "../../app/taskDelta.ts";
 import { shouldRunTrialMerge, type TrialMergeHead } from "../../app/trialMerge.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface Result {
-  status?: unknown;
-  summary?: unknown;
-  pr?: unknown;
-  delta?: unknown;
-}
-interface WaveTaskIn {
-  id?: unknown;
-}
-// NOTE (issue #211): this worker reads ARRAY inputs (`waveTasks[]`, `waveResults[]`), which the
-// scalar-only `nano:dataEnvelope` cannot express, so it keeps a hand-written `interface In` pending
-// a decision on extending the envelope schema to arrays. See the PR body's "array inputs" escalation.
-interface In extends Record<string, unknown> {
-  planKey: string;
-  currentWave: number;
-  waveCount: number;
-  waveTasks?: WaveTaskIn[];
-  waveResults?: Result[];
-}
+// Input typed off the model data envelope (`RecordWaveIn` in plan-fanout.bpmn) — ADR 0040. The
+// `waveTasks[]` / `waveResults[]` array fields are `nano:reference`s to the `RecordWaveTaskRef` /
+// `RecordWaveResult` shapes (`list="true"`), so they resolve to `<Shape>[]` with no hand-written
+// interface.
+type In = WorkerInputs["pr.record-wave"];
 interface Out extends Record<string, unknown> {
   currentWave: number;
   hasMoreWaves: boolean;