diff --git a/.dependency-cruiser.json b/.dependency-cruiser.json index 99561bb1..133c1641 100644 --- a/.dependency-cruiser.json +++ b/.dependency-cruiser.json @@ -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/", diff --git a/README.md b/README.md index 787e9ca2..26eb8b0c 100644 --- a/README.md +++ b/README.md @@ -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 | diff --git a/docs/README.md b/docs/README.md index 2d152a47..01fa1e5e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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/` 밖에 그대로 둔다 | diff --git a/docs/operations/adapter-remediation-ledger.md b/docs/operations/adapter-remediation-ledger.md index 36691b56..5a958f5f 100644 --- a/docs/operations/adapter-remediation-ledger.md +++ b/docs/operations/adapter-remediation-ledger.md @@ -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 diff --git a/docs/reviews/adapters/05-service-worker-and-web-push.md b/docs/reviews/adapters/05-service-worker-and-web-push.md index 66fff55b..c3b31e4f 100644 --- a/docs/reviews/adapters/05-service-worker-and-web-push.md +++ b/docs/reviews/adapters/05-service-worker-and-web-push.md @@ -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을 직접 만든다. 결정: diff --git a/docs/reviews/adapters/README.md b/docs/reviews/adapters/README.md index 1c70e9b4..05d85706 100644 --- a/docs/reviews/adapters/README.md +++ b/docs/reviews/adapters/README.md @@ -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을 완료로 표시하거나 삭제하지 않는다. diff --git a/scripts/check-app-build-input.ts b/scripts/check-app-build-input.ts index c8c60024..9dc7d023 100644 --- a/scripts/check-app-build-input.ts +++ b/scripts/check-app-build-input.ts @@ -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 diff --git a/scripts/check-request-fanout.ts b/scripts/check-request-fanout.ts index a4a7838e..3fcbe287 100644 --- a/scripts/check-request-fanout.ts +++ b/scripts/check-request-fanout.ts @@ -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 diff --git a/scripts/create-feature.ts b/scripts/create-feature.ts index f31a91b4..dd91369d 100644 --- a/scripts/create-feature.ts +++ b/scripts/create-feature.ts @@ -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) { diff --git a/scripts/scale/benchmark-result.ts b/scripts/scale/benchmark-result.ts index 53c7f040..6ad1274e 100644 --- a/scripts/scale/benchmark-result.ts +++ b/scripts/scale/benchmark-result.ts @@ -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"; diff --git a/scripts/scale/benchmark.ts b/scripts/scale/benchmark.ts index cb5ba4a5..87025b16 100644 --- a/scripts/scale/benchmark.ts +++ b/scripts/scale/benchmark.ts @@ -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 diff --git a/scripts/scale/browser-soak.ts b/scripts/scale/browser-soak.ts index 4fe91514..66ef7200 100644 --- a/scripts/scale/browser-soak.ts +++ b/scripts/scale/browser-soak.ts @@ -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. diff --git a/scripts/scale/check-scale-baseline.ts b/scripts/scale/check-scale-baseline.ts index 62e07af0..82e577c6 100644 --- a/scripts/scale/check-scale-baseline.ts +++ b/scripts/scale/check-scale-baseline.ts @@ -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 diff --git a/scripts/scale/collect-tsc-diagnostics.ts b/scripts/scale/collect-tsc-diagnostics.ts index d5827091..e3070b6e 100644 --- a/scripts/scale/collect-tsc-diagnostics.ts +++ b/scripts/scale/collect-tsc-diagnostics.ts @@ -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 diff --git a/scripts/scale/composition-workloads.ts b/scripts/scale/composition-workloads.ts index 1f2cb9b3..adeb8646 100644 --- a/scripts/scale/composition-workloads.ts +++ b/scripts/scale/composition-workloads.ts @@ -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<{ diff --git a/scripts/scale/memory-slope.ts b/scripts/scale/memory-slope.ts index 71230b67..48423309 100644 --- a/scripts/scale/memory-slope.ts +++ b/scripts/scale/memory-slope.ts @@ -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 diff --git a/scripts/scale/run-composition-scale.ts b/scripts/scale/run-composition-scale.ts index 2ce5028b..c9b03528 100644 --- a/scripts/scale/run-composition-scale.ts +++ b/scripts/scale/run-composition-scale.ts @@ -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. diff --git a/scripts/scale/run-scale-profile.ts b/scripts/scale/run-scale-profile.ts index ac360ff1..151f6d57 100644 --- a/scripts/scale/run-scale-profile.ts +++ b/scripts/scale/run-scale-profile.ts @@ -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 diff --git a/scripts/scale/scale-baseline.ts b/scripts/scale/scale-baseline.ts index 39115cef..be86f481 100644 --- a/scripts/scale/scale-baseline.ts +++ b/scripts/scale/scale-baseline.ts @@ -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 diff --git a/src/adapters/http/http-contract-bridge.ts b/src/adapters/http/http-contract-bridge.ts index 1232cf86..5c3d1d81 100644 --- a/src/adapters/http/http-contract-bridge.ts +++ b/src/adapters/http/http-contract-bridge.ts @@ -115,7 +115,7 @@ const TRANSPORT_OWNED_HEADERS: ReadonlySet = 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", diff --git a/src/adapters/http/http-execution-v3.ts b/src/adapters/http/http-execution-v3.ts index 6d4c8b40..8ef1eb42 100644 --- a/src/adapters/http/http-execution-v3.ts +++ b/src/adapters/http/http-execution-v3.ts @@ -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( "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 ( diff --git a/src/adapters/http/http-retry-lifecycle.ts b/src/adapters/http/http-retry-lifecycle.ts index 3354d21b..ae9e30da 100644 --- a/src/adapters/http/http-retry-lifecycle.ts +++ b/src/adapters/http/http-retry-lifecycle.ts @@ -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. diff --git a/src/adapters/http/index.ts b/src/adapters/http/index.ts index 72723330..bee67abd 100644 --- a/src/adapters/http/index.ts +++ b/src/adapters/http/index.ts @@ -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, diff --git a/src/adapters/http/platform-error-mapping.ts b/src/adapters/http/platform-error-mapping.ts index 751a4a6c..7b852f2c 100644 --- a/src/adapters/http/platform-error-mapping.ts +++ b/src/adapters/http/platform-error-mapping.ts @@ -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`. diff --git a/src/adapters/telemetry/best-effort-telemetry.ts b/src/adapters/telemetry/best-effort-telemetry.ts index 0e6d66de..d42c9c59 100644 --- a/src/adapters/telemetry/best-effort-telemetry.ts +++ b/src/adapters/telemetry/best-effort-telemetry.ts @@ -31,7 +31,7 @@ export type TelemetryAdapterOptions = Readonly<{ onDrop?: (event: TelemetryEvent) => void; lifecycle?: Pick; /** - * 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. */ diff --git a/src/adapters/telemetry/feature-telemetry.ts b/src/adapters/telemetry/feature-telemetry.ts index f4a7a603..3c013201 100644 --- a/src/adapters/telemetry/feature-telemetry.ts +++ b/src/adapters/telemetry/feature-telemetry.ts @@ -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 diff --git a/src/adapters/telemetry/index.ts b/src/adapters/telemetry/index.ts index 1d762dd5..48c0baa0 100644 --- a/src/adapters/telemetry/index.ts +++ b/src/adapters/telemetry/index.ts @@ -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, diff --git a/src/adapters/telemetry/telemetry-collector.ts b/src/adapters/telemetry/telemetry-collector.ts index d3bb2300..5aa24f70 100644 --- a/src/adapters/telemetry/telemetry-collector.ts +++ b/src/adapters/telemetry/telemetry-collector.ts @@ -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 diff --git a/src/bootstrap/boot-release-recovery.ts b/src/bootstrap/boot-release-recovery.ts index 5c1ce924..60ac954a 100644 --- a/src/bootstrap/boot-release-recovery.ts +++ b/src/bootstrap/boot-release-recovery.ts @@ -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. diff --git a/src/bootstrap/boot.tsx b/src/bootstrap/boot.tsx index 5d4526ee..e49dda96 100644 --- a/src/bootstrap/boot.tsx +++ b/src/bootstrap/boot.tsx @@ -47,7 +47,7 @@ async function boot(): Promise { : 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(); diff --git a/src/bootstrap/load-release-manifest.ts b/src/bootstrap/load-release-manifest.ts index fa8c7520..5050f48e 100644 --- a/src/bootstrap/load-release-manifest.ts +++ b/src/bootstrap/load-release-manifest.ts @@ -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> = { diff --git a/src/bootstrap/load-runtime-config.ts b/src/bootstrap/load-runtime-config.ts index ac12061e..566002fa 100644 --- a/src/bootstrap/load-runtime-config.ts +++ b/src/bootstrap/load-runtime-config.ts @@ -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( diff --git a/src/bootstrap/runtime-adapters.ts b/src/bootstrap/runtime-adapters.ts index 47ddb848..3563b814 100644 --- a/src/bootstrap/runtime-adapters.ts +++ b/src/bootstrap/runtime-adapters.ts @@ -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, diff --git a/src/contracts/external-contract-runtime.ts b/src/contracts/external-contract-runtime.ts index 86a942f0..4ecc81d8 100644 --- a/src/contracts/external-contract-runtime.ts +++ b/src/contracts/external-contract-runtime.ts @@ -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. diff --git a/src/contracts/storage-keys.ts b/src/contracts/storage-keys.ts index dd374e49..38f99821 100644 --- a/src/contracts/storage-keys.ts +++ b/src/contracts/storage-keys.ts @@ -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. */ diff --git a/src/features/feature-adapter-contribution.ts b/src/features/feature-adapter-contribution.ts index fcda2418..77a9874d 100644 --- a/src/features/feature-adapter-contribution.ts +++ b/src/features/feature-adapter-contribution.ts @@ -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; } diff --git a/src/features/reference-feature/application/reference-error.ts b/src/features/reference-feature/application/reference-error.ts index f55fde53..0ac57401 100644 --- a/src/features/reference-feature/application/reference-error.ts +++ b/src/features/reference-feature/application/reference-error.ts @@ -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 diff --git a/src/features/reference-feature/application/reference-feature-api.ts b/src/features/reference-feature/application/reference-feature-api.ts index 22bb7057..c896b71e 100644 --- a/src/features/reference-feature/application/reference-feature-api.ts +++ b/src/features/reference-feature/application/reference-feature-api.ts @@ -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). } } diff --git a/src/platform/cardinality/growth-regression.ts b/src/platform/cardinality/growth-regression.ts index e743b699..e78a081c 100644 --- a/src/platform/cardinality/growth-regression.ts +++ b/src/platform/cardinality/growth-regression.ts @@ -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 diff --git a/src/platform/errors/app-error.ts b/src/platform/errors/app-error.ts index c344cecd..b641369c 100644 --- a/src/platform/errors/app-error.ts +++ b/src/platform/errors/app-error.ts @@ -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) diff --git a/src/platform/errors/context-error-boundary.tsx b/src/platform/errors/context-error-boundary.tsx index 402d6ad2..81bb8a75 100644 --- a/src/platform/errors/context-error-boundary.tsx +++ b/src/platform/errors/context-error-boundary.tsx @@ -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. */ diff --git a/src/platform/errors/feature-error-boundary.tsx b/src/platform/errors/feature-error-boundary.tsx index 473537e7..3a2ededf 100644 --- a/src/platform/errors/feature-error-boundary.tsx +++ b/src/platform/errors/feature-error-boundary.tsx @@ -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( diff --git a/src/platform/errors/platform-errors.ts b/src/platform/errors/platform-errors.ts index 40a80b04..970320f0 100644 --- a/src/platform/errors/platform-errors.ts +++ b/src/platform/errors/platform-errors.ts @@ -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. */ diff --git a/src/platform/errors/scoped-error-boundary.tsx b/src/platform/errors/scoped-error-boundary.tsx index 2ae3753c..b4d3d8a9 100644 --- a/src/platform/errors/scoped-error-boundary.tsx +++ b/src/platform/errors/scoped-error-boundary.tsx @@ -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; diff --git a/src/platform/execution/execution-context.ts b/src/platform/execution/execution-context.ts index e60de32e..452d93f8 100644 --- a/src/platform/execution/execution-context.ts +++ b/src/platform/execution/execution-context.ts @@ -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. */ diff --git a/src/platform/release/release-coherence.ts b/src/platform/release/release-coherence.ts index b24060db..a9d3cd17 100644 --- a/src/platform/release/release-coherence.ts +++ b/src/platform/release/release-coherence.ts @@ -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 diff --git a/src/platform/release/release-mismatch-recovery.ts b/src/platform/release/release-mismatch-recovery.ts index 1b5efcf5..11fe4124 100644 --- a/src/platform/release/release-mismatch-recovery.ts +++ b/src/platform/release/release-mismatch-recovery.ts @@ -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 diff --git a/src/platform/resilience/deadline.ts b/src/platform/resilience/deadline.ts index 9d7305e8..968bccd5 100644 --- a/src/platform/resilience/deadline.ts +++ b/src/platform/resilience/deadline.ts @@ -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: diff --git a/src/platform/resilience/retry-budget.ts b/src/platform/resilience/retry-budget.ts index bfd90895..52e7edc6 100644 --- a/src/platform/resilience/retry-budget.ts +++ b/src/platform/resilience/retry-budget.ts @@ -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 diff --git a/src/platform/telemetry/redact-telemetry.ts b/src/platform/telemetry/redact-telemetry.ts index 5c850d7b..9cc55159 100644 --- a/src/platform/telemetry/redact-telemetry.ts +++ b/src/platform/telemetry/redact-telemetry.ts @@ -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 diff --git a/src/platform/telemetry/telemetry-buffer.ts b/src/platform/telemetry/telemetry-buffer.ts index 44ba9015..23d75781 100644 --- a/src/platform/telemetry/telemetry-buffer.ts +++ b/src/platform/telemetry/telemetry-buffer.ts @@ -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 diff --git a/src/platform/telemetry/telemetry-deduplicator.ts b/src/platform/telemetry/telemetry-deduplicator.ts index f7bb87d2..855f851d 100644 --- a/src/platform/telemetry/telemetry-deduplicator.ts +++ b/src/platform/telemetry/telemetry-deduplicator.ts @@ -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 diff --git a/src/platform/telemetry/telemetry-event.ts b/src/platform/telemetry/telemetry-event.ts index 9ee6fd1a..4bca2649 100644 --- a/src/platform/telemetry/telemetry-event.ts +++ b/src/platform/telemetry/telemetry-event.ts @@ -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 diff --git a/src/platform/telemetry/telemetry-fingerprint.ts b/src/platform/telemetry/telemetry-fingerprint.ts index f70e69bc..eb27e930 100644 --- a/src/platform/telemetry/telemetry-fingerprint.ts +++ b/src/platform/telemetry/telemetry-fingerprint.ts @@ -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 diff --git a/src/platform/telemetry/telemetry-pipeline.ts b/src/platform/telemetry/telemetry-pipeline.ts index 94ba7799..37d11dff 100644 --- a/src/platform/telemetry/telemetry-pipeline.ts +++ b/src/platform/telemetry/telemetry-pipeline.ts @@ -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). */ diff --git a/src/platform/telemetry/telemetry-port.ts b/src/platform/telemetry/telemetry-port.ts index d2f1d655..a564270a 100644 --- a/src/platform/telemetry/telemetry-port.ts +++ b/src/platform/telemetry/telemetry-port.ts @@ -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({ diff --git a/src/platform/telemetry/telemetry-sampler.ts b/src/platform/telemetry/telemetry-sampler.ts index 07900a8d..55a7b448 100644 --- a/src/platform/telemetry/telemetry-sampler.ts +++ b/src/platform/telemetry/telemetry-sampler.ts @@ -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. diff --git a/src/platform/telemetry/trace-context.ts b/src/platform/telemetry/trace-context.ts index a22baff1..3348e558 100644 --- a/src/platform/telemetry/trace-context.ts +++ b/src/platform/telemetry/trace-context.ts @@ -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 diff --git a/src/platform/traffic/concurrency-budget.ts b/src/platform/traffic/concurrency-budget.ts index 0925df4a..385598df 100644 --- a/src/platform/traffic/concurrency-budget.ts +++ b/src/platform/traffic/concurrency-budget.ts @@ -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 diff --git a/src/platform/traffic/request-budget.ts b/src/platform/traffic/request-budget.ts index 6205d7c8..1ca4a23a 100644 --- a/src/platform/traffic/request-budget.ts +++ b/src/platform/traffic/request-budget.ts @@ -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 diff --git a/src/platform/traffic/request-fanout.ts b/src/platform/traffic/request-fanout.ts index 4c2cb6c7..e343cb46 100644 --- a/src/platform/traffic/request-fanout.ts +++ b/src/platform/traffic/request-fanout.ts @@ -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. */ diff --git a/src/platform/traffic/traffic-budget.ts b/src/platform/traffic/traffic-budget.ts index bbe9975e..1c757384 100644 --- a/src/platform/traffic/traffic-budget.ts +++ b/src/platform/traffic/traffic-budget.ts @@ -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 { diff --git a/src/platform/validation/bounded-json.ts b/src/platform/validation/bounded-json.ts index 91d9d5cb..69aef489 100644 --- a/src/platform/validation/bounded-json.ts +++ b/src/platform/validation/bounded-json.ts @@ -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 diff --git a/src/platform/validation/validation-budget.ts b/src/platform/validation/validation-budget.ts index c918f9f4..5d6b20df 100644 --- a/src/platform/validation/validation-budget.ts +++ b/src/platform/validation/validation-budget.ts @@ -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 diff --git a/tests/architecture/observability-boundaries.test.ts b/tests/architecture/observability-boundaries.test.ts index d1e7cc98..61e4a724 100644 --- a/tests/architecture/observability-boundaries.test.ts +++ b/tests/architecture/observability-boundaries.test.ts @@ -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. diff --git a/tests/features/reference-feature/reference-request-deduplication.test.ts b/tests/features/reference-feature/reference-request-deduplication.test.ts index 409ea898..8dda7deb 100644 --- a/tests/features/reference-feature/reference-request-deduplication.test.ts +++ b/tests/features/reference-feature/reference-request-deduplication.test.ts @@ -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. */ diff --git a/tests/platform/traffic/request-deduplication.test.ts b/tests/platform/traffic/request-deduplication.test.ts index 98335ea8..866b7595 100644 --- a/tests/platform/traffic/request-deduplication.test.ts +++ b/tests/platform/traffic/request-deduplication.test.ts @@ -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. */ diff --git a/tests/platform/traffic/request-fanout.test.ts b/tests/platform/traffic/request-fanout.test.ts index 1a3ddb79..1d8eccce 100644 --- a/tests/platform/traffic/request-fanout.test.ts +++ b/tests/platform/traffic/request-fanout.test.ts @@ -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) { diff --git a/tests/platform/traffic/traffic-amplification.test.ts b/tests/platform/traffic/traffic-amplification.test.ts index 68e91ef1..5efff9b6 100644 --- a/tests/platform/traffic/traffic-amplification.test.ts +++ b/tests/platform/traffic/traffic-amplification.test.ts @@ -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. */ diff --git a/tests/release/release-matrix.test.ts b/tests/release/release-matrix.test.ts index ab017482..0896805a 100644 --- a/tests/release/release-matrix.test.ts +++ b/tests/release/release-matrix.test.ts @@ -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. */ diff --git a/tests/scale/global-local-independence.test.ts b/tests/scale/global-local-independence.test.ts index 0daca96c..c80834ac 100644 --- a/tests/scale/global-local-independence.test.ts +++ b/tests/scale/global-local-independence.test.ts @@ -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 diff --git a/tests/scale/scale-profile.ts b/tests/scale/scale-profile.ts index 4b2e7bae..196713eb 100644 --- a/tests/scale/scale-profile.ts +++ b/tests/scale/scale-profile.ts @@ -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({ diff --git a/tests/scale/session/long-session.test.ts b/tests/scale/session/long-session.test.ts index 516c88cf..dfebffc3 100644 --- a/tests/scale/session/long-session.test.ts +++ b/tests/scale/session/long-session.test.ts @@ -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. */ diff --git a/tests/scale/session/network-flap.test.ts b/tests/scale/session/network-flap.test.ts index ff0710e9..58a78a18 100644 --- a/tests/scale/session/network-flap.test.ts +++ b/tests/scale/session/network-flap.test.ts @@ -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. */ diff --git a/tests/scale/synthetic-topology.ts b/tests/scale/synthetic-topology.ts index e0174043..987e06c8 100644 --- a/tests/scale/synthetic-topology.ts +++ b/tests/scale/synthetic-topology.ts @@ -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 diff --git a/tests/scale/telemetry/telemetry-storm.test.ts b/tests/scale/telemetry/telemetry-storm.test.ts index 7d4b9bf3..c8b0c5e4 100644 --- a/tests/scale/telemetry/telemetry-storm.test.ts +++ b/tests/scale/telemetry/telemetry-storm.test.ts @@ -16,7 +16,7 @@ const IDENTICAL: TelemetryEvent = { }; /** - * 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( diff --git a/tests/scale/traffic/amplification-metrics.ts b/tests/scale/traffic/amplification-metrics.ts index c3ca76ab..8bf67d05 100644 --- a/tests/scale/traffic/amplification-metrics.ts +++ b/tests/scale/traffic/amplification-metrics.ts @@ -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 diff --git a/tests/scale/traffic/synthetic-traffic.ts b/tests/scale/traffic/synthetic-traffic.ts index 588e1893..440ab295 100644 --- a/tests/scale/traffic/synthetic-traffic.ts +++ b/tests/scale/traffic/synthetic-traffic.ts @@ -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. */ diff --git a/tests/unit/deletable-history-documents.test.ts b/tests/unit/deletable-history-documents.test.ts index 01bbaec7..387fbd63 100644 --- a/tests/unit/deletable-history-documents.test.ts +++ b/tests/unit/deletable-history-documents.test.ts @@ -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 { const entries = await readdir(directory, { withFileTypes: true }).catch( @@ -45,21 +53,31 @@ async function codeFiles(directory: string): Promise { return files.flat(); } +async function linesMatching(patterns: readonly RegExp[]): Promise { + 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([]); }); }); diff --git a/tests/unit/telemetry.test.ts b/tests/unit/telemetry.test.ts index c775767d..45a6c8a7 100644 --- a/tests/unit/telemetry.test.ts +++ b/tests/unit/telemetry.test.ts @@ -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> = [];