Files
clean-architecture-frontend…/docs/design/2026-08-01-runtime-integrity-refactor-design.md
DongHyeonka 75fad73a7d docs(records): 기록·설계서·결정 기록 67개에 한국어 머리 블록을 단다
문제: 옮긴 기록은 지금 동작을 설명하는지, 상태가 무엇인지, 지금
정본이 어디인지 알 길이 없다. 설계서·계획서 27개와 docs/architecture
목표 설계 16개에는 상태 칸이 없고, VD는 「상태: Accepted」 같은 영어
값을 쓴다.

고른 방법: docs-system.md 4절 형식으로 맨 위에 머리 블록을 달고 본문은
한 글자도 고치지 않는다. 상태는 기계 변환이다.
- 설계서: Accepted·확정·정본·설계 완료 → 채택, 상태 줄이 없으면
  확인 안 함 (채택 4, 확인 안 함 21)
- 계획서: 체크 상자가 모두 표시됐으면 끝남, 아니면 확인 안 함. SPEC.md는
  같은 폴더 plan.md와 같은 근거(0.2.0으로 끝난 라운드)로 끝남 (끝남 5,
  확인 안 함 14. 이미 블록이 있던 5개는 그대로)
- 결정 기록: Accepted → 채택, 날짜가 붙은 뒤늦은 보완 메모가 본문에
  있으면 채택(보완) (채택 14, 채택(보완) 9). 프론트 VD는 처음부터
  한국어로 썼고 번역하지 않으므로 둘째 줄은 「원문이다」 문구다.
- 작성일: 파일 이름 날짜 → 본문 날짜 줄(VD는 `결정일:`) → git 첫 추가일.

위험: VD-09·11·13은 git으로 보면 결정 뒤 본문이 그 자리에서
고쳐졌지만 본문에 날짜 표시가 없어 기계 규칙대로 채택으로 두었다.
보완으로 올릴지는 사람이 정한다. 「현재 정본」은 지금 있는 살아 있는
문서나 코드 경로만 쓴다.

검증: 블록과 그 뒤 빈 줄 하나를 빼면 72개 모두 `git show HEAD:`와 바이트가
같다. 뒤 커밋의 문서 검사 head 규칙으로 돌려 문제 0건.
2026-11-08 17:25:41 +09:00

8.3 KiB

기록 · 설계서 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 확인 안 함
  • 작성일: 2026-08-01
  • 요약: release 산출물과 boot 프로토콜에서 실패를 통과시키던 경로를 먼저 막고, 런타임 소유권을 드러낸 뒤 도구와 큰 adapter를 정리하는 단계별 리팩터링 설계다.
  • 현재 정본: scripts/contracts/release-artifacts.ts, src/bootstrap/

Runtime Integrity Refactor Design

Purpose

Apply the repository-wide refactoring review without discarding the current uncommitted implementation snapshot. The program closes release and boot fail-open paths first, then makes runtime ownership explicit, and finally consolidates tooling and large adapter modules.

Chosen approach

Use a phased compatibility migration.

  • Rejected: a big-bang V2-only rewrite. It removes legacy code quickly but combines artifact, boot, HTTP, cache, and worker changes into one unsafe release.
  • Rejected: patch only the currently failing verifier. It makes one gate green while leaving cross-version boot acceptance, schema drift, and duplicate execution contracts intact.
  • Chosen: introduce explicit V1/V2 discriminated contracts, route every writer and reader through them, migrate production execution onto one registry, and remove legacy bridges only after each vertical is covered by tests.

Program boundaries

The work is split into independently testable sub-projects.

  1. Release artifact integrity
    • One executable schema for release, runtime-config, and build artifacts.
    • Version-specific token projection.
    • Real build-to-verification integration coverage.
  2. Boot protocol integrity
    • Exact supported version selection.
    • V1/V1 and V2/V2 pairing only.
    • Mandatory V2 contract-set verification and HTTP(S) endpoint policy.
  3. Scope-owned server state and HTTP contract execution
    • A scope generation owns QueryClient, mutations, optimistic state, and cross-context resources.
    • The composed external-contract registry is the only executable HTTP registry.
  4. Optional runtime and Service Worker lifecycle
    • Generation-fenced start/stop.
    • Nonce-based activation/reset acknowledgements.
    • Bounded install streams and one verified rollback revision.
  5. Quality infrastructure
    • Typed subprocess results, bounded CI steps, generated artifact schemas, one authoritative architecture analyzer, and representative coverage.
  6. Adapter hardening and decomposition
    • Shared bounded-body and worker-RPC primitives.
    • IndexedDB singleflight.
    • Route-policy closure, invalidation tuple identity, and focused extraction from the largest adapter runtimes.

Release artifact architecture

