fix(docs): 설계 주석에 문서 이름을 붙이고 지운 뒤 끊기는 링크를 없앤다 (1101/14-01)

문제: 코드 주석 87곳(74파일, .dependency-cruiser.json 포함)이 "Spec §N"
처럼 문서 이름 없이 절 번호만 적는다(대문자 83, 소문자 "spec §" 4).
가리키는 설계서는 README가 복사 뒤 지워도 된다고 한 docs/reviews/ 안에
있었다. 지울 수 있는 기록 검사는 경로 문자열만 찾아 이 참조를 잡지
못했다. 현재 계약 문서도 지울 수 있는 파일로 링크한다:
docs/reviews/adapters/INVENTORY.md 145행이 옆의 adapter 리뷰로,
docs/operations/adapter-remediation-ledger.md가 adapter 리뷰와
docs/superpowers/plans의 계획으로.

고른 방법:
- 주석의 "Spec §"/"spec §"를 "scale-architecture.md §"로 바꾼다(앞
  커밋이 옮긴 docs/architecture/scale-architecture.md). 설명 문장과 절
  번호는 그대로다. 절 번호가 없는 "Spec §"는 없었다.
- tests/unit/deletable-history-documents.test.ts에 "spec" + 선택 공백 +
  "§"(대소문자 무시)를 거부하는 검사를 더하고, 검사 대상에
  .dependency-cruiser.json을 넣는다.
- README "Files you can delete after copying"에서 INVENTORY.md 한 파일
  대신 docs/reviews/adapters/ 폴더를 남기게 하고 이유(INVENTORY 행과
  ledger가 그 리뷰로 링크한다)를 적는다. docs/README.md §3도 같게 고친다.
  INVENTORY의 행 구조는 바꾸지 않는다.
- 남긴 adapter 리뷰와 ledger가 docs/superpowers/plans로 거는 링크 5곳은
  링크를 풀고 "작업 이력 계획, 복사본은 지울 수 있다"로 적는다.
버린 대안: INVENTORY 145칸의 링크를 그룹 이름으로 바꾸기. 템플릿에서도
상세 리뷰로 가는 길이 없어지고 수정이 145곳이다. 계획 3개도 지우기
목록에서 빼기. 지울 수 있는 폴더 안에 예외가 흩어지고, 계획이 다시
다른 이력을 가리키면 남길 목록이 계속 커진다.

위험·한계: 검사는 "HTML spec §4"처럼 다른 명세를 "spec §"로 부르는
주석도 거부한다. 그때는 "HTML Standard §4"처럼 이름을 쓴다.
src/contracts/storage-keys.ts:79의 "release-coherence plan Task 6"처럼
이름 없는 계획 참조는 이 검사가 잡지 않는다. 복사한 프로젝트가 이미
docs/reviews/adapters/를 지웠다면 링크는 계속 끊겨 있다. CHANGELOG.md의
이력 언급 4곳(:15 두 경로, :75 PRODUCT.md, :93)은 고치지 않았다.
check:remediation-ledger는 이 변경 전후 같은 4줄로 실패한다(이미 있던
실패, 게이트 밖). tests/unit/telemetry.test.ts의 describe 이름 하나가
바뀐다.

검증:
- RED: 치환 전 새 검사가 87줄을 들어 실패(1 failed | 1 passed).
- GREEN: 같은 테스트 2 passed. 변이 "// Spec §4. budgets live here"를
  src/platform/errors/app-error.ts에 넣으면 그 한 줄로 실패, 되돌림.
- 치환 diff: 바뀐 87줄 쌍이 토큰 외에 같음(스크립트 대조, 불일치 0).
- 삭제 실험(작업 트리 복사본에서 README 목록대로 지움): 끊긴 링크
  148→0, 끊긴 경로 언급 10→4(남은 4는 CHANGELOG.md), 이름 없는 설계
  참조 87→0, scale-architecture.md §N 87곳 중 없는 절 0. 같은 복사본에서
  verify-documentation-readiness PASS_SCOPED, 지울 수 있는 기록 테스트
  2 passed.
- node scripts/verify-documentation-readiness.ts: PASS_SCOPED
- node scripts/check-adapter-inventory.ts: PASS
- node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts
  tests/unit/documentation-readiness.test.ts tests/unit/telemetry.test.ts:
  50 passed. tests/architecture: 39 passed.
- npx tsc --noEmit (app·node·test): 모두 통과. 바꾼 TS 74파일 eslint 통과.
  .dependency-cruiser.json JSON 파싱 통과.
