|
| 1 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * #17541 — the resume door's `repairable` is answered by the ENGINE on the |
| 5 | + * exits that stamp no `status`, instead of being read off a stamp that is not |
| 6 | + * there (the maintainer's ruling on this card, 2026-09-17, letter 1). |
| 7 | + * |
| 8 | + * ## The defect, as a wire reading |
| 9 | + * |
| 10 | + * `repairable` used to be the single expression `status === 'stranded'`. That |
| 11 | + * word is stamped on exactly one exit — the run that consumed its OWN pause |
| 12 | + * and then threw downstream. The subflow **delegation** exit deliberately |
| 13 | + * stamps nothing: a caller resumes the PARENT, `resumeInternal` forwards the |
| 14 | + * signal down, the child strands, and the parent frame answers |
| 15 | + * `{ success: false, error, durationMs }`, because nothing re-arms an ancestor |
| 16 | + * by resuming it and stamping `'stranded'` there would send an operator to |
| 17 | + * retry a recovery that cannot succeed. Since #15222 that parent's consumed |
| 18 | + * pause IS journalled and `restoreConsumedSuspension(parentRunId)` re-arms the |
| 19 | + * chain as one unit — so the wire answered `repairable: false` about a run the |
| 20 | + * operator verb WILL repair, and a client written exactly as the docs instruct |
| 21 | + * closed it as terminal. |
| 22 | + * |
| 23 | + * ## What this file pins, and what it deliberately does NOT |
| 24 | + * |
| 25 | + * This is the DOOR's shaping, with a fake service, so every arm is reachable |
| 26 | + * by name — including the two that a real engine will not produce on demand (a |
| 27 | + * host with no inspection member; a store the inspection cannot read). The |
| 28 | + * end-to-end fact, driven through the real engine and the HTTP route, is |
| 29 | + * `@objectstack/verify`'s `automation-resume-delegation-repairable.test.ts`; |
| 30 | + * the engine's own halves are `service-automation`'s |
| 31 | + * `nested-strand-chain-restore.test.ts` and |
| 32 | + * `consumed-suspension-inspection.test.ts`. |
| 33 | + * |
| 34 | + * ⛔ The fence #15222 was dispatched with is untouched and is not re-pinned |
| 35 | + * here: a cascade-failed ancestor is still never STAMPED `'stranded'`. Its |
| 36 | + * repairability is carried by the journal and REPORTED by the inspection, |
| 37 | + * which is precisely why the door has to ask instead of reading a word. |
| 38 | + * |
| 39 | + * ⛔ And the door asks a member the CONTRACT declares — `IAutomationService` |
| 40 | + * gained the optional read-only `inspectConsumedSuspension` for this card. |
| 41 | + * Reaching for an undeclared member would be the fail-open shape the route's |
| 42 | + * own `501` arm exists to prevent, so every way of not getting an answer here |
| 43 | + * is FAIL-CLOSED: no member, and a rejected read, both answer `false`. |
| 44 | + * |
| 45 | + * The sibling file `automation-resume-stranded-details.test.ts` is the CONTROL |
| 46 | + * for this change and is deliberately left untouched: every non-delegation |
| 47 | + * exit it pins — the stamped `'stranded'`, the stamped `'failed'`, the |
| 48 | + * status-less arm on a service with no inspection member, the regex control, |
| 49 | + * the trigger door's absent member — still answers exactly what it did. |
| 50 | + */ |
| 51 | + |
| 52 | +import { describe, it, expect, vi, afterEach } from 'vitest'; |
| 53 | + |
| 54 | +import { ResumeFailureDetailsSchema } from '@objectstack/spec/api'; |
| 55 | +import type { AutomationResult, IAutomationService } from '@objectstack/spec/contracts'; |
| 56 | + |
| 57 | +import { HttpDispatcher } from '../http-dispatcher.js'; |
| 58 | + |
| 59 | +const CTX = { request: {}, executionContext: { userId: 'user_1' } } as any; |
| 60 | +const RESUME = '/parent_flow/runs/run_parent/resume'; |
| 61 | + |
| 62 | +/** |
| 63 | + * The engine's answer on the delegation exit, measured through the real |
| 64 | + * engine while this card was written: the parent frame carries no `status`, |
| 65 | + * no `errorMessage` and no `summary` — only the subflow failure text. |
| 66 | + */ |
| 67 | +const DELEGATION_FRAME: AutomationResult = { |
| 68 | + success: false, |
| 69 | + error: "subflow run 'run_child' (child_flow) failed: update_record(crm_leave_request) failed: Record 9SEmlyRfw8D9-J7Z not found", |
| 70 | + durationMs: 7, |
| 71 | +}; |
| 72 | + |
| 73 | +type Inspect = NonNullable<IAutomationService['inspectConsumedSuspension']>; |
| 74 | + |
| 75 | +function makeDispatcher(resumeResult: AutomationResult, inspect?: Inspect) { |
| 76 | + const spies = { |
| 77 | + resume: vi.fn(async () => resumeResult), |
| 78 | + ...(inspect ? { inspectConsumedSuspension: vi.fn(inspect) } : {}), |
| 79 | + }; |
| 80 | + const services: Record<string, unknown> = { automation: spies }; |
| 81 | + const resolve = (name: string) => services[name]; |
| 82 | + const kernel: any = { |
| 83 | + getService: resolve, |
| 84 | + getServiceAsync: async (name: string) => resolve(name), |
| 85 | + context: { getService: resolve }, |
| 86 | + }; |
| 87 | + return { dispatcher: new HttpDispatcher(kernel), spies }; |
| 88 | +} |
| 89 | + |
| 90 | +afterEach(() => { vi.restoreAllMocks(); }); |
| 91 | + |
| 92 | +describe('#17541 — the status-less resume exit asks the engine whether the run is still repairable', () => { |
| 93 | + it('DELEGATION — a frame with no status answers repairable: true when the engine holds the consumed suspension', async () => { |
| 94 | + const { dispatcher, spies } = makeDispatcher( |
| 95 | + DELEGATION_FRAME, |
| 96 | + async (runId: string) => ({ repairable: true, runId }), |
| 97 | + ); |
| 98 | + |
| 99 | + const result = await dispatcher.handleAutomation(RESUME, 'POST', {}, CTX); |
| 100 | + |
| 101 | + // The door asked about the run it was addressed to — the path's |
| 102 | + // `:runId`, which on this exit IS the run whose pause was consumed. |
| 103 | + expect(spies.inspectConsumedSuspension).toHaveBeenCalledWith('run_parent'); |
| 104 | + expect(result.response?.status).toBe(400); |
| 105 | + const error = result.response?.body?.error; |
| 106 | + expect(error?.code).toBe('FLOW_FAILED'); |
| 107 | + // ⛔ Still no `status`: the door relays the producer's stamp and the |
| 108 | + // producer stamped none. `repairable` is the answer, not the word. |
| 109 | + expect(error?.details).toEqual({ runId: 'run_parent', repairable: true }); |
| 110 | + expect(ResumeFailureDetailsSchema.safeParse(error?.details).success).toBe(true); |
| 111 | + // Not prose: the message names the subflow failure, not the verdict. |
| 112 | + expect(error?.message).not.toMatch(/repairable/i); |
| 113 | + }); |
| 114 | + |
| 115 | + it('FIRING CONTROL — the same status-less arm answers false when the engine says the suspension is gone', async () => { |
| 116 | + // Without this the pin above would pass over a door that simply |
| 117 | + // flipped the status-less arm to `true` and never asked anything. |
| 118 | + const { dispatcher, spies } = makeDispatcher( |
| 119 | + DELEGATION_FRAME, |
| 120 | + async (runId: string) => ({ repairable: false, runId, reason: 'NO_CONSUMED_SUSPENSION' }), |
| 121 | + ); |
| 122 | + |
| 123 | + const result = await dispatcher.handleAutomation(RESUME, 'POST', {}, CTX); |
| 124 | + |
| 125 | + expect(spies.inspectConsumedSuspension).toHaveBeenCalledWith('run_parent'); |
| 126 | + expect(result.response?.status).toBe(400); |
| 127 | + expect(result.response?.body?.error?.details).toEqual({ runId: 'run_parent', repairable: false }); |
| 128 | + }); |
| 129 | + |
| 130 | + it('FAIL-CLOSED — a service that declares no inspection member answers false, exactly as it did before this card', async () => { |
| 131 | + const { dispatcher } = makeDispatcher(DELEGATION_FRAME); |
| 132 | + |
| 133 | + const result = await dispatcher.handleAutomation(RESUME, 'POST', {}, CTX); |
| 134 | + |
| 135 | + expect(result.response?.status).toBe(400); |
| 136 | + expect(result.response?.body?.error?.details).toEqual({ runId: 'run_parent', repairable: false }); |
| 137 | + }); |
| 138 | + |
| 139 | + it('FAIL-CLOSED — an inspection that REJECTS still answers the 400 it was asked for, with repairable false and one warning', async () => { |
| 140 | + // An unreadable store is UNKNOWN, not "nothing to restore" — so it is |
| 141 | + // said out loud once. ⛔ And it never replaces the answer: the caller |
| 142 | + // asked about a run that failed, and turning a store outage into a |
| 143 | + // 500 would withhold that in order to report a detail. |
| 144 | + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}); |
| 145 | + const { dispatcher } = makeDispatcher( |
| 146 | + DELEGATION_FRAME, |
| 147 | + async () => { throw new Error('connection reset'); }, |
| 148 | + ); |
| 149 | + |
| 150 | + const result = await dispatcher.handleAutomation(RESUME, 'POST', {}, CTX); |
| 151 | + |
| 152 | + expect(result.response?.status).toBe(400); |
| 153 | + expect(result.response?.body?.error?.code).toBe('FLOW_FAILED'); |
| 154 | + expect(result.response?.body?.error?.details).toEqual({ runId: 'run_parent', repairable: false }); |
| 155 | + const said = warn.mock.calls.map(c => String(c[0])).filter(l => l.includes('inspectConsumedSuspension')); |
| 156 | + expect(said).toHaveLength(1); |
| 157 | + expect(said[0]).toContain('connection reset'); |
| 158 | + expect(said[0]).toContain('run_parent'); |
| 159 | + }); |
| 160 | + |
| 161 | + it('CONTROL — a stamped `stranded` is answered by the STAMP: repairable true, and the engine is never asked', async () => { |
| 162 | + const { dispatcher, spies } = makeDispatcher( |
| 163 | + { success: false, error: 'tail blew up', durationMs: 12, status: 'stranded' }, |
| 164 | + async (runId: string) => ({ repairable: false, runId, reason: 'NO_CONSUMED_SUSPENSION' }), |
| 165 | + ); |
| 166 | + |
| 167 | + const result = await dispatcher.handleAutomation(RESUME, 'POST', {}, CTX); |
| 168 | + |
| 169 | + // The inspection would have answered `false` here. It is not consulted, |
| 170 | + // so the stamp is demonstrably what decided — and the pre-existing |
| 171 | + // exits keep costing exactly one engine call. |
| 172 | + expect(spies.inspectConsumedSuspension).not.toHaveBeenCalled(); |
| 173 | + expect(result.response?.body?.error?.details).toEqual({ |
| 174 | + runId: 'run_parent', status: 'stranded', repairable: true, |
| 175 | + }); |
| 176 | + }); |
| 177 | + |
| 178 | + it('CONTROL — a stamped `failed` is answered by the STAMP: repairable false, and the engine is never asked', async () => { |
| 179 | + const { dispatcher, spies } = makeDispatcher( |
| 180 | + { success: false, error: 'rejected', durationMs: 3, status: 'failed' }, |
| 181 | + async (runId: string) => ({ repairable: true, runId }), |
| 182 | + ); |
| 183 | + |
| 184 | + const result = await dispatcher.handleAutomation(RESUME, 'POST', {}, CTX); |
| 185 | + |
| 186 | + // The inspection would have answered `true` here — a stamped `failed` |
| 187 | + // is a run that ran and was rejected, and no reading of a leftover |
| 188 | + // snapshot is allowed to overturn the producer's own verdict. |
| 189 | + expect(spies.inspectConsumedSuspension).not.toHaveBeenCalled(); |
| 190 | + expect(result.response?.body?.error?.details).toEqual({ |
| 191 | + runId: 'run_parent', status: 'failed', repairable: false, |
| 192 | + }); |
| 193 | + }); |
| 194 | +}); |
0 commit comments