scripts/contracts/release-artifacts.ts owns Zod schemas for Release Manifest V1/V2, Runtime Config V1/V2, and Build Manifest V1. Writers parse before writing; readers parse before comparing. JSON Schema files are generated views and never an independent source of truth.

projectReleaseTokens(document) maps a parsed artifact into comparison tokens. V1 projects the legacy API contract version. V2 projects contractSet.setDigest as contractSetDigest and never requires the removed scalar. Token comparison receives projected values, not arbitrary records.

Boot protocol architecture

The version selector accepts only "1" and "2.0". Parsing preserves the versioned shape through manifest loading:

type BootProtocol =
  | { kind: "V1"; config: RuntimeConfigV1; manifest: ReleaseManifestV1 }
  | { kind: "V2"; config: RuntimeConfigV2; manifest: ReleaseManifestV2 };

Mixed pairs fail before application composition. V2 requires a contract set and verifies it exactly once. Endpoint protocols are http: or https: in local and development, and https: elsewhere.

Scope and execution ownership

A ScopeGenerationBundle owns every resource capable of retaining account data: QueryClient, mutation admission, optimistic layers, cross-context invalidation, and optional closers. Transition order is fixed:

  1. publish FENCED and render only the transition surface;
  2. close query and mutation admission;
  3. abort in-flight work and roll back optimistic layers;
  4. detach providers and close scoped transports;
  5. clear and dispose the old QueryClient;
  6. construct and mount a new bundle;
  7. publish READY.

Mandatory cleanup failure remains terminal/FENCED. It never publishes READY.

The composed contract-contribution registry becomes the only HTTP operation registry. Feature gateways resolve installed operations and map executor outcomes; they do not carry parallel schemas or retry definitions.

Optional runtime and worker lifecycle

Optional hosts use explicit lifecycle states plus a generation token. Every continuation after an await verifies that generation. Stop closes admission, waits for pending startup to settle, and disposes children in reverse order.

Service Worker activation and reset messages are discriminated by kind and carry source build, target build, nonce, and a typed result. Activation calls skipWaiting() only after every controlled client acknowledges the same nonce. Install owns a deadline AbortController, reads at most declared bytes plus one, aborts siblings on first failure, and atomically records current and previous verified asset digests.

Tooling and schema policy

Subprocesses return SUCCESS, EXPECTED_DIAGNOSTIC, TOOL_FAILURE, SIGNAL, or TIMEOUT. Negative fixtures must match expected diagnostic identifiers; arbitrary non-zero exits are failures. CI gates have per-step timeouts and are generated or structurally checked against config/ci/gates.json.

The TypeScript-aware custom source analyzer becomes authoritative unless a dependency-cruiser version with TypeScript 7 support is selected. A zero-module analysis is always a gate failure. Concrete adapter-to-adapter dependencies are replaced by injected ports or explicitly named shared infrastructure.

Error handling

  • Artifact or boot schema mismatches use stable, version-specific failure codes.
  • Unknown future versions fail closed and do not fall back to V1.
  • Mandatory scope cleanup and worker protocol failures remain terminal.
  • Transport readers return closed failure unions; UNKNOWN is not a success fallback.
  • Tool invocation failures are never accepted as expected fixture rejection.

Testing strategy

Every behavior change follows red-green-refactor. Required matrices include:

  • Release V1/V2 success plus field, digest, package, and schema tampering.
  • Boot V1/V1 and V2/V2 success; mixed and future versions fail.
  • Synchronous old-data hiding, late completion fencing, and cleanup failure.
  • Old-page/new-worker activation, partial acknowledgement, reset results, and install deadline/body limits.
  • Process spawn error, null status, signal, timeout, and expected diagnostic.
  • IndexedDB concurrent open, worker RPC crash/abort, and composite-key collision.

Repository-wide verification includes types, lint, unit/component/integration, browser capability tests where supported, build, release verification, schema round-trip, architecture analysis, and diff hygiene.

Delivery order and compatibility

Release artifact integrity and boot protocol integrity ship first and retain a read-only V1 window. Scope ownership and HTTP registry consolidation ship next. Optional runtime, quality infrastructure, and adapter decomposition follow as separate reviewable changes. Public facades remain stable during internal file splits; removal of legacy exports occurs only after static usage checks reach zero.

Acceptance criteria

  • A clean V2 build passes release verification; every supported tamper fails.
  • No accepted V2 boot bypasses contract-set verification.
  • FENCED renders no previous-account data and late work cannot mutate a new generation.
  • Selected optional capabilities have a concrete host or fail composition.
  • Negative quality fixtures cannot pass because a tool crashed or timed out.
  • Checked-in JSON schemas exactly match executable schemas.
  • Architecture analysis covers a non-zero complete module graph.
  • No source file contains an actual NUL byte, and all final verification gates report their real status.