fix: UI 감사와 11-01·11-03 성숙도 리뷰의 발견을 반영한다 #4

Merged
donghyeon.kang merged 361 commits from fix/ui-design-audit-2026-11-01 into main 2026-11-05 10:33:58 +00:00
3 changed files with 65 additions and 30 deletions
Showing only changes of commit 17fa8d1f65 - Show all commits
@@ -1895,11 +1895,11 @@ credential을 보호할 수 있다고 주장하지 않는다.
| `UNSUPPORTED` | browser capability 없음 | declared fallback |
| `OFFLINE` | network hint/attempt failure | online hint 뒤 bounded check |
| `CONNECT_TIMEOUT` | open deadline 초과 | bounded reconnect |
| `IDLE_TIMEOUT` | transport: heartbeat/byte/unsubscribe deadline 초과(operation `RECEIVE`·`SUBSCRIBE`). handoff coordinator의 quiescence·checkpoint·close deadline 초과(operation `RECOVER`·`CLOSE`) | transport: close + bounded reconnect. handoff 마감은 재연결로 풀리지 않는다: 그 전환을 fail-close한다(결과는 kind 기본값대로 retryable). 두 뜻은 `operation`으로 구분한다 |
| `IDLE_TIMEOUT` | transport: heartbeat/byte/unsubscribe deadline 초과(operation `RECEIVE`·`SUBSCRIBE`). 내부 task 마감에는 쓰지 않는다 | close + bounded reconnect |
| `AUTH_REQUIRED` | session expired/recovery 실패 | sign-in UX |
| `FORBIDDEN` | stream/resource 거절 | retry 없음 |
| `RATE_LIMITED` | connection/request/provider limit | bounded server hint |
| `PROVIDER_UNAVAILABLE` | backend/push/hosting unavailable. stream coordinator의 recovery deadline 초과(operation `RECOVER`)와 close drain deadline 초과(operation `CLOSE`)도 이 kind다(`retryable: false`) | bounded retry 또는 degraded. stream coordinator 마감은 재연결로 풀리지 않는다: task가 settle할 때까지 `DRAINING`을 유지한다. settle 뒤 recovery 마감은 다음 event가 recovery부터 하고, close 마감은 `CLOSED`가 된다 |
| `PROVIDER_UNAVAILABLE` | backend/push/hosting unavailable. stream coordinator의 recovery deadline 초과(operation `RECOVER`)와 close drain deadline 초과(operation `CLOSE`)도 이 kind다(`retryable: false`). live↔Poll handoff coordinator의 checkpoint deadline 초과(operation `RECOVER`)와 close drain deadline 초과(operation `CLOSE`)도 이 kind다(`retryable: true`) | bounded retry 또는 degraded. stream coordinator 마감은 재연결로 풀리지 않는다: task가 settle할 때까지 `DRAINING`을 유지한다. settle 뒤 recovery 마감은 다음 event가 recovery부터 하고, close 마감은 `CLOSED`가 된다. handoff checkpoint 마감은 그 전환을 fail-close하므로 새 handoff만 돌 수 있다. handoff close 마감 뒤에는 writer·checkpoint task가 settle하면 다시 부른 `close()`가 성공한다 |
| `PROTOCOL_MISMATCH` | version/subprotocol/content type | terminal/rollout rollback |
| `MALFORMED_EVENT` | state-bearing syntax/schema/exact-key 실패 | cursor 미진행, freshness `UNKNOWN`, close + registered recovery |
| `MAPPING_CONTRACT_VIOLATION` | validated DTO의 registered mapper 실패 | effect/cache/cursor write 0, close + registered recovery |
@@ -1910,7 +1910,7 @@ credential을 보호할 수 있다고 주장하지 않는다.
| `SEQUENCE_GAP` | missing event | snapshot resync |
| `CURSOR_EXPIRED` | replay retention 밖 | snapshot reset |
| `QUEUE_OVERFLOW` | backpressure ceiling | close + registered snapshot/session rebuild |
| `APPLY_FAILED` | feature effect 실패. stream coordinator의 effect deadline 초과(operation `APPLY`, `retryable: false`)도 이 kind다 | cursor 미commit, bounded registered recovery. deadline 초과는 recovery를 바로 하지 않는다: task가 settle할 때까지 `DRAINING`을 유지하고, settle 뒤 다음 event가 recovery부터 한다 |
| `APPLY_FAILED` | feature effect 실패. stream coordinator의 effect deadline 초과(operation `APPLY`, `retryable: false`)도 이 kind다. live↔Poll handoff coordinator에서 이전 writer의 effect가 quiescence deadline 안에 끝나지 않은 것(operation `RECOVER`, `retryable: true`)도 이 kind다 | cursor 미commit, bounded registered recovery. deadline 초과는 recovery를 바로 하지 않는다: task가 settle할 때까지 `DRAINING`을 유지하고, settle 뒤 다음 event가 recovery부터 한다. handoff quiescence 마감은 그 전환을 fail-close하므로 새 handoff만 돌 수 있다 |
| `POLL_BUDGET_EXHAUSTED` | lease 한도 도달 | stale/manual retry |
| `PUSH_PERMISSION_DENIED` | 사용자 거절 | foreground fallback |
| `PUSH_SUBSCRIPTION_STALE` | rotation/expiry/provider gone | bounded re-registration |
@@ -398,12 +398,7 @@ export function createLivePollHandoffCoordinator<Value>(
}
if (quiescence !== "QUIESCED") {
failClosed();
return handoffFailure(
quiescence === "TIMED_OUT"
? "IDLE_TIMEOUT"
: "PROVIDER_UNAVAILABLE",
"RECOVER",
);
return quiescenceFailure(quiescence);
}
quiescing = null;
const checkpoint = await establishCheckpoint(
@@ -497,12 +492,7 @@ export function createLivePollHandoffCoordinator<Value>(
}
if (quiescence !== "QUIESCED") {
failClosed();
return handoffFailure(
quiescence === "TIMED_OUT"
? "IDLE_TIMEOUT"
: "PROVIDER_UNAVAILABLE",
"RECOVER",
);
return quiescenceFailure(quiescence);
}
quiescing = null;
const checkpoint = await establishCheckpoint(
@@ -588,8 +578,10 @@ export function createLivePollHandoffCoordinator<Value>(
return handoffFailure("ABORTED", "RECOVER");
}
if (selected.kind === "TIMEOUT") {
// 1101/04-02. Design 13.1: the checkpoint authority did not answer in
// time, the same kind as when it throws.
candidate.controller.abort();
return handoffFailure("IDLE_TIMEOUT", "RECOVER");
return handoffFailure("PROVIDER_UNAVAILABLE", "RECOVER");
}
if (selected.kind !== "VALUE") {
candidate.controller.abort();
@@ -691,13 +683,12 @@ export function createLivePollHandoffCoordinator<Value>(
quiescing = null;
transitionCandidate = null;
transitioning = false;
if (outcomes.includes("TIMED_OUT")) {
return handoffFailure("IDLE_TIMEOUT", "CLOSE");
}
if (outcomes.includes("TIMER_FAILED")) {
return handoffFailure("PROVIDER_UNAVAILABLE", "CLOSE");
}
return realtimeSuccess(undefined);
// 1101/04-02. A drain past its bound is PROVIDER_UNAVAILABLE/CLOSE, as in
// the stream and reconnect coordinators, never the transport's
// IDLE_TIMEOUT.
return outcomes.every((outcome) => outcome === "QUIESCED")
? realtimeSuccess(undefined)
: handoffFailure("PROVIDER_UNAVAILABLE", "CLOSE");
}
function inspect(): LivePollHandoffInspection {
@@ -871,6 +862,21 @@ function handoffFailure(
: realtimeFailure(kind, operation, retryable);
}
/**
* 1101/04-02. Design 13.1: a prior writer that does not quiesce in time is a
* stalled effect, APPLY_FAILED, never the transport's IDLE_TIMEOUT. Retryable
* as before: the handoff fail-closes and only a new one can run.
*/
function quiescenceFailure(
outcome: Exclude<QuiescenceOutcome, "QUIESCED">,
): Extract<RealtimeResult<never>, { ok: false }> {
return handoffFailure(
outcome === "TIMED_OUT" ? "APPLY_FAILED" : "PROVIDER_UNAVAILABLE",
"RECOVER",
true,
);
}
function remapFailure(
failure: RealtimeFailure,
operation: RealtimeOperation,
@@ -266,7 +266,7 @@ describe("live/poll authoritative writer handoff", () => {
harness.clock.advance(100);
await expect(closing).resolves.toMatchObject({
ok: false,
error: { kind: "IDLE_TIMEOUT", operation: "CLOSE" },
error: { kind: "PROVIDER_UNAVAILABLE", operation: "CLOSE", retryable: true },
});
release?.(realtimeSuccess(undefined));
@@ -356,9 +356,11 @@ describe("live/poll authoritative writer handoff", () => {
expect(harness.clock.sleepers).toHaveLength(1);
harness.clock.advance(100);
// 1101/04-02. The prior writer's effect stalled (design 13.1), not the
// transport's IDLE_TIMEOUT.
await expect(transition).resolves.toMatchObject({
ok: false,
error: { kind: "IDLE_TIMEOUT", operation: "RECOVER" },
error: { kind: "APPLY_FAILED", operation: "RECOVER", retryable: true },
});
expect(harness.recover).not.toHaveBeenCalled();
expect(harness.coordinator.inspect()).toMatchObject({
@@ -367,6 +369,32 @@ describe("live/poll authoritative writer handoff", () => {
});
});
it("fails a probe activation closed when poll cannot quiesce before the bound", async () => {
const harness = createHarness({
initial: "POLL",
apply: vi.fn(async ({ writer }) =>
writer === "POLL"
? await new Promise<RealtimeResult<void>>(() => {})
: realtimeSuccess(undefined),
),
});
void harness.coordinator.currentWriter()!.write("hung-poll", 4);
const live = expectProbe(harness.coordinator.beginLiveProbe());
await flush();
const activation = live.activate();
await flush();
expect(harness.clock.sleepers).toHaveLength(1);
harness.clock.advance(100);
await expect(activation).resolves.toMatchObject({
ok: false,
error: { kind: "APPLY_FAILED", operation: "RECOVER", retryable: true },
});
expect(harness.recover).not.toHaveBeenCalled();
expect(harness.coordinator.inspect().state).toBe("CLOSED");
});
it("keeps poll authoritative while probing, then recovers and drains live values serially", async () => {
const firstLive = deferred<RealtimeResult<void>>();
const order: string[] = [];
@@ -550,9 +578,10 @@ describe("live/poll authoritative writer handoff", () => {
expect(harness.clock.sleepers).toHaveLength(1);
harness.clock.advance(100);
// 1101/04-02. The checkpoint authority did not answer in time.
await expect(transition).resolves.toMatchObject({
ok: false,
error: { kind: "IDLE_TIMEOUT", operation: "RECOVER" },
error: { kind: "PROVIDER_UNAVAILABLE", operation: "RECOVER", retryable: true },
});
expect(checkpointIsCurrent?.()).toBe(false);
expect(harness.coordinator.inspect().state).toBe("CLOSED");
@@ -579,7 +608,7 @@ describe("live/poll authoritative writer handoff", () => {
harness.clock.advance(100);
await expect(closing).resolves.toMatchObject({
ok: false,
error: { kind: "IDLE_TIMEOUT", operation: "CLOSE" },
error: { kind: "PROVIDER_UNAVAILABLE", operation: "CLOSE", retryable: true },
});
// RT-RR-03. A second close re-runs rather than replaying a cached verdict.
// The writer is still hung, so it still reports a timeout.
@@ -588,7 +617,7 @@ describe("live/poll authoritative writer handoff", () => {
harness.clock.advance(100);
await expect(second).resolves.toMatchObject({
ok: false,
error: { kind: "IDLE_TIMEOUT", operation: "CLOSE" },
error: { kind: "PROVIDER_UNAVAILABLE", operation: "CLOSE", retryable: true },
});
});
@@ -616,7 +645,7 @@ describe("live/poll authoritative writer handoff", () => {
harness.clock.advance(100);
await expect(first).resolves.toMatchObject({
ok: false,
error: { kind: "IDLE_TIMEOUT", operation: "CLOSE" },
error: { kind: "PROVIDER_UNAVAILABLE", operation: "CLOSE", retryable: true },
});
// The writer finishes after the first close gave up.
@@ -654,7 +683,7 @@ describe("live/poll authoritative writer handoff", () => {
harness.clock.advance(100);
await expect(closing).resolves.toMatchObject({
ok: false,
error: { kind: "IDLE_TIMEOUT", operation: "CLOSE" },
error: { kind: "PROVIDER_UNAVAILABLE", operation: "CLOSE", retryable: true },
});
harness.clock.advance(100);