fix(http): classify every terminal wait through terminalOutcomeFor (Q-6.3-6)

The executor decided the terminal outcome of an ended wait in six places
(credentials, lease, dispatch, transport backoff, admission, retry
backoff). The two backoff copies only checked the caller, so a scope
fence during a retry sleep ended as TRANSPORT_FAILURE{TIMEOUT} and the
user saw "timed out, retry" after logging out.

All six sites now call one terminalOutcomeFor(phase) helper: the caller
cancels, the deadline times out, a scope fence during a wait is
ABORTED_BY_SCOPE and during admission stays the SCOPE_FENCED violation.

Verified: a new owner x phase table in http-execution-v3.test.ts pins
the 16 existing combinations and failed RED only for the two backoff
scope-fence cases (TIMEOUT instead of ABORTED_BY_SCOPE). All lane gates
pass except the known removal-fixture test (missing artifacts/).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-24 13:41:45 +09:00
co-authored by Claude Opus 5.5
parent 042427c887
commit 4c7737361a
2 changed files with 193 additions and 93 deletions
+44 -93
View File
@@ -582,6 +582,31 @@ export function createContractHttpExecutor(
return outcome;
};
/**
* Q-6.3-6. The one classifier for a wait that a terminal owner ended. The
* caller cancels and the deadline times out. A scope fence during a `WAIT`
* (credentials, lease, dispatch, backoff) aborts the transport; during
* `ADMISSION` the response headers prove the request reached the server,
* so a stale generation stays the `SCOPE_FENCED` contract violation.
*/
const terminalOutcomeFor = (
phase: "WAIT" | "ADMISSION",
): HttpExecutionOutcome<WireOutput, Problem> => {
switch (terminalCancellation) {
case "CALLER":
return finish(cancelled(abandonedCertainty()), "CANCELLED");
case "SCOPE_FENCE":
return phase === "ADMISSION"
? finish(scopeFenced(abandonedCertainty()), "SCOPE_FENCED")
: finish(
abandonedTransportFailure("ABORTED_BY_SCOPE"),
"SCOPE_FENCED",
);
default:
return finish(abandonedTransportFailure("TIMEOUT"), "TIMEOUT");
}
};
try {
// §7.7. The installed registry is the only source of a profile. Composition
@@ -684,20 +709,7 @@ export function createContractHttpExecutor(
"AUTH_INTEGRATION_FAILURE",
);
}
if (patchResult === ABORTED) {
if (terminalCancellation === "SCOPE_FENCE") {
return finish(
abandonedTransportFailure("ABORTED_BY_SCOPE"),
"SCOPE_FENCED",
);
}
return terminalCancellation === "CALLER"
? finish(cancelled("NOT_STARTED"), "CANCELLED")
: finish(
abandonedTransportFailure("TIMEOUT"),
"TIMEOUT",
);
}
if (patchResult === ABORTED) return terminalOutcomeFor("WAIT");
// NS-01. The whole answer is decoded once, inside the auth boundary, before
// any field is used. Reading `kind` and `headers` off the raw object left
// the decode outside that boundary: a throwing getter escaped into the
@@ -818,16 +830,7 @@ export function createContractHttpExecutor(
"TRAFFIC_BUDGET_EXCEEDED",
);
}
if (terminalCancellation === "CALLER") {
return finish(cancelled(abandonedCertainty()), "CANCELLED");
}
if (terminalCancellation === "SCOPE_FENCE") {
return finish(
abandonedTransportFailure("ABORTED_BY_SCOPE"),
"SCOPE_FENCED",
);
}
return finish(abandonedTransportFailure("TIMEOUT"), "TIMEOUT");
return terminalOutcomeFor("WAIT");
}
try {
const controller = new AbortController();
@@ -919,22 +922,10 @@ export function createContractHttpExecutor(
} else {
clearTimeout(deadlineTimer);
lifetimeController.signal.removeEventListener("abort", forwardLifetime);
const owner = terminalCancellation;
if (owner === "CALLER") {
return finish(
cancelled(abandonedCertainty()),
"CANCELLED",
);
if (terminalCancellation !== null) {
return terminalOutcomeFor("WAIT");
}
if (owner === "SCOPE_FENCE") {
return finish(
abandonedTransportFailure("ABORTED_BY_SCOPE"),
"SCOPE_FENCED",
);
}
const kind = owner === "DEADLINE" ? "TIMEOUT" : "NETWORK_FAILURE";
if (
owner === null &&
canRetryTransport(contract.retrySemantics, attemptState) &&
retryIndex < retryCeiling &&
remaining() > 0
@@ -946,23 +937,13 @@ export function createContractHttpExecutor(
sleep(delay, lifetimeController.signal),
lifetimeController.signal,
);
if (slept === ABORTED) {
return terminalCancellation === "CALLER"
? finish(
cancelled(abandonedCertainty()),
"CANCELLED",
)
: finish(
abandonedTransportFailure("TIMEOUT"),
"TIMEOUT",
);
}
if (slept === ABORTED) return terminalOutcomeFor("WAIT");
continue;
}
}
return finish(
abandonedTransportFailure(kind),
kind,
abandonedTransportFailure("NETWORK_FAILURE"),
"NETWORK_FAILURE",
);
}
@@ -983,42 +964,22 @@ export function createContractHttpExecutor(
controller.signal,
() => cancelResponseBody(response),
);
// LIVE-04. Once response headers are in hand the request demonstrably
// reached the server, so a terminal owner that lands during admission
// keeps the dispatched classification: a stale generation stays the
// `SCOPE_FENCED` contract violation it has always been, and only the
// deadline and the caller reclassify the outcome.
const abandonAdmission = ():
| HttpExecutionOutcome<WireOutput, Problem>
| null => {
switch (terminalCancellation) {
case "DEADLINE":
return finish(abandonedTransportFailure("TIMEOUT"), "TIMEOUT");
case "CALLER":
return finish(cancelled(abandonedCertainty()), "CANCELLED");
case "SCOPE_FENCE":
return finish(
scopeFenced(abandonedCertainty()),
"SCOPE_FENCED",
);
default:
return null;
}
};
// LIVE-04. A terminal owner that lands during admission wins over the
// admitted answer.
if (admission.kind !== "VALUE") {
cancelResponseBody(response);
return (
abandonAdmission() ??
finish(
abandonedTransportFailure("NETWORK_FAILURE"),
"NETWORK_FAILURE",
)
);
return terminalCancellation === null
? finish(
abandonedTransportFailure("NETWORK_FAILURE"),
"NETWORK_FAILURE",
)
: terminalOutcomeFor("ADMISSION");
}
const outcome = admission.value;
attemptState = "SETTLED";
const abandoned = abandonAdmission();
if (abandoned) return abandoned;
if (terminalCancellation !== null) {
return terminalOutcomeFor("ADMISSION");
}
if (
outcome.retryHint &&
retryIndex < retryCeiling &&
@@ -1036,17 +997,7 @@ export function createContractHttpExecutor(
sleep(delay, lifetimeController.signal),
lifetimeController.signal,
);
if (slept === ABORTED) {
return terminalCancellation === "CALLER"
? finish(
cancelled(abandonedCertainty()),
"CANCELLED",
)
: finish(
abandonedTransportFailure("TIMEOUT"),
"TIMEOUT",
);
}
if (slept === ABORTED) return terminalOutcomeFor("WAIT");
continue;
}
}
+149
View File
@@ -10,6 +10,10 @@ import {
} from "../../src/adapters/http/http-execution-v3.ts";
import { mappingSuccess } from "../../src/contracts/boundary-mapper.ts";
import type { InstalledHttpContract } from "../../src/contracts/external-contract-runtime.ts";
import {
createExecutionContext,
type ExecutionContext,
} from "../../src/platform/execution/execution-context.ts";
import {
TEST_CREATE_HTTP_CONTRACT,
TEST_LIST_HTTP_CONTRACT,
@@ -842,3 +846,148 @@ describe("gateway failures without a usable problem body", () => {
},
);
});
/**
* Q-6.3-6. Every wait the lifetime signal can end reports its owner the same
* way: the caller cancels, the deadline times out, and a scope fence ends as a
* scope abort — a transport abort before response headers, the stale-generation
* violation after them. A fence during a retry backoff used to read as TIMEOUT.
*/
describe("terminal owner classification at every wait", () => {
const phases = [
"credentials",
"lease",
"dispatch",
"transport backoff",
"admission",
"retry backoff",
] as const;
type Phase = (typeof phases)[number];
type Owner = "CALLER" | "SCOPE_FENCE" | "DEADLINE";
const hang = () => new Promise<never>(() => {});
async function endWaitAt(phase: Phase, owner: Owner) {
const caller = new AbortController();
const fence = new AbortController();
const fencedScope = Object.freeze({
...scope,
signal: fence.signal,
isCurrent: () => !fence.signal.aborted,
});
let reached = false;
const reach = () => {
reached = true;
};
let execution: ExecutionContext | undefined;
if (phase === "lease") {
execution = createExecutionContext({
interactionId: "held-lease",
deadlineMs: 10_000,
traffic: {
maxPhysicalRequests: 4,
maxRetries: 2,
maxConcurrentRequests: 1,
maxQueuedRequests: 1,
},
});
await execution.traffic.concurrency.acquire(new AbortController().signal);
}
const observations: HttpExecutionObservation[] = [];
const executor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 2,
attachCredentials: () =>
phase === "credentials"
? (reach(), hang())
: { kind: "READY", headers: {} },
fetcher: vi.fn(async () => {
switch (phase) {
case "transport backoff":
throw new TypeError("network down");
case "admission":
return new Response(
new ReadableStream<Uint8Array>({
pull: () => (reach(), hang()),
}),
{ status: 200, headers: { "content-type": "application/json" } },
);
case "retry backoff":
return Response.json(
{ type: "about:blank", title: "temporary", status: 503 },
{ status: 503 },
);
default:
reach();
return hang();
}
}),
sleep: () => (reach(), hang()),
random: () => 0,
observe: (observation) => void observations.push(observation),
});
const pending = executor.execute(
operation({ deadlineMs: owner === "DEADLINE" ? 30 : 10_000 }),
{ limit: 20 },
{
routeId: ROUTE_ID,
scope: fencedScope,
signal: caller.signal,
...(execution === undefined ? {} : { execution }),
},
);
if (owner !== "DEADLINE") {
await vi.waitFor(() =>
expect(reached || execution?.traffic.concurrency.queued === 1).toBe(
true,
),
);
(owner === "CALLER" ? caller : fence).abort();
}
const outcome = await pending;
return {
outcome,
cancellationOwner: observations.at(-1)?.cancellationOwner,
};
}
it.each(phases)(
"cancels at the %s wait when the caller aborts",
async (phase) => {
await expect(endWaitAt(phase, "CALLER")).resolves.toMatchObject({
outcome: { kind: "CANCELLED", effect: "NOT_STARTED" },
cancellationOwner: "CALLER",
});
},
);
it.each(phases)(
"times out at the %s wait when the deadline fires",
async (phase) => {
await expect(endWaitAt(phase, "DEADLINE")).resolves.toMatchObject({
outcome: { kind: "TRANSPORT_FAILURE", failure: { kind: "TIMEOUT" } },
cancellationOwner: "DEADLINE",
});
},
);
it.each(phases)(
"ends the %s wait as a scope abort when the scope is fenced",
async (phase) => {
await expect(endWaitAt(phase, "SCOPE_FENCE")).resolves.toMatchObject({
outcome:
phase === "admission"
? {
kind: "CONTRACT_VIOLATION",
violation: { kind: "SCOPE_FENCED" },
}
: {
kind: "TRANSPORT_FAILURE",
failure: { kind: "ABORTED_BY_SCOPE" },
},
cancellationOwner: "SCOPE_FENCE",
});
},
);
});