chore: sync the frontend template from 4dc033c to 8157ad4
The product was materialized from the template at `4dc033c` and has stayed on it through 43 template commits, so it was missing all three rounds of adapter remediation — including files it never had, such as the shared `abortable-operation` primitive and the `exact-snapshot` decoder that later fixes are written against. Taking only the newest round was not possible for that reason: the delta is coherent only as a whole. The product had not touched `src/adapters` at all since materialization, so the 140-file delta applied with a three-way merge and no conflicts. `package.json` was the single overlap and merged cleanly: the product owns `name`, the template contributed `check:adapter-inventory`, `check:remediation-ledger` and the image-resolve-signal type fixture. All 24 product-owned files — README, index.html, CI workflow, i18n catalog, home page, generated schemas, evidence scripts, component and visual snapshots — are byte-identical to `main`. `template.lock.json` now pins the synced revision and tree. Verified in this repository, not inherited from the template: six type projects, lint, nine gates (adapter inventory, remediation ledger, registries, diagnostics, realtime boundaries, architecture, browser file/storage boundaries, optional recipes, documentation), the production build, and 2,054 of 2,073 tests. The 19 failures are all in `tests/unit/ci-artifact-contract.test.ts` and are the same pre-existing sandbox RLIMIT, EMFILE, umask and `/tmp` permission behaviour the template records; four suites that failed once under parallel load pass in isolation. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
co-authored by
Claude Opus 5
Claude Opus 5
parent
002ba3624e
commit
4bff9ca151
@@ -690,11 +690,20 @@ default physical layout은 구현과 동일하게 다음과 같다.
|
||||
```text
|
||||
/ca-frontend-opfs-v1/
|
||||
authorities/<authorityToken>/<namespaceToken>/<partitionToken>/
|
||||
objects/<object-id-prefix>/<opaque-object-id>/<generation>/manifest.json
|
||||
objects/<object-id-prefix>/<opaque-object-id>/<generation>/manifest.json # physical v1 (read-only)
|
||||
objects/<object-id-prefix>/<opaque-object-id>/g<generation>-<token>/manifest.json # physical v2 (new writes)
|
||||
chunks/sha256/<digest-prefix>/<digest>.bin
|
||||
staging/<transaction-id>/receipt.json
|
||||
```
|
||||
|
||||
physical v2는 STO-01 수정의 일부다. logical `generation`은 설계상 transaction 간에
|
||||
재사용되므로, 늦게 도착한 T1 보상이 같은 logical generation을 쓰는 T2의 디렉터리를
|
||||
지울 수 있었다. v2는 transaction-unique `physicalGenerationId` fencing token을
|
||||
경로, staging receipt, prepared object에 함께 기록해 보상이 자기 transaction의
|
||||
디렉터리만 삭제하도록 만든다. expand 단계에서는 v1 경로/receipt/prepared object를
|
||||
계속 읽고 새 write만 v2로 쓴다. rollback window가 끝나기 전에 v1 physical
|
||||
generation을 일괄 삭제하지 않는다.
|
||||
|
||||
구조화 metadata, query, revision, refcount와 operation journal은 IndexedDB가
|
||||
소유한다. OPFS에는 immutable chunk와 bounded runtime-schema-validated manifest만
|
||||
둔다. readable `scope.namespace`는 경로에 쓰지 않는다.
|
||||
@@ -736,6 +745,23 @@ COMMITTED <- 사용자에게 보이는 유일한 commit point
|
||||
CLEANED -> journal 제거
|
||||
```
|
||||
|
||||
보상(compensation)은 saga의 반쪽이며 다음 규칙을 따른다.
|
||||
|
||||
- journal row와 budget reservation은 physical cleanup effect가
|
||||
`CLEANED` 또는 `ALREADY_CLEAN`으로 확인된 뒤에만 해제한다. timeout, crash,
|
||||
malformed response, `EFFECT_UNKNOWN`은 성공이 아니며 `PREPARING`/`FILES_READY`를
|
||||
그대로 남기고 `OBJECT_RECONCILE`로 반환한다.
|
||||
- coordinator가 `abortPreparedPut()` 하나만 소유한다. worker client는 prepare 실패
|
||||
시 별도의 fire-and-forget abort를 발행하지 않는다. 중복 보상은 아직 남아 있어야
|
||||
할 journal row를 조기에 지우는 경로였다.
|
||||
- 보상은 caller signal을 상속하지 않는다. composition이 소유한 bounded
|
||||
`compensationSignal`을 사용하므로 이미 abort된 caller가 cleanup RPC 자체를
|
||||
시작조차 못 하게 만들 수 없다.
|
||||
- abort/cleanup은 origin mutation Web Lock을 physical 삭제와 staging 제거가 끝날
|
||||
때까지 계속 보유한다. lease를 먼저 release하지 않는다. 단, staging이 아직 없는
|
||||
transaction은 삭제할 것이 없으므로 lock을 기다리지 않고 `ALREADY_CLEAN`을
|
||||
반환한다. 이는 자기 자신이 취소하는 BEGIN과의 deadlock을 막는다.
|
||||
|
||||
- `PREPARING` crash: partial staging을 검증 후 resume하거나 purge한다.
|
||||
- `FILES_READY` crash: expected generation과 digest가 맞으면 idempotent logical
|
||||
commit, 아니면 quarantine한다.
|
||||
|
||||
@@ -37,12 +37,41 @@ vendor 결정 전에는 안전한 기본값이 아니다.
|
||||
abort마다 `http.request.completed` diagnostics를 정확히 한 번 남긴다.
|
||||
`api.request.failed` telemetry는 retry가 끝난 terminal non-abort failure에만
|
||||
정확히 한 번 발행한다.
|
||||
5-1. V2 client와 V3 contract executor는 각각 자신의 logical execution에 대해
|
||||
이 규칙을 만족한다. V3에서는 execution site가 `HttpExecutionObservation`
|
||||
typed record 하나만 만들고, composition root의
|
||||
`createHttpObservationProjector`가 유일한 projection authority다. observation은
|
||||
arbitrary context map이 아니며 projector는 `route_id`, `operation_id`,
|
||||
`operation`, `outcome`, `error_kind`, `http_status_group`,
|
||||
`attempt_count_bucket`, `duration_bucket`만 사용한다. raw attempt count,
|
||||
duration, status, URL, intent, key, input identity와 내부 `terminalReason`은
|
||||
sink로 나가지 않는다. effect certainty가 운영상 필요해지면 `effect_certainty`
|
||||
key와 닫힌 value policy를 contract·fixture·이 ADR에 동시에 추가한 뒤에만
|
||||
전달한다.
|
||||
5-2. caller cancellation과 scope fence는 API failure가 아니다. diagnostics는 한
|
||||
번 남기고 `api.request.failed`는 발행하지 않는다.
|
||||
5-3. `routeId`는 installed operation-executor 경계의 필수 입력이다. feature
|
||||
gateway가 소유한 low-cardinality route identity를 URL에서 재구성하지 않는다.
|
||||
6. `app.boot.failed`, `ui.render.failed`, `release.mismatch.detected`,
|
||||
`telemetry.delivery.dropped`를 production path에 연결한다. cache와 storage
|
||||
실패는 diagnostics로 기록하되 raw key/value를 기록하지 않는다.
|
||||
7. queue full, invalid event/context, serialization과 sink failure는 제한된
|
||||
reason bucket으로 집계한다. drop observer의 failure는 다시 telemetry를
|
||||
발행하지 않는 nonrecursive 경계다.
|
||||
7-1. telemetry adapter lifecycle은 `ACTIVE | DISPOSED` 둘뿐이다. `dispose()`는
|
||||
한 번만 전이하고 `pagehide` listener 제거, queue 비우기, scheduled callback
|
||||
generation 무효화, in-flight sink `AbortController` abort를 모두 수행한다.
|
||||
dispose 뒤 `emit()`은 no-op이고 새 flush는 스케줄되지 않으며, abort를 무시한
|
||||
sink가 늦게 settle해도 post-dispose delivery state를 갱신하거나 재스케줄하지
|
||||
못한다. 종료 중 drop telemetry를 재귀적으로 발행하지 않는다.
|
||||
7-2. `flush()`는 active delivery promise를 join한다. 이미 진행 중인 flush가
|
||||
있으면 같은 promise를 반환하므로 `await flush()`는 실제 settle을 뜻한다.
|
||||
7-3. runtime `infrastructure.dispose()`는 diagnostics/state dependency를 파괴하기
|
||||
전에 `telemetry.dispose()`를 먼저 호출한다.
|
||||
7-4. queue/entry capacity는 construction-time 계약이다. `Number.isSafeInteger`가
|
||||
아니거나 1 미만이거나 문서화된 ceiling(각각 `MAX_TELEMETRY_QUEUE`,
|
||||
`MAX_DIAGNOSTIC_ENTRIES` = 10,000)을 넘으면 `TypeError`로 거절한다. NaN/Infinity가
|
||||
조용히 eviction을 비활성화하는 경로를 남기지 않는다.
|
||||
8. diagnostics와 telemetry failure는 제품 흐름, HTTP 결과, route transition,
|
||||
storage/cache fallback과 React error surface를 바꾸지 않는다.
|
||||
9. mount 전 bootstrap failure는 안전한 build/config/error kind만 별도 evidence로
|
||||
@@ -79,6 +108,11 @@ route/application/HTTP/cache/storage/bootstrap
|
||||
queue full, sink/observer failure와 pre-mount boot evidence를 검증한다.
|
||||
- HTTP integration은 success, retry recovery, terminal failure와 abort의 producer
|
||||
횟수, route/operation/correlation context와 요청 값 비노출을 검증한다.
|
||||
- `tests/integration/http-execution-v3-observability.test.ts`는 V3 terminal
|
||||
outcome이 실제로 closed allowlist를 통과하는지, terminal non-abort failure가
|
||||
`api.request.failed`를 정확히 한 번 발행하는지, cancellation/scope fence가
|
||||
발행하지 않는지, feature route ID가 executor 경계까지 보존되는지, sink 예외가
|
||||
HTTP 결과를 바꾸지 못하는지를 검증한다.
|
||||
- cache/storage/release/application/runtime test는 각 production wiring과
|
||||
diagnostics failure isolation을 검증한다.
|
||||
|
||||
|
||||
@@ -262,6 +262,55 @@ auth-required operation은 session state가 `authenticated`가 아니면 fetch
|
||||
`integration-failed`, `unauthenticated`와 credential attach rejection을 anonymous
|
||||
request로 downgrade하지 않는다.
|
||||
|
||||
#### 5-0. Logical effect certainty는 단조 증가한다
|
||||
|
||||
`PhysicalAttemptState`는 현재 attempt만 설명한다. logical execution 전체에는
|
||||
별도의 monotonic accumulator를 두고 `joinMutationEffectCertainty`로 join한다.
|
||||
join 순서는 보수적이다.
|
||||
|
||||
```text
|
||||
NOT_STARTED < NOT_APPLIED < MAYBE_APPLIED < APPLIED_CONFIRMED
|
||||
```
|
||||
|
||||
`fetch()` dispatch 시점에 command는 즉시 `MAYBE_APPLIED`를 기록한다. 이후 retry
|
||||
loop entry, pre-dispatch final invariant, scope fence, cancellation, timeout
|
||||
return은 모두 accumulator를 읽는다. 아직 보내지 않은 새 retry가 있다는 이유로
|
||||
전체 logical operation을 `NOT_STARTED`로 되돌리지 않는다. query operation은
|
||||
`NOT_APPLICABLE`로 남고 이 lattice를 쓰지 않는다.
|
||||
|
||||
#### 5-1. Installed auth profile registry (V3 집행)
|
||||
|
||||
`installRestAuthProfileRegistry()`가 composition 시점에 profile을 한 번 설치하고
|
||||
`INSTALLED_REST_AUTH_PROFILES`가 유일한 authority다. contract composition
|
||||
(`assertExecutionPolicy`)은 등록되지 않은 `authProfileId`를 거절하므로 executor는
|
||||
runtime에 profile을 발명하지 않는다. profile은 다음을 exact하게 소유한다.
|
||||
|
||||
- Fetch `credentials` (credential collaborator가 바꿀 수 없다)
|
||||
- `allowedCredentialHeaders`: 이 operation이 허용하는 정확한 proof header 집합
|
||||
- `requiredCredentialHeaders`: dispatch 전에 반드시 관찰되어야 하는 집합
|
||||
|
||||
`CredentialPatchOutcome.READY`는 proof header만 담는다. `credentials` field는
|
||||
제거되었다. credential owner가 transport-owned header(`accept`, `content-type`,
|
||||
`idempotency-key`)나 forbidden header를 넣거나, profile이 허용하지 않는 header를
|
||||
넣거나, required header를 빠뜨리면 `AUTH_INTEGRATION_FAILURE`이고 fetch 0회이며
|
||||
command effect는 `NOT_STARTED`다. `idempotency-key`는 contract-owned이므로 더
|
||||
구체적인 `UNEXPECTED_IDEMPOTENCY_KEY` request violation으로 남는다.
|
||||
`UNAUTHENTICATED`는 user/session state이지 integration failure가 아니다.
|
||||
|
||||
transport-owned header는 credential header 뒤에 기록되어 key ordering으로도
|
||||
shadow될 수 없고, final invariant가 `init.credentials`와 profile을 다시 대조하며
|
||||
allowed/required credential header 집합을 독립적으로 재검증한다.
|
||||
|
||||
`AUTH_MODE=demo`는 profile을 약화시키지 않는다. `createDemoSessionAdapter`가
|
||||
고정된 비밀 아닌 `DEMO_AUTHORIZATION_MARKER` proof header를 제공하여 strict
|
||||
`REFERENCE_EXTERNAL_BEARER`를 그대로 만족시킨다. 진짜 anonymous backend는 별도
|
||||
anonymous contract/profile을 composition에서 선택해야 한다.
|
||||
|
||||
credential collaborator는 `AuthOperationContext { signal, deadlineAtMonotonicMs }`를
|
||||
받는다. cooperative owner는 스스로 중단하고, non-cooperative owner도 executor가
|
||||
같은 lifetime signal과 race하므로 operation 수명을 넘기지 못하며 late completion은
|
||||
관찰되지 않는다.
|
||||
|
||||
### 6. Cookie auth, CSRF와 CORS
|
||||
|
||||
same-origin BFF cookie session을 기본 권장한다.
|
||||
|
||||
@@ -11,6 +11,26 @@
|
||||
첫 제품 stream/Web Push를 선택할 때, 또는 backend replay/hosting/provider
|
||||
protocol이 바뀔 때
|
||||
|
||||
|
||||
## 스트림 lifecycle은 freshness와 직교한다 (R-02, R-03)
|
||||
|
||||
`RealtimeStreamLifecycle = OPEN | DRAINING | CLOSED`는 freshness
|
||||
(`UNKNOWN/CURRENT/STALE/RESYNCING`)와 별개다.
|
||||
|
||||
- effect/recovery deadline에 도달하면 commit capability를 즉시 영구 무효화하고
|
||||
abort한다. caller에는 bounded `IDLE_TIMEOUT`(non-retryable, operation
|
||||
`APPLY`/`RECOVER`)을 반환하되 **실제 task는 버리지 않고 retain**한다.
|
||||
- retain된 task가 하나라도 있으면 stream은 `DRAINING`이고 새 event/recovery
|
||||
admission을 거절한다. 실제 settlement가 일어나야 `STALE`로 돌아가
|
||||
authoritative recovery를 요구하거나, close 요청이면 `CLOSED`가 된다.
|
||||
- `close()`는 `Promise<RealtimeResult<void>>`다. 모든 retain task가 실제로
|
||||
settle해야 success이고, drain bound를 넘기면 `IDLE_TIMEOUT/CLOSE`를 반환하며
|
||||
stream은 계속 `DRAINING`이다. teardown success가 곧 quiescence다.
|
||||
- LIVE↔POLL overflow fail-close는 active/probe/quiescing/transition lease를
|
||||
모두 abort한 뒤 **retired writer set**으로 옮기고 나서 reference를 지운다.
|
||||
`close()`는 current와 retired를 dedupe해 함께 기다리므로, 버려진
|
||||
non-cooperative writer가 아직 실행 중인데 close가 성공을 보고할 수 없다.
|
||||
|
||||
## 배경
|
||||
|
||||
현재 optional recipe catalog는 realtime capability에
|
||||
|
||||
@@ -19,6 +19,37 @@
|
||||
- 운영 절차:
|
||||
[API contract와 server-state recovery](../operations/api-contract-and-server-state-recovery.md)
|
||||
|
||||
|
||||
## Installed binding snapshot과 stream cleanup bound (R-01, R-04, R-05, R-06)
|
||||
|
||||
- `installBrowserRpcContractBindings()`가 registry를 **parse → validate →
|
||||
install** 순서로 처리한다. own data descriptor만 읽어 exact key set으로
|
||||
null-prototype frozen snapshot을 만들고, 그 snapshot을 검증한 뒤 설치한다.
|
||||
getter/accessor, extra key, symbol key, malformed descriptor, revoked proxy는
|
||||
composition-time `TypeError`이며 getter는 호출조차 되지 않는다. runtime과
|
||||
transport call은 이후 snapshot만 읽으므로 validation 이후 registry mutation이
|
||||
replay policy·deadline·byte ceiling·transport selection을 바꿀 수 없다.
|
||||
- server stream 종료는 transport iterator에 lifecycle authority를 위임하지
|
||||
않는다. commit/admission generation은 즉시 fence하고 listener는 바로 해제하며,
|
||||
`iterator.return()`은 cleanup **요청**으로서 bound 안에서만 기다린다. 끝나지
|
||||
않은 cleanup은 관찰만 유지되고(unhandled rejection 없음) application generator는
|
||||
bound 안에 종료된다. cleanup rejection은 이미 선택된 application failure를
|
||||
덮지 않는다.
|
||||
- WebSocket text frame은 allocation 전에 admission한다. UTF-16 code unit 길이가
|
||||
이미 cap을 넘으면 encoder를 만들지 않고 거절하고, 나머지는 early exit하는
|
||||
code-point 누적으로 센다. valid surrogate pair는 4 bytes, lone surrogate는
|
||||
`TextEncoder`와 동일하게 replacement 3 bytes다.
|
||||
- clock/fence collaborator 예외는 Result 경계를 벗어나지 않는다. clock 실패는
|
||||
`SERVER_FAILURE/RPC_RUNTIME_DEPENDENCY_FAILED`, capture 실패는
|
||||
`SCOPE_GENERATION_CHANGED/RPC_SCOPE_GENERATION_UNAVAILABLE`, `isCurrent` 실패는
|
||||
fail-closed로 canonicalize하며 listener/timer는 단일 exit path에서 정확히 한 번
|
||||
해제한다.
|
||||
|
||||
Browser RPC는 여전히 `AVAILABLE_NOT_COMPOSED`다. 선택된 Connect/gRPC-Web
|
||||
transport는 enqueue-time `maxBufferedBytes`, raw/decompressed ceiling,
|
||||
cancel/closed receipt, terminal framing, target browser와 load behavior를
|
||||
별도로 증명해야 조립할 수 있다 (R-07).
|
||||
|
||||
## 1. 먼저 축을 분리한다
|
||||
|
||||
네 이름은 같은 종류의 대안이 아니다.
|
||||
|
||||
@@ -34,6 +34,16 @@ capability가 설치됐거나 production-ready라는 뜻이 아니다.
|
||||
[Frontend ports, adapters, and boundaries](./frontend-ports-adapters-and-boundaries.md)
|
||||
를 따른다.
|
||||
|
||||
|
||||
## Bounded task lease와 DRAINING (R-02, R-03)
|
||||
|
||||
non-cooperative effect/recovery authority 하나가 stream tail 전체를 영구
|
||||
wedge하지 못하도록, common coordinator는 각 task를 deadline으로 감싼다. deadline
|
||||
초과 시 commit capability는 즉시 취소되지만 task 자체는 `retainedTasks`에 남아
|
||||
stream을 `DRAINING`으로 유지한다. `close()`는 이 retain 집합이 실제로 settle해야
|
||||
성공을 반환한다. handoff coordinator도 같은 원칙으로 fail-close된 writer를
|
||||
`retiredWriters`에 보존한다.
|
||||
|
||||
## 0. 현재 상태와 목표 delta
|
||||
|
||||
이 문서에서 설계 승인, reference source 존재, production 조합과 target browser의
|
||||
|
||||
Reference in New Issue
Block a user