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:
@@ -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/",
|
||||
|
||||
@@ -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
@@ -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을 직접 만든다.
|
||||
|
||||
결정:
|
||||
|
||||
@@ -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을 완료로 표시하거나 삭제하지 않는다.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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) {
|
||||
|
||||
@@ -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";
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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,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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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 (
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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.
|
||||
*/
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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>> = {
|
||||
|
||||
@@ -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(
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
*/
|
||||
|
||||
@@ -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,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,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;
|
||||
|
||||
@@ -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,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,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,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,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
|
||||
|
||||
@@ -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,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
|
||||
|
||||
@@ -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).
|
||||
*/
|
||||
|
||||
@@ -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,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,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,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,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,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.
|
||||
*/
|
||||
|
||||
@@ -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,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,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.
|
||||
*/
|
||||
|
||||
@@ -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,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({
|
||||
|
||||
@@ -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.
|
||||
*/
|
||||
|
||||
@@ -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.
|
||||
*/
|
||||
|
||||
@@ -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,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
|
||||
|
||||
@@ -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.
|
||||
*/
|
||||
|
||||
@@ -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([]);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -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> = [];
|
||||
|
||||
Reference in New Issue
Block a user