- 미실행: check:architecture(pnpm 필요).
This commit is contained in:
DongHyeonka
2026-11-03 07:17:49 +09:00
parent 0a7fbedca9
commit b26517e6f2
80 changed files with 126 additions and 107 deletions
+2 -2
View File
@@ -324,7 +324,7 @@
},
{
"name": "observability-vendors-live-behind-adapters",
"comment": "Spec §24. Features, platform, application, domain, contracts and presentation emit observability only through the provider-neutral TelemetryPort. A vendor telemetry SDK may be imported only by an adapter-side transport under src/adapters.",
"comment": "scale-architecture.md §24. Features, platform, application, domain, contracts and presentation emit observability only through the provider-neutral TelemetryPort. A vendor telemetry SDK may be imported only by an adapter-side transport under src/adapters.",
"severity": "error",
"from": {
"path": "^src/",
@@ -336,7 +336,7 @@
},
{
"name": "platform-kernel-is-product-neutral",
"comment": "Spec §4. src/platform holds product-neutral primitives (budgets, execution, telemetry pipeline, validation, error envelopes). It never reaches up into a concrete feature, context, adapter, bootstrap or presentation module. Exception: src/platform/routing composes deployable-app descriptors by type. Owner: frontend-platform. Revisit if routing gains a product-specific import.",
"comment": "scale-architecture.md §4. src/platform holds product-neutral primitives (budgets, execution, telemetry pipeline, validation, error envelopes). It never reaches up into a concrete feature, context, adapter, bootstrap or presentation module. Exception: src/platform/routing composes deployable-app descriptors by type. Owner: frontend-platform. Revisit if routing gains a product-specific import.",
"severity": "error",
"from": {
"path": "^src/platform/",
+1 -1
View File
@@ -222,7 +222,7 @@ reads them, except the one file noted below
| Path | Contents |
| --- | --- |
| `docs/superpowers/` | past plans and specs |
| `docs/reviews/` | reviews and the review guide. Keep `docs/reviews/adapters/INVENTORY.md`: `check:adapter-inventory` (FE-GATE-010) reads it |
| `docs/reviews/` | reviews and the review guide. Keep `docs/reviews/adapters/`: `check:adapter-inventory` (FE-GATE-010) reads its `INVENTORY.md`, whose rows link to the adapter reviews beside it, and `docs/operations/adapter-remediation-ledger.md` cites those reviews |
| `SPEC.md`, `tasks/` | requirements and task list of the 2026-09-25 review fix round |
| `CLAUDE.md` | review instructions for the template repository itself; replace it with your own |
| `PRODUCT.md` | product context of the template itself (users, purpose, principles) for design tools; replace it with your product's |
+1 -1
View File
@@ -76,5 +76,5 @@ README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어
| 경로 | 내용 |
|---|---|
| [`superpowers/`](superpowers/) | 과거 작업 계획과 스펙 |
| [`reviews/`](reviews/) | 리뷰 결과와 리뷰 가이드. `reviews/adapters/INVENTORY.md`만 게이트가 읽는다 |
| [`reviews/`](reviews/) | 리뷰 결과와 리뷰 가이드. `reviews/adapters/INVENTORY.md`만 게이트가 읽는다. `reviews/adapters/`는 지우지 않는다: INVENTORY의 행과 `operations/adapter-remediation-ledger.md`가 그 안의 리뷰로 링크한다 |
| [`../SPEC.md`](../SPEC.md), [`../tasks/`](../tasks/) | 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 `docs/` 밖에 그대로 둔다 |
@@ -3,7 +3,8 @@
> Source of truth for the execution state of every confirmed finding in
> [`docs/reviews/adapters/`](../reviews/adapters/README.md).
>
> Plan: [2026-08-13 adapter remediation](../superpowers/plans/2026-08-13-adapter-remediation.md).
> Plan: 2026-08-13 adapter remediation, a work-history plan under docs/superpowers/plans
> that a copied project may delete (README, "Files you can delete after copying").
> Baseline revision: `develop` / `4dc033cf33a5b6173bbf960d5eb464a406dc4c92`.
>
> Test paths are given at their current location. Two suites moved after
@@ -181,7 +181,7 @@ Build gate 필수 조건:
### SW-10 — message protocol을 kind별 discriminated schema와 full identity로 승격
- 우선순위/분류: **P1 before release hardening / 기존 계획 승계**
- 근거: `service-worker-protocol.ts:44-143`; `SERVICE_WORKER_PROTOCOL_VERSION = 1`; 기존 `docs/superpowers/plans/2026-08-01-http-worker-adapter-remediation.md` Task 5
- 근거: `service-worker-protocol.ts:44-143`; `SERVICE_WORKER_PROTOCOL_VERSION = 1`; 기존 2026-08-01 HTTP/worker remediation 계획(작업 이력 docs/superpowers/plans) Task 5
- 현재 동작: 모든 kind가 하나의 optional field bag을 공유하고 page-worker correlation은 주로 buildId에 의존한다. `service-worker-entry.ts:151-166`의 sync message는 codec 대신 V1 literal을 직접 만든다.
결정:
+3 -3
View File
@@ -96,18 +96,18 @@ listener/timer 정리, first-terminal-owner, late rejection 관찰, late native
6. **구조 리팩터링:** behavior가 모두 green인 상태에서 resumable upload, image CDN, OPFS worker, public cache, download strategy를 characterization-preserving extraction으로 나눈다.
7. **Promotion gaps:** preview decode, bounded origin/cache maintenance, Browser RPC concrete transport, image descriptor provider 등 명시된 gap을 실제 browser/provider conformance와 함께 구현한다. 완료 전 availability state를 올리지 않는다.
질문 없는 세부 실행 절차는 [Adapter Remediation Implementation Plan](../../superpowers/plans/2026-08-13-adapter-remediation.md)에 있으며, finding별 exact API·test·migration은 각 하위 리뷰가 source of truth다.
질문 없는 세부 실행 절차는 Adapter Remediation Implementation Plan(작업 이력 docs/superpowers/plans의 2026-08-13 계획. 복사한 프로젝트는 지울 수 있다)에 있으며, finding별 exact API·test·migration은 각 하위 리뷰가 source of truth다.
## 기존 계획과의 우선권
| 기존 계획 | 유지할 내용 | 이번 리뷰가 추가하는 선행 조건 |
| --- | --- | --- |
| [2026-08-01 HTTP/worker remediation](../../superpowers/plans/2026-08-01-http-worker-adapter-remediation.md) Tasks 1–3 | installed HTTP contract 단일 권위, provider-neutral outcome, bound-only query API | `N-01`~`N-03` auth/observation/effect 결함을 같은 V3 migration에 먼저 포함 |
| 2026-08-01 HTTP/worker remediation(작업 이력 계획) Tasks 1–3 | installed HTTP contract 단일 권위, provider-neutral outcome, bound-only query API | `N-01`~`N-03` auth/observation/effect 결함을 같은 V3 migration에 먼저 포함 |
| 같은 계획 Task 4 | bounded Service Worker marker reader | 그대로 유지; `SW-01`~`SW-09`의 cache/lifecycle truth를 함께 닫은 뒤 V2로 이동 |
| 같은 계획 Task 5 | full identity Service Worker protocol V2 | `SW-10`으로 승계. 새 protocol을 두 번 설계하지 않는다. |
| 같은 계획 Task 6 | shared IndexedDB persisted-row schema | 그대로 유지하되 `STO-06` deadline/drain lease test를 extraction 전 추가 |
| 같은 계획 Task 7 | OPFS/cache/download cohesive decomposition | `STO-01`~`STO-05` correctness fix와 characterization이 먼저다. |
| [2026-08-01 runtime correctness](../../superpowers/plans/2026-08-01-runtime-correctness-remediation.md) Tasks 1–5 | query key/invalidation, application mutation intent, keyed command preflight, effect-aware settlement | 새 plan이 대체하지 않는다. `N-03`, `N-05`, `N-06`을 동일 certainty/key authority에 병합한다. |
| 2026-08-01 runtime correctness(작업 이력 계획) Tasks 1–5 | query key/invalidation, application mutation intent, keyed command preflight, effect-aware settlement | 새 plan이 대체하지 않는다. `N-03`, `N-05`, `N-06`을 동일 certainty/key authority에 병합한다. |
충돌 시 우선순위는 **현재 재현 결함의 fail-close 수정 → 기존 plan의 계약 통합 → 구조 추출 → optional capability 조립**이다. 두 기존 plan을 완료로 표시하거나 삭제하지 않는다.
+1 -1
View File
@@ -7,7 +7,7 @@ import {
} from "./generate-product-feature-index.ts";
/**
* Spec §3 / §37. Build-input regression gate for deployable-app isolation.
* scale-architecture.md §3 / §37. Build-input regression gate for deployable-app isolation.
*
* The app being built is the one recorded in `src/.generated/product-app.ts`.
* Its allowed features are exactly those owned (via their context) by that
+1 -1
View File
@@ -4,7 +4,7 @@ import path from "node:path";
import { parseAsync } from "@babel/core";
/**
* Spec §12 / §41. Source gate against frontend N+1 request fan-out.
* scale-architecture.md §12 / §41. Source gate against frontend N+1 request fan-out.
*
* In feature code and application use cases, a physical-request dispatch must
* not run once per element of a collection. The gate rejects a dispatch call
+1 -1
View File
@@ -825,7 +825,7 @@ export function create${pascal}FeatureInput(
gateway: ${pascal}Gateway,
{ telemetry = NO_OP_TELEMETRY_PORT }: Readonly<{ telemetry?: TelemetryPort }> = {},
): ${pascal}FeatureInput {
// Spec §24, §26: telemetry is best-effort and never changes the result.
// scale-architecture.md §24, §26: telemetry is best-effort and never changes the result.
const events = failOpenTelemetryPort(telemetry);
return Object.freeze({
async listItems(context) {
+1 -1
View File
@@ -2,7 +2,7 @@ import { mkdir, writeFile } from "node:fs/promises";
import { dirname } from "node:path";
/**
* Spec §48. Machine-readable benchmark result.
* scale-architecture.md §48. Machine-readable benchmark result.
*/
export type BenchmarkProfile = "S0" | "S1" | "S2" | "S3" | "S4";
+1 -1
View File
@@ -8,7 +8,7 @@ import {
} from "./benchmark-result.ts";
/**
* Spec §49. Repeated samples with a median, so one noisy scheduler slice can
* scale-architecture.md §49. Repeated samples with a median, so one noisy scheduler slice can
* neither fail a linear implementation nor hide a slow one.
*
* `run` either does the work (and is timed here) or returns a duration it
+1 -1
View File
@@ -11,7 +11,7 @@ import {
} from "./memory-slope.ts";
/**
* Spec §33 / §44. Browser soak on the existing Playwright runner.
* scale-architecture.md §33 / §44. Browser soak on the existing Playwright runner.
*
* Serves the built `dist/` on an OS-assigned 127.0.0.1 port and keeps one
* long-lived page cycling through the app's routes by client-side navigation.
+1 -1
View File
@@ -13,7 +13,7 @@ import {
} from "./scale-baseline.ts";
/**
* Spec §48–§49. Relative regression gate against the stored, approved scale
* scale-architecture.md §48–§49. Relative regression gate against the stored, approved scale
* baseline (`config/scale/benchmark-baseline.json`).
*
* node scripts/scale/check-scale-baseline.ts compare, fail on regression
+1 -1
View File
@@ -8,7 +8,7 @@ import {
} from "../../src/platform/cardinality/growth-regression.ts";
/**
* Spec §38. TypeScript scale gate.
* scale-architecture.md §38. TypeScript scale gate.
*
* Parses `tsc --extendedDiagnostics` and measures bounded local fixtures:
* generated feature modules composed by one context, at increasing local
+1 -1
View File
@@ -7,7 +7,7 @@ import { defineBoundedContextModule } from "../../src/contexts/bounded-context-m
import { defineDeployableAppModule } from "../../src/apps/deployable-app-module.ts";
/**
* Spec §39. Scale-sensitive production composition paths, each parameterized
* scale-architecture.md §39. Scale-sensitive production composition paths, each parameterized
* by one cardinality `n`. Inputs are built outside the timed region.
*/
export type CompositionWorkload = Readonly<{
+1 -1
View File
@@ -1,5 +1,5 @@
/**
* Spec §44. Soak classification.
* scale-architecture.md §44. Soak classification.
*
* The leak signal is sustained positive growth after warm-up, not an
* arbitrary absolute maximum. The classifier fits a least-squares line over
+1 -1
View File
@@ -13,7 +13,7 @@ import {
import { COMPOSITION_WORKLOADS } from "./composition-workloads.ts";
/**
* Spec §36 / §39. Runtime composition scale gate for S0-S2.
* scale-architecture.md §36 / §39. Runtime composition scale gate for S0-S2.
*
* Every production composition workload runs at each requested profile with
* warm-up and repeated samples; the median series must be linear-or-better.
+1 -1
View File
@@ -3,7 +3,7 @@ import { mkdir, writeFile } from "node:fs/promises";
import path from "node:path";
/**
* Spec §47. Execution tiers for the scale/chaos/soak program.
* scale-architecture.md §47. Execution tiers for the scale/chaos/soak program.
*
* pr architecture and traffic invariants, S0-S2 composition growth
* main pr + TypeScript diagnostics and the stored baseline regression
+1 -1
View File
@@ -6,7 +6,7 @@ import type { BenchmarkResult } from "./benchmark-result.ts";
import type { TscDiagnostics } from "./collect-tsc-diagnostics.ts";
/**
* Spec §48–§49. Stored benchmark baseline, compatibility check and relative
* scale-architecture.md §48–§49. Stored benchmark baseline, compatibility check and relative
* regression gate.
*
* The growth gates judge the *shape* of one run. This module compares a run
+1 -1
View File
@@ -115,7 +115,7 @@ const TRANSPORT_OWNED_HEADERS: ReadonlySet<string> = new Set([
"accept",
"content-type",
"idempotency-key",
// Spec §29. Interaction trace propagation is runtime-owned; a credential
// scale-architecture.md §29. Interaction trace propagation is runtime-owned; a credential
// collaborator can never supply or shadow these.
"traceparent",
"x-correlation-id",
+8 -8
View File
@@ -256,7 +256,7 @@ export interface HttpExecutionContext {
readonly scope: CacheScopeSnapshot;
readonly intent?: MutationIntent;
/**
* Spec §10–§15. The interaction this execution belongs to. Every physical
* scale-architecture.md §10–§15. The interaction this execution belongs to. Every physical
* attempt consumes the interaction's shared request budget, retry budget and
* concurrency lease, and the interaction's absolute deadline caps the
* operation deadline. Absent, the executor creates a single-operation
@@ -267,7 +267,7 @@ export interface HttpExecutionContext {
}
/**
* Spec §11. The bounded traffic policy of an operation that declares none:
* scale-architecture.md §11. The bounded traffic policy of an operation that declares none:
* one initial attempt plus the hard retry ceiling, strictly sequential.
*/
export const DEFAULT_OPERATION_TRAFFIC_BUDGET: TrafficBudget = Object.freeze({
@@ -544,7 +544,7 @@ export function createContractHttpExecutor(
clock: now,
startedAt,
});
// Spec §15. A late operation only receives what is left of the
// scale-architecture.md §15. A late operation only receives what is left of the
// interaction's absolute deadline; it never restarts its own full timeout.
const totalDeadlineMs = Math.max(
0,
@@ -604,7 +604,7 @@ export function createContractHttpExecutor(
once: true,
});
}
// Spec §10. Cancelling the interaction cancels every child execution the
// scale-architecture.md §10. Cancelling the interaction cancels every child execution the
// same way the caller's own signal does.
const interactionSignal = context.execution?.cancellation.signal;
if (interactionSignal?.aborted) forwardCallerToLifetime();
@@ -861,7 +861,7 @@ export function createContractHttpExecutor(
if (intentValidation.intent?.idempotencyKey !== undefined) {
headers["Idempotency-Key"] = intentValidation.intent.idempotencyKey;
}
// Spec §29. Only an interaction that opted into tracing propagates its
// scale-architecture.md §29. Only an interaction that opted into tracing propagates its
// identity; every child request carries the same trace and correlation.
if (context.execution?.trace !== undefined) {
Object.assign(headers, buildTraceHeaders(context.execution));
@@ -883,7 +883,7 @@ export function createContractHttpExecutor(
HTTP_EXECUTION_CEILINGS.hardRetryCount,
);
// Spec §13. A retry is admitted only when the interaction still has both a
// scale-architecture.md §13. A retry is admitted only when the interaction still has both a
// shared retry and a physical request left; the retry budget is consumed
// only for a retry that will actually be dispatched.
const admitRetry = (): boolean =>
@@ -909,7 +909,7 @@ export function createContractHttpExecutor(
if (remaining() <= 0) {
return finish(abandonedTransportFailure("TIMEOUT"), "TIMEOUT");
}
// Spec §11 / §14. Physical request budget first, then a cancellable
// scale-architecture.md §11 / §14. Physical request budget first, then a cancellable
// concurrency lease whose wait is bounded by the operation lifetime.
if (!execution.traffic.requests.tryConsume()) {
return finish(
@@ -1392,7 +1392,7 @@ async function admitResponse<Input, WireOutput, Problem>(
"CONTRACT_VIOLATION",
);
}
// Spec §21–§22. Structure before validation/mapping: the byte ceiling
// scale-architecture.md §21–§22. Structure before validation/mapping: the byte ceiling
// already bounded the parse; the structural budget bounds what the schema
// validator and mapper are asked to walk.
if (
+1 -1
View File
@@ -46,7 +46,7 @@ export function jitteredDelay(
}
/**
* Spec §13.3. `Retry-After` is a floor, never an exact instant: every client
* scale-architecture.md §13.3. `Retry-After` is a floor, never an exact instant: every client
* that received the same hint would otherwise retry in one synchronized second
* spike. The cohort is spread over a bounded window that grows with the hint
* (a quarter of it) but never beyond the local 2s jitter ceiling.
+1 -1
View File
@@ -20,7 +20,7 @@ export {
type HttpTransportFailure,
type SafeResponseMetadata,
} from "./http-execution-v3.ts";
/** Spec §17. V3 결과를 플랫폼 오류 봉투(`AppError`)로 정규화한다. */
/** scale-architecture.md §17. V3 결과를 플랫폼 오류 봉투(`AppError`)로 정규화한다. */
export { platformErrorForOutcome } from "./platform-error-mapping.ts";
export {
createFeatureHttpBinding,
+1 -1
View File
@@ -3,7 +3,7 @@ import { PLATFORM_ERRORS } from "../../platform/errors/platform-errors.ts";
import type { HttpExecutionOutcome } from "./http-execution-v3.ts";
/**
* Spec §17. Adapter-boundary normalization of transport-level outcomes into
* scale-architecture.md §17. Adapter-boundary normalization of transport-level outcomes into
* the platform error envelope. Only failures no feature owns are mapped here;
* a `PROBLEM`, an auth verdict or a scope fence is interpreted by its owner
* (the feature binding or the session), so those return `null`.
@@ -31,7 +31,7 @@ export type TelemetryAdapterOptions = Readonly<{
onDrop?: (event: TelemetryEvent) => void;
lifecycle?: Pick<EventTarget, "addEventListener" | "removeEventListener">;
/**
* Spec §27. Sink sends allowed per rolling minute (default 20). Beyond it
* scale-architecture.md §27. Sink sends allowed per rolling minute (default 20). Beyond it
* events wait in the bounded queue until the window reopens; a sustained
* failure storm therefore cannot turn into one collector POST per failure.
*/
+1 -1
View File
@@ -12,7 +12,7 @@ import {
} from "./telemetry-collector.ts";
/**
* Spec §24–§27. Adapter side of the provider-neutral feature telemetry port.
* scale-architecture.md §24–§27. Adapter side of the provider-neutral feature telemetry port.
*
* Features emit through the platform `TelemetryPort`; only this adapter knows
* the collector protocol. A vendor SDK, if a product installs one, belongs in a
+1 -1
View File
@@ -5,7 +5,7 @@ export {
type TelemetryAdapter,
type TelemetryAdapterOptions,
} from "./best-effort-telemetry.ts";
/** Spec §24–§27. 기능 소유 텔레메트리의 수집기 전송(공급자 중립 포트 뒤). */
/** scale-architecture.md §24–§27. 기능 소유 텔레메트리의 수집기 전송(공급자 중립 포트 뒤). */
export {
createFeatureTelemetry,
createFetchTelemetryTransport,
@@ -15,7 +15,7 @@ import { assertBoundedCapacity } from "../platform/bounded-capacity.ts";
* `pagehide` listener that flushes every queue.
*/
export type TelemetryCollector = Readonly<{
/** Spec §27. Shared by every queue posting to this collector. */
/** scale-architecture.md §27. Shared by every queue posting to this collector. */
sendRate: TelemetrySendRate;
/**
* POSTs `{ events }`, split into bodies under the keepalive limit. Rejects
+1 -1
View File
@@ -8,7 +8,7 @@ import { BootConfigError } from "./load-runtime-config.ts";
import { ReleaseManifestError } from "./load-release-manifest.ts";
/**
* Boot-time release-mismatch recovery (spec §45). The reload-once marker is
* Boot-time release-mismatch recovery (scale-architecture.md §45). The reload-once marker is
* the registered session key `RELEASE_MISMATCH_RECOVERY`, reached only through
* the approved browser storage adapter. Without a working session store the
* adapter refuses to persist (`no-persist`), so recovery fails closed.
+1 -1
View File
@@ -47,7 +47,7 @@ async function boot(): Promise<void> {
: unexpectedBootFailure(error);
recordBootFailure(error, safe);
// Spec §45. A rolling-release mismatch gets exactly one fresh navigation
// scale-architecture.md §45. A rolling-release mismatch gets exactly one fresh navigation
// (HTML is revalidated); a repeat of the same mismatch fails closed.
if (decideBootFailure(error, releaseRecovery) === "reload-once") {
window.location.reload();
+1 -1
View File
@@ -246,7 +246,7 @@ export async function loadReleaseManifest(
}
// §6.7 steps 5-6, in order: build, config, release, assets, then contractSet.
// Spec §45. Every identity comparison is delegated to the one pure,
// scale-architecture.md §45. Every identity comparison is delegated to the one pure,
// fail-closed release-coherence validator; only the V1 scalar API contract
// pair (which has no place in the release identity) stays local.
const identities: Readonly<Record<"html" | "config" | "manifest", ReleaseIdentity>> = {
+1 -1
View File
@@ -149,7 +149,7 @@ export async function loadRuntimeConfig(
});
}
// Spec §45. HTML/JS build vs runtime config: delegated to the one pure
// scale-architecture.md §45. HTML/JS build vs runtime config: delegated to the one pure
// release-coherence validator so config and manifest checks cannot drift.
if (
!checkReleaseCoherence(
+1 -1
View File
@@ -650,7 +650,7 @@ export async function createRuntimeAdapters(
return outcome;
},
});
// Spec §24–§27. Feature-owned events go through the bounded, fail-open
// scale-architecture.md §24–§27. Feature-owned events go through the bounded, fail-open
// pipeline behind the provider-neutral port; features never see the sink.
const featureTelemetry = createFeatureTelemetry({
enabled: config.TELEMETRY_ENABLED,
+1 -1
View File
@@ -170,7 +170,7 @@ export interface HttpExecutionPolicy {
readonly authProfileId: string;
readonly diagnosticsOperation: string;
/**
* Spec §11. Optional operation-owned interaction traffic policy. When a
* scale-architecture.md §11. Optional operation-owned interaction traffic policy. When a
* caller supplies no interaction `ExecutionContext`, the executor creates one
* from this policy (or the bounded platform default), so every logical
* execution carries finite request/retry/concurrency budgets.
+1 -1
View File
@@ -76,7 +76,7 @@ export const STORAGE_REGISTRY = Object.freeze({
quotaFallback: "no-persist",
}),
/**
* Spec §45 / release-coherence plan Task 6. One reload-once marker per boot
* scale-architecture.md §45 / release-coherence plan Task 6. One reload-once marker per boot
* release-mismatch key, so a mixed rolling release can recover with one
* fresh HTML fetch but can never reload-loop.
*/
+1 -1
View File
@@ -50,7 +50,7 @@ export function createIndexedDbRepositoryProvider(
export interface FeaturePlatformCapabilities {
readonly http: InstalledHttpOperationExecutor;
readonly indexedDb: IndexedDbRepositoryProvider;
/** Spec §24. Provider-neutral, bounded, fail-open feature telemetry. */
/** scale-architecture.md §24. Provider-neutral, bounded, fail-open feature telemetry. */
readonly telemetry: TelemetryPort;
}
@@ -5,7 +5,7 @@ import {
import type { AppFailure } from "../../../contracts/errors.ts";
/**
* Spec §17–§19. The reference feature's own domain errors.
* scale-architecture.md §17–§19. The reference feature's own domain errors.
*
* This union is local to the feature. It satisfies the platform `AppError`
* envelope structurally; nothing central enumerates it, so adding or removing
@@ -12,7 +12,7 @@ import type { AppFailure } from "../../../contracts/errors.ts";
import { REFERENCE_FEATURE_ID } from "../contracts/reference-feature-contract.ts";
/**
* Spec §10. Every call may join a caller-owned interaction so several
* scale-architecture.md §10. Every call may join a caller-owned interaction so several
* operations share one request/retry/concurrency budget and one deadline.
*/
export type ReferenceCallContext = Readonly<{
@@ -70,7 +70,7 @@ export type ReferenceGateway = Readonly<{
}>;
/**
* Spec §24. Feature-owned telemetry payload. The platform envelope carries it;
* scale-architecture.md §24. Feature-owned telemetry payload. The platform envelope carries it;
* no central union lists it. Only the bounded failure kind leaves the feature.
*/
export type ReferenceLoadFailedPayload = Readonly<{
@@ -100,7 +100,7 @@ function reportLoadFailure(
}),
).catch(() => undefined);
} catch {
// A throwing port is contained at the call site (spec §26).
// A throwing port is contained at the call site (scale-architecture.md §26).
}
}
@@ -1,5 +1,5 @@
/**
* Spec §36 / §39 / §49. Growth-shape regression detector.
* scale-architecture.md §36 / §39 / §49. Growth-shape regression detector.
*
* This is a regression detector, not a Big-O proof. It estimates the local
* growth exponent between consecutive measurements on a log-log scale
+1 -1
View File
@@ -1,5 +1,5 @@
/**
* Spec §17–§18. The platform error envelope.
* scale-architecture.md §17–§18. The platform error envelope.
*
* The platform owns only the generic shape and its closed classification
* axes. Concrete `kind` literals belong to the feature (or platform module)
@@ -6,7 +6,7 @@ import {
} from "./scoped-error-boundary.tsx";
/**
* Spec §30. Contains a bounded context's render failure so the app shell and
* scale-architecture.md §30. Contains a bounded context's render failure so the app shell and
* every other context keep working. It is the escalation target for a feature
* failure that its own feature boundary did not contain.
*/
@@ -6,7 +6,7 @@ import {
} from "./scoped-error-boundary.tsx";
/**
* Spec §30. Contains a feature-local render failure inside the feature's own
* scale-architecture.md §30. Contains a feature-local render failure inside the feature's own
* subtree. The enclosing context boundary is the next escalation.
*/
export function FeatureErrorBoundary(
+1 -1
View File
@@ -1,7 +1,7 @@
import { defineAppError, type AppError } from "./app-error.ts";
/**
* Spec §17. Stable machine-readable platform error kinds for failures that no
* scale-architecture.md §17. Stable machine-readable platform error kinds for failures that no
* feature owns: the network, the deadline, cancellation, response bounds and
* the interaction traffic budget.
*/
@@ -3,7 +3,7 @@ import { Component, type ReactNode } from "react";
import { newIncidentId } from "./incident-id.ts";
/**
* Spec §30. Render-failure containment aligned with ownership boundaries.
* scale-architecture.md §30. Render-failure containment aligned with ownership boundaries.
*
* A boundary exists per owner scope (context, feature), never per leaf
* component. A caught failure replaces only the owning scope with its fallback;
+2 -2
View File
@@ -7,7 +7,7 @@ import {
} from "../traffic/traffic-budget.ts";
/**
* Spec §10. One root execution context per user/application interaction.
* scale-architecture.md §10. One root execution context per user/application interaction.
*
* The interaction identity, absolute deadline and traffic policy are immutable.
* The only mutable state is the interaction-local traffic runtime (counters and
@@ -40,7 +40,7 @@ export interface ExecutionContext {
}>;
readonly traffic: TrafficRuntime;
/**
* Spec §29. The interaction trace identity. Present only when the
* scale-architecture.md §29. The interaction trace identity. Present only when the
* interaction opted into propagation; every child request then carries the
* same `traceparent` and correlation id.
*/
+1 -1
View File
@@ -1,5 +1,5 @@
/**
* Spec §45–§46. One pure, fail-closed release-coherence validator.
* scale-architecture.md §45–§46. One pure, fail-closed release-coherence validator.
*
* Horizontally scaled stateless replicas are safe without sticky sessions only
* when every boot observes one coherent release tuple: the HTML/JS build, the
@@ -1,5 +1,5 @@
/**
* Spec §45 / §46. Bounded recovery from a boot-time release mismatch.
* scale-architecture.md §45 / §46. Bounded recovery from a boot-time release mismatch.
*
* During a rolling release a browser can hold HTML from one release while a
* replica answers config/manifest from another. One fresh navigation usually
+1 -1
View File
@@ -1,5 +1,5 @@
/**
* Spec §15. One absolute deadline per interaction.
* scale-architecture.md §15. One absolute deadline per interaction.
*
* A retry started late only receives what is left of the original deadline; it
* never restarts an independent timeout. The helper never reads a clock itself:
+1 -1
View File
@@ -1,7 +1,7 @@
import { assertFiniteBudget } from "../traffic/request-budget.ts";
/**
* Spec §13. Retry capacity is interaction-scoped, not request-scoped.
* scale-architecture.md §13. Retry capacity is interaction-scoped, not request-scoped.
*
* Two independent requests that fail inside the same interaction compete for
* the same retries; the budget is never reset per request, so N parallel
+1 -1
View File
@@ -1,5 +1,5 @@
/**
* Spec §28. Redaction before buffering.
* scale-architecture.md §28. Redaction before buffering.
*
* The sanitizer copies only plain own data into fresh objects/arrays: it never
* preserves prototypes and never invokes getters or `toJSON` on untrusted
+1 -1
View File
@@ -4,7 +4,7 @@ import {
} from "./telemetry-event.ts";
/**
* Spec §25 / §27. Bounded, severity-aware telemetry buffer.
* scale-architecture.md §25 / §27. Bounded, severity-aware telemetry buffer.
*
* The buffer never exceeds `maxEvents` or `maxBytes`. When full, buffered
* events no more severe than the incoming one are evicted, lowest severity
@@ -1,5 +1,5 @@
/**
* Spec §27. Bounded fingerprint deduplication.
* scale-architecture.md §27. Bounded fingerprint deduplication.
*
* Each fingerprint is admitted once per window; later occurrences inside the
* window only increment a counter. The table never holds more than
+1 -1
View File
@@ -1,7 +1,7 @@
import type { ErrorSeverity } from "../errors/app-error.ts";
/**
* Spec §23–§24. The provider-neutral telemetry envelope.
* scale-architecture.md §23–§24. The provider-neutral telemetry envelope.
*
* The platform owns the envelope and its bounded dimensions. The concrete
* `kind` and `payload` belong to the emitting feature; there is no global
@@ -1,7 +1,7 @@
import type { TelemetryEvent } from "./telemetry-event.ts";
/**
* Spec §27. Deterministic fingerprint over the bounded dimensions of an event.
* scale-architecture.md §27. Deterministic fingerprint over the bounded dimensions of an event.
*
* Request-cardinality fields (`interactionId`, `traceId`) are excluded on
* purpose: the same failure hitting ten thousand interactions must collapse to
+2 -2
View File
@@ -18,7 +18,7 @@ import {
import { createDeterministicSampler } from "./telemetry-sampler.ts";
/**
* Spec §25–§28. The bounded, fail-open telemetry pipeline:
* scale-architecture.md §25–§28. The bounded, fail-open telemetry pipeline:
*
* redact -> fingerprint -> deduplicate -> sample -> buffer
* -> rate limit -> batch -> transport
@@ -94,7 +94,7 @@ function assertPositive(name: string, value: number): void {
}
/**
* Spec §27. A rolling one-minute send budget. Several queues that post to the
* scale-architecture.md §27. A rolling one-minute send budget. Several queues that post to the
* same collector share one instance, so the limit belongs to the collector
* rather than to each queue (Q-6.9-4).
*/
+2 -2
View File
@@ -1,7 +1,7 @@
import type { TelemetryEvent } from "./telemetry-event.ts";
/**
* Spec §24. The only observability surface feature code may use.
* scale-architecture.md §24. The only observability surface feature code may use.
*
* `emit` is best-effort: an implementation must never throw or reject into
* business behavior. Vendor SDKs live behind an adapter-side transport, never
@@ -17,7 +17,7 @@ export const NO_OP_TELEMETRY_PORT: TelemetryPort = Object.freeze({
/**
* Wraps any port so that a synchronous throw or an asynchronous rejection is
* contained at the call site (spec §26).
* contained at the call site (scale-architecture.md §26).
*/
export function failOpenTelemetryPort(port: TelemetryPort): TelemetryPort {
return Object.freeze({
+1 -1
View File
@@ -1,7 +1,7 @@
import { stableHash64 } from "./telemetry-fingerprint.ts";
/**
* Spec §25. Deterministic sampling by a stable key (interaction or trace id).
* scale-architecture.md §25. Deterministic sampling by a stable key (interaction or trace id).
*
* The same key always yields the same decision, so one interaction's events
* are kept or dropped together instead of producing partial traces.
+1 -1
View File
@@ -1,5 +1,5 @@
/**
* Spec §29. One interaction trace identity propagated to every child request.
* scale-architecture.md §29. One interaction trace identity propagated to every child request.
*
* The header names follow the conventions already in the repository: the W3C
* `traceparent` (validated by `safeTraceparent` in the telemetry adapter) and
+1 -1
View File
@@ -1,7 +1,7 @@
import { assertFiniteBudget } from "./request-budget.ts";
/**
* Spec §14. Cancellable concurrency leases with a bounded FIFO waiting queue.
* scale-architecture.md §14. Cancellable concurrency leases with a bounded FIFO waiting queue.
*
* - No more than `maximum` leases are ever active at once.
* - No more than `maxQueued` callers ever wait; the next caller is rejected
+1 -1
View File
@@ -1,5 +1,5 @@
/**
* Spec §11. The number of physical requests one interaction may dispatch.
* scale-architecture.md §11. The number of physical requests one interaction may dispatch.
*
* Consumption is monotonic: a budget never refills inside the interaction that
* owns it, so a retry storm cannot turn one user action into an unbounded
+1 -1
View File
@@ -1,5 +1,5 @@
/**
* Spec §12 / §41. Collection cardinality must not become physical request
* scale-architecture.md §12 / §41. Collection cardinality must not become physical request
* cardinality. Loading N rows costs a bounded number of requests (one page or
* one bulk/read-model call), never one request per row.
*/
+1 -1
View File
@@ -13,7 +13,7 @@ import {
} from "./request-budget.ts";
/**
* Spec §11. Immutable traffic policy. Every field is a finite safe integer;
* scale-architecture.md §11. Immutable traffic policy. Every field is a finite safe integer;
* there is no "unlimited" sentinel.
*/
export interface TrafficBudget {
+1 -1
View File
@@ -1,7 +1,7 @@
import type { ValidationBudget } from "./validation-budget.ts";
/**
* Spec §20–§22. Size before parse, structure before mapping.
* scale-architecture.md §20–§22. Size before parse, structure before mapping.
*
* `parseBoundedJson` rejects oversized text before `JSON.parse` runs, then
* walks the parsed value with an explicit stack (never recursion) so an
+1 -1
View File
@@ -1,5 +1,5 @@
/**
* Spec §22. Structural limits for data that crosses a trust boundary.
* scale-architecture.md §22. Structural limits for data that crosses a trust boundary.
*
* Every value is a finite positive safe integer: there is no "unbounded"
* validation configuration. These limits protect local CPU/memory cost; they
@@ -4,7 +4,7 @@ import path from "node:path";
import { describe, expect, it } from "vitest";
/**
* Spec §17 / §24 / §50. Observability boundary gates:
* scale-architecture.md §17 / §24 / §50. Observability boundary gates:
* - feature (and every non-adapter) code never imports a vendor telemetry SDK,
* - no global union of every feature error or telemetry payload exists,
* - the dependency rule that enforces the first point stays configured.
@@ -12,7 +12,7 @@ import {
import { referenceFeatureOver } from "./reference-traffic-kit.ts";
/**
* Spec §16. Multiple consumers of one query identity must not imply multiple
* scale-architecture.md §16. Multiple consumers of one query identity must not imply multiple
* physical requests. TanStack Query owns in-flight coalescing; this suite pins
* that the installed query client plus the real V3 executor keep it that way.
*/
@@ -21,7 +21,7 @@ const TEST_QUERY = TEST_LIST_HTTP_CONTRACT as InstalledHttpContract<
>;
/**
* Spec §16. Multiple consumers of one query identity must not imply multiple
* scale-architecture.md §16. Multiple consumers of one query identity must not imply multiple
* physical requests. TanStack Query owns in-flight coalescing; this suite pins
* that the installed query client plus the real V3 executor keep it that way.
*/
@@ -25,7 +25,7 @@ const TEST_QUERY = TEST_LIST_HTTP_CONTRACT as InstalledHttpContract<
const COLLECTION_LOAD_FANOUT_BUDGET = 1;
/**
* Spec §12 / §41. Feature-neutral fan-out gate over the installed-contract
* scale-architecture.md §12 / §41. Feature-neutral fan-out gate over the installed-contract
* path; the reference feature's own collection proof lives with the feature.
*/
async function loadCollection(transport: Transport) {
@@ -17,7 +17,7 @@ const TEST_QUERY = TEST_LIST_HTTP_CONTRACT as InstalledHttpContract<
>;
/**
* Spec §32 / §34. Backend failure coinciding with a user spike must not let
* scale-architecture.md §32 / §34. Backend failure coinciding with a user spike must not let
* the client multiply the incident: physical requests per interaction stay at
* or below the interaction budget no matter how many operations it starts.
*/
+1 -1
View File
@@ -10,7 +10,7 @@ import {
} from "./release-fixture.ts";
/**
* Spec §46. The multi-replica release matrix. Each row boots the real config
* scale-architecture.md §46. The multi-replica release matrix. Each row boots the real config
* and manifest loaders against a two-release deployment and then loads the
* HTML's hashed entry asset.
*/
@@ -24,7 +24,7 @@ import {
} from "./synthetic-topology.ts";
/**
* Spec §37. The central 1M architectural proof, on the production path.
* scale-architecture.md §37. The central 1M architectural proof, on the production path.
*
* - S0-S2: real on-disk repositories, generated by the production command
* (`scripts/generate-product-feature-index.ts --app=`), whose discovery reads
+1 -1
View File
@@ -1,5 +1,5 @@
/**
* Spec §35. Synthetic scale profiles. S3/S4 are logical cardinalities: they
* scale-architecture.md §35. Synthetic scale profiles. S3/S4 are logical cardinalities: they
* are modelled as topology, never compiled as one SPA.
*/
export const SCALE_PROFILES = Object.freeze({
+1 -1
View File
@@ -66,7 +66,7 @@ function countingScope() {
}
/**
* Spec §33 / §44. Thousands of login/navigation/query/mutation/logout cycles.
* scale-architecture.md §33 / §44. Thousands of login/navigation/query/mutation/logout cycles.
* Every long-lived resource must return to (or stabilize at) its post-warm-up
* bound rather than grow with the number of cycles.
*/
+1 -1
View File
@@ -18,7 +18,7 @@ const TEST_COMMAND = TEST_CREATE_HTTP_CONTRACT as InstalledHttpContract<
>;
/**
* Spec §42 (network flap). The network alternates online/offline. An
* scale-architecture.md §42 (network flap). The network alternates online/offline. An
* offline attempt that reached `fetch` is a dispatched attempt whose effect is
* unknown; the executor must never replay a keyed command automatically.
*/
+1 -1
View File
@@ -14,7 +14,7 @@ import {
} from "./scale-profile.ts";
/**
* Spec §37. A compact model of a global product topology.
* scale-architecture.md §37. A compact model of a global product topology.
*
* Only counts are stored. An app's contexts and feature ids are derived on
* demand from its index, so a 1,000,000-feature topology costs a handful of
@@ -16,7 +16,7 @@ const IDENTICAL: TelemetryEvent<unknown> = {
};
/**
* Spec §43. Many logical failures -> fingerprint/dedup/sample -> a bounded
* scale-architecture.md §43. Many logical failures -> fingerprint/dedup/sample -> a bounded
* number of buffered and sent telemetry events.
*/
async function runTelemetryStorm(
+1 -1
View File
@@ -1,5 +1,5 @@
/**
* Spec §34. Operational amplification metrics.
* scale-architecture.md §34. Operational amplification metrics.
*
* - request amplification = physical requests / logical interactions
* - retry amplification = total physical attempts / initial requests
+1 -1
View File
@@ -39,7 +39,7 @@ export type SyntheticTrafficResult = Readonly<{
}>;
/**
* Spec §32 / §42. Drives many independent interactions through the real V3
* scale-architecture.md §32 / §42. Drives many independent interactions through the real V3
* executor, each with its own interaction budget, and counts physical
* dispatches at the transport.
*/
+31 -13
View File
@@ -17,6 +17,7 @@ const ROOT_FILES = [
"vitest.config.ts",
"eslint.config.ts",
"playwright.config.ts",
".dependency-cruiser.json",
];
// Built from pieces so that this file does not match itself.
@@ -29,6 +30,13 @@ const DELETABLE = [
new RegExp(`\\b${"CLAUDE"}\\.md\\b`, "u"),
new RegExp(`(^|["'\`(\\s])${"tasks"}/`, "u"),
];
/**
* 1101/14-01. A section number without a document name cannot be followed,
* and the scale design it meant used to live only in the history bundle a
* copy deletes. Cite it as `scale-architecture.md §N`
* (docs/architecture/scale-architecture.md, a current contract).
*/
const UNNAMED_SECTION = new RegExp(`\\b${"spec"} ?§`, "iu");
async function codeFiles(directory: string): Promise<string[]> {
const entries = await readdir(directory, { withFileTypes: true }).catch(
@@ -45,21 +53,31 @@ async function codeFiles(directory: string): Promise<string[]> {
return files.flat();
}
async function linesMatching(patterns: readonly RegExp[]): Promise<string[]> {
const files = [
...(await Promise.all(CODE_ROOTS.map(codeFiles))).flat(),
...ROOT_FILES,
];
const matches: string[] = [];
for (const file of files) {
const lines = (await readFile(file, "utf8").catch(() => "")).split("\n");
lines.forEach((line, index) => {
if (patterns.some((pattern) => pattern.test(line)))
matches.push(`${file}:${index + 1}`);
});
}
return matches;
}
describe("deletable history documents", () => {
it("are read by no code, test, script or configuration", async () => {
const files = [
...(await Promise.all(CODE_ROOTS.map(codeFiles))).flat(),
...ROOT_FILES,
];
const readers: string[] = [];
for (const file of files) {
const lines = (await readFile(file, "utf8").catch(() => "")).split("\n");
lines.forEach((line, index) => {
if (DELETABLE.some((pattern) => pattern.test(line)))
readers.push(`${file}:${index + 1}`);
});
}
expect(await linesMatching(DELETABLE), `only ${KEPT} may be read`).toEqual([]);
});
expect(readers, `only ${KEPT} may be read`).toEqual([]);
it("are not cited as an unnamed design section", async () => {
expect(
await linesMatching([UNNAMED_SECTION]),
"name the document: scale-architecture.md §N",
).toEqual([]);
});
});
+1 -1
View File
@@ -728,7 +728,7 @@ describe("collector keepalive budget (03-05)", () => {
});
});
describe("telemetry adapter send-rate limit (spec §27)", () => {
describe("telemetry adapter send-rate limit (scale-architecture.md §27)", () => {
function harness(maxSendsPerMinute = 3) {
let now = 0;
const timers: Array<() => void> = [];