fix(automation): report a subflow parent stranded by a failed up-bubble at error, not warn

An approval hosted in a subflow child was driven end to end for the first time
(the card was filed NOT MEASURED). It reproduces: the child's resume completes,
`bubbleToParent` resumes the parent, the parent's downstream node throws, and
`resumeInternal` answers the #13937 stranded exit — `{ success: false, status:
'stranded' }`, no `code` — which consumed the parent's suspension, journalled a
repair snapshot and recorded the run `failed`. Nothing in the engine moves it
again; only `restoreConsumedSuspension` can.

The seam's #4632 verdict was FUNCTIONAL for the whole arm, on the enumeration
"the parent either failed terminally or stays visibly parked and resumable".
The measurement falsifies it: a stranded parent is neither, the approval row is
durably terminal, and the decision door answered its caller success. That is
AGENTS.md's DURABILITY class verbatim, and the rule's third legal answer (a
failure handed to the CALLER) does not apply because no caller is told.

The level is now graded by the engine's own discriminator, never by this seam's
guess: `status === 'stranded'` reports at `error`, naming the run and the repair
verb; every other exit stays `warn` unchanged, because escalating a parent that
is still parked is how `error` becomes unreadable.

⚠️ The log half only. What the child's resumer — and through it the approvals
decision door — is TOLD still reads as full success; making that truthful moves
a public contract and is #15556's open decision.

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

Author: claude

.changeset/subflow-bubble-stranded-parent.md

@@ -0,0 +1,22 @@
+---
+'@objectstack/service-automation': patch
+---
+
+automation: a subflow parent left STRANDED by a failed up-bubble is reported at `error`, not `warn`
+
+When an approval (or any pause) sits inside a subflow child, resuming the child
+bubbles up to the parent. If the parent's own continuation then fails on the
+engine's stranded exit — its suspension consumed, a repair snapshot journalled,
+the run recorded `failed` — nothing but a `warn` said so, while the child's
+resumer (an approvals decision door, a wait timer) was told the resume
+succeeded. Persisted state and runtime state disagree and nothing looks broken
+from the outside, which is the durability class.
+
+`bubbleToParent` now grades that record by the engine's own
+`AutomationResult.status` discriminator: `'stranded'` is reported at `error`,
+naming the parent run and the `restoreConsumedSuspension` verb that repairs it.
+Every other parent-resume failure — a concurrent resume, an unreachable store,
+a thrown resume — stays at `warn` unchanged, because on those exits the parent
+is still parked and resumable.
+
+⚠️ This is the log half only. What the child's resumer is told is unchanged.

…rovals/src/subflow-bubble-strand.test.ts …c/subflow-hosted-approval-strand.test.tspackages/plugins/plugin-approvals/src/subflow-bubble-strand.test.ts renamed to packages/plugins/plugin-approvals/src/subflow-hosted-approval-strand.test.ts packages/plugins/plugin-approvals/src/subflow-bubble-strand.test.ts renamed to packages/plugins/plugin-approvals/src/subflow-hosted-approval-strand.test.ts

@@ -1,10 +1,44 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * REPRODUCTION PROBE for #15556 — an approval hosted inside a SUBFLOW CHILD.
- * Not a deliverable yet: this file exists to measure what the decision door
- * actually answers when `bubbleToParent` fails, with its controls in the
- * same run.
+ * #15556 — the REPRODUCTION: an approval hosted inside a SUBFLOW CHILD, whose
+ * parent's continuation fails.
+ *
+ * The card was filed NOT MEASURED — the seam and its swallowing `catch` were
+ * found by reading `engine.ts`, and nobody had driven the composition. This
+ * file is that drive, with its controls in the same run, and it reproduces.
+ *
+ * ## The composition
+ *
+ * `deal_parent` parks at a `subflow` node; the child `deal_approval` parks at
+ * an `approval` node, so the approvals row names the CHILD run. The decision
+ * door resumes the child, the child completes, `bubbleToParent` resumes the
+ * parent, and the parent's own downstream node throws.
+ *
+ * ## What is measured, and what is only characterised
+ *
+ * MEASURED FACT, now fixed engine-side: the parent lands on the engine's
+ * stranded exit — `{ success: false, status: 'stranded' }`, journalled and
+ * repairable — and `bubbleToParent` logged that at `warn`. The level is now
+ * graded by that discriminator (`subflow-bubble-strand-log-level.test.ts` in
+ * `service-automation` holds the pins, both directions).
+ *
+ * ⚠️ CHARACTERISED, NOT BLESSED: the decision door still answers full success.
+ * Its resume-facing answer is IDENTICAL to the one a healthy composition
+ * produces, so no caller can tell the two apart, and the `runId` it hands back
+ * names the CHILD — which completed — never the stranded parent. Making that
+ * truthful moves a public contract (`AutomationResult`,
+ * `ApprovalDecisionResult`) and is #15556's open decision, the sibling one
+ * level up of the #13807 ruling (maintainer 2026-09-04, decision batch #37).
+ * ⛔ The assertions below record what the door does TODAY; whatever ruling
+ * lands must turn them red on purpose.
+ *
+ * ## The control that makes the reading trustworthy
+ *
+ * `CONTROL` drives the #13807 shape through the SAME door in the same run — no
+ * subflow, the child's own branch throws — and the door throws `RESUME_FAILED`
+ * with its stranded envelope. So the absence of a throw above is a fact about
+ * the composition, not about a mis-wired harness.
  */
 
 import { describe, it, expect, beforeEach } from 'vitest';
@@ -16,6 +50,17 @@ import { registerApprovalNode } from './approval-node.js';
 
 const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as any;
 
+/** The card's own downstream failure text, in shape. */
+const DOWNSTREAM_FAILURE = 'update_record(crm_leave_request) failed: Record 9SEmlyRfw8D9-J7Z not found';
+
+/**
+ * The resume-facing answer a caller reads, minus the run id. Asserted by BOTH
+ * the stranded composition and the healthy one — that shared literal, and not
+ * a value smuggled between tests, is what carries the claim that the two are
+ * indistinguishable at the door.
+ */
+const FULL_SUCCESS = { finalized: true, decision: 'approve', resumed: true, resumeError: undefined };
+
 /** Records every level so the "only artefact is a log line" claim is measurable. */
 function recordingLogger() {
   const lines: Array<{ level: string; msg: string; meta?: unknown }> = [];
@@ -116,7 +161,7 @@ const PARENT = {
   ],
 };
 
-describe('#15556 probe — approval inside a subflow child, parent bubble fails', () => {
+describe('#15556 — an approval hosted in a subflow child, whose parent bubble fails', () => {
   let data: ReturnType<typeof makeFakeEngine>;
   let service: ApprovalService;
   let logger: ReturnType<typeof recordingLogger>;
@@ -153,27 +198,30 @@ describe('#15556 probe — approval inside a subflow child, parent bubble fails'
   const pendingRequest = async () =>
     (await data.find('sys_approval_request', { where: { status: 'pending' } }))[0];
 
-  it('MEASUREMENT — parent bubble fails: what does the door answer?', async () => {
-    throwOn.after_sub = 'update_record(crm_leave_request) failed: Record 9SEmlyRfw8D9-J7Z not found';
+  /** The resume-facing projection of the door's answer — everything a caller reads about the run. */
+  const resumeFacing = (r: any) => ({
+    finalized: r.finalized, decision: r.decision, resumed: r.resumed, resumeError: r.resumeError,
+  });
+
+  it('the parent STRANDS while the door answers full success', async () => {
+    throwOn.after_sub = DOWNSTREAM_FAILURE;
     const automation = boot();
 
     const started = await automation.execute('deal_parent', {
       object: 'crm_deal', record: { id: 'd1', amount: 100 }, userId: 'submitter',
     } as never);
-    // eslint-disable-next-line no-console
-    console.log('PROBE started =', JSON.stringify(started));
     const parentRunId = (started as any).runId as string;
+    expect((started as any).status, 'the parent parks at its subflow node').toBe('paused');
 
     const req = await pendingRequest();
-    // eslint-disable-next-line no-console
-    console.log('PROBE request =', JSON.stringify(req && { id: req.id, run: req.flow_run_id, status: req.status }));
     const childRunId = req?.flow_run_id as string;
-    expect(childRunId, 'the request must name the CHILD run').toBeTruthy();
+    expect(childRunId, 'the request names the CHILD run, never the parent').toBeTruthy();
     expect(childRunId).not.toBe(parentRunId);
     expect(await automation.hasSuspendedRun(parentRunId)).toBe(true);
 
-    // Capture the envelope `bubbleToParent` receives for the PARENT resume —
-    // the thing the swallowing catch throws away.
+    // The envelope `bubbleToParent` receives for the PARENT — the thing this
+    // card is about. Captured through `resumeInternal` because the up-bubble
+    // never goes through the public `resume` door.
     const bubbled: any[] = [];
     const realInternal = (automation as any).resumeInternal.bind(automation);
     (automation as any).resumeInternal = async (...args: any[]) => {
@@ -186,61 +234,88 @@ describe('#15556 probe — approval inside a subflow child, parent bubble fails'
       .decide(req.id, { decision: 'approve', actorId: 'u1' }, SYSTEM_CTX)
       .then(r => ({ ok: true as const, r }), (e: Error) => ({ ok: false as const, e }));
 
-    // eslint-disable-next-line no-console
-    console.log('PROBE door =', JSON.stringify(outcome.ok ? outcome.r : { threw: outcome.e.message, details: strandedDecisionDetails(outcome.e) }));
-    // eslint-disable-next-line no-console
-    console.log('PROBE marks =', JSON.stringify(marks));
-    // eslint-disable-next-line no-console
-    console.log('PROBE parent suspended?', await automation.hasSuspendedRun(parentRunId));
-    // eslint-disable-next-line no-console
-    console.log('PROBE parent resume =', JSON.stringify(await automation.resume(parentRunId)));
-    const parentRow = await automation.getRun(parentRunId);
-    // eslint-disable-next-line no-console
-    console.log('PROBE parent run row =', JSON.stringify(parentRow && {
-      status: (parentRow as any).status, error: (parentRow as any).error,
-      consumedSuspension: Boolean((parentRow as any).consumedSuspension),
-    }));
-    // eslint-disable-next-line no-console
-    console.log('PROBE child run row =', JSON.stringify(await automation.getRun(childRunId).then(r => r && { status: (r as any).status })));
-    // eslint-disable-next-line no-console
-    console.log('PROBE request row =', JSON.stringify((await data.find('sys_approval_request', { where: { id: req.id } }))[0]?.status));
-    // eslint-disable-next-line no-console
-    console.log('PROBE parent bubble envelope =', JSON.stringify(bubbled.map(b => ({ success: b.success, code: b.code, status: b.status, error: b.error }))));
-    // eslint-disable-next-line no-console
-    console.log('PROBE parent restore =', JSON.stringify(await automation.restoreConsumedSuspension(parentRunId, { requestedBy: 'probe' })));
-    // eslint-disable-next-line no-console
-    console.log('PROBE log lines =', JSON.stringify(logger.lines.filter((l: any) => l.level !== 'debug' && l.level !== 'info').map((l: any) => [l.level, l.msg])));
+    // ── The parent's resume answers the #13937 discriminator, and no `code`.
+    expect(bubbled.length).toBe(1);
+    expect(bubbled[0].success).toBe(false);
+    expect(bubbled[0].status, "the producer's own verdict").toBe('stranded');
+    expect(bubbled[0].code, 'and it names no code at all').toBeUndefined();
+    expect(bubbled[0].error).toBe(DOWNSTREAM_FAILURE);
+
+    // ── The parent really is dead, and really is repairable.
+    expect(await automation.hasSuspendedRun(parentRunId)).toBe(false);
+    expect((await automation.resume(parentRunId)).code).toBe('RUN_NOT_FOUND');
+    expect((await automation.getRun(parentRunId))?.status).toBe('failed');
+
+    // ── The child is fine, and so is the decision: both halves of the
+    //    divergence are real, which is what makes it a divergence.
+    expect((await automation.getRun(childRunId))?.status).toBe('completed');
+    expect(marks, 'the child advanced; the parent died on the node after the subflow')
+      .toEqual(['on_approved']);
+    expect((await data.find('sys_approval_request', { where: { id: req.id } }))[0].status).toBe('approved');
+
+    // ⚠️ CHARACTERISED, NOT BLESSED — see the file header. The door does not
+    // throw, reports `resumed: true`, carries no `resumeError`, and the run it
+    // names is the CHILD, which completed. Nothing in the response reaches the
+    // stranded parent.
+    expect(outcome.ok, 'today the door does not throw').toBe(true);
+    const answer = outcome.ok ? outcome.r : (undefined as never);
+    expect(resumeFacing(answer)).toEqual(FULL_SUCCESS);
+    expect(answer.runId, 'the id handed back is the CHILD — the run that is fine').toBe(childRunId);
+    expect(strandedDecisionDetails(answer as unknown)).toBeUndefined();
+
+    // The one artefact the operator gets, at the level AGENTS.md's durability
+    // rule requires, naming the run and the repair verb (#15556's shipped half).
+    const durability = logger.lines.filter(
+      (l: any) => l.level === 'error' && String(l.msg).includes('STRANDED'),
+    );
+    expect(durability.length, 'exactly one, at `error`').toBe(1);
+    expect(durability[0].msg).toContain(`restoreConsumedSuspension('${parentRunId}')`);
+
+    // …and the repair verb it promises actually works.
+    expect((await automation.restoreConsumedSuspension(parentRunId, { requestedBy: 'ops' })).restored).toBe(true);
+
   });
 
-  it('CONTROL A — same composition, parent downstream node healthy', async () => {
+  it('CONTROL A — the healthy composition answers IDENTICALLY, which is the defect', async () => {
     const automation = boot();
     const started = await automation.execute('deal_parent', {
-      object: 'crm_deal', record: { id: 'd2', amount: 100 }, userId: 'submitter',
+      object: 'crm_deal', record: { id: 'd1', amount: 100 }, userId: 'submitter',
     } as never);
     const parentRunId = (started as any).runId as string;
     const req = await pendingRequest();
-    const outcome = await service
-      .decide(req.id, { decision: 'approve', actorId: 'u1' }, SYSTEM_CTX)
-      .then(r => ({ ok: true as const, r }), (e: Error) => ({ ok: false as const, e }));
-    // eslint-disable-next-line no-console
-    console.log('CTRL-A door =', JSON.stringify(outcome.ok ? outcome.r : { threw: outcome.e.message }));
-    // eslint-disable-next-line no-console
-    console.log('CTRL-A marks =', JSON.stringify(marks));
-    // eslint-disable-next-line no-console
-    console.log('CTRL-A parent run row =', JSON.stringify(await automation.getRun(parentRunId).then(r => r && { status: (r as any).status })));
+
+    const answer = await service.decide(req.id, { decision: 'approve', actorId: 'u1' }, SYSTEM_CTX);
+
+    // The parent ran to completion this time — the only thing that changed.
+    expect(marks).toEqual(['on_approved', 'after_sub']);
+    expect((await automation.getRun(parentRunId))?.status).toBe('completed');
+    expect(logger.lines.filter((l: any) => l.level === 'error')).toEqual([]);
+
+    // ⭐ The sharpest statement of the defect: the SAME literal the stranded
+    // composition asserted. A caller comparing the two answers has nothing to
+    // compare — only the run ids differ, and both name a healthy child.
+    expect(resumeFacing(answer)).toEqual(FULL_SUCCESS);
+    expect(answer.runId).toBe(req.flow_run_id);
   });
 
-  it('CONTROL B — no subflow: the #13807 shape still throws at this door', async () => {
+  it("CONTROL B — the #13807 shape still throws at this door, so the harness is live", async () => {
+    // Without this control, "the door did not throw" above would be
+    // indistinguishable from a door that was never wired to throw at all.
     throwOn.on_approved = 'the child branch blew up';
     const automation = boot();
     await automation.execute('deal_approval', {
       object: 'crm_deal', record: { id: 'd3', amount: 100 }, userId: 'submitter',
     } as never);
     const req = await pendingRequest();
-    const outcome = await service
+
+    const err = await service
       .decide(req.id, { decision: 'approve', actorId: 'u1' }, SYSTEM_CTX)
-      .then(r => ({ ok: true as const, r }), (e: Error) => ({ ok: false as const, e }));
-    // eslint-disable-next-line no-console
-    console.log('CTRL-B door =', JSON.stringify(outcome.ok ? outcome.r : { threw: outcome.e.message, details: strandedDecisionDetails(outcome.e) }));
+      .then(() => null, (e: Error) => e);
+
+    expect(err, 'the direct shape is reported — this door can fail').toBeTruthy();
+    expect(err?.message).toMatch(/^RESUME_FAILED/);
+    expect(strandedDecisionDetails(err)).toEqual({
+      finalized: true, decision: 'approve', runId: req.flow_run_id, repairable: true,
+    });
   });
 });