wip(spec): ExecutionStepMetrics failure slot + FlowRunSummary.failed fold reconciliation (#15617 spec half)

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F8SRGcf2eKTK7RRpWCGxwf

Author: claude

.changeset/execution-step-metrics-failure-slot.md

@@ -0,0 +1,59 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec): `ExecutionStepMetrics` gains an optional `failures` slot, and `FlowRunSummary.failed` is declared as the fold INCLUDING what a delegating node rolled up from its child — the rule `acted` already follows (maintainer ruling 2026-09-06 on #15617, spec half)
+
+Additive. Nothing an author writes is renamed, retired or narrowed; no accept
+set shrinks. One optional key is declared on a runtime-produced schema and the
+prose of a published contract is reconciled with itself.
+
+**What was wrong.** `FlowRunSummary` said two things about `failed`. Its
+header paragraph declared that a `subflow` node rolls its child run's totals
+up into the parent — "this summary answers *what did this run cause*" — while
+the field itself declared `failed = Σ nodes[].failures`, a fold over the
+parent's own node executions. For a parent that delegates its rows to a
+`subflow` (or a `map` item) those give different answers, and the engine could
+only satisfy the second one: `ExecutionStepMetrics` carried `selected` /
+`acted` / `unmeasuredEffect` and no failure slot, so a child's contained
+failures had no path into the parent's fold. Measured on the real engine by
+the services seat (#15617): parent `loop { subflow(child) }` → parent
+`failed=0` while the five child summaries carried `failed=[0,0,0,0,1]` —
+`acted` rolled up, `failed` did not.
+
+**What this declares.**
+
+- `ExecutionStepMetrics.failures` (optional, integer ≥ 0): node executions
+  that failed inside a child run this execution delegated to and went on from
+  — a `subflow` child or a `map` item whose run COMPLETED while containing
+  failures, i.e. the child's `summary.failed`, rolled up. It folds into the
+  delegating node's `nodes[].failures` and so into the run-level `failed`, by
+  exactly the path the child's writes take into `acted`. Absent means the
+  step delegated nothing or its child tracked no count — not zero.
+- It is NOT the step's own outcome. A step that failed is `status: 'failure'`
+  and counts once through `nodes[].failures`, as before; a child that FAILED
+  rather than contained is precisely that step failure — its own `failed`
+  stays on the child's run row and nothing rides up, so one failure is never
+  counted twice. The control the card measured (a failing child → parent
+  `failed=1`) keeps counting exactly as today.
+- `FlowRunSummary.failed` is declared, at the field, as the fold of
+  `nodes[].failures` INCLUDING what a delegating node rolled up; the
+  `FlowRunNodeSummary.failures` describe names the roll-up path, and its
+  `status` describe states that a delegating node whose child contained
+  failures reads `success` beside `failures > 0` — status is judged on the
+  node's own executions.
+
+**What this does not do yet.** This is the contract half of a two-lane
+landing (contract first). No producer populates `failures` in this release:
+`subflow-node.ts` and the `map` node roll the child's contained failures into
+the slot in the services half, #16314, and only then does a parent's
+`failed` start counting them. Until that lands, every `ExecutionStepMetrics`
+the engine emits is byte-identical to today's, `failed` is numerically what it
+was, and the flow-run reference page keeps the narrowed wording PR #15609
+shipped ("node executions **of this run**") on purpose — it is widened when
+both halves are in.
+
+**Consumers.** A reader of `ExecutionStepMetrics` sees one more optional
+number and nothing else changes shape; a consumer that already sums
+`nodes[].failures` to cross-check `failed` keeps agreeing with it, because the
+fold is unchanged — the roll-up enters the per-node array, not beside it.

packages/spec/src/automation/execution.test.ts

@@ -9,6 +9,8 @@ import {
   ConcurrencyPolicySchema,
   ScheduleStateSchema,
   FlowRunSummarySchema,
+  FlowRunNodeSummarySchema,
+  ExecutionStepMetricsSchema,
 } from './execution.zod';
 
 // ==========================================
@@ -47,6 +49,39 @@ describe('ExecutionStatus', () => {
 // Execution Step Log
 // ==========================================
 
+describe('ExecutionStepMetricsSchema', () => {
+  // #15617 — the failure slot a delegating node rolls its child's contained
+  // failures through. `z.object` STRIPS an undeclared key on parse, so keeping
+  // the value through the parse is what proves the declaration exists.
+  it('declares `failures` — a delegating step keeps its child\'s contained-failure count through the parse', () => {
+    const metrics = ExecutionStepMetricsSchema.parse({ selected: 5, acted: 4, failures: 1 });
+    expect(metrics.failures).toBe(1);
+    expect(metrics).toEqual({ selected: 5, acted: 4, failures: 1 });
+  });
+
+  it('leaves `failures` absent on a step that delegated nothing — absent is not zero, and is not defaulted', () => {
+    const metrics = ExecutionStepMetricsSchema.parse({ selected: 1, acted: 1 });
+    expect(metrics.failures).toBeUndefined();
+    expect(Object.keys(metrics)).not.toContain('failures');
+  });
+
+  it('rejects a negative or fractional `failures`', () => {
+    expect(ExecutionStepMetricsSchema.safeParse({ failures: -1 }).success).toBe(false);
+    expect(ExecutionStepMetricsSchema.safeParse({ failures: 1.5 }).success).toBe(false);
+  });
+
+  it('says at the point of use which shape it is for, and that it is not the step\'s own outcome', () => {
+    // The carve-out has to be readable where a consumer reads the field, not
+    // only in a paragraph above the schema: the describe names both delegating
+    // node kinds and separates the slot from the step's own `status`.
+    const doc = ExecutionStepMetricsSchema.shape.failures.description ?? '';
+    expect(doc).toContain('`subflow`');
+    expect(doc).toContain('`map`');
+    expect(doc).toContain('`summary.failed`');
+    expect(doc).toContain('NOT this execution');
+  });
+});
+
 describe('ExecutionStepLogSchema', () => {
   it('should accept a valid step log', () => {
     const step = ExecutionStepLogSchema.parse({
@@ -157,6 +192,24 @@ describe('ExecutionStepLogSchema', () => {
     expect(step.branch).toBe(1);
   });
 
+  it('a `success` step that delegated to a child carries the child\'s contained failures on `metrics.failures` (#15617)', () => {
+    // The card's shape: `loop { subflow(child) }`, one iteration whose child
+    // COMPLETED while losing a row. The subflow step itself succeeded — the
+    // failure is the child's, contained — so `status` stays `success` and the
+    // count rides on the metrics, not on the step's own outcome.
+    const step = ExecutionStepLogSchema.parse({
+      nodeId: 'call',
+      nodeType: 'subflow',
+      status: 'success',
+      startedAt: '2026-09-05T00:00:00Z',
+      iteration: 4,
+      regionKind: 'loop-body',
+      metrics: { selected: 1, acted: 0, failures: 1 },
+    });
+    expect(step.status).toBe('success');
+    expect(step.metrics?.failures).toBe(1);
+  });
+
   it('`branch: 0` — the first branch — survives the parse as 0', () => {
     // Zero is a real index; a falsy-check anywhere on the way would drop it.
     const step = ExecutionStepLogSchema.parse({
@@ -350,6 +403,68 @@ describe('FlowRunSummarySchema', () => {
     expect(summary.failed).toBe(summary.nodes.reduce((sum, node) => sum + node.failures, 0));
   });
 
+  it('`failed` is the fold INCLUDING what a delegating node rolled up from its child — the card\'s measured shape, as ruled (#15617)', () => {
+    // Parent `loop { subflow(child) }` over five rows; the child COMPLETED on
+    // every iteration and contained one failure on the last. The subflow node
+    // succeeded five times — `status: success`, its own executions never
+    // failed — and carries the rolled-up count on `failures`, exactly as it
+    // carries the child's writes on `acted`. The fold then sees it, so the
+    // parent no longer reads `failed: 0` while a child lost a row.
+    const summary = FlowRunSummarySchema.parse({
+      selected: 5, acted: 4, skipped: 0, failed: 1,
+      nodes: [
+        { nodeId: 'each', nodeType: 'loop', status: 'success' as const, runs: 1, failures: 0, skipped: 0 },
+        { nodeId: 'call', nodeType: 'subflow', status: 'success' as const, runs: 5, failures: 1, skipped: 0, selected: 5, acted: 4 },
+      ],
+      gates: [],
+    });
+    expect(summary.failed).toBe(1);
+    expect(summary.failed).toBe(summary.nodes.reduce((sum, node) => sum + node.failures, 0));
+    // Declared shape: a delegating node's status is judged on its OWN
+    // executions, so `success` beside `failures: 1` is the contract, not a
+    // contradiction.
+    const call = summary.nodes.find((node) => node.nodeId === 'call');
+    expect(call?.status).toBe('success');
+    expect(call?.failures).toBe(1);
+  });
+
+  it('the control keeps counting as before: a child that FAILED is the delegating step\'s own failure, counted once (#15617)', () => {
+    // Same parent, but the child FAILED on the last row rather than containing
+    // the failure. That is the subflow step's own `status: failure` — one
+    // execution failed — and nothing rides up on top of it: the child's own
+    // `failed` stays on the child's run row, so the parent reads 1, not 2.
+    const summary = FlowRunSummarySchema.parse({
+      selected: 5, acted: 4, skipped: 0, failed: 1,
+      nodes: [
+        { nodeId: 'each', nodeType: 'loop', status: 'success' as const, runs: 1, failures: 0, skipped: 0 },
+        { nodeId: 'call', nodeType: 'subflow', status: 'failure' as const, runs: 5, failures: 1, skipped: 0, selected: 5, acted: 4 },
+      ],
+      gates: [],
+    });
+    expect(summary.failed).toBe(1);
+    expect(summary.failed).toBe(summary.nodes.reduce((sum, node) => sum + node.failures, 0));
+  });
+
+  it('declares the roll-up at the point of use — the field describes say so, not only the paragraph above the schema (#15617)', () => {
+    // Triage's explicit failure mode for this card: a reconciliation that
+    // leaves `failed`'s own `.describe()` saying the narrow thing. A consumer
+    // reads the field's description, so the widened rule has to be there.
+    const failedDoc = FlowRunSummarySchema.shape.failed.description ?? '';
+    expect(failedDoc).toContain('a fold of `nodes[].failures`');
+    expect(failedDoc).toContain('INCLUDING');
+    expect(failedDoc).toContain('`subflow`');
+    expect(failedDoc).toContain('`map`');
+    expect(failedDoc).toContain('what did this run cause');
+
+    const nodeFailuresDoc = FlowRunNodeSummarySchema.shape.failures.description ?? '';
+    expect(nodeFailuresDoc).toContain('`metrics.failures`');
+    expect(nodeFailuresDoc).toContain('the run-level `failed` is the sum of this across `nodes`');
+
+    const nodeStatusDoc = FlowRunNodeSummarySchema.shape.status.description ?? '';
+    expect(nodeStatusDoc).toContain('OWN executions');
+    expect(nodeStatusDoc).toContain('`failures > 0`');
+  });
+
   it('leaves `failed` absent on a run that never tracked it — absent is not zero, and is not defaulted', () => {
     // Same convention as `unmeasured`: a run recorded before the field existed
     // did not count contained failures, and a `0` here would tell an operator