diff --git a/.dependency-cruiser.json b/.dependency-cruiser.json index f3ffd9db..b3c60795 100644 --- a/.dependency-cruiser.json +++ b/.dependency-cruiser.json @@ -204,6 +204,54 @@ "pathNot": "^src/adapters/[^/]+/index\\.ts$|^src/adapters/[^/]+/[^/]+/index\\.ts$" } }, + { + "name": "features-do-not-import-other-features", + "comment": "A feature may depend on shared contracts/ports, but never on another feature concrete implementation.", + "severity": "error", + "from": { + "path": "^src/features/([^/]+)/" + }, + "to": { + "path": "^src/features/[^/]+/", + "pathNot": "^src/features/$1/" + } + }, + { + "name": "contexts-do-not-import-other-contexts", + "comment": "A bounded context may compose its own features and shared platform contracts, but not another context concrete implementation.", + "severity": "error", + "from": { + "path": "^src/contexts/([^/]+)/" + }, + "to": { + "path": "^src/contexts/[^/]+/", + "pathNot": "^src/contexts/$1/" + } + }, + { + "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.", + "severity": "error", + "from": { + "path": "^src/", + "pathNot": "^src/adapters/" + }, + "to": { + "path": "^(@sentry|@datadog|@opentelemetry|@newrelic|newrelic|@honeycombio|@bugsnag|bugsnag-js|@rollbar|rollbar|logrocket|@logrocket|@amplitude|posthog-js|mixpanel-browser|@segment|@elastic/apm-rum|@grafana/faro-web-sdk|@microsoft/applicationinsights-web)(/|$)" + } + }, + { + "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. Routing composes deployable-app descriptors by type and is the one named exception.", + "severity": "error", + "from": { + "path": "^src/platform/", + "pathNot": "^src/platform/routing/" + }, + "to": { + "path": "^src/(features|contexts|apps|adapters|bootstrap|presentation|application)/" + } + }, { "name": "no-circular-dependencies", "severity": "error", diff --git a/artifacts/phase5/check-architecture.log b/artifacts/phase5/check-architecture.log new file mode 100644 index 00000000..70a3edf3 --- /dev/null +++ b/artifacts/phase5/check-architecture.log @@ -0,0 +1,5 @@ +$ node scripts/check-architecture.ts +Static import graph: 330 modules, 984 dependencies, all imports resolved +Architecture graph fixtures: 16 regression checks PASS +TypeScript-only source policy: PASS (src, scripts, tests, .storybook, recipes; no fixture exceptions) +Architecture fixtures: allowed PASS, 9 forbidden rejected diff --git a/artifacts/phase5/check-types-app.log b/artifacts/phase5/check-types-app.log new file mode 100644 index 00000000..388c04b1 --- /dev/null +++ b/artifacts/phase5/check-types-app.log @@ -0,0 +1 @@ +$ tsc --project tsconfig.app.json diff --git a/artifacts/phase5/check-types-test.log b/artifacts/phase5/check-types-test.log new file mode 100644 index 00000000..08d11af4 --- /dev/null +++ b/artifacts/phase5/check-types-test.log @@ -0,0 +1 @@ +$ tsc --project tsconfig.test.json diff --git a/artifacts/phase5/traffic-regression.log b/artifacts/phase5/traffic-regression.log new file mode 100644 index 00000000..fe4cb21b --- /dev/null +++ b/artifacts/phase5/traffic-regression.log @@ -0,0 +1,20 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/unit/http-retry-lifecycle.test.ts (4 tests) 4ms + โœ“ tests/unit/realtime/bounded-polling-policy.test.ts (3 tests) 6ms + โœ“ tests/unit/realtime/realtime-reconnect-policy.test.ts (7 tests) 6ms + โœ“ tests/unit/retry-policy.test.ts (4 tests) 5ms + โœ“ tests/unit/realtime/bounded-poll-coordinator.test.ts (16 tests) 25ms + โœ“ tests/unit/realtime/live-poll-handoff-coordinator.test.ts (13 tests) 71ms + โœ“ tests/unit/resumable-upload-runtime.test.ts (18 tests) 87ms + โœ“ tests/unit/realtime/realtime-reconnect-coordinator.test.ts (25 tests) 32ms + โœ“ tests/unit/tanstack-cache-coordinator.test.ts (8 tests) 168ms + โœ“ tests/unit/resumable-upload-runtime-teardown.test.ts (4 tests) 163ms + โœ“ tests/unit/realtime/stream-coordinator.test.ts (36 tests) 625ms + + Test Files  11 passed (11) + Tests  138 passed (138) + Start at  08:27:14 + Duration  1.40s (transform 1.56s, setup 3.50s, import 2.09s, tests 1.19s, environment 2ms) + diff --git a/artifacts/quality/extreme-scale-gates/build.log b/artifacts/quality/extreme-scale-gates/build.log new file mode 100644 index 00000000..98603526 --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/build.log @@ -0,0 +1,37 @@ +contract set: 0 package(s) sha256:ad6aab71fea6a9ff87cbd170b984b339965afc90d85bb57f87801c9e0c020da2 +vite v8.1.5 building client environment for production... + transforming...โœ“ 2113 modules transformed. +rendering chunks... +computing gzip size... +dist/index.html 1.12 kB โ”‚ gzip: 0.45 kB +dist/.vite/manifest.json 8.11 kB โ”‚ gzip: 1.04 kB +dist/.vite/module-inventory.json 21.94 kB โ”‚ gzip: 3.15 kB +dist/assets/index-C0p5zoj4.css 39.62 kB โ”‚ gzip: 8.51 kB +dist/assets/installed-contract-contributions-CFHdeDEf.js 0.16 kB โ”‚ gzip: 0.15 kB +dist/assets/not-found-page-CHQA5rw5.js 0.45 kB โ”‚ gzip: 0.30 kB +dist/assets/reference-resource-status-page-t3RWROLD.js 0.51 kB โ”‚ gzip: 0.45 kB +dist/assets/use-reference-failure-action-BYb2UYeT.js 0.57 kB โ”‚ gzip: 0.37 kB +dist/assets/session-provider-CIR3Mmin.js 0.60 kB โ”‚ gzip: 0.39 kB +dist/assets/application-provider-_OkSTAcq.js 0.61 kB โ”‚ gzip: 0.34 kB +dist/assets/reference-resource-page-1-Q0DGen.js 1.21 kB โ”‚ gzip: 0.77 kB +dist/assets/reference-resource-detail-page-D5mbWw2a.js 1.23 kB โ”‚ gzip: 0.72 kB +dist/assets/async-state-CfvFHl3I.js 1.53 kB โ”‚ gzip: 0.49 kB +dist/assets/auth-example-page-htVwyPYW.js 1.78 kB โ”‚ gzip: 0.94 kB +dist/assets/context-routes-CEM0c3Wb.js 1.80 kB โ”‚ gzip: 0.70 kB +dist/assets/server-state-DQADfngu.js 2.24 kB โ”‚ gzip: 0.90 kB +dist/assets/home-page-a_jMrdst.js 2.37 kB โ”‚ gzip: 1.27 kB +dist/assets/state-gallery-page-CunviFji.js 2.70 kB โ”‚ gzip: 1.22 kB +dist/assets/reference-resource-form-page-BHq_gRJf.js 2.77 kB โ”‚ gzip: 1.50 kB +dist/assets/installed-feature-contracts-DgTAlLr2.js 4.52 kB โ”‚ gzip: 1.43 kB +dist/assets/ui-gallery-page-Ru0CrH32.js 8.09 kB โ”‚ gzip: 2.90 kB +dist/assets/platform-overview-page-BgxC-c_W.js 11.90 kB โ”‚ gzip: 4.08 kB +dist/assets/route-input-DpW3PpRj.js 19.72 kB โ”‚ gzip: 6.27 kB +dist/assets/use-reference-feature-DkrwJNPz.js 23.75 kB โ”‚ gzip: 8.06 kB +dist/assets/preload-helper-ChbRSsLi.js 101.06 kB โ”‚ gzip: 27.93 kB +dist/assets/design-system-Bd1NzELd.js 213.52 kB โ”‚ gzip: 65.78 kB +dist/assets/index-zhAbJ8ef.js 294.86 kB โ”‚ gzip: 91.72 kB + +โœ“ built in 361ms +runtime config: local profile written to dist/config.json (APP_ENV=local, AUTH_MODE=demo) +service worker mode null: skipping worker build +$ node scripts/build-frontend.ts diff --git a/artifacts/quality/extreme-scale-gates/check-app-build-input-bundle.log b/artifacts/quality/extreme-scale-gates/check-app-build-input-bundle.log new file mode 100644 index 00000000..d6bc0c9a --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-app-build-input-bundle.log @@ -0,0 +1,2 @@ +app build input: app=template-app contexts=1 features=1 generatedImports=1 bundle=1 feature dirs PASS +$ node scripts/check-app-build-input.ts --require-bundle diff --git a/artifacts/quality/extreme-scale-gates/check-app-build-input.log b/artifacts/quality/extreme-scale-gates/check-app-build-input.log new file mode 100644 index 00000000..24ccd47a --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-app-build-input.log @@ -0,0 +1,2 @@ +app build input: app=template-app contexts=1 features=1 generatedImports=1 bundle=not checked PASS +$ node scripts/check-app-build-input.ts diff --git a/artifacts/quality/extreme-scale-gates/check-architecture.log b/artifacts/quality/extreme-scale-gates/check-architecture.log new file mode 100644 index 00000000..565ed845 --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-architecture.log @@ -0,0 +1,5 @@ +Static import graph: 363 modules, 1043 dependencies, all imports resolved +Architecture graph fixtures: 16 regression checks PASS +TypeScript-only source policy: PASS (src, scripts, tests, .storybook, recipes; no fixture exceptions) +Architecture fixtures: allowed PASS, 9 forbidden rejected +$ node scripts/check-architecture.ts diff --git a/artifacts/quality/extreme-scale-gates/check-diagnostics.log b/artifacts/quality/extreme-scale-gates/check-diagnostics.log new file mode 100644 index 00000000..bfc6c2b0 --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-diagnostics.log @@ -0,0 +1,2 @@ +Diagnostics contract: 8 diagnostics and 5 telemetry producers PASS +$ node scripts/check-diagnostics.ts diff --git a/artifacts/quality/extreme-scale-gates/check-feature-index.log b/artifacts/quality/extreme-scale-gates/check-feature-index.log new file mode 100644 index 00000000..27dc0c3a --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-feature-index.log @@ -0,0 +1 @@ +$ node scripts/generate-product-feature-index.ts --check diff --git a/artifacts/quality/extreme-scale-gates/check-observability.log b/artifacts/quality/extreme-scale-gates/check-observability.log new file mode 100644 index 00000000..02d9e4c9 --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-observability.log @@ -0,0 +1,23 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/platform/telemetry/telemetry-port.test.ts (3 tests) 8ms + โœ“ tests/platform/telemetry/redact-telemetry.test.ts (14 tests) 17ms + โœ“ tests/platform/telemetry/telemetry-buffer.test.ts (8 tests) 22ms + โœ“ tests/platform/validation/validation-budget.test.ts (7 tests) 10ms + โœ“ tests/platform/telemetry/telemetry-deduplicator.test.ts (8 tests) 13ms + โœ“ tests/architecture/observability-boundaries.test.ts (4 tests) 142ms + โœ“ tests/platform/errors/platform-errors.test.ts (16 tests) 23ms + โœ“ tests/platform/telemetry/trace-context.test.ts (6 tests) 63ms + โœ“ tests/platform/validation/bounded-json.test.ts (10 tests) 107ms + โœ“ tests/platform/errors/app-error.test.ts (10 tests) 7ms + โœ“ tests/platform/errors/failure-boundary.test.tsx (4 tests) 55ms + โœ“ tests/platform/telemetry/telemetry-pipeline.test.ts (9 tests) 785ms + โœ“ bounds network sends during a repeated error storm  718ms + + Test Files  12 passed (12) + Tests  99 passed (99) + Start at  13:29:27 + Duration  1.58s (transform 1.38s, setup 3.81s, import 1.84s, tests 1.25s, environment 902ms) + +$ node scripts/run-vitest.ts run tests/platform/errors tests/platform/validation tests/platform/telemetry tests/architecture/observability-boundaries.test.ts --reporter=default diff --git a/artifacts/quality/extreme-scale-gates/check-registries.log b/artifacts/quality/extreme-scale-gates/check-registries.log new file mode 100644 index 00000000..1abd421a --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-registries.log @@ -0,0 +1,2 @@ +Registry governance: 11 registries PASS; compatibility=breaking +$ node scripts/check-registries.ts diff --git a/artifacts/quality/extreme-scale-gates/check-release-coherence.log b/artifacts/quality/extreme-scale-gates/check-release-coherence.log new file mode 100644 index 00000000..e981f0df --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-release-coherence.log @@ -0,0 +1,16 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/platform/release/release-coherence.test.ts (10 tests) 9ms + โœ“ tests/platform/release/release-mismatch-recovery.test.ts (10 tests) 14ms + โœ“ tests/release/old-asset-reachability.test.ts (4 tests) 8ms + โœ“ tests/platform/release/cache-policy.test.ts (5 tests) 39ms + โœ“ tests/release/release-matrix.test.ts (7 tests) 48ms + โœ“ tests/release/mixed-replica.test.ts (7 tests) 69ms + + Test Files  6 passed (6) + Tests  43 passed (43) + Start at  13:29:30 + Duration  914ms (transform 1.31s, setup 1.45s, import 2.18s, tests 187ms, environment 1ms) + +$ node scripts/run-vitest.ts run tests/platform/release tests/release --reporter=default diff --git a/artifacts/quality/extreme-scale-gates/check-request-fanout.log b/artifacts/quality/extreme-scale-gates/check-request-fanout.log new file mode 100644 index 00000000..03e090d1 --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-request-fanout.log @@ -0,0 +1,3 @@ +request fan-out: 77 files scanned, 0 per-row dispatches PASS +request fan-out fixtures: forbidden 3 rejected in 3 files, allowed 0 violations PASS +$ node scripts/check-request-fanout.ts && node scripts/check-request-fanout.ts --fixture diff --git a/artifacts/quality/extreme-scale-gates/check-scale-baseline.log b/artifacts/quality/extreme-scale-gates/check-scale-baseline.log new file mode 100644 index 00000000..b624defd --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-scale-baseline.log @@ -0,0 +1,4 @@ +compatibility: structural=true compiler=true timing=true +axes: absolute 28 (ok), growth 8 (ok), relative 16 compiler + 12 timing +scale baseline gate: PASSED (artifacts/scale/baseline-comparison.json) +$ node scripts/scale/check-scale-baseline.ts diff --git a/artifacts/quality/extreme-scale-gates/check-scale-main.log b/artifacts/quality/extreme-scale-gates/check-scale-main.log new file mode 100644 index 00000000..c9cf9ea5 --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-scale-main.log @@ -0,0 +1,10 @@ +PASSED main:architecture-topology (3173ms) +PASSED main:traffic-budgets (1489ms) +PASSED main:scale-units (2433ms) +PASSED main:composition-s0-s1 (91ms) +PASSED main:composition-s0-s2 (232ms) +PASSED main:composition-scale-suite (941ms) +PASSED main:typescript-diagnostics (1543ms) +PASSED main:baseline-regression (1739ms) +scale tier main: PASSED (artifacts/scale/main/summary.json) +$ node scripts/scale/run-scale-profile.ts main diff --git a/artifacts/quality/extreme-scale-gates/check-scale-nightly.log b/artifacts/quality/extreme-scale-gates/check-scale-nightly.log new file mode 100644 index 00000000..32a2a312 --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-scale-nightly.log @@ -0,0 +1,14 @@ +PASSED nightly:architecture-topology (3175ms) +PASSED nightly:traffic-budgets (1393ms) +PASSED nightly:scale-units (2435ms) +PASSED nightly:composition-s0-s1 (90ms) +PASSED nightly:composition-s0-s2 (226ms) +PASSED nightly:composition-scale-suite (861ms) +PASSED nightly:typescript-diagnostics (1552ms) +PASSED nightly:baseline-regression (1750ms) +PASSED nightly:topology-s3-s4 (6995ms) +PASSED nightly:telemetry-storm (3703ms) +PASSED nightly:session-cycles (1703ms) +PASSED nightly:browser-soak (121407ms) +scale tier nightly: PASSED (artifacts/scale/nightly/summary.json) +$ node scripts/scale/run-scale-profile.ts nightly diff --git a/artifacts/quality/extreme-scale-gates/check-scale-pr.log b/artifacts/quality/extreme-scale-gates/check-scale-pr.log new file mode 100644 index 00000000..e629a086 --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-scale-pr.log @@ -0,0 +1,6 @@ +PASSED pr:architecture-topology (4307ms) +PASSED pr:traffic-budgets (1446ms) +PASSED pr:scale-units (2377ms) +PASSED pr:composition-s0-s1 (87ms) +scale tier pr: PASSED (artifacts/scale/pr/summary.json) +$ node scripts/scale/run-scale-profile.ts pr diff --git a/artifacts/quality/extreme-scale-gates/check-scale-release.log b/artifacts/quality/extreme-scale-gates/check-scale-release.log new file mode 100644 index 00000000..d145f26f --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-scale-release.log @@ -0,0 +1,13 @@ +PASSED release:release-coherence (1123ms) +PASSED release:architecture-topology (3142ms) +PASSED release:traffic-budgets (1432ms) +PASSED release:scale-units (2318ms) +PASSED release:composition-s0-s1 (95ms) +PASSED release:composition-s0-s2 (235ms) +PASSED release:composition-scale-suite (843ms) +PASSED release:typescript-diagnostics (1499ms) +PASSED release:baseline-regression (1820ms) +PASSED release:topology-s3-s4 (7137ms) +PASSED release:telemetry-storm (3364ms) +scale tier release: PASSED (artifacts/scale/release/summary.json) +$ node scripts/scale/run-scale-profile.ts release diff --git a/artifacts/quality/extreme-scale-gates/check-topology.log b/artifacts/quality/extreme-scale-gates/check-topology.log new file mode 100644 index 00000000..f971e428 --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-topology.log @@ -0,0 +1,19 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/platform/cardinality/cardinality-budget.test.ts (3 tests) 7ms + โœ“ tests/platform/cardinality/compose-unique-record.test.ts (2 tests) 9ms + โœ“ tests/architecture/context-lazy-loading.test.ts (1 test) 6ms + โœ“ tests/platform/routing/context-route-module.test.ts (3 tests) 9ms + โœ“ tests/architecture/topology-cardinality.test.ts (9 tests) 13ms + โœ“ tests/platform/cardinality/extreme-scale-registry.test.ts (3 tests) 2363ms + โœ“ keeps 10k -> 100k composition growth below a quadratic regression budget  391ms + โœ“ keeps one million lookups bounded on a 100k-entry runtime registry  1515ms + โœ“ selects and resolves 100k feature ids within the membership budget  455ms + + Test Files  6 passed (6) + Tests  21 passed (21) + Start at  13:29:21 + Duration  2.94s (transform 231ms, setup 1.63s, import 305ms, tests 2.41s, environment 1ms) + +$ node scripts/run-vitest.ts run tests/architecture/topology-cardinality.test.ts tests/architecture/context-lazy-loading.test.ts tests/platform/cardinality tests/platform/routing --reporter=default diff --git a/artifacts/quality/extreme-scale-gates/check-traffic.log b/artifacts/quality/extreme-scale-gates/check-traffic.log new file mode 100644 index 00000000..dbc62acb --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-traffic.log @@ -0,0 +1,21 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/platform/traffic/request-budget.test.ts (7 tests) 17ms + โœ“ tests/platform/resilience/retry-budget.test.ts (6 tests) 7ms + โœ“ tests/platform/resilience/deadline.test.ts (3 tests) 6ms + โœ“ tests/platform/traffic/concurrency-budget.test.ts (6 tests) 11ms + โœ“ tests/platform/execution/execution-context.test.ts (10 tests) 11ms + โœ“ tests/platform/traffic/traffic-budget.test.ts (9 tests) 11ms + โœ“ tests/platform/traffic/operation-traffic-policy.test.ts (7 tests) 10ms + โœ“ tests/platform/traffic/request-fanout.test.ts (6 tests) 49ms + โœ“ tests/platform/traffic/request-deduplication.test.ts (3 tests) 47ms + โœ“ tests/platform/traffic/http-budget-integration.test.ts (9 tests) 130ms + โœ“ tests/platform/traffic/traffic-amplification.test.ts (3 tests) 391ms + + Test Files  11 passed (11) + Tests  69 passed (69) + Start at  13:29:25 + Duration  1.34s (transform 858ms, setup 4.17s, import 1.44s, tests 690ms, environment 2ms) + +$ node scripts/run-vitest.ts run tests/platform/execution tests/platform/traffic tests/platform/resilience --reporter=default diff --git a/artifacts/quality/extreme-scale-gates/check-types-app.log b/artifacts/quality/extreme-scale-gates/check-types-app.log new file mode 100644 index 00000000..388c04b1 --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-types-app.log @@ -0,0 +1 @@ +$ tsc --project tsconfig.app.json diff --git a/artifacts/quality/extreme-scale-gates/check-types-test.log b/artifacts/quality/extreme-scale-gates/check-types-test.log new file mode 100644 index 00000000..08d11af4 --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-types-test.log @@ -0,0 +1 @@ +$ tsc --project tsconfig.test.json diff --git a/artifacts/quality/extreme-scale-gates/check-types.log b/artifacts/quality/extreme-scale-gates/check-types.log new file mode 100644 index 00000000..9a7a2716 --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/check-types.log @@ -0,0 +1,7 @@ +$ corepack pnpm check:types:app && corepack pnpm check:types:node && corepack pnpm check:types:test && corepack pnpm check:types:recipes && corepack pnpm check:types:web-worker && corepack pnpm check:types:service-worker +$ tsc --project tsconfig.app.json +$ tsc --project tsconfig.node.json +$ tsc --project tsconfig.test.json +$ node scripts/check-optional-recipe-types.ts +$ tsc --project tsconfig.web-worker.json +$ tsc --project tsconfig.service-worker.json diff --git a/artifacts/quality/extreme-scale-gates/lint.log b/artifacts/quality/extreme-scale-gates/lint.log new file mode 100644 index 00000000..90a5c4cf --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/lint.log @@ -0,0 +1 @@ +$ eslint src scripts tests recipes .storybook vite.config.ts vitest.config.ts playwright*.config.ts --max-warnings=0 diff --git a/artifacts/quality/extreme-scale-gates/test-extreme-scale-focused.log b/artifacts/quality/extreme-scale-gates/test-extreme-scale-focused.log new file mode 100644 index 00000000..45372352 --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/test-extreme-scale-focused.log @@ -0,0 +1,23 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/scripts/generate-product-feature-index.test.ts (8 tests) 41ms + โœ“ tests/platform/traffic/request-deduplication.test.ts (3 tests) 54ms + โœ“ tests/platform/traffic/request-fanout.test.ts (6 tests) 56ms + โœ“ tests/architecture/request-fanout.test.ts (4 tests) 194ms + โœ“ tests/features/reference-feature/reference-request-deduplication.test.ts (3 tests) 50ms + โœ“ tests/features/reference-feature/reference-request-fanout.test.ts (8 tests) 68ms + โœ“ tests/architecture/app-build-input.test.ts (4 tests) 2380ms + โœ“ accepts the production generator's output and an app-local bundle  771ms + โœ“ rejects a generator regression that imports every discovered feature  673ms + โœ“ rejects a production bundle that contains another app's feature  643ms + โœ“ tests/scale/global-local-independence.test.ts (7 tests) 7755ms + โœ“ keeps App A's generated indexes and reachable source graph identical from S0 to S2 on disk  5260ms + โœ“ selects another app from the same repository without App A's features  982ms + + Test Files  8 passed (8) + Tests  43 passed (43) + Start at  13:29:12 + Duration  8.30s (transform 919ms, setup 1.94s, import 1.61s, tests 10.60s, environment 1ms) + +$ node scripts/run-vitest.ts run tests/scale/global-local-independence.test.ts tests/architecture/app-build-input.test.ts tests/architecture/request-fanout.test.ts tests/platform/traffic/request-fanout.test.ts tests/platform/traffic/request-deduplication.test.ts tests/features/reference-feature/reference-request-fanout.test.ts tests/features/reference-feature/reference-request-deduplication.test.ts tests/scripts/generate-product-feature-index.test.ts --reporter=default diff --git a/artifacts/quality/extreme-scale-gates/test-platform.log b/artifacts/quality/extreme-scale-gates/test-platform.log new file mode 100644 index 00000000..d634a635 --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/test-platform.log @@ -0,0 +1,55 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/architecture/app-build-input.test.ts (4 tests) 9429ms + โœ“ accepts the production generator's output and an app-local bundle  1340ms + โœ“ rejects a generator regression that imports every discovered feature  5122ms + โœ“ rejects a production bundle that contains another app's feature  2464ms + โœ“ tests/platform/cardinality/extreme-scale-registry.test.ts (3 tests) 3975ms + โœ“ keeps 10k -> 100k composition growth below a quadratic regression budget  634ms + โœ“ keeps one million lookups bounded on a 100k-entry runtime registry  2331ms + โœ“ selects and resolves 100k feature ids within the membership budget  1007ms + โœ“ tests/platform/telemetry/telemetry-pipeline.test.ts (9 tests) 1077ms + โœ“ bounds network sends during a repeated error storm  961ms + โœ“ tests/platform/traffic/traffic-amplification.test.ts (3 tests) 558ms + โœ“ keeps physical requests bounded when every dispatch fails  307ms + โœ“ tests/architecture/request-fanout.test.ts (4 tests) 344ms + โœ“ finds no per-row dispatch in feature code or application use cases  330ms + โœ“ tests/architecture/observability-boundaries.test.ts (4 tests) 235ms + โœ“ tests/platform/traffic/http-budget-integration.test.ts (9 tests) 133ms + โœ“ tests/platform/validation/bounded-json.test.ts (10 tests) 140ms + โœ“ tests/platform/telemetry/trace-context.test.ts (6 tests) 82ms + โœ“ tests/platform/errors/failure-boundary.test.tsx (4 tests) 87ms + โœ“ tests/platform/traffic/request-fanout.test.ts (6 tests) 75ms + โœ“ tests/platform/traffic/request-deduplication.test.ts (3 tests) 74ms + โœ“ tests/platform/release/cache-policy.test.ts (5 tests) 40ms + โœ“ tests/platform/errors/platform-errors.test.ts (16 tests) 19ms + โœ“ tests/platform/telemetry/telemetry-buffer.test.ts (8 tests) 20ms + โœ“ tests/platform/telemetry/redact-telemetry.test.ts (14 tests) 14ms + โœ“ tests/platform/traffic/request-budget.test.ts (7 tests) 7ms + โœ“ tests/platform/release/release-mismatch-recovery.test.ts (10 tests) 12ms + โœ“ tests/architecture/topology-cardinality.test.ts (9 tests) 10ms + โœ“ tests/platform/telemetry/telemetry-deduplicator.test.ts (8 tests) 9ms + โœ“ tests/platform/traffic/concurrency-budget.test.ts (6 tests) 11ms + โœ“ tests/platform/execution/execution-context.test.ts (10 tests) 12ms + โœ“ tests/platform/traffic/traffic-budget.test.ts (9 tests) 8ms + โœ“ tests/platform/validation/validation-budget.test.ts (7 tests) 11ms + โœ“ tests/platform/traffic/operation-traffic-policy.test.ts (7 tests) 11ms + โœ“ tests/platform/routing/context-route-module.test.ts (3 tests) 10ms + โœ“ tests/platform/release/release-coherence.test.ts (10 tests) 13ms + โœ“ tests/platform/cardinality/compose-unique-record.test.ts (2 tests) 5ms + โœ“ tests/platform/telemetry/telemetry-port.test.ts (3 tests) 6ms + โœ“ tests/platform/resilience/retry-budget.test.ts (6 tests) 5ms + โœ“ tests/platform/errors/app-error.test.ts (10 tests) 6ms + โœ“ tests/platform/cardinality/cardinality-budget.test.ts (3 tests) 7ms + โœ“ tests/architecture/context-lazy-loading.test.ts (1 test) 6ms + โœ“ tests/platform/resilience/deadline.test.ts (3 tests) 7ms + โœ“ tests/architecture/module-hierarchy.test.ts (1 test) 6ms + + Test Files  35 passed (35) + Tests  223 passed (223) + Start at  13:29:32 + Duration  33.44s (transform 977ms, setup 7.36s, import 2.52s, tests 16.46s, environment 1.01s) + +JUNIT report written to /shared/codebase/clean-architecture-frontend-template/artifacts/tests/platform.xml +$ node scripts/run-vitest.ts run tests/platform tests/architecture --no-file-parallelism --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/platform.xml diff --git a/artifacts/quality/extreme-scale-gates/test-reference-feature.log b/artifacts/quality/extreme-scale-gates/test-reference-feature.log new file mode 100644 index 00000000..84e4fd89 --- /dev/null +++ b/artifacts/quality/extreme-scale-gates/test-reference-feature.log @@ -0,0 +1,30 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/features/reference-feature/reference-error.test.ts (3 tests) 102ms + โœ“ tests/features/reference-feature/reference-telemetry.test.ts (4 tests) 55ms + โœ“ tests/features/reference-feature/reference-http-problem-mapping.test.ts (6 tests) 12ms + โœ“ tests/features/reference-feature/reference-request-deduplication.test.ts (3 tests) 112ms + โœ“ tests/features/reference-feature/reference-request-fanout.test.ts (8 tests) 189ms + โœ“ tests/features/reference-feature/reference-traffic-policy.test.ts (1 test) 9ms + โœ“ tests/features/reference-feature/installed-context-routing.test.ts (2 tests) 108ms + โœ“ tests/features/reference-feature/reference-contract.test.ts (7 tests) 35ms + โœ“ tests/features/reference-feature/feature-module.test.ts (1 test) 6ms + โœ“ tests/features/reference-feature/reference-http-gateway.test.ts (2 tests) 8ms + โœ“ tests/features/reference-feature/reference-installed-executor.test.ts (1 test) 7ms + โœ“ tests/features/reference-feature/reference-diagnostics.test.ts (1 test) 81ms + โœ“ tests/features/reference-feature/reference-runtime-composition.test.ts (3 tests) 201ms + โœ“ tests/features/reference-feature/reference-production-vertical.test.tsx (1 test) 1243ms + โœ“ traverses bootstrap, router, application, HTTP schema/mapper and query cache  1237ms + โœ“ tests/features/reference-feature/reference-page.test.tsx (11 tests) 3248ms + โœ“ mounts list and detail keys under the installed governed namespace  1035ms + โœ“ renders backend forbidden even when the client access hint allowed entry  423ms + โœ“ deduplicates create, preserves input and surfaces a conflict  584ms + + Test Files  15 passed (15) + Tests  54 passed (54) + Start at  13:30:06 + Duration  7.80s (transform 13.26s, setup 7.90s, import 20.03s, tests 5.42s, environment 2.84s) + +JUNIT report written to /shared/codebase/clean-architecture-frontend-template/artifacts/tests/reference-feature.xml +$ node scripts/run-vitest.ts run tests/features/reference-feature --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/reference-feature.xml --passWithNoTests diff --git a/artifacts/scale/main/architecture-topology.log b/artifacts/scale/main/architecture-topology.log new file mode 100644 index 00000000..26511617 --- /dev/null +++ b/artifacts/scale/main/architecture-topology.log @@ -0,0 +1,25 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/platform/cardinality/cardinality-budget.test.ts (3 tests) 6ms + โœ“ tests/platform/cardinality/compose-unique-record.test.ts (2 tests) 7ms + โœ“ tests/architecture/module-hierarchy.test.ts (1 test) 5ms + โœ“ tests/architecture/context-lazy-loading.test.ts (1 test) 6ms + โœ“ tests/platform/routing/context-route-module.test.ts (3 tests) 10ms + โœ“ tests/architecture/topology-cardinality.test.ts (9 tests) 11ms + โœ“ tests/architecture/observability-boundaries.test.ts (4 tests) 97ms + โœ“ tests/architecture/request-fanout.test.ts (4 tests) 206ms + โœ“ tests/platform/cardinality/extreme-scale-registry.test.ts (3 tests) 2005ms + โœ“ keeps 10k -> 100k composition growth below a quadratic regression budget  407ms + โœ“ keeps one million lookups bounded on a 100k-entry runtime registry  1229ms + โœ“ selects and resolves 100k feature ids within the membership budget  366ms + โœ“ tests/architecture/app-build-input.test.ts (4 tests) 2215ms + โœ“ accepts the production generator's output and an app-local bundle  714ms + โœ“ rejects a generator regression that imports every discovered feature  626ms + โœ“ rejects a production bundle that contains another app's feature  613ms + + Test Files  10 passed (10) + Tests  34 passed (34) + Start at  13:30:24 + Duration  2.82s (transform 645ms, setup 2.94s, import 949ms, tests 4.57s, environment 2ms) + diff --git a/artifacts/scale/main/baseline-regression.log b/artifacts/scale/main/baseline-regression.log new file mode 100644 index 00000000..041945a2 --- /dev/null +++ b/artifacts/scale/main/baseline-regression.log @@ -0,0 +1,3 @@ +compatibility: structural=true compiler=true timing=true +axes: absolute 28 (ok), growth 8 (ok), relative 16 compiler + 12 timing +scale baseline gate: PASSED (artifacts/scale/main/baseline-regression.json) diff --git a/artifacts/scale/main/composition-s0-s1.log b/artifacts/scale/main/composition-s0-s1.log new file mode 100644 index 00000000..8b47e2ad --- /dev/null +++ b/artifacts/scale/main/composition-s0-s1.log @@ -0,0 +1,5 @@ +PASS registry-composition:growth (exponents 0.00) +PASS product-feature-selection:growth (exponents 0.00) +PASS product-feature-resolution:growth (exponents 0.00) +PASS context-hierarchy-composition:growth (exponents 0.00) +composition scale artifact: /shared/codebase/clean-architecture-frontend-template/artifacts/scale/main/composition-s0-s1.json diff --git a/artifacts/scale/main/composition-s0-s2.log b/artifacts/scale/main/composition-s0-s2.log new file mode 100644 index 00000000..5a79c68b --- /dev/null +++ b/artifacts/scale/main/composition-s0-s2.log @@ -0,0 +1,5 @@ +PASS registry-composition:growth (exponents 0.00, 0.64) +PASS product-feature-selection:growth (exponents 0.00, 0.83) +PASS product-feature-resolution:growth (exponents 0.00, 0.83) +PASS context-hierarchy-composition:growth (exponents 0.00, 0.34) +composition scale artifact: /shared/codebase/clean-architecture-frontend-template/artifacts/scale/main/composition-s0-s2.json diff --git a/artifacts/scale/main/composition-scale-suite.log b/artifacts/scale/main/composition-scale-suite.log new file mode 100644 index 00000000..9ce1a4eb --- /dev/null +++ b/artifacts/scale/main/composition-scale-suite.log @@ -0,0 +1,11 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/scale/tsc-diagnostics-parser.test.ts (3 tests) 7ms + โœ“ tests/scale/composition-scale.test.ts (6 tests) 232ms + + Test Files  2 passed (2) + Tests  9 passed (9) + Start at  13:30:31 + Duration  596ms (transform 94ms, setup 326ms, import 114ms, tests 239ms, environment 0ms) + diff --git a/artifacts/scale/main/scale-units.log b/artifacts/scale/main/scale-units.log new file mode 100644 index 00000000..52c54bf4 --- /dev/null +++ b/artifacts/scale/main/scale-units.log @@ -0,0 +1,17 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/scale/growth-regression.test.ts (7 tests) 6ms + โœ“ tests/scale/traffic/retry-after-jitter.test.ts (5 tests) 38ms + โœ“ tests/scale/traffic/amplification-metrics.test.ts (6 tests) 5ms + โœ“ tests/scale/benchmark.test.ts (4 tests) 8ms + โœ“ tests/scale/synthetic-topology.test.ts (8 tests) 8ms + โœ“ tests/scale/scale-baseline.test.ts (11 tests) 11ms + โœ“ tests/scale/traffic/failure-scenarios.test.ts (5 tests) 1420ms + โœ“ bounds physical requests when all upstream calls fail  896ms + + Test Files  7 passed (7) + Tests  46 passed (46) + Start at  13:30:29 + Duration  2.04s (transform 695ms, setup 1.76s, import 808ms, tests 1.50s, environment 1ms) + diff --git a/artifacts/scale/main/traffic-budgets.log b/artifacts/scale/main/traffic-budgets.log new file mode 100644 index 00000000..b49a8ea7 --- /dev/null +++ b/artifacts/scale/main/traffic-budgets.log @@ -0,0 +1,20 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/platform/resilience/deadline.test.ts (3 tests) 4ms + โœ“ tests/platform/traffic/request-budget.test.ts (7 tests) 5ms + โœ“ tests/platform/resilience/retry-budget.test.ts (6 tests) 7ms + โœ“ tests/platform/traffic/concurrency-budget.test.ts (6 tests) 11ms + โœ“ tests/platform/traffic/traffic-budget.test.ts (9 tests) 10ms + โœ“ tests/platform/execution/execution-context.test.ts (10 tests) 9ms + โœ“ tests/platform/traffic/operation-traffic-policy.test.ts (7 tests) 9ms + โœ“ tests/platform/traffic/request-fanout.test.ts (6 tests) 59ms + โœ“ tests/platform/traffic/request-deduplication.test.ts (3 tests) 47ms + โœ“ tests/platform/traffic/http-budget-integration.test.ts (9 tests) 124ms + โœ“ tests/platform/traffic/traffic-amplification.test.ts (3 tests) 379ms + + Test Files  11 passed (11) + Tests  69 passed (69) + Start at  13:30:27 + Duration  1.13s (transform 1.01s, setup 3.62s, import 1.55s, tests 663ms, environment 2ms) + diff --git a/artifacts/scale/main/typescript-diagnostics.log b/artifacts/scale/main/typescript-diagnostics.log new file mode 100644 index 00000000..f0982fbb --- /dev/null +++ b/artifacts/scale/main/typescript-diagnostics.log @@ -0,0 +1,5 @@ +tsc app: files=827 types=279186 instantiations=700415 +PASS tsc:types (exponents 0.84, 0.96) +PASS tsc:symbols (exponents 0.51, 0.80) +PASS tsc:instantiations (exponents 0.97, 0.99) +tsc diagnostics artifact: /shared/codebase/clean-architecture-frontend-template/artifacts/scale/main/typescript-diagnostics.json diff --git a/artifacts/scale/nightly/architecture-topology.log b/artifacts/scale/nightly/architecture-topology.log new file mode 100644 index 00000000..9debb7bf --- /dev/null +++ b/artifacts/scale/nightly/architecture-topology.log @@ -0,0 +1,25 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/platform/cardinality/compose-unique-record.test.ts (2 tests) 5ms + โœ“ tests/platform/cardinality/cardinality-budget.test.ts (3 tests) 5ms + โœ“ tests/architecture/module-hierarchy.test.ts (1 test) 6ms + โœ“ tests/architecture/context-lazy-loading.test.ts (1 test) 7ms + โœ“ tests/platform/routing/context-route-module.test.ts (3 tests) 8ms + โœ“ tests/architecture/topology-cardinality.test.ts (9 tests) 13ms + โœ“ tests/architecture/observability-boundaries.test.ts (4 tests) 109ms + โœ“ tests/architecture/request-fanout.test.ts (4 tests) 151ms + โœ“ tests/platform/cardinality/extreme-scale-registry.test.ts (3 tests) 1946ms + โœ“ keeps 10k -> 100k composition growth below a quadratic regression budget  378ms + โœ“ keeps one million lookups bounded on a 100k-entry runtime registry  1201ms + โœ“ selects and resolves 100k feature ids within the membership budget  365ms + โœ“ tests/architecture/app-build-input.test.ts (4 tests) 2219ms + โœ“ accepts the production generator's output and an app-local bundle  671ms + โœ“ rejects a generator regression that imports every discovered feature  648ms + โœ“ rejects a production bundle that contains another app's feature  649ms + + Test Files  10 passed (10) + Tests  34 passed (34) + Start at  13:30:41 + Duration  2.82s (transform 580ms, setup 3.20s, import 787ms, tests 4.47s, environment 2ms) + diff --git a/artifacts/scale/nightly/baseline-regression.log b/artifacts/scale/nightly/baseline-regression.log new file mode 100644 index 00000000..47c89185 --- /dev/null +++ b/artifacts/scale/nightly/baseline-regression.log @@ -0,0 +1,3 @@ +compatibility: structural=true compiler=true timing=true +axes: absolute 28 (ok), growth 8 (ok), relative 16 compiler + 12 timing +scale baseline gate: PASSED (artifacts/scale/nightly/baseline-regression.json) diff --git a/artifacts/scale/nightly/browser-soak.log b/artifacts/scale/nightly/browser-soak.log new file mode 100644 index 00000000..7751993d --- /dev/null +++ b/artifacts/scale/nightly/browser-soak.log @@ -0,0 +1,12 @@ +browser soak: passed classification=stable samples=24 cycles=2012 +PASS cycles (2012 >= 200) +PASS post-warmup samples (18 >= 3) +PASS navigation (0 failures) +PASS heap slope (stable) +PASS listeners (stable, delta 2) +PASS timers (delta 0, max 2) +PASS in-flight settles (final 0, max 0) +PASS storage growth (keys 0, bytes 0) +PASS backend failure exercised (68 settled visits, 479 API requests, 24 telemetry events) +PASS request amplification (479 requests / 336 visits) +PASS telemetry rate (max 14/min, 24 posts, 24 events) diff --git a/artifacts/scale/nightly/composition-s0-s1.log b/artifacts/scale/nightly/composition-s0-s1.log new file mode 100644 index 00000000..f6854892 --- /dev/null +++ b/artifacts/scale/nightly/composition-s0-s1.log @@ -0,0 +1,5 @@ +PASS registry-composition:growth (exponents 0.00) +PASS product-feature-selection:growth (exponents 0.00) +PASS product-feature-resolution:growth (exponents 0.00) +PASS context-hierarchy-composition:growth (exponents 0.00) +composition scale artifact: /shared/codebase/clean-architecture-frontend-template/artifacts/scale/nightly/composition-s0-s1.json diff --git a/artifacts/scale/nightly/composition-s0-s2.log b/artifacts/scale/nightly/composition-s0-s2.log new file mode 100644 index 00000000..cf0e827b --- /dev/null +++ b/artifacts/scale/nightly/composition-s0-s2.log @@ -0,0 +1,5 @@ +PASS registry-composition:growth (exponents 0.00, 0.64) +PASS product-feature-selection:growth (exponents 0.00, 0.85) +PASS product-feature-resolution:growth (exponents 0.00, 0.83) +PASS context-hierarchy-composition:growth (exponents 0.00, 0.34) +composition scale artifact: /shared/codebase/clean-architecture-frontend-template/artifacts/scale/nightly/composition-s0-s2.json diff --git a/artifacts/scale/nightly/composition-scale-suite.log b/artifacts/scale/nightly/composition-scale-suite.log new file mode 100644 index 00000000..055c5b6a --- /dev/null +++ b/artifacts/scale/nightly/composition-scale-suite.log @@ -0,0 +1,11 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/scale/tsc-diagnostics-parser.test.ts (3 tests) 6ms + โœ“ tests/scale/composition-scale.test.ts (6 tests) 191ms + + Test Files  2 passed (2) + Tests  9 passed (9) + Start at  13:30:48 + Duration  514ms (transform 78ms, setup 296ms, import 81ms, tests 197ms, environment 0ms) + diff --git a/artifacts/scale/nightly/scale-units.log b/artifacts/scale/nightly/scale-units.log new file mode 100644 index 00000000..acaba57c --- /dev/null +++ b/artifacts/scale/nightly/scale-units.log @@ -0,0 +1,17 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/scale/traffic/retry-after-jitter.test.ts (5 tests) 34ms + โœ“ tests/scale/traffic/amplification-metrics.test.ts (6 tests) 6ms + โœ“ tests/scale/benchmark.test.ts (4 tests) 8ms + โœ“ tests/scale/growth-regression.test.ts (7 tests) 6ms + โœ“ tests/scale/synthetic-topology.test.ts (8 tests) 8ms + โœ“ tests/scale/scale-baseline.test.ts (11 tests) 14ms + โœ“ tests/scale/traffic/failure-scenarios.test.ts (5 tests) 1453ms + โœ“ bounds physical requests when all upstream calls fail  896ms + + Test Files  7 passed (7) + Tests  46 passed (46) + Start at  13:30:45 + Duration  2.07s (transform 436ms, setup 1.74s, import 563ms, tests 1.53s, environment 1ms) + diff --git a/artifacts/scale/nightly/session-cycles.log b/artifacts/scale/nightly/session-cycles.log new file mode 100644 index 00000000..978ef846 --- /dev/null +++ b/artifacts/scale/nightly/session-cycles.log @@ -0,0 +1,12 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/scale/session/network-flap.test.ts (2 tests) 324ms + โœ“ tests/scale/session/long-session.test.ts (1 test) 921ms + โœ“ returns timers, listeners, leases, buffers and cache entries to a stable bound  919ms + + Test Files  2 passed (2) + Tests  3 passed (3) + Start at  13:31:03 + Duration  1.37s (transform 228ms, setup 296ms, import 363ms, tests 1.24s, environment 0ms) + diff --git a/artifacts/scale/nightly/telemetry-storm.log b/artifacts/scale/nightly/telemetry-storm.log new file mode 100644 index 00000000..0823d58b --- /dev/null +++ b/artifacts/scale/nightly/telemetry-storm.log @@ -0,0 +1,19 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/platform/telemetry/telemetry-port.test.ts (3 tests) 6ms + โœ“ tests/platform/telemetry/telemetry-deduplicator.test.ts (8 tests) 11ms + โœ“ tests/platform/telemetry/telemetry-buffer.test.ts (8 tests) 15ms + โœ“ tests/platform/telemetry/redact-telemetry.test.ts (14 tests) 11ms + โœ“ tests/platform/telemetry/trace-context.test.ts (6 tests) 43ms + โœ“ tests/platform/telemetry/telemetry-pipeline.test.ts (9 tests) 669ms + โœ“ bounds network sends during a repeated error storm  609ms + โœ“ tests/scale/telemetry/telemetry-storm.test.ts (4 tests) 2882ms + โœ“ does not turn 100000 identical failures into 100000 sends  748ms + โœ“ bounds sends and buffer when a storm has many distinct fingerprints  2099ms + + Test Files  7 passed (7) + Tests  52 passed (52) + Start at  13:30:59 + Duration  3.35s (transform 427ms, setup 1.75s, import 534ms, tests 3.64s, environment 1ms) + diff --git a/artifacts/scale/nightly/topology-s3-s4.log b/artifacts/scale/nightly/topology-s3-s4.log new file mode 100644 index 00000000..d035d0dc --- /dev/null +++ b/artifacts/scale/nightly/topology-s3-s4.log @@ -0,0 +1,16 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/platform/cardinality/extreme-scale-registry.test.ts (3 tests) 1822ms + โœ“ keeps 10k -> 100k composition growth below a quadratic regression budget  313ms + โœ“ keeps one million lookups bounded on a 100k-entry runtime registry  1163ms + โœ“ selects and resolves 100k feature ids within the membership budget  345ms + โœ“ tests/scale/global-local-independence.test.ts (7 tests) 6311ms + โœ“ keeps App A's generated indexes and reachable source graph identical from S0 to S2 on disk  4764ms + โœ“ selects another app from the same repository without App A's features  583ms + + Test Files  2 passed (2) + Tests  10 passed (10) + Start at  13:30:52 + Duration  6.64s (transform 87ms, setup 327ms, import 80ms, tests 8.13s, environment 0ms) + diff --git a/artifacts/scale/nightly/traffic-budgets.log b/artifacts/scale/nightly/traffic-budgets.log new file mode 100644 index 00000000..7d62db26 --- /dev/null +++ b/artifacts/scale/nightly/traffic-budgets.log @@ -0,0 +1,20 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/platform/traffic/concurrency-budget.test.ts (6 tests) 9ms + โœ“ tests/platform/resilience/deadline.test.ts (3 tests) 4ms + โœ“ tests/platform/traffic/request-budget.test.ts (7 tests) 7ms + โœ“ tests/platform/resilience/retry-budget.test.ts (6 tests) 5ms + โœ“ tests/platform/traffic/traffic-budget.test.ts (9 tests) 8ms + โœ“ tests/platform/execution/execution-context.test.ts (10 tests) 10ms + โœ“ tests/platform/traffic/operation-traffic-policy.test.ts (7 tests) 9ms + โœ“ tests/platform/traffic/request-fanout.test.ts (6 tests) 41ms + โœ“ tests/platform/traffic/request-deduplication.test.ts (3 tests) 40ms + โœ“ tests/platform/traffic/http-budget-integration.test.ts (9 tests) 121ms + โœ“ tests/platform/traffic/traffic-amplification.test.ts (3 tests) 316ms + + Test Files  11 passed (11) + Tests  69 passed (69) + Start at  13:30:44 + Duration  1.04s (transform 890ms, setup 3.40s, import 1.40s, tests 570ms, environment 2ms) + diff --git a/artifacts/scale/nightly/typescript-diagnostics.log b/artifacts/scale/nightly/typescript-diagnostics.log new file mode 100644 index 00000000..a9f17c57 --- /dev/null +++ b/artifacts/scale/nightly/typescript-diagnostics.log @@ -0,0 +1,5 @@ +tsc app: files=827 types=279186 instantiations=700415 +PASS tsc:types (exponents 0.84, 0.96) +PASS tsc:symbols (exponents 0.51, 0.80) +PASS tsc:instantiations (exponents 0.97, 0.99) +tsc diagnostics artifact: /shared/codebase/clean-architecture-frontend-template/artifacts/scale/nightly/typescript-diagnostics.json diff --git a/artifacts/scale/pr/architecture-topology.log b/artifacts/scale/pr/architecture-topology.log new file mode 100644 index 00000000..7bb024ec --- /dev/null +++ b/artifacts/scale/pr/architecture-topology.log @@ -0,0 +1,25 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/architecture/module-hierarchy.test.ts (1 test) 14ms + โœ“ tests/architecture/topology-cardinality.test.ts (9 tests) 37ms + โœ“ tests/architecture/observability-boundaries.test.ts (4 tests) 210ms + โœ“ tests/architecture/context-lazy-loading.test.ts (1 test) 18ms + โœ“ tests/platform/cardinality/cardinality-budget.test.ts (3 tests) 22ms + โœ“ tests/platform/cardinality/compose-unique-record.test.ts (2 tests) 12ms + โœ“ tests/platform/routing/context-route-module.test.ts (3 tests) 11ms + โœ“ tests/architecture/request-fanout.test.ts (4 tests) 234ms + โœ“ tests/platform/cardinality/extreme-scale-registry.test.ts (3 tests) 2791ms + โœ“ keeps 10k -> 100k composition growth below a quadratic regression budget  721ms + โœ“ keeps one million lookups bounded on a 100k-entry runtime registry  1649ms + โœ“ selects and resolves 100k feature ids within the membership budget  420ms + โœ“ tests/architecture/app-build-input.test.ts (4 tests) 2872ms + โœ“ accepts the production generator's output and an app-local bundle  996ms + โœ“ rejects a generator regression that imports every discovered feature  897ms + โœ“ rejects a production bundle that contains another app's feature  723ms + + Test Files  10 passed (10) + Tests  34 passed (34) + Start at  13:30:15 + Duration  3.81s (transform 625ms, setup 4.78s, import 1.11s, tests 6.22s, environment 2ms) + diff --git a/artifacts/scale/pr/composition-s0-s1.log b/artifacts/scale/pr/composition-s0-s1.log new file mode 100644 index 00000000..bd2058b4 --- /dev/null +++ b/artifacts/scale/pr/composition-s0-s1.log @@ -0,0 +1,5 @@ +PASS registry-composition:growth (exponents 0.00) +PASS product-feature-selection:growth (exponents 0.00) +PASS product-feature-resolution:growth (exponents 0.00) +PASS context-hierarchy-composition:growth (exponents 0.00) +composition scale artifact: /shared/codebase/clean-architecture-frontend-template/artifacts/scale/pr/composition-s0-s1.json diff --git a/artifacts/scale/pr/scale-units.log b/artifacts/scale/pr/scale-units.log new file mode 100644 index 00000000..7d2a53fa --- /dev/null +++ b/artifacts/scale/pr/scale-units.log @@ -0,0 +1,17 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/scale/traffic/amplification-metrics.test.ts (6 tests) 5ms + โœ“ tests/scale/growth-regression.test.ts (7 tests) 6ms + โœ“ tests/scale/traffic/retry-after-jitter.test.ts (5 tests) 38ms + โœ“ tests/scale/benchmark.test.ts (4 tests) 7ms + โœ“ tests/scale/synthetic-topology.test.ts (8 tests) 10ms + โœ“ tests/scale/scale-baseline.test.ts (11 tests) 11ms + โœ“ tests/scale/traffic/failure-scenarios.test.ts (5 tests) 1429ms + โœ“ bounds physical requests when all upstream calls fail  919ms + + Test Files  7 passed (7) + Tests  46 passed (46) + Start at  13:30:21 + Duration  2.02s (transform 485ms, setup 1.52s, import 646ms, tests 1.51s, environment 1ms) + diff --git a/artifacts/scale/pr/traffic-budgets.log b/artifacts/scale/pr/traffic-budgets.log new file mode 100644 index 00000000..2026fd77 --- /dev/null +++ b/artifacts/scale/pr/traffic-budgets.log @@ -0,0 +1,20 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/platform/traffic/request-budget.test.ts (7 tests) 5ms + โœ“ tests/platform/resilience/deadline.test.ts (3 tests) 5ms + โœ“ tests/platform/traffic/concurrency-budget.test.ts (6 tests) 10ms + โœ“ tests/platform/resilience/retry-budget.test.ts (6 tests) 5ms + โœ“ tests/platform/execution/execution-context.test.ts (10 tests) 9ms + โœ“ tests/platform/traffic/traffic-budget.test.ts (9 tests) 10ms + โœ“ tests/platform/traffic/operation-traffic-policy.test.ts (7 tests) 7ms + โœ“ tests/platform/traffic/request-fanout.test.ts (6 tests) 44ms + โœ“ tests/platform/traffic/request-deduplication.test.ts (3 tests) 40ms + โœ“ tests/platform/traffic/http-budget-integration.test.ts (9 tests) 127ms + โœ“ tests/platform/traffic/traffic-amplification.test.ts (3 tests) 328ms + + Test Files  11 passed (11) + Tests  69 passed (69) + Start at  13:30:20 + Duration  1.09s (transform 1.03s, setup 3.64s, import 1.52s, tests 590ms, environment 2ms) + diff --git a/artifacts/scale/release/architecture-topology.log b/artifacts/scale/release/architecture-topology.log new file mode 100644 index 00000000..30f4f1ab --- /dev/null +++ b/artifacts/scale/release/architecture-topology.log @@ -0,0 +1,25 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/platform/cardinality/compose-unique-record.test.ts (2 tests) 7ms + โœ“ tests/architecture/context-lazy-loading.test.ts (1 test) 7ms + โœ“ tests/platform/routing/context-route-module.test.ts (3 tests) 9ms + โœ“ tests/platform/cardinality/cardinality-budget.test.ts (3 tests) 6ms + โœ“ tests/architecture/module-hierarchy.test.ts (1 test) 6ms + โœ“ tests/architecture/topology-cardinality.test.ts (9 tests) 12ms + โœ“ tests/architecture/observability-boundaries.test.ts (4 tests) 101ms + โœ“ tests/architecture/request-fanout.test.ts (4 tests) 155ms + โœ“ tests/platform/cardinality/extreme-scale-registry.test.ts (3 tests) 1941ms + โœ“ keeps 10k -> 100k composition growth below a quadratic regression budget  383ms + โœ“ keeps one million lookups bounded on a 100k-entry runtime registry  1177ms + โœ“ selects and resolves 100k feature ids within the membership budget  379ms + โœ“ tests/architecture/app-build-input.test.ts (4 tests) 2191ms + โœ“ accepts the production generator's output and an app-local bundle  659ms + โœ“ rejects a generator regression that imports every discovered feature  635ms + โœ“ rejects a production bundle that contains another app's feature  660ms + + Test Files  10 passed (10) + Tests  34 passed (34) + Start at  13:33:08 + Duration  2.80s (transform 512ms, setup 3.13s, import 681ms, tests 4.43s, environment 2ms) + diff --git a/artifacts/scale/release/baseline-regression.log b/artifacts/scale/release/baseline-regression.log new file mode 100644 index 00000000..2de93de9 --- /dev/null +++ b/artifacts/scale/release/baseline-regression.log @@ -0,0 +1,3 @@ +compatibility: structural=true compiler=true timing=true +axes: absolute 28 (ok), growth 8 (ok), relative 16 compiler + 12 timing +scale baseline gate: PASSED (artifacts/scale/release/baseline-regression.json) diff --git a/artifacts/scale/release/composition-s0-s1.log b/artifacts/scale/release/composition-s0-s1.log new file mode 100644 index 00000000..edb0d391 --- /dev/null +++ b/artifacts/scale/release/composition-s0-s1.log @@ -0,0 +1,5 @@ +PASS registry-composition:growth (exponents 0.00) +PASS product-feature-selection:growth (exponents 0.00) +PASS product-feature-resolution:growth (exponents 0.00) +PASS context-hierarchy-composition:growth (exponents 0.00) +composition scale artifact: /shared/codebase/clean-architecture-frontend-template/artifacts/scale/release/composition-s0-s1.json diff --git a/artifacts/scale/release/composition-s0-s2.log b/artifacts/scale/release/composition-s0-s2.log new file mode 100644 index 00000000..c3156c6c --- /dev/null +++ b/artifacts/scale/release/composition-s0-s2.log @@ -0,0 +1,5 @@ +PASS registry-composition:growth (exponents 0.00, 0.65) +PASS product-feature-selection:growth (exponents 0.00, 0.90) +PASS product-feature-resolution:growth (exponents 0.00, 0.85) +PASS context-hierarchy-composition:growth (exponents 0.00, 0.44) +composition scale artifact: /shared/codebase/clean-architecture-frontend-template/artifacts/scale/release/composition-s0-s2.json diff --git a/artifacts/scale/release/composition-scale-suite.log b/artifacts/scale/release/composition-scale-suite.log new file mode 100644 index 00000000..d366d63e --- /dev/null +++ b/artifacts/scale/release/composition-scale-suite.log @@ -0,0 +1,11 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/scale/tsc-diagnostics-parser.test.ts (3 tests) 7ms + โœ“ tests/scale/composition-scale.test.ts (6 tests) 186ms + + Test Files  2 passed (2) + Tests  9 passed (9) + Start at  13:33:15 + Duration  494ms (transform 86ms, setup 297ms, import 80ms, tests 193ms, environment 0ms) + diff --git a/artifacts/scale/release/release-coherence.log b/artifacts/scale/release/release-coherence.log new file mode 100644 index 00000000..f348e9a1 --- /dev/null +++ b/artifacts/scale/release/release-coherence.log @@ -0,0 +1,15 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/platform/release/release-coherence.test.ts (10 tests) 8ms + โœ“ tests/platform/release/release-mismatch-recovery.test.ts (10 tests) 14ms + โœ“ tests/release/old-asset-reachability.test.ts (4 tests) 7ms + โœ“ tests/platform/release/cache-policy.test.ts (5 tests) 29ms + โœ“ tests/release/release-matrix.test.ts (7 tests) 39ms + โœ“ tests/release/mixed-replica.test.ts (7 tests) 67ms + + Test Files  6 passed (6) + Tests  43 passed (43) + Start at  13:33:06 + Duration  780ms (transform 1.11s, setup 1.22s, import 1.79s, tests 163ms, environment 1ms) + diff --git a/artifacts/scale/release/scale-units.log b/artifacts/scale/release/scale-units.log new file mode 100644 index 00000000..12c471b0 --- /dev/null +++ b/artifacts/scale/release/scale-units.log @@ -0,0 +1,17 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/scale/traffic/amplification-metrics.test.ts (6 tests) 6ms + โœ“ tests/scale/growth-regression.test.ts (7 tests) 9ms + โœ“ tests/scale/traffic/retry-after-jitter.test.ts (5 tests) 27ms + โœ“ tests/scale/benchmark.test.ts (4 tests) 11ms + โœ“ tests/scale/synthetic-topology.test.ts (8 tests) 13ms + โœ“ tests/scale/scale-baseline.test.ts (11 tests) 11ms + โœ“ tests/scale/traffic/failure-scenarios.test.ts (5 tests) 1362ms + โœ“ bounds physical requests when all upstream calls fail  874ms + + Test Files  7 passed (7) + Tests  46 passed (46) + Start at  13:33:12 + Duration  1.96s (transform 513ms, setup 1.59s, import 672ms, tests 1.44s, environment 1ms) + diff --git a/artifacts/scale/release/telemetry-storm.log b/artifacts/scale/release/telemetry-storm.log new file mode 100644 index 00000000..89083c98 --- /dev/null +++ b/artifacts/scale/release/telemetry-storm.log @@ -0,0 +1,12 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/scale/telemetry/telemetry-storm.test.ts (4 tests) 2705ms + โœ“ does not turn 100000 identical failures into 100000 sends  672ms + โœ“ bounds sends and buffer when a storm has many distinct fingerprints  1998ms + + Test Files  1 passed (1) + Tests  4 passed (4) + Start at  13:33:26 + Duration  3.01s (transform 58ms, setup 146ms, import 52ms, tests 2.71s, environment 0ms) + diff --git a/artifacts/scale/release/topology-s3-s4.log b/artifacts/scale/release/topology-s3-s4.log new file mode 100644 index 00000000..2ada7f2a --- /dev/null +++ b/artifacts/scale/release/topology-s3-s4.log @@ -0,0 +1,12 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/scale/global-local-independence.test.ts (7 tests) 6484ms + โœ“ keeps App A's generated indexes and reachable source graph identical from S0 to S2 on disk  4707ms + โœ“ selects another app from the same repository without App A's features  646ms + + Test Files  1 passed (1) + Tests  7 passed (7) + Start at  13:33:19 + Duration  6.79s (transform 53ms, setup 145ms, import 49ms, tests 6.48s, environment 0ms) + diff --git a/artifacts/scale/release/traffic-budgets.log b/artifacts/scale/release/traffic-budgets.log new file mode 100644 index 00000000..31abbdee --- /dev/null +++ b/artifacts/scale/release/traffic-budgets.log @@ -0,0 +1,20 @@ + + RUN  v4.1.10 /shared/codebase/clean-architecture-frontend-template + + โœ“ tests/platform/traffic/request-budget.test.ts (7 tests) 5ms + โœ“ tests/platform/traffic/concurrency-budget.test.ts (6 tests) 10ms + โœ“ tests/platform/resilience/retry-budget.test.ts (6 tests) 5ms + โœ“ tests/platform/resilience/deadline.test.ts (3 tests) 6ms + โœ“ tests/platform/traffic/traffic-budget.test.ts (9 tests) 9ms + โœ“ tests/platform/execution/execution-context.test.ts (10 tests) 13ms + โœ“ tests/platform/traffic/operation-traffic-policy.test.ts (7 tests) 7ms + โœ“ tests/platform/traffic/request-fanout.test.ts (6 tests) 47ms + โœ“ tests/platform/traffic/request-deduplication.test.ts (3 tests) 50ms + โœ“ tests/platform/traffic/http-budget-integration.test.ts (9 tests) 121ms + โœ“ tests/platform/traffic/traffic-amplification.test.ts (3 tests) 331ms + + Test Files  11 passed (11) + Tests  69 passed (69) + Start at  13:33:11 + Duration  1.08s (transform 940ms, setup 3.62s, import 1.46s, tests 603ms, environment 2ms) + diff --git a/artifacts/scale/release/typescript-diagnostics.log b/artifacts/scale/release/typescript-diagnostics.log new file mode 100644 index 00000000..a9e02468 --- /dev/null +++ b/artifacts/scale/release/typescript-diagnostics.log @@ -0,0 +1,5 @@ +tsc app: files=827 types=279186 instantiations=700415 +PASS tsc:types (exponents 0.84, 0.96) +PASS tsc:symbols (exponents 0.51, 0.80) +PASS tsc:instantiations (exponents 0.97, 0.99) +tsc diagnostics artifact: /shared/codebase/clean-architecture-frontend-template/artifacts/scale/release/typescript-diagnostics.json diff --git a/config/contracts/registry-change-evidence.json b/config/contracts/registry-change-evidence.json index b039daae..0329c0a2 100644 --- a/config/contracts/registry-change-evidence.json +++ b/config/contracts/registry-change-evidence.json @@ -96,6 +96,14 @@ "compatibilityWindow": "Existing valid envelopes continue to decode; invalid values fail closed.", "rollback": "Remove the required codec field and runtime codec dispatch together.", "owner": "frontend-platform" + }, + { + "changeId": "FE-REG-ERROR:QUERY_CACHE_FAILURE:telemetryEvent:field-changed", + "versionBump": "Error taxonomy observability references became the closed union of registered diagnostic and telemetry event ids (extreme-scale Phase 4 ledger, 2026-09-23).", + "migration": "QUERY_CACHE_FAILURE pointed at the unregistered event id query.cache.failed; it now references the registered cache.operation.failed diagnostic event that the query cache adapter actually emits.", + "compatibilityWindow": "No wire, storage or runtime-config format changes: the old id was never emitted by any producer, so no consumer could observe it.", + "rollback": "Restore the previous telemetryEvent string on QUERY_CACHE_FAILURE in src/contracts/errors.ts and widen ErrorObservationEvent back to string.", + "owner": "frontend-platform" } ] } diff --git a/config/scale/benchmark-baseline.json b/config/scale/benchmark-baseline.json new file mode 100644 index 00000000..643bd334 --- /dev/null +++ b/config/scale/benchmark-baseline.json @@ -0,0 +1,135 @@ +{ + "schemaVersion": 1, + "environment": { + "nodeMajor": 24, + "platform": "linux", + "arch": "x64", + "cpuModel": "Intel(R) Core(TM) i5-10400F CPU @ 2.90GHz", + "cpuCount": 12, + "typescript": "7.0.2" + }, + "metrics": { + "timing": [ + { + "workload": "context-hierarchy-composition", + "profile": "S0", + "cardinality": 100, + "medianMs": 0.025, + "minMs": 0.022 + }, + { + "workload": "context-hierarchy-composition", + "profile": "S1", + "cardinality": 1000, + "medianMs": 0.115, + "minMs": 0.111 + }, + { + "workload": "context-hierarchy-composition", + "profile": "S2", + "cardinality": 10000, + "medianMs": 1.208, + "minMs": 1.086 + }, + { + "workload": "product-feature-resolution", + "profile": "S0", + "cardinality": 100, + "medianMs": 0.028, + "minMs": 0.02 + }, + { + "workload": "product-feature-resolution", + "profile": "S1", + "cardinality": 1000, + "medianMs": 0.177, + "minMs": 0.173 + }, + { + "workload": "product-feature-resolution", + "profile": "S2", + "cardinality": 10000, + "medianMs": 3.404, + "minMs": 3.316 + }, + { + "workload": "product-feature-selection", + "profile": "S0", + "cardinality": 100, + "medianMs": 0.045, + "minMs": 0.043 + }, + { + "workload": "product-feature-selection", + "profile": "S1", + "cardinality": 1000, + "medianMs": 0.261, + "minMs": 0.246 + }, + { + "workload": "product-feature-selection", + "profile": "S2", + "cardinality": 10000, + "medianMs": 3.149, + "minMs": 3.042 + }, + { + "workload": "registry-composition", + "profile": "S0", + "cardinality": 100, + "medianMs": 0.046, + "minMs": 0.043 + }, + { + "workload": "registry-composition", + "profile": "S1", + "cardinality": 1000, + "medianMs": 0.269, + "minMs": 0.244 + }, + { + "workload": "registry-composition", + "profile": "S2", + "cardinality": 10000, + "medianMs": 2.634, + "minMs": 2.209 + } + ], + "compiler": [ + { + "fixture": "app", + "files": 824, + "types": 278300, + "symbols": 794961, + "instantiations": 699730 + }, + { + "fixture": "local-100", + "files": 158, + "types": 6413, + "symbols": 20267, + "instantiations": 8573 + }, + { + "fixture": "local-25", + "files": 83, + "types": 1995, + "symbols": 9978, + "instantiations": 2222 + }, + { + "fixture": "local-400", + "files": 458, + "types": 24113, + "symbols": 61442, + "instantiations": 33998 + } + ] + }, + "approval": { + "owner": "frontend-platform", + "reason": "Initial extreme-scale benchmark baseline (composition S0-S2, tsc app + local 25/100/400), 2026-09-23", + "approvedAt": "2026-09-23T10:44:14.787Z", + "metricsDigest": "97bcf7620a1fac46a44fcd4e7f611c05fc2024ed023454ef4fc340c44912bda1" + } +} diff --git a/docs/reviews/2026-09-23-domain-scale-horizontal-scaling-review.md b/docs/reviews/2026-09-23-domain-scale-horizontal-scaling-review.md new file mode 100644 index 00000000..0354f928 --- /dev/null +++ b/docs/reviews/2026-09-23-domain-scale-horizontal-scaling-review.md @@ -0,0 +1,454 @@ +# Clean Architecture Frontend Template โ€” Domain Scale / High Traffic / Horizontal Scaling Review + +- Review date: 2026-09-23 +- Repository: `/shared/codebase/clean-architecture-frontend-template` +- Review baseline: `origin/main` `ebea300` (`2026-09-20 13:47:27 +0900`) +- Source modification: ์—†์Œ +- Scope: ๋Œ€์šฉ๋Ÿ‰ ํŠธ๋ž˜ํ”ฝ, feature/domain 100โ†’1,000โ†’10,000 ํ™•์žฅ, ๋ฌธ์ œ ์ธ์‹์ด ์ฝ”๋“œ์— ๋“œ๋Ÿฌ๋‚˜๋Š” ๊ตฌ์กฐ, ํด๋ผ์šฐ๋“œ ์ˆ˜ํ‰ ํ™•์žฅ + +## 0. Baseline ์ฃผ์˜์‚ฌํ•ญ + +ํ˜„์žฌ ๋กœ์ปฌ `main`์€ `91ae42a` Initial commit์— ๋จธ๋ฌผ๋Ÿฌ ์žˆ๊ณ  `origin/main`๋ณด๋‹ค 235 commit ๋’ค์— ์žˆ๋‹ค. ํ˜„์žฌ working tree์˜ `src/`, `tests/`, `dist/`, `artifacts/` ๋“ฑ์€ untracked ์ƒํƒœ์ด๋ฏ€๋กœ ๊ทธ ์ƒํƒœ๋ฅผ ์ตœ์‹  ํ…œํ”Œ๋ฆฟ์œผ๋กœ ๊ฐ„์ฃผํ•˜๋ฉด ์ž˜๋ชป๋œ ๋ฆฌ๋ทฐ๊ฐ€ ๋œ๋‹ค. + +๋”ฐ๋ผ์„œ ์ด๋ฒˆ ๊ฒ€ํ† ๋Š” working tree๋ฅผ ๋ณ€๊ฒฝํ•˜์ง€ ์•Š๊ณ  `origin/main`์„ `/tmp/clean-architecture-frontend-template-review-20260923`์— ๋ณ„๋„ archive๋กœ ์ „๊ฐœํ•œ ๋’ค ์ˆ˜ํ–‰ํ–ˆ๋‹ค. `git fetch origin --prune`์œผ๋กœ ํ™•์ธํ–ˆ์„ ๋•Œ `origin/main`์€ `ebea300`์œผ๋กœ ๋™์ผํ–ˆ๋‹ค. + +## 1. ๊ฒฐ๋ก  + +ํ˜„์žฌ ๊ตฌ์กฐ๋Š” **ํด๋ฆฐ ์•„ํ‚คํ…์ฒ˜ ๊ฒฝ๊ณ„, ๋ธŒ๋ผ์šฐ์ € ์ƒํƒœ ๊ฒฉ๋ฆฌ, HTTP ์‹คํŒจ/์žฌ์‹œ๋„ ์ •์ฑ…, ๋ฐฐํฌ release coherence**๋Š” ์ƒ๋‹นํžˆ ๊ฐ•ํ•˜๋‹ค. ํŠนํžˆ ๋‹ค์Œ์€ ์ข‹์€ ๋ฐฉํ–ฅ์ด๋‹ค. + +- feature ๋‚ด๋ถ€๋ฅผ `domain / application / adapters / presentation / contracts`๋กœ ๋ถ„๋ฆฌํ•œ๋‹ค. +- application input์€ module augmentation์œผ๋กœ feature๊ฐ€ ์ž๊ธฐ ๊ณ„์•ฝ์„ ๋“ฑ๋กํ•œ๋‹ค. +- presentation์ด ์ง์ ‘ `fetch`, storage, concrete adapter๋ฅผ ์‚ฌ์šฉํ•˜์ง€ ๋ชปํ•˜๊ฒŒ lint/architecture rule์„ ๋‘”๋‹ค. +- Query ๊ธฐ๋ณธ retry๋ฅผ ๋„๊ณ  HTTP retry๋ฅผ idempotency/replay semantics์™€ full jitter๋กœ ์ œํ•œํ•œ๋‹ค. +- API response์™€ boot JSON์˜ ํฌ๊ธฐ/deadline์„ bounded contract๋กœ ํ‘œํ˜„ํ•œ๋‹ค. +- route owner, query invalidation topic/namespace/edge, schema/mapper owner๊ฐ€ ์ฝ”๋“œ์— ๋“œ๋Ÿฌ๋‚œ๋‹ค. +- static hosting์€ immutable asset + no-store config/manifest + release/build identity validation์„ ์‚ฌ์šฉํ•œ๋‹ค. + +๊ทธ๋Ÿฌ๋‚˜ **100โ†’1,000โ†’10,000 feature/domain ํ™•์žฅ์„ฑ** ๊ธฐ์ค€์œผ๋กœ๋Š” ํ˜„์žฌ ๊ทธ๋Œ€๋กœ ๋๋‚œ ๊ตฌ์กฐ๊ฐ€ ์•„๋‹ˆ๋‹ค. + +ํ•ต์‹ฌ ๋ฌธ์ œ๋Š” ๋‹ค์Œ ๋„ค ๊ฐ€์ง€๋‹ค. + +1. feature ์„ค์น˜๋ฅผ ์œ„ํ•ด ์—ฌ๋Ÿฌ ์ค‘์•™ ํŒŒ์ผ์„ ์ˆ˜์ •ํ•ด์•ผ ํ•œ๋‹ค. +2. feature ๊ฐ„ ์ง์ ‘ ์˜์กด์„ ์›์ฒœ์ ์œผ๋กœ ๋ง‰๋Š” ๊ทœ์น™์ด ์—†๋‹ค. +3. ์ผ๋ถ€ registry/product composition์ด O(Nยฒ)์ด๋‹ค. +4. ๋ชจ๋“  feature contract/route metadata๊ฐ€ ํ•˜๋‚˜์˜ ์ •์  TypeScript/SPA graph์— ๋“ค์–ด๊ฐ„๋‹ค. + +๋”ฐ๋ผ์„œ ํ˜„์žฌ ๊ตฌ์กฐ๋Š” **100๊ฐœ ์ •๋„์˜ bounded feature๊นŒ์ง€๋Š” ๊ฐœ์„ ์„ ์ „์ œ๋กœ ์œ ์ง€ ๊ฐ€๋Šฅ**, **1,000๊ฐœ๋ถ€ํ„ฐ๋Š” ์ค‘์•™ composition ๊ตฌ์กฐ๋ฅผ ๋ฐ”๊พธ์ง€ ์•Š์œผ๋ฉด ์œ ์ง€๋ณด์ˆ˜์™€ startup/build cost๊ฐ€ ๋ฌธ์ œ**, **10,000๊ฐœ๋ฅผ ํ•œ SPA์˜ flat registry๋กœ ์ˆ˜์šฉํ•˜๋Š” ๋ชจ๋ธ์€ ์ ํ•ฉํ•˜์ง€ ์•Š๋‹ค**๊ณ  ํŒ๋‹จํ•œ๋‹ค. + +## 2. ์ข‹์€ ์  โ€” ๋ฌธ์ œ๊ฐ€ ์ฝ”๋“œ์—์„œ ๋“œ๋Ÿฌ๋‚˜๋Š” ๋ถ€๋ถ„ + +### 2.1 Feature capability๊ฐ€ compile-time dependency๋กœ ๋“œ๋Ÿฌ๋‚œ๋‹ค + +`ApplicationFeatureInputs`์™€ `FeatureIndexedDbRepositories`๋Š” ๋นˆ interface๋ฅผ ๋‘๊ณ  feature๊ฐ€ module augmentation์œผ๋กœ ์ž๊ธฐ input/repository๋ฅผ ๋“ฑ๋กํ•œ๋‹ค. + +์ด ๋ฐฉ์‹์˜ ์žฅ์ ์€ ์ƒˆ๋กœ์šด feature๊ฐ€ `indexedDb` ๊ฐ™์€ capability๋ฅผ ์š”๊ตฌํ•˜๋ฉด composition root๊ฐ€ ๊ทธ๊ฒƒ์„ ๊ณต๊ธ‰ํ•˜์ง€ ์•Š๋Š” ํ•œ ํƒ€์ž… ์ˆ˜์ค€์—์„œ ๋‹ซํžˆ์ง€ ์•Š๋Š”๋‹ค๋Š” ์ ์ด๋‹ค. + +์˜ˆ๋ฅผ ๋“ค์–ด `local-draft-feature`๋Š” `needs: ["indexedDb"]`๋ฅผ ์„ ์–ธํ•œ๋‹ค. ํ˜„์žฌ production adapter catalog์—๋Š” reference feature๋งŒ ์„ค์น˜๋˜์–ด ์žˆ์–ด `createRuntimeAdapters()`๋Š” `{ http: contractOperations }`๋งŒ ๊ณต๊ธ‰ํ•œ๋‹ค. ํ–ฅํ›„ local draft๋ฅผ ์‹ค์ œ catalog์— ๋„ฃ์œผ๋ฉด `indexedDb` capability wiring์ด ๋น ์กŒ๋‹ค๋Š” ์‚ฌ์‹ค์ด composition boundary์—์„œ ๋“œ๋Ÿฌ๋‚˜๊ฒŒ ๋œ๋‹ค. + +์ด๋Š” ์„œ๋ฒ„์—์„œ ์—ฐ๊ด€๊ด€๊ณ„ ๋น„์šฉ์„ ์ˆจ๊ธฐ์ง€ ์•Š๋Š” ๊ฒƒ๊ณผ ์œ ์‚ฌํ•˜๊ฒŒ, **feature๊ฐ€ ์–ด๋–ค ์ธํ”„๋ผ capability๋ฅผ ์š”๊ตฌํ•˜๋Š”์ง€ ์ฝ”๋“œ์—์„œ ์ˆจ๊ธธ ์ˆ˜ ์—†๊ฒŒ ํ•œ๋‹ค**๋Š” ์ ์—์„œ ์ข‹๋‹ค. + +### 2.2 Network fan-out์˜ ์ผ๋ถ€ ์œ„ํ—˜์ด contract์— ์˜ฌ๋ผ์™€ ์žˆ๋‹ค + +HTTP operation์—๋Š” ๋‹ค์Œ์ด ๋ช…์‹œ๋ผ ์žˆ๋‹ค. + +- idempotency / replay policy +- retry policy +- deadline ceiling +- request/response schema +- success status +- response media type +- `maxResponseBytes` +- mapper์™€ `maxOutputItems` + +์ฆ‰ "๊ทธ๋ƒฅ fetchํ•œ๋‹ค"๊ฐ€ ์•„๋‹ˆ๋ผ ๋„คํŠธ์›Œํฌ ์š”์ฒญ์˜ ๋น„์šฉ๊ณผ ์‹คํŒจ ์˜๋ฏธ๊ฐ€ operation contract์— ์˜ฌ๋ผ์™€ ์žˆ๋‹ค. + +๋˜ QueryClient ๊ธฐ๋ณธ๊ฐ’์€ `retry: false`, mutation๋„ `retry: false`์ด๊ณ  HTTP ๊ณ„์ธต์—์„œ๋งŒ retry authority๋ฅผ ๊ฐ€์ง„๋‹ค. HTTP retry๋Š” safe/idempotent semantics, bounded attempt, exponential full jitter, Retry-After ceiling์„ ์‚ฌ์šฉํ•œ๋‹ค. ์žฅ์•  ์‹œ ๋ธŒ๋ผ์šฐ์ € ์ „์ฒด๊ฐ€ ๋ฌด์ œํ•œ ์žฌ์‹œ๋„๋กœ ์„œ๋ฒ„๋ฅผ ๋” ์••๋ฐ•ํ•˜๋Š” ๊ตฌ์กฐ๋ฅผ ํ”ผํ•˜๊ณ  ์žˆ๋‹ค. + +### 2.3 Browser-local state์™€ hosting instance state๊ฐ€ ๋ถ„๋ฆฌ๋ผ ์žˆ๋‹ค + +TanStack Query client, generation store, session integration, local/session storage, cross-context invalidation์€ ๋ธŒ๋ผ์šฐ์ € runtime์—์„œ ์ƒ์„ฑ๋œ๋‹ค. frontend hosting instance ๋ฉ”๋ชจ๋ฆฌ์— ์‚ฌ์šฉ์ž session/cache๋ฅผ ์ €์žฅํ•˜๋Š” ๊ตฌ์กฐ๊ฐ€ ์•„๋‹ˆ๋‹ค. + +๋”ฐ๋ผ์„œ **๋™์ผํ•œ release artifact๋ฅผ ์ œ๊ณตํ•˜๋Š” stateless web origin replica๋ฅผ ๋Š˜๋ฆฌ๋Š” ๊ฒƒ ์ž์ฒด๋Š” application correctness๋ฅผ ๊นจ์ง€ ์•Š๋Š”๋‹ค.** + +### 2.4 Release coherence๊ฐ€ ์ฝ”๋“œ์™€ ์šด์˜ ๊ณ„์•ฝ ์–‘์ชฝ์— ์žˆ๋‹ค + +๋ฐฐํฌ ๊ณ„์•ฝ์€ ๋‹ค์Œ์„ ๊ฐ•์ œํ•œ๋‹ค. + +- hashed assets: `public, max-age=31536000, immutable` +- HTML: `no-cache` +- runtime config / release manifest: `no-store` +- runtime config์˜ build id ๊ฒ€์ฆ +- release manifest์˜ build/config/release/contract identity ๊ฒ€์ฆ +- immutable `releases//` tuple ์ƒ์„ฑ ํ›„ active pointer ์ „ํ™˜ + +๋”ฐ๋ผ์„œ replica A์™€ B๊ฐ€ ์„œ๋กœ ๋‹ค๋ฅธ ์ž์‚ฐ์„ ์ œ๋ฉ‹๋Œ€๋กœ ์„ž์–ด ์ œ๊ณตํ•˜๋Š” ์ƒํ™ฉ์„ ๋‹จ์ˆœํ•œ "๋ฐฐํฌ ๋ฌธ์ œ"๋กœ ๋ฐฉ์น˜ํ•˜์ง€ ์•Š๊ณ  boot failure๋กœ ๋“œ๋Ÿฌ๋‚ผ ๊ธฐ๋ฐ˜์ด ์žˆ๋‹ค. + +## 3. P0 โ€” Registry composition ์ผ๋ถ€๊ฐ€ O(Nยฒ)์ด๋‹ค + +### 3.1 `installed-feature-contracts.ts` route composition + +ํ˜„์žฌ ํŒจํ„ด: + +```ts +INSTALLED_FEATURE_CONTRACTS.reduce( + (registry, contract) => ({ ...registry, ...contract.routes }), + { ...PLATFORM_ROUTE_REGISTRY }, +) +``` + +๋งค iteration๋งˆ๋‹ค ์ด์ „ registry ์ „์ฒด๋ฅผ ๋‹ค์‹œ copyํ•œ๋‹ค. feature ์ˆ˜์™€ route ์ˆ˜๊ฐ€ ๋Š˜์–ด๋‚ ์ˆ˜๋ก ๋ˆ„์  copy๊ฐ€ ์ปค์ง„๋‹ค. + +ํ•ฉ์„ฑ benchmark๋Š” feature๋งˆ๋‹ค route 1๊ฐœ์ธ ์ตœ์†Œ ์กฐ๊ฑด์œผ๋กœ ์ธก์ •ํ–ˆ๋‹ค. + +| feature ์ˆ˜ | ํ˜„์žฌ route spread reduce | ์„ ํ˜• Object.assign ์กฐํ•ฉ | +|---:|---:|---:| +| 100 | 0.46 ms | 0.06 ms | +| 1,000 | 92.94 ms | 0.24 ms | +| 5,000 | 3,769.40 ms | 0.54 ms | +| 10,000 | 16,527.58 ms | 1.20 ms | + +์ด benchmark๋Š” Node 22์—์„œ ์ˆ˜ํ–‰ํ•œ synthetic microbenchmark์ด๋ฉฐ ์‹ค์ œ browser boot time ๊ทธ ์ž์ฒด๋Š” ์•„๋‹ˆ๋‹ค. ๊ทธ๋Ÿฌ๋‚˜ ์ฆ๊ฐ€ ํ˜•ํƒœ๊ฐ€ O(Nยฒ)์ธ์ง€ ํ™•์ธํ•˜๊ธฐ์—๋Š” ์ถฉ๋ถ„ํ•˜๋‹ค. + +**๊ฐœ์„ :** mutable local accumulator์— ์ค‘๋ณต ๊ฒ€์ฆ์„ ํ•˜๋ฉด์„œ ํ•œ ๋ฒˆ๋งŒ assignํ•œ ๋’ค ๋งˆ์ง€๋ง‰์— freezeํ•œ๋‹ค. Schema/API/mapper registry๊ฐ€ ์ด๋ฏธ ์ด ๋ฐฉ์‹์— ๊ฐ€๊น๋‹ค. + +### 3.2 `product-features.ts`์˜ ๋ฐ˜๋ณต `includes()` + +๋‹ค์Œ ๋กœ์ง๋„ ํฐ N์—์„œ O(Nยฒ)์ด๋‹ค. + +- requested feature ๊ฒ€์ฆ: `compiledIds.includes(id)` +- selection: `requested.includes(feature.featureId)` +- status resolve: `installedIds.includes(featureId)` + +10,000 feature synthetic ๊ฒฐ๊ณผ: + +- selection: ์•ฝ 441.87 ms +- status resolve: ์•ฝ 218.93 ms +- `Set` ๊ธฐ๋ฐ˜ status resolve: ์•ฝ 1.68 ms + +**๊ฐœ์„ :** membership query๋Š” composition ์‹œ์ž‘ ์‹œ `Set`์œผ๋กœ ๋ณ€ํ™˜ํ•œ๋‹ค. + +### 3.3 runtime/contract contribution filter๋„ ๋™์ผํ•˜๋‹ค + +`installed-feature-runtimes.tsx`, `installed-contract-contributions.ts`๊ฐ€ `INSTALLED_PRODUCT_FEATURE_IDS.includes(...)`๋กœ filterํ•œ๋‹ค. + +10,000 feature synthetic filter๋Š” ์•ฝ 122.58 ms์˜€๋‹ค. ์ด๊ฒƒ ์—ญ์‹œ `Set`์œผ๋กœ ๋ฐ”๊พธ๋ฉด ์„ ํ˜•ํ™”ํ•  ์ˆ˜ ์žˆ๋‹ค. + +## 4. P0 โ€” Feature ํ•˜๋‚˜ ์ถ”๊ฐ€ํ•  ๋•Œ ์ค‘์•™ ํŒŒ์ผ์ด ๋„ˆ๋ฌด ๋งŽ์ด ๋ฐ”๋€๋‹ค + +ํ˜„์žฌ `reference-feature`๋Š” feature directory ๋ฐ–์—์„œ ๋‹ค์Œ ์ค‘์•™ ํŒŒ์ผ์— ์ง์ ‘ import๋œ๋‹ค. + +1. `installed-product-manifest.ts` +2. `installed-feature-adapters.ts` +3. `installed-feature-runtimes.tsx` +4. `installed-feature-messages.ts` +5. `installed-contract-contributions.ts` + +`installed-feature-contracts.ts`๋Š” product manifest์—์„œ ํŒŒ์ƒ๋˜๋ฏ€๋กœ ๊ฐœ์„ ๋์ง€๋งŒ, feature ์„ค์น˜๋ฅผ "ํ•œ ๋ฒˆ ์„ ์–ธ"ํ•˜๋Š” ์ƒํƒœ๊นŒ์ง€๋Š” ์•„๋‹ˆ๋‹ค. + +`test-sample-removal.ts`๋„ reference feature๋ฅผ ์ œ๊ฑฐํ•˜๋Š” fixture๋ฅผ ๋งŒ๋“ค ๋•Œ ์œ„ ์ค‘์•™ ํŒŒ์ผ๋“ค์„ ๊ฐ๊ฐ empty variant๋กœ ๊ต์ฒดํ•œ๋‹ค. ์ฆ‰ ํ…Œ์ŠคํŠธ ์ž์ฒด๊ฐ€ ํ˜„์žฌ์˜ multi-touch installation cost๋ฅผ ์ฆ๋ช…ํ•œ๋‹ค. + +feature 10๊ฐœ์—์„œ๋Š” ๋ฌธ์ œ๊ฐ€ ์ž‘๋‹ค. 100๊ฐœ๋ถ€ํ„ฐ๋Š” merge hotspot์ด ๋˜๊ณ , 1,000๊ฐœ์—์„œ๋Š” ์‚ฌ๋žŒ์ด central catalog๋ฅผ ์ง์ ‘ ์œ ์ง€ํ•˜๋Š” ๋ฐฉ์‹์ด ์‹ค์งˆ์ ์œผ๋กœ ์œ ์ง€ ๋ถˆ๊ฐ€๋Šฅํ•ด์ง„๋‹ค. + +**๊ฐœ์„  ๋ฐฉํ–ฅ:** feature ํ•˜๋‚˜๊ฐ€ ํ•˜๋‚˜์˜ `FeatureModuleDescriptor`๋ฅผ ์†Œ์œ ํ•˜๊ฒŒ ํ•œ๋‹ค. + +์˜ˆ: + +```ts +export const FEATURE = defineFeatureModule({ + id, + contracts, + adapterContribution, + runtimeContribution, + messages, + contractContributions, +}); +``` + +๊ทธ๋ฆฌ๊ณ  ์ค‘์•™ catalog๋Š” ์‚ฌ๋žŒ์ด 5๊ณณ์„ ํŽธ์ง‘ํ•˜๋Š” ๋ฐฉ์‹์ด ์•„๋‹ˆ๋ผ **build-time generated static index** ํ•˜๋‚˜๋กœ ๋งŒ๋“ ๋‹ค. + +์ค‘์š”ํ•œ ์ ์€ runtime string์œผ๋กœ ์ž„์˜ `import()` ํ•˜๋Š” plugin system์„ ๋งŒ๋“ค์ž๋Š” ๋œป์ด ์•„๋‹ˆ๋‹ค. ํ˜„์žฌ ๋ณด์•ˆ/๊ณต๊ธ‰๋ง ์ฒ ํ•™์„ ์œ ์ง€ํ•˜๋ฉด์„œ build ๋‹จ๊ณ„์—์„œ ๋ช…์‹œ์ ์ธ static module map์„ ์ƒ์„ฑํ•˜๋ฉด ๋œ๋‹ค. + +## 5. P0 โ€” Cross-feature dependency๊ฐ€ ๊ธฐ๋ณธ ๊ธˆ์ง€๋˜์–ด ์žˆ์ง€ ์•Š๋‹ค + +ํ˜„์žฌ architecture rules๋Š” ๊ฐ feature ๋‚ด๋ถ€์˜ layer ๋ฐฉํ–ฅ์€ ์ž˜ ๋ง‰๋Š”๋‹ค. + +์˜ˆ: + +- feature domain โ†’ application/adapters/presentation ๊ธˆ์ง€ +- feature application โ†’ adapters/presentation ๊ธˆ์ง€ +- feature presentation โ†’ concrete adapter ๊ธˆ์ง€ +- feature adapters โ†’ presentation ๊ธˆ์ง€ + +ํ•˜์ง€๋งŒ **feature A โ†’ feature B ์ž์ฒด๋ฅผ ๊ธˆ์ง€ํ•˜๋Š” ์ผ๋ฐ˜ ๊ทœ์น™์€ ์—†๋‹ค.** + +๋”ฐ๋ผ์„œ ์˜ˆ๋ฅผ ๋“ค์–ด: + +```text +features/order/application + -> features/member/application + -> features/payment/domain +``` + +๊ฐ™์€ concrete cross-feature edge๊ฐ€ ์ƒ๊ฒจ๋„ layer rule๋งŒ ๋งŒ์กฑํ•˜๋ฉด ํ†ต๊ณผํ•  ์—ฌ์ง€๊ฐ€ ์žˆ๋‹ค. + +์ด๊ฒŒ ์„œ๋ฒ„์˜ `OneToMany` ๋น„์œ ์™€ ๊ฐ€์žฅ ๊ฐ€๊นŒ์šด ํ•ต์‹ฌ ๋ฌธ์ œ๋‹ค. feature ์ˆ˜๊ฐ€ ์ปค์งˆ ๋•Œ ์ง„์งœ ์œ„ํ—˜ํ•œ ๊ฒƒ์€ ํŒŒ์ผ ์ˆ˜ ์ž์ฒด๊ฐ€ ์•„๋‹ˆ๋ผ **feature fan-out์ด ์ฝ”๋“œ ์–ด๋””์„œ๋“  ์กฐ์šฉํžˆ ์ฆ๊ฐ€ํ•˜๋Š” ๊ฒƒ**์ด๋‹ค. + +**๊ถŒ์žฅ invariant:** + +```text +src/features/A/** -> src/features/B/** ๊ธฐ๋ณธ ๊ธˆ์ง€ (A != B) +``` + +๊ณต์œ ๊ฐ€ ํ•„์š”ํ•˜๋ฉด ๋‹ค์Œ ์ค‘ ํ•˜๋‚˜๋กœ ๋ฌธ์ œ๋ฅผ ๋ช…์‹œ์ ์œผ๋กœ ์Šน๊ฒฉํ•œ๋‹ค. + +- `src/contracts`์˜ stable contract +- `src/application/ports`์˜ platform/application capability +- ๋ณ„๋„ orchestration/workflow feature +- ๋ช…์‹œ์  public facade package + +์ฆ‰ cross-domain ์˜์กด์ด ํ•„์š”ํ•  ๋•Œ ๊ฐœ๋ฐœ์ž๊ฐ€ "๊ทธ๋ƒฅ import"๋กœ ํ•ด๊ฒฐํ•˜์ง€ ๋ชปํ•˜๊ฒŒ ํ•ด์•ผ ํ•œ๋‹ค. ์ด๊ฒƒ์ด ์ฝ”๋“œ์—์„œ ๋ฌธ์ œ๋ฅผ ์กฐ๊ธฐ์— ์ธ์‹ํ•˜๊ฒŒ ๋งŒ๋“œ๋Š” frontend ์ชฝ ํ•ต์‹ฌ ์žฅ์น˜๋‹ค. + +## 6. P1 โ€” Build-time feature selection์ด bundle graph๋ฅผ ์ค„์ด์ง€ ์•Š๋Š”๋‹ค + +`installed-product-manifest.ts` ์ฃผ์„๋„ ์ด๋ฏธ ์ด๋ฅผ ๋ช…ํ™•ํžˆ ์ ๊ณ  ์žˆ๋‹ค. + +`VITE_PRODUCT_FEATURES`๋Š” installed registry์—์„œ๋Š” feature๋ฅผ ์ œ์™ธํ•˜์ง€๋งŒ static import ์ž์ฒด๋Š” ์ œ๊ฑฐํ•˜์ง€ ์•Š๋Š”๋‹ค. + +๋”ฐ๋ผ์„œ feature๊ฐ€ 1,000/10,000๊ฐœ๊นŒ์ง€ ๋Š˜๋ฉด "๋น„ํ™œ์„ฑ feature๋Š” runtime์—์„œ ์•ˆ ์“ฐ๋‹ˆ๊นŒ ๊ดœ์ฐฎ๋‹ค"๊ณ  ๋ณผ ์ˆ˜ ์—†๋‹ค. TypeScript compiler, Vite/Rollup graph, registry metadata, schema/codec import๊ฐ€ ์˜ํ–ฅ์„ ๋ฐ›๋Š”๋‹ค. + +ํŽ˜์ด์ง€ component๋Š” `React.lazy()`๋กœ route chunk ๋ถ„๋ฆฌ๊ฐ€ ๋˜์–ด ์žˆ์–ด ์ข‹์€ ํŽธ์ด๋‹ค. ๊ทธ๋Ÿฌ๋‚˜ feature contract/runtime contribution์˜ ์ƒ์œ„ graph๋Š” ์—ฌ์ „ํžˆ ์ •์ ์ด๋‹ค. + +**๊ฐœ์„ :** product๋ณ„ build input์—์„œ ํ•„์š”ํ•œ feature set๋งŒ ๋Œ€์ƒ์œผ๋กœ static index๋ฅผ ์ƒ์„ฑํ•œ๋‹ค. ๋ชจ๋“  ์ œํ’ˆ์ด ๋ชจ๋“  domain source๋ฅผ compiler graph์— ๋ฐ˜๋“œ์‹œ ๋„ฃ์–ด์•ผ ํ•˜๋Š” ๊ตฌ์กฐ๋ฅผ ํ”ผํ•œ๋‹ค. + +## 7. P1 โ€” 10,000 route๋ฅผ flat router์— ํ•œ ๋ฒˆ์— ๋„ฃ๋Š” ๋ชจ๋ธ์€ ๋ถ€์ ์ ˆํ•˜๋‹ค + +`AppRouter`๋Š” boot ์‹œ: + +```ts +Object.values(ROUTE_REGISTRY).map(...) +``` + +์œผ๋กœ ๋ชจ๋“  route์— ๋Œ€ํ•œ `RouteObject`๋ฅผ ์ƒ์„ฑํ•œ๋‹ค. + +์„ ํ˜•์ด๋ผ๋„ 10,000 route๊ฐ€ ํ•˜๋‚˜์˜ browser application์— ๋™์‹œ์— ์กด์žฌํ•ด์•ผ ํ•˜๋Š” ์ด์œ ๋ถ€ํ„ฐ ๋‹ค์‹œ ๊ฒ€ํ† ํ•ด์•ผ ํ•œ๋‹ค. + +๋Œ€๊ทœ๋ชจ์—์„œ๋Š” ๋‹ค์Œ ๊ณ„์ธต์ด ์ ํ•ฉํ•˜๋‹ค. + +```text +Product Router + -> Bounded Context / Domain Router + -> Feature Router + -> Page Route +``` + +์ƒ์œ„ prefix์—์„œ domain group์„ ์„ ํƒํ•˜๊ณ  ํ•ด๋‹น group์˜ runtime/route table์„ lazy-loadํ•œ๋‹ค. "10,000๊ฐœ๋ฅผ ๋” ๋น ๋ฅด๊ฒŒ flat map"ํ•˜๋Š” ๊ฒƒ๋ณด๋‹ค **์• ์ดˆ์— ํ•œ browser boot๊ฐ€ 10,000๊ฐœ๋ฅผ ์•Œ ํ•„์š”๊ฐ€ ์—†๊ฒŒ ํ•˜๋Š” ๊ฒƒ**์ด ์ค‘์š”ํ•˜๋‹ค. + +## 8. P1 โ€” Global TypeScript augmentation registry๋„ ๋ฌดํ•œ ํ™•์žฅ ๋Œ€์ƒ์œผ๋กœ ๋ณด๋ฉด ์•ˆ ๋œ๋‹ค + +`ApplicationFeatureInputs` module augmentation์€ ์ˆ˜์‹ญ~์ˆ˜๋ฐฑ feature์—์„œ๋Š” ํƒ€์ž… ์•ˆ์ „์„ฑ์ด ์ข‹๋‹ค. ๊ทธ๋Ÿฌ๋‚˜ 10,000๊ฐœ feature key๊ฐ€ ํ•œ interface์— ํ•ฉ์ณ์ง€๋Š” ๊ตฌ์กฐ๋Š” TypeScript compiler์˜ symbol/type graph๋„ ํ•จ๊ป˜ ํ‚ค์šด๋‹ค. + +๋”ฐ๋ผ์„œ 1,000+ bounded context๋ฅผ ์‹ค์ œ ๋ชฉํ‘œ๋กœ ํ•œ๋‹ค๋ฉด global interface ํ•˜๋‚˜๋ณด๋‹ค package/context ๋‹จ์œ„ typed registry๋ฅผ ๋งŒ๋“ค๊ณ  product composition ์‹œ ํ•ฉ์น˜๋Š” ๊ฒƒ์ด ๋‚ซ๋‹ค. + +์ฆ‰ runtime complexity๋ฟ ์•„๋‹ˆ๋ผ **compile-time complexity๋„ budget ๋Œ€์ƒ**์ด์–ด์•ผ ํ•œ๋‹ค. + +## 9. P1 โ€” Message catalog๋Š” ์•„์ง feature contribution ๋ชจ๋ธ๊ณผ ์–ด๊ธ‹๋‚œ๋‹ค + +`installed-feature-messages.ts`๋Š” `REFERENCE_MESSAGE_CATALOGS`๋ฅผ ์ง์ ‘ importํ•˜๊ณ  locale object์— spreadํ•œ๋‹ค. + +๋‹ค๋ฅธ contract/runtime/adapter๊ฐ€ contribution ๋ฐฉ์‹์œผ๋กœ ์ด๋™ํ•œ ๊ฒƒ์— ๋น„ํ•ด i18n์€ reference-specific central wiring์ด ๋‚จ์•„ ์žˆ๋‹ค. + +feature๊ฐ€ ๋Š˜์ˆ˜๋ก message catalog๋„ `FeatureModuleDescriptor.messages` ๊ฐ™์€ feature-owned contribution์œผ๋กœ ํ†ตํ•ฉํ•ด์•ผ ํ•œ๋‹ค. + +## 10. ๋Œ€์šฉ๋Ÿ‰ ํŠธ๋ž˜ํ”ฝ ๊ด€์  + +### ๊ฐ•์  + +1. **Static asset offload ๊ฐ€๋Šฅ** + - content-hashed immutable asset์ด๋ผ CDN/cache ํšจ๊ณผ๋ฅผ ์ตœ๋Œ€ํ™”ํ•˜๊ธฐ ์ข‹๋‹ค. +2. **Query retry ๊ธฐ๋ณธ OFF** + - React Query๊ฐ€ ๋ณ„๋„๋กœ ์žฌ์‹œ๋„ํ•˜๊ณ  HTTP client๊ฐ€ ๋˜ ์žฌ์‹œ๋„ํ•˜๋Š” ์ด์ค‘ ์ฆํญ์„ ํ”ผํ•œ๋‹ค. +3. **HTTP retry authority ์ค‘์•™ํ™”** + - safe/idempotent semantics๋งŒ retryํ•œ๋‹ค. + - full jitter๊ฐ€ ์žˆ๋‹ค. + - Retry-After ceiling์ด ์žˆ๋‹ค. +4. **bounded payload** + - response byte limit, mapper output limit, boot JSON size limit์ด ์žˆ๋‹ค. +5. **scope fencing / cancellation** + - session/state generation ์ „ํ™˜ ์ค‘ stale request๊ฐ€ ์ƒˆ scope๋ฅผ ์˜ค์—ผ์‹œํ‚ค์ง€ ์•Š๋„๋ก ํ•œ๋‹ค. +6. **cache invalidation edge ๋ช…์‹œ** + - namespace/topic/edge๊ฐ€ registry์— ์˜ฌ๋ผ์™€ ์žˆ์–ด mutation ์˜ํ–ฅ ๋ฒ”์œ„๋ฅผ ์ฝ”๋“œ๋กœ ์ถ”์ ํ•  ์ˆ˜ ์žˆ๋‹ค. + +### ์ถ”๊ฐ€๋กœ ์ฝ”๋“œ invariant๋กœ ์˜ฌ๋ฆด ๊ฒƒ + +๋Œ€์šฉ๋Ÿ‰ ์„œ๋น„์Šค์—์„œ backend์˜ N+1๊ณผ ๋น„์Šทํ•œ frontend ๋ฌธ์ œ๋Š” "list 1๊ฑด์„ ๋ Œ๋”๋งํ•  ๋•Œ item ์ˆ˜๋งŒํผ detail request"๊ฐ€ ๋ฐœ์ƒํ•˜๋Š” query waterfall/fan-out์ด๋‹ค. + +ํ˜„์žฌ `presentation -> direct fetch`๋Š” ๋ง‰ํ˜€ ์žˆ์ง€๋งŒ, application use case๊ฐ€ ์—ฌ๋Ÿฌ operation์„ item ๋‹จ์œ„๋กœ ๋ฐ˜๋ณต ํ˜ธ์ถœํ•˜๋Š” ๊ฒƒ์€ ๋ณ„๋„ invariant๊ฐ€ ์—†๋‹ค. + +๊ถŒ์žฅ: + +- collection operation์€ pagination/cursor์™€ ์ตœ๋Œ€ page size๋ฅผ contract๋กœ ๊ฐ–๊ฒŒ ํ•œ๋‹ค. +- list rendering์„ ์œ„ํ•ด item๋ณ„ network request๋ฅผ ๋งŒ๋“œ๋Š” API๋ฅผ ๊ธฐ๋ณธ ๊ธˆ์ง€ํ•œ๋‹ค. +- relation/detail์ด ํ•„์š”ํ•˜๋ฉด backend bulk/read-model endpoint๋ฅผ ์š”๊ตฌํ•œ๋‹ค. +- ํ•œ user action์—์„œ ๋ฐœ์ƒ ๊ฐ€๋Šฅํ•œ physical request count์— budget/evidence๋ฅผ ๋‘”๋‹ค. +- integration test์—์„œ "N๊ฐœ์˜ row โ†’ N๊ฐœ์˜ request"๊ฐ€ ์ƒ๊ธฐ๋ฉด failํ•˜๋„๋ก request-count assertion์„ ๋‘”๋‹ค. + +์ด๋ ‡๊ฒŒ ํ•ด์•ผ ์„ฑ๋Šฅ ๋ฌธ์ œ๊ฐ€ production APM์—์„œ ์ฒ˜์Œ ๋ณด์ด๋Š” ๊ฒƒ์ด ์•„๋‹ˆ๋ผ ์ฝ”๋“œ/ํ…Œ์ŠคํŠธ ๋‹จ๊ณ„์—์„œ ๋“œ๋Ÿฌ๋‚œ๋‹ค. + +## 11. ํด๋ผ์šฐ๋“œ instance ์ˆ˜ํ‰ ํ™•์žฅ ๊ด€์  + +### Application code ํŒ์ • + +**replica-safe ๋ฐฉํ–ฅ์ด๋‹ค.** + +frontend hosting instance์— ๋‹ค์Œ์ด ์—†๋‹ค. + +- ์‚ฌ์šฉ์ž๋ณ„ HttpSession +- process-local authenticated session authority +- process-local query cache shared by users +- process-local mutation state + +์ค‘์š”ํ•œ mutable state๋Š” browser runtime์— ์žˆ๋‹ค. ๋”ฐ๋ผ์„œ static origin์„ 1โ†’N replica๋กœ ๋Š˜๋ ค๋„ ํŠน์ • replica affinity/sticky session์„ ์š”๊ตฌํ•˜์ง€ ์•Š๋Š”๋‹ค. + +### ๋ฐ˜๋“œ์‹œ ์ง€์ผœ์•ผ ํ•˜๋Š” infra ์กฐ๊ฑด + +๋‹ค๋งŒ frontend repo๋งŒ ๋ณด๊ณ  "์–ด๋–ค ํด๋ผ์šฐ๋“œ ๋ฐฐํฌ์—์„œ๋„ ๋ฌด์กฐ๊ฑด ์•ˆ์ „"์ด๋ผ๊ณ  ํ•  ์ˆ˜๋Š” ์—†๋‹ค. ๋‹ค์Œ์ด ๊นจ์ง€๋ฉด replica ์ˆ˜๋ฅผ ๋Š˜๋ฆด์ˆ˜๋ก mixed release ํ™•๋ฅ ์ด ์˜ฌ๋ผ๊ฐ„๋‹ค. + +1. ๋ชจ๋“  replica๊ฐ€ ๋™์ผ immutable release artifact๋ฅผ ์ œ๊ณตํ•ด์•ผ ํ•œ๋‹ค. +2. HTML active pointer ์ „ํ™˜์€ release tuple ๊ธฐ์ค€์œผ๋กœ ์›์ž์ ์ด์–ด์•ผ ํ•œ๋‹ค. +3. `/config.json`, `/release-manifest.json`์€ `no-store` ๊ณ„์•ฝ์„ ์ง€์ผœ์•ผ ํ•œ๋‹ค. +4. hashed asset์€ release ๊ฐ„ overwriteํ•˜์ง€ ์•Š์•„์•ผ ํ•œ๋‹ค. +5. load balancer/CDN์ด ๋‹ค๋ฅธ release์˜ HTML/config/manifest๋ฅผ ํ˜ผํ•ฉํ•˜์ง€ ์•Š์•„์•ผ ํ•œ๋‹ค. +6. rolling deployment ์ค‘ old/new release๊ฐ€ ๋™์‹œ์— ์‚ด์•„๋„ old HTML์ด ์ฐธ์กฐํ•˜๋Š” old hashed asset์€ ๊ณ„์† ์ ‘๊ทผ ๊ฐ€๋Šฅํ•ด์•ผ ํ•œ๋‹ค. + +ํ˜„์žฌ ์ฝ”๋“œ์™€ ๋ฌธ์„œ๋Š” build/release mismatch๋ฅผ fail-closeํ•˜๋„๋ก ์ž˜ ๊ตฌ์„ฑ๋ผ ์žˆ๋‹ค. ๋‹ค์Œ ๋‹จ๊ณ„๋Š” infra repo์—์„œ ์‹ค์ œ CDN/LB/origin ์„ค์ •์ด ์ด ๊ณ„์•ฝ์„ ๋งŒ์กฑํ•˜๋Š”์ง€ ๋ณ„๋„๋กœ ๊ฒ€์ฆํ•˜๋Š” ๊ฒƒ์ด๋‹ค. + +## 12. ๋ชฉํ‘œ ๊ตฌ์กฐ + +๊ถŒ์žฅ ๊ตฌ์กฐ๋Š” ๋‹ค์Œ๊ณผ ๊ฐ™๋‹ค. + +```text +src/features// + domain/ + application/ + contracts/ + adapters/ + presentation/ + feature-module.ts # feature-owned ๋‹จ์ผ descriptor + +.generated/ + product-feature-index.ts # build-time ์ƒ์„ฑ + +bootstrap/ + compose-product.ts # generic composition only +``` + +ํ•ต์‹ฌ invariant: + +```text +Feature -> Platform Contract ํ—ˆ์šฉ +Feature -> Application Port ํ—ˆ์šฉ +Feature A -> Feature B concrete ๊ธˆ์ง€ +Presentation -> Fetch/Storage ๊ธˆ์ง€ (์ด๋ฏธ ์กด์žฌ) +Adapter -> Presentation ๊ธˆ์ง€ (์ด๋ฏธ ์กด์žฌ) +Registry composition O(N) +Route/domain loading hierarchical + lazy +Runtime user state browser-owned / external authority +Hosting replica stateless +``` + +## 13. ์ถ”๊ฐ€ํ•ด์•ผ ํ•  ๊ฒ€์ฆ Gate + +### Gate A โ€” cross-feature dependency + +๋‹ค๋ฅธ feature directory๋กœ์˜ direct import๊ฐ€ ํ•˜๋‚˜๋ผ๋„ ์ƒ๊ธฐ๋ฉด CI fail. + +### Gate B โ€” composition complexity + +100 / 1,000 / 10,000 synthetic feature descriptors๋ฅผ ์ƒ์„ฑํ•ด ๋‹ค์Œ์„ ์ธก์ •ํ•œ๋‹ค. + +- product selection +- contract registry composition +- route registry composition +- feature input composition +- route group creation + +์ ˆ๋Œ€ ์ˆซ์ž๋Š” CI runner baseline์„ ๋จผ์ € ์ธก์ •ํ•ด ๊ฒฐ์ •ํ•˜๋˜, N ์ฆ๊ฐ€์— ๋Œ€ํ•ด quadratic regression์ด ๋ฐœ์ƒํ•˜๋ฉด ์‹คํŒจํ•˜๊ฒŒ ํ•œ๋‹ค. + +### Gate C โ€” central touchpoint count + +์ƒˆ feature fixture๋ฅผ ์ถ”๊ฐ€ํ•  ๋•Œ feature directory + generated index ์™ธ์˜ production ํŒŒ์ผ์„ ์‚ฌ๋žŒ์ด ์ˆ˜์ •ํ•ด์•ผ ํ•˜๋ฉด fail. + +๋ชฉํ‘œ: **feature ์ถ”๊ฐ€ ์‹œ central handwritten file ์ˆ˜์ • 0๊ฐœ ๋˜๋Š” 1๊ฐœ**. + +### Gate D โ€” cross-domain request fan-out + +๋Œ€ํ‘œ collection page์—์„œ data cardinality๊ฐ€ ์ฆ๊ฐ€ํ•ด๋„ request count๊ฐ€ ์„ ํ˜• ์ฆ๊ฐ€ํ•˜์ง€ ์•Š๋Š”์ง€ integration test๋กœ ๊ฒ€์ฆํ•œ๋‹ค. + +### Gate E โ€” build/typecheck scale + +100/1,000 feature fixture์—์„œ TypeScript typecheck memory/time๊ณผ production build time์„ ๊ธฐ๋กํ•œ๋‹ค. runtime๋งŒ ๋น ๋ฅด๊ณ  compiler๊ฐ€ ์ˆ˜์‹ญ ๋ถ„ ๊ฑธ๋ฆฌ๋Š” ๊ตฌ์กฐ๋„ scale-ready๊ฐ€ ์•„๋‹ˆ๋‹ค. + +### Gate F โ€” replica release coherence + +์„œ๋กœ ๋‹ค๋ฅธ old/new frontend replica๋ฅผ ๋‘” fixture์—์„œ LB๊ฐ€ ์š”์ฒญ์„ ๊ต์ฐจ ๋ถ„๋ฐฐํ•ด๋„: + +- coherent release๋Š” ์ •์ƒ boot +- mixed config/manifest/build๋Š” ๋ช…์‹œ์  boot failure +- old hashed asset์€ ๊ณ„์† 200 +- ์ƒˆ active pointer ์ „ํ™˜ ํ›„ reload loop๊ฐ€ ๋ฐœ์ƒํ•˜์ง€ ์•Š์Œ + +์„ ๊ฒ€์ฆํ•œ๋‹ค. + +## 14. ๊ทœ๋ชจ๋ณ„ ํŒ์ • + +| ๊ทœ๋ชจ | ํ˜„์žฌ ๊ตฌ์กฐ ํŒ์ • | ์ด์œ  | +|---|---|---| +| 100 feature/domain | ๊ฐœ์„  ์ „์ œ ์‚ฌ์šฉ ๊ฐ€๋Šฅ | layer/capability ๊ฒฝ๊ณ„๋Š” ์ข‹์ง€๋งŒ ์ค‘์•™ 5-file wiring์ด merge hotspot์ด ๋จ | +| 1,000 | ํ˜„์žฌ ๊ทธ๋Œ€๋กœ๋Š” ๋ถ€์ ํ•ฉ | O(Nยฒ) composition, central catalogs, compiler graph, flat route registry ๋ถ€๋‹ด์ด ์ปค์ง | +| 10,000 | ๊ตฌ์กฐ ๋ณ€๊ฒฝ ํ•„์š” | ํ•˜๋‚˜์˜ SPA๊ฐ€ ๋ชจ๋“  feature/route/typed registry๋ฅผ flatํ•˜๊ฒŒ ์•„๋Š” ๋ชจ๋ธ ์ž์ฒด๊ฐ€ ๋งž์ง€ ์•Š์Œ | + +## 15. ์šฐ์„ ์ˆœ์œ„ + +### P0 + +1. route registry์˜ repeated object spread ์ œ๊ฑฐ +2. product/runtime selection์˜ `includes()` membership์„ `Set`์œผ๋กœ ๋ณ€๊ฒฝ +3. feature ์„ค์น˜๋ฅผ ๋‹จ์ผ descriptor + generated product index๋กœ ๋ณ€๊ฒฝ +4. cross-feature concrete import ๊ธˆ์ง€ rule ์ถ”๊ฐ€ + +### P1 + +5. route๋ฅผ bounded-context ๋‹จ์œ„ hierarchical/lazy composition์œผ๋กœ ๋ณ€๊ฒฝ +6. i18n์„ feature-owned contribution์œผ๋กœ ํ†ตํ•ฉ +7. 100/1,000/10,000 synthetic scale gate ์ถ”๊ฐ€ +8. request fan-out / waterfall budget test ์ถ”๊ฐ€ +9. TypeScript/build scale evidence ์ถ”๊ฐ€ + +### P2 + +10. ์‹ค์ œ cloud infra์—์„œ multi-replica mixed-release test ์ˆ˜ํ–‰ +11. CDN/LB/active-pointer/cache header๊ฐ€ repo์˜ release contract์™€ ์ผ์น˜ํ•˜๋Š”์ง€ ๊ฒ€์ฆ + +## 16. ๊ฒ€์ฆ ๋ฉ”๋ชจ + +- `origin/main`: `ebea300`, fetch ํ›„ ๋™์ผ +- direct `tsc --project tsconfig.app.json`: PASS +- direct `tsc --project tsconfig.test.json`: PASS +- `dependency-cruiser`: TypeScript 7 ๋ฏธ์ง€์›์œผ๋กœ 0 module์„ ๋ณด๊ณ ํ•˜๋ฏ€๋กœ ์ด๋ฒˆ ๋ฆฌ๋ทฐ์˜ architecture evidence๋กœ ์‚ฌ์šฉํ•˜์ง€ ์•Š์Œ +- ์ „์ฒด `pnpm check:*`๋Š” ํ˜„์žฌ Coka host Node 22์™€ repo engine ์š”๊ตฌ Node 24 ๋ถˆ์ผ์น˜ ๋ฐ snapshot node_modules ์ •ํ•ฉ์„ฑ ๋•Œ๋ฌธ์— ์ˆ˜ํ–‰ํ•˜์ง€ ์•Š์Œ +- benchmark๋Š” synthetic microbenchmark์ด๋ฉฐ production browser latency ์ˆ˜์น˜๋กœ ํ•ด์„ํ•˜์ง€ ์•Š์Œ + +## Final assessment + +์ด ํ…œํ”Œ๋ฆฟ์€ "๋Œ€์ถฉ layer๋งŒ ๋‚˜๋ˆˆ frontend"๋Š” ์•„๋‹ˆ๋‹ค. ๋„คํŠธ์›Œํฌ, browser capability, release identity, invalidation, retry, runtime state์˜ ์œ„ํ—˜์„ ๊ณ„์•ฝ๊ณผ gate๋กœ ๋Œ์–ด์˜ฌ๋ฆฌ๋Š” ๋ฐฉํ–ฅ์€ ์ข‹๋‹ค. + +๋‹ค์Œ ๋‹จ๊ณ„์˜ ํ•ต์‹ฌ์€ **๋„๋ฉ”์ธ์ด ๋Š˜์–ด๋‚  ๋•Œ ์ƒ๊ธฐ๋Š” coupling๊ณผ cardinality ์ž์ฒด๋„ ๊ฐ™์€ ๋ฐฉ์‹์œผ๋กœ ์ฝ”๋“œ์— ๋“œ๋Ÿฌ๋‚ด๋Š” ๊ฒƒ**์ด๋‹ค. + +์„œ๋ฒ„์—์„œ `OneToMany`๋ฅผ ์‚ฌ์šฉํ•˜์ง€ ์•Š์•„ ๊ด€๊ณ„ fan-out์„ ์ˆจ๊ธฐ์ง€ ์•Š๋Š” ๊ฒƒ๊ณผ ๊ฐ™์€ ์ฒ ํ•™์„ frontend์— ์ ์šฉํ•œ๋‹ค๋ฉด ๊ฐ€์žฅ ์ค‘์š”ํ•œ ๊ทœ์น™์€ ๋‹ค์Œ ๋‘ ์ค„์ด๋‹ค. + +```text +Feature A -> Feature B concrete import ๊ธˆ์ง€ +Unbounded feature/route/request fan-out ๊ธˆ์ง€ +``` + +๊ทธ๋ฆฌ๊ณ  ์ด ๋‘ ๊ทœ์น™์„ ์‚ฌ๋žŒ์˜ ๋ฆฌ๋ทฐ ๊ทœ์น™์ด ์•„๋‹ˆ๋ผ architecture gate์™€ scale test๋กœ ๊ณ ์ •ํ•ด์•ผ ํ•œ๋‹ค. diff --git a/docs/reviews/2026-09-23-extreme-scale-acceptance.md b/docs/reviews/2026-09-23-extreme-scale-acceptance.md new file mode 100644 index 00000000..f62aba3c --- /dev/null +++ b/docs/reviews/2026-09-23-extreme-scale-acceptance.md @@ -0,0 +1,46 @@ +# Extreme-scale frontend architecture โ€” acceptance matrix (spec ยง54) + +Plan bundle: `docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/`. One row per acceptance criterion. Status is `์™„๋ฃŒ` or `์•„์ง ๋” ๋ด์•ผ๋Œ`. Each `์™„๋ฃŒ` row names the executable evidence. + +| # | Acceptance criterion (spec ยง54) | Status | Evidence | +| --- | --- | --- | --- | +| 1 | Adding a normal feature does not require editing a collection of central handwritten installation registries. | ์™„๋ฃŒ | `scripts/generate-product-feature-index.ts` โ†’ `src/.generated/product-feature-index.ts`, `src/.generated/product-context-index.ts`; `tests/features/feature-installation-surface.test.ts`; `tests/scripts/generate-product-feature-index.test.ts`; `pnpm check:feature-index`; `pnpm test:sample-removal` | +| 2 | Composition does not contain known quadratic accumulation patterns. | ์™„๋ฃŒ | `src/platform/cardinality/compose-unique-record.ts`; `tests/platform/cardinality/compose-unique-record.test.ts`; `tests/platform/cardinality/extreme-scale-registry.test.ts`; growth gate `scripts/scale/run-composition-scale.ts` + `src/platform/cardinality/growth-regression.ts` (`tests/scale/composition-scale.test.ts`, `tests/scale/growth-regression.test.ts`, artifact `artifacts/scale/main/composition-s0-s2.json`); stored-baseline gate `pnpm check:scale:baseline` (`config/scale/benchmark-baseline.json`) | +| 3 | Membership checks on scale-sensitive paths use appropriate indexed structures. | ์™„๋ฃŒ | `src/contracts/product-features.ts` (`Set` membership); `tests/unit/product-features.test.ts`; `tests/features/product-features-scale.test.ts`; 100k selection/resolution in `tests/platform/cardinality/extreme-scale-registry.test.ts`; workloads `product-feature-selection`/`product-feature-resolution` in `scripts/scale/composition-workloads.ts` | +| 4 | Concrete imports across unrelated features fail architecture checks. | ์™„๋ฃŒ | `.dependency-cruiser.json` rules `features-do-not-import-other-features`, `contexts-do-not-import-other-contexts`; rejected fixtures `tests/fixtures/architecture/dependency-graph/cross-boundary/`; assertions in `scripts/check-architecture.ts`; `pnpm check:architecture` | +| 5 | Context/app cardinality ceilings are explicit and testable. | ์™„๋ฃŒ | `src/platform/cardinality/cardinality-budget.ts`; `src/contexts/bounded-context-module.ts`; `src/apps/deployable-app-module.ts`; `tests/architecture/topology-cardinality.test.ts`; `tests/architecture/module-hierarchy.test.ts`; `tests/platform/cardinality/cardinality-budget.test.ts` | +| 6 | An unchanged local app does not grow materially when global logical topology grows toward S3/S4 fixtures. | ์™„๋ฃŒ | (1) Ownership source: `src/apps/template-app/app-module.ts`, `src/contexts/reference-context/context-module.ts`, `FEATURE_CONTEXT_ID`. (2) Production projection: `scripts/generate-product-feature-index.ts` selects one app (`--app=`/`PRODUCT_APP_ID`) โ†’ `src/.generated/{product-feature-index,product-context-index,product-app}.ts` โ†’ `src/apps/template-app.ts`. (3) S0โ†’S4 invariant: `tests/scale/global-local-independence.test.ts` โ€” S0/S1/S2 real on-disk repos through the generator command (identical generated files, sha256 and reachable source graph); S0โ†’S4 through the same `selectAppIndexes` (identical feature/context ids, route roots, generated files, hashes and compile-input paths; only App A's declarations read at 1M), pinned to the filesystem source by an equivalence test. (4) Build-input gate: `scripts/check-app-build-input.ts` (`pnpm check:app-build-input`, and `check:app-build-input:bundle` on the fresh production bundle), negative fixtures in `tests/architecture/app-build-input.test.ts` | +| 7 | Initial routing is hierarchical/lazy rather than a product-wide flat feature table. | ์™„๋ฃŒ | `src/platform/routing/context-route-module.ts`; `src/presentation/routes/app-router.tsx` (`ContextRouteGateway`); `tests/platform/routing/context-route-module.test.ts`; `tests/architecture/context-lazy-loading.test.ts`; `tests/features/reference-feature/installed-context-routing.test.ts` | +| 8 | User interactions carry bounded request, retry, concurrency, cancellation, and deadline semantics. | ์™„๋ฃŒ | `src/platform/execution/execution-context.ts`; `src/platform/traffic/{request-budget,concurrency-budget,traffic-budget}.ts`; `src/platform/resilience/{retry-budget,deadline}.ts`; enforcement in `src/adapters/http/http-execution-v3.ts`; operation policy `HttpExecutionPolicy.traffic` (`src/contracts/external-contract-runtime.ts`); `tests/platform/traffic/http-budget-integration.test.ts`; `tests/platform/traffic/traffic-amplification.test.ts`; `pnpm check:traffic` | +| 9 | Representative collections do not create frontend N+1 request fan-out. | ์™„๋ฃŒ | Policy (spec ยง41 implementation note): paginated bulk read, page โ‰ค 100 by contract (not raised). `tests/platform/traffic/request-fanout.test.ts`, `tests/features/reference-feature/reference-request-fanout.test.ts`: 10/50/100/1,000-row collections load a page with 1 request; full 1,000-row walk โ‰ค ceil(N/100)+1 requests; single oversized response rejected within 1 request. Coalescing: `tests/platform/traffic/request-deduplication.test.ts`. Source gate: `scripts/check-request-fanout.ts` (`pnpm check:request-fanout`; forbidden/allowed fixtures in `tests/fixtures/architecture/request-fanout/`, `tests/architecture/request-fanout.test.ts`) | +| 10 | Errors remain local and typed without constructing a global union of all feature errors. | ์™„๋ฃŒ | `src/platform/errors/app-error.ts`; `src/platform/errors/platform-errors.ts`; `src/adapters/http/platform-error-mapping.ts`; `src/features/reference-feature/application/reference-error.ts`; `tests/features/reference-feature/reference-error.test.ts`; `tests/architecture/observability-boundaries.test.ts` | +| 11 | External data is validated at trust boundaries with bounded payload/structure cost. | ์™„๋ฃŒ | `src/platform/validation/{validation-budget,bounded-json}.ts`; structure-before-mapping in `src/adapters/http/http-execution-v3.ts`; existing byte ceilings `src/adapters/http/bounded-body-reader.ts`; `src/contracts/validation-issues.ts`; `tests/platform/validation/*.test.ts` | +| 12 | Feature code emits observability through a platform port rather than vendor SDKs. | ์™„๋ฃŒ | `src/platform/telemetry/telemetry-port.ts`; capability `telemetry` in `src/features/feature-adapter-contribution.ts`; reference emission `src/features/reference-feature/application/reference-feature-api.ts`; collector transport `src/adapters/telemetry/feature-telemetry.ts`; rule `observability-vendors-live-behind-adapters` in `.dependency-cruiser.json`; `tests/architecture/observability-boundaries.test.ts`; `tests/features/reference-feature/reference-telemetry.test.ts` | +| 13 | Telemetry is redacted, deduplicated, sampled, buffered, and rate-limited with bounded memory. | ์™„๋ฃŒ | `src/platform/telemetry/{redact-telemetry,telemetry-fingerprint,telemetry-deduplicator,telemetry-sampler,telemetry-buffer,telemetry-pipeline}.ts`; `tests/platform/telemetry/*.test.ts`; `tests/scale/telemetry/telemetry-storm.test.ts` | +| 14 | Telemetry failure does not fail business behavior. | ์™„๋ฃŒ | `tests/platform/telemetry/telemetry-pipeline.test.ts` (transport throw/reject); `tests/platform/telemetry/telemetry-port.test.ts` (`failOpenTelemetryPort`); `tests/features/reference-feature/reference-telemetry.test.ts`; collector outage in `tests/scale/telemetry/telemetry-storm.test.ts` | +| 15 | Failure boundaries prevent one feature/context from unnecessarily collapsing unrelated UI. | ์™„๋ฃŒ | `src/platform/errors/{scoped-error-boundary,feature-error-boundary,context-error-boundary}.tsx`; wiring in `src/presentation/routes/app-router.tsx`; `tests/platform/errors/failure-boundary.test.tsx` | +| 16 | Spike and sustained-load tests detect request, retry, telemetry, and memory amplification. | ์™„๋ฃŒ | `tests/scale/traffic/*`, `tests/scale/telemetry/telemetry-storm.test.ts`, `tests/scale/session/*`; real Chromium soak `scripts/scale/browser-soak.ts` against the fresh build with telemetry on and a 503 API: 2,012 cycles, heap/listeners/timers/storage stable, 0 in-flight at end, 1.43 API requests per reference visit (โ‰ค 3), telemetry โ‰ค 14 posts/min (โ‰ค 40), checks in `artifacts/scale/nightly/browser-soak.json`; evaluator tests `tests/scale/browser-soak.contract.test.ts`; skipped โ‡’ tier `incomplete` (non-zero). Platform telemetry adapter now send-rate limited (`src/adapters/telemetry/best-effort-telemetry.ts`, tests in `tests/unit/telemetry.test.ts`) | +| 17 | Multi-replica release tests verify fail-closed coherence and old-asset reachability. | ์™„๋ฃŒ | `src/platform/release/release-coherence.ts` (delegated to by `src/bootstrap/load-runtime-config.ts`, `src/bootstrap/load-release-manifest.ts`); `src/platform/release/release-mismatch-recovery.ts` + `src/bootstrap/boot-release-recovery.ts`; `tests/platform/release/*.test.ts`; `tests/release/{old-asset-reachability,mixed-replica,release-matrix}.test.ts`; `pnpm check:release-coherence` | + +Overall: **์™„๋ฃŒ** โ€” every spec ยง54 criterion is `์™„๋ฃŒ`. + +## Executable evidence (supported runtime) + +Re-run on Node **v24.11.0** / pnpm 11.17.0 inside the `workmachine` container (whose default Node v22.23.2 is below `engines.node`): + +``` +PATH=$PWD/.tmp/node24/bin:$PATH corepack pnpm run verify:extreme-scale +``` + +Record `artifacts/quality/extreme-scale-gates.json` (logs in `artifacts/quality/extreme-scale-gates/`): status `passed`, **24/24 gates, 552 tests passed, 0 failed** โ€” `check:feature-index`, `check:types:app`, `check:types:test`, `check:types`, `lint`, `check:architecture`, `check:app-build-input`, `check:request-fanout`, `check:registries`, `check:diagnostics`, `test:extreme-scale:focused`, `check:topology`, `check:traffic`, `check:observability`, `check:release-coherence`, `test:platform`, `test:reference-feature`, `check:scale:pr`, `check:scale:main`, `check:scale:baseline`, `build`, `check:app-build-input:bundle`, `check:scale:nightly`, `check:scale:release`. + +The same record carries 12 evidence checks, all passed: nightly/release summaries and the soak, baseline comparison and bundle inventory were regenerated by this run; tier summaries have `environment.nodeMajor == 24`, status `passed` and no skipped step; the soak is `passed`; the baseline comparison is `passed` on all three axes (absolute ceiling, relative regression, growth shape) with a timing-compatible environment (an incompatible one is `incomplete`, never passed); and the source digest (`source.digest`, 1,048 files) did not change while the gates ran. On an unsupported Node the runner writes `not-executed` and exits 2. + +Also on Node v24.11.0 in the container: `test:sample-removal` PASS (13 checks, no fixture IDs); coverage suite 217 files / 2,314 tests PASS; risk coverage 362/362 modules, 80 thresholds PASS. + +## Notes that do not change a row + +- Behavior changes worth review: `retryDelayFor()` now treats `Retry-After` as a floor plus bounded jitter (spec ยง13.3); a boot-time release mismatch now performs at most one automatic reload per mismatch key before showing the boot error shell (spec ยง45). +- Fixed while closing coverage: `src/contracts/diagnostics.ts` rejected its own bounded bucket labels `51+`/`5+`; admitted finite-set values are now projected as-is. +- Stored baseline and relative regression gate: `config/scale/benchmark-baseline.json` (approved, digest-checked) + `scripts/scale/{scale-baseline,check-scale-baseline}.ts`, run by `pnpm check:scale:baseline` and the `baseline-regression` step of the main/nightly/release tiers; logic tested in `tests/scale/scale-baseline.test.ts`. Compiler counts must stay within +10% and need re-approval on a compiler change; timings must stay within 2.5x (1 ms noise floor) and are enforced only on a timing-compatible machine (same Node major, platform/arch, CPU model), otherwise reported as advisory. Re-approve with `SCALE_BASELINE_OWNER=โ€ฆ SCALE_BASELINE_REASON=โ€ฆ pnpm update:scale-baseline`. +- Host-checkout-only failures (not reproduced in the container run above): tests that need a git-tracked `src/` inventory (`tests/integration/security-followup-archive.test.ts`, `tests/system/ci-runner/ci-artifact-contract.test.ts`) and `check:adapter-inventory`; Playwright `*.spec.ts` files are not vitest suites. diff --git a/docs/reviews/2026-09-23-extreme-scale-baseline-map.md b/docs/reviews/2026-09-23-extreme-scale-baseline-map.md new file mode 100644 index 00000000..20d5f061 --- /dev/null +++ b/docs/reviews/2026-09-23-extreme-scale-baseline-map.md @@ -0,0 +1,190 @@ +# Extreme-scale frontend implementation baseline + +## Live baseline + +- Verified source baseline: `origin/main` `ebea300e4ffd9ef9312d3982b44ccda2fc3fea2c`. +- Local branch remains the user-owned initial branch and was not reset because the worktree already contained untracked project files. +- Missing baseline files were materialized with `git archive origin/main | tar --skip-old-files -x`; existing files were preserved byte-for-byte. +- Host during implementation: Node `v22.23.2`, pnpm `11.17.0`. +- Repository engine requests Node `>=24.11.0 <25.0.0`; checks executed on this host therefore retain an engine warning. +- `tsconfig.app.json` passed before production edits. + +## Verified scale-sensitive baseline paths + +- `src/features/installed-product-manifest.ts` directly imported the reference feature contract. +- `src/features/installed-feature-adapters.ts` directly imported the reference adapter contribution. +- `src/features/installed-feature-runtimes.tsx` directly imported the reference runtime contribution and used installed-id membership filtering. +- `src/features/installed-feature-messages.ts` directly imported the reference message catalogs. +- `src/features/installed-contract-contributions.ts` directly imported the reference contract contribution and used installed-id membership filtering. +- `src/features/installed-feature-contracts.ts` composed routes and route-runtime contracts with repeated accumulator object spread inside `reduce()`. +- `src/contracts/product-features.ts` used repeated array `includes()` membership checks. +- `src/presentation/routes/app-router.tsx` flattened `Object.values(ROUTE_REGISTRY)` into boot-time route objects. +- `.dependency-cruiser.json` had feature-local layer rules but no generic Feature-A -> Feature-B or Context-A -> Context-B concrete import prohibition. + +## Live-path ruling + +The supplied plan names `src/features/product-features.ts`; the verified live implementation is `src/contracts/product-features.ts`. The live path is used throughout implementation. The live reference feature id is `reference-feature`; example ids such as `reference` in the plan are treated as illustrative and do not replace the existing contract id. + +## 2026-09-23 Phase 2 continuation ledger + +### Execution environment + +- Continuation checks ran with Node `v24.11.0` from the verified host-local Node 24.11.0 binary path; no Node installation files were added to the repository. +- The existing working tree was preserved. No reset, clean, checkout, rebase, merge, commit, or push was performed. + +### Phase 2-B โ€” ์™„๋ฃŒ + +- `tests/platform/cardinality/extreme-scale-registry.test.ts` was executed before modification and passed 3/3 tests against the existing O(N) production composition path. +- The scale gate now performs one warm-up plus three measured runs and compares the median instead of relying on one timing sample. +- Registry composition validates 10k -> 100k relative growth with a generous hard ceiling. +- Runtime registry lookup validates 100k entries with 1,000,000 repeated lookups. +- Product feature selection and installed/active resolution validate 100k feature ids. +- Related cardinality/routing/product-feature regression: 7 files, 28 tests PASS. + +### Phase 2-C โ€” ์™„๋ฃŒ + +- Context route loading remains lazy and is now single-flight per context. +- A successful context route composition is frozen and cached; later entries reuse the same route array. +- A failed lazy load clears only the in-flight promise so the next entry can retry. +- `ContextRouteGateway` no longer clones the already-frozen route array after each context load. +- Generator regression verifies that feature executable route modules are emitted as dynamic imports behind one context loader, not as boot-time static imports. +- Focused lazy-composition regression: 3 files, 9 tests PASS. + +### Phase 2-D โ€” ์™„๋ฃŒ + +- The topology gate now proves with a generic 20-context app that app boot constructs context gateways without executing any context route loader. +- Entering one context executes only that context loader; re-entry reuses the cached result. +- The test contains no concrete product feature id, so the physical feature-removal fixture remains valid. +- `check:topology` includes this boot/lazy regression permanently. + +### Phase 2-E / Phase 2-F โ€” ์™„๋ฃŒ + +- Topology capacity remains covered at 100 / 1k / 10k / 100k / 1M feature tiers using partition math rather than materializing one million executable feature objects. +- The 100k registry / 1,000,000 lookup scale gate is part of the same topology CI gate. +- Latest `check:topology`: 6 files, 21 tests PASS. + +### Required gates after Phase 2 + +- `check:types:app`: PASS. +- `check:types:test`: PASS. +- `check:feature-index`: PASS. +- `check:architecture`: 329 modules, 979 dependencies, all imports resolved; 16 graph regression checks PASS; allowed fixture PASS; 9 forbidden fixtures rejected. +- `test:sample-removal`: 13/13 checks PASS, no fixture ids. +- Sample-removal coverage run: 168 test files PASS, 1604 passed, 3 skipped. +- Sample-removal risk coverage: 307/307 production modules PASS, 76 thresholds. +- Sample-removal fixture architecture: 308 modules, 897 dependencies, 16 graph regression checks PASS, 9 forbidden fixtures rejected. + +Phase 2 status: **์™„๋ฃŒ**. + +## 2026-09-23 Phase 3 continuation ledger + +### Phase 3 โ€” logging / diagnostics cardinality โ€” ์™„๋ฃŒ + +- Every diagnostic context key now has an explicit cardinality class: `bounded`, `taxonomy`, `topology`, `deployment`, or `request`. +- `correlation_id` is explicitly request-cardinality and remains diagnostics-only; `check:diagnostics` rejects any request-cardinality key added to telemetry dimensions. +- Route/operation ids are topology-cardinality and are bounded by the deployed topology rather than raw URL/user values. +- Outcome, HTTP status group, attempt count, duration, component boundary, and queue size are validated as bounded dimensions rather than arbitrary safe strings. +- Existing source-controlled error/reason taxonomies remain distinct from request-cardinality identifiers. +- Focused diagnostics/telemetry regression: 5 files, 33 tests PASS. +- `check:diagnostics`: 8 diagnostic producers and 5 telemetry producers PASS. +- `check:types:app`: PASS. +- `check:types:test`: PASS. +- `check:architecture`: 329 modules, 979 dependencies, 16 graph regression checks PASS, 9 forbidden fixtures rejected. + +Phase 3 status: **์™„๋ฃŒ**. + +## 2026-09-23 Phase 4 continuation ledger + +### Phase 4 โ€” error taxonomy / validation โ€” ์™„๋ฃŒ + +- Validation issue projection is centralized in `src/contracts/validation-issues.ts`. +- Failure handling admits at most 50 projected issues, scans at most 200 candidates, and rejects issue paths longer than 120 characters or codes longer than 80 characters. +- `createFailure()`, legacy HTTP schema projection, and installed runtime schema codec projection use the same bounded issue policy. +- A Feature codec can no longer return an unbounded validation issue array through the runtime schema registry. +- Error taxonomy observability references are no longer free-form strings: `ErrorObservationEvent` is the union of registered diagnostic and telemetry event ids. +- The stale `QUERY_CACHE_FAILURE -> query.cache.failed` reference was corrected to the registered `cache.operation.failed` event. +- Focused error/schema regression: 4 files, 27 tests PASS. +- `check:types:app`: PASS. +- `check:types:test`: PASS. +- `check:architecture`: 330 modules, 984 dependencies, 16 graph regression checks PASS, 9 forbidden fixtures rejected. + +Phase 4 status: **์™„๋ฃŒ**. + +## 2026-09-23 plan-bundle continuation ledger (Phases 2โ€“5 of `2026-09-23-extreme-scale-frontend-plan-bundle`) + +The ledger sections above track the earlier numbering. This section maps the remaining work onto the bundle's five plans. Phase 1 (topology/composition) was verified complete before starting (`check:feature-index`, `check:architecture`, `check:topology`, both type checks PASS; no spread accumulators, no `includes()` membership, no `REFERENCE_*` in installed central files). + +### Execution environment + +- Node `v24.14.0`; pnpm scripts run with `pnpm_config_verify_deps_before_run=false` because pnpm's deps-status check tried to purge `node_modules` without a TTY. No dependency was installed or changed. +- Project files written by the previous in-container (root) session were re-owned to uid 1000 so the host user could edit them; contents were not changed. + +### Phase 2 โ€” execution/traffic โ€” ์™„๋ฃŒ + +- `src/platform/execution/execution-context.ts`, `src/platform/traffic/{request-budget,concurrency-budget,traffic-budget,request-fanout}.ts`, `src/platform/resilience/{retry-budget,deadline}.ts`. +- `HttpExecutionPolicy.traffic` (optional, validated, snapshotted) in `src/contracts/external-contract-runtime.ts`; reference operations declare it. +- V3 executor enforces: cancellation โ†’ remaining interaction deadline โ†’ request budget โ†’ cancellable concurrency lease โ†’ dispatch โ†’ shared retry budget; operations without an interaction get a bounded implicit one (`DEFAULT_OPERATION_TRAFFIC_BUDGET`). Existing HTTP suites unchanged and green. +- `check:traffic`: 11 files PASS. + +### Phase 3 โ€” errors/validation/telemetry โ€” ์™„๋ฃŒ + +- `src/platform/errors/*` (envelope, platform kinds, scoped/feature/context boundaries wired in `ContextRouteGateway`), `src/adapters/http/platform-error-mapping.ts`, feature-local `reference-error.ts`. +- `src/platform/validation/*`; structure-before-mapping in V3 response admission. +- `src/platform/telemetry/*` (port, redaction, fingerprint, dedup, sampler, buffer, fail-open pipeline, trace context); `telemetry` feature capability; bootstrap composes `createFeatureTelemetry`; reference feature emits `reference.load.failed`. +- `.dependency-cruiser.json`: `observability-vendors-live-behind-adapters`, `platform-kernel-is-product-neutral`. +- `check:observability`: 12 files PASS. + +### Phase 4 โ€” scale/chaos/soak โ€” ์™„๋ฃŒ + +- `tests/scale/**`, `scripts/scale/**`, `src/platform/cardinality/growth-regression.ts`. +- Retry-After now a floor plus bounded jitter (`src/adapters/http/http-retry-lifecycle.ts`), found by the jitter regression. +- Tiers: `check:scale:pr`, `check:scale:main`, `check:scale:nightly` (includes a 120 s real-Chromium soak: stable), `check:scale:release` โ€” all PASS; summaries in `artifacts/scale//summary.json`. + +### Phase 5 โ€” release coherence โ€” ์™„๋ฃŒ + +- `docs/reviews/2026-09-23-release-coherence-baseline.md`; `src/platform/release/{release-coherence,release-mismatch-recovery}.ts`; both boot loaders delegate identity checks; `src/bootstrap/boot-release-recovery.ts` + `main.tsx` allow one reload per mismatch key via registered session key `RELEASE_MISMATCH_RECOVERY`. +- `tests/platform/release/*`, `tests/release/*` (R10/R11 fixtures, mixed replicas, matrix, no reload loop); `check:release-coherence` PASS. + +### Gaps from the earlier session closed here + +- `check:registries` failed on `FE-REG-ERROR:QUERY_CACHE_FAILURE:telemetryEvent:field-changed`; evidence added to `config/contracts/registry-change-evidence.json`. +- `check:types` (node project) failed on parameter properties in `src/platform/cardinality/cardinality-budget.ts` and a narrowed comparison in `scripts/check-diagnostics.ts`; both fixed. +- Risk coverage failed on `src/contracts/diagnostics.ts`; the new tests exposed that bounded buckets `51+`/`5+` were rejected by the free-form safe-string pattern, fixed in the projection. + +### Final verification + +- PASS: `check:feature-index`, `check:architecture`, `check:topology`, `check:traffic`, `check:observability`, `check:release-coherence`, `check:scale:{pr,main,nightly,release}`, `check:types`, `check:registries`, `check:diagnostics`, `check:ci`, `lint`, `test:platform`, `test:reference-feature`. +- Coverage suite (runtime-schema, unit, contract, component, integration, reference-feature, platform): 217 files / 2307 tests PASS; risk coverage 359/359 modules, 80 thresholds PASS. +- `test:sample-removal`: typecheck, architecture, registries, residue and CI checks PASS inside the removal fixture; its unit/coverage stages stop only on `tests/integration/security-followup-archive.test.ts`. +- Environment-only failures (not caused by this work): tests requiring a git-tracked `src/` inventory (`tests/integration/security-followup-archive.test.ts`, `tests/system/ci-runner/ci-artifact-contract.test.ts`) and `check:adapter-inventory`; this checkout tracks 1 file. + +Acceptance matrix: `docs/reviews/2026-09-23-extreme-scale-acceptance.md` โ€” all 17 spec ยง54 criteria `์™„๋ฃŒ`. + +### Follow-up โ€” stored benchmark baseline and relative regression gate โ€” ์™„๋ฃŒ + +- Baseline: `config/scale/benchmark-baseline.json` โ€” environment (Node 24, linux/x64, i5-10400F ร—12, TypeScript 7.0.2), 12 composition timings (4 workloads ร— S0/S1/S2, median and best-of-9) and 4 compiler fixtures (app + local 25/100/400: files/types/symbols/instantiations), approval owner/reason/time and a sha256 digest of the metrics. +- Compatibility check (`scripts/scale/scale-baseline.ts`): structural (schema, digest, coverage of every measured workload/fixture) โ†’ must pass; compiler (same TypeScript) โ†’ a change fails and requires re-approval; timing (same Node major, platform/arch, CPU model) โ†’ otherwise timing is advisory and skipped. +- Relative gate: compiler counts โ‰ค baseline ร— 1.10; best-observed timing โ‰ค max(baseline ร— 2.5, baseline + 1 ms). +- Commands: `check:scale:baseline`, `update:scale-baseline` (requires `SCALE_BASELINE_OWNER`/`SCALE_BASELINE_REASON`); step `baseline-regression` in `check:scale:{main,nightly,release}`; `tests/scale/scale-baseline.test.ts` (9 tests) in the PR tier. +- Verification: gate PASS 4/4 consecutive runs (closest metric at 0.91 of its limit โ€” compiler counts equal to baseline); `check:types`, `lint`, `check:architecture`, `check:ci`, `check:scale:{pr,main,release}` PASS. +- Master plan Final Verification: all 14 items checked. + +### Follow-up โ€” 2026-09-23 re-verification findings โ€” ์™„๋ฃŒ + +The re-verification ("์•„์ง ๋” ๋ด์•ผ๋Œ") raised three blockers; each is closed with executable evidence. + +1. **Gates not executed on Node 22.** New `pnpm verify:extreme-scale` (`scripts/verify-extreme-scale.ts`) runs all 18 cited gates under the current Node and records `artifacts/quality/extreme-scale-gates.json`; on an unsupported Node it records `not-executed` and exits 2. Re-run inside `workmachine` with the repository-local Node 24.11.0 first on PATH: 18/18 PASS, including `check:scale:nightly` with a real Chromium soak (Playwright headless shell provided via `PLAYWRIGHT_BROWSERS_PATH=.tmp/ms-playwright`; all shared libraries resolved in the container) and a timing-compatible `check:scale:baseline`. `test:sample-removal` PASS (13 checks); coverage 217 files / 2308 tests; risk coverage 362/362. +2. **S4 proof not linked to production discovery.** The generator now discovers ownership declarations (`src/apps//app-module.ts` โ†’ `src/contexts//context-module.ts` โ†’ `FEATURE_CONTEXT_ID`) and emits indexes for exactly one selected app (`--app=`/`PRODUCT_APP_ID`, or the single declared app), including `src/.generated/product-app.ts`, which `src/apps/template-app.ts` consumes. Context route root and budget moved from the feature to the context declaration. `tests/scale/global-local-independence.test.ts` runs the production generator command on real S0/S1/S2 on-disk repositories (identical outputs and reachable source graph for App A) and the same `selectAppIndexes` at S3/S4 over a declaration source proven equivalent to the filesystem one; the removal drill now also removes the sample context. +3. **N+1 at 1,000 rows only proven by rejection.** Fan-out tests now load 10/100/1,000-row paginated collections successfully with one request per page (โ‰ค ceil(N/100)+1 for a full walk); the single-oversized-response rejection remains a separate bounded-rejection case. + +Also: a tier with a skipped step is now `incomplete` and exits non-zero; the soak fails on `insufficient-data` and records the soaked build identity and browser version. + +### Follow-up โ€” second re-verification (production-path rigor) โ€” ์™„๋ฃŒ + +- Build-input regression gate: `scripts/check-app-build-input.ts` checks the generated indexes (and, after a fresh build, the production module inventory) contain only features owned by the built app; negative fixtures cover an "import every discovered feature" regression and a foreign module in the bundle. +- S0โ†’S4 invariant extended to generated-file sha256 and compile-input paths through `selectAppIndexes`; on-disk S0โ€“S2 also compares hashes. +- Baseline gate now evaluates absolute ceilings, relative regression and growth shape; a timing-incompatible environment yields `incomplete` (non-zero), not `passed`. +- N+1: supported page cardinalities 10/50/100 plus 1,000-row collections; spec ยง41 carries the policy note; `check:request-fanout` AST gate with forbidden/allowed fixtures. +- Browser soak v2: cycles, navigation verification, listener/timer/storage deltas, in-flight settle, request amplification and telemetry rate against a 503 API with telemetry enabled; non-vacuity required. Found and fixed: the platform-event telemetry adapter had no send-rate limit (now 20/min, bounded queue, page-exit flush may exceed once). +- `verify:extreme-scale` records pnpm version, node major, a source digest (checked unchanged across the run), per-gate test counts and artifact-freshness checks. +- Result: 24/24 gates, 552 tests, 12/12 evidence checks on Node v24.11.0 in the container; removal drill 13/13; coverage 2,314 tests; risk coverage 362/362. diff --git a/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-error-validation-telemetry-plan.md b/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-error-validation-telemetry-plan.md new file mode 100644 index 00000000..d9b7b19e --- /dev/null +++ b/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-error-validation-telemetry-plan.md @@ -0,0 +1,715 @@ +# Error, Validation, Telemetry, and Failure Boundary Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` or `superpowers:executing-plans` to implement this plan task-by-task. + +**Goal:** Make errors, external validation, observability, and UI failure containment maintainable at extreme domain/traffic scale without global unions/registries or telemetry amplification. + +**Architecture:** Platform code owns generic envelopes and enforcement; features own concrete domain errors, validation schemas/contracts, message mappings, and telemetry payloads. External data is bounded before expensive parsing/mapping. Telemetry passes through a provider-neutral port and bounded pipeline: redact -> fingerprint -> deduplicate -> sample -> bounded buffer -> batch/rate-limit -> transport. Failure boundaries align with app/context/feature ownership. + +**Tech Stack:** TypeScript, current runtime schema system, React Error Boundary mechanism/current router, current HTTP contract layer, provider-neutral telemetry adapter. + +**Spec:** `docs/superpowers/specs/2026-09-23-extreme-scale-frontend-architecture-design.md` + +## Global Constraints + +- No global union of all feature errors or telemetry payloads. +- Feature code cannot import Sentry/Datadog/vendor SDK APIs directly. +- Telemetry failure cannot fail business behavior. +- Buffers, dedup tables, rate windows, payloads, collection size, depth, and string length are bounded. +- Access tokens, refresh tokens, authorization, cookies, passwords, and equivalent secrets are never emitted. +- Validation at frontend trust boundaries does not replace backend validation. +- Do not commit/merge/reset/discard repository changes. + +## Review Focus + +1. An unknown error type must still be represented without extending a global union. +2. A huge/deep malformed payload must be rejected within configured structural limits. +3. Repeated identical browser errors must not produce proportional telemetry network calls. +4. Telemetry transport failure must not reject the business operation. +5. A feature render failure must not collapse unrelated context/app UI. + +--- + +### Task 1: Define the platform error envelope + +**Files:** +- Create: `src/platform/errors/app-error.ts` +- Test: `tests/platform/errors/app-error.test.ts` + +**Interfaces:** +- Produces: + - `AppError` + - `ErrorCategory` + - `ErrorSeverity` + - `Retryability` + - `isAppError()` + +- [ ] **Step 1: Write the failing structural test** + +```ts +it("recognizes feature-owned errors through the platform envelope", () => { + const error = { + kind: "payment.declined", + category: "domain", + severity: "warning", + retryability: "never", + } as const; + + expect(isAppError(error)).toBe(true); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/platform/errors/app-error.test.ts +``` + +- [ ] **Step 3: Implement the generic envelope** + +```ts +export type ErrorCategory = + | "transport" + | "contract" + | "validation" + | "domain" + | "application" + | "platform"; + +export type ErrorSeverity = "info" | "warning" | "error" | "critical"; +export type Retryability = "never" | "safe" | "policy"; + +export interface AppError { + readonly kind: string; + readonly category: ErrorCategory; + readonly severity: ErrorSeverity; + readonly retryability: Retryability; +} +``` + +Do not create a union enumerating all feature `kind` literals. + +- [ ] **Step 4: Run test** + +```bash +pnpm exec vitest run tests/platform/errors/app-error.test.ts +``` + +--- + +### Task 2: Normalize platform/transport errors at the adapter boundary + +**Files:** +- Create: `src/platform/errors/platform-errors.ts` +- Modify: current HTTP executor/transport error mapper from Phase 2 +- Test: `tests/platform/errors/platform-errors.test.ts` + +**Interfaces:** +- Produces concrete platform errors for network unavailable, timeout, cancellation, oversized response, invalid transport response, and traffic-budget exhaustion. + +- [ ] **Step 1: Write a mapper test** + +```ts +it("maps an abort caused by interaction cancellation to request.cancelled", () => { + const error = mapTransportFailure(abortError(), { deadlineExpired: false }); + + expect(error).toMatchObject({ + kind: "request.cancelled", + category: "transport", + retryability: "never", + }); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/platform/errors/platform-errors.test.ts +``` + +- [ ] **Step 3: Implement stable machine-readable platform kinds** + +Use stable kinds such as: +- `network.unavailable` +- `request.timeout` +- `request.cancelled` +- `response.too-large` +- `response.invalid` +- `traffic.budget-exceeded` + +- [ ] **Step 4: Run HTTP/error tests** + +```bash +pnpm exec vitest run tests/platform/errors tests --testNamePattern="http|transport" +``` + +--- + +### Task 3: Prove feature-local domain errors need no global union + +**Files:** +- Create: `src/features/reference-feature/application/reference-error.ts` +- Test: `tests/features/reference-feature/reference-error.test.ts` + +**Interfaces:** +- Consumes: `AppError`. +- Produces `ReferenceError` local union only. + +- [ ] **Step 1: Write the local type/runtime test** + +```ts +type ReferenceError = + | { + readonly kind: "reference.not-found"; + readonly category: "domain"; + readonly severity: "warning"; + readonly retryability: "never"; + } + | { + readonly kind: "reference.conflict"; + readonly category: "domain"; + readonly severity: "warning"; + readonly retryability: "never"; + }; + +it("keeps concrete error kinds feature-local", () => { + const error: ReferenceError = { + kind: "reference.not-found", + category: "domain", + severity: "warning", + retryability: "never", + }; + + expect(isAppError(error)).toBe(true); +}); +``` + +- [ ] **Step 2: Run TypeScript/test checks** + +```bash +pnpm exec vitest run tests/features/reference-feature/reference-error.test.ts +pnpm exec tsc --project tsconfig.app.json --noEmit +``` + +- [ ] **Step 3: Scan against global mega-union creation** + +```bash +rg -n 'Global(Application)?Error|AllFeatureErrors|InstalledFeatureErrors' src +``` + +Expected: no global feature-error union. + +--- + +### Task 4: Add validation budget primitives + +**Files:** +- Create: `src/platform/validation/validation-budget.ts` +- Test: `tests/platform/validation/validation-budget.test.ts` + +**Interfaces:** +- Produces `ValidationBudget` and finite-value validation. + +- [ ] **Step 1: Write failing finite-bound tests** + +```ts +it("rejects unbounded validation configuration", () => { + expect(() => + defineValidationBudget({ + maxBytes: Infinity, + maxItems: 1_000, + maxDepth: 20, + maxStringLength: 32_768, + }), + ).toThrow(/maxBytes/); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/platform/validation/validation-budget.test.ts +``` + +- [ ] **Step 3: Implement** + +```ts +export interface ValidationBudget { + readonly maxBytes: number; + readonly maxItems: number; + readonly maxDepth: number; + readonly maxStringLength: number; +} +``` + +All values must be finite positive safe integers. + +- [ ] **Step 4: Run test** + +```bash +pnpm exec vitest run tests/platform/validation/validation-budget.test.ts +``` + +--- + +### Task 5: Enforce size before parse and structure before mapping + +**Files:** +- Create: `src/platform/validation/bounded-json.ts` +- Modify: current bounded body reader/HTTP response parsing path +- Test: `tests/platform/validation/bounded-json.test.ts` + +**Interfaces:** +- Produces `parseBoundedJson(text, budget)` or equivalent integration with existing body reader. + +- [ ] **Step 1: Write oversized-input test** + +```ts +it("rejects oversized input before JSON.parse is invoked", () => { + const parse = vi.spyOn(JSON, "parse"); + const payload = "x".repeat(101); + + expect(() => + parseBoundedJson(payload, { + maxBytes: 100, + maxItems: 10, + maxDepth: 10, + maxStringLength: 100, + }), + ).toThrow(/too-large/i); + + expect(parse).not.toHaveBeenCalled(); +}); +``` + +- [ ] **Step 2: Add depth/array/string tests** + +```ts +it("rejects arrays above maxItems", () => { + expect(() => validateJsonStructure([1, 2, 3], { ...BUDGET, maxItems: 2 })) + .toThrow(/items/i); +}); +``` + +Add analogous explicit tests for `maxDepth` and `maxStringLength`. + +- [ ] **Step 3: Implement iterative bounded structural traversal** + +Use an explicit stack/queue rather than unbounded recursive descent so adversarial nesting cannot overflow the JS call stack. + +- [ ] **Step 4: Integrate with existing response contract** + +Existing `maxResponseBytes` remains the transport-size ceiling; `ValidationBudget` controls parsed structure. + +- [ ] **Step 5: Run validation/HTTP tests** + +```bash +pnpm exec vitest run tests/platform/validation tests --testNamePattern="response|schema" +``` + +--- + +### Task 6: Define provider-neutral telemetry event and port + +**Files:** +- Create: `src/platform/telemetry/telemetry-event.ts` +- Create: `src/platform/telemetry/telemetry-port.ts` +- Test: `tests/platform/telemetry/telemetry-port.test.ts` + +**Interfaces:** +- Produces: + - `TelemetryEvent` + - `TelemetryPort.emit(event): void | Promise` + +- [ ] **Step 1: Write the compile/runtime test** + +```ts +it("accepts feature-owned payloads through a generic envelope", async () => { + const seen: TelemetryEvent[] = []; + const port: TelemetryPort = { + emit(event) { + seen.push(event); + }, + }; + + await port.emit({ + kind: "reference.load.failed", + severity: "error", + contextId: "reference", + featureId: "reference", + interactionId: "i-1", + payload: { reason: "timeout" }, + }); + + expect(seen).toHaveLength(1); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/platform/telemetry/telemetry-port.test.ts +``` + +- [ ] **Step 3: Implement only the common envelope** + +No Sentry/Datadog/vendor type appears in these interfaces. + +- [ ] **Step 4: Run test** + +```bash +pnpm exec vitest run tests/platform/telemetry/telemetry-port.test.ts +``` + +--- + +### Task 7: Implement telemetry redaction before buffering + +**Files:** +- Create: `src/platform/telemetry/redact-telemetry.ts` +- Test: `tests/platform/telemetry/redact-telemetry.test.ts` + +**Interfaces:** +- Produces `redactTelemetryPayload()`. + +- [ ] **Step 1: Write secret-removal tests** + +```ts +it.each([ + "password", + "authorization", + "cookie", + "accessToken", + "refreshToken", +])("redacts %s recursively", (secretKey) => { + const input = { nested: { [secretKey]: "secret", safe: "ok" } }; + const result = redactTelemetryPayload(input); + + expect(JSON.stringify(result)).not.toContain("secret"); + expect(result).toMatchObject({ nested: { safe: "ok" } }); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/platform/telemetry/redact-telemetry.test.ts +``` + +- [ ] **Step 3: Implement bounded recursive/iterative sanitizer** + +Do not preserve prototypes or execute getters from untrusted payloads. Cap traversal using the telemetry payload structural budget. + +- [ ] **Step 4: Run test** + +```bash +pnpm exec vitest run tests/platform/telemetry/redact-telemetry.test.ts +``` + +--- + +### Task 8: Implement deterministic fingerprinting and bounded deduplication + +**Files:** +- Create: `src/platform/telemetry/telemetry-fingerprint.ts` +- Create: `src/platform/telemetry/telemetry-deduplicator.ts` +- Test: `tests/platform/telemetry/telemetry-deduplicator.test.ts` + +**Interfaces:** +- Produces: + - `fingerprintTelemetryEvent()` + - `TelemetryDeduplicator(maxEntries, windowMs)` + +- [ ] **Step 1: Write repeated-error test** + +```ts +it("collapses repeated identical failures into one active fingerprint entry", () => { + const dedup = new TelemetryDeduplicator({ maxEntries: 100, windowMs: 60_000 }); + + for (let i = 0; i < 10_000; i += 1) { + dedup.record(FINGERPRINT, i); + } + + expect(dedup.size).toBe(1); + expect(dedup.count(FINGERPRINT)).toBe(10_000); +}); +``` + +- [ ] **Step 2: Add capacity test** + +```ts +it("never retains more than maxEntries fingerprints", () => { + const dedup = new TelemetryDeduplicator({ maxEntries: 2, windowMs: 60_000 }); + dedup.record("a", 1); + dedup.record("b", 2); + dedup.record("c", 3); + + expect(dedup.size).toBe(2); +}); +``` + +- [ ] **Step 3: Implement bounded LRU/window eviction** + +- [ ] **Step 4: Run tests** + +```bash +pnpm exec vitest run tests/platform/telemetry/telemetry-deduplicator.test.ts +``` + +--- + +### Task 9: Implement deterministic sampling and bounded buffer + +**Files:** +- Create: `src/platform/telemetry/telemetry-sampler.ts` +- Create: `src/platform/telemetry/telemetry-buffer.ts` +- Test: `tests/platform/telemetry/telemetry-buffer.test.ts` + +**Interfaces:** +- Produces deterministic sampling by interaction/trace key and bounded event/byte buffer. + +- [ ] **Step 1: Write deterministic sampling test** + +```ts +it("makes the same sampling decision for the same stable key", () => { + const sampler = createDeterministicSampler({ rate: 0.1 }); + + expect(sampler.keep("interaction-123")).toBe(sampler.keep("interaction-123")); +}); +``` + +- [ ] **Step 2: Write bounded buffer test** + +```ts +it("never exceeds event or byte ceilings", () => { + const buffer = createTelemetryBuffer({ + maxEvents: 2, + maxBytes: 1_024, + }); + + buffer.push(infoEvent("a")); + buffer.push(infoEvent("b")); + buffer.push(criticalEvent("c")); + + expect(buffer.size).toBeLessThanOrEqual(2); + expect(buffer.bytes).toBeLessThanOrEqual(1_024); + expect(buffer.items.some((item) => item.severity === "critical")).toBe(true); +}); +``` + +- [ ] **Step 3: Implement severity-aware drop policy** + +Lowest-priority events are evicted/dropped first; buffer growth is never used as backpressure. + +- [ ] **Step 4: Run tests** + +```bash +pnpm exec vitest run tests/platform/telemetry/telemetry-buffer.test.ts +``` + +--- + +### Task 10: Implement rate-limited fail-open telemetry pipeline + +**Files:** +- Create: `src/platform/telemetry/telemetry-pipeline.ts` +- Test: `tests/platform/telemetry/telemetry-pipeline.test.ts` + +**Interfaces:** +- Consumes redaction, fingerprinting, dedup, sampler, buffer, provider transport. +- Produces `TelemetryPipeline.emit()` that never throws into business behavior. + +- [ ] **Step 1: Write transport-failure test** + +```ts +it("does not reject business flow when telemetry transport fails", async () => { + const pipeline = createTelemetryPipeline({ + transport: { + async send() { + throw new Error("collector unavailable"); + }, + }, + budget: TEST_TELEMETRY_BUDGET, + }); + + await expect(pipeline.emit(TEST_EVENT)).resolves.toBeUndefined(); +}); +``` + +- [ ] **Step 2: Write storm-bound test** + +```ts +it("bounds network sends during a repeated error storm", async () => { + const send = vi.fn().mockResolvedValue(undefined); + const pipeline = createTelemetryPipeline({ + transport: { send }, + budget: { ...TEST_TELEMETRY_BUDGET, maxSendsPerMinute: 10 }, + }); + + for (let i = 0; i < 100_000; i += 1) { + await pipeline.emit(REPEATED_ERROR); + } + + await pipeline.flush(); + expect(send.mock.calls.length).toBeLessThanOrEqual(10); +}); +``` + +- [ ] **Step 3: Implement the fixed pipeline order** + +```text +redact +fingerprint +deduplicate +sample +buffer +rate limit +batch +transport +``` + +Every internal exception is swallowed or converted to an internal dropped-event counter; it never rejects the business caller. + +- [ ] **Step 4: Run telemetry tests** + +```bash +pnpm exec vitest run tests/platform/telemetry +``` + +--- + +### Task 11: Add trace/correlation propagation to execution and transport + +**Files:** +- Create: `src/platform/telemetry/trace-context.ts` +- Modify: `src/platform/execution/execution-context.ts` +- Modify: current HTTP request header builder +- Test: `tests/platform/telemetry/trace-context.test.ts` + +**Interfaces:** +- Produces stable interaction/trace context and valid `traceparent`/correlation metadata according to the existing server contract. + +- [ ] **Step 1: Write propagation test** + +```ts +it("propagates one interaction trace identity to child requests", () => { + const context = testExecutionContext({ interactionId: "i-1", traceId: VALID_TRACE_ID }); + + const a = buildRequestHeaders(context); + const b = buildRequestHeaders(context); + + expect(a.get("traceparent")).toBe(b.get("traceparent")); + expect(a.get("x-correlation-id")).toBe("i-1"); +}); +``` + +- [ ] **Step 2: Verify RED and then implement** + +Use existing header conventions if the repository already defines them; do not introduce duplicate competing correlation headers. + +- [ ] **Step 3: Run tests** + +```bash +pnpm exec vitest run tests/platform/telemetry/trace-context.test.ts +``` + +--- + +### Task 12: Align React failure boundaries with ownership boundaries + +**Files:** +- Create: `src/platform/errors/feature-error-boundary.tsx` +- Create: `src/platform/errors/context-error-boundary.tsx` +- Modify: context/feature route composition from Phase 1 +- Test: `tests/platform/errors/failure-boundary.test.tsx` + +**Interfaces:** +- Produces feature- and context-scoped render containment. + +- [ ] **Step 1: Write the isolation test** + +```tsx +it("keeps sibling feature UI mounted when one feature throws during render", () => { + render( + + + + +
healthy-feature
+
, + ); + + expect(screen.getByText("healthy-feature")).toBeInTheDocument(); + expect(screen.getByTestId("feature-fallback-broken")).toBeInTheDocument(); +}); +``` + +- [ ] **Step 2: Verify RED** + +Run the repository's existing React test command for this file. + +- [ ] **Step 3: Implement scoped boundaries** + +Feature fallback contains feature-local render failures; context boundary is the next escalation. Do not add an ErrorBoundary around every leaf component. + +- [ ] **Step 4: Run UI/router tests** + +Run the existing React/router test suite. + +--- + +### Task 13: Close Phase 3 with global-union/vendor-import/boundedness gates + +**Files:** +- Create: `tests/architecture/observability-boundaries.test.ts` +- Modify: `.dependency-cruiser.json` +- Modify: `package.json` + +**Interfaces:** +- Produces `check:observability`. + +- [ ] **Step 1: Add architecture prohibition for vendor SDKs in feature code** + +Dependency rule: + +```text +src/features/** + X +@sentry/* +@datadog/* +vendor telemetry SDK package names present in package.json +``` + +Only platform adapter code may import configured observability vendors. + +- [ ] **Step 2: Add a source scan test against global mega unions** + +```ts +it("does not define installed/global unions of all feature errors or telemetry payloads", async () => { + const source = await readProductionSources(); + expect(source).not.toMatch(/AllFeatureErrors|GlobalFeatureErrors|AllTelemetryEvents/); +}); +``` + +- [ ] **Step 3: Add script** + +```json +{ + "scripts": { + "check:observability": "vitest run tests/platform/errors tests/platform/validation tests/platform/telemetry tests/architecture/observability-boundaries.test.ts" + } +} +``` + +- [ ] **Step 4: Run Phase 3 verification** + +```bash +pnpm run check:architecture +pnpm run check:observability +pnpm exec tsc --project tsconfig.app.json --noEmit +pnpm exec tsc --project tsconfig.test.json --noEmit +``` + +- [ ] **Step 5: Phase decision** + +**์™„๋ฃŒ** only if concrete errors remain local, validation cost is bounded, telemetry is provider-neutral/bounded/fail-open, secrets are redacted, and feature/context render failures are isolated. Otherwise **์•„์ง ๋” ๋ด์•ผ๋Œ**. diff --git a/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-execution-traffic-plan.md b/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-execution-traffic-plan.md new file mode 100644 index 00000000..88e7e2e7 --- /dev/null +++ b/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-execution-traffic-plan.md @@ -0,0 +1,594 @@ +# Execution Context and Traffic Resilience Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` or `superpowers:executing-plans` to implement this plan task-by-task. + +**Goal:** Make every user interaction carry bounded physical-request, retry, concurrency, cancellation, and deadline semantics so spike traffic and slow/failing backends cannot cause unbounded client-side amplification. + +**Architecture:** `ExecutionContext` is created once per user/application interaction and passed through application/adapter boundaries. `TrafficBudget` is immutable configuration; mutable counters/leases are interaction-local runtime state. Retry consumes a shared interaction budget, concurrency uses cancellable leases, and every physical request uses the remaining interaction deadline rather than restarting independent timeouts. + +**Tech Stack:** TypeScript, current HTTP operation executor, AbortController, current retry/idempotency implementation, TanStack Query integration points. + +**Spec:** `docs/superpowers/specs/2026-09-23-extreme-scale-frontend-architecture-design.md` + +## Global Constraints + +- No unbounded retry, request fan-out, concurrency, waiting queue, or timeout reset. +- Existing idempotency/replay-safety semantics remain authoritative. +- Retry budget is interaction-scoped, not request-scoped. +- Cancellation propagates to queue waits, in-flight transport, retry delay, and dedup waiters. +- Telemetry integration is deferred to Phase 3 but event hooks must not require vendor SDKs. +- Do not commit/merge/reset/discard repository changes. + +## Review Focus + +1. Two failing requests in the same interaction compete for one shared retry budget. +2. An aborted interaction releases all concurrency leases and waiting queue entries. +3. A retry started late cannot extend the original interaction deadline. +4. Collection cardinality growth must not create proportional physical requests. +5. Safe/idempotent retry rules from the current HTTP layer must remain intact. + +--- + +### Task 1: Add interaction identity and execution context + +**Files:** +- Create: `src/platform/execution/execution-context.ts` +- Test: `tests/platform/execution/execution-context.test.ts` + +**Interfaces:** +- Produces: + - `InteractionId` + - `ExecutionContext` + - `createExecutionContext(options)` + +- [ ] **Step 1: Write the failing test** + +```ts +it("creates one immutable root context with one abort signal and absolute deadline", () => { + const now = 1_000; + const context = createExecutionContext({ + interactionId: "interaction-1", + startedAt: now, + deadlineMs: 5_000, + traffic: { + maxPhysicalRequests: 4, + maxConcurrentRequests: 2, + maxRetries: 1, + }, + }); + + expect(context.interaction.deadlineAt).toBe(6_000); + expect(context.cancellation.signal.aborted).toBe(false); + expect(Object.isFrozen(context.interaction)).toBe(true); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/platform/execution/execution-context.test.ts +``` + +- [ ] **Step 3: Implement immutable configuration and private mutable budget state** + +```ts +export interface ExecutionContext { + readonly interaction: { + readonly id: string; + readonly startedAt: number; + readonly deadlineAt: number; + }; + readonly cancellation: { + readonly signal: AbortSignal; + }; + readonly traffic: TrafficRuntime; +} +``` + +`TrafficRuntime` is defined in later tasks and is injected by `createExecutionContext()`. + +- [ ] **Step 4: Run focused test** + +```bash +pnpm exec vitest run tests/platform/execution/execution-context.test.ts +``` + +--- + +### Task 2: Implement physical request budget + +**Files:** +- Create: `src/platform/traffic/request-budget.ts` +- Test: `tests/platform/traffic/request-budget.test.ts` + +**Interfaces:** +- Produces: + - `RequestBudgetExceededError` + - `RequestBudget` + - `createRequestBudget(maxPhysicalRequests)` + +- [ ] **Step 1: Write failing tests** + +```ts +it("allows exactly the configured number of physical requests", () => { + const budget = createRequestBudget(2); + expect(budget.tryConsume()).toBe(true); + expect(budget.tryConsume()).toBe(true); + expect(budget.tryConsume()).toBe(false); + expect(budget.consumed).toBe(2); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/platform/traffic/request-budget.test.ts +``` + +- [ ] **Step 3: Implement monotonic bounded consumption** + +```ts +export interface RequestBudget { + readonly maximum: number; + readonly consumed: number; + tryConsume(): boolean; +} +``` + +Reject non-positive/non-safe-integer maxima at construction. + +- [ ] **Step 4: Run test** + +```bash +pnpm exec vitest run tests/platform/traffic/request-budget.test.ts +``` + +--- + +### Task 3: Implement interaction-scoped retry budget + +**Files:** +- Create: `src/platform/resilience/retry-budget.ts` +- Test: `tests/platform/resilience/retry-budget.test.ts` + +**Interfaces:** +- Produces `RetryBudget`. + +- [ ] **Step 1: Write the shared-budget test** + +```ts +it("shares retry capacity across independent requests in the same interaction", () => { + const budget = createRetryBudget(1); + + expect(budget.tryConsume("request-a")).toBe(true); + expect(budget.tryConsume("request-b")).toBe(false); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/platform/resilience/retry-budget.test.ts +``` + +- [ ] **Step 3: Implement** + +```ts +export interface RetryBudget { + readonly maximum: number; + readonly consumed: number; + tryConsume(requestId: string): boolean; +} +``` + +Do not reset this budget per request. + +- [ ] **Step 4: Run focused tests** + +```bash +pnpm exec vitest run tests/platform/resilience/retry-budget.test.ts +``` + +--- + +### Task 4: Implement cancellable concurrency leases with bounded waiting + +**Files:** +- Create: `src/platform/traffic/concurrency-budget.ts` +- Test: `tests/platform/traffic/concurrency-budget.test.ts` + +**Interfaces:** +- Produces: + - `ConcurrencyLease` + - `ConcurrencyBudget` + - `createConcurrencyBudget({ maximum, maxQueued })` + +- [ ] **Step 1: Write the concurrency and abort tests** + +```ts +it("never grants more than maximum simultaneous leases", async () => { + const budget = createConcurrencyBudget({ maximum: 2, maxQueued: 1 }); + const first = await budget.acquire(new AbortController().signal); + const second = await budget.acquire(new AbortController().signal); + + expect(budget.active).toBe(2); + await expect(budget.acquire(new AbortController().signal)).rejects.toThrow(/queue/i); + + first.release(); + second.release(); +}); + +it("removes an aborted waiter", async () => { + const budget = createConcurrencyBudget({ maximum: 1, maxQueued: 1 }); + const lease = await budget.acquire(new AbortController().signal); + const controller = new AbortController(); + const waiting = budget.acquire(controller.signal); + controller.abort(); + + await expect(waiting).rejects.toMatchObject({ name: "AbortError" }); + lease.release(); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/platform/traffic/concurrency-budget.test.ts +``` + +- [ ] **Step 3: Implement FIFO bounded waiters** + +Each lease is idempotently releasable. An abort listener removes its waiter immediately. `maxQueued` is mandatory and finite. + +- [ ] **Step 4: Run focused tests** + +```bash +pnpm exec vitest run tests/platform/traffic/concurrency-budget.test.ts +``` + +--- + +### Task 5: Implement absolute deadline propagation + +**Files:** +- Create: `src/platform/resilience/deadline.ts` +- Test: `tests/platform/resilience/deadline.test.ts` + +**Interfaces:** +- Produces: + - `remainingDeadlineMs(deadlineAt, now)` + - `DeadlineExceededError` + +- [ ] **Step 1: Write the no-timeout-reset test** + +```ts +it("returns only time remaining from the original absolute deadline", () => { + expect(remainingDeadlineMs(6_000, 1_000)).toBe(5_000); + expect(remainingDeadlineMs(6_000, 5_500)).toBe(500); + expect(() => remainingDeadlineMs(6_000, 6_001)).toThrow(DeadlineExceededError); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/platform/resilience/deadline.test.ts +``` + +- [ ] **Step 3: Implement with monotonic caller-provided time** + +The helper does not call `Date.now()` internally; callers provide `now` so fake clocks and monotonic clocks can be used. + +- [ ] **Step 4: Run test** + +```bash +pnpm exec vitest run tests/platform/resilience/deadline.test.ts +``` + +--- + +### Task 6: Create one traffic runtime from immutable policy + +**Files:** +- Create: `src/platform/traffic/traffic-budget.ts` +- Modify: `src/platform/execution/execution-context.ts` +- Test: `tests/platform/traffic/traffic-budget.test.ts` + +**Interfaces:** +- Produces: + - `TrafficBudget` + - `TrafficRuntime` + - `createTrafficRuntime(policy)` + +- [ ] **Step 1: Write composition test** + +```ts +it("creates one request, retry, and concurrency budget per interaction", () => { + const runtime = createTrafficRuntime({ + maxPhysicalRequests: 4, + maxRetries: 1, + maxConcurrentRequests: 2, + maxQueuedRequests: 2, + }); + + expect(runtime.requests.maximum).toBe(4); + expect(runtime.retries.maximum).toBe(1); + expect(runtime.concurrency.maximum).toBe(2); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/platform/traffic/traffic-budget.test.ts +``` + +- [ ] **Step 3: Implement immutable policy + mutable runtime separation** + +```ts +export interface TrafficBudget { + readonly maxPhysicalRequests: number; + readonly maxRetries: number; + readonly maxConcurrentRequests: number; + readonly maxQueuedRequests: number; +} +``` + +`ExecutionContext` creates the runtime once and shares it with all child operations. + +- [ ] **Step 4: Run execution/traffic tests** + +```bash +pnpm exec vitest run tests/platform/execution tests/platform/traffic tests/platform/resilience +``` + +--- + +### Task 7: Attach traffic policy to operation contracts + +**Files:** +- Modify: current HTTP operation-contract type file identified by the Phase 1 baseline map +- Modify: representative reference-feature operation contract +- Test: existing operation-contract tests plus `tests/platform/traffic/operation-traffic-policy.test.ts` + +**Interfaces:** +- Consumes: `TrafficBudget`. +- Produces operation metadata with explicit bounded request policy. + +- [ ] **Step 1: Write a failing operation policy test** + +```ts +it("requires finite positive traffic limits for an operation", () => { + expect(() => + defineQueryOperation({ + id: "reference.list", + traffic: { + maxPhysicalRequests: Number.POSITIVE_INFINITY, + maxRetries: 1, + maxConcurrentRequests: 2, + maxQueuedRequests: 2, + }, + }), + ).toThrow(/traffic/i); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/platform/traffic/operation-traffic-policy.test.ts +``` + +- [ ] **Step 3: Extend operation contracts** + +Query/command operation definitions carry immutable traffic policy. Preserve current semantics/idempotency/replay metadata. + +- [ ] **Step 4: Run operation contract tests** + +```bash +pnpm exec vitest run tests --testNamePattern="operation" +``` + +--- + +### Task 8: Integrate budgets into the physical HTTP dispatch path + +**Files:** +- Modify: the current HTTP executor file identified in the Phase 1 baseline map by searching `maxResponseBytes`, retry lifecycle, and `Retry-After` +- Test: current HTTP executor tests plus `tests/platform/traffic/http-budget-integration.test.ts` + +**Interfaces:** +- Consumes: `ExecutionContext`, operation traffic policy, current safe-retry logic. +- Produces: one bounded physical-dispatch path. + +- [ ] **Step 1: Add a failing request-budget integration test** + +```ts +it("does not dispatch after the interaction physical-request budget is exhausted", async () => { + const transport = vi.fn().mockRejectedValue(new TypeError("network")); + const context = testExecutionContext({ + maxPhysicalRequests: 1, + maxRetries: 3, + }); + + await expect(executeHttpOperation(TEST_QUERY, context, transport)).rejects.toBeDefined(); + expect(transport).toHaveBeenCalledTimes(1); +}); +``` + +- [ ] **Step 2: Add a failing deadline integration test** + +```ts +it("does not reset the interaction deadline before retry", async () => { + const clock = fakeClock([0, 4_900, 5_001]); + const transport = vi.fn().mockRejectedValue(new TypeError("network")); + + await expect( + executeHttpOperation(TEST_QUERY, testExecutionContext({ deadlineMs: 5_000, clock }), transport), + ).rejects.toThrow(/deadline/i); +}); +``` + +- [ ] **Step 3: Run focused test and verify RED** + +```bash +pnpm exec vitest run tests/platform/traffic/http-budget-integration.test.ts +``` + +- [ ] **Step 4: Integrate enforcement in this order** + +```text +check cancellation +check remaining deadline +consume physical request budget +acquire concurrency lease +dispatch +release lease +classify failure +verify existing retry safety/idempotency +consume shared retry budget +wait jittered backoff bounded by remaining deadline +repeat +``` + +- [ ] **Step 5: Run complete HTTP tests** + +```bash +pnpm exec vitest run tests --testNamePattern="http|retry|idempot" +``` + +Expected: current retry/idempotency behavior remains green, new budgets pass. + +--- + +### Task 9: Add request fan-out budget to representative collection flows + +**Files:** +- Create: `src/platform/traffic/request-fanout.ts` +- Test: `tests/platform/traffic/request-fanout.test.ts` +- Modify: representative reference-feature collection use case/test fixture + +**Interfaces:** +- Produces: `assertRequestFanoutWithinBudget()` for integration tests/diagnostics. + +- [ ] **Step 1: Write cardinality-independent request-count test** + +```ts +it.each([10, 100, 1_000])( + "does not create one physical request per row for %i rows", + async (rows) => { + const transport = vi.fn().mockResolvedValue(fakeCollectionResponse(rows)); + + await loadReferenceCollection({ rows, transport }); + + expect(transport.mock.calls.length).toBeLessThanOrEqual(3); + }, +); +``` + +- [ ] **Step 2: Verify current behavior** + +Run the test. If it already passes, preserve it as a regression gate. If it fails, replace per-row transport with a bounded bulk/read-model operation before continuing. + +- [ ] **Step 3: Implement the assertion utility** + +```ts +export function assertRequestFanoutWithinBudget( + physicalRequests: number, + maximum: number, +): void { + if (physicalRequests > maximum) { + throw new Error(`Request fan-out ${physicalRequests} exceeds ${maximum}`); + } +} +``` + +- [ ] **Step 4: Run focused tests** + +```bash +pnpm exec vitest run tests/platform/traffic/request-fanout.test.ts +``` + +--- + +### Task 10: Add dedup/coalescing regression coverage + +**Files:** +- Test: `tests/platform/traffic/request-deduplication.test.ts` +- Modify: current TanStack Query/client request integration only if the test exposes a duplicate-dispatch gap + +**Interfaces:** +- Consumes: current query cache/in-flight behavior. +- Produces proof that multiple consumers do not imply multiple physical requests for one query identity. + +- [ ] **Step 1: Write the concurrent-consumer test** + +```ts +it("coalesces concurrent consumers of the same query identity", async () => { + const transport = vi.fn().mockResolvedValue({ items: [] }); + + await Promise.all([ + loadSameQuery(transport), + loadSameQuery(transport), + loadSameQuery(transport), + ]); + + expect(transport).toHaveBeenCalledTimes(1); +}); +``` + +- [ ] **Step 2: Run and verify** + +```bash +pnpm exec vitest run tests/platform/traffic/request-deduplication.test.ts +``` + +If current TanStack Query integration already satisfies it, no production modification is made. + +--- + +### Task 11: Close Phase 2 with amplification invariants + +**Files:** +- Create: `tests/platform/traffic/traffic-amplification.test.ts` +- Modify: `package.json` + +**Interfaces:** +- Produces `check:traffic`. + +- [ ] **Step 1: Write an outage amplification bound** + +```ts +it("keeps physical requests bounded when every dispatch fails", async () => { + const transport = vi.fn().mockRejectedValue(new TypeError("network")); + const interactions = Array.from({ length: 1_000 }, () => + runInteraction({ transport, maxPhysicalRequests: 2, maxRetries: 1 }), + ); + + await Promise.allSettled(interactions); + + expect(transport.mock.calls.length).toBeLessThanOrEqual(2_000); +}); +``` + +- [ ] **Step 2: Add the check script** + +```json +{ + "scripts": { + "check:traffic": "vitest run tests/platform/execution tests/platform/traffic tests/platform/resilience" + } +} +``` + +- [ ] **Step 3: Run Phase 2 verification** + +```bash +pnpm run check:traffic +pnpm exec tsc --project tsconfig.app.json --noEmit +pnpm exec tsc --project tsconfig.test.json --noEmit +``` + +- [ ] **Step 4: Phase decision** + +**์™„๋ฃŒ** only if physical requests, retries, concurrency queues, and deadlines are all explicitly bounded and existing retry/idempotency semantics remain green. Otherwise **์•„์ง ๋” ๋ด์•ผ๋Œ**. diff --git a/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-extreme-scale-frontend-master-plan.md b/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-extreme-scale-frontend-master-plan.md new file mode 100644 index 00000000..9d2e0ff4 --- /dev/null +++ b/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-extreme-scale-frontend-master-plan.md @@ -0,0 +1,113 @@ +# Extreme-Scale Frontend Architecture Implementation Master Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` (recommended where a subagent runner exists) or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Evolve `clean-architecture-frontend-template` so global product growth toward 1,000,000 logical features is partitioned into bounded local build/runtime graphs, while spike traffic, sustained traffic, failures, validation, telemetry, and multi-replica releases remain explicitly bounded and testable. + +**Architecture:** The implementation is deliberately split into five independently reviewable plans. Product growth is modeled as `Product -> Deployable App -> Bounded Context -> Feature -> Operation`, and no parent flattens all descendants into a global registry. Runtime work is rooted in an interaction-scoped execution context that carries request, retry, concurrency, cancellation, and deadline budgets. Error, validation, telemetry, scale testing, and release coherence all use the same bounded-cardinality principle. + +**Tech Stack:** TypeScript, React, Vite, TanStack Query, existing HTTP operation-contract layer, Vitest/current unit-test runner, dependency-cruiser/current architecture checks, Node-based scale harnesses, current release-manifest/runtime-config implementation. + +**Spec:** `docs/superpowers/specs/2026-09-23-extreme-scale-frontend-architecture-design.md` + +## Global Constraints + +- Global logical feature count may reach 100, 1,000, 10,000, 100,000, or 1,000,000; one SPA must never compile or boot that entire global graph. +- No cardinality may become implicitly unbounded. +- Normal feature addition should change only the feature-owned directory plus generated indexes; central handwritten installation registries are not the extension mechanism. +- No runtime discovery of arbitrary remote code or untrusted dynamic import paths. +- Preserve existing Clean Architecture layer rules, capability-driven adapter composition, HTTP operation contracts, response-size bounds, retry/idempotency semantics, TanStack Query ownership, scope fencing, and release/build/config coherence. +- Frontend validation improves UX and protects local runtime cost; backend validation remains authoritative. +- Telemetry must be best-effort and must not fail business behavior. +- No global mega-error union, telemetry union, route registry, feature registry, or compile graph. +- No source UI/design changes are required for this architecture work. +- Project repository instruction overrides generic workflow defaults: do not run destructive git commands, commit, merge, or discard existing changes. +- Existing-file paths in the phase plans are based on the last verified `origin/main` snapshot from 2026-09-23. At execution start, verify those paths against the live worktree; if a listed existing path moved, update the plan mapping before code edits instead of guessing. + +## Review Focus + +1. **Global topology grows while one app is unchanged** โ€” the unchanged app's generated index, initial route graph, bundle inputs, and compile graph must not grow materially. +2. **Backend failure coincides with user spike** โ€” retry, concurrency, and telemetry must remain bounded instead of multiplying the incident. +3. **Malformed or oversized external payload** โ€” size/structure limits must stop expensive parsing or mapping before unbounded CPU/memory work. +4. **One feature/context fails** โ€” unrelated contexts/features must continue to render and execute. +5. **Rolling release mixes replicas** โ€” coherent release tuples boot; mismatched HTML/config/manifest/assets fail closed without reload loops. + +--- + +## Phase Order + +1. `2026-09-23-topology-composition-plan.md` +2. `2026-09-23-execution-traffic-plan.md` +3. `2026-09-23-error-validation-telemetry-plan.md` +4. `2026-09-23-scale-chaos-soak-plan.md` +5. `2026-09-23-release-coherence-plan.md` + +Each phase must be **์™„๋ฃŒ** before moving to the next. If any acceptance condition is not met, its status is **์•„์ง ๋” ๋ด์•ผ๋Œ**. + +### Phase 1 exit contract + +Produces: +- `FeatureModule` +- `BoundedContextModule` +- `DeployableAppModule` +- deterministic generated static indexes +- O(N) duplicate-safe composition +- indexed membership +- cross-feature/context import gates +- hierarchical route ownership +- explicit cardinality budgets + +### Phase 2 exit contract + +Produces: +- `ExecutionContext` +- interaction-scoped `TrafficBudget` +- request/retry/concurrency/deadline/cancellation enforcement +- request fan-out budget +- request dedup/coalescing integration points + +### Phase 3 exit contract + +Produces: +- typed local error model without global union +- bounded trust-boundary validation +- provider-neutral `TelemetryPort` +- redaction, fingerprinting, deduplication, deterministic sampling, bounded buffering, rate limiting +- failure boundaries aligned to app/context/feature ownership + +### Phase 4 exit contract + +Produces: +- S0/S1/S2 runtime/compiler fixtures +- S3/S4 topology simulation up to 1,000,000 logical features +- complexity-growth regression gates +- request/retry/telemetry amplification tests +- slow API, partial/total failure, network flap, telemetry-outage scenarios +- soak/long-session memory-slope checks +- PR/main/nightly/release test-tier commands + +### Phase 5 exit contract + +Produces: +- multi-replica release-coherence matrix +- old hashed-asset reachability checks +- mixed release fail-closed tests +- no reload-loop proof +- deployment contract documentation/gates + +## Final Verification + +- [x] Run app TypeScript check. +- [x] Run test TypeScript check. +- [x] Run architecture check. +- [x] Run complete unit/integration test suite. +- [x] Run S0/S1 PR scale profile. +- [x] Run S2 main scale profile. +- [x] Run S3/S4 topology simulation. +- [x] Run traffic amplification suite. +- [x] Run telemetry-storm suite. +- [x] Run release-coherence matrix. +- [x] Compare current architecture budgets and benchmark artifacts against baselines. (`pnpm check:scale:baseline` against the approved `config/scale/benchmark-baseline.json`; also the `baseline-regression` step of `check:scale:{main,nightly,release}`.) +- [x] Confirm no normal feature addition requires multiple central handwritten registry edits. +- [x] Confirm no unrelated feature-to-feature concrete import can pass architecture checks. +- [x] Confirm the final implementation meets every acceptance criterion in spec section 54. diff --git a/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-release-coherence-plan.md b/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-release-coherence-plan.md new file mode 100644 index 00000000..24871de7 --- /dev/null +++ b/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-release-coherence-plan.md @@ -0,0 +1,307 @@ +# Multi-Replica Release Coherence Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` or `superpowers:executing-plans` to implement this plan task-by-task. + +**Goal:** Prove frontend horizontal scaling remains safe during rolling releases by enforcing coherent HTML/runtime-config/manifest/assets, immutable old assets, fail-closed mismatch behavior, and no reload loops. + +**Architecture:** Stateless frontend replicas may scale horizontally without sticky sessions only when every boot observes a coherent release tuple. HTML is revalidated/no-cache, runtime config and release manifest are no-store, hashed assets are immutable and never overwritten, and old hashed assets remain reachable for clients that loaded an older HTML document. + +**Tech Stack:** Current release manifest/runtime config validation, static asset deployment model, current HTTP/static test harness, Node/browser integration tests. + +**Spec:** `docs/superpowers/specs/2026-09-23-extreme-scale-frontend-architecture-design.md` + +## Global Constraints + +- No hosting-instance user session is introduced. +- Hashed assets are immutable and release-addressable. +- Runtime config and release manifest are never cached as immutable assets. +- Release mismatch fails closed; it must not limp forward with mixed contract/build identity. +- Fail-closed handling must not create infinite reload loops. +- Old release assets stay reachable through the rolling window. +- Do not commit/merge/reset/discard repository changes. + +## Review Focus + +1. R10 HTML + R11 config must fail before application bootstrap. +2. A browser holding R10 HTML during R11 rollout must still fetch R10 hashed assets successfully. +3. Two replicas serving R10/R11 during rollout must not produce a silently mixed boot. +4. A mismatch must not cause an automatic reload loop. +5. CDN/LB caching headers must preserve HTML/config/manifest coherence assumptions. + +--- + +### Task 1: Capture the existing release identity contract + +**Files:** +- Read: current runtime-config loader +- Read: current release-manifest validator +- Read: current static-delivery/cache policy docs/config +- Create: `docs/reviews/2026-09-23-release-coherence-baseline.md` + +**Interfaces:** +- Produces exact current fields for build id, release id, config identity, asset identity, and contract identity. + +- [ ] **Step 1: Locate existing release identity code** + +```bash +rg -n 'releaseId|buildId|manifest|runtime.?config|no-store|immutable|max-age=31536000' src public docs nginx* . 2>/dev/null +``` + +- [ ] **Step 2: Record only verified fields/paths** + +Baseline document lists the exact current identity tuple and cache directives. No new format is invented if current code already covers it. + +- [ ] **Step 3: Run existing release/config tests** + +Use the test files named by the search results. They must be green before changes. + +--- + +### Task 2: Extract one pure release-coherence validator + +**Files:** +- Create: `src/platform/release/release-coherence.ts` +- Modify: current boot/release validation path to delegate to it +- Test: `tests/platform/release/release-coherence.test.ts` + +**Interfaces:** +- Produces: + - `ReleaseIdentity` + - `assertReleaseCoherent(htmlIdentity, configIdentity, manifestIdentity)` + +- [ ] **Step 1: Write the coherence matrix** + +```ts +it.each([ + ["R10", "R10", "R10", true], + ["R10", "R11", "R10", false], + ["R10", "R10", "R11", false], + ["R11", "R11", "R11", true], +])( + "HTML %s config %s manifest %s => coherent=%s", + (html, config, manifest, coherent) => { + const run = () => + assertReleaseCoherent( + identity(html), + identity(config), + identity(manifest), + ); + + if (coherent) expect(run).not.toThrow(); + else expect(run).toThrow(/release.*mismatch/i); + }, +); +``` + +- [ ] **Step 2: Verify RED/coverage against current code** + +- [ ] **Step 3: Implement one pure fail-closed validator** + +Compare every identity field that the current release contract treats as boot-critical. Return no partial-success state. + +- [ ] **Step 4: Run tests** + +```bash +pnpm exec vitest run tests/platform/release/release-coherence.test.ts +``` + +--- + +### Task 3: Add cache-policy contract tests + +**Files:** +- Create: `tests/platform/release/cache-policy.test.ts` +- Modify: current static-server/deployment config only if tests reveal a mismatch + +**Interfaces:** +- Produces cache policy assertions. + +- [ ] **Step 1: Assert immutable hashed assets** + +Expected directive includes: + +```text +public, max-age=31536000, immutable +``` + +- [ ] **Step 2: Assert HTML is revalidated/not immutable** + +Expected: HTML does not carry immutable long-lived caching. + +- [ ] **Step 3: Assert runtime config and release manifest are `no-store`** + +Both resources must not be reused across release identity changes. + +- [ ] **Step 4: Run test** + +Use the repository's static-config test mechanism. If cache headers are generated outside TypeScript, parse that configuration as text in the test rather than duplicating values in production code. + +--- + +### Task 4: Model two releases and old-asset reachability + +**Files:** +- Create: `tests/release/fixtures/R10/` +- Create: `tests/release/fixtures/R11/` +- Create: `tests/release/old-asset-reachability.test.ts` + +**Interfaces:** +- Produces immutable fixture artifacts for two release tuples. + +- [ ] **Step 1: Create distinct hashed assets** + +Fixture example: + +```text +R10/assets/app.aaaa.js +R11/assets/app.bbbb.js +``` + +- [ ] **Step 2: Write reachability test** + +```ts +it("keeps R10 hashed assets reachable after R11 becomes active", async () => { + const deployment = createReleaseFixture(["R10", "R11"]); + deployment.activate("R11"); + + expect(await deployment.fetch("/releases/R10/assets/app.aaaa.js")) + .toMatchObject({ status: 200 }); +}); +``` + +- [ ] **Step 3: Run test** + +```bash +pnpm exec vitest run tests/release/old-asset-reachability.test.ts +``` + +--- + +### Task 5: Add mixed-replica routing simulation + +**Files:** +- Create: `tests/release/mixed-replica.test.ts` + +**Interfaces:** +- Produces deterministic LB simulation alternating R10/R11 replica responses. + +- [ ] **Step 1: Write coherent-old and coherent-new tests** + +A request sequence that remains entirely R10 boots; entirely R11 boots. + +- [ ] **Step 2: Write mixed tuple tests** + +```ts +it("fails closed when HTML and runtime config come from different releases", async () => { + const result = await bootAgainstReplicaSequence([ + response("html", "R10"), + response("config", "R11"), + response("manifest", "R10"), + ]); + + expect(result.state).toBe("release-mismatch"); + expect(result.applicationMounted).toBe(false); +}); +``` + +- [ ] **Step 3: Run** + +```bash +pnpm exec vitest run tests/release/mixed-replica.test.ts +``` + +--- + +### Task 6: Prove mismatch handling cannot reload-loop + +**Files:** +- Create: `src/platform/release/release-mismatch-recovery.ts` +- Test: `tests/platform/release/release-mismatch-recovery.test.ts` + +**Interfaces:** +- Produces bounded mismatch recovery decision. + +- [ ] **Step 1: Write one-recovery-attempt test** + +```ts +it("allows at most one automatic recovery attempt per release mismatch key", () => { + const recovery = createReleaseMismatchRecovery(sessionStorageLike()); + + expect(recovery.decide("R10->R11")).toBe("reload-once"); + expect(recovery.decide("R10->R11")).toBe("show-failure"); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/platform/release/release-mismatch-recovery.test.ts +``` + +- [ ] **Step 3: Implement bounded recovery** + +Recovery marker is scoped to a stable mismatch key and expires/clears after a coherent boot. It must not loop on every page load. + +- [ ] **Step 4: Run test** + +```bash +pnpm exec vitest run tests/platform/release/release-mismatch-recovery.test.ts +``` + +--- + +### Task 7: Add release-coherence command and close the architecture program + +**Files:** +- Modify: `package.json` +- Create: `tests/release/release-matrix.test.ts` + +**Interfaces:** +- Produces `check:release-coherence`. + +- [ ] **Step 1: Encode the complete matrix** + +At minimum: +- R10/R10/R10/old R10 asset => PASS +- R10/R11/R10 => FAIL CLOSED +- R10/R10/R11 => FAIL CLOSED +- R10/R10/R10 with only R11 asset path => FAIL +- R11/R11/R11/R11 asset => PASS +- R10 client after R11 activation with R10 hashed asset retained => PASS + +- [ ] **Step 2: Add script** + +```json +{ + "scripts": { + "check:release-coherence": "vitest run tests/platform/release tests/release" + } +} +``` + +- [ ] **Step 3: Run final deterministic suite** + +```bash +pnpm run check:feature-index +pnpm run check:architecture +pnpm run check:topology +pnpm run check:traffic +pnpm run check:observability +pnpm run check:scale:pr +pnpm run check:scale:main +pnpm run check:release-coherence +pnpm exec tsc --project tsconfig.app.json --noEmit +pnpm exec tsc --project tsconfig.test.json --noEmit +``` + +- [ ] **Step 4: Re-read spec section 54 and create an acceptance matrix** + +Create `docs/reviews/2026-09-23-extreme-scale-acceptance.md` with exactly one row per acceptance criterion and status only: +- `์™„๋ฃŒ` +- `์•„์ง ๋” ๋ด์•ผ๋Œ` + +Every `์™„๋ฃŒ` row includes the exact test/script evidence path. + +- [ ] **Step 5: Final decision** + +The overall architecture work is **์™„๋ฃŒ** only when every spec section 54 criterion is `์™„๋ฃŒ`. Any remaining row makes the overall result **์•„์ง ๋” ๋ด์•ผ๋Œ**. diff --git a/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-scale-chaos-soak-plan.md b/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-scale-chaos-soak-plan.md new file mode 100644 index 00000000..b770f744 --- /dev/null +++ b/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-scale-chaos-soak-plan.md @@ -0,0 +1,550 @@ +# Scale, Chaos, Spike, and Soak Verification Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` or `superpowers:executing-plans` to implement this plan task-by-task. + +**Goal:** Convert the extreme-scale architecture into executable evidence at 100 / 1K / 10K / 100K / 1M logical scale and under spike, sustained, partial-failure, total-failure, slow-upstream, telemetry-storm, and long-session conditions. + +**Architecture:** Small/medium profiles instantiate real TypeScript/runtime fixtures; 100K/1M profiles simulate topology rather than compiling one impossible SPA. Gates combine absolute ceilings, relative baseline regression, and growth-shape checks. Traffic tests measure amplification factors rather than only latency. + +**Tech Stack:** Node `perf_hooks`, current test runner, `tsc --extendedDiagnostics`, current browser/e2e runner when available, JSON benchmark artifacts. + +**Spec:** `docs/superpowers/specs/2026-09-23-extreme-scale-frontend-architecture-design.md` + +## Global Constraints + +- S4 does not create one SPA with 1,000,000 TypeScript feature modules. +- Global topology growth must not materially grow an unchanged app's local artifact/route/build inputs. +- Structural failures are deterministic and fail immediately. +- Performance gates use repeated samples/median where scheduler/environment noise matters. +- No new load-test dependency is required for the first implementation; Node/browser fixtures are sufficient to prove client amplification and growth properties. +- Do not commit/merge/reset/discard repository changes. + +## Review Focus + +1. A linear implementation must not fail because one noisy timing sample is slow. +2. A quadratic implementation must fail even when absolute times are still small at S0. +3. S3/S4 must test global/local independence rather than attempting a 1M-module compile. +4. Total backend failure must keep request/retry/telemetry amplification within explicit ceilings. +5. Long-running sessions must stabilize rather than exhibit positive unbounded heap/listener/timer slopes. + +--- + +### Task 1: Define scale profiles and synthetic topology model + +**Files:** +- Create: `tests/scale/scale-profile.ts` +- Create: `tests/scale/synthetic-topology.ts` +- Test: `tests/scale/synthetic-topology.test.ts` + +**Interfaces:** +- Produces S0-S4 profiles and topology generator. + +- [ ] **Step 1: Write exact profile test** + +```ts +expect(SCALE_PROFILES).toEqual({ + S0: 100, + S1: 1_000, + S2: 10_000, + S3: 100_000, + S4: 1_000_000, +}); +``` + +- [ ] **Step 2: Write local-bound preservation test** + +```ts +it("grows global topology without growing a selected local app beyond its budgets", () => { + const small = createSyntheticTopology({ globalFeatures: 100 }); + const huge = createSyntheticTopology({ globalFeatures: 1_000_000 }); + + expect(huge.apps[0].contexts.length).toBeLessThanOrEqual(APP_CONTEXT_BUDGET); + expect(huge.apps[0].localFeatureCount).toBeLessThanOrEqual(APP_LOCAL_FEATURE_BUDGET); + expect(huge.apps[0].localFeatureCount).toBe(small.apps[0].localFeatureCount); +}); +``` + +- [ ] **Step 3: Implement topology generation with bounded app/context shards** + +S3/S4 models store counts/identifiers compactly; they do not materialize a million source files. + +- [ ] **Step 4: Run test** + +```bash +pnpm exec vitest run tests/scale/synthetic-topology.test.ts +``` + +--- + +### Task 2: Add reusable benchmark runner and JSON artifact schema + +**Files:** +- Create: `scripts/scale/benchmark.ts` +- Create: `scripts/scale/benchmark-result.ts` +- Test: `tests/scale/benchmark.test.ts` + +**Interfaces:** +- Produces median samples and machine-readable results. + +- [ ] **Step 1: Write median/result test** + +```ts +it("records median rather than a single timing sample", async () => { + const result = await benchmark("compose", { + samples: 5, + run: fakeDurations([10, 11, 100, 12, 9]), + }); + + expect(result.medianMs).toBe(11); + expect(result.samples).toHaveLength(5); +}); +``` + +- [ ] **Step 2: Implement result schema** + +```ts +export interface BenchmarkResult { + readonly name: string; + readonly profile: "S0" | "S1" | "S2" | "S3" | "S4"; + readonly cardinality: number; + readonly samples: readonly number[]; + readonly medianMs: number; + readonly heapBytes?: number; + readonly metadata: Readonly>; +} +``` + +- [ ] **Step 3: Run tests** + +```bash +pnpm exec vitest run tests/scale/benchmark.test.ts +``` + +--- + +### Task 3: Add growth-shape regression detector + +**Files:** +- Create: `src/platform/cardinality/growth-regression.ts` +- Test: `tests/scale/growth-regression.test.ts` + +**Interfaces:** +- Produces `assertLinearOrBetter(samples, tolerance)`. + +- [ ] **Step 1: Write linear and quadratic examples** + +```ts +it("accepts roughly linear growth", () => { + expect(() => + assertLinearOrBetter([ + { n: 100, cost: 1 }, + { n: 1_000, cost: 10 }, + { n: 10_000, cost: 100 }, + ]), + ).not.toThrow(); +}); + +it("rejects quadratic-shaped growth", () => { + expect(() => + assertLinearOrBetter([ + { n: 100, cost: 1 }, + { n: 1_000, cost: 100 }, + { n: 10_000, cost: 10_000 }, + ]), + ).toThrow(/growth/i); +}); +``` + +- [ ] **Step 2: Implement ratio/slope based detector with tolerance** + +It is a regression detector, not a mathematical Big-O proof. Document this in code comments. + +- [ ] **Step 3: Run test** + +```bash +pnpm exec vitest run tests/scale/growth-regression.test.ts +``` + +--- + +### Task 4: Benchmark registry/composition S0-S2 + +**Files:** +- Create: `scripts/scale/run-composition-scale.ts` +- Test: `tests/scale/composition-scale.test.ts` + +**Interfaces:** +- Consumes Phase 1 composition functions. +- Produces S0/S1/S2 timing + heap artifact. + +- [ ] **Step 1: Write structural test first** + +```ts +it.each([100, 1_000, 10_000])( + "composes %i unique entries without duplicates", + (count) => { + const parts = createUniqueRegistryParts(count); + const result = composeUniqueRecord(parts, () => "route"); + + expect(Object.keys(result)).toHaveLength(count); + }, +); +``` + +- [ ] **Step 2: Implement runner** + +Runner executes multiple samples and writes: + +```json +{ + "name": "registry-composition", + "profile": "S2", + "cardinality": 10000, + "medianMs": 0, + "heapBytes": 0, + "metadata": { + "implementation": "composeUniqueRecord" + } +} +``` + +Runtime values replace zero. + +- [ ] **Step 3: Add growth assertion** + +S0/S1/S2 result series must pass `assertLinearOrBetter()`. + +--- + +### Task 5: Capture TypeScript extended diagnostics for bounded local apps + +**Files:** +- Create: `scripts/scale/collect-tsc-diagnostics.ts` +- Create: `tests/scale/fixtures/typescript/` +- Test: `tests/scale/tsc-diagnostics-parser.test.ts` + +**Interfaces:** +- Produces parsed `Files`, `Types`, `Symbols`, `Instantiations`, `Memory used`, `Total time`. + +- [ ] **Step 1: Write parser test against fixed diagnostic text** + +```ts +const text = ` +Files: 321 +Types: 12000 +Symbols: 18000 +Instantiations: 5000 +Memory used: 128000K +Total time: 4.20s +`; + +expect(parseTscExtendedDiagnostics(text)).toMatchObject({ + files: 321, + types: 12_000, + symbols: 18_000, + instantiations: 5_000, +}); +``` + +- [ ] **Step 2: Implement parser and runner** + +Runner invokes repository-supported TypeScript with: + +```bash +pnpm exec tsc --project tsconfig.app.json --noEmit --extendedDiagnostics +``` + +- [ ] **Step 3: Compare bounded local fixtures, not 1M modules** + +S0/S1/S2 can use generated local fixtures up to the measured safe ceiling. S3/S4 only verify topology partitioning. + +--- + +### Task 6: Prove global-to-local independence at S3/S4 + +**Files:** +- Create: `tests/scale/global-local-independence.test.ts` + +**Interfaces:** +- Consumes topology generator and generated-index projection logic. +- Produces the central 1M architectural proof. + +- [ ] **Step 1: Write the S4 invariance test** + +```ts +it("keeps one unchanged app's local inputs constant from S0 to S4", () => { + const s0 = selectAppInputs(createSyntheticTopology({ globalFeatures: 100 }), "app-0"); + const s4 = selectAppInputs(createSyntheticTopology({ globalFeatures: 1_000_000 }), "app-0"); + + expect(s4.contextIds).toEqual(s0.contextIds); + expect(s4.featureIds).toEqual(s0.featureIds); + expect(s4.routeRootIds).toEqual(s0.routeRootIds); +}); +``` + +- [ ] **Step 2: Run test** + +```bash +pnpm exec vitest run tests/scale/global-local-independence.test.ts +``` + +Expected: PASS. + +--- + +### Task 7: Add request/retry amplification metrics + +**Files:** +- Create: `tests/scale/traffic/amplification-metrics.ts` +- Test: `tests/scale/traffic/amplification-metrics.test.ts` + +**Interfaces:** +- Produces request, retry, telemetry amplification calculations. + +- [ ] **Step 1: Write exact metric tests** + +```ts +expect(requestAmplification({ + interactions: 1_000, + physicalRequests: 1_150, +})).toBe(1.15); + +expect(retryAmplification({ + initialRequests: 1_000, + totalRequests: 1_200, +})).toBe(1.2); +``` + +- [ ] **Step 2: Reject zero/negative denominators** + +Add explicit tests that invalid denominators throw. + +- [ ] **Step 3: Implement and run** + +```bash +pnpm exec vitest run tests/scale/traffic/amplification-metrics.test.ts +``` + +--- + +### Task 8: Add total/partial/slow failure traffic scenarios + +**Files:** +- Create: `tests/scale/traffic/failure-scenarios.test.ts` + +**Interfaces:** +- Consumes Phase 2 budgets. +- Produces bounded failure-amplification evidence. + +- [ ] **Step 1: Total outage test** + +```ts +it("bounds physical requests when all upstream calls fail", async () => { + const result = await runSyntheticTraffic({ + interactions: 10_000, + upstream: "always-fail", + maxPhysicalRequestsPerInteraction: 2, + maxRetriesPerInteraction: 1, + }); + + expect(result.physicalRequests).toBeLessThanOrEqual(20_000); +}); +``` + +- [ ] **Step 2: Partial outage test** + +Payment failures do not prevent order/catalog synthetic flows from completing; assert success counters by context. + +- [ ] **Step 3: Slow upstream test** + +Use a fake clock/controlled promises to assert: +- active requests never exceed concurrency budget, +- queued requests never exceed queue budget, +- deadline expiration drains waiters, +- no retry begins after deadline. + +- [ ] **Step 4: Run** + +```bash +pnpm exec vitest run tests/scale/traffic/failure-scenarios.test.ts +``` + +--- + +### Task 9: Add Retry-After jitter distribution regression + +**Files:** +- Create: `tests/scale/traffic/retry-after-jitter.test.ts` + +**Interfaces:** +- Consumes current retry scheduling implementation. +- Produces proof that a Retry-After cohort is not synchronized to one exact retry instant. + +- [ ] **Step 1: Write distribution test** + +```ts +it("spreads retries around Retry-After instead of synchronizing all clients", () => { + const delays = Array.from({ length: 10_000 }, (_, seed) => + calculateRetryDelay({ + retryAfterMs: 10_000, + jitterSeed: seed, + attempt: 1, + }), + ); + + expect(new Set(delays).size).toBeGreaterThan(100); + expect(Math.max(...delays) - Math.min(...delays)).toBeGreaterThan(500); +}); +``` + +- [ ] **Step 2: Run** + +```bash +pnpm exec vitest run tests/scale/traffic/retry-after-jitter.test.ts +``` + +--- + +### Task 10: Add telemetry-storm and collector-outage scenarios + +**Files:** +- Create: `tests/scale/telemetry/telemetry-storm.test.ts` + +**Interfaces:** +- Consumes Phase 3 telemetry pipeline. +- Produces bounded-memory/network evidence. + +- [ ] **Step 1: Repeated-error storm test** + +```ts +it("does not turn 100000 identical failures into 100000 sends", async () => { + const result = await runTelemetryStorm({ + identicalEvents: 100_000, + maxSendsPerMinute: 20, + maxBufferedEvents: 200, + }); + + expect(result.networkSends).toBeLessThanOrEqual(20); + expect(result.peakBufferedEvents).toBeLessThanOrEqual(200); +}); +``` + +- [ ] **Step 2: Collector outage test** + +The transport rejects every send; assert business promises remain fulfilled and buffer limits remain respected. + +- [ ] **Step 3: Run** + +```bash +pnpm exec vitest run tests/scale/telemetry/telemetry-storm.test.ts +``` + +--- + +### Task 11: Add network flap and long-session state-cycle tests + +**Files:** +- Create: `tests/scale/session/network-flap.test.ts` +- Create: `tests/scale/session/long-session.test.ts` + +**Interfaces:** +- Produces regression evidence for offline/online, login/navigation/query/mutation/logout cycles. + +- [ ] **Step 1: Network flap test** + +Repeat online/offline transitions and assert: +- no duplicate unsafe mutation replay, +- retry queue stays bounded, +- stale interaction cancellation completes. + +- [ ] **Step 2: Long-session logical leak test** + +Run thousands of synthetic cycles and record: +- active timers, +- listeners, +- telemetry buffer size, +- active AbortControllers, +- query scope generations. + +Assert each returns to or stabilizes near its post-warmup bound. + +- [ ] **Step 3: Run** + +```bash +pnpm exec vitest run tests/scale/session +``` + +--- + +### Task 12: Add optional browser heap-slope harness + +**Files:** +- Create: `scripts/scale/browser-soak.ts` +- Create: `tests/scale/browser-soak.contract.test.ts` + +**Interfaces:** +- Produces JSON series `{ elapsedMs, heapBytes, domNodes, activeTimers }` when the repository's browser runner exposes these metrics. + +- [ ] **Step 1: Test the slope classifier independently of browser availability** + +```ts +it("flags a persistent positive heap slope after warmup", () => { + expect( + classifyMemorySlope([ + { minute: 10, heapMb: 100 }, + { minute: 20, heapMb: 200 }, + { minute: 30, heapMb: 300 }, + ]), + ).toBe("unbounded-growth"); +}); +``` + +- [ ] **Step 2: Implement browser harness using the existing e2e runner** + +Do not add a second browser automation framework. If the repository uses Playwright, use Playwright; if it uses another existing runner, use that runner. + +- [ ] **Step 3: Write artifacts under `artifacts/scale/` and keep generated artifacts out of source imports** + +--- + +### Task 13: Define PR/main/nightly/release commands + +**Files:** +- Modify: `package.json` +- Create: `scripts/scale/run-scale-profile.ts` + +**Interfaces:** +- Produces: + - `check:scale:pr` + - `check:scale:main` + - `check:scale:nightly` + - `check:scale:release` + +- [ ] **Step 1: Wire PR** + +PR includes S0/S1 architecture/composition/traffic tests. + +- [ ] **Step 2: Wire main** + +Main adds S2 registry/composition/TypeScript diagnostics. + +- [ ] **Step 3: Wire nightly** + +Nightly adds S3/S4 topology, telemetry storm, session cycles, browser soak if available. + +- [ ] **Step 4: Wire release** + +Release invokes release-coherence tests from Phase 5 plus the stable main/nightly subset appropriate to the environment. + +- [ ] **Step 5: Run Phase 4 deterministic subset** + +```bash +pnpm run check:scale:pr +pnpm run check:scale:main +``` + +Expected: PASS. + +- [ ] **Step 6: Phase decision** + +**์™„๋ฃŒ** only if scale growth, amplification, topology independence, storm boundedness, and session-growth properties are executable and produce machine-readable results. Otherwise **์•„์ง ๋” ๋ด์•ผ๋Œ**. diff --git a/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-topology-composition-plan.md b/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-topology-composition-plan.md new file mode 100644 index 00000000..e3b0e9fa --- /dev/null +++ b/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/plans/2026-09-23-topology-composition-plan.md @@ -0,0 +1,862 @@ +# Topology, Composition, and Cardinality Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Replace flat central installation and scale-sensitive composition with feature-owned descriptors, bounded-context/app ownership, deterministic generated static indexes, O(N) composition, indexed membership, dependency gates, and hierarchical routing. + +**Architecture:** Every feature owns one descriptor; contexts compose only direct features; deployable apps compose only direct contexts. Static generated indexes replace multi-file handwritten installation lists. Duplicate identifiers and budget violations fail deterministically. Cross-feature/context concrete imports fail architecture checks. + +**Tech Stack:** TypeScript, current test runner, dependency-cruiser, Vite, current routing stack. + +**Spec:** `docs/superpowers/specs/2026-09-23-extreme-scale-frontend-architecture-design.md` + +## Global Constraints + +- No global registry containing all product descendants. +- No repeated object-spread accumulator on scale-sensitive paths. +- Membership checks on scale-sensitive paths use `Set`/`Map`. +- Generated indexes use static imports only. +- Adding a normal feature changes feature-owned files plus generated files; central handwritten production registries are not manually extended. +- Cross-feature concrete imports and cross-context concrete imports are forbidden. +- Existing UI behavior and route URLs remain unchanged during this phase. +- Do not commit/merge/reset/discard existing repository changes. + +## Review Focus + +1. Duplicate feature/route/operation IDs must fail with deterministic diagnostics. +2. Generated index order must be deterministic across repeated runs. +3. A feature may import its own layers but may not concrete-import another feature. +4. A context budget overflow must fail before runtime boot. +5. Product selection must remain equivalent after replacing `includes()` scans with indexed membership. + +--- + +### Task 1: Lock the live baseline before architectural edits + +**Files:** +- Read: `src/features/feature-adapter-contribution.ts` +- Read: `src/features/installed-product-manifest.ts` +- Read: `src/features/installed-feature-contracts.ts` +- Read: `src/features/installed-feature-adapters.ts` +- Read: `src/features/installed-feature-runtimes.tsx` +- Read: `src/features/installed-feature-messages.ts` +- Read: `src/features/installed-contract-contributions.ts` +- Read: `src/features/product-features.ts` +- Read: `.dependency-cruiser.json` +- Read: `package.json` +- Create: `docs/reviews/2026-09-23-extreme-scale-baseline-map.md` + +**Interfaces:** +- Consumes: current `origin/main` implementation. +- Produces: verified path/symbol map used by every later task. + +- [ ] **Step 1: Verify expected files without modifying them** + +```bash +for f in \ + src/features/feature-adapter-contribution.ts \ + src/features/installed-product-manifest.ts \ + src/features/installed-feature-contracts.ts \ + src/features/installed-feature-adapters.ts \ + src/features/installed-feature-runtimes.tsx \ + src/features/installed-feature-messages.ts \ + src/features/installed-contract-contributions.ts \ + src/features/product-features.ts \ + .dependency-cruiser.json \ + package.json +do + test -f "$f" || { echo "MISSING:$f"; exit 1; } +done +``` + +Expected: exit `0`. + +- [ ] **Step 2: Record the scale-sensitive symbols** + +```bash +rg -n \ + 'INSTALLED_PRODUCT_FEATURE_IDS|INSTALLED_FEATURE_CONTRACTS|reduce\(|\.includes\(|ROUTE_REGISTRY|REFERENCE_FEATURE_ADAPTER_CONTRIBUTION|REFERENCE_MESSAGE_CATALOGS' \ + src .dependency-cruiser.json package.json \ + > /tmp/extreme-scale-baseline-symbols.txt +``` + +Expected: matches identify the current composition and membership paths. + +- [ ] **Step 3: Write the baseline map** + +Create `docs/reviews/2026-09-23-extreme-scale-baseline-map.md` with the exact paths and symbol names returned above and the verified `origin/main` SHA. Do not describe unverified paths. + +- [ ] **Step 4: Re-run current non-mutating baseline checks** + +```bash +pnpm exec tsc --project tsconfig.app.json --noEmit +pnpm exec tsc --project tsconfig.test.json --noEmit +``` + +Expected: PASS under the repository-supported Node version. + +- [ ] **Step 5: Checkpoint** + +Status is **์™„๋ฃŒ** only when all expected files and baseline checks are verified. Otherwise status is **์•„์ง ๋” ๋ด์•ผ๋Œ** and later tasks do not start. + +--- + +### Task 2: Introduce the feature-owned descriptor contract + +**Files:** +- Create: `src/features/feature-module.ts` +- Test: `tests/features/feature-module.test.ts` + +**Interfaces:** +- Consumes: existing route/contracts/adapter/runtime/message contribution types. +- Produces: + - `FeatureModuleId` + - `FeatureModule` + - `defineFeatureModule()` + +- [ ] **Step 1: Write the failing descriptor identity/immutability test** + +```ts +import { describe, expect, it } from "vitest"; +import { defineFeatureModule } from "../../src/features/feature-module"; + +describe("defineFeatureModule", () => { + it("keeps one stable feature id and freezes the descriptor", () => { + const module = defineFeatureModule({ + id: "reference", + routes: {}, + contracts: {}, + adapters: [], + runtimes: [], + messages: {}, + contractContributions: [], + }); + + expect(module.id).toBe("reference"); + expect(Object.isFrozen(module)).toBe(true); + }); +}); +``` + +- [ ] **Step 2: Run the test and verify RED** + +```bash +pnpm exec vitest run tests/features/feature-module.test.ts +``` + +Expected: FAIL because `feature-module` does not exist. + +- [ ] **Step 3: Implement the minimal descriptor** + +```ts +export type FeatureModuleId = string & { readonly __brand: "FeatureModuleId" }; + +export interface FeatureModule { + readonly id: string; + readonly routes: Readonly>; + readonly contracts: Readonly>; + readonly adapters: readonly unknown[]; + readonly runtimes: readonly unknown[]; + readonly messages: Readonly>; + readonly contractContributions: readonly unknown[]; +} + +export function defineFeatureModule(module: T): Readonly { + return Object.freeze(module); +} +``` + +During implementation, replace `unknown` with the exact existing contribution types identified in Task 1; preserve the function and property names above. + +- [ ] **Step 4: Run the focused test** + +```bash +pnpm exec vitest run tests/features/feature-module.test.ts +``` + +Expected: PASS. + +- [ ] **Step 5: Run both TypeScript checks** + +```bash +pnpm exec tsc --project tsconfig.app.json --noEmit +pnpm exec tsc --project tsconfig.test.json --noEmit +``` + +Expected: PASS. + +--- + +### Task 3: Migrate the reference feature to one owned descriptor + +**Files:** +- Create: `src/features/reference-feature/feature-module.ts` +- Modify: existing reference feature export barrel if one exists in the baseline map +- Test: `tests/features/reference-feature/feature-module.test.ts` + +**Interfaces:** +- Consumes: `defineFeatureModule()`. +- Produces: `REFERENCE_FEATURE_MODULE`. + +- [ ] **Step 1: Write the failing ownership test** + +```ts +import { describe, expect, it } from "vitest"; +import { REFERENCE_FEATURE_MODULE } from "../../../src/features/reference-feature/feature-module"; + +describe("REFERENCE_FEATURE_MODULE", () => { + it("owns every install-time contribution under one feature id", () => { + expect(REFERENCE_FEATURE_MODULE.id).toBe("reference"); + expect(REFERENCE_FEATURE_MODULE.routes).toBeDefined(); + expect(REFERENCE_FEATURE_MODULE.adapters).toBeDefined(); + expect(REFERENCE_FEATURE_MODULE.runtimes).toBeDefined(); + expect(REFERENCE_FEATURE_MODULE.messages).toBeDefined(); + expect(REFERENCE_FEATURE_MODULE.contractContributions).toBeDefined(); + }); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/features/reference-feature/feature-module.test.ts +``` + +- [ ] **Step 3: Create `REFERENCE_FEATURE_MODULE`** + +```ts +export const REFERENCE_FEATURE_MODULE = defineFeatureModule({ + id: "reference", + routes: REFERENCE_ROUTES, + contracts: REFERENCE_CONTRACTS, + adapters: [REFERENCE_FEATURE_ADAPTER_CONTRIBUTION], + runtimes: [REFERENCE_FEATURE_RUNTIME_CONTRIBUTION], + messages: REFERENCE_MESSAGE_CATALOGS, + contractContributions: [REFERENCE_CONTRACT_CONTRIBUTION], +}); +``` + +Use the exact existing reference-feature symbols from Task 1. + +- [ ] **Step 4: Run focused and reference-feature tests** + +```bash +pnpm exec vitest run tests/features/reference-feature +``` + +Expected: PASS. + +--- + +### Task 4: Add bounded-context and deployable-app descriptors + +**Files:** +- Create: `src/contexts/bounded-context-module.ts` +- Create: `src/apps/deployable-app-module.ts` +- Test: `tests/architecture/module-hierarchy.test.ts` + +**Interfaces:** +- Consumes: `FeatureModule`. +- Produces: + - `BoundedContextModule` + - `defineBoundedContextModule()` + - `DeployableAppModule` + - `defineDeployableAppModule()` + +- [ ] **Step 1: Write the failing hierarchy test** + +```ts +import { describe, expect, it } from "vitest"; +import { defineBoundedContextModule } from "../../src/contexts/bounded-context-module"; +import { defineDeployableAppModule } from "../../src/apps/deployable-app-module"; + +describe("module hierarchy", () => { + it("exposes only direct children at each boundary", () => { + const context = defineBoundedContextModule({ + id: "commerce", + features: [], + budget: { maxFeatures: 200 }, + }); + + const app = defineDeployableAppModule({ + id: "customer", + contexts: [context], + budget: { maxContexts: 20 }, + }); + + expect(app.contexts).toEqual([context]); + expect("features" in app).toBe(false); + }); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/architecture/module-hierarchy.test.ts +``` + +- [ ] **Step 3: Implement direct-child descriptors** + +```ts +export interface BoundedContextModule { + readonly id: string; + readonly features: readonly FeatureModule[]; + readonly budget: Readonly<{ maxFeatures: number }>; +} + +export interface DeployableAppModule { + readonly id: string; + readonly contexts: readonly BoundedContextModule[]; + readonly budget: Readonly<{ maxContexts: number }>; +} +``` + +Both factory functions freeze descriptors and copy child arrays before freezing them. + +- [ ] **Step 4: Run focused tests and TypeScript checks** + +```bash +pnpm exec vitest run tests/architecture/module-hierarchy.test.ts +pnpm exec tsc --project tsconfig.app.json --noEmit +pnpm exec tsc --project tsconfig.test.json --noEmit +``` + +Expected: PASS. + +--- + +### Task 5: Add explicit cardinality budgets and fail-fast validation + +**Files:** +- Create: `src/platform/cardinality/cardinality-budget.ts` +- Test: `tests/platform/cardinality/cardinality-budget.test.ts` + +**Interfaces:** +- Produces: + - `CardinalityBudgetExceededError` + - `assertWithinCardinalityBudget(name, current, maximum)` + +- [ ] **Step 1: Write failing tests** + +```ts +import { describe, expect, it } from "vitest"; +import { + CardinalityBudgetExceededError, + assertWithinCardinalityBudget, +} from "../../../src/platform/cardinality/cardinality-budget"; + +describe("assertWithinCardinalityBudget", () => { + it("accepts the exact ceiling", () => { + expect(() => assertWithinCardinalityBudget("commerce.features", 200, 200)).not.toThrow(); + }); + + it("rejects values above the ceiling with the boundary name", () => { + expect(() => assertWithinCardinalityBudget("commerce.features", 201, 200)) + .toThrow(CardinalityBudgetExceededError); + }); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/platform/cardinality/cardinality-budget.test.ts +``` + +- [ ] **Step 3: Implement fail-fast budget validation** + +```ts +export class CardinalityBudgetExceededError extends Error { + constructor( + readonly boundary: string, + readonly current: number, + readonly maximum: number, + ) { + super(`${boundary} cardinality ${current} exceeds ${maximum}`); + } +} + +export function assertWithinCardinalityBudget( + boundary: string, + current: number, + maximum: number, +): void { + if (!Number.isSafeInteger(maximum) || maximum < 1) { + throw new TypeError(`Invalid cardinality ceiling for ${boundary}: ${maximum}`); + } + if (current > maximum) { + throw new CardinalityBudgetExceededError(boundary, current, maximum); + } +} +``` + +- [ ] **Step 4: Run tests** + +```bash +pnpm exec vitest run tests/platform/cardinality/cardinality-budget.test.ts +``` + +Expected: PASS. + +--- + +### Task 6: Replace quadratic registry accumulation with duplicate-safe O(N) composition + +**Files:** +- Create: `src/platform/cardinality/compose-unique-record.ts` +- Modify: `src/features/installed-feature-contracts.ts` +- Test: `tests/platform/cardinality/compose-unique-record.test.ts` + +**Interfaces:** +- Produces: `composeUniqueRecord(parts, describePart)`. + +- [ ] **Step 1: Write failing duplicate and merge tests** + +```ts +import { describe, expect, it } from "vitest"; +import { composeUniqueRecord } from "../../../src/platform/cardinality/compose-unique-record"; + +describe("composeUniqueRecord", () => { + it("composes entries without repeated accumulator copies", () => { + expect(composeUniqueRecord([{ a: 1 }, { b: 2 }], () => "test")) + .toEqual({ a: 1, b: 2 }); + }); + + it("rejects duplicate keys", () => { + expect(() => composeUniqueRecord([{ a: 1 }, { a: 2 }], () => "routes")) + .toThrow(/Duplicate routes key: a/); + }); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/platform/cardinality/compose-unique-record.test.ts +``` + +- [ ] **Step 3: Implement one mutable local accumulator and one final freeze** + +```ts +export function composeUniqueRecord( + parts: readonly Readonly>[], + describePart: () => string, +): Readonly> { + const result: Record = Object.create(null); + + for (const part of parts) { + for (const [key, value] of Object.entries(part)) { + if (Object.hasOwn(result, key)) { + throw new TypeError(`Duplicate ${describePart()} key: ${key}`); + } + result[key] = value; + } + } + + return Object.freeze(result); +} +``` + +- [ ] **Step 4: Replace the spread-reduce in `installed-feature-contracts.ts`** + +Route/API/schema/mapper/invalidation composition uses `composeUniqueRecord()` rather than `{ ...registry, ...next }`. + +- [ ] **Step 5: Run focused tests and scan for the old pattern** + +```bash +pnpm exec vitest run tests/platform/cardinality/compose-unique-record.test.ts +rg -n '\{\s*\.\.\.[A-Za-z_][A-Za-z0-9_]*,\s*\.\.\.' src/features src/platform +``` + +Expected: no scale-sensitive accumulation pattern remains. + +--- + +### Task 7: Replace scale-sensitive membership scans with indexed membership + +**Files:** +- Modify: `src/features/product-features.ts` +- Modify: `src/features/installed-feature-runtimes.tsx` +- Modify: `src/features/installed-contract-contributions.ts` +- Test: `tests/features/product-features.test.ts` + +**Interfaces:** +- Produces: one immutable/set-backed installed-feature membership predicate. + +- [ ] **Step 1: Add behavior-equivalence tests for product selection** + +```ts +it("selects requested compiled features and reports unknown ids", () => { + const result = resolveProductFeatures( + ["reference", "unknown"], + ["reference", "local-draft"], + ); + + expect(result.installed).toEqual(["reference"]); + expect(result.unknownRequested).toEqual(["unknown"]); +}); +``` + +- [ ] **Step 2: Run the existing/product feature test and establish GREEN before refactor** + +```bash +pnpm exec vitest run tests/features/product-features.test.ts +``` + +Expected: PASS before refactor. + +- [ ] **Step 3: Build `Set` instances once per resolution/composition call** + +```ts +const compiledSet = new Set(compiledIds); +const requestedSet = new Set(requested); +const installedSet = new Set(installedIds); +``` + +All scale-sensitive membership checks use `.has()`. + +- [ ] **Step 4: Replace runtime and contract filters** + +`installed-feature-runtimes.tsx` and `installed-contract-contributions.ts` consume the same installed membership abstraction instead of repeating `INSTALLED_PRODUCT_FEATURE_IDS.includes(...)`. + +- [ ] **Step 5: Verify equivalence and scan** + +```bash +pnpm exec vitest run tests/features/product-features.test.ts +rg -n 'INSTALLED_PRODUCT_FEATURE_IDS\.includes|compiledIds\.includes|requested\.includes' src/features +``` + +Expected: tests PASS and scan returns no scale-sensitive matches. + +--- + +### Task 8: Generate a deterministic static feature index + +**Files:** +- Create: `scripts/generate-product-feature-index.ts` +- Create: `src/.generated/product-feature-index.ts` +- Test: `tests/scripts/generate-product-feature-index.test.ts` +- Modify: `package.json` + +**Interfaces:** +- Consumes: feature modules with stable `feature-module.ts` entrypoints. +- Produces: deterministic static TypeScript import/index file. + +- [ ] **Step 1: Write a failing deterministic-generation test** + +```ts +it("sorts feature module imports by normalized feature id and produces identical output", async () => { + const first = renderFeatureIndex([ + { id: "zeta", importPath: "../features/zeta/feature-module" }, + { id: "alpha", importPath: "../features/alpha/feature-module" }, + ]); + const second = renderFeatureIndex([ + { id: "alpha", importPath: "../features/alpha/feature-module" }, + { id: "zeta", importPath: "../features/zeta/feature-module" }, + ]); + + expect(first).toBe(second); + expect(first.indexOf("alpha")).toBeLessThan(first.indexOf("zeta")); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/scripts/generate-product-feature-index.test.ts +``` + +- [ ] **Step 3: Implement generator rules** + +The generator: +- enumerates approved local feature entrypoints, +- reads stable ids from a deterministic metadata source, +- sorts by id, +- rejects duplicate ids, +- emits literal static imports, +- writes only `src/.generated/product-feature-index.ts`, +- never emits runtime-computed import paths. + +- [ ] **Step 4: Add scripts** + +```json +{ + "scripts": { + "generate:feature-index": "tsx scripts/generate-product-feature-index.ts", + "check:feature-index": "pnpm generate:feature-index && git diff --exit-code -- src/.generated/product-feature-index.ts" + } +} +``` + +Use the repository's existing TypeScript script runner if it differs from `tsx`; do not add a new runtime dependency solely for this task. + +- [ ] **Step 5: Run generator twice and compare hashes** + +```bash +pnpm generate:feature-index +sha256sum src/.generated/product-feature-index.ts > /tmp/index.first +pnpm generate:feature-index +sha256sum src/.generated/product-feature-index.ts > /tmp/index.second +diff -u /tmp/index.first /tmp/index.second +``` + +Expected: no diff. + +--- + +### Task 9: Retire handwritten multi-registry feature installation + +**Files:** +- Modify: `src/features/installed-product-manifest.ts` +- Modify: `src/features/installed-feature-adapters.ts` +- Modify: `src/features/installed-feature-runtimes.tsx` +- Modify: `src/features/installed-feature-messages.ts` +- Modify: `src/features/installed-contract-contributions.ts` +- Modify: `src/features/installed-feature-contracts.ts` +- Test: existing sample-removal test and new `tests/features/feature-installation-surface.test.ts` + +**Interfaces:** +- Consumes: generated feature index. +- Produces: generic composition from `FeatureModule[]`. + +- [ ] **Step 1: Write the installation-surface test** + +```ts +it("derives install-time collections from feature modules instead of reference-specific imports", async () => { + const sourceFiles = await readInstalledFeatureSourceFiles(); + + for (const source of sourceFiles) { + expect(source).not.toMatch(/REFERENCE_FEATURE_(ADAPTER|RUNTIME|CONTRACT)/); + expect(source).not.toMatch(/REFERENCE_MESSAGE_CATALOGS/); + } +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/features/feature-installation-surface.test.ts +``` + +Expected: FAIL against current handwritten reference imports. + +- [ ] **Step 3: Rewrite installed collections as generic projections** + +Conceptual shape: + +```ts +export const INSTALLED_FEATURE_ADAPTERS = + INSTALLED_PRODUCT_FEATURE_MODULES.flatMap((feature) => feature.adapters); +``` + +Equivalent projections are used for runtimes/messages/contracts, with duplicate detection where identifier collisions are possible. + +- [ ] **Step 4: Run feature installation and sample-removal tests** + +```bash +pnpm exec vitest run tests/features +pnpm run test:sample-removal +``` + +Use the exact existing sample-removal script name from `package.json` if its spelling differs. + +- [ ] **Step 5: Scan for reference-specific imports in installed central files** + +```bash +rg -n 'REFERENCE_' \ + src/features/installed-product-manifest.ts \ + src/features/installed-feature-adapters.ts \ + src/features/installed-feature-runtimes.tsx \ + src/features/installed-feature-messages.ts \ + src/features/installed-contract-contributions.ts \ + src/features/installed-feature-contracts.ts +``` + +Expected: no install-time reference-specific import. + +--- + +### Task 10: Enforce cross-feature and cross-context concrete import prohibition + +**Files:** +- Modify: `.dependency-cruiser.json` +- Test fixture: `tests/architecture/fixtures/cross-feature-import/` +- Test fixture: `tests/architecture/fixtures/same-feature-import/` +- Test: `tests/architecture/dependency-boundaries.test.ts` + +**Interfaces:** +- Produces deterministic architecture failures for illegal feature/context edges. + +- [ ] **Step 1: Create an illegal fixture** + +```ts +// tests/architecture/fixtures/cross-feature-import/order.ts +import { concretePaymentThing } from "../../../../src/features/payment/application/concrete-payment-thing"; + +export const illegal = concretePaymentThing; +``` + +The fixture must target two real/synthetic feature roots that exist in the test harness. + +- [ ] **Step 2: Create a legal same-feature fixture** + +```ts +// tests/architecture/fixtures/same-feature-import/order.ts +import { orderPort } from "../../../../src/features/order/application/order-port"; + +export const legal = orderPort; +``` + +- [ ] **Step 3: Extend dependency-cruiser rules** + +The rule must reject `src/features//** -> src/features//**` when `A !== B`, except imports through explicitly approved shared `src/contracts/**`, `src/application/ports/**`, or orchestration/public-facade boundaries. + +Add the analogous stricter context rule for `src/contexts//** -> src/contexts//**`. + +- [ ] **Step 4: Run architecture checks against both fixtures** + +```bash +pnpm run check:architecture +``` + +Expected: legal fixture accepted; illegal cross-feature fixture rejected by the named rule. + +- [ ] **Step 5: Run full architecture checks** + +```bash +pnpm run check:architecture +``` + +Expected: PASS for production sources. + +--- + +### Task 11: Introduce hierarchical/lazy route ownership + +**Files:** +- Create: `src/platform/routing/context-route-module.ts` +- Modify: current `AppRouter` file identified in Task 1 baseline map +- Modify: `src/features/installed-feature-contracts.ts` only if route projection remains there +- Test: `tests/platform/routing/context-route-module.test.ts` + +**Interfaces:** +- Consumes: app/context/feature descriptors. +- Produces: + - top-level context routes at app boot, + - lazy feature route resolution inside the selected context. + +- [ ] **Step 1: Write a failing test proving boot does not flatten all feature routes** + +```ts +it("creates only direct context route entries at app boot", () => { + const routes = createAppRoutes(customerApp); + + expect(routes.map((route) => route.id)).toEqual(["commerce", "account"]); + expect(routes.some((route) => route.id === "order-create")).toBe(false); +}); +``` + +- [ ] **Step 2: Verify RED** + +```bash +pnpm exec vitest run tests/platform/routing/context-route-module.test.ts +``` + +- [ ] **Step 3: Implement lazy context route modules** + +```ts +export interface ContextRouteModule { + readonly id: string; + readonly path: string; + readonly loadRoutes: () => Promise; +} +``` + +The app router creates only `ContextRouteModule` entries. `loadRoutes()` imports the context-owned static route module; it does not accept arbitrary runtime paths. + +- [ ] **Step 4: Preserve existing public route URLs** + +Run route contract tests and compare route URL snapshots before/after. + +```bash +pnpm exec vitest run tests --testNamePattern="route" +``` + +Expected: route URLs unchanged. + +--- + +### Task 12: Add topology/cardinality composition tests and close Phase 1 + +**Files:** +- Create: `tests/architecture/topology-cardinality.test.ts` +- Modify: `package.json` + +**Interfaces:** +- Consumes: module hierarchy, generated index, cardinality assertions. +- Produces: `check:topology`. + +- [ ] **Step 1: Write boundary-ceiling tests** + +```ts +it("rejects a context above its feature budget", () => { + const features = Array.from({ length: 201 }, (_, index) => fakeFeature(`f${index}`)); + + expect(() => + defineBoundedContextModule({ + id: "commerce", + features, + budget: { maxFeatures: 200 }, + }), + ).toThrow(/commerce.*201.*200/); +}); +``` + +- [ ] **Step 2: Add duplicate-id tests** + +```ts +it("rejects duplicate direct child ids", () => { + expect(() => + defineDeployableAppModule({ + id: "customer", + contexts: [fakeContext("commerce"), fakeContext("commerce")], + budget: { maxContexts: 20 }, + }), + ).toThrow(/Duplicate.*commerce/); +}); +``` + +- [ ] **Step 3: Add `check:topology`** + +```json +{ + "scripts": { + "check:topology": "vitest run tests/architecture/topology-cardinality.test.ts tests/platform/cardinality tests/platform/routing" + } +} +``` + +- [ ] **Step 4: Run Phase 1 verification** + +```bash +pnpm run check:feature-index +pnpm run check:architecture +pnpm run check:topology +pnpm exec tsc --project tsconfig.app.json --noEmit +pnpm exec tsc --project tsconfig.test.json --noEmit +``` + +Expected: PASS. + +- [ ] **Step 5: Phase decision** + +**์™„๋ฃŒ** only if: +- feature installation no longer depends on multiple reference-specific central registry edits, +- scale-sensitive composition has no repeated accumulator spread, +- membership scans are indexed, +- cross-feature/context illegal imports fail, +- app boot routing is hierarchical, +- cardinality budgets are executable. + +Otherwise: **์•„์ง ๋” ๋ด์•ผ๋Œ**. diff --git a/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/specs/2026-09-23-extreme-scale-frontend-architecture-design.md b/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/specs/2026-09-23-extreme-scale-frontend-architecture-design.md new file mode 100644 index 00000000..c327cc88 --- /dev/null +++ b/docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/specs/2026-09-23-extreme-scale-frontend-architecture-design.md @@ -0,0 +1,1294 @@ +# Extreme-Scale Frontend Architecture Design + +- Date: 2026-09-23 +- Target: `clean-architecture-frontend-template` +- Status: Design approved in conversation; implementation plan not yet written +- Intended repository path: `docs/superpowers/specs/2026-09-23-extreme-scale-frontend-architecture-design.md` + +## 1. Purpose + +This design evolves the frontend template from a single-application Clean Architecture skeleton into a frontend application platform that remains maintainable when logical domain count, traffic, failure rate, and operating duration become extreme. + +The design must remain valid under worst-case growth assumptions: + +- 100, 1,000, 10,000, 100,000, or 1,000,000 logical features/domains across the product ecosystem. +- Short, severe spike traffic. +- Sustained high traffic over long periods. +- Partial and total backend failures. +- Retry storms, telemetry storms, cache-miss storms, and slow upstreams. +- Long-lived browser sessions. +- Multi-replica frontend deployments during rolling releases. + +The goal is **not** to make one SPA compile and boot one million features. The goal is to make global growth independent from local runtime and build cost by enforcing bounded architecture boundaries. + +## 2. Core Principle + +> No cardinality may become implicitly unbounded. + +The same rule applies to: + +- compile graphs, +- route graphs, +- feature registries, +- cross-feature dependencies, +- HTTP request fan-out, +- retries, +- concurrency, +- payload size, +- validation cost, +- telemetry buffering, +- timers/listeners, +- browser storage, +- failure propagation. + +The platform must expose these costs explicitly in code and CI instead of allowing them to hide behind arrays, `map`, `Promise.all`, global registries, retries, timers, or framework abstractions. + +## 3. Scale Model + +### 3.1 Separate global and local cardinality + +Two different concepts must never be conflated: + +```text +GlobalFeatureCount += logical feature count across the whole product ecosystem + +LocalFeatureCount += feature count compiled and booted by one deployable frontend application +``` + +A system may contain 1,000,000 logical features while an individual deployable app sees only 100-300 features. + +### 3.2 Architectural hierarchy + +```text +Product + -> Deployable App + -> Bounded Context + -> Feature + -> Use Case / Operation + -> Route / Adapter +``` + +A parent boundary knows only its direct children. It does not flatten every descendant into a global registry. + +Example: + +```text +Product + -> Commerce App + -> Order Context + -> Order Creation Feature + -> Payment Context + -> Account App + -> Identity Context +``` + +`Product` must not import `OrderCreatePage`, `PaymentRefundUseCase`, or other deep descendants. + +### 3.3 Scale escape rule + +When a boundary reaches its measured cardinality ceiling, the response is architectural split, not increasing the ceiling indefinitely. + +```text +Feature too large + -> split feature + +Context too large + -> split bounded context + +App too large + -> split deployable app +``` + +This is equivalent to refusing an implicit unbounded one-to-many relation in server-side architecture. + +## 4. Target Source Structure + +```text +src/ +โ”œโ”€ domain/ +โ”œโ”€ application/ +โ”‚ โ””โ”€ ports/ +โ”œโ”€ contracts/ +โ”œโ”€ platform/ +โ”‚ โ”œโ”€ cardinality/ +โ”‚ โ”œโ”€ traffic/ +โ”‚ โ”œโ”€ resilience/ +โ”‚ โ”œโ”€ errors/ +โ”‚ โ”œโ”€ validation/ +โ”‚ โ””โ”€ telemetry/ +โ”œโ”€ features/ +โ”‚ โ””โ”€ / +โ”‚ โ”œโ”€ domain/ +โ”‚ โ”œโ”€ application/ +โ”‚ โ”œโ”€ contracts/ +โ”‚ โ”œโ”€ adapters/ +โ”‚ โ”œโ”€ presentation/ +โ”‚ โ””โ”€ feature-module.ts +โ”œโ”€ contexts/ +โ”‚ โ””โ”€ / +โ”‚ โ””โ”€ context-module.ts +โ”œโ”€ apps/ +โ”‚ โ””โ”€ / +โ”‚ โ””โ”€ app-module.ts +โ”œโ”€ .generated/ +โ”‚ โ””โ”€ +โ””โ”€ bootstrap/ + โ””โ”€ compose-product.ts +``` + +The exact path layout may adapt to current repository conventions, but ownership boundaries are mandatory. + +## 5. Module Ownership + +### 5.1 Feature module + +Each feature owns one descriptor containing its own contributions. + +Conceptual API: + +```ts +export const ORDER_FEATURE = defineFeatureModule({ + id: "order", + contracts, + adapters, + runtime, + routes, + messages, + invalidation, + telemetry, +}); +``` + +A new feature must not require hand editing multiple central installation files. + +Target change surface: + +```text +src/features/new-feature/** +.generated/** +``` + +Central handwritten production files changed for a normal feature addition: + +```text +0 preferred +1 maximum when a deliberate bounded-context registration is required +``` + +### 5.2 Bounded context module + +A context composes only its direct feature modules. + +```ts +export const COMMERCE_CONTEXT = defineBoundedContextModule({ + id: "commerce", + features: COMMERCE_FEATURE_INDEX, + budget: COMMERCE_CARDINALITY_BUDGET, +}); +``` + +It does not expose concrete internal feature implementations to unrelated contexts. + +### 5.3 Deployable app module + +A deployable app owns only direct bounded contexts. + +```ts +export const CUSTOMER_APP = defineDeployableApp({ + id: "customer", + contexts: CUSTOMER_CONTEXT_INDEX, +}); +``` + +Each app becomes an independent compilation and deployment unit once scale requires it. + +### 5.4 Generated indexes + +Indexes are generated at build time from approved static source declarations. + +Required properties: + +- static TypeScript imports, +- deterministic output, +- no arbitrary runtime import path, +- no runtime plugin discovery from untrusted configuration, +- generated files are not handwritten registries. + +This preserves tree-shaking, supply-chain reviewability, and compile-time visibility while eliminating central merge hotspots. + +## 6. Dependency Rules + +### 6.1 Cross-feature concrete imports are forbidden + +For different features A and B: + +```text +src/features/A/** -> src/features/B/** +``` + +is an architecture violation unless the dependency is through an explicitly approved public contract boundary. + +Preferred interaction boundaries: + +```text +feature + -> src/contracts + -> src/application/ports + -> explicit orchestration/workflow feature +``` + +### 6.2 Cross-context imports are stricter + +A context must not import another context's concrete feature internals. + +Allowed communication is through: + +- public contracts, +- application ports, +- explicitly named integration contracts, +- server-backed integration where appropriate. + +### 6.3 Cycles are always forbidden + +No cycle is permitted across feature, context, or app boundaries. + +## 7. Cardinality Budgets + +The platform defines explicit architectural budgets. + +Conceptual shape: + +```ts +interface ArchitectureCardinalityBudget { + readonly maxContextsPerApp: number; + readonly maxFeaturesPerContext: number; + readonly maxRoutesPerFeature: number; + readonly maxOperationsPerFeature: number; + readonly maxMessagesPerFeature: number; +} +``` + +Initial numeric values are not hardcoded by this design. They must be established through repository benchmarks. + +Budget files must be visible in review and version controlled. + +Budget increases must produce a detectable architecture-review signal. + +Example failure: + +```text +ARCHITECTURE_CARDINALITY_EXCEEDED +Context: commerce +Current: 201 +Allowed: 200 +Action: split the context or create another deployable boundary. +``` + +## 8. Registry Composition + +### 8.1 No repeated object spread in accumulation loops + +This pattern is forbidden in scale-sensitive composition paths: + +```ts +features.reduce( + (registry, feature) => ({ ...registry, ...feature.routes }), + {}, +); +``` + +It repeatedly copies accumulated state and becomes quadratic-like as the registry grows. + +### 8.2 Required composition strategy + +Use one mutable local accumulator, explicit duplicate detection, then freeze once. + +```ts +const result = Object.create(null); + +for (const feature of features) { + for (const [id, route] of Object.entries(feature.routes)) { + if (Object.hasOwn(result, id)) { + throw new DuplicateRouteError(id); + } + result[id] = route; + } +} + +return Object.freeze(result); +``` + +The same strategy applies to operation, schema, mapper, invalidation, adapter, runtime, and message contribution composition when a registry is necessary. + +### 8.3 Membership checks + +Repeated linear membership tests such as: + +```ts +installedIds.includes(featureId) +``` + +must not be used in scale-sensitive loops. + +Build a `Set` once and use `has`. + +## 9. Router Architecture + +A flat product-wide route table is not an acceptable extreme-scale model. + +Target hierarchy: + +```text +Product Router + -> Deployable App Router + -> Context Router + -> Feature Router + -> Page Route +``` + +Only the next boundary is loaded eagerly. + +Example at global scale: + +```text +Global logical features: 1,000,000 +Browser boot routes: product/app boundary only +Commerce app selected: commerce context routes loaded +Order context selected: order feature routes loaded +``` + +Global feature count must not linearly increase initial route object count, initial bundle size, or boot heap. + +## 10. Execution Model + +### 10.1 Interaction is the root execution scope + +HTTP requests are not the highest-level unit. A user or application interaction is. + +Examples: + +- open an order page, +- submit a payment, +- change workspace, +- load search results. + +Conceptual context: + +```ts +interface ExecutionContext { + readonly interaction: InteractionContext; + readonly traffic: TrafficContext; + readonly telemetry: TelemetryContext; + readonly cancellation: CancellationContext; +} +``` + +Operations run under the same interaction scope. + +### 10.2 Interaction context + +```ts +interface InteractionContext { + readonly interactionId: InteractionId; + readonly startedAt: number; + readonly deadlineAt: number; +} +``` + +All child operations inherit correlation and deadline information. + +## 11. Traffic Budget + +Traffic cost must be explicit and bounded. + +Conceptual model: + +```ts +interface TrafficBudget { + readonly maxPhysicalRequests: number; + readonly maxConcurrentRequests: number; + readonly maxRetries: number; + readonly deadlineMs: number; +} +``` + +A feature owns the policy declaration; the platform owns enforcement. + +```ts +defineQueryOperation({ + id: "order.list", + traffic: { + maxPhysicalRequests: 2, + maxConcurrentRequests: 2, + maxRetries: 1, + deadlineMs: 4_000, + }, +}); +``` + +The platform must not maintain one global per-feature traffic registry. + +## 12. Request Fan-Out + +Frontend N+1 is treated as an architecture defect. + +Forbidden behavior: + +```text +load 1 collection + -> N rows + -> N detail requests +``` + +Preferred behavior: + +- pagination/cursor APIs, +- bounded page sizes, +- backend bulk endpoints, +- backend read models, +- request coalescing, +- shared query/cache ownership. + +A representative user interaction must have a physical-request budget. + +Synthetic integration tests increase data cardinality while asserting that network request count remains bounded rather than O(N). + +## 13. Retry Model + +### 13.1 Retry budget is interaction-scoped + +Retry count is not independently reset for every request. + +```text +Interaction retry budget = 2 +A consumes retry +B consumes retry +C cannot retry after budget exhaustion +``` + +This prevents multiple child requests from multiplying recovery traffic. + +### 13.2 Retry prerequisites + +Retries are allowed only when operation semantics permit them. + +The existing idempotency/replay semantics remain authoritative. + +### 13.3 Retry-After and jitter + +A `Retry-After` response must not synchronize all clients into a second spike. + +Effective scheduling combines server guidance with bounded jitter. + +## 14. Concurrency Budget + +Each interaction has bounded concurrent physical requests. + +Waiting work must be cancelable. + +Cancellation of an interaction must cancel or release: + +- queued requests, +- in-flight requests where possible, +- retry timers, +- concurrency leases, +- delayed telemetry associated only with that discarded interaction when safe. + +## 15. Deadline Propagation + +Timeouts do not reset after each retry or downstream call. + +A root deadline is established at interaction start. + +Each child computes remaining time: + +```ts +remainingMs = deadlineAt - now(); +``` + +A chain of retries therefore cannot turn a 5-second user operation into an unbounded 20- or 30-second operation. + +## 16. Request Deduplication and Coalescing + +Multiple consumers requesting the same logical resource concurrently should share compatible in-flight work. + +```text +10 consumers + -> 1 physical request + -> 10 subscribers +``` + +The existing TanStack Query infrastructure is a natural implementation foundation where its semantics match the operation. + +Deduplication must never merge requests across incompatible authentication, tenant, scope, locale, or cache identity boundaries. + +## 17. Error Model + +Errors are owned at the correct boundary. + +```text +Platform Error +Contract Error +Application / Domain Error +Presentation Mapping +``` + +### 17.1 Platform errors + +Examples: + +- network unavailable, +- request timeout, +- cancellation, +- response too large, +- unsupported content type, +- malformed transport response, +- traffic budget exceeded. + +### 17.2 Contract errors + +Contract failures identify violations at an external boundary: + +- schema mismatch, +- protocol mismatch, +- unsupported media type, +- missing required field, +- malformed payload. + +### 17.3 Domain/application errors + +Concrete business errors remain feature-owned. + +Example: + +```ts +type PaymentError = + | PaymentDeclined + | PaymentAlreadyProcessed + | PaymentLimitExceeded; +``` + +### 17.4 No global error union + +This is forbidden: + +```ts +type GlobalApplicationError = + | OrderError + | PaymentError + | ...; +``` + +Use local generic boundaries instead: + +```ts +Result +``` + +The platform understands only the common envelope. + +## 18. Error Envelope + +Unstructured `throw new Error("...")` is not the primary cross-layer error contract. + +Conceptual common metadata: + +```ts +interface AppError { + readonly kind: string; + readonly category: ErrorCategory; + readonly retryability: Retryability; + readonly severity: ErrorSeverity; +} +``` + +Concrete domain error semantics remain local. + +## 19. Presentation Error Mapping + +HTTP status codes and transport details must not leak into presentation logic. + +Bad: + +```ts +if (status === 409) { ... } +``` + +Preferred flow: + +```text +HTTP 409 + -> Transport/Contract interpretation + -> PaymentAlreadyProcessed + -> localized presentation message +``` + +## 20. Validation Boundaries + +Validation has distinct purposes: + +1. user-input validation, +2. transport validation, +3. domain invariant validation, +4. runtime configuration validation. + +Frontend validation improves UX but is never an authoritative security boundary. Backend validation remains authoritative. + +## 21. Validate Once at Trust Boundaries + +External data enters as unknown/untrusted data. + +```text +unknown HTTP body + -> size/content checks + -> parse + -> schema validation + -> Validated DTO + -> mapper + -> domain/application types +``` + +The same payload should not be repeatedly schema-validated at every internal layer without a specific trust-boundary reason. + +## 22. Validation Budget + +Validation itself has bounded cost. + +Before expensive parsing and validation, enforce structural constraints where possible: + +- maximum response bytes, +- maximum collection items, +- maximum string lengths, +- maximum allowed nesting/depth where relevant, +- bounded mapper output size. + +Oversized responses must be rejected before allocating or validating an arbitrarily large object graph. + +## 23. Telemetry Model + +Production frontend observability is required, but raw logging is not the architecture. + +The platform supports: + +- error reporting, +- real user monitoring, +- trace/correlation propagation, +- structured operational events, +- performance metrics. + +Feature code must not depend directly on a vendor SDK such as Sentry or Datadog. + +Conceptual port: + +```ts +interface TelemetryPort { + emit(event: TelemetryEvent): void; +} +``` + +Provider adapters live behind the platform boundary. + +## 24. Telemetry Ownership + +The platform owns a common envelope, not every feature event definition. + +Common metadata may include: + +- event name, +- severity, +- release, +- app/context/feature identifiers, +- interaction ID, +- trace/correlation identifiers, +- timestamp, +- safe attributes. + +Concrete event payload schemas remain feature-owned. + +No global telemetry event union containing every feature is allowed. + +## 25. Telemetry Pipeline + +Required conceptual pipeline: + +```text +Feature event + -> normalize + -> redact + -> fingerprint + -> deduplicate + -> sample + -> bounded buffer + -> batch + -> rate limit + -> transport +``` + +All in-browser queues and maps are bounded. + +## 26. Telemetry Must Fail Open for Business Behavior + +Telemetry failure must not fail application behavior. + +```text +business path +telemetry path +``` + +are separated. + +When telemetry capacity is exhausted, low-priority observability data is dropped rather than growing browser memory or blocking user operations. + +## 27. Telemetry Storm Protection + +A production incident may cause millions of browsers to report the same error simultaneously. + +The telemetry subsystem therefore requires: + +- deterministic or policy-driven sampling, +- repeated-error fingerprinting, +- bounded deduplication state, +- bounded batch size, +- bounded queue bytes/events, +- rate limiting, +- priority-based dropping. + +Observability must never amplify an incident into another outage. + +## 28. Telemetry Privacy and Redaction + +Feature authors must not be able to casually emit secrets. + +Runtime sanitization must reject/redact sensitive classes such as: + +- Authorization values, +- cookies, +- access tokens, +- refresh tokens, +- passwords, +- known secret fields. + +Typed safe payloads may be added where they improve correctness, but runtime defense remains required because compile-time types are not a security boundary. + +## 29. Trace and Correlation + +User interactions should connect browser events with backend traces where supported. + +```text +user interaction + -> interaction id + -> request trace/correlation metadata + -> backend trace + -> downstream dependency +``` + +Trace propagation must follow the chosen backend/OTel contract and must not invent incompatible identifiers independently per feature. + +## 30. Failure Boundaries + +Failure containment mirrors architecture ownership. + +```text +App Boundary + -> Context Boundary + -> Feature Boundary + -> Page Boundary where useful +``` + +Not every component gets an ErrorBoundary. Boundaries correspond to meaningful recovery/fallback domains. + +A payment UI failure should not necessarily destroy order, catalog, or account UI. + +## 31. Async Failure Model + +React render failures are only one class of failure. + +The architecture also models: + +- query failure, +- mutation failure, +- validation failure, +- timeout, +- cancellation, +- traffic-budget exhaustion. + +Presentation state should distinguish recoverable, terminal, and cancelled outcomes where useful. + +## 32. Spike Traffic Design + +Spike scenarios include rapid jumps such as: + +```text +100 clients + -> 10,000 + -> 100,000+ +``` + +The frontend platform cannot control the number of users, but it must control client-side amplification. + +Critical risks: + +- retry storm, +- authentication refresh storm, +- cache-miss storm, +- telemetry storm, +- synchronized `Retry-After`, +- uncontrolled concurrency, +- duplicate requests. + +## 33. Sustained Traffic Design + +Long-running high traffic and long-lived SPA sessions expose different risks: + +- heap growth, +- timer/listener leaks, +- query cache churn, +- browser storage growth, +- stale auth/session state, +- repeated background polling, +- telemetry backlog, +- orphaned AbortControllers or tasks. + +Scale verification therefore includes soak-style tests and memory slope, not only peak request count. + +## 34. Amplification Metrics + +The platform test harness defines operational amplification metrics. + +### 34.1 Request amplification + +```text +physical HTTP requests / logical interactions +``` + +### 34.2 Retry amplification + +```text +total physical attempts / initial physical requests +``` + +### 34.3 Telemetry amplification + +```text +telemetry sends / logical failures or events +``` + +These are measured under healthy, slow, partial-failure, and total-failure conditions. + +## 35. Scale Profiles + +Synthetic scale profiles: + +```text +S0 100 +S1 1,000 +S2 10,000 +S3 100,000 +S4 1,000,000 +``` + +These do not all mean โ€œgenerate that many TypeScript source filesโ€. + +### S0-S1 + +Can exercise concrete module composition and type-check fixtures. + +### S2 + +Exercises larger generated indexes and composition structures when affordable. + +### S3-S4 + +Primarily verify global topology and local-boundary independence. They model one hundred thousand or one million logical features while asserting that any one app/context remains within local budgets. + +## 36. Local Scale Verification + +Within one allowed boundary, measure: + +- registry composition, +- route composition, +- generated index cost, +- TypeScript diagnostics, +- bundle/build cost, +- browser boot cost. + +Scale-sensitive composition should exhibit linear-or-better growth where linear work is unavoidable. + +Quadratic-like growth is a failure. + +## 37. Global Topology Verification + +Increase global logical cardinality while holding one app unchanged. + +Assertions: + +```text +Global feature count increases +but unchanged App A should not materially increase: +- TypeScript source graph +- initial bundle bytes +- initial routes +- initial runtime registries +- boot heap +- boot CPU +``` + +This is the critical proof that the architecture can extend toward 100K/1M logical domains. + +## 38. TypeScript Scale Gate + +Use compiler diagnostics where supported, including `--extendedDiagnostics`. + +Track at least: + +- source file count, +- type count, +- symbol count, +- instantiations, +- memory, +- total type-check time. + +A global module augmentation or giant union that causes unrelated app compile cost to rise with global domain count is a design regression. + +## 39. Runtime Composition Scale Gate + +Benchmark relevant registries: + +- route, +- API operation, +- schema, +- mapper, +- invalidation, +- adapter contribution, +- runtime contribution, +- locale/message contribution. + +Test multiple N values to detect nonlinear regression. + +Absolute timing alone is insufficient; growth behavior matters. + +## 40. Browser Boot Gate + +Measure: + +- initial JS transferred, +- parsed/executed JS, +- initial route count, +- initial heap, +- bootstrap CPU, +- runtime config fetch, +- release manifest verification, +- first meaningful application render. + +Global topology growth must not cause proportional growth in these metrics for an unchanged app. + +## 41. Request Fan-Out Gate + +Use representative collection pages with increasing server-returned cardinality: + +```text +N = 10 +N = 100 +N = 1,000 +``` + +A page that requires two bounded bulk requests should remain around that request count instead of issuing O(N) row-detail calls. + +> **Implementation note (2026-09-23).** The template's representative collection contract is a paginated bulk read with a hard page ceiling of 100 rows (`limit` โ‰ค 100, response schema `max(100)`). `N` above is the server-side collection cardinality, not the size of one response. Acceptance is therefore two-layered: +> +> - supported cardinality โ€” collections of N = 10 / 50 / 100 / 1,000 rows load a page with **1** physical request, and a full 1,000-row walk costs โ‰ค ceil(N / 100) + 1 page requests, never one request per row; +> - oversized response โ€” a single response carrying more than the page ceiling (e.g. 1,000 rows at once) is rejected within **1** request as a contract violation, with no per-row downstream fan-out. +> +> The ceiling is not raised to make an oversized fixture pass. A source gate (`pnpm check:request-fanout`) rejects any request dispatch inside a loop or array-iteration callback in feature/application code. + +## 42. Failure and Chaos Scenarios + +Required scenarios include: + +### Total API failure + +Verify: + +- retry bound, +- concurrency bound, +- telemetry bound, +- bounded memory, +- no infinite loop, +- no reload loop. + +### Partial failure + +Example: + +```text +Payment 100% failure +Order healthy +Catalog healthy +``` + +Payment should degrade without collapsing unrelated contexts. + +### Slow API + +Test long-tail latency. Verify deadlines, cancellation, concurrency queues, and queue limits. + +### Network flap + +Repeated online/offline transitions must not produce duplicate unsafe mutations or retry bursts. + +### Telemetry endpoint failure + +Business behavior remains functional and telemetry storage remains bounded. + +## 43. Telemetry Storm Test + +Generate a large number of identical errors/events. + +Expected behavior: + +```text +many logical errors + -> fingerprint/dedup/sample + -> bounded number of buffered/sent telemetry events +``` + +The test records emitted, deduplicated, sampled, dropped, and transmitted counts. + +## 44. Soak Testing + +Long-session profiles may include 30 minutes, 2 hours, 8 hours, or 24 hours depending on environment cost. + +Observe: + +- heap size and slope, +- active timers, +- event listeners, +- DOM nodes, +- query cache size, +- telemetry buffer, +- IndexedDB/browser storage, +- stale auth/session leakage. + +The primary leak signal is sustained positive growth after expected warm-up stabilization, not only an arbitrary maximum heap value. + +## 45. Horizontal Scaling and Release Coherence + +Frontend application instances are intended to remain stateless with respect to server-hosted browser user state. + +Horizontal scaling is safe only when release coherence is maintained. + +Deployment contract: + +- content-hashed assets are immutable, +- HTML is revalidated/no-cache according to current release strategy, +- runtime config and release manifest are no-store, +- old hashed assets remain available during rolling release windows, +- a deployment switches an active release tuple atomically, +- mixed incompatible HTML/config/manifest combinations fail closed rather than executing ambiguously. + +## 46. Multi-Replica Release Matrix + +At minimum verify: + +| HTML | Config | Manifest | Asset | Expected | +| --- | --- | --- | --- | --- | +| R10 | R10 | R10 | R10 | PASS | +| R10 | R11 | R10 | R10 | FAIL CLOSED | +| R10 | R10 | R11 | R10 | FAIL CLOSED | +| R10 | R10 | R10 | missing/incompatible | FAIL | +| R11 | R11 | R11 | R11 | PASS | + +Rolling deployments must also preserve reachability of previous immutable hashed assets for clients that loaded earlier HTML. + +## 47. CI Execution Tiers + +Heavy scale tests must not make every pull request unusably expensive. + +### Pull request + +Fast deterministic gates: + +- dependency architecture, +- cardinality budgets, +- unit tests, +- app/test type-check, +- small composition fixtures, +- duplicate collision tests, +- cross-feature dependency fixture, +- small request fan-out fixture. + +### Main branch + +Medium scale regression: + +- 1K/10K synthetic composition where appropriate, +- TypeScript diagnostic comparison, +- route/bootstrap growth checks, +- generated index validation. + +### Nightly + +Heavy synthetic and browser verification: + +- 10K/100K/1M topology model, +- browser memory and route loading, +- telemetry storm, +- failure scenarios, +- longer navigation/session cycles. + +### Release / dedicated environment + +Environment-dependent checks: + +- spike load, +- soak load, +- cache behavior, +- multi-replica mixed-release validation, +- CDN/LB/origin release contract. + +## 48. Benchmark Result Format + +Scale results are machine-readable artifacts, not only console output. + +Example: + +```json +{ + "profile": "S2", + "globalLogicalFeatures": 10000, + "localFeatures": 150, + "routeCompositionMs": 3.21, + "typescriptMs": 4312, + "heapBytes": 1234567 +} +``` + +Store enough metadata to compare against a compatible baseline. + +## 49. Regression Policy + +Use three kinds of thresholds: + +1. absolute ceiling, +2. relative regression percentage, +3. growth-complexity trend. + +Performance measurements should use multiple runs and robust summaries such as median where environment noise is relevant. + +Structural failures such as cycles, duplicate IDs, cross-feature concrete imports, or cardinality-budget violations are deterministic and should fail immediately. + +## 50. Required Architecture Gates + +The architecture must eventually provide automated gates for: + +1. cross-feature concrete import prohibition, +2. cross-context concrete import prohibition, +3. cycle prohibition, +4. cardinality budgets, +5. duplicate feature/route/operation/schema IDs, +6. O(Nยฒ)-style registry regression, +7. request fan-out regression, +8. retry-budget enforcement, +9. telemetry-buffer boundedness, +10. global-to-local scale independence, +11. TypeScript/build scale regression, +12. multi-replica release coherence. + +## 51. Compatibility With Current Template Strengths + +This design preserves and extends current strengths rather than replacing them: + +- Clean Architecture layer rules, +- capability-driven adapter composition, +- HTTP operation contracts, +- bounded response handling, +- retry/idempotency semantics, +- TanStack Query cache ownership, +- scope fencing/generation behavior, +- release/build/config coherence, +- immutable static asset release model. + +The implementation should refactor composition and introduce platform policies without unnecessary UI/design changes. + +## 52. Explicit Non-Goals + +This design does not require: + +- one SPA containing 1M TypeScript features, +- runtime discovery of arbitrary remote code, +- Module Federation or micro-frontends as the default starting point, +- a global mega-registry, +- a global mega-error union, +- a global telemetry schema union, +- vendor-specific observability APIs in feature code, +- frontend validation as a replacement for backend validation. + +Remote/micro-frontend deployment can remain an optional future escalation when organizational or deployment boundaries require independent teams/releases. It is not required to solve the current scaling architecture. + +## 53. Implementation Sequence Constraints + +Implementation should be incremental and preserve behavior. + +A safe high-level sequence is: + +1. establish deterministic architecture/scale tests around current behavior, +2. remove known O(Nยฒ) and repeated-membership composition paths, +3. introduce feature-owned descriptor boundaries, +4. generate static product/context indexes, +5. enforce cross-feature/context dependency rules, +6. introduce hierarchical route composition, +7. introduce cardinality budgets, +8. introduce execution context and traffic budgets, +9. normalize error and validation boundaries, +10. introduce telemetry port/pipeline/budgets, +11. add scale/chaos/soak/release gates by CI tier. + +The detailed implementation plan must decompose these into test-first tasks and identify exact existing files after re-reading the live repository state. + +## 54. Acceptance Criteria + +The design is considered implemented only when all of the following are true: + +- Adding a normal feature does not require editing a collection of central handwritten installation registries. +- Composition does not contain known quadratic accumulation patterns. +- Membership checks on scale-sensitive paths use appropriate indexed structures. +- Concrete imports across unrelated features fail architecture checks. +- Context/app cardinality ceilings are explicit and testable. +- An unchanged local app does not grow materially when global logical topology grows toward S3/S4 fixtures. +- Initial routing is hierarchical/lazy rather than a product-wide flat feature table. +- User interactions carry bounded request, retry, concurrency, cancellation, and deadline semantics. +- Representative collections do not create frontend N+1 request fan-out. +- Errors remain local and typed without constructing a global union of all feature errors. +- External data is validated at trust boundaries with bounded payload/structure cost. +- Feature code emits observability through a platform port rather than vendor SDKs. +- Telemetry is redacted, deduplicated, sampled, buffered, and rate-limited with bounded memory. +- Telemetry failure does not fail business behavior. +- Failure boundaries prevent one feature/context from unnecessarily collapsing unrelated UI. +- Spike and sustained-load tests detect request, retry, telemetry, and memory amplification. +- Multi-replica release tests verify fail-closed coherence and old-asset reachability. + +## 55. Design Summary + +The architecture is based on one rule: + +> Global scale must be partitioned into bounded local scale, and every remaining local cardinality must have an explicit budget. + +Therefore the platform avoids: + +```text +unbounded registry +unbounded compile graph +unbounded route graph +unbounded request fan-out +unbounded retries +unbounded concurrency +unbounded payloads +unbounded validation +unbounded telemetry +unbounded memory growth +unbounded failure propagation +``` + +This allows the product ecosystem to grow from hundreds toward hundreds of thousands or millions of logical domains without requiring a single browser, TypeScript compiler invocation, router, or runtime registry to directly carry that global cardinality. diff --git a/docs/reviews/2026-09-23-release-coherence-baseline.md b/docs/reviews/2026-09-23-release-coherence-baseline.md new file mode 100644 index 00000000..5f901d20 --- /dev/null +++ b/docs/reviews/2026-09-23-release-coherence-baseline.md @@ -0,0 +1,38 @@ +# Release coherence baseline (2026-09-23) + +Verified before Phase 5 edits. Only fields and paths that exist in the live tree are listed. + +## Identity tuple + +| Source | Where it is read | Boot-critical identity fields | +| --- | --- | --- | +| HTML + hashed JS (build) | `src/contracts/env.ts` `getBuildConfig()` (`VITE_BUILD_ID`) | `buildId`; optional expected `assetManifestHash` (`LoadReleaseManifestOptions.expectedAssetManifestHash`) | +| Runtime config (`/config.json`) | `src/bootstrap/load-runtime-config.ts`, `src/bootstrap/runtime-config-schema.ts` | `BUILD_ID` (optional in schema, always written by `scripts/generate-runtime-config.ts`), `RELEASE_ID` (same), `CONFIG_SCHEMA_VERSION` | +| Release manifest (`/release-manifest.json`) | `src/bootstrap/load-release-manifest.ts` | `buildId`, `releaseId`, `configSchemaVersion`, `assetManifestHash`, `contractSet` (V2) / `legacyApiContractVersion` (V1) | + +Existing checks before Phase 5: + +- `loadRuntimeConfig`: config `BUILD_ID` vs build `buildId` โ†’ `CONFIG_BUILD_MISMATCH`. +- `loadReleaseManifest` (order: build, config schema, V1 API contract, release, assets, then contract set): `MANIFEST_BUILD_MISMATCH`, `MANIFEST_CONFIG_SCHEMA_MISMATCH`, `MANIFEST_API_CONTRACT_MISMATCH`, `MANIFEST_RELEASE_MISMATCH`, `MANIFEST_ASSET_MISMATCH`, `CONTRACT_SET_*`. +- `src/contracts/compatibility.ts` `verifyCompatibilityTuple()` treats `releaseId` as a warning only; it is used by release tooling, not by boot. +- Boot failure renders `BootErrorShell` from `src/bootstrap/main.tsx`; there was no automatic boot reload, so no loop, but also no bounded recovery for a stale HTML document during a rolling release. +- Runtime chunk recovery already has a reload-once guard (`src/application/use-cases/decide-chunk-recovery.ts`, storage key `CHUNK_RELOAD_GUARD`). + +## Cache directives + +| Surface | `config/hosting/cache-policy.json` | `config/hosting/response-headers.fixture.json` | +| --- | --- | --- | +| `/` (HTML) | `no-cache` | `no-cache` | +| `/config.json` | `no-store` | `no-store` | +| `/release-manifest.json` | `no-store` | `no-store` | +| `/assets/*` (hashed) | `public, max-age=31536000, immutable` | same | + +Client side, `src/bootstrap/read-bounded-boot-json.ts` fetches config and manifest with `cache: "no-store"`. + +## Existing tests exercised before changes + +- `tests/runtime-schema/release-manifest.test.ts`, `tests/runtime-schema/runtime-config.test.ts` (boot loaders), `tests/unit/release-coherence.test.ts` and `tests/unit/compatibility.test.ts` (release tooling tuple), `tests/unit/read-bounded-boot-json.test.ts` (no-store boot reads), `scripts/verify-hosting-headers.ts` (fixture headers). + +## Phase 5 ruling + +No new identity format is introduced. Phase 5 extracts the existing comparisons into one pure validator (`src/platform/release/release-coherence.ts`) that both boot loaders delegate to, keeps the existing error codes and precedence, and adds a bounded reload-once recovery keyed by the mismatch. diff --git a/package.json b/package.json index ab51ed95..0e55b880 100644 --- a/package.json +++ b/package.json @@ -78,9 +78,9 @@ "test:realtime-removal": "node scripts/test-realtime-runtime-removal.ts", "test:reference-feature": "node scripts/run-vitest.ts run tests/features/reference-feature --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/reference-feature.xml --passWithNoTests", "check:v8-coverage-counter-semantics": "node scripts/check-v8-coverage-counter-semantics.ts", - "test:coverage": "corepack pnpm check:v8-coverage-counter-semantics && node scripts/run-vitest.ts run tests/runtime-schema tests/unit tests/contract tests/component tests/integration tests/features/reference-feature --coverage --maxWorkers=4 --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/coverage.xml && node scripts/check-risk-coverage.ts", + "test:coverage": "corepack pnpm check:v8-coverage-counter-semantics && node scripts/run-vitest.ts run tests/runtime-schema tests/unit tests/contract tests/component tests/integration tests/features/reference-feature tests/platform --coverage --maxWorkers=4 --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/coverage.xml && node scripts/check-risk-coverage.ts", "check:coverage:fixture": "node scripts/check-risk-coverage.ts --summary tests/fixtures/coverage/below-threshold.json --artifact artifacts/quality/risk-coverage-fixture.json", - "test:all": "corepack pnpm test:runtime-schema && corepack pnpm test:unit && corepack pnpm test:contract && corepack pnpm test:component && corepack pnpm test:integration && corepack pnpm test:reference-feature && corepack pnpm test:recipes", + "test:all": "corepack pnpm test:runtime-schema && corepack pnpm test:unit && corepack pnpm test:contract && corepack pnpm test:component && corepack pnpm test:integration && corepack pnpm test:reference-feature && corepack pnpm test:platform && corepack pnpm check:release-coherence && corepack pnpm test:recipes", "verify:lockfile": "corepack pnpm install --frozen-lockfile --ignore-scripts", "check:frozen-lockfile:fixture": "node scripts/check-frozen-lockfile-fixture.ts", "generate:artifact-schemas": "node scripts/generate-artifact-schemas.ts", @@ -131,7 +131,25 @@ "check:types:fixture:http-route-id": "tsc -p tests/fixtures/typecheck/tsconfig.http-route-id.json", "check:types:fixture:feature-contribution-input": "tsc -p tests/fixtures/typecheck/tsconfig.feature-contribution-input.json", "check:types:fixture:feature-capability-selection": "tsc -p tests/fixtures/typecheck/tsconfig.feature-capability-selection.json", - "check:types:fixture:direct-feature-composition": "tsc -p tests/fixtures/typecheck/tsconfig.direct-feature-composition.json" + "check:types:fixture:direct-feature-composition": "tsc -p tests/fixtures/typecheck/tsconfig.direct-feature-composition.json", + "generate:feature-index": "node scripts/generate-product-feature-index.ts", + "check:feature-index": "node scripts/generate-product-feature-index.ts --check", + "check:topology": "node scripts/run-vitest.ts run tests/architecture/topology-cardinality.test.ts tests/architecture/context-lazy-loading.test.ts tests/platform/cardinality tests/platform/routing --reporter=default", + "check:traffic": "node scripts/run-vitest.ts run tests/platform/execution tests/platform/traffic tests/platform/resilience --reporter=default", + "check:observability": "node scripts/run-vitest.ts run tests/platform/errors tests/platform/validation tests/platform/telemetry tests/architecture/observability-boundaries.test.ts --reporter=default", + "test:platform": "node scripts/run-vitest.ts run tests/platform tests/architecture --no-file-parallelism --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/platform.xml", + "check:scale:pr": "node scripts/scale/run-scale-profile.ts pr", + "check:scale:main": "node scripts/scale/run-scale-profile.ts main", + "check:scale:nightly": "node scripts/scale/run-scale-profile.ts nightly", + "check:scale:release": "node scripts/scale/run-scale-profile.ts release", + "check:scale:baseline": "node scripts/scale/check-scale-baseline.ts", + "update:scale-baseline": "node scripts/scale/check-scale-baseline.ts --update", + "verify:extreme-scale": "node scripts/verify-extreme-scale.ts", + "check:request-fanout": "node scripts/check-request-fanout.ts && node scripts/check-request-fanout.ts --fixture", + "check:app-build-input": "node scripts/check-app-build-input.ts", + "check:app-build-input:bundle": "node scripts/check-app-build-input.ts --require-bundle", + "test:extreme-scale:focused": "node scripts/run-vitest.ts run tests/scale/global-local-independence.test.ts tests/architecture/app-build-input.test.ts tests/architecture/request-fanout.test.ts tests/platform/traffic/request-fanout.test.ts tests/platform/traffic/request-deduplication.test.ts tests/features/reference-feature/reference-request-fanout.test.ts tests/features/reference-feature/reference-request-deduplication.test.ts tests/scripts/generate-product-feature-index.test.ts --reporter=default", + "check:release-coherence": "node scripts/run-vitest.ts run tests/platform/release tests/release --reporter=default" }, "dependencies": { "@tanstack/react-query": "5.101.4", diff --git a/scripts/check-app-build-input.ts b/scripts/check-app-build-input.ts new file mode 100644 index 00000000..c8c60024 --- /dev/null +++ b/scripts/check-app-build-input.ts @@ -0,0 +1,143 @@ +import { readFile } from "node:fs/promises"; +import path from "node:path"; + +import { + createFileSystemDeclarationSource, + type TopologyDeclarationSource, +} from "./generate-product-feature-index.ts"; + +/** + * Spec ยง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 + * app's declarations. The gate fails when + * - a generated index imports a feature or declares a context outside that + * ownership set (e.g. a regression back to "import every src/features"), + * - the production bundle's module inventory contains a module of a feature + * the app does not own. + */ +export type AppBuildInputReport = Readonly<{ + appId: string; + ownedContexts: readonly string[]; + ownedFeatureDirectories: readonly string[]; + generatedFeatureImports: readonly string[]; + generatedContexts: readonly string[]; + bundle: Readonly<{ checked: boolean; featureDirectories: readonly string[] }>; + violations: readonly string[]; +}>; + +const GENERATED = [ + "src/.generated/product-feature-index.ts", + "src/.generated/product-context-index.ts", + "src/.generated/product-app.ts", +] as const; + +function unique(values: Iterable): string[] { + return [...new Set(values)].sort(); +} + +export async function inspectAppBuildInput( + root: string, + options: Readonly<{ + source?: TopologyDeclarationSource; + bundleInventory?: string | null; + }> = {}, +): Promise { + const source = options.source ?? (await createFileSystemDeclarationSource(root)); + const [featureIndex, contextIndex, appIndex] = await Promise.all( + GENERATED.map((file) => readFile(path.join(root, file), "utf8")), + ); + const appId = /id:\s*"([^"]+)"/u.exec(appIndex ?? "")?.[1]; + const violations: string[] = []; + if (!appId || !source.app(appId)) { + violations.push(`generated app ${appId ?? ""} is not a declared deployable app`); + } + const ownedContexts = appId ? source.contextsOf(appId).map((context) => context.id) : []; + const ownedFeatureDirectories = unique( + ownedContexts.flatMap((contextId) => source.featuresOf(contextId).map((feature) => feature.directory)), + ); + const owned = new Set(ownedFeatureDirectories); + + const featureDirectoriesIn = (text: string) => + unique([...text.matchAll(/\.\.\/features\/([^/"']+)\//gu)].map((match) => match[1] as string)); + const generatedFeatureImports = unique([ + ...featureDirectoriesIn(featureIndex ?? ""), + ...featureDirectoriesIn(contextIndex ?? ""), + ]); + for (const directory of generatedFeatureImports) { + if (!owned.has(directory)) { + violations.push(`generated index imports feature "${directory}" not owned by app ${appId}`); + } + } + const generatedContexts = unique( + [...(contextIndex ?? "").matchAll(/defineBoundedContextModule\(\{\s*id:\s*"([^"]+)"/gu)].map( + (match) => match[1] as string, + ), + ); + const ownedContextSet = new Set(ownedContexts); + for (const contextId of generatedContexts) { + if (!ownedContextSet.has(contextId)) { + violations.push(`generated index declares context "${contextId}" not owned by app ${appId}`); + } + } + + let bundle: AppBuildInputReport["bundle"] = { checked: false, featureDirectories: [] }; + const inventoryPath = + options.bundleInventory === undefined + ? path.join(root, "artifacts/quality/vite-module-inventory.json") + : options.bundleInventory; + if (inventoryPath) { + const raw = await readFile(inventoryPath, "utf8").catch(() => null); + if (raw !== null) { + const inventory = JSON.parse(raw) as { chunks?: { modules?: string[] }[] }; + const modules = (inventory.chunks ?? []).flatMap((chunk) => chunk.modules ?? []); + const featureDirectories = unique( + modules.flatMap((module) => { + const match = /^src\/features\/([^/]+)\//u.exec(module); + return match ? [match[1] as string] : []; + }), + ); + bundle = { checked: true, featureDirectories }; + for (const directory of featureDirectories) { + if (!owned.has(directory)) { + violations.push(`production bundle contains feature "${directory}" not owned by app ${appId}`); + } + } + } + } + + return Object.freeze({ + appId: appId ?? "", + ownedContexts: unique(ownedContexts), + ownedFeatureDirectories, + generatedFeatureImports, + generatedContexts, + bundle, + violations, + }); +} + +async function main(): Promise { + // The bundle inventory is only meaningful right after a build of this tree; + // without `--require-bundle` the gate checks the generated indexes only, so a + // stale inventory from another build can never pass or fail it. + const requireBundle = process.argv.includes("--require-bundle"); + const report = await inspectAppBuildInput(process.cwd(), requireBundle ? {} : { bundleInventory: null }); + if (requireBundle && !report.bundle.checked) { + process.stderr.write("app build input: no production module inventory; run the build first\n"); + process.exit(1); + } + for (const violation of report.violations) process.stderr.write(`FAIL ${violation}\n`); + process.stdout.write( + `app build input: app=${report.appId} contexts=${report.ownedContexts.length} ` + + `features=${report.ownedFeatureDirectories.length} generatedImports=${report.generatedFeatureImports.length} ` + + `bundle=${report.bundle.checked ? `${report.bundle.featureDirectories.length} feature dirs` : "not checked"} ` + + `${report.violations.length === 0 ? "PASS" : "FAIL"}\n`, + ); + if (report.violations.length > 0) process.exitCode = 1; +} + +if (import.meta.url === `file://${process.argv[1]}`) { + await main(); +} diff --git a/scripts/check-architecture.ts b/scripts/check-architecture.ts index ee4c14f0..4853044b 100644 --- a/scripts/check-architecture.ts +++ b/scripts/check-architecture.ts @@ -824,14 +824,21 @@ async function runGraphFixtureChecks(): Promise { "tests/fixtures/architecture/dependency-graph", ); const allowedRoot = resolve(fixtureRoot, "allowed"); - const [allowedGraph, unresolvedGraph, layerGraph, cycleGraph, barrelGraph] = - await Promise.all([ - analyzeSourceGraph(allowedRoot, "src"), - analyzeSourceGraph(resolve(fixtureRoot, "unresolved"), "src"), - analyzeSourceGraph(resolve(fixtureRoot, "layer"), "src"), - analyzeSourceGraph(resolve(fixtureRoot, "cycle"), "src"), - analyzeSourceGraph(resolve(fixtureRoot, "barrel"), "src"), - ]); + const [ + allowedGraph, + unresolvedGraph, + layerGraph, + cycleGraph, + barrelGraph, + crossBoundaryGraph, + ] = await Promise.all([ + analyzeSourceGraph(allowedRoot, "src"), + analyzeSourceGraph(resolve(fixtureRoot, "unresolved"), "src"), + analyzeSourceGraph(resolve(fixtureRoot, "layer"), "src"), + analyzeSourceGraph(resolve(fixtureRoot, "cycle"), "src"), + analyzeSourceGraph(resolve(fixtureRoot, "barrel"), "src"), + analyzeSourceGraph(resolve(fixtureRoot, "cross-boundary"), "src"), + ]); const allowedFiles = new Set(await listFiles(allowedRoot)); const allowedSourceFile = resolve( allowedRoot, @@ -851,6 +858,24 @@ async function runGraphFixtureChecks(): Promise { ), ); const assertions = [ + { + name: "cross-feature concrete imports are rejected", + passed: blockingViolations(crossBoundaryGraph).some( + ({ rule, source, target }) => + rule === "features-do-not-import-other-features" && + source === "src/features/alpha/read-beta.ts" && + target === "src/features/beta/value.ts", + ), + }, + { + name: "cross-context concrete imports are rejected", + passed: blockingViolations(crossBoundaryGraph).some( + ({ rule, source, target }) => + rule === "contexts-do-not-import-other-contexts" && + source === "src/contexts/customer/read-admin.ts" && + target === "src/contexts/admin/value.ts", + ), + }, { name: "deep adapter import from outside the group is rejected", passed: blockingViolations(barrelGraph).some( diff --git a/scripts/check-diagnostics.ts b/scripts/check-diagnostics.ts index 5a0569f8..7823f6b5 100644 --- a/scripts/check-diagnostics.ts +++ b/scripts/check-diagnostics.ts @@ -4,8 +4,15 @@ import { diagnosticsReportArtifactSchema } from "./contracts/release-artifacts.t import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts"; import path from "node:path"; -import { DIAGNOSTIC_EVENT_REGISTRY } from "../src/contracts/diagnostics.ts"; -import { TELEMETRY_REGISTRY } from "../src/contracts/telemetry.ts"; +import { + DIAGNOSTIC_CONTEXT_ALLOWLIST, + DIAGNOSTIC_CONTEXT_CARDINALITY, + DIAGNOSTIC_EVENT_REGISTRY, +} from "../src/contracts/diagnostics.ts"; +import { + TELEMETRY_ATTRIBUTE_ALLOWLIST, + TELEMETRY_REGISTRY, +} from "../src/contracts/telemetry.ts"; const fixtureMode = process.argv.includes("--fixture"); const failures: string[] = []; @@ -40,7 +47,20 @@ const diagnosticProducerFiles: Readonly> = { "ui.render.failed": "src/application/create-application.ts", "release.mismatch.detected": "src/application/create-application.ts", "telemetry.delivery.dropped": "src/bootstrap/runtime-adapters.ts", - }; +}; + +for (const key of DIAGNOSTIC_CONTEXT_ALLOWLIST) { + if (!DIAGNOSTIC_CONTEXT_CARDINALITY[key]) { + failures.push(`diagnostic context key has no cardinality class: ${key}`); + } +} +for (const key of TELEMETRY_ATTRIBUTE_ALLOWLIST) { + // Defensive at runtime: the types already exclude it, the gate still checks. + const cardinality: string | undefined = DIAGNOSTIC_CONTEXT_CARDINALITY[key]; + if (cardinality === "request") { + failures.push(`request-cardinality telemetry attribute is forbidden: ${key}`); + } +} if (!fixtureMode) { for (const eventName of Object.keys(TELEMETRY_REGISTRY)) { diff --git a/scripts/check-request-fanout.ts b/scripts/check-request-fanout.ts new file mode 100644 index 00000000..a4a7838e --- /dev/null +++ b/scripts/check-request-fanout.ts @@ -0,0 +1,185 @@ +import { readdir, readFile } from "node:fs/promises"; +import path from "node:path"; + +import { parseAsync } from "@babel/core"; + +/** + * Spec ยง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 + * - inside a loop statement (for / for-of / for-in / while / do-while), or + * - inside a callback passed to an array iteration method + * (map, flatMap, forEach, filter, reduce, some, every, find, findIndex), + * where a dispatch is `fetch(...)`, or any method call on a receiver named like + * a transport (`http`, `executor`, `client`, `gateway`, `api`, `transport`). + * + * The HTTP runtime itself (src/adapters/http) owns its bounded retry loop and is + * out of scope. A reviewed exception is written on the call's line as + * `// fanout-reviewed: `. + */ +export const REQUEST_FANOUT_ROOTS = Object.freeze(["src/features", "src/application"]); + +const TRANSPORT_RECEIVER = /^(?:http|executor|client|gateway|api|transport)$|(?:Http|Executor|Client|Gateway|Api|Transport)$/u; +const ITERATION_METHODS = new Set([ + "map", + "flatMap", + "forEach", + "filter", + "reduce", + "some", + "every", + "find", + "findIndex", +]); +const LOOP_TYPES = new Set([ + "ForStatement", + "ForOfStatement", + "ForInStatement", + "WhileStatement", + "DoWhileStatement", +]); +const FUNCTION_TYPES = new Set(["ArrowFunctionExpression", "FunctionExpression"]); + +type Node = { type: string; loc?: { start: { line: number } } } & Record; + +export type FanoutViolation = Readonly<{ file: string; line: number; call: string; context: string }>; + +function receiverName(node: Node | undefined): string | null { + if (!node) return null; + if (node.type === "Identifier") return node["name"] as string; + if (node.type === "MemberExpression" && (node["property"] as Node).type === "Identifier") { + return ((node["property"] as Node)["name"] as string) ?? null; + } + if (node.type === "ThisExpression") return "this"; + return null; +} + +function dispatchDescription(call: Node): string | null { + const callee = call["callee"] as Node; + if (callee.type === "Identifier" && callee["name"] === "fetch") return "fetch()"; + if (callee.type === "MemberExpression") { + const receiver = receiverName(callee["object"] as Node); + const property = callee["property"] as Node; + const method = property.type === "Identifier" ? (property["name"] as string) : "?"; + if (receiver && TRANSPORT_RECEIVER.test(receiver)) return `${receiver}.${method}()`; + } + return null; +} + +function iterationCallback(parent: Node | undefined, child: Node): string | null { + if (!parent || parent.type !== "CallExpression" || !FUNCTION_TYPES.has(child.type)) return null; + if (!(parent["arguments"] as Node[]).includes(child)) return null; + const callee = parent["callee"] as Node; + if (callee.type !== "MemberExpression") return null; + const property = callee["property"] as Node; + const method = property.type === "Identifier" ? (property["name"] as string) : ""; + return ITERATION_METHODS.has(method) ? `.${method}() callback` : null; +} + +export async function findRequestFanout( + file: string, + sourceText: string, +): Promise { + const plugins: ("jsx" | ["typescript", { dts: boolean }])[] = [["typescript", { dts: false }]]; + if (file.endsWith(".tsx")) plugins.push("jsx"); + const tree = (await parseAsync(sourceText, { + filename: file, + babelrc: false, + configFile: false, + sourceType: "module", + parserOpts: { plugins }, + })) as unknown as Node | null; + if (!tree) throw new Error(`cannot parse ${file}`); + const lines = sourceText.split("\n"); + const violations: FanoutViolation[] = []; + + const visit = (node: Node, parent: Node | undefined, repeating: string | null): void => { + let context = repeating; + if (LOOP_TYPES.has(node.type)) context = node.type.replace("Statement", " loop"); + const callback = iterationCallback(parent, node); + if (callback) context = callback; + // A nested function declared (not iterated) resets the repetition context. + if (!callback && FUNCTION_TYPES.has(node.type)) context = null; + if (node.type === "FunctionDeclaration") context = null; + + if (node.type === "CallExpression" && context) { + const call = dispatchDescription(node); + const line = node.loc?.start.line ?? 0; + if (call && !/fanout-reviewed:\s*\S/u.test(lines[line - 1] ?? "")) { + violations.push({ file, line, call, context }); + } + } + for (const [key, value] of Object.entries(node)) { + if (key === "loc" || key === "start" || key === "end" || key === "extra") continue; + const children = Array.isArray(value) ? value : [value]; + for (const child of children) { + if (child && typeof child === "object" && typeof (child as Node).type === "string") { + visit(child as Node, node, context); + } + } + } + }; + visit(tree, undefined, null); + return violations; +} + +async function sourceFiles(directory: string): Promise { + const found: string[] = []; + let entries; + try { + entries = await readdir(directory, { withFileTypes: true }); + } catch { + return found; + } + for (const entry of entries) { + const target = path.join(directory, entry.name); + if (entry.isDirectory()) found.push(...(await sourceFiles(target))); + else if (/\.tsx?$/u.test(entry.name) && !/\.d\.ts$/u.test(entry.name)) found.push(target); + } + return found; +} + +export async function scanRequestFanout( + root: string, + roots: readonly string[] = REQUEST_FANOUT_ROOTS, +): Promise> { + const files = (await Promise.all(roots.map((entry) => sourceFiles(path.join(root, entry))))).flat(); + const violations: FanoutViolation[] = []; + for (const file of files) { + violations.push( + ...(await findRequestFanout(path.relative(root, file), await readFile(file, "utf8"))), + ); + } + return { files: files.length, violations }; +} + +async function main(): Promise { + const fixture = process.argv.includes("--fixture"); + const root = process.cwd(); + if (fixture) { + // The forbidden fixture must be rejected; the allowed fixture must pass. + const forbidden = await scanRequestFanout(root, ["tests/fixtures/architecture/request-fanout/forbidden"]); + const allowed = await scanRequestFanout(root, ["tests/fixtures/architecture/request-fanout/allowed"]); + const ok = forbidden.violations.length >= forbidden.files && forbidden.files > 0 && allowed.violations.length === 0; + process.stdout.write( + `request fan-out fixtures: forbidden ${forbidden.violations.length} rejected in ${forbidden.files} files, allowed ${allowed.violations.length} violations ${ok ? "PASS" : "FAIL"}\n`, + ); + if (!ok) process.exitCode = 1; + return; + } + const result = await scanRequestFanout(root); + for (const violation of result.violations) { + process.stderr.write( + `FAIL ${violation.file}:${violation.line} ${violation.call} inside ${violation.context}\n`, + ); + } + process.stdout.write( + `request fan-out: ${result.files} files scanned, ${result.violations.length} per-row dispatches ${result.violations.length === 0 ? "PASS" : "FAIL"}\n`, + ); + if (result.violations.length > 0) process.exitCode = 1; +} + +if (import.meta.url === `file://${process.argv[1]}`) { + await main(); +} diff --git a/scripts/generate-product-feature-index.ts b/scripts/generate-product-feature-index.ts new file mode 100644 index 00000000..7f96301d --- /dev/null +++ b/scripts/generate-product-feature-index.ts @@ -0,0 +1,376 @@ +import { mkdir, readdir, readFile, writeFile } from "node:fs/promises"; +import { dirname, relative, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +export type FeatureImportEntry = Readonly<{ + id: string; + importPath: string; +}>; + +export type FeatureIndexEntry = FeatureImportEntry & Readonly<{ + directory: string; + contextId: string; + contextRoutePath: string; + contextMaxFeatures: number; +}>; + +export function renderFeatureIndex(entries: readonly FeatureImportEntry[]): string { + const sorted = [...entries].sort((left, right) => left.id.localeCompare(right.id)); + const imports = sorted + .map( + (entry, index) => + `import { FEATURE_MODULE as featureModule${index} } from ${JSON.stringify(entry.importPath)};`, + ) + .join("\n"); + const modules = sorted.map((_, index) => ` featureModule${index},`).join("\n"); + const featureImports = imports.length > 0 ? `${imports}\n` : ""; + return `// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand.\nimport type { FeatureModule } from "../features/feature-module.ts";\n${featureImports}\nexport const PRODUCT_FEATURE_MODULES = Object.freeze([\n${modules}\n] as const);\n\ntype GeneratedProductFeatureModule = (typeof PRODUCT_FEATURE_MODULES)[number];\nexport type ProductFeatureModule =\n [GeneratedProductFeatureModule] extends [never]\n ? FeatureModule\n : GeneratedProductFeatureModule;\n`; +} + +export function renderContextIndex(entries: readonly FeatureIndexEntry[]): string { + if (entries.length === 0) { + return `// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand.\nexport const PRODUCT_CONTEXT_MODULES = Object.freeze([] as const);\n`; + } + const sorted = [...entries].sort((left, right) => left.id.localeCompare(right.id)); + const imports = sorted + .map( + (entry, index) => + `import { FEATURE_MODULE as featureModule${index} } from ${JSON.stringify(entry.importPath)};`, + ) + .join("\n"); + const indexById = new Map(sorted.map((entry, index) => [entry.id, index] as const)); + const grouped = new Map(); + for (const entry of sorted) { + const group = grouped.get(entry.contextId) ?? []; + group.push(entry); + grouped.set(entry.contextId, group); + } + + const contexts = [...grouped.entries()] + .sort(([left], [right]) => left.localeCompare(right)) + .map(([contextId, features]) => { + const first = features[0]; + if (!first) throw new Error(`Context ${contextId} has no features`); + for (const feature of features) { + if (feature.contextRoutePath !== first.contextRoutePath) { + throw new Error( + `Context ${contextId} has conflicting route paths: ${first.contextRoutePath}, ${feature.contextRoutePath}`, + ); + } + if (feature.contextMaxFeatures !== first.contextMaxFeatures) { + throw new Error( + `Context ${contextId} has conflicting maxFeatures budgets: ${first.contextMaxFeatures}, ${feature.contextMaxFeatures}`, + ); + } + } + if (features.length > first.contextMaxFeatures) { + throw new Error( + `Context ${contextId} feature cardinality ${features.length} exceeds budget ${first.contextMaxFeatures}`, + ); + } + const featureRefs = features + .map((feature) => `featureModule${indexById.get(feature.id)}`) + .join(", "); + const routeImports = features + .map( + (feature, index) => + ` import(${JSON.stringify(`../features/${feature.directory}/context-routes.ts`)})${index < features.length - 1 ? "," : ""}`, + ) + .join("\n"); + const routeSpreads = features + .map((_, index) => ` ...routeModule${index}.FEATURE_CONTEXT_ROUTES,`) + .join("\n"); + const routeBindings = features + .map((_, index) => `routeModule${index}`) + .join(", "); + return ` defineBoundedContextModule({\n id: ${JSON.stringify(contextId)},\n features: Object.freeze([${featureRefs}]),\n budget: Object.freeze({ maxFeatures: ${first.contextMaxFeatures} }),\n route: Object.freeze({\n path: ${JSON.stringify(first.contextRoutePath)},\n async loadRoutes() {\n const [${routeBindings}] = await Promise.all([\n${routeImports}\n ]);\n return Object.freeze([\n${routeSpreads}\n ]);\n },\n }),\n }),`; + }) + .join("\n"); + + const featureImports = imports.length > 0 ? `${imports}\n` : ""; + return `// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand.\nimport { defineBoundedContextModule } from "../contexts/bounded-context-module.ts";\n${featureImports}\nexport const PRODUCT_CONTEXT_MODULES = Object.freeze([\n${contexts}\n] as const);\n`; +} + +/** + * Spec ยง3.2 / ยง5. Ownership declarations the generator reads. Each boundary + * declares only its parent: + * + * src/apps//app-module.ts APP_MODULE_ID, APP_MAX_CONTEXTS + * src/contexts//context-module.ts CONTEXT_MODULE_ID, CONTEXT_APP_ID, + * CONTEXT_ROUTE_PATH, CONTEXT_MAX_FEATURES + * src/features//feature-module.ts FEATURE_MODULE_ID, FEATURE_CONTEXT_ID + * + * The generated indexes describe exactly one deployable app: the contexts it + * owns and the features those contexts own. Features of other apps are never + * imported, so global growth elsewhere cannot enter this app's compile or + * boot graph. + */ +export type AppDeclaration = Readonly<{ id: string; maxContexts: number }>; +export type ContextDeclaration = Readonly<{ + id: string; + appId: string; + routePath: string; + maxFeatures: number; +}>; +export type FeatureDeclaration = Readonly<{ + id: string; + contextId: string; + directory: string; +}>; + +/** + * Ownership-indexed view of the declarations. The generator only asks for one + * app, that app's contexts and those contexts' features, so its work and its + * output are local to the selected app. + */ +export interface TopologyDeclarationSource { + appIds(): readonly string[]; + app(appId: string): AppDeclaration | undefined; + contextsOf(appId: string): readonly ContextDeclaration[]; + featuresOf(contextId: string): readonly FeatureDeclaration[]; +} + +export type SelectedAppIndexes = Readonly<{ + app: AppDeclaration; + entries: readonly FeatureIndexEntry[]; + featureIndex: string; + contextIndex: string; + appIndex: string; +}>; + +export function renderAppIndex(app: AppDeclaration): string { + return `// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand. +export const PRODUCT_APP = Object.freeze({ + id: ${JSON.stringify(app.id)}, + maxContexts: ${app.maxContexts}, +} as const); +`; +} + +export function resolveSelectedApp( + source: TopologyDeclarationSource, + requested: string | undefined, +): string { + if (requested) { + if (!source.app(requested)) throw new Error(`Unknown deployable app: ${requested}`); + return requested; + } + const ids = source.appIds(); + if (ids.length !== 1) { + throw new Error( + `Select a deployable app with --app= or PRODUCT_APP_ID (declared: ${ids.join(", ") || "none"})`, + ); + } + return ids[0] as string; +} + +/** The production selection: one app -> its direct contexts -> their features. */ +export function selectAppIndexes( + source: TopologyDeclarationSource, + appId: string, +): SelectedAppIndexes { + const app = source.app(appId); + if (!app) throw new Error(`Unknown deployable app: ${appId}`); + const contexts = [...source.contextsOf(appId)].sort((left, right) => + left.id.localeCompare(right.id), + ); + const entries: FeatureIndexEntry[] = []; + let populatedContexts = 0; + for (const context of contexts) { + const features = source.featuresOf(context.id); + if (features.length === 0) continue; + populatedContexts += 1; + if (features.length > context.maxFeatures) { + throw new Error( + `Context ${context.id} feature cardinality ${features.length} exceeds budget ${context.maxFeatures}`, + ); + } + for (const feature of features) { + entries.push({ + id: feature.id, + importPath: `../features/${feature.directory}/feature-module.ts`, + directory: feature.directory, + contextId: context.id, + contextRoutePath: context.routePath, + contextMaxFeatures: context.maxFeatures, + }); + } + } + if (populatedContexts > app.maxContexts) { + throw new Error( + `App ${app.id} context cardinality ${populatedContexts} exceeds budget ${app.maxContexts}`, + ); + } + const ids = entries.map((entry) => entry.id); + if (new Set(ids).size !== ids.length) { + throw new Error(`Duplicate generated feature ids: ${ids.join(", ")}`); + } + return Object.freeze({ + app, + entries: Object.freeze(entries), + featureIndex: renderFeatureIndex(entries), + contextIndex: renderContextIndex(entries), + appIndex: renderAppIndex(app), + }); +} + +function requiredLiteral(source: string, name: string, file: string): string { + const match = source.match( + new RegExp(`export\\s+const\\s+${name}\\s*=\\s*["']([^"']+)["']`), + ); + if (!match?.[1]) { + throw new Error(`${file} must export a literal ${name}`); + } + return match[1]; +} + +function requiredInteger(source: string, name: string, file: string): number { + const match = source.match( + new RegExp(`export\\s+const\\s+${name}\\s*=\\s*(\\d+)`), + ); + const parsed = match?.[1] ? Number.parseInt(match[1], 10) : Number.NaN; + if (!Number.isSafeInteger(parsed) || parsed < 1) { + throw new Error(`${file} must export a positive integer ${name}`); + } + return parsed; +} + +async function readDeclarations( + directory: string, + fileName: string, +): Promise[]> { + const found: { directory: string; file: string; source: string }[] = []; + let items; + try { + items = await readdir(directory, { withFileTypes: true }); + } catch { + return found; + } + for (const item of items) { + if (!item.isDirectory()) continue; + const file = resolve(directory, item.name, fileName); + try { + found.push({ directory: item.name, file, source: await readFile(file, "utf8") }); + } catch { + continue; + } + } + return found; +} + +/** + * Filesystem declaration source. Declarations are small literal headers, so + * reading them is a metadata scan; only the selected app's features are ever + * imported by the generated output. + */ +export async function createFileSystemDeclarationSource( + root: string, +): Promise { + const apps = new Map(); + for (const declaration of await readDeclarations(resolve(root, "src/apps"), "app-module.ts")) { + const id = requiredLiteral(declaration.source, "APP_MODULE_ID", declaration.file); + if (apps.has(id)) throw new Error(`Duplicate app id: ${id}`); + apps.set(id, { + id, + maxContexts: requiredInteger(declaration.source, "APP_MAX_CONTEXTS", declaration.file), + }); + } + const contextsByApp = new Map(); + const contextIds = new Set(); + for (const declaration of await readDeclarations(resolve(root, "src/contexts"), "context-module.ts")) { + const context: ContextDeclaration = { + id: requiredLiteral(declaration.source, "CONTEXT_MODULE_ID", declaration.file), + appId: requiredLiteral(declaration.source, "CONTEXT_APP_ID", declaration.file), + routePath: requiredLiteral(declaration.source, "CONTEXT_ROUTE_PATH", declaration.file), + maxFeatures: requiredInteger(declaration.source, "CONTEXT_MAX_FEATURES", declaration.file), + }; + if (contextIds.has(context.id)) throw new Error(`Duplicate context id: ${context.id}`); + if (!apps.has(context.appId)) { + throw new Error(`Context ${context.id} belongs to undeclared app ${context.appId}`); + } + contextIds.add(context.id); + const owned = contextsByApp.get(context.appId) ?? []; + owned.push(context); + contextsByApp.set(context.appId, owned); + } + const featuresByContext = new Map(); + const featureIds = new Set(); + for (const declaration of await readDeclarations(resolve(root, "src/features"), "feature-module.ts")) { + const feature: FeatureDeclaration = { + id: requiredLiteral(declaration.source, "FEATURE_MODULE_ID", declaration.file), + contextId: requiredLiteral(declaration.source, "FEATURE_CONTEXT_ID", declaration.file), + directory: declaration.directory, + }; + if (featureIds.has(feature.id)) throw new Error(`Duplicate generated feature ids: ${feature.id}`); + if (!contextIds.has(feature.contextId)) { + throw new Error(`Feature ${feature.id} belongs to undeclared context ${feature.contextId}`); + } + featureIds.add(feature.id); + const owned = featuresByContext.get(feature.contextId) ?? []; + owned.push(feature); + featuresByContext.set(feature.contextId, owned); + } + return Object.freeze({ + appIds: () => [...apps.keys()].sort(), + app: (appId: string) => apps.get(appId), + contextsOf: (appId: string) => contextsByApp.get(appId) ?? [], + featuresOf: (contextId: string) => featuresByContext.get(contextId) ?? [], + }); +} + +export async function generateAppIndexes( + root: string, + requestedApp: string | undefined, +): Promise { + const source = await createFileSystemDeclarationSource(root); + return selectAppIndexes(source, resolveSelectedApp(source, requestedApp)); +} + +async function main(): Promise { + const scriptDir = dirname(fileURLToPath(import.meta.url)); + // `--root=` points the same production command at another checkout (used by + // the multi-app topology evidence); the default is this repository. + const rootArgument = process.argv + .find((argument) => argument.startsWith("--root=")) + ?.slice("--root=".length); + const root = rootArgument ? resolve(rootArgument) : resolve(scriptDir, ".."); + const outputRoot = resolve(root, "src/.generated"); + const outputs = { + feature: resolve(outputRoot, "product-feature-index.ts"), + context: resolve(outputRoot, "product-context-index.ts"), + app: resolve(outputRoot, "product-app.ts"), + }; + const requestedApp = + process.argv.find((argument) => argument.startsWith("--app="))?.slice("--app=".length) || + process.env["PRODUCT_APP_ID"] || + undefined; + const selected = await generateAppIndexes(root, requestedApp); + const rendered = { + feature: selected.featureIndex, + context: selected.contextIndex, + app: selected.appIndex, + }; + await mkdir(outputRoot, { recursive: true }); + + if (process.argv.includes("--check")) { + const stale: string[] = []; + for (const key of ["feature", "context", "app"] as const) { + const current = await readFile(outputs[key], "utf8").catch(() => ""); + if (current !== rendered[key]) stale.push(relative(root, outputs[key])); + } + if (stale.length > 0) { + throw new Error(`Generated topology index is stale: ${stale.join(", ")}`); + } + return; + } + + await Promise.all( + (["feature", "context", "app"] as const).map((key) => + writeFile(outputs[key], rendered[key], "utf8"), + ), + ); +} + +if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { + await main(); +} diff --git a/scripts/scale/benchmark-result.ts b/scripts/scale/benchmark-result.ts new file mode 100644 index 00000000..53c7f040 --- /dev/null +++ b/scripts/scale/benchmark-result.ts @@ -0,0 +1,69 @@ +import { mkdir, writeFile } from "node:fs/promises"; +import { dirname } from "node:path"; + +/** + * Spec ยง48. Machine-readable benchmark result. + */ +export type BenchmarkProfile = "S0" | "S1" | "S2" | "S3" | "S4"; + +export interface BenchmarkResult { + readonly name: string; + readonly profile: BenchmarkProfile; + readonly cardinality: number; + readonly samples: readonly number[]; + readonly medianMs: number; + readonly heapBytes?: number; + readonly metadata: Readonly>; +} + +export type BenchmarkArtifact = Readonly<{ + schemaVersion: 1; + suite: string; + generatedAt: string; + node: string; + passed: boolean; + results: readonly BenchmarkResult[]; + checks: readonly Readonly<{ name: string; passed: boolean; detail: string }>[]; +}>; + +const PROFILES: ReadonlySet = new Set(["S0", "S1", "S2", "S3", "S4"]); + +export function median(values: readonly number[]): number { + if (values.length === 0) throw new TypeError("median of an empty series"); + const sorted = [...values].sort((left, right) => left - right); + const middle = Math.floor(sorted.length / 2); + return sorted.length % 2 === 1 + ? (sorted[middle] as number) + : ((sorted[middle - 1] as number) + (sorted[middle] as number)) / 2; +} + +export function assertBenchmarkResult(value: BenchmarkResult): BenchmarkResult { + if (typeof value.name !== "string" || value.name.length === 0) { + throw new TypeError("benchmark name required"); + } + if (!PROFILES.has(value.profile)) { + throw new TypeError(`unknown benchmark profile ${String(value.profile)}`); + } + if (!Number.isSafeInteger(value.cardinality) || value.cardinality < 0) { + throw new TypeError("benchmark cardinality must be a non-negative integer"); + } + if ( + value.samples.length === 0 || + value.samples.some((sample) => !Number.isFinite(sample) || sample < 0) + ) { + throw new TypeError("benchmark samples must be finite non-negative numbers"); + } + if (value.medianMs !== median(value.samples)) { + throw new TypeError("benchmark medianMs must be the median of its samples"); + } + return value; +} + +export async function writeBenchmarkArtifact( + path: string, + artifact: BenchmarkArtifact, +): Promise { + for (const result of artifact.results) assertBenchmarkResult(result); + await mkdir(dirname(path), { recursive: true }); + await writeFile(path, `${JSON.stringify(artifact, null, 2)}\n`); +} diff --git a/scripts/scale/benchmark.ts b/scripts/scale/benchmark.ts new file mode 100644 index 00000000..cb5ba4a5 --- /dev/null +++ b/scripts/scale/benchmark.ts @@ -0,0 +1,64 @@ +import { performance } from "node:perf_hooks"; + +import { + assertBenchmarkResult, + median, + type BenchmarkProfile, + type BenchmarkResult, +} from "./benchmark-result.ts"; + +/** + * Spec ยง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 + * measured itself, which lets tests inject exact durations. + */ +export type BenchmarkOptions = Readonly<{ + samples: number; + warmup?: number; + profile?: BenchmarkProfile; + cardinality?: number; + metadata?: Readonly>; + measureHeap?: boolean; + run: () => unknown; +}>; + +function heapUsed(): number { + return process.memoryUsage().heapUsed; +} + +export async function benchmark( + name: string, + options: BenchmarkOptions, +): Promise { + if (!Number.isSafeInteger(options.samples) || options.samples < 1) { + throw new TypeError("benchmark samples must be a positive integer"); + } + for (let index = 0; index < (options.warmup ?? 0); index += 1) { + await options.run(); + } + const samples: number[] = []; + let peakHeapDelta = 0; + for (let index = 0; index < options.samples; index += 1) { + const heapBefore = options.measureHeap ? heapUsed() : 0; + const startedAt = performance.now(); + const reported = await options.run(); + const elapsed = performance.now() - startedAt; + if (options.measureHeap) { + peakHeapDelta = Math.max(peakHeapDelta, heapUsed() - heapBefore); + } + samples.push(typeof reported === "number" && Number.isFinite(reported) ? reported : elapsed); + } + return assertBenchmarkResult( + Object.freeze({ + name, + profile: options.profile ?? "S0", + cardinality: options.cardinality ?? 0, + samples: Object.freeze(samples), + medianMs: median(samples), + ...(options.measureHeap ? { heapBytes: Math.max(0, peakHeapDelta) } : {}), + metadata: Object.freeze({ ...(options.metadata ?? {}) }), + }), + ); +} diff --git a/scripts/scale/browser-soak.ts b/scripts/scale/browser-soak.ts new file mode 100644 index 00000000..4fe91514 --- /dev/null +++ b/scripts/scale/browser-soak.ts @@ -0,0 +1,554 @@ +import { createReadStream } from "node:fs"; +import { access, mkdir, readFile, stat, writeFile } from "node:fs/promises"; +import { createServer, type Server } from "node:http"; +import type { AddressInfo } from "node:net"; +import path from "node:path"; + +import { + classifyCounterSeries, + classifyMemorySlope, + type MemorySlopeClass, +} from "./memory-slope.ts"; + +/** + * Spec ยง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. + * The served runtime config turns telemetry on (pointed at a local collector) + * and points the API at a stub that always answers 503, so every cycle also + * exercises bounded retries and telemetry under a sustained backend failure. + * + * Collected per sample: JS heap, DOM nodes, event listeners, live timers, + * in-flight fetches, Web Storage size. Collected overall: cycles, navigation + * failures, API requests, telemetry POSTs/events. Without a build or browser + * the result is `skipped` (never a pass); too little evidence fails. + */ +export type SoakSample = Readonly<{ + elapsedMs: number; + cycles: number; + heapBytes: number; + domNodes: number; + listeners: number; + activeTimers: number; + inFlightRequests: number; + storageKeys: number; + storageBytes: number; +}>; + +export type SoakSummary = Readonly<{ + cycles: number; + navigationFailures: number; + maxHeapBytes: number; + heapClassification: MemorySlopeClass; + listenerDelta: number; + listenerClassification: MemorySlopeClass; + timerDelta: number; + maxActiveTimers: number; + domNodeDelta: number; + maxInFlightRequests: number; + finalInFlightRequests: number; + storageKeyDelta: number; + storageByteDelta: number; + apiRequests: number; + referenceVisits: number; + settledReferenceVisits: number; + apiRequestsPerReferenceVisit: number; + telemetryPosts: number; + telemetryEvents: number; + maxTelemetryPostsPerMinute: number; +}>; + +export type SoakCheck = Readonly<{ name: string; passed: boolean; detail: string }>; + +export type SoakArtifact = Readonly<{ + schemaVersion: 2; + status: "passed" | "failed" | "skipped"; + reason?: string; + durationMs: number; + classification?: MemorySlopeClass; + summary?: SoakSummary; + checks?: readonly SoakCheck[]; + /** Identity of the soaked build (from dist/release-manifest.json). */ + build?: Readonly<{ buildId?: string; releaseId?: string; builtAt?: string }>; + browser?: string; + samples: readonly SoakSample[]; +}>; + +/** Thresholds a soak must meet; each is checked and recorded by name. */ +export const SOAK_LIMITS = Object.freeze({ + minCycles: 200, + minPostWarmupSamples: 3, + maxListenerDelta: 50, + maxTimerDelta: 10, + maxStorageKeyDelta: 2, + /** One logical execution: 1 attempt + at most 2 retries. */ + maxApiRequestsPerReferenceVisit: 3, + /** Two bounded pipelines (platform events + feature events) x 20/min. */ + maxTelemetryPostsPerMinute: 40, +}); + +export function summarizeSoak( + samples: readonly Pick[], + warmupMs: number, +): MemorySlopeClass { + return classifyMemorySlope( + samples.map((sample) => ({ + minute: sample.elapsedMs / 60_000, + heapMb: sample.heapBytes / (1024 * 1024), + })), + { warmupMinutes: warmupMs / 60_000, maxSlopeMbPerMinute: 1, maxRelativeGrowth: 0.2 }, + ); +} + +export type SoakTotals = Readonly<{ + cycles: number; + navigationFailures: number; + referenceVisits: number; + settledReferenceVisits: number; + finalInFlightRequests: number; + apiRequests: number; + telemetryPosts: number; + telemetryEvents: number; + telemetryPostTimes: readonly number[]; +}>; + +export function evaluateSoak( + samples: readonly SoakSample[], + totals: SoakTotals, + warmupMs: number, +): Readonly<{ summary: SoakSummary; checks: readonly SoakCheck[] }> { + const measured = samples.filter((sample) => sample.elapsedMs >= warmupMs); + const first = measured[0]; + const last = measured[measured.length - 1]; + const delta = (pick: (sample: SoakSample) => number) => + first && last ? pick(last) - pick(first) : 0; + let maxTelemetryPostsPerMinute = 0; + for (const time of totals.telemetryPostTimes) { + const inWindow = totals.telemetryPostTimes.filter( + (other) => other >= time && other < time + 60_000, + ).length; + maxTelemetryPostsPerMinute = Math.max(maxTelemetryPostsPerMinute, inWindow); + } + const summary: SoakSummary = { + cycles: totals.cycles, + navigationFailures: totals.navigationFailures, + maxHeapBytes: Math.max(0, ...samples.map((sample) => sample.heapBytes)), + heapClassification: summarizeSoak(samples, warmupMs), + listenerDelta: delta((sample) => sample.listeners), + listenerClassification: classifyCounterSeries( + measured.map((sample) => sample.listeners), + { maxSlopePerSample: 1 }, + ), + timerDelta: delta((sample) => sample.activeTimers), + maxActiveTimers: Math.max(0, ...samples.map((sample) => sample.activeTimers)), + domNodeDelta: delta((sample) => sample.domNodes), + maxInFlightRequests: Math.max(0, ...samples.map((sample) => sample.inFlightRequests)), + finalInFlightRequests: totals.finalInFlightRequests, + storageKeyDelta: delta((sample) => sample.storageKeys), + storageByteDelta: delta((sample) => sample.storageBytes), + apiRequests: totals.apiRequests, + referenceVisits: totals.referenceVisits, + settledReferenceVisits: totals.settledReferenceVisits, + apiRequestsPerReferenceVisit: + totals.referenceVisits === 0 + ? 0 + : Math.round((totals.apiRequests / totals.referenceVisits) * 1_000) / 1_000, + telemetryPosts: totals.telemetryPosts, + telemetryEvents: totals.telemetryEvents, + maxTelemetryPostsPerMinute, + }; + const checks: SoakCheck[] = [ + { name: "cycles", passed: summary.cycles >= SOAK_LIMITS.minCycles, detail: `${summary.cycles} >= ${SOAK_LIMITS.minCycles}` }, + { + name: "post-warmup samples", + passed: measured.length >= SOAK_LIMITS.minPostWarmupSamples, + detail: `${measured.length} >= ${SOAK_LIMITS.minPostWarmupSamples}`, + }, + { name: "navigation", passed: summary.navigationFailures === 0, detail: `${summary.navigationFailures} failures` }, + { name: "heap slope", passed: summary.heapClassification === "stable", detail: summary.heapClassification }, + { + name: "listeners", + passed: + summary.listenerClassification === "stable" && + summary.listenerDelta <= SOAK_LIMITS.maxListenerDelta, + detail: `${summary.listenerClassification}, delta ${summary.listenerDelta}`, + }, + { + name: "timers", + passed: summary.timerDelta <= SOAK_LIMITS.maxTimerDelta, + detail: `delta ${summary.timerDelta}, max ${summary.maxActiveTimers}`, + }, + { + name: "in-flight settles", + passed: summary.finalInFlightRequests === 0, + detail: `final ${summary.finalInFlightRequests}, max ${summary.maxInFlightRequests}`, + }, + { + name: "storage growth", + passed: summary.storageKeyDelta <= SOAK_LIMITS.maxStorageKeyDelta, + detail: `keys ${summary.storageKeyDelta}, bytes ${summary.storageByteDelta}`, + }, + { + name: "backend failure exercised", + passed: + summary.settledReferenceVisits > 0 && summary.apiRequests > 0 && summary.telemetryEvents > 0, + detail: `${summary.settledReferenceVisits} settled visits, ${summary.apiRequests} API requests, ${summary.telemetryEvents} telemetry events`, + }, + { + name: "request amplification", + passed: + summary.referenceVisits > 0 && + summary.apiRequestsPerReferenceVisit <= SOAK_LIMITS.maxApiRequestsPerReferenceVisit, + detail: `${summary.apiRequests} requests / ${summary.referenceVisits} visits`, + }, + { + name: "telemetry rate", + passed: summary.maxTelemetryPostsPerMinute <= SOAK_LIMITS.maxTelemetryPostsPerMinute, + detail: `max ${summary.maxTelemetryPostsPerMinute}/min, ${summary.telemetryPosts} posts, ${summary.telemetryEvents} events`, + }, + ]; + return { summary, checks }; +} + +const CONTENT_TYPES: Readonly> = { + ".css": "text/css; charset=utf-8", + ".html": "text/html; charset=utf-8", + ".js": "text/javascript; charset=utf-8", + ".json": "application/json; charset=utf-8", + ".svg": "image/svg+xml", + ".png": "image/png", + ".webmanifest": "application/manifest+json", +}; + +type Counters = { + apiRequests: number; + telemetryPosts: number; + telemetryEvents: number; + telemetryPostTimes: number[]; +}; + +async function serveSoakTarget( + root: string, + counters: Counters, + startedAt: () => number, +): Promise> { + let baseUrl = ""; + const baseConfig = JSON.parse( + await readFile(path.join(root, "config.json"), "utf8"), + ) as Record; + const server = createServer(async (request, response) => { + try { + const url = new URL(request.url ?? "/", "http://127.0.0.1"); + if (url.pathname === "/__telemetry") { + let body = ""; + request.on("data", (chunk: Buffer) => { + body += chunk.toString("utf8"); + }); + request.on("end", () => { + counters.telemetryPosts += 1; + counters.telemetryPostTimes.push(Date.now() - startedAt()); + try { + const parsed = JSON.parse(body) as { events?: unknown[] }; + counters.telemetryEvents += Array.isArray(parsed.events) ? parsed.events.length : 0; + } catch { + // Counted as a post regardless of its body. + } + response.writeHead(204).end(); + }); + return; + } + if (url.pathname.startsWith("/api/")) { + counters.apiRequests += 1; + response.writeHead(503, { "Content-Type": "application/json" }).end("{}"); + return; + } + if (url.pathname === "/config.json") { + response + .writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" }) + .end( + JSON.stringify({ + ...baseConfig, + API_BASE_URL: `${baseUrl}/api/`, + TELEMETRY_ENABLED: true, + TELEMETRY_ENDPOINT: `${baseUrl}/__telemetry`, + }), + ); + return; + } + const requested = path.resolve(root, `.${decodeURIComponent(url.pathname)}`); + if (requested !== root && !requested.startsWith(`${root}${path.sep}`)) { + response.writeHead(403).end(); + return; + } + const details = await stat(requested).catch(() => null); + const file = details?.isFile() ? requested : path.join(root, "index.html"); + response.writeHead(200, { + "Content-Type": CONTENT_TYPES[path.extname(file)] ?? "application/octet-stream", + "Cache-Control": "no-store", + }); + createReadStream(file).pipe(response); + } catch { + response.writeHead(404).end(); + } + }); + await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve)); + const { port } = server.address() as AddressInfo; + baseUrl = `http://127.0.0.1:${port}`; + return { server, baseUrl }; +} + +const PAGE_PROBES = ` +(() => { + const live = new Set(); + const setT = window.setTimeout, clearT = window.clearTimeout; + const setI = window.setInterval, clearI = window.clearInterval; + window.setTimeout = (fn, ms, ...rest) => { + const id = setT(() => { live.delete(id); typeof fn === "function" && fn(...rest); }, ms); + live.add(id); return id; + }; + window.clearTimeout = (id) => { live.delete(id); clearT(id); }; + window.setInterval = (fn, ms, ...rest) => { const id = setI(fn, ms, ...rest); live.add(id); return id; }; + window.clearInterval = (id) => { live.delete(id); clearI(id); }; + let inFlight = 0; + const nativeFetch = window.fetch.bind(window); + window.fetch = (...args) => { + inFlight += 1; + return nativeFetch(...args).finally(() => { inFlight -= 1; }); + }; + const storageSize = (storage) => { + let bytes = 0; + for (let i = 0; i < storage.length; i += 1) { + const key = storage.key(i) ?? ""; + bytes += key.length + (storage.getItem(key) ?? "").length; + } + return { keys: storage.length, bytes }; + }; + Object.defineProperty(window, "__soakProbe", { + value: () => { + const local = storageSize(window.localStorage); + const session = storageSize(window.sessionStorage); + return { + activeTimers: live.size, + inFlight, + storageKeys: local.keys + session.keys, + storageBytes: local.bytes + session.bytes, + }; + }, + }); +})(); +`; + +type Probe = { activeTimers: number; inFlight: number; storageKeys: number; storageBytes: number }; + +export async function runBrowserSoak( + options: Readonly<{ + distRoot: string; + durationMs: number; + intervalMs: number; + warmupMs: number; + routes: readonly string[]; + }>, +): Promise { + try { + await access(path.join(options.distRoot, "index.html")); + await access(path.join(options.distRoot, "config.json")); + } catch { + return { + schemaVersion: 2, + status: "skipped", + reason: "no built dist/index.html + config.json", + durationMs: 0, + samples: [], + }; + } + let chromium: (typeof import("@playwright/test"))["chromium"]; + try { + ({ chromium } = await import("@playwright/test")); + } catch { + return { schemaVersion: 2, status: "skipped", reason: "playwright unavailable", durationMs: 0, samples: [] }; + } + const counters: Counters = { + apiRequests: 0, + telemetryPosts: 0, + telemetryEvents: 0, + telemetryPostTimes: [], + }; + let started = Date.now(); + const { server, baseUrl } = await serveSoakTarget( + path.resolve(options.distRoot), + counters, + () => started, + ); + let browser: Awaited> | undefined; + try { + try { + browser = await chromium.launch(); + } catch (error) { + return { + schemaVersion: 2, + status: "skipped", + reason: `browser unavailable: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`, + durationMs: 0, + samples: [], + }; + } + const page = await browser.newPage(); + await page.addInitScript(PAGE_PROBES); + const cdp = await page.context().newCDPSession(page); + await cdp.send("Performance.enable"); + await page.goto(`${baseUrl}/examples/reference-resources`, { waitUntil: "load" }); + await page.waitForSelector("#root > *", { timeout: 15_000 }); + // Protected routes need a session: start the local demo session once, so + // the reference feature really dispatches its (failing) API requests. + const login = page.getByRole("button", { name: /๋กœ๊ทธ์ธ ์‹œ์ž‘|Sign in|Start sign-in/u }); + if (await login.count()) { + await login.first().click(); + await page.waitForTimeout(500); + } + + const samples: SoakSample[] = []; + started = Date.now(); + let nextSample = 0; + let cycles = 0; + let navigationFailures = 0; + let referenceVisits = 0; + let settledReferenceVisits = 0; + const probe = async () => + (await page.evaluate(() => + (window as unknown as { __soakProbe: () => Probe }).__soakProbe(), + )) as Probe; + while (Date.now() - started < options.durationMs) { + const route = options.routes[cycles % options.routes.length] ?? "/"; + cycles += 1; + if (route === "/examples/reference-resources") referenceVisits += 1; + // Client-side navigation keeps one long-lived document, like a real session. + await page.evaluate((target) => { + window.history.pushState({}, "", target); + window.dispatchEvent(new PopStateEvent("popstate")); + }, route); + await page.waitForTimeout(50); + const rendered = await page.evaluate( + (target) => + window.location.pathname === target && + (document.getElementById("root")?.childElementCount ?? 0) > 0, + route, + ); + if (!rendered) navigationFailures += 1; + // Most visits leave after 50ms, which cancels the query (a cancelled + // request is intentionally not reported). Every 5th reference visit + // dwells until its interaction settles, so the failing backend is really + // observed end to end: bounded retries, then feature/platform telemetry. + if (route === "/examples/reference-resources" && referenceVisits % 5 === 1) { + await page.waitForTimeout(200); + await page + .waitForFunction( + () => (window as unknown as { __soakProbe: () => Probe }).__soakProbe().inFlight === 0, + undefined, + { timeout: 5_000 }, + ) + .catch(() => undefined); + settledReferenceVisits += 1; + } + const elapsedMs = Date.now() - started; + if (elapsedMs >= nextSample) { + nextSample = elapsedMs + options.intervalMs; + await cdp.send("HeapProfiler.collectGarbage").catch(() => undefined); + const { metrics } = (await cdp.send("Performance.getMetrics")) as { + metrics: { name: string; value: number }[]; + }; + const metric = (name: string) => metrics.find((entry) => entry.name === name)?.value ?? 0; + const probed = await probe(); + samples.push({ + elapsedMs, + cycles, + heapBytes: metric("JSHeapUsedSize"), + domNodes: metric("Nodes"), + listeners: metric("JSEventListeners"), + activeTimers: probed.activeTimers, + inFlightRequests: probed.inFlight, + storageKeys: probed.storageKeys, + storageBytes: probed.storageBytes, + }); + } + } + // Let the last interaction's bounded retries and deadlines settle. + let finalInFlightRequests = (await probe()).inFlight; + for (let wait = 0; wait < 30 && finalInFlightRequests > 0; wait += 1) { + await page.waitForTimeout(500); + finalInFlightRequests = (await probe()).inFlight; + } + const evaluation = evaluateSoak( + samples, + { + cycles, + navigationFailures, + referenceVisits, + settledReferenceVisits, + finalInFlightRequests, + apiRequests: counters.apiRequests, + telemetryPosts: counters.telemetryPosts, + telemetryEvents: counters.telemetryEvents, + telemetryPostTimes: counters.telemetryPostTimes, + }, + options.warmupMs, + ); + const build = await readFile(path.join(options.distRoot, "release-manifest.json"), "utf8") + .then((raw) => { + const manifest = JSON.parse(raw) as Record; + const pick = (key: string) => + typeof manifest[key] === "string" ? (manifest[key] as string) : undefined; + return { + ...(pick("buildId") ? { buildId: pick("buildId") } : {}), + ...(pick("releaseId") ? { releaseId: pick("releaseId") } : {}), + ...(pick("builtAt") ? { builtAt: pick("builtAt") } : {}), + }; + }) + .catch(() => ({})); + return { + schemaVersion: 2, + status: evaluation.checks.every((check) => check.passed) ? "passed" : "failed", + durationMs: options.durationMs, + classification: evaluation.summary.heapClassification, + summary: evaluation.summary, + checks: evaluation.checks, + build, + browser: `chromium ${browser.version()}`, + samples, + }; + } finally { + await browser?.close().catch(() => undefined); + await new Promise((resolve) => server.close(() => resolve())); + } +} + +async function main(): Promise { + const argument = (name: string, fallback: string) => + process.argv.find((entry) => entry.startsWith(`--${name}=`))?.slice(name.length + 3) ?? fallback; + const artifact = path.resolve(argument("artifact", "artifacts/scale/browser-soak.json")); + const result = await runBrowserSoak({ + distRoot: argument("dist", "dist"), + durationMs: Number(argument("duration-ms", "60000")), + intervalMs: Number(argument("interval-ms", "5000")), + warmupMs: Number(argument("warmup-ms", "15000")), + routes: argument( + "routes", + "/,/examples/reference-resources,/examples/platform,/examples/ui,/examples/states,/examples/reference-resources/status", + ).split(","), + }); + await mkdir(path.dirname(artifact), { recursive: true }); + await writeFile(artifact, `${JSON.stringify(result, null, 2)}\n`); + process.stdout.write( + `browser soak: ${result.status}${result.reason ? ` (${result.reason})` : ""}` + + `${result.classification ? ` classification=${result.classification}` : ""} samples=${result.samples.length}` + + `${result.summary ? ` cycles=${result.summary.cycles}` : ""}\n`, + ); + for (const check of result.checks ?? []) { + process.stdout.write(`${check.passed ? "PASS" : "FAIL"} ${check.name} (${check.detail})\n`); + } + if (result.status === "failed") process.exitCode = 1; +} + +if (import.meta.url === `file://${process.argv[1]}`) { + await main(); +} diff --git a/scripts/scale/check-scale-baseline.ts b/scripts/scale/check-scale-baseline.ts new file mode 100644 index 00000000..62e07af0 --- /dev/null +++ b/scripts/scale/check-scale-baseline.ts @@ -0,0 +1,113 @@ +import { spawnSync } from "node:child_process"; +import { mkdir, readFile, writeFile } from "node:fs/promises"; +import path from "node:path"; + +import { collectTscScale } from "./collect-tsc-diagnostics.ts"; +import { runCompositionScale } from "./run-composition-scale.ts"; +import { + approveBaseline, + compareToBaseline, + currentEnvironment, + snapshotMetrics, + type ScaleBaseline, +} from "./scale-baseline.ts"; + +/** + * Spec ยง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 + * SCALE_BASELINE_OWNER=... SCALE_BASELINE_REASON=... \ + * node scripts/scale/check-scale-baseline.ts --update re-measure and re-approve + * + * The comparison is written to artifacts/scale/baseline-comparison.json (or + * `--artifact=`). Updating is an explicit, attributed act; the check never + * rewrites the baseline. + */ +export const BASELINE_PATH = "config/scale/benchmark-baseline.json"; +export const LOCAL_TSC_SIZES = Object.freeze([25, 100, 400]); + +function typescriptVersion(): string { + const result = spawnSync(path.resolve("node_modules/.bin/tsc"), ["-v"], { encoding: "utf8" }); + const match = /Version\s+(\S+)/u.exec(result.stdout ?? ""); + if (!match?.[1]) throw new Error("cannot determine TypeScript version"); + return match[1]; +} + +async function measure() { + const composition = await runCompositionScale(["S0", "S1", "S2"], { samples: 9, warmup: 2 }); + const compiler = await collectTscScale(LOCAL_TSC_SIZES); + return snapshotMetrics(composition.results, compiler); +} + +async function main(): Promise { + const update = process.argv.includes("--update"); + const artifact = path.resolve( + process.argv.find((entry) => entry.startsWith("--artifact="))?.slice("--artifact=".length) ?? + "artifacts/scale/baseline-comparison.json", + ); + const environment = currentEnvironment(typescriptVersion()); + const metrics = await measure(); + + if (update) { + const owner = process.env["SCALE_BASELINE_OWNER"]; + const reason = process.env["SCALE_BASELINE_REASON"]; + if (!owner || !reason) { + process.stderr.write("SCALE_BASELINE_OWNER and SCALE_BASELINE_REASON are required.\n"); + process.exit(1); + } + const baseline = approveBaseline(environment, metrics, { + owner, + reason, + approvedAt: new Date().toISOString(), + }); + await mkdir(path.dirname(BASELINE_PATH), { recursive: true }); + await writeFile(BASELINE_PATH, `${JSON.stringify(baseline, null, 2)}\n`); + process.stdout.write(`scale baseline approved: ${baseline.approval.metricsDigest}\n`); + return; + } + + let baseline: ScaleBaseline; + try { + baseline = JSON.parse(await readFile(BASELINE_PATH, "utf8")) as ScaleBaseline; + } catch { + process.stderr.write(`missing or unreadable ${BASELINE_PATH}; run update:scale-baseline\n`); + process.exit(1); + } + const comparison = compareToBaseline(baseline, environment, metrics); + await mkdir(path.dirname(artifact), { recursive: true }); + await writeFile( + artifact, + `${JSON.stringify( + { schemaVersion: 1, generatedAt: new Date().toISOString(), environment, baselineApproval: baseline.approval, ...comparison }, + null, + 2, + )}\n`, + ); + const { compatibility } = comparison; + process.stdout.write( + `compatibility: structural=${compatibility.structural.ok} compiler=${compatibility.compiler.ok} timing=${compatibility.timing.ok}\n`, + ); + if (!compatibility.timing.ok) { + process.stdout.write( + `timing regression NOT compared (incomplete): ${compatibility.timing.reasons.join("; ")}\n`, + ); + } + process.stdout.write( + `axes: absolute ${comparison.absolute.findings.length} (${comparison.absolute.passed ? "ok" : "FAIL"}), ` + + `growth ${comparison.growth.findings.length} (${comparison.growth.passed ? "ok" : "FAIL"}), ` + + `relative ${comparison.compiler.length} compiler + ${comparison.timing.length} timing\n`, + ); + for (const failure of comparison.failures) process.stdout.write(`FAIL ${failure}\n`); + process.stdout.write( + `scale baseline gate: ${comparison.status.toUpperCase()} (${path.relative(process.cwd(), artifact)})\n`, + ); + if (comparison.status === "failed") process.exitCode = 1; + else if (comparison.status === "incomplete" && process.env["SCALE_ALLOW_INCOMPLETE"] !== "1") { + process.exitCode = 1; + } +} + +if (import.meta.url === `file://${process.argv[1]}`) { + await main(); +} diff --git a/scripts/scale/collect-tsc-diagnostics.ts b/scripts/scale/collect-tsc-diagnostics.ts new file mode 100644 index 00000000..d5827091 --- /dev/null +++ b/scripts/scale/collect-tsc-diagnostics.ts @@ -0,0 +1,208 @@ +import { spawnSync } from "node:child_process"; +import { mkdir, rm, writeFile } from "node:fs/promises"; +import { join, resolve } from "node:path"; + +import { + assertLinearOrBetter, + growthExponents, +} from "../../src/platform/cardinality/growth-regression.ts"; + +/** + * Spec ยง38. TypeScript scale gate. + * + * Parses `tsc --extendedDiagnostics` and measures bounded local fixtures: + * generated feature modules composed by one context, at increasing local + * cardinality. S3/S4 are never compiled; they are verified as topology. + */ +export type TscDiagnostics = Readonly<{ + files: number; + lines?: number; + types: number; + symbols: number; + instantiations: number; + memoryKb?: number; + totalTimeSeconds?: number; +}>; + +const FIELD_NAMES: Readonly> = Object.freeze({ + Files: "files", + Lines: "lines", + Types: "types", + Symbols: "symbols", + Instantiations: "instantiations", + "Memory used": "memoryKb", + "Total time": "totalTimeSeconds", +}); + +export function parseTscExtendedDiagnostics(text: string): TscDiagnostics { + const parsed: Partial> = {}; + for (const line of text.split(/\r?\n/u)) { + const match = /^\s*([A-Za-z][A-Za-z ]*?):\s+([\d.]+)\s*([KMs]?)\s*$/u.exec(line); + if (!match) continue; + const field = FIELD_NAMES[match[1] as string]; + if (!field) continue; + const value = Number(match[2]); + if (!Number.isFinite(value)) continue; + parsed[field] = match[3] === "M" ? value * 1024 : value; + } + for (const required of ["files", "types", "symbols", "instantiations"] as const) { + if (parsed[required] === undefined) { + throw new TypeError(`tsc diagnostics missing ${required}`); + } + } + return Object.freeze(parsed) as TscDiagnostics; +} + +export function runTscDiagnostics(project: string, cwd = process.cwd()): TscDiagnostics { + const tsc = resolve(cwd, "node_modules/.bin/tsc"); + const result = spawnSync(tsc, ["--project", project, "--noEmit", "--extendedDiagnostics"], { + cwd, + encoding: "utf8", + maxBuffer: 16 * 1024 * 1024, + }); + if (result.status !== 0) { + throw new Error(`tsc failed for ${project}: ${(result.stdout + result.stderr).slice(-2_000)}`); + } + return parseTscExtendedDiagnostics(result.stdout); +} + +/** + * Generates one bounded local app: `features` feature modules, each with its + * own typed contract, composed by one generated index. The shape mirrors the + * repository's feature-module/generated-index pattern. + */ +export async function writeLocalTscFixture( + root: string, + features: number, +): Promise { + await rm(root, { recursive: true, force: true }); + await mkdir(join(root, "features"), { recursive: true }); + const imports: string[] = []; + const members: string[] = []; + for (let index = 0; index < features; index += 1) { + const id = `feature${index}`; + await writeFile( + join(root, "features", `${id}.ts`), + `export type ${id}Input = Readonly<{ id: string; limit: number; tags?: readonly string[] }>;\n` + + `export type ${id}Output = Readonly<{ items: readonly Readonly<{ id: string; name: string }>[] }>;\n` + + `export const ${id} = Object.freeze({\n` + + ` id: "${id}" as const,\n` + + ` routes: Object.freeze({ ${id.toUpperCase()}_LIST: "/${id}" }),\n` + + ` execute(input: ${id}Input): ${id}Output {\n` + + ` return { items: [{ id: input.id, name: String(input.limit) }] };\n` + + ` },\n` + + `});\n`, + ); + imports.push(`import { ${id} } from "./features/${id}.ts";`); + members.push(` ${id},`); + } + await writeFile( + join(root, "index.ts"), + `${imports.join("\n")}\nexport const LOCAL_FEATURES = Object.freeze([\n${members.join("\n")}\n] as const);\n` + + `export type LocalFeatureId = (typeof LOCAL_FEATURES)[number]["id"];\n`, + ); + const tsconfig = join(root, "tsconfig.json"); + await writeFile( + tsconfig, + JSON.stringify( + { + compilerOptions: { + target: "ES2022", + module: "ESNext", + moduleResolution: "Bundler", + allowImportingTsExtensions: true, + strict: true, + noEmit: true, + skipLibCheck: true, + types: [], + lib: ["ES2022"], + }, + include: ["index.ts", "features/*.ts"], + }, + null, + 2, + ), + ); + return tsconfig; +} + +export type TscScaleReport = Readonly<{ + passed: boolean; + app: TscDiagnostics; + local: readonly Readonly<{ features: number; diagnostics: TscDiagnostics }>[]; + checks: readonly Readonly<{ name: string; passed: boolean; detail: string }>[]; +}>; + +export async function collectTscScale( + localSizes: readonly number[], + cwd = process.cwd(), +): Promise { + const app = runTscDiagnostics("tsconfig.app.json", cwd); + const local: { features: number; diagnostics: TscDiagnostics }[] = []; + for (const features of localSizes) { + const tsconfig = await writeLocalTscFixture( + resolve(cwd, ".tmp/scale-tsc", `local-${features}`), + features, + ); + local.push({ features, diagnostics: runTscDiagnostics(tsconfig, cwd) }); + } + const checks: { name: string; passed: boolean; detail: string }[] = []; + for (const metric of ["types", "symbols", "instantiations"] as const) { + const series = local.map(({ features, diagnostics }) => ({ + n: features, + // Library/baseline cost is constant; growth is judged on what the local + // features add on top of the smallest fixture. + cost: Math.max(1, diagnostics[metric]), + })); + try { + assertLinearOrBetter(series, { maxExponent: 1.3 }); + checks.push({ + name: `tsc:${metric}`, + passed: true, + detail: `exponents ${growthExponents(series).map((value) => value.toFixed(2)).join(", ")}`, + }); + } catch (error) { + checks.push({ + name: `tsc:${metric}`, + passed: false, + detail: error instanceof Error ? error.message : String(error), + }); + } + } + return Object.freeze({ + passed: checks.every((check) => check.passed), + app, + local: Object.freeze(local), + checks: Object.freeze(checks), + }); +} + +async function main(): Promise { + const artifactArg = process.argv.find((argument) => argument.startsWith("--artifact=")); + const sizesArg = process.argv.find((argument) => argument.startsWith("--local-sizes=")); + const sizes = (sizesArg?.slice("--local-sizes=".length) ?? "25,100,400") + .split(",") + .map(Number) + .filter((value) => Number.isSafeInteger(value) && value > 0); + const artifact = resolve( + artifactArg?.slice("--artifact=".length) ?? "artifacts/scale/tsc-diagnostics.json", + ); + const report = await collectTscScale(sizes); + await mkdir(resolve(artifact, ".."), { recursive: true }); + await writeFile( + artifact, + `${JSON.stringify({ schemaVersion: 1, generatedAt: new Date().toISOString(), ...report }, null, 2)}\n`, + ); + process.stdout.write( + `tsc app: files=${report.app.files} types=${report.app.types} instantiations=${report.app.instantiations}\n`, + ); + for (const check of report.checks) { + process.stdout.write(`${check.passed ? "PASS" : "FAIL"} ${check.name} (${check.detail})\n`); + } + process.stdout.write(`tsc diagnostics artifact: ${artifact}\n`); + if (!report.passed) process.exitCode = 1; +} + +if (import.meta.url === `file://${process.argv[1]}`) { + await main(); +} diff --git a/scripts/scale/composition-workloads.ts b/scripts/scale/composition-workloads.ts new file mode 100644 index 00000000..5193205d --- /dev/null +++ b/scripts/scale/composition-workloads.ts @@ -0,0 +1,108 @@ +import { composeUniqueRecord } from "../../src/platform/cardinality/compose-unique-record.ts"; +import { + resolveProductFeatures, + selectCompiledProductFeatures, +} from "../../src/contracts/product-features.ts"; +import { defineBoundedContextModule } from "../../src/contexts/bounded-context-module.ts"; +import { defineDeployableAppModule } from "../../src/apps/deployable-app-module.ts"; + +/** + * Spec ยง39. Scale-sensitive production composition paths, each parameterized + * by one cardinality `n`. Inputs are built outside the timed region. + */ +export type CompositionWorkload = Readonly<{ + name: string; + implementation: string; + prepare(n: number): () => unknown; +}>; + +export function createUniqueRegistryParts( + count: number, +): readonly Readonly>[] { + return Array.from({ length: count }, (_, index) => + Object.freeze({ [`route-${index}`]: index }), + ); +} + +function featureIds(count: number): string[] { + return Array.from( + { length: count }, + (_, index) => `feature-${index.toString().padStart(7, "0")}`, + ); +} + +const CONTEXT_FEATURES = 200; + +export const COMPOSITION_WORKLOADS: readonly CompositionWorkload[] = Object.freeze([ + { + name: "registry-composition", + implementation: "composeUniqueRecord", + prepare(n: number) { + const parts = createUniqueRegistryParts(n); + return () => composeUniqueRecord(parts, () => "route"); + }, + }, + { + name: "product-feature-selection", + implementation: "selectCompiledProductFeatures", + prepare(n: number) { + const compiled = featureIds(n).map((featureId) => Object.freeze({ featureId })); + const declared = compiled + .filter((_, index) => index % 2 === 0) + .map((feature) => feature.featureId) + .join(","); + return () => selectCompiledProductFeatures(compiled, declared); + }, + }, + { + name: "product-feature-resolution", + implementation: "resolveProductFeatures", + prepare(n: number) { + const compiled = featureIds(n); + const installed = compiled.filter((_, index) => index % 3 !== 0); + return () => resolveProductFeatures(compiled, installed); + }, + }, + { + name: "context-hierarchy-composition", + implementation: "defineBoundedContextModule+defineDeployableAppModule", + prepare(n: number) { + const features = featureIds(n).map((id) => + Object.freeze({ + id, + contracts: Object.freeze({ featureId: id }), + routes: Object.freeze({}), + adapters: Object.freeze([]), + runtimes: Object.freeze([]), + messages: Object.freeze({}), + contractContributions: Object.freeze([]), + }), + ); + const contextCount = Math.ceil(n / CONTEXT_FEATURES); + return () => { + const contexts = Array.from({ length: contextCount }, (_, contextIndex) => + defineBoundedContextModule({ + id: `context-${contextIndex}`, + features: features.slice( + contextIndex * CONTEXT_FEATURES, + (contextIndex + 1) * CONTEXT_FEATURES, + ), + budget: Object.freeze({ maxFeatures: CONTEXT_FEATURES }), + }), + ); + // Apps are sharded by the same direct-child budget. + const apps: unknown[] = []; + for (let index = 0; index < contexts.length; index += 20) { + apps.push( + defineDeployableAppModule({ + id: `app-${index / 20}`, + contexts: contexts.slice(index, index + 20), + budget: Object.freeze({ maxContexts: 20 }), + }), + ); + } + return apps; + }; + }, + }, +]); diff --git a/scripts/scale/memory-slope.ts b/scripts/scale/memory-slope.ts new file mode 100644 index 00000000..71230b67 --- /dev/null +++ b/scripts/scale/memory-slope.ts @@ -0,0 +1,66 @@ +/** + * Spec ยง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 + * the post-warm-up samples and reports `unbounded-growth` only when both the + * slope and the total relative growth are material. + */ +export type SlopeSample = Readonly<{ minute: number; heapMb: number }>; + +export type MemorySlopeClass = "stable" | "unbounded-growth" | "insufficient-data"; + +export type MemorySlopeOptions = Readonly<{ + /** Samples before this minute are warm-up. Default 0. */ + warmupMinutes?: number; + /** Largest tolerated post-warm-up slope in MB per minute. Default 0.5. */ + maxSlopeMbPerMinute?: number; + /** Largest tolerated relative growth first->last fitted value. Default 0.1. */ + maxRelativeGrowth?: number; +}>; + +export function linearSlope(points: readonly Readonly<{ x: number; y: number }>[]): number { + const count = points.length; + if (count < 2) return 0; + const meanX = points.reduce((sum, point) => sum + point.x, 0) / count; + const meanY = points.reduce((sum, point) => sum + point.y, 0) / count; + let numerator = 0; + let denominator = 0; + for (const point of points) { + numerator += (point.x - meanX) * (point.y - meanY); + denominator += (point.x - meanX) ** 2; + } + return denominator === 0 ? 0 : numerator / denominator; +} + +export function classifyMemorySlope( + samples: readonly SlopeSample[], + options: MemorySlopeOptions = {}, +): MemorySlopeClass { + const warmup = options.warmupMinutes ?? 0; + const maxSlope = options.maxSlopeMbPerMinute ?? 0.5; + const maxGrowth = options.maxRelativeGrowth ?? 0.1; + const measured = samples + .filter((sample) => sample.minute >= warmup) + .filter((sample) => Number.isFinite(sample.minute) && Number.isFinite(sample.heapMb)) + .sort((left, right) => left.minute - right.minute); + if (measured.length < 3) return "insufficient-data"; + const slope = linearSlope(measured.map((sample) => ({ x: sample.minute, y: sample.heapMb }))); + const first = measured[0] as SlopeSample; + const last = measured[measured.length - 1] as SlopeSample; + const fittedStart = Math.max(first.heapMb, Number.MIN_VALUE); + const growth = (slope * (last.minute - first.minute)) / fittedStart; + return slope > maxSlope && growth > maxGrowth ? "unbounded-growth" : "stable"; +} + +/** Generic variant for logical counters (timers, listeners, buffered events). */ +export function classifyCounterSeries( + values: readonly number[], + options: Readonly<{ warmupSamples?: number; maxSlopePerSample?: number }> = {}, +): MemorySlopeClass { + const warmup = options.warmupSamples ?? 0; + const measured = values.slice(warmup); + if (measured.length < 3) return "insufficient-data"; + const slope = linearSlope(measured.map((y, x) => ({ x, y }))); + return slope > (options.maxSlopePerSample ?? 0.01) ? "unbounded-growth" : "stable"; +} diff --git a/scripts/scale/run-composition-scale.ts b/scripts/scale/run-composition-scale.ts new file mode 100644 index 00000000..2ce5028b --- /dev/null +++ b/scripts/scale/run-composition-scale.ts @@ -0,0 +1,136 @@ +import { resolve } from "node:path"; + +import { + assertLinearOrBetter, + growthExponents, +} from "../../src/platform/cardinality/growth-regression.ts"; +import { benchmark } from "./benchmark.ts"; +import { + writeBenchmarkArtifact, + type BenchmarkProfile, + type BenchmarkResult, +} from "./benchmark-result.ts"; +import { COMPOSITION_WORKLOADS } from "./composition-workloads.ts"; + +/** + * Spec ยง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. + * Results are written as a machine-readable artifact under artifacts/scale/. + */ +export const COMPOSITION_PROFILES: Readonly> = Object.freeze({ + S0: 100, + S1: 1_000, + S2: 10_000, +}); + +/** Scheduler noise below this median is not evidence of growth. */ +export const COMPOSITION_NOISE_FLOOR_MS = 0.5; +/** + * n log n paths (sorting, allocation-heavy string work) measure ~1.1-1.4 + * between S1 and S2; a quadratic path measures ~2. 1.6 separates the two. + */ +export const COMPOSITION_MAX_EXPONENT = 1.6; + +export type CompositionScaleReport = Readonly<{ + passed: boolean; + results: readonly BenchmarkResult[]; + checks: readonly Readonly<{ name: string; passed: boolean; detail: string }>[]; +}>; + +export async function runCompositionScale( + profiles: readonly string[], + options: Readonly<{ + samples?: number; + warmup?: number; + /** + * `median` (default) for standalone gate runs. `min` (best observed) when + * the gate shares the machine with other suites: stolen CPU and foreign + * GC only ever add time, so the minimum keeps the algorithmic shape. + */ + statistic?: "median" | "min"; + }> = {}, +): Promise { + const results: BenchmarkResult[] = []; + const checks: { name: string; passed: boolean; detail: string }[] = []; + for (const workload of COMPOSITION_WORKLOADS) { + const series: { n: number; cost: number }[] = []; + for (const profile of profiles) { + const cardinality = COMPOSITION_PROFILES[profile]; + if (cardinality === undefined) throw new TypeError(`unknown profile ${profile}`); + const run = workload.prepare(cardinality); + const result = await benchmark(workload.name, { + samples: options.samples ?? 7, + warmup: options.warmup ?? 2, + profile: profile as BenchmarkProfile, + cardinality, + measureHeap: true, + metadata: { implementation: workload.implementation }, + run, + }); + results.push(result); + series.push({ + n: cardinality, + cost: + options.statistic === "min" ? Math.min(...result.samples) : result.medianMs, + }); + } + if (series.length < 2) continue; + try { + assertLinearOrBetter(series, { + maxExponent: COMPOSITION_MAX_EXPONENT, + noiseFloor: COMPOSITION_NOISE_FLOOR_MS, + }); + checks.push({ + name: `${workload.name}:growth`, + passed: true, + detail: `exponents ${growthExponents(series, COMPOSITION_NOISE_FLOOR_MS) + .map((exponent) => exponent.toFixed(2)) + .join(", ")}`, + }); + } catch (error) { + checks.push({ + name: `${workload.name}:growth`, + passed: false, + detail: error instanceof Error ? error.message : String(error), + }); + } + } + return Object.freeze({ + passed: checks.every((check) => check.passed), + results: Object.freeze(results), + checks: Object.freeze(checks), + }); +} + +async function main(): Promise { + const profileArg = process.argv.find((argument) => argument.startsWith("--profiles=")); + const artifactArg = process.argv.find((argument) => argument.startsWith("--artifact=")); + const profiles = (profileArg?.slice("--profiles=".length) ?? "S0,S1,S2") + .split(",") + .map((entry) => entry.trim()) + .filter(Boolean); + const artifact = resolve( + artifactArg?.slice("--artifact=".length) ?? "artifacts/scale/composition-scale.json", + ); + const report = await runCompositionScale(profiles); + await writeBenchmarkArtifact(artifact, { + schemaVersion: 1, + suite: "composition-scale", + generatedAt: new Date().toISOString(), + node: process.version, + passed: report.passed, + results: report.results, + checks: report.checks, + }); + for (const check of report.checks) { + process.stdout.write(`${check.passed ? "PASS" : "FAIL"} ${check.name} (${check.detail})\n`); + } + process.stdout.write(`composition scale artifact: ${artifact}\n`); + if (!report.passed) process.exitCode = 1; +} + +if (import.meta.url === `file://${process.argv[1]}`) { + await main(); +} diff --git a/scripts/scale/run-scale-profile.ts b/scripts/scale/run-scale-profile.ts new file mode 100644 index 00000000..c22b6919 --- /dev/null +++ b/scripts/scale/run-scale-profile.ts @@ -0,0 +1,190 @@ +import { spawnSync } from "node:child_process"; +import { mkdir, writeFile } from "node:fs/promises"; +import path from "node:path"; + +/** + * Spec ยง47. CI execution tiers for the scale/chaos/soak program. + * + * pr S0/S1 architecture, composition and traffic invariants + * main pr + S2 composition, TypeScript diagnostics and the stored + * baseline regression gate (config/scale/benchmark-baseline.json) + * nightly main + S3/S4 topology, telemetry storm, session cycles, browser soak + * release release-coherence matrix + the stable main/nightly subset + * + * Every step's output goes to artifacts/scale//.log and the tier + * writes one machine-readable summary.json. A step that could not run (e.g. a + * browser soak without a build or browser) is `skipped`, and a tier with any + * skipped step is `incomplete`: it is never reported as passed and exits + * non-zero. `SCALE_ALLOW_INCOMPLETE=1` keeps the exit code zero for local runs, + * but the summary still says `incomplete`. + */ +export type ScaleTier = "pr" | "main" | "nightly" | "release"; + +type Step = Readonly<{ + id: string; + command: readonly string[]; + /** A step that may legitimately report `skipped` in its own artifact. */ + optional?: boolean; +}>; + +const VITEST = ["scripts/run-vitest.ts", "run", "--reporter=default"]; + +const PR_STEPS: readonly Step[] = [ + { + id: "architecture-topology", + command: [...VITEST, "tests/architecture", "tests/platform/cardinality", "tests/platform/routing"], + }, + { + id: "traffic-budgets", + command: [...VITEST, "tests/platform/execution", "tests/platform/traffic", "tests/platform/resilience"], + }, + { + id: "scale-units", + command: [ + ...VITEST, + "tests/scale/growth-regression.test.ts", + "tests/scale/benchmark.test.ts", + "tests/scale/synthetic-topology.test.ts", + "tests/scale/scale-baseline.test.ts", + "tests/scale/traffic", + ], + }, + { + id: "composition-s0-s1", + command: ["scripts/scale/run-composition-scale.ts", "--profiles=S0,S1"], + }, +]; + +const MAIN_STEPS: readonly Step[] = [ + ...PR_STEPS, + { + id: "composition-s0-s2", + command: ["scripts/scale/run-composition-scale.ts", "--profiles=S0,S1,S2"], + }, + { + id: "composition-scale-suite", + command: [...VITEST, "tests/scale/composition-scale.test.ts", "tests/scale/tsc-diagnostics-parser.test.ts"], + }, + { + id: "typescript-diagnostics", + command: ["scripts/scale/collect-tsc-diagnostics.ts", "--local-sizes=25,100,400"], + }, + { + id: "baseline-regression", + command: ["scripts/scale/check-scale-baseline.ts"], + }, +]; + +const NIGHTLY_STEPS: readonly Step[] = [ + ...MAIN_STEPS, + { + id: "topology-s3-s4", + command: [...VITEST, "tests/scale/global-local-independence.test.ts", "tests/platform/cardinality/extreme-scale-registry.test.ts"], + }, + { + id: "telemetry-storm", + command: [...VITEST, "tests/scale/telemetry", "tests/platform/telemetry"], + }, + { id: "session-cycles", command: [...VITEST, "tests/scale/session"] }, + { + id: "browser-soak", + command: ["scripts/scale/browser-soak.ts", "--duration-ms=120000", "--interval-ms=5000", "--warmup-ms=30000"], + optional: true, + }, +]; + +const RELEASE_STEPS: readonly Step[] = [ + { + id: "release-coherence", + command: [...VITEST, "tests/platform/release", "tests/release"], + }, + ...MAIN_STEPS, + { + id: "topology-s3-s4", + command: [...VITEST, "tests/scale/global-local-independence.test.ts"], + }, + { + id: "telemetry-storm", + command: [...VITEST, "tests/scale/telemetry"], + }, +]; + +export const SCALE_TIERS: Readonly> = Object.freeze({ + pr: PR_STEPS, + main: MAIN_STEPS, + nightly: NIGHTLY_STEPS, + release: RELEASE_STEPS, +}); + +function withArtifact(step: Step, directory: string): readonly string[] { + const script = step.command[0] ?? ""; + if ( + script.endsWith("run-composition-scale.ts") || + script.endsWith("collect-tsc-diagnostics.ts") || + script.endsWith("browser-soak.ts") || + script.endsWith("check-scale-baseline.ts") + ) { + return [...step.command, `--artifact=${path.join(directory, `${step.id}.json`)}`]; + } + return step.command; +} + +async function main(): Promise { + const tier = process.argv[2] as ScaleTier | undefined; + if (!tier || !(tier in SCALE_TIERS)) { + process.stderr.write(`usage: run-scale-profile.ts <${Object.keys(SCALE_TIERS).join("|")}>\n`); + process.exit(2); + } + const directory = path.resolve("artifacts/scale", tier); + await mkdir(directory, { recursive: true }); + const results: { id: string; status: "passed" | "failed" | "skipped"; durationMs: number; log: string }[] = []; + for (const step of SCALE_TIERS[tier]) { + const startedAt = Date.now(); + const run = spawnSync(process.execPath, [...withArtifact(step, directory)], { + encoding: "utf8", + maxBuffer: 64 * 1024 * 1024, + env: { ...process.env, SCALE_ARTIFACT_DIR: path.join(directory, "metrics") }, + }); + const log = path.join(directory, `${step.id}.log`); + await writeFile(log, `${run.stdout ?? ""}${run.stderr ?? ""}`); + const skipped = step.optional === true && /: skipped/u.test(run.stdout ?? ""); + const status = run.status === 0 ? (skipped ? "skipped" : "passed") : "failed"; + results.push({ id: step.id, status, durationMs: Date.now() - startedAt, log: path.relative(process.cwd(), log) }); + process.stdout.write(`${status.toUpperCase()} ${tier}:${step.id} (${Date.now() - startedAt}ms)\n`); + } + const failed = results.some((result) => result.status === "failed"); + const skipped = results.filter((result) => result.status === "skipped").map((result) => result.id); + const status = failed ? "failed" : skipped.length > 0 ? "incomplete" : "passed"; + await writeFile( + path.join(directory, "summary.json"), + `${JSON.stringify( + { + schemaVersion: 1, + tier, + generatedAt: new Date().toISOString(), + node: process.version, + environment: { + node: process.version, + nodeMajor: Number(process.versions.node.split(".")[0]), + platform: process.platform, + arch: process.arch, + }, + status, + passed: status === "passed", + skipped, + steps: results, + }, + null, + 2, + )}\n`, + ); + process.stdout.write( + `scale tier ${tier}: ${status.toUpperCase()}${skipped.length > 0 ? ` (skipped: ${skipped.join(", ")})` : ""} (artifacts/scale/${tier}/summary.json)\n`, + ); + if (status === "failed") process.exitCode = 1; + else if (status === "incomplete" && process.env["SCALE_ALLOW_INCOMPLETE"] !== "1") process.exitCode = 1; +} + +if (import.meta.url === `file://${process.argv[1]}`) { + await main(); +} diff --git a/scripts/scale/scale-baseline.ts b/scripts/scale/scale-baseline.ts new file mode 100644 index 00000000..39115cef --- /dev/null +++ b/scripts/scale/scale-baseline.ts @@ -0,0 +1,381 @@ +import { createHash } from "node:crypto"; +import { cpus } from "node:os"; + +import { growthExponents } from "../../src/platform/cardinality/growth-regression.ts"; +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 + * regression gate. + * + * The growth gates judge the *shape* of one run. This module compares a run + * against an approved stored baseline so a change that keeps the shape but + * multiplies the cost (or silently adds compiler work) is still caught. + * + * Two kinds of metric are compared differently: + * - deterministic metrics (TypeScript types/symbols/instantiations/files) are + * exact for a given compiler, so they use a tight relative tolerance and + * require a compatible toolchain; + * - timing metrics depend on the machine, so they use a loose tolerance plus an + * absolute noise floor, and are only enforced on a compatible environment. + */ +export const SCALE_BASELINE_SCHEMA_VERSION = 1; + +export type ScaleEnvironment = Readonly<{ + nodeMajor: number; + platform: string; + arch: string; + cpuModel: string; + cpuCount: number; + typescript: string; +}>; + +export type TimingEntry = Readonly<{ + workload: string; + profile: string; + cardinality: number; + medianMs: number; + minMs: number; +}>; + +export type CompilerEntry = Readonly<{ + fixture: string; + files: number; + types: number; + symbols: number; + instantiations: number; +}>; + +export type ScaleMetrics = Readonly<{ + timing: readonly TimingEntry[]; + compiler: readonly CompilerEntry[]; +}>; + +export type ScaleBaseline = Readonly<{ + schemaVersion: typeof SCALE_BASELINE_SCHEMA_VERSION; + environment: ScaleEnvironment; + metrics: ScaleMetrics; + approval: Readonly<{ + owner: string; + reason: string; + approvedAt: string; + metricsDigest: string; + }>; +}>; + +export const REGRESSION_TOLERANCE = Object.freeze({ + /** Deterministic compiler counts may grow at most 10% without re-approval. */ + compilerRelative: 0.1, + /** Timings may grow at most 2.5x (scheduler/GC noise lives below that)... */ + timingRelative: 1.5, + /** ...and never fail on differences below this absolute noise floor. */ + timingNoiseFloorMs: 1, +}); + +/** + * Axis 1 โ€” absolute ceilings. Machine-agnostic hard limits (roughly 50x the + * approved baseline for timings, ~2x for compiler work) that hold even with + * no comparable baseline. + */ +export const ABSOLUTE_CEILINGS = Object.freeze({ + timingMinMsByProfile: Object.freeze({ S0: 5, S1: 25, S2: 150 } as Record), + app: Object.freeze({ files: 1_500, types: 600_000, symbols: 1_600_000, instantiations: 1_500_000 }), + /** + * Generated `local-` compiler fixtures: a fixed base (lib/runtime + * overhead present at any N) plus a per-local-feature allowance. + */ + localBase: Object.freeze({ files: 100, types: 5_000, symbols: 15_000, instantiations: 5_000 }), + localPerFeature: Object.freeze({ files: 2, types: 100, symbols: 250, instantiations: 150 }), +}); + +/** Axis 3 โ€” growth shape (see src/platform/cardinality/growth-regression.ts). */ +export const GROWTH_LIMITS = Object.freeze({ + timingMaxExponent: 1.6, + timingNoiseFloorMs: 0.5, + compilerMaxExponent: 1.3, +}); + +export function currentEnvironment(typescript: string): ScaleEnvironment { + const cpu = cpus(); + return Object.freeze({ + nodeMajor: Number(process.versions.node.split(".")[0]), + platform: process.platform, + arch: process.arch, + cpuModel: cpu[0]?.model.trim() ?? "unknown", + cpuCount: cpu.length, + typescript, + }); +} + +function canonical(value: unknown): string { + if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`; + if (value && typeof value === "object") { + return `{${Object.keys(value) + .sort() + .map((key) => `${JSON.stringify(key)}:${canonical((value as Record)[key])}`) + .join(",")}}`; + } + return JSON.stringify(value); +} + +export function metricsDigest(metrics: ScaleMetrics): string { + return createHash("sha256").update(canonical(metrics)).digest("hex"); +} + +export function snapshotMetrics( + composition: readonly BenchmarkResult[], + compiler: Readonly<{ + app: TscDiagnostics; + local: readonly Readonly<{ features: number; diagnostics: TscDiagnostics }>[]; + }>, +): ScaleMetrics { + const round = (value: number) => Math.round(value * 1_000) / 1_000; + const toCompiler = (fixture: string, diagnostics: TscDiagnostics): CompilerEntry => ({ + fixture, + files: diagnostics.files, + types: diagnostics.types, + symbols: diagnostics.symbols, + instantiations: diagnostics.instantiations, + }); + return Object.freeze({ + timing: composition + .map((result) => ({ + workload: result.name, + profile: result.profile, + cardinality: result.cardinality, + medianMs: round(result.medianMs), + minMs: round(Math.min(...result.samples)), + })) + .sort((left, right) => + `${left.workload}/${left.profile}`.localeCompare(`${right.workload}/${right.profile}`), + ), + compiler: [ + toCompiler("app", compiler.app), + ...compiler.local.map((entry) => toCompiler(`local-${entry.features}`, entry.diagnostics)), + ].sort((left, right) => left.fixture.localeCompare(right.fixture)), + }); +} + +export type Compatibility = Readonly<{ + /** Baseline format, digest and metric coverage are usable at all. */ + structural: Readonly<{ ok: boolean; reasons: readonly string[] }>; + /** Same compiler: deterministic compiler counts are comparable. */ + compiler: Readonly<{ ok: boolean; reasons: readonly string[] }>; + /** Same machine class and runtime: timings are comparable. */ + timing: Readonly<{ ok: boolean; reasons: readonly string[] }>; +}>; + +export function checkCompatibility( + baseline: ScaleBaseline, + environment: ScaleEnvironment, + current: ScaleMetrics, +): Compatibility { + const structural: string[] = []; + if (baseline.schemaVersion !== SCALE_BASELINE_SCHEMA_VERSION) { + structural.push(`baseline schemaVersion ${String(baseline.schemaVersion)} is not ${SCALE_BASELINE_SCHEMA_VERSION}`); + } + if (metricsDigest(baseline.metrics) !== baseline.approval?.metricsDigest) { + structural.push("baseline metrics do not match their approved digest (hand-edited?)"); + } + const timingKey = (entry: TimingEntry) => `${entry.workload}/${entry.profile}/${entry.cardinality}`; + const baselineTiming = new Set(baseline.metrics.timing.map(timingKey)); + const baselineCompiler = new Set(baseline.metrics.compiler.map((entry) => entry.fixture)); + for (const entry of current.timing) { + if (!baselineTiming.has(timingKey(entry))) structural.push(`no baseline for timing ${timingKey(entry)}`); + } + for (const entry of current.compiler) { + if (!baselineCompiler.has(entry.fixture)) structural.push(`no baseline for compiler fixture ${entry.fixture}`); + } + + const compiler: string[] = []; + if (baseline.environment.typescript !== environment.typescript) { + compiler.push(`TypeScript ${environment.typescript} differs from baseline ${baseline.environment.typescript}`); + } + + const timing: string[] = []; + const base = baseline.environment; + if (base.nodeMajor !== environment.nodeMajor) timing.push(`Node ${environment.nodeMajor} vs baseline ${base.nodeMajor}`); + if (base.platform !== environment.platform || base.arch !== environment.arch) { + timing.push(`${environment.platform}/${environment.arch} vs baseline ${base.platform}/${base.arch}`); + } + if (base.cpuModel !== environment.cpuModel) timing.push(`CPU "${environment.cpuModel}" vs baseline "${base.cpuModel}"`); + return Object.freeze({ + structural: { ok: structural.length === 0, reasons: structural }, + compiler: { ok: compiler.length === 0, reasons: compiler }, + timing: { ok: timing.length === 0, reasons: timing }, + }); +} + +export type RegressionFinding = Readonly<{ + metric: string; + baseline: number; + current: number; + limit: number; + passed: boolean; +}>; + +export type AxisResult = Readonly<{ + passed: boolean; + findings: readonly RegressionFinding[]; +}>; + +export type BaselineComparison = Readonly<{ + /** + * `passed` only when every axis was evaluated and held. `incomplete` when the + * environment is not timing-compatible: timing regression was not compared, + * so it is not evidence of a pass. + */ + status: "passed" | "failed" | "incomplete"; + passed: boolean; + compatibility: Compatibility; + absolute: AxisResult; + growth: AxisResult; + compiler: readonly RegressionFinding[]; + /** Empty when the environment is not timing-compatible. */ + timing: readonly RegressionFinding[]; + failures: readonly string[]; +}>; + +function finding(metric: string, baseline: number, current: number, limit: number): RegressionFinding { + return { metric, baseline, current, limit: Math.round(limit * 1_000) / 1_000, passed: current <= limit }; +} + +export function checkAbsoluteCeilings(current: ScaleMetrics): AxisResult { + const findings: RegressionFinding[] = []; + for (const entry of current.timing) { + const limit = ABSOLUTE_CEILINGS.timingMinMsByProfile[entry.profile]; + if (limit !== undefined) { + findings.push(finding(`ceiling:time:${entry.workload}/${entry.profile}`, 0, entry.minMs, limit)); + } + } + for (const entry of current.compiler) { + const local = /^local-(\d+)$/u.exec(entry.fixture); + for (const metric of ["files", "types", "symbols", "instantiations"] as const) { + const limit = local + ? ABSOLUTE_CEILINGS.localBase[metric] + + ABSOLUTE_CEILINGS.localPerFeature[metric] * Number(local[1]) + : entry.fixture === "app" + ? ABSOLUTE_CEILINGS.app[metric] + : Number.POSITIVE_INFINITY; + findings.push(finding(`ceiling:tsc:${entry.fixture}:${metric}`, 0, entry[metric], limit)); + } + } + return { passed: findings.every((item) => item.passed), findings }; +} + +export function checkGrowthShape(current: ScaleMetrics): AxisResult { + const findings: RegressionFinding[] = []; + const byWorkload = new Map(); + for (const entry of current.timing) { + const series = byWorkload.get(entry.workload) ?? []; + series.push({ n: entry.cardinality, cost: entry.minMs }); + byWorkload.set(entry.workload, series); + } + for (const [workload, series] of byWorkload) { + if (series.length < 2) continue; + const worst = Math.max(...growthExponents(series, GROWTH_LIMITS.timingNoiseFloorMs)); + findings.push(finding(`growth:time:${workload}`, 1, Math.round(worst * 1_000) / 1_000, GROWTH_LIMITS.timingMaxExponent)); + } + const local = current.compiler + .map((entry) => ({ entry, n: Number(/^local-(\d+)$/u.exec(entry.fixture)?.[1]) })) + .filter(({ n }) => Number.isFinite(n)); + if (local.length >= 2) { + for (const metric of ["files", "types", "symbols", "instantiations"] as const) { + const worst = Math.max(...growthExponents(local.map(({ entry, n }) => ({ n, cost: entry[metric] })))); + findings.push(finding(`growth:tsc:local:${metric}`, 1, Math.round(worst * 1_000) / 1_000, GROWTH_LIMITS.compilerMaxExponent)); + } + } + return { passed: findings.every((item) => item.passed), findings }; +} + +export function compareToBaseline( + baseline: ScaleBaseline, + environment: ScaleEnvironment, + current: ScaleMetrics, + tolerance = REGRESSION_TOLERANCE, +): BaselineComparison { + const compatibility = checkCompatibility(baseline, environment, current); + const failures: string[] = [...compatibility.structural.reasons]; + // A different compiler changes every deterministic count: the baseline must + // be re-approved, it is never silently compared or silently skipped. + if (!compatibility.compiler.ok) { + failures.push( + ...compatibility.compiler.reasons.map((reason) => `${reason}; re-approve with update:scale-baseline`), + ); + } + + const absolute = checkAbsoluteCeilings(current); + const growth = checkGrowthShape(current); + for (const item of [...absolute.findings, ...growth.findings]) { + if (!item.passed) failures.push(`${item.metric} ${item.current} exceeds ${item.limit}`); + } + + const compiler: RegressionFinding[] = []; + if (compatibility.structural.ok && compatibility.compiler.ok) { + const byFixture = new Map(baseline.metrics.compiler.map((entry) => [entry.fixture, entry])); + for (const entry of current.compiler) { + const reference = byFixture.get(entry.fixture); + if (!reference) continue; + for (const metric of ["files", "types", "symbols", "instantiations"] as const) { + const item = finding( + `tsc:${entry.fixture}:${metric}`, + reference[metric], + entry[metric], + Math.floor(reference[metric] * (1 + tolerance.compilerRelative)), + ); + compiler.push(item); + if (!item.passed) { + failures.push(`${item.metric} ${item.current} exceeds ${item.limit} (baseline ${item.baseline})`); + } + } + } + } + + const timing: RegressionFinding[] = []; + if (compatibility.structural.ok && compatibility.timing.ok) { + const key = (entry: TimingEntry) => `${entry.workload}/${entry.profile}`; + const byKey = new Map(baseline.metrics.timing.map((entry) => [key(entry), entry])); + for (const entry of current.timing) { + const reference = byKey.get(key(entry)); + if (!reference) continue; + // Best-observed samples: contention only ever adds time. + const item = finding( + `time:${key(entry)}`, + reference.minMs, + entry.minMs, + Math.max(reference.minMs * (1 + tolerance.timingRelative), reference.minMs + tolerance.timingNoiseFloorMs), + ); + timing.push(item); + if (!item.passed) { + failures.push(`${item.metric} ${item.current}ms exceeds ${item.limit}ms (baseline ${item.baseline}ms)`); + } + } + } + + const status = + failures.length > 0 ? "failed" : compatibility.timing.ok ? "passed" : "incomplete"; + return Object.freeze({ + status, + passed: status === "passed", + compatibility, + absolute, + growth, + compiler, + timing, + failures, + }); +} + +export function approveBaseline( + environment: ScaleEnvironment, + metrics: ScaleMetrics, + approval: Readonly<{ owner: string; reason: string; approvedAt: string }>, +): ScaleBaseline { + return Object.freeze({ + schemaVersion: SCALE_BASELINE_SCHEMA_VERSION, + environment, + metrics, + approval: { ...approval, metricsDigest: metricsDigest(metrics) }, + }); +} diff --git a/scripts/test-sample-removal.ts b/scripts/test-sample-removal.ts index 0c480b8c..f6db20c8 100644 --- a/scripts/test-sample-removal.ts +++ b/scripts/test-sample-removal.ts @@ -41,6 +41,8 @@ const commonTestPaths = [ const featureOwnedPaths = [ featureSource, featureTests, + // The sample's bounded-context declaration; the template app stays. + "src/contexts/reference-context", "tests/integration/http-scenario-catalog.test.ts", "tests/component/product-feature-switch.test.tsx", "tests/e2e/reference-form.spec.ts", @@ -64,116 +66,6 @@ const featureOwnedPaths = [ "tests/fixtures/typecheck/tsconfig.feature-capability-selection.json", ]; -const emptyProductManifest = `export const COMPILED_PRODUCT_FEATURE_IDS: readonly string[] = Object.freeze([]); -export const INSTALLED_PRODUCT_FEATURES: readonly never[] = Object.freeze([]); -export const INSTALLED_PRODUCT_FEATURE_IDS: readonly string[] = Object.freeze([]); -`; - -const emptyContracts = `import { PLATFORM_ROUTE_RUNTIME_CONTRACT } from "../contracts/route-runtime-contract.ts"; -import { PLATFORM_ROUTE_REGISTRY, type RouteDefinition } from "../contracts/routes.ts"; -import { PLATFORM_SCHEMA_REGISTRY } from "../contracts/schema-registry.ts"; -import { INSTALLED_PRODUCT_FEATURES } from "./installed-product-manifest.ts"; - -export const INSTALLED_FEATURE_CONTRACTS = INSTALLED_PRODUCT_FEATURES; -export const ROUTE_REGISTRY = PLATFORM_ROUTE_REGISTRY; -export const ROUTE_RUNTIME_CONTRACT = PLATFORM_ROUTE_RUNTIME_CONTRACT; -export const API_OPERATIONS = Object.freeze({}); -export const INVALIDATION_REGISTRY = Object.freeze({ - topics: Object.freeze([]), - namespaces: Object.freeze([]), - edges: Object.freeze([]), -}); -export const INVALIDATION_TOPIC_VERSIONS = Object.freeze([]); -export const SCHEMA_REGISTRY = PLATFORM_SCHEMA_REGISTRY; -export const ROUTE_FEATURE_OWNER: Readonly> = Object.freeze({}); -export const NAVIGATION_ROUTES = Object.freeze( - Object.values(ROUTE_REGISTRY) - .filter((definition) => definition.navigationOrder !== null) - .sort( - (left, right) => - left.navigationOrder! - right.navigationOrder!, - ), -); -export function getRoute(routeId: string): RouteDefinition { - const registry = ROUTE_REGISTRY as Readonly>; - const selected = registry[routeId]; - if (!selected) throw new Error(\`Unregistered route: \${routeId}\`); - return selected; -} -export function routePath(routeId: string): string { - return getRoute(routeId).path; -} -`; - -const emptyRuntimes = `import { PLATFORM_ROUTE_CODECS } from "../presentation/routes/platform-route-codecs.ts"; -import { PLATFORM_ROUTE_RUNTIME } from "../presentation/routes/route-runtime.tsx"; -import { INSTALLED_PRODUCT_FEATURE_IDS } from "./installed-product-manifest.ts"; - -const COMPILED_FEATURE_RUNTIME_CONTRIBUTIONS: readonly Readonly<{ - featureId: string; -}>[] = Object.freeze([]); - -const INSTALLED_FEATURE_RUNTIME_CONTRIBUTIONS = - COMPILED_FEATURE_RUNTIME_CONTRIBUTIONS.filter((contribution) => - INSTALLED_PRODUCT_FEATURE_IDS.includes(contribution.featureId), - ); - -void INSTALLED_FEATURE_RUNTIME_CONTRIBUTIONS; - -export const ROUTE_CODECS = PLATFORM_ROUTE_CODECS; -export const ROUTE_RUNTIME = PLATFORM_ROUTE_RUNTIME; -`; - -const emptyAdapters = `import { - composeFeatureAdapterInputs, - type InstalledFeatureInputs, -} from "./feature-adapter-contribution.ts"; -import { INSTALLED_PRODUCT_FEATURE_IDS } from "./installed-product-manifest.ts"; - -const COMPILED_FEATURE_ADAPTER_CONTRIBUTIONS = Object.freeze([] as const); - -export function createInstalledFeatureInputs( - context: Readonly>, -): InstalledFeatureInputs { - return composeFeatureAdapterInputs( - COMPILED_FEATURE_ADAPTER_CONTRIBUTIONS, - INSTALLED_PRODUCT_FEATURE_IDS, - context, - ); -} -`; - -const emptyContractContributions = `import { - composeContractContributions, - type InstalledContractContribution, - type InstalledContractPackageIdentity, -} from "../contracts/external-contract-runtime.ts"; -import { INSTALLED_PRODUCT_FEATURE_IDS } from "./installed-product-manifest.ts"; - -const COMPILED_CONTRACT_CONTRIBUTIONS: readonly InstalledContractContribution[] = - Object.freeze([]); - -export const INSTALLED_CONTRACT_CONTRIBUTIONS: readonly InstalledContractContribution[] = - Object.freeze( - COMPILED_CONTRACT_CONTRIBUTIONS.filter((contribution) => - INSTALLED_PRODUCT_FEATURE_IDS.includes(contribution.featureId), - ), - ); - -export const COMPOSED_CONTRACT_CONTRIBUTIONS = composeContractContributions( - INSTALLED_CONTRACT_CONTRIBUTIONS, -); - -export const EXPECTED_CONTRACT_SET_PACKAGES: readonly InstalledContractPackageIdentity[] = - COMPOSED_CONTRACT_CONTRIBUTIONS.externalPackages; -`; - -const emptyMessages = `export const INSTALLED_MESSAGE_CATALOGS = Object.freeze({ - "ko-KR": Object.freeze({}), - "en-US": Object.freeze({}), -}); -`; - type CoveragePolicy = { repositoryBaseline: number; generatedPaths: string[]; @@ -236,30 +128,9 @@ try { force: true, }); } - await writeFile( - path.join(fixtureRoot, "src/features/installed-product-manifest.ts"), - emptyProductManifest, - ); - await writeFile( - path.join(fixtureRoot, "src/features/installed-feature-contracts.ts"), - emptyContracts, - ); - await writeFile( - path.join(fixtureRoot, "src/features/installed-feature-runtimes.tsx"), - emptyRuntimes, - ); - await writeFile( - path.join(fixtureRoot, "src/features/installed-feature-adapters.ts"), - emptyAdapters, - ); - await writeFile( - path.join(fixtureRoot, "src/features/installed-feature-messages.ts"), - emptyMessages, - ); - await writeFile( - path.join(fixtureRoot, "src/features/installed-contract-contributions.ts"), - emptyContractContributions, - ); + if (!runPnpm("generate:feature-index")) { + throw new Error("Feature topology indexes failed to regenerate after sample removal"); + } // Runtime profiles are product configuration. Once the feature is physically // removed, its override key must disappear too or the built config still diff --git a/scripts/verify-extreme-scale.ts b/scripts/verify-extreme-scale.ts new file mode 100644 index 00000000..2fc9c913 --- /dev/null +++ b/scripts/verify-extreme-scale.ts @@ -0,0 +1,332 @@ +import { spawnSync } from "node:child_process"; +import { createHash } from "node:crypto"; +import { existsSync } from "node:fs"; +import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises"; +import { arch, platform, userInfo } from "node:os"; +import path from "node:path"; + +/** + * Executable evidence for the extreme-scale acceptance matrix. + * + * Runs every gate the acceptance rows cite, in order, under the *current* + * Node, and writes one machine-readable record: + * artifacts/quality/extreme-scale-gates.json + * artifacts/quality/extreme-scale-gates/.log + * + * On an unsupported Node the gates are not run at all and the record says + * `not-executed`; it is never reported as a failure of the code or as a pass. + * In an environment whose default Node is too old, put a supported binary + * first on PATH (for example a repository-local `.tmp/node24/bin`). + */ +export const EXTREME_SCALE_GATES = Object.freeze([ + "check:feature-index", + "check:types:app", + "check:types:test", + "check:types", + "lint", + "check:architecture", + "check:app-build-input", + "check:request-fanout", + "check:registries", + "check:diagnostics", + "test:extreme-scale:focused", + "check:topology", + "check:traffic", + "check:observability", + "check:release-coherence", + "test:platform", + "test:reference-feature", + "check:scale:pr", + "check:scale:main", + "check:scale:baseline", + // The soak needs a build of the current source, never a stale dist/. + "build", + // The production bundle closure of the built app contains only its features. + "check:app-build-input:bundle", + "check:scale:nightly", + "check:scale:release", +] as const); + +/** Inputs whose content defines "the current code" for this evidence. */ +const SOURCE_ROOTS = Object.freeze(["src", "scripts", "tests", "config", ".storybook", "recipes"]); +const SOURCE_FILES = Object.freeze([ + "package.json", + "pnpm-lock.yaml", + ".dependency-cruiser.json", + "eslint.config.ts", + "vite.config.ts", + "vitest.config.ts", + "tsconfig.json", + "tsconfig.app.json", + "tsconfig.test.json", + "tsconfig.node.json", +]); + +async function listFiles(directory: string): Promise { + const found: string[] = []; + let entries; + try { + entries = await readdir(directory, { withFileTypes: true }); + } catch { + return found; + } + for (const entry of entries) { + const target = path.join(directory, entry.name); + if (entry.isDirectory()) found.push(...(await listFiles(target))); + else if (entry.isFile()) found.push(target); + } + return found; +} + +/** sha256 over every source input (path + content), in a stable order. */ +export async function sourceDigest(root: string): Promise> { + const files = [ + ...(await Promise.all(SOURCE_ROOTS.map((entry) => listFiles(path.join(root, entry))))).flat(), + ...SOURCE_FILES.map((file) => path.join(root, file)).filter((file) => existsSync(file)), + ] + .map((file) => path.relative(root, file)) + .sort(); + const hash = createHash("sha256"); + for (const file of files) { + hash.update(file).update("\0").update(await readFile(path.join(root, file))).update("\0"); + } + return { digest: hash.digest("hex"), files: files.length }; +} + +/** Sums vitest `Tests N passed` / `N failed` lines from a gate log. */ +export function vitestCounts(log: string): Readonly<{ passed: number; failed: number; skipped: number; files: number }> { + const escape = String.fromCharCode(27); + const plain = log.split(escape).map((part, index) => (index === 0 ? part : part.replace(/^\[[0-9;]*m/u, ""))).join(""); + let passed = 0; + let failed = 0; + let skipped = 0; + let files = 0; + for (const line of plain.split("\n")) { + const tests = /^\s*Tests\s+(.*)$/u.exec(line); + if (tests) { + passed += Number(/(\d+) passed/u.exec(tests[1] as string)?.[1] ?? 0); + failed += Number(/(\d+) failed/u.exec(tests[1] as string)?.[1] ?? 0); + skipped += Number(/(\d+) skipped/u.exec(tests[1] as string)?.[1] ?? 0); + } + const fileLine = /^\s*Test Files\s+.*?(\d+) passed/u.exec(line); + if (fileLine) files += Number(fileLine[1]); + } + return { passed, failed, skipped, files }; +} + +type Version = readonly [number, number, number]; + +function parseVersion(value: string): Version { + const [major = 0, minor = 0, patch = 0] = value.replace(/^v/u, "").split(".").map(Number); + return [major, minor, patch]; +} + +function compare(left: Version, right: Version): number { + for (let index = 0; index < 3; index += 1) { + const difference = (left[index] ?? 0) - (right[index] ?? 0); + if (difference !== 0) return difference; + } + return 0; +} + +/** Supports the `>=a.b.c =|<=|>|<|=)?(\d+(?:\.\d+){0,2})$/u.exec(clause); + if (!match) return false; + const order = compare(current, parseVersion(match[2] as string)); + const operator = match[1] ?? "="; + const ok = + operator === ">=" ? order >= 0 + : operator === "<=" ? order <= 0 + : operator === ">" ? order > 0 + : operator === "<" ? order < 0 + : order === 0; + if (!ok) return false; + } + return true; +} + +async function main(): Promise { + const root = process.cwd(); + const pkg = JSON.parse(await readFile(path.join(root, "package.json"), "utf8")) as { + engines?: { node?: string }; + }; + const engine = pkg.engines?.node ?? ""; + const directory = path.join(root, "artifacts/quality/extreme-scale-gates"); + const artifact = path.join(root, "artifacts/quality/extreme-scale-gates.json"); + await mkdir(directory, { recursive: true }); + const startedAt = new Date(); + const pnpmVersion = + spawnSync("corepack", ["pnpm", "--version"], { cwd: root, encoding: "utf8" }).stdout?.trim() ?? ""; + const identity = { + node: process.version, + nodeMajor: Number(process.versions.node.split(".")[0]), + pnpm: pnpmVersion, + engine, + platform: platform(), + arch: arch(), + user: (() => { + try { + return userInfo().username; + } catch { + return "unknown"; + } + })(), + }; + + if (!satisfiesEngine(process.version, engine)) { + await writeFile( + artifact, + `${JSON.stringify( + { + schemaVersion: 1, + generatedAt: new Date().toISOString(), + ...identity, + status: "not-executed", + reason: `Node ${process.version} does not satisfy engines.node "${engine}"`, + gates: [], + }, + null, + 2, + )}\n`, + ); + process.stderr.write( + `not executed: Node ${process.version} does not satisfy "${engine}". Put a supported node first on PATH.\n`, + ); + process.exit(2); + } + + const browsers = path.join(root, ".tmp/ms-playwright"); + const env = { + ...process.env, + pnpm_config_verify_deps_before_run: "false", + ...(process.env["PLAYWRIGHT_BROWSERS_PATH"] === undefined && existsSync(browsers) + ? { PLAYWRIGHT_BROWSERS_PATH: browsers } + : {}), + }; + const only = process.argv.find((argument) => argument.startsWith("--only="))?.slice(7).split(","); + const gates = only ? EXTREME_SCALE_GATES.filter((gate) => only.includes(gate)) : EXTREME_SCALE_GATES; + const sourceBefore = await sourceDigest(root); + const results: { + gate: string; + status: "passed" | "failed"; + exitCode: number | null; + durationMs: number; + tests: ReturnType; + log: string; + }[] = []; + for (const gate of gates) { + const gateStartedAt = Date.now(); + const run = spawnSync("corepack", ["pnpm", "run", gate], { + cwd: root, + env, + encoding: "utf8", + maxBuffer: 256 * 1024 * 1024, + }); + const log = path.join(directory, `${gate.replaceAll(":", "-")}.log`); + await writeFile(log, `${run.stdout ?? ""}${run.stderr ?? ""}`); + const status = run.status === 0 ? "passed" : "failed"; + const tests = vitestCounts(`${run.stdout ?? ""}${run.stderr ?? ""}`); + results.push({ + gate, + status, + exitCode: run.status, + durationMs: Date.now() - gateStartedAt, + tests, + log: path.relative(root, log), + }); + process.stdout.write( + `${status.toUpperCase()} ${gate} (${Date.now() - gateStartedAt}ms${tests.passed + tests.failed > 0 ? `, ${tests.passed} tests passed, ${tests.failed} failed` : ""})\n`, + ); + } + const sourceAfter = await sourceDigest(root); + + const readJson = async (relative: string) => { + const file = path.join(root, relative); + if (!existsSync(file)) return null; + const fresh = (await stat(file)).mtimeMs >= startedAt.getTime(); + return { fresh, value: JSON.parse(await readFile(file, "utf8")) as Record }; + }; + // Machine-readable artifacts the acceptance depends on must be produced by + // this run, on this Node, and say passed. An old PASS is not evidence. + const evidenceChecks: { artifact: string; check: string; passed: boolean }[] = []; + const expect = (artifact: string, check: string, passed: boolean) => + evidenceChecks.push({ artifact, check, passed }); + const ran = new Set(gates); + for (const tier of ["nightly", "release"] as const) { + if (!ran.has(`check:scale:${tier}`)) continue; + const relative = `artifacts/scale/${tier}/summary.json`; + const summary = await readJson(relative); + expect(relative, "regenerated during this run", summary?.fresh === true); + expect(relative, "status passed with no skipped step", summary?.value["status"] === "passed" && Array.isArray(summary.value["skipped"]) && summary.value["skipped"].length === 0); + const environment = summary?.value["environment"] as { nodeMajor?: number } | undefined; + expect(relative, `environment.nodeMajor == ${identity.nodeMajor}`, environment?.nodeMajor === identity.nodeMajor); + } + const soakRecord = ran.has("check:scale:nightly") + ? await readJson("artifacts/scale/nightly/browser-soak.json") + : null; + if (ran.has("check:scale:nightly")) { + expect("artifacts/scale/nightly/browser-soak.json", "regenerated during this run", soakRecord?.fresh === true); + expect("artifacts/scale/nightly/browser-soak.json", "status passed (not skipped)", soakRecord?.value["status"] === "passed"); + } + if (ran.has("check:scale:baseline")) { + const comparison = await readJson("artifacts/scale/baseline-comparison.json"); + expect("artifacts/scale/baseline-comparison.json", "regenerated during this run", comparison?.fresh === true); + expect("artifacts/scale/baseline-comparison.json", "status passed on all axes (timing compatible)", comparison?.value["status"] === "passed"); + } + if (ran.has("check:app-build-input:bundle")) { + const inventory = await readJson("artifacts/quality/vite-module-inventory.json"); + expect( + "artifacts/quality/vite-module-inventory.json", + "produced by this run's build (bundle isolation checked on current code)", + inventory?.fresh === true, + ); + } + expect("source tree", "unchanged while the gates ran", sourceBefore.digest === sourceAfter.digest); + const soak = soakRecord?.value ?? null; + const status = + results.every((result) => result.status === "passed") && evidenceChecks.every((check) => check.passed) + ? "passed" + : "failed"; + await writeFile( + artifact, + `${JSON.stringify( + { + schemaVersion: 1, + generatedAt: new Date().toISOString(), + startedAt: startedAt.toISOString(), + ...identity, + source: { digest: sourceAfter.digest, files: sourceAfter.files }, + status, + gates: results, + totals: { + gates: results.length, + passedGates: results.filter((result) => result.status === "passed").length, + testsPassed: results.reduce((sum, result) => sum + result.tests.passed, 0), + testsFailed: results.reduce((sum, result) => sum + result.tests.failed, 0), + }, + evidenceChecks, + browserSoak: soak + ? { + status: soak["status"], + classification: soak["classification"], + samples: Array.isArray(soak["samples"]) ? soak["samples"].length : 0, + summary: soak["summary"], + browser: soak["browser"], + build: soak["build"], + } + : null, + }, + null, + 2, + )}\n`, + ); + process.stdout.write(`extreme-scale gates: ${status.toUpperCase()} on Node ${process.version} (${path.relative(root, artifact)})\n`); + if (status !== "passed") process.exitCode = 1; +} + +if (import.meta.url === `file://${process.argv[1]}`) { + await main(); +} diff --git a/src/adapters/http/feature-http-binding.ts b/src/adapters/http/feature-http-binding.ts index 838a461d..644d96c2 100644 --- a/src/adapters/http/feature-http-binding.ts +++ b/src/adapters/http/feature-http-binding.ts @@ -11,6 +11,7 @@ import { type FailureKind, } from "../../contracts/errors.ts"; import type { MutationIntent } from "../../contracts/mutation-intent.ts"; +import type { ExecutionContext } from "../../platform/execution/execution-context.ts"; import type { HttpExecutionOutcome, SafeResponseMetadata, @@ -64,6 +65,7 @@ export type InstalledHttpOperationExecutor = Readonly<{ routeId: string; signal?: AbortSignal; intent?: MutationIntent; + execution?: ExecutionContext; }>, ): Promise>; }>; @@ -211,6 +213,7 @@ export type FeatureHttpBinding< context?: Readonly<{ signal?: AbortSignal; intent?: MutationIntent; + execution?: ExecutionContext; }>, ): Promise, ApiFailure>>; }>; @@ -243,6 +246,7 @@ export function createFeatureHttpBinding< context: Readonly<{ signal?: AbortSignal; intent?: MutationIntent; + execution?: ExecutionContext; }> = {}, ): Promise, ApiFailure>> { const operation = operations[operationId]; @@ -261,6 +265,9 @@ export function createFeatureHttpBinding< routeId: operation.routeId, ...(context.signal === undefined ? {} : { signal: context.signal }), ...(context.intent === undefined ? {} : { intent: context.intent }), + ...(context.execution === undefined + ? {} + : { execution: context.execution }), }); return projectExecutionOutcome( operation.operationId, diff --git a/src/adapters/http/http-contract-bridge.ts b/src/adapters/http/http-contract-bridge.ts index 662143c2..4413782b 100644 --- a/src/adapters/http/http-contract-bridge.ts +++ b/src/adapters/http/http-contract-bridge.ts @@ -109,6 +109,10 @@ const TRANSPORT_OWNED_HEADERS: ReadonlySet = new Set([ "accept", "content-type", "idempotency-key", + // Spec ยง29. Interaction trace propagation is runtime-owned; a credential + // collaborator can never supply or shadow these. + "traceparent", + "x-correlation-id", ]); const FORBIDDEN_REQUEST_HEADERS: ReadonlySet = new Set([ diff --git a/src/adapters/http/http-execution-v3.ts b/src/adapters/http/http-execution-v3.ts index 74d6d3e0..f8033c70 100644 --- a/src/adapters/http/http-execution-v3.ts +++ b/src/adapters/http/http-execution-v3.ts @@ -41,6 +41,19 @@ import { type PhysicalAttemptState, } from "./http-effect-certainty.ts"; import { parseRetryAfter } from "./retry-policy.ts"; +import { + createExecutionContext, + MAX_INTERACTION_DEADLINE_MS, + type ExecutionContext, +} from "../../platform/execution/execution-context.ts"; +import { + ConcurrencyQueueFullError, + type ConcurrencyLease, +} from "../../platform/traffic/concurrency-budget.ts"; +import type { TrafficBudget } from "../../platform/traffic/traffic-budget.ts"; +import { checkJsonStructure } from "../../platform/validation/bounded-json.ts"; +import { buildTraceHeaders } from "../../platform/telemetry/trace-context.ts"; +import { responseValidationBudget } from "../../platform/validation/validation-budget.ts"; import { canRetryTransport, isRetryableHttpStatus, @@ -196,8 +209,28 @@ export interface HttpExecutionContext { readonly signal?: AbortSignal; readonly scope: CacheScopeSnapshot; readonly intent?: MutationIntent; + /** + * Spec ยง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 + * interaction from the operation's own traffic policy, so no execution is + * ever unbudgeted. + */ + readonly execution?: ExecutionContext; } +/** + * Spec ยง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({ + maxPhysicalRequests: 1 + HTTP_EXECUTION_CEILINGS.hardRetryCount, + maxRetries: HTTP_EXECUTION_CEILINGS.hardRetryCount, + maxConcurrentRequests: 1, + maxQueuedRequests: 0, +}); + export interface ContractHttpExecutor { execute( operation: InstalledHttpContract, @@ -417,9 +450,30 @@ export function createContractHttpExecutor( // ยง8.5. One monotonic deadline covers credential resolution, encoding, // backoff, every physical attempt, body read and validation. const startedAt = now(); - const totalDeadlineMs = effectiveDeadlineMs(policy.totalDeadlineMs); + const execution = + context.execution ?? + createExecutionContext({ + interactionId: "implicit-operation", + deadlineMs: Math.max( + 1, + Math.min( + MAX_INTERACTION_DEADLINE_MS, + Math.ceil(effectiveDeadlineMs(policy.totalDeadlineMs)), + ), + ), + traffic: policy.traffic ?? DEFAULT_OPERATION_TRAFFIC_BUDGET, + clock: now, + startedAt, + }); + // Spec ยง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, + Math.min(effectiveDeadlineMs(policy.totalDeadlineMs), execution.remainingMs()), + ); const deadlineAt = startedAt + totalDeadlineMs; - const remaining = () => deadlineAt - now(); + const remaining = () => + Math.min(deadlineAt - now(), execution.remainingMs()); let attemptState: PhysicalAttemptState = "PREPARING"; let attempts = 0; @@ -460,6 +514,15 @@ export function createContractHttpExecutor( once: true, }); } + // Spec ยง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(); + else { + interactionSignal?.addEventListener("abort", forwardCallerToLifetime, { + once: true, + }); + } if (context.scope.signal.aborted) forwardScopeToLifetime(); else { context.scope.signal.addEventListener("abort", forwardScopeToLifetime, { @@ -476,6 +539,7 @@ export function createContractHttpExecutor( lifetimeDisposed = true; clearTimeout(lifetimeDeadlineTimer); callerSignal?.removeEventListener("abort", forwardCallerToLifetime); + interactionSignal?.removeEventListener("abort", forwardCallerToLifetime); context.scope.signal.removeEventListener("abort", forwardScopeToLifetime); lifetimeController.abort(); }; @@ -688,6 +752,11 @@ 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 + // identity; every child request carries the same trace and correlation. + if (context.execution?.trace !== undefined) { + Object.assign(headers, buildTraceHeaders(context.execution)); + } const retryCeiling = Math.min( policy.retryBudget, @@ -695,8 +764,15 @@ export function createContractHttpExecutor( HTTP_EXECUTION_CEILINGS.hardRetryCount, ); + // Spec ยง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 => + execution.traffic.requests.remaining > 0 && + execution.traffic.retries.tryConsume(contract.operationId); + for (let retryIndex = 0; ; retryIndex += 1) { - if (callerSignal?.aborted) { + if (callerSignal?.aborted || interactionSignal?.aborted) { terminalCancellation ??= "CALLER"; return finish( cancelled(abandonedCertainty()), @@ -711,6 +787,41 @@ export function createContractHttpExecutor( ); } + if (remaining() <= 0) { + return finish(abandonedTransportFailure("TIMEOUT"), "TIMEOUT"); + } + // Spec ยง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( + abandonedTransportFailure("OVERLOADED_BEFORE_SEND"), + "TRAFFIC_BUDGET_EXCEEDED", + ); + } + let lease: ConcurrencyLease; + try { + lease = await execution.traffic.concurrency.acquire( + lifetimeController.signal, + ); + } catch (error) { + if (error instanceof ConcurrencyQueueFullError) { + return finish( + abandonedTransportFailure("OVERLOADED_BEFORE_SEND"), + "TRAFFIC_BUDGET_EXCEEDED", + ); + } + if (terminalCancellation === "CALLER") { + return finish(cancelled(abandonedCertainty()), "CANCELLED"); + } + if (terminalCancellation === "SCOPE_FENCE") { + return finish( + abandonedTransportFailure("ABORTED_BY_SCOPE"), + "SCOPE_FENCED", + ); + } + return finish(abandonedTransportFailure("TIMEOUT"), "TIMEOUT"); + } + try { const controller = new AbortController(); const budget = remaining(); if (budget <= 0) { @@ -821,7 +932,8 @@ export function createContractHttpExecutor( remaining() > 0 ) { const delay = jitteredDelay(retryIndex, random); - if (delay < remaining()) { + if (delay < remaining() && admitRetry()) { + lease.release(); const slept = await awaitWithAbort( sleep(delay, lifetimeController.signal), lifetimeController.signal, @@ -905,7 +1017,8 @@ export function createContractHttpExecutor( isRetryableSemantics(contract.retrySemantics) ) { const delay = retryDelayFor(outcome.retryAfterMs, retryIndex, random); - if (delay !== null && delay < remaining()) { + if (delay !== null && delay < remaining() && admitRetry()) { + lease.release(); clearTimeout(deadlineTimer); lifetimeController.signal.removeEventListener( "abort", @@ -934,6 +1047,9 @@ export function createContractHttpExecutor( clearTimeout(deadlineTimer); lifetimeController.signal.removeEventListener("abort", forwardLifetime); } + } finally { + lease.release(); + } } } catch { return finish( @@ -1191,6 +1307,20 @@ async function admitResponse( "CONTRACT_VIOLATION", ); } + // Spec ยง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 ( + !checkJsonStructure( + decoded.value, + responseValidationBudget(policy.responseByteLimit), + ).ok + ) { + return settled( + violation("RESPONSE_TOO_LARGE", "RESPONSE", postDispatchEffect(isCommand)), + "RESPONSE_STRUCTURE_LIMIT", + ); + } const validated = invokeValidator(contract.outputValidator, decoded.value); if (validated.outcome === "THROWN") { @@ -1393,6 +1523,24 @@ async function admitProblem( }); } + if ( + !checkJsonStructure( + decoded.value, + responseValidationBudget(HTTP_EXECUTION_CEILINGS.problemResponseBytes), + ).ok + ) { + return Object.freeze({ + result: violation( + "PROBLEM_SCHEMA_INVALID", + "VALIDATION", + postDispatchEffect(isCommand), + ), + certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED", + retryHint: false, + retryAfterMs: metadata.retryAfterMs ?? null, + }); + } + const validated = invokeValidator(contract.problemValidator, decoded.value); if (validated.outcome !== "VALID") { return Object.freeze({ diff --git a/src/adapters/http/http-retry-lifecycle.ts b/src/adapters/http/http-retry-lifecycle.ts index ec7139b2..3354d21b 100644 --- a/src/adapters/http/http-retry-lifecycle.ts +++ b/src/adapters/http/http-retry-lifecycle.ts @@ -33,25 +33,34 @@ export function isRetryableSemantics(semantics: RetrySemantics): boolean { return semantics === "SAFE" || semantics === "IDEMPOTENT"; } +function localJitterCeiling(retryIndex: number): number { + return Math.min(RETRY_MAX_LOCAL_DELAY_MS, RETRY_BASE_DELAY_MS * 2 ** retryIndex); +} + /** Full jitter over min(2000, 250 * 2^retryIndex). */ export function jitteredDelay( retryIndex: number, random: () => number, ): number { - const ceiling = Math.min( - RETRY_MAX_LOCAL_DELAY_MS, - RETRY_BASE_DELAY_MS * 2 ** retryIndex, - ); - return Math.floor(random() * ceiling); + return Math.floor(random() * localJitterCeiling(retryIndex)); } +/** + * Spec ยง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. + */ export function retryDelayFor( retryAfterMs: number | null, retryIndex: number, random: () => number, ): number | null { - const local = jitteredDelay(retryIndex, random); - if (retryAfterMs === null) return local; + if (retryAfterMs === null) return jitteredDelay(retryIndex, random); if (retryAfterMs > RETRY_AFTER_CEILING_MS) return null; - return Math.max(local, retryAfterMs); + const window = Math.min( + RETRY_MAX_LOCAL_DELAY_MS, + Math.max(localJitterCeiling(retryIndex), Math.ceil(retryAfterMs / 4)), + ); + return retryAfterMs + Math.floor(random() * window); } diff --git a/src/adapters/http/index.ts b/src/adapters/http/index.ts index 626f3268..a70f84e2 100644 --- a/src/adapters/http/index.ts +++ b/src/adapters/http/index.ts @@ -19,6 +19,8 @@ export { type HttpTransportFailure, type SafeResponseMetadata, } from "./http-execution-v3.ts"; +/** Spec ยง17. V3 ๊ฒฐ๊ณผ๋ฅผ ํ”Œ๋žซํผ ์˜ค๋ฅ˜ ๋ด‰ํˆฌ(`AppError`)๋กœ ์ •๊ทœํ™”ํ•œ๋‹ค. */ +export { platformErrorForOutcome } from "./platform-error-mapping.ts"; export { createFeatureHttpBinding, defineFeatureHttpOperation, diff --git a/src/adapters/http/platform-error-mapping.ts b/src/adapters/http/platform-error-mapping.ts new file mode 100644 index 00000000..751a4a6c --- /dev/null +++ b/src/adapters/http/platform-error-mapping.ts @@ -0,0 +1,45 @@ +import type { AppError } from "../../platform/errors/app-error.ts"; +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 + * 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`. + */ +export function platformErrorForOutcome( + outcome: HttpExecutionOutcome, +): AppError | null { + switch (outcome.kind) { + case "CANCELLED": + return PLATFORM_ERRORS.REQUEST_CANCELLED; + case "TRANSPORT_FAILURE": + switch (outcome.failure.kind) { + case "TIMEOUT": + return PLATFORM_ERRORS.REQUEST_TIMEOUT; + case "ABORTED_BY_CALLER": + return PLATFORM_ERRORS.REQUEST_CANCELLED; + case "OVERLOADED_BEFORE_SEND": + return PLATFORM_ERRORS.TRAFFIC_BUDGET_EXCEEDED; + case "ABORTED_BY_SCOPE": + return null; + default: + return PLATFORM_ERRORS.NETWORK_UNAVAILABLE; + } + case "CONTRACT_VIOLATION": + switch (outcome.violation.kind) { + case "RESPONSE_TOO_LARGE": + return PLATFORM_ERRORS.RESPONSE_TOO_LARGE; + case "SCOPE_FENCED": + case "MISSING_IDEMPOTENCY_KEY": + case "UNEXPECTED_IDEMPOTENCY_KEY": + case "FINAL_REQUEST_INVARIANT_FAILED": + return null; + default: + return PLATFORM_ERRORS.RESPONSE_INVALID; + } + default: + return null; + } +} diff --git a/src/adapters/http/schema-registry.ts b/src/adapters/http/schema-registry.ts index 09a4a528..1edb48c8 100644 --- a/src/adapters/http/schema-registry.ts +++ b/src/adapters/http/schema-registry.ts @@ -1,4 +1,5 @@ import { z } from "zod"; +import { projectValidationIssues } from "../../contracts/validation-issues.ts"; const metaSchema = z .object({ @@ -104,9 +105,6 @@ function projectResult( return { success: false, - issues: result.error.issues.map((issue) => ({ - path: issue.path.join("."), - code: issue.code, - })), + issues: projectValidationIssues(result.error.issues), }; } diff --git a/src/adapters/telemetry/best-effort-telemetry.ts b/src/adapters/telemetry/best-effort-telemetry.ts index 7797b105..63027b44 100644 --- a/src/adapters/telemetry/best-effort-telemetry.ts +++ b/src/adapters/telemetry/best-effort-telemetry.ts @@ -26,8 +26,21 @@ export type TelemetryAdapterOptions = Readonly<{ now?: () => number; onDrop?: (event: TelemetryEvent) => void; lifecycle?: Pick; + /** + * Spec ยง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. + */ + maxSendsPerMinute?: number; + /** Monotonic clock for the send-rate window (default `performance.now`). */ + monotonicNow?: () => number; + setTimer?: (callback: () => void, ms: number) => unknown; + clearTimer?: (handle: unknown) => void; }>; +export const DEFAULT_TELEMETRY_SENDS_PER_MINUTE = 20; +const SEND_WINDOW_MS = 60_000; + export const noOpTelemetry: TelemetryAdapter = Object.freeze({ emit: () => {}, flush: async () => {}, @@ -62,6 +75,20 @@ export function createTelemetryAdapter( "telemetry maxQueue", ); const schedule = options.schedule ?? queueMicrotask; + const maxSendsPerMinute = assertBoundedCapacity( + options.maxSendsPerMinute ?? DEFAULT_TELEMETRY_SENDS_PER_MINUTE, + MAX_TELEMETRY_QUEUE, + "telemetry maxSendsPerMinute", + ); + const monotonicNow = options.monotonicNow ?? (() => performance.now()); + const setTimer = + options.setTimer ?? ((callback: () => void, ms: number) => setTimeout(callback, ms)); + const clearTimer = + options.clearTimer ?? + ((handle: unknown) => clearTimeout(handle as ReturnType)); + /** Send instants inside the current window; never longer than the limit. */ + const sendTimes: number[] = []; + let rateTimer: unknown = null; const queue: TelemetryEvent[] = []; let lifecycleState: TelemetryLifecycle = "ACTIVE"; /** Scheduled callbacks captured before disposal must not run afterwards. */ @@ -146,15 +173,40 @@ export function createTelemetryAdapter( scheduleFlush(); } + function rateAllows(at: number): boolean { + while (sendTimes.length > 0 && at - (sendTimes[0] as number) >= SEND_WINDOW_MS) { + sendTimes.shift(); + } + return sendTimes.length < maxSendsPerMinute; + } + + function armRateTimer(at: number): void { + if (rateTimer !== null || lifecycleState === "DISPOSED") return; + const reopenIn = Math.max(1, (sendTimes[0] ?? at) + SEND_WINDOW_MS - at); + rateTimer = setTimer(() => { + rateTimer = null; + void flush(); + }, reopenIn); + } + /** * `flush()` joins the active delivery instead of resolving immediately, so an * awaited flush really means "the in-flight batch has settled". */ - function flush(): Promise { + function flush(bypassRate = false): Promise { if (activeFlush) return activeFlush; if (lifecycleState === "DISPOSED" || queue.length === 0) { return Promise.resolve(); } + const at = monotonicNow(); + if (!rateAllows(at)) { + if (!bypassRate) { + armRateTimer(at); + return Promise.resolve(); + } + } + sendTimes.push(at); + if (sendTimes.length > maxSendsPerMinute) sendTimes.shift(); const generation = scheduleGeneration; const run = async () => { const batch = queue.splice(0, queue.length); @@ -186,8 +238,9 @@ export function createTelemetryAdapter( return activeFlush; } + // Page exit is the last chance to deliver: it may exceed the window once. const flushBeforePageExit = () => { - void flush(); + void flush(true); }; lifecycle?.addEventListener("pagehide", flushBeforePageExit); @@ -201,6 +254,8 @@ export function createTelemetryAdapter( scheduleGeneration += 1; scheduled = false; lifecycle?.removeEventListener("pagehide", flushBeforePageExit); + if (rateTimer !== null) clearTimer(rateTimer); + rateTimer = null; queue.length = 0; activeSink?.abort(); activeSink = null; @@ -209,7 +264,7 @@ export function createTelemetryAdapter( return Object.freeze({ emit, - flush, + flush: () => flush(), pendingCount: () => queue.length, droppedCount: () => dropped, dropReasons: () => Object.freeze(Object.fromEntries(dropReasons)), diff --git a/src/adapters/telemetry/feature-telemetry.ts b/src/adapters/telemetry/feature-telemetry.ts new file mode 100644 index 00000000..2b242e9f --- /dev/null +++ b/src/adapters/telemetry/feature-telemetry.ts @@ -0,0 +1,78 @@ +import { + createTelemetryPipeline, + DEFAULT_TELEMETRY_PIPELINE_BUDGET, + type TelemetryBatchItem, + type TelemetryPipeline, + type TelemetryPipelineBudget, + type TelemetryTransport, +} from "../../platform/telemetry/telemetry-pipeline.ts"; + +/** + * Spec ยง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 + * transport here, never in feature code. + */ +export function createFetchTelemetryTransport( + options: Readonly<{ endpoint: string; fetcher?: typeof fetch }>, +): TelemetryTransport { + const fetcher = options.fetcher ?? fetch; + return Object.freeze({ + async send(batch: readonly TelemetryBatchItem[]): Promise { + const response = await fetcher(options.endpoint, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ + events: batch.map((item) => ({ + ...item.event, + fingerprint: item.fingerprint, + occurrences: item.occurrences, + })), + }), + keepalive: true, + credentials: "omit", + cache: "no-store", + }); + if (!response.ok) throw new Error("telemetry collector rejected batch"); + }, + }); +} + +const DISABLED_FEATURE_TELEMETRY: TelemetryPipeline = Object.freeze({ + emit: () => Promise.resolve(), + flush: () => Promise.resolve(), + stats: () => + Object.freeze({ + accepted: 0, + invalid: 0, + deduplicated: 0, + sampledOut: 0, + dropped: 0, + sends: 0, + failedSends: 0, + buffered: 0, + bufferedBytes: 0, + peakBuffered: 0, + fingerprints: 0, + }), + dispose: () => {}, +}); + +export function createFeatureTelemetry( + options: Readonly<{ + enabled: boolean; + endpoint?: string; + fetcher?: typeof fetch; + budget?: TelemetryPipelineBudget; + }>, +): TelemetryPipeline { + if (!options.enabled || !options.endpoint) return DISABLED_FEATURE_TELEMETRY; + return createTelemetryPipeline({ + transport: createFetchTelemetryTransport({ + endpoint: options.endpoint, + ...(options.fetcher === undefined ? {} : { fetcher: options.fetcher }), + }), + budget: options.budget ?? DEFAULT_TELEMETRY_PIPELINE_BUDGET, + }); +} diff --git a/src/adapters/telemetry/index.ts b/src/adapters/telemetry/index.ts index f6abed32..5c1f6d57 100644 --- a/src/adapters/telemetry/index.ts +++ b/src/adapters/telemetry/index.ts @@ -5,3 +5,8 @@ export { type TelemetryAdapter, type TelemetryAdapterOptions, } from "./best-effort-telemetry.ts"; +/** Spec ยง24โ€“ยง27. ๊ธฐ๋Šฅ ์†Œ์œ  ํ…”๋ ˆ๋ฉ”ํŠธ๋ฆฌ์˜ ์ˆ˜์ง‘๊ธฐ ์ „์†ก(๊ณต๊ธ‰์ž ์ค‘๋ฆฝ ํฌํŠธ ๋’ค). */ +export { + createFeatureTelemetry, + createFetchTelemetryTransport, +} from "./feature-telemetry.ts"; diff --git a/src/apps/deployable-app-module.ts b/src/apps/deployable-app-module.ts new file mode 100644 index 00000000..7100473b --- /dev/null +++ b/src/apps/deployable-app-module.ts @@ -0,0 +1,34 @@ +import type { BoundedContextModule } from "../contexts/bounded-context-module.ts"; +import { assertWithinCardinalityBudget } from "../platform/cardinality/cardinality-budget.ts"; + +export type DeployableAppModule = Readonly<{ + id: string; + contexts: readonly Context[]; + budget: Readonly<{ maxContexts: number }>; +}>; + +export function defineDeployableAppModule( + definition: Readonly<{ + id: string; + contexts: readonly Context[]; + budget: Readonly<{ maxContexts: number }>; + }>, +): DeployableAppModule { + assertWithinCardinalityBudget( + `${definition.id}.contexts`, + definition.contexts.length, + definition.budget.maxContexts, + ); + const seen = new Set(); + for (const context of definition.contexts) { + if (seen.has(context.id)) { + throw new TypeError(`Duplicate ${definition.id}.contexts child id: ${context.id}`); + } + seen.add(context.id); + } + return Object.freeze({ + ...definition, + contexts: Object.freeze([...definition.contexts]), + budget: Object.freeze({ ...definition.budget }), + }); +} diff --git a/src/apps/template-app.ts b/src/apps/template-app.ts new file mode 100644 index 00000000..2d03472d --- /dev/null +++ b/src/apps/template-app.ts @@ -0,0 +1,14 @@ +import { PRODUCT_APP } from "../.generated/product-app.ts"; +import { PRODUCT_CONTEXT_MODULES } from "../.generated/product-context-index.ts"; +import { defineDeployableAppModule } from "./deployable-app-module.ts"; + +/** + * The deployable app this build produces. Its identity, budget and direct + * contexts all come from the generator's selected app (`--app=`/`PRODUCT_APP_ID`, + * or the single declared app), so the bundle only ever contains that app. + */ +export const TEMPLATE_APP_MODULE = defineDeployableAppModule({ + id: PRODUCT_APP.id, + contexts: PRODUCT_CONTEXT_MODULES, + budget: Object.freeze({ maxContexts: PRODUCT_APP.maxContexts }), +} as const); diff --git a/src/apps/template-app/app-module.ts b/src/apps/template-app/app-module.ts new file mode 100644 index 00000000..0b10e621 --- /dev/null +++ b/src/apps/template-app/app-module.ts @@ -0,0 +1,6 @@ +/** + * Spec ยง5.3. Ownership declaration of the template deployable app. The + * generator reads these literals; contexts name this id as their owner. + */ +export const APP_MODULE_ID = "template-app"; +export const APP_MAX_CONTEXTS = 20; diff --git a/src/bootstrap/boot-release-recovery.ts b/src/bootstrap/boot-release-recovery.ts new file mode 100644 index 00000000..bc972453 --- /dev/null +++ b/src/bootstrap/boot-release-recovery.ts @@ -0,0 +1,87 @@ +import { createBrowserStorageAdapter } from "../adapters/storage/index.ts"; +import { + createReleaseMismatchRecovery, + type RecoveryMarkerStore, + type ReleaseMismatchDecision, +} from "../platform/release/release-mismatch-recovery.ts"; +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 + * 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. + */ +const RECOVERY_KEY = "RELEASE_MISMATCH_RECOVERY"; + +const RELEASE_MISMATCH_KINDS: ReadonlySet = new Set([ + "BUILD_MISMATCH", + "PROTOCOL_PAIR_MISMATCH", + "CONFIG_MISMATCH", + "API_CONTRACT_MISMATCH", + "RELEASE_MISMATCH", + "ASSET_MISMATCH", + "CONTRACT_SET_MISMATCH", +]); + +/** A stable key for a boot failure that is a release mismatch, else null. */ +export function releaseMismatchKey(error: unknown): string | null { + if (error instanceof ReleaseManifestError && RELEASE_MISMATCH_KINDS.has(error.kind)) { + return `${error.safe.buildId}:${error.code}:${error.safe.releaseId ?? "-"}`; + } + if (error instanceof BootConfigError && error.code === "CONFIG_BUILD_MISMATCH") { + return `${error.safe.buildId}:${error.code}:${error.safe.releaseId ?? "-"}`; + } + return null; +} + +function sessionStorageOf(host: Record): Storage | undefined { + try { + const candidate = Reflect.get(host, "sessionStorage") as unknown; + if (!candidate || typeof candidate !== "object") return undefined; + return ["getItem", "setItem", "removeItem"].every( + (method) => typeof Reflect.get(candidate, method) === "function", + ) + ? (candidate as Storage) + : undefined; + } catch { + return undefined; + } +} + +export function createBootReleaseRecovery( + host: Record = globalThis as unknown as Record, +) { + const sessionStorage = sessionStorageOf(host); + const storage = createBrowserStorageAdapter( + sessionStorage === undefined ? {} : { sessionStorage }, + ); + const store: RecoveryMarkerStore = Object.freeze({ + read() { + const result = storage.read(RECOVERY_KEY); + return result.ok && typeof result.value === "string" ? result.value : null; + }, + write(value: string) { + if (!storage.write(RECOVERY_KEY, value).ok) { + throw new Error("release recovery marker was not persisted"); + } + }, + clear() { + storage.remove(RECOVERY_KEY); + }, + }); + return createReleaseMismatchRecovery(store); +} + +/** + * Decides what a failed boot does: a release mismatch may reload exactly once + * per mismatch key; anything else (and a repeated mismatch) shows the failure. + */ +export function decideBootFailure( + error: unknown, + recovery: ReturnType, +): ReleaseMismatchDecision { + const key = releaseMismatchKey(error); + return key === null ? "show-failure" : recovery.decide(key); +} diff --git a/src/bootstrap/load-release-manifest.ts b/src/bootstrap/load-release-manifest.ts index 79f1661d..fa8c7520 100644 --- a/src/bootstrap/load-release-manifest.ts +++ b/src/bootstrap/load-release-manifest.ts @@ -17,6 +17,19 @@ import { type BootLoadFailure, } from "./read-bounded-boot-json.ts"; import type { RuntimeConfigLoadResult } from "./load-runtime-config.ts"; +import { + checkReleaseCoherence, + type ReleaseIdentity, + type ReleaseIdentityField, +} from "../platform/release/release-coherence.ts"; + +const MISMATCH_CODE: Readonly> = + Object.freeze({ + buildId: "MANIFEST_BUILD_MISMATCH", + configSchemaVersion: "MANIFEST_CONFIG_SCHEMA_MISMATCH", + releaseId: "MANIFEST_RELEASE_MISMATCH", + assetManifestHash: "MANIFEST_ASSET_MISMATCH", + }); /** ยง5.8. Retained for one compatibility window; carries the removed scalar. */ export const releaseManifestV1Schema = releaseManifestV1ArtifactSchema; @@ -233,23 +246,38 @@ export async function loadReleaseManifest( } // ยง6.7 steps 5-6, in order: build, config, release, assets, then contractSet. - let mismatchCode: ReleaseManifestErrorCode | null = null; - if (manifest.buildId !== runtime.build.buildId) { - mismatchCode = "MANIFEST_BUILD_MISMATCH"; - } - if ( - !mismatchCode && - runtime.config.BUILD_ID && - manifest.buildId !== runtime.config.BUILD_ID - ) { - mismatchCode = "MANIFEST_BUILD_MISMATCH"; - } - if ( - !mismatchCode && - manifest.configSchemaVersion !== runtime.config.CONFIG_SCHEMA_VERSION - ) { - mismatchCode = "MANIFEST_CONFIG_SCHEMA_MISMATCH"; - } + // Spec ยง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> = { + html: { + buildId: runtime.build.buildId, + ...(options.expectedAssetManifestHash + ? { assetManifestHash: options.expectedAssetManifestHash } + : {}), + }, + config: { + ...(runtime.config.BUILD_ID ? { buildId: runtime.config.BUILD_ID } : {}), + ...(runtime.config.RELEASE_ID ? { releaseId: runtime.config.RELEASE_ID } : {}), + configSchemaVersion: runtime.config.CONFIG_SCHEMA_VERSION, + }, + manifest: { + buildId: manifest.buildId, + releaseId: manifest.releaseId, + configSchemaVersion: manifest.configSchemaVersion, + assetManifestHash: manifest.assetManifestHash, + }, + }; + const mismatchFor = ( + fields: readonly ReleaseIdentityField[], + ): ReleaseManifestErrorCode | null => { + const result = checkReleaseCoherence(identities, fields); + return result.coherent ? null : MISMATCH_CODE[result.field]; + }; + let mismatchCode: ReleaseManifestErrorCode | null = mismatchFor([ + "buildId", + "configSchemaVersion", + ]); if ( !mismatchCode && runtime.configSchema === "V1" && @@ -260,20 +288,7 @@ export async function loadReleaseManifest( ) { mismatchCode = "MANIFEST_API_CONTRACT_MISMATCH"; } - if ( - !mismatchCode && - runtime.config.RELEASE_ID && - manifest.releaseId !== runtime.config.RELEASE_ID - ) { - mismatchCode = "MANIFEST_RELEASE_MISMATCH"; - } - if ( - !mismatchCode && - options.expectedAssetManifestHash && - manifest.assetManifestHash !== options.expectedAssetManifestHash - ) { - mismatchCode = "MANIFEST_ASSET_MISMATCH"; - } + mismatchCode ??= mismatchFor(["releaseId", "assetManifestHash"]); if (mismatchCode) { throw new ReleaseManifestError(mismatchCode, identity); } diff --git a/src/bootstrap/load-runtime-config.ts b/src/bootstrap/load-runtime-config.ts index af0f8157..5cd5f40f 100644 --- a/src/bootstrap/load-runtime-config.ts +++ b/src/bootstrap/load-runtime-config.ts @@ -1,4 +1,5 @@ import { assertSafeConfigNames, getBuildConfig } from "../contracts/env.ts"; +import { checkReleaseCoherence } from "../platform/release/release-coherence.ts"; import { BOOT_JSON_POLICIES, readBoundedBootJson, @@ -128,9 +129,16 @@ export async function loadRuntimeConfig( }); } + // Spec ยง45. HTML/JS build vs runtime config: delegated to the one pure + // release-coherence validator so config and manifest checks cannot drift. if ( - validated.data.BUILD_ID && - validated.data.BUILD_ID !== buildConfig.buildId + !checkReleaseCoherence( + { + html: { buildId: buildConfig.buildId }, + config: validated.data.BUILD_ID ? { buildId: validated.data.BUILD_ID } : {}, + }, + ["buildId"], + ).coherent ) { throw new BootConfigError("CONFIG_BUILD_MISMATCH", { buildId: buildConfig.buildId, diff --git a/src/bootstrap/main.tsx b/src/bootstrap/main.tsx index d7417726..49ff1f73 100644 --- a/src/bootstrap/main.tsx +++ b/src/bootstrap/main.tsx @@ -3,6 +3,10 @@ import { createRoot } from "react-dom/client"; import { recordBootFailure } from "../adapters/diagnostics/index.ts"; import { BootErrorShell } from "../presentation/boundaries/boot-error-shell.tsx"; import "../presentation/styles/theme.css"; +import { + createBootReleaseRecovery, + decideBootFailure, +} from "./boot-release-recovery.ts"; import { createRuntimeComposition } from "./create-runtime-composition.ts"; import { initializeColorScheme } from "./initialize-color-scheme.ts"; import { ReleaseManifestError } from "./load-release-manifest.ts"; @@ -18,8 +22,11 @@ if (!rootElement) { const root = createRoot(rootElement); async function boot(): Promise { + const releaseRecovery = createBootReleaseRecovery(); try { const composition = await createRuntimeComposition(); + // A coherent boot clears any reload-once marker from a previous mismatch. + releaseRecovery.markCoherentBoot(); document.documentElement.dataset.buildId = composition.release.buildId; document.documentElement.dataset.releaseId = composition.release.releaseId; initializeColorScheme(composition.application.preferences); @@ -34,6 +41,12 @@ async function boot(): Promise { : { supportReference: "boot:unknown" }; recordBootFailure(error, safe); + // Spec ยง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(); + return; + } root.render(); } } diff --git a/src/bootstrap/runtime-adapters.ts b/src/bootstrap/runtime-adapters.ts index 06e1672e..83703530 100644 --- a/src/bootstrap/runtime-adapters.ts +++ b/src/bootstrap/runtime-adapters.ts @@ -27,7 +27,10 @@ import { } from "../adapters/query-cache/index.ts"; import { createBrowserStorageAdapter } from "../adapters/storage/index.ts"; import { createBrowserMutationIntentFactory } from "../adapters/platform/index.ts"; -import { createTelemetryAdapter } from "../adapters/telemetry/index.ts"; +import { + createFeatureTelemetry, + createTelemetryAdapter, +} from "../adapters/telemetry/index.ts"; import type { AuthSessionPort } from "../application/ports/auth-session-port.ts"; import type { ReleaseInfo } from "../application/ports/release-info-port.ts"; import { @@ -510,6 +513,9 @@ export async function createRuntimeAdapters( ...(executionContext.intent === undefined ? {} : { intent: executionContext.intent }), + ...(executionContext.execution === undefined + ? {} + : { execution: executionContext.execution }), }); if (outcome.kind === "UNAUTHENTICATED") { authSession.onUnauthenticated(); @@ -517,9 +523,21 @@ export async function createRuntimeAdapters( return outcome; }, }); - const featureInputs = createInstalledFeatureInputs({ - http: contractOperations, + // Spec ยง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, + ...(config.TELEMETRY_ENDPOINT === undefined + ? {} + : { endpoint: config.TELEMETRY_ENDPOINT }), + ...(context.fetcher === undefined ? {} : { fetcher: context.fetcher }), }); + // Each installed contribution receives only the capabilities it declares. + const featureCapabilities = Object.freeze({ + http: contractOperations, + telemetry: featureTelemetry, + }); + const featureInputs = createInstalledFeatureInputs(featureCapabilities); return Object.freeze({ outputPorts: Object.freeze({ @@ -550,6 +568,7 @@ export async function createRuntimeAdapters( // delivering before the diagnostics and state dependencies it observes // are destroyed. telemetry.dispose(); + featureTelemetry.dispose(); conditionalValidators.clear(); serverStateScope.dispose(); serverStateGeneration.dispose(); diff --git a/src/contexts/bounded-context-module.ts b/src/contexts/bounded-context-module.ts new file mode 100644 index 00000000..1e05f34b --- /dev/null +++ b/src/contexts/bounded-context-module.ts @@ -0,0 +1,45 @@ +import type { RouteObject } from "react-router-dom"; +import type { AnyFeatureModule } from "../features/feature-module.ts"; +import { assertWithinCardinalityBudget } from "../platform/cardinality/cardinality-budget.ts"; + +export type BoundedContextRouteModule = Readonly<{ + path: string; + loadRoutes(): Promise; +}>; + +export type BoundedContextModule< + Feature extends AnyFeatureModule = AnyFeatureModule, +> = Readonly<{ + id: string; + features: readonly Feature[]; + budget: Readonly<{ maxFeatures: number }>; + route?: BoundedContextRouteModule; +}>; + +export function defineBoundedContextModule( + definition: Readonly<{ + id: string; + features: readonly Feature[]; + budget: Readonly<{ maxFeatures: number }>; + route?: BoundedContextRouteModule; + }>, +): BoundedContextModule { + assertWithinCardinalityBudget( + `${definition.id}.features`, + definition.features.length, + definition.budget.maxFeatures, + ); + const seen = new Set(); + for (const feature of definition.features) { + if (seen.has(feature.id)) { + throw new TypeError(`Duplicate ${definition.id}.features child id: ${feature.id}`); + } + seen.add(feature.id); + } + return Object.freeze({ + ...definition, + features: Object.freeze([...definition.features]), + budget: Object.freeze({ ...definition.budget }), + ...(definition.route ? { route: Object.freeze({ ...definition.route }) } : {}), + }); +} diff --git a/src/contexts/reference-context/context-module.ts b/src/contexts/reference-context/context-module.ts new file mode 100644 index 00000000..bba3c41d --- /dev/null +++ b/src/contexts/reference-context/context-module.ts @@ -0,0 +1,9 @@ +/** + * Spec ยง5.2. Ownership declaration of the reference bounded context: the app + * that owns it, its route root, and its direct-feature budget. Features name + * this id as their owner. + */ +export const CONTEXT_MODULE_ID = "reference-context"; +export const CONTEXT_APP_ID = "template-app"; +export const CONTEXT_ROUTE_PATH = "examples/reference-resources/*"; +export const CONTEXT_MAX_FEATURES = 200; diff --git a/src/contracts/diagnostics.ts b/src/contracts/diagnostics.ts index bbbeb1b0..976851f4 100644 --- a/src/contracts/diagnostics.ts +++ b/src/contracts/diagnostics.ts @@ -42,10 +42,71 @@ export const DIAGNOSTIC_CONTEXT_ALLOWLIST = Object.freeze([ ] as const); export type DiagnosticContextKey = (typeof DIAGNOSTIC_CONTEXT_ALLOWLIST)[number]; + +export type DiagnosticCardinalityClass = + | "bounded" + | "taxonomy" + | "topology" + | "deployment" + | "request"; + +/** + * Cardinality ownership is explicit so a field cannot silently move from + * bounded operational evidence into an unbounded metric dimension. + * + * `request` values are unique per request and are diagnostics-only. + * `topology` values are bounded by the deployed App/Context/Feature topology. + * `taxonomy` values are bounded by source-controlled error/reason taxonomies. + * `deployment` values rotate with a release, not with user traffic. + * `bounded` values are validated against a finite set below. + */ +export const DIAGNOSTIC_CONTEXT_CARDINALITY = Object.freeze({ + app_version: "deployment", + build_id: "deployment", + release_id: "deployment", + active_release_id: "deployment", + config_schema_version: "deployment", + api_contract_version: "deployment", + route_id: "topology", + operation_id: "topology", + correlation_id: "request", + error_kind: "taxonomy", + outcome: "bounded", + http_status_group: "bounded", + attempt_count_bucket: "bounded", + duration_bucket: "bounded", + component_boundary: "bounded", + mismatch_kind: "taxonomy", + operation: "topology", + reason: "taxonomy", + queue_size_bucket: "bounded", +} satisfies Readonly>); + export type DiagnosticContext = Readonly< Partial> >; +const BOUNDED_CONTEXT_VALUE_POLICIES: Readonly< + Partial boolean>> +> = Object.freeze({ + outcome: (value) => + typeof value === "string" && + /^(?:success|recovered|failed|aborted|SUCCESS|PROBLEM|UNAUTHENTICATED|FORBIDDEN|RATE_LIMITED|CONTRACT_VIOLATION|TRANSPORT_FAILURE|CANCELLED|AUTH_INTEGRATION_FAILURE|FAILED|DEGRADED)$/.test( + value, + ), + http_status_group: (value) => + typeof value === "string" && /^(?:[0-9]xx|none)$/.test(value), + attempt_count_bucket: (value) => + typeof value === "string" && /^(?:1|2|3|3-4|5\+)$/.test(value), + duration_bucket: (value) => + typeof value === "string" && + /^(?:lt100ms|100-499ms|500-1999ms|gte2000ms|unknown)$/.test(value), + component_boundary: (value) => + typeof value === "string" && /^(?:route|feature|boot)$/.test(value), + queue_size_bucket: (value) => + typeof value === "string" && /^(?:0|1-10|11-50|51\+)$/.test(value), +}); + export type DiagnosticRecordInput = Readonly<{ level: DiagnosticLevel; eventId: DiagnosticEventId; @@ -86,11 +147,20 @@ function projectDiagnosticRecordUnsafe( ) { return { success: false, reason: "unknown-context" }; } - if (typeof value === "string") { + const contextKey = key as DiagnosticContextKey; + const boundedPolicy = BOUNDED_CONTEXT_VALUE_POLICIES[contextKey]; + if (boundedPolicy && !boundedPolicy(value)) { + return { success: false, reason: "invalid-context" }; + } + if (boundedPolicy && typeof value === "string") { + // Admitted from a finite, source-controlled set (e.g. "51+"), so the + // free-form safe-string pattern does not apply. + projected[contextKey] = value; + } else if (typeof value === "string") { if (!SAFE_VALUE.test(value)) { return { success: false, reason: "invalid-context" }; } - projected[key as DiagnosticContextKey] = value; + projected[contextKey] = value; } else if (typeof value === "number" && Number.isFinite(value)) { projected[key as DiagnosticContextKey] = value; } else if (typeof value === "boolean") { diff --git a/src/contracts/errors.ts b/src/contracts/errors.ts index 6ef354ab..3fc3e571 100644 --- a/src/contracts/errors.ts +++ b/src/contracts/errors.ts @@ -1,3 +1,12 @@ +import type { DiagnosticEventId } from "./diagnostics.ts"; +import type { TelemetryEventName } from "./telemetry.ts"; +import { + projectValidationIssues, + type ValidationIssue, +} from "./validation-issues.ts"; + +export type { ValidationIssue } from "./validation-issues.ts"; + const DROP_SENSITIVE = Object.freeze([ "cause", "body", @@ -17,13 +26,15 @@ export type ErrorAction = | "contact-support" | "none"; +export type ErrorObservationEvent = DiagnosticEventId | TelemetryEventName; + export type ErrorDefinition = Readonly<{ kind: Kind; defaultRetryable: boolean; severity: string; userMessageKey: string; action: ErrorAction; - telemetryEvent: string; + telemetryEvent: ErrorObservationEvent; redaction: readonly string[]; }>; @@ -32,7 +43,7 @@ const row = ( defaultRetryable: boolean, severity: string, action: ErrorAction, - telemetryEvent = "api.request.failed", + telemetryEvent: ErrorObservationEvent = "api.request.failed", ): ErrorDefinition => Object.freeze({ kind, @@ -214,7 +225,7 @@ export const ERROR_REGISTRY = Object.freeze({ false, "error", "retry", - "query.cache.failed", + "cache.operation.failed", ), UNKNOWN_FAILURE: row("UNKNOWN_FAILURE", false, "error", "contact-support"), }); @@ -226,8 +237,6 @@ export const ERROR_REGISTRY = Object.freeze({ */ export type FailureKind = keyof typeof ERROR_REGISTRY; -export type ValidationIssue = Readonly<{ path: string; code: string }>; - export type FailureEffectCertainty = | "NOT_APPLICABLE" | "NOT_STARTED" @@ -297,22 +306,7 @@ export function createFailure( : {}), ...(details.effect === undefined ? {} : { effect: details.effect }), ...(Array.isArray(details.validationIssues) - ? { - validationIssues: Object.freeze( - details.validationIssues - .filter( - (issue) => - issue && - typeof issue === "object" && - typeof issue.path === "string" && - typeof issue.code === "string", - ) - .slice(0, 50) - .map((issue) => - Object.freeze({ path: issue.path, code: issue.code }), - ), - ), - } + ? { validationIssues: projectValidationIssues(details.validationIssues) } : {}), ...(typeof details.causeClass === "string" ? { causeClass: details.causeClass } @@ -365,27 +359,7 @@ export function safeValidationIssues( : Array.isArray(candidate.fieldErrors) ? candidate.fieldErrors : []; - return Object.freeze( - issues - .filter( - (issue): issue is ValidationIssue => - issue && - typeof issue === "object" && - "path" in issue && - "code" in issue && - typeof issue.path === "string" && - typeof issue.code === "string" && - issue.path.length <= 120 && - issue.code.length <= 80, - ) - .slice(0, 50) - .map((issue) => - Object.freeze({ - path: issue.path, - code: issue.code, - }), - ), - ); + return projectValidationIssues(issues); } export function kindForStatus(status: number): FailureKind { diff --git a/src/contracts/external-contract-runtime.ts b/src/contracts/external-contract-runtime.ts index 7ed430c6..71b5b5a7 100644 --- a/src/contracts/external-contract-runtime.ts +++ b/src/contracts/external-contract-runtime.ts @@ -8,6 +8,11 @@ */ import { INSTALLED_REST_AUTH_PROFILES } from "./rest-profiles.ts"; +import { + defineTrafficBudget, + TRAFFIC_BUDGET_KEYS, + type TrafficBudget, +} from "../platform/traffic/traffic-budget.ts"; import { createReadOnlyRegistry, exactOwnDataSnapshot, @@ -129,6 +134,13 @@ export interface HttpExecutionPolicy { readonly retryBudget: 0 | 1 | 2; readonly authProfileId: string; readonly diagnosticsOperation: string; + /** + * Spec ยง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. + */ + readonly traffic?: TrafficBudget; } export interface InstalledHttpContract { @@ -353,6 +365,15 @@ function assertExecutionPolicy( ) { fail(`${label}: retryBudget must be 0, 1 or 2`); } + if (policy.traffic !== undefined) { + try { + defineTrafficBudget(policy.traffic); + } catch (error) { + fail( + `${label}: traffic policy ${error instanceof Error ? error.message : "invalid"}`, + ); + } + } } function assertHttpContract( @@ -511,6 +532,11 @@ const EXECUTION_POLICY_KEYS = [ "diagnosticsOperation", ] as const; +const EXECUTION_POLICY_ALLOWED_KEYS = [ + ...EXECUTION_POLICY_KEYS, + "traffic", +] as const; + const HTTP_CONTRACT_KEYS = [ "operationId", "method", @@ -554,12 +580,24 @@ function snapshotHttpContract( const row = exactOwnDataSnapshot< InstalledHttpContract >(installed, ["contract", "frontend"], ["contract", "frontend"], reject); - const frontend = exactOwnDataSnapshot( + const policy = exactOwnDataSnapshot( row.frontend, - EXECUTION_POLICY_KEYS, + EXECUTION_POLICY_ALLOWED_KEYS, EXECUTION_POLICY_KEYS, reject, ); + const frontend: HttpExecutionPolicy = + policy.traffic === undefined + ? policy + : Object.freeze({ + ...policy, + traffic: exactOwnDataSnapshot( + policy.traffic, + TRAFFIC_BUDGET_KEYS, + TRAFFIC_BUDGET_KEYS, + reject, + ), + }); const source = exactOwnDataSnapshot< InstalledHttpContract["contract"] >(row.contract, HTTP_CONTRACT_KEYS, HTTP_CONTRACT_KEYS, reject); diff --git a/src/contracts/product-features.ts b/src/contracts/product-features.ts index 6ab6192e..a6e5cd26 100644 --- a/src/contracts/product-features.ts +++ b/src/contracts/product-features.ts @@ -68,6 +68,7 @@ export function selectCompiledProductFeatures< ): readonly Feature[] { const compiledIds = compiled.map((feature) => feature.featureId); assertUniqueFeatureIds(compiledIds); + const compiledIdSet = new Set(compiledIds); if (declared === undefined || declared.trim() === "") { return Object.freeze([...compiled]); } @@ -83,7 +84,7 @@ export function selectCompiledProductFeatures< `unset to keep ${compiledIds.join(", ")}.`, ); } - const unknown = requested.filter((id) => !compiledIds.includes(id)); + const unknown = requested.filter((id) => !compiledIdSet.has(id)); if (unknown.length > 0) { throw new Error( `VITE_PRODUCT_FEATURES names features this build does not contain: ${unknown.join( @@ -91,8 +92,9 @@ export function selectCompiledProductFeatures< )}. Selection can only remove from ${compiledIds.join(", ")}.`, ); } + const requestedSet = new Set(requested); return Object.freeze( - compiled.filter((feature) => requested.includes(feature.featureId)), + compiled.filter((feature) => requestedSet.has(feature.featureId)), ); } @@ -111,11 +113,12 @@ export function resolveProductFeatures( overrides: ProductFeatureOverrideMap = {}, ): readonly ProductFeatureStatus[] { assertUniqueFeatureIds(compiledIds); + const installedIdSet = new Set(installedIds); return Object.freeze( [...compiledIds].sort().map((featureId) => Object.freeze({ featureId, - state: !installedIds.includes(featureId) + state: !installedIdSet.has(featureId) ? ("NOT_INSTALLED" as const) : overrides[featureId] === "DISABLED" ? ("DISABLED_BY_CONFIG" as const) diff --git a/src/contracts/schema-registry.ts b/src/contracts/schema-registry.ts index ceeff372..2ce68194 100644 --- a/src/contracts/schema-registry.ts +++ b/src/contracts/schema-registry.ts @@ -1,3 +1,5 @@ +import { projectValidationIssues } from "./validation-issues.ts"; + export type SchemaDefinition = Readonly<{ schemaId: string; boundary: @@ -60,7 +62,12 @@ export function validateWithRuntimeSchemaRegistry( }); } try { - return codec.parse(value); + const result = codec.parse(value); + if (result.success) return result; + return Object.freeze({ + success: false, + issues: projectValidationIssues(result.issues), + }); } catch { return Object.freeze({ success: false, diff --git a/src/contracts/storage-keys.ts b/src/contracts/storage-keys.ts index bb726c12..e2be748e 100644 --- a/src/contracts/storage-keys.ts +++ b/src/contracts/storage-keys.ts @@ -57,6 +57,23 @@ export const STORAGE_REGISTRY = Object.freeze({ migration: "discard", quotaFallback: "no-persist", }), + /** + * Spec ยง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. + */ + RELEASE_MISMATCH_RECOVERY: defineStorageKey({ + logicalName: "RELEASE_MISMATCH_RECOVERY", + scope: "release", + name: "boot-mismatch-recovery", + backend: "sessionStorage", + classification: "opaque-cache", + schemaVersion: 1, + valueCodec: "opaque-string-v1", + ttl: "session", + migration: "discard", + quotaFallback: "no-persist", + }), QUERY_PERSISTENCE: defineStorageKey({ logicalName: "QUERY_PERSISTENCE", scope: "cache", diff --git a/src/contracts/validation-issues.ts b/src/contracts/validation-issues.ts new file mode 100644 index 00000000..29d79c96 --- /dev/null +++ b/src/contracts/validation-issues.ts @@ -0,0 +1,56 @@ +export const MAX_VALIDATION_ISSUES = 50; +export const MAX_VALIDATION_ISSUE_CANDIDATES = 200; +export const MAX_VALIDATION_PATH_LENGTH = 120; +export const MAX_VALIDATION_CODE_LENGTH = 80; + +export type ValidationIssue = Readonly<{ + path: string; + code: string; +}>; + +function normalizePath(value: unknown): string | null { + if (typeof value === "string") return value; + if (!Array.isArray(value)) return null; + try { + return value.map((segment) => String(segment)).join("."); + } catch { + return null; + } +} + +/** + * Projects validation metadata into a fixed-size, copy-only representation. + * Invalid entries are skipped, and candidate scanning is itself bounded so a + * hostile issue array cannot turn failure handling into unbounded work. + */ +export function projectValidationIssues(value: unknown): readonly ValidationIssue[] { + if (!Array.isArray(value)) return Object.freeze([]); + + const projected: ValidationIssue[] = []; + const candidateCount = Math.min( + value.length, + MAX_VALIDATION_ISSUE_CANDIDATES, + ); + for (let index = 0; index < candidateCount; index += 1) { + if (projected.length >= MAX_VALIDATION_ISSUES) break; + try { + const candidate = value[index]; + if (!candidate || typeof candidate !== "object") continue; + const record = candidate as Readonly>; + const path = normalizePath(record.path); + const code = record.code; + if ( + path === null || + typeof code !== "string" || + path.length > MAX_VALIDATION_PATH_LENGTH || + code.length > MAX_VALIDATION_CODE_LENGTH + ) { + continue; + } + projected.push(Object.freeze({ path, code })); + } catch { + continue; + } + } + return Object.freeze(projected); +} diff --git a/src/features/feature-adapter-contribution.ts b/src/features/feature-adapter-contribution.ts index 46cdafc2..6e657e9d 100644 --- a/src/features/feature-adapter-contribution.ts +++ b/src/features/feature-adapter-contribution.ts @@ -5,6 +5,7 @@ import type { import type { InstalledHttpOperationExecutor, } from "../adapters/http/index.ts"; +import type { TelemetryPort } from "../platform/telemetry/telemetry-port.ts"; /** * Features augment this registry with the repository identities they consume. @@ -45,6 +46,8 @@ export function createIndexedDbRepositoryProvider( export type FeaturePlatformCapabilities = Readonly<{ http: InstalledHttpOperationExecutor; indexedDb: IndexedDbRepositoryProvider; + /** Spec ยง24. Provider-neutral, bounded, fail-open feature telemetry. */ + telemetry: TelemetryPort; }>; export type FeaturePlatformCapabilityId = diff --git a/src/features/feature-module.ts b/src/features/feature-module.ts new file mode 100644 index 00000000..4f944742 --- /dev/null +++ b/src/features/feature-module.ts @@ -0,0 +1,86 @@ +export type FeatureContractIdentity = Readonly<{ featureId: string }>; + +type EmptyRecord = Readonly>; + +/** + * Zero-feature products are a supported topology. The fallback contract keeps + * every composer's property access valid without pretending that any feature + * route, operation, schema, mapper, or invalidation edge exists. + */ +export type EmptyFeatureContract = FeatureContractIdentity & + Readonly<{ + routes: EmptyRecord; + routeRuntimeContracts: EmptyRecord; + apiOperations: EmptyRecord; + invalidation: Readonly<{ + topics: readonly []; + namespaces: readonly []; + edges: readonly []; + }>; + topicVersions: readonly []; + schemas: EmptyRecord; + runtimeSchemas: EmptyRecord; + mappers: EmptyRecord; + }>; + +export type FeatureMessageCatalogs = Readonly< + Record>> +>; + +type EmptyFeatureMessageCatalogs = Readonly< + Record>> +>; + +type EmptyFeatureRuntimeDescriptor = Readonly<{ + featureId: string; + routeCodecs: EmptyRecord; + routeRuntime: EmptyRecord; +}>; + +/** + * The default parameters deliberately describe the empty-product fallback. + * Concrete generated modules retain their literal types; only an empty + * generated tuple resolves to this default shape. + */ +export type FeatureModule< + Contract extends FeatureContractIdentity = EmptyFeatureContract, + Routes extends Readonly> = EmptyRecord, + Adapter = never, + Runtime = EmptyFeatureRuntimeDescriptor, + Messages extends FeatureMessageCatalogs = EmptyFeatureMessageCatalogs, + ContractContribution = never, +> = Readonly<{ + id: string; + contracts: Contract; + routes: Routes; + adapters: readonly Adapter[]; + runtimes: readonly Runtime[]; + messages: Messages; + contractContributions: readonly ContractContribution[]; +}>; + +/** Structural supertype used when accepting any concrete feature descriptor. */ +export type AnyFeatureModule = FeatureModule< + FeatureContractIdentity, + Readonly>, + unknown, + unknown, + FeatureMessageCatalogs, + unknown +>; + +export function defineFeatureModule( + module: Module, +): Readonly { + if (module.id !== module.contracts.featureId) { + throw new TypeError( + `Feature module id ${module.id} does not match contract featureId ${module.contracts.featureId}`, + ); + } + return Object.freeze({ + ...module, + adapters: Object.freeze([...module.adapters]), + runtimes: Object.freeze([...module.runtimes]), + contractContributions: Object.freeze([...module.contractContributions]), + }) as unknown as Readonly; +} diff --git a/src/features/installed-contract-contributions.ts b/src/features/installed-contract-contributions.ts index 5c3d44c1..029a5451 100644 --- a/src/features/installed-contract-contributions.ts +++ b/src/features/installed-contract-contributions.ts @@ -3,24 +3,12 @@ import { type InstalledContractContribution, type InstalledContractPackageIdentity, } from "../contracts/external-contract-runtime.ts"; -import { INSTALLED_PRODUCT_FEATURE_IDS } from "./installed-product-manifest.ts"; -import { REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION } from "./reference-feature/contracts/reference-feature-contract-contribution.ts"; +import { INSTALLED_PRODUCT_FEATURE_MODULES } from "./installed-product-manifest.ts"; -const COMPILED_CONTRACT_CONTRIBUTIONS = Object.freeze([ - REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION, -] as const); - -/** - * Central contract installation is aggregation only. - * - * Each feature owns its concrete service/package contribution. This catalog - * selects contributions whose feature is installed; it does not contain - * feature-specific branching or service wiring. - */ export const INSTALLED_CONTRACT_CONTRIBUTIONS: readonly InstalledContractContribution[] = Object.freeze( - COMPILED_CONTRACT_CONTRIBUTIONS.filter((contribution) => - INSTALLED_PRODUCT_FEATURE_IDS.includes(contribution.featureId), + INSTALLED_PRODUCT_FEATURE_MODULES.flatMap( + (module) => module.contractContributions, ), ); @@ -28,9 +16,5 @@ export const COMPOSED_CONTRACT_CONTRIBUTIONS = composeContractContributions( INSTALLED_CONTRACT_CONTRIBUTIONS, ); -/** - * ยง5.4. `TEMPLATE_FIXTURE` provenance is filtered out before the contract set - * is canonicalized, so a fixture can never influence the release digest. - */ export const EXPECTED_CONTRACT_SET_PACKAGES: readonly InstalledContractPackageIdentity[] = COMPOSED_CONTRACT_CONTRIBUTIONS.externalPackages; diff --git a/src/features/installed-feature-adapters.ts b/src/features/installed-feature-adapters.ts index 303941e3..165f38ec 100644 --- a/src/features/installed-feature-adapters.ts +++ b/src/features/installed-feature-adapters.ts @@ -3,29 +3,26 @@ import { type ContributionsCapabilityContext, type InstalledFeatureInputs, } from "./feature-adapter-contribution.ts"; -import { REFERENCE_FEATURE_ADAPTER_CONTRIBUTION } from "./reference-feature/adapters/create-reference-feature-input.ts"; -import { INSTALLED_PRODUCT_FEATURE_IDS } from "./installed-product-manifest.ts"; +import { INSTALLED_PRODUCT_FEATURE_MODULES } from "./installed-product-manifest.ts"; -const COMPILED_FEATURE_ADAPTER_CONTRIBUTIONS = Object.freeze([ - REFERENCE_FEATURE_ADAPTER_CONTRIBUTION, -] as const); +const INSTALLED_FEATURE_ADAPTER_CONTRIBUTIONS = Object.freeze( + INSTALLED_PRODUCT_FEATURE_MODULES.flatMap((module) => module.adapters), +); -type InstalledFeatureCapabilityContext = - ContributionsCapabilityContext< - typeof COMPILED_FEATURE_ADAPTER_CONTRIBUTIONS - >; +type InstalledFeatureCapabilityContext = ContributionsCapabilityContext< + typeof INSTALLED_FEATURE_ADAPTER_CONTRIBUTIONS +>; /** - * Central adapter composition only selects and aggregates feature-owned - * contributions. The feature owns how its application input is bound to the - * reusable platform capabilities declared by its `needs` list. + * Adapter installation is a projection of feature-owned descriptors. Adding a + * feature changes its descriptor and the generated index, not this composer. */ export function createInstalledFeatureInputs( context: InstalledFeatureCapabilityContext, ): InstalledFeatureInputs { return composeFeatureAdapterInputs( - COMPILED_FEATURE_ADAPTER_CONTRIBUTIONS, - INSTALLED_PRODUCT_FEATURE_IDS, + INSTALLED_FEATURE_ADAPTER_CONTRIBUTIONS, + INSTALLED_PRODUCT_FEATURE_MODULES.map((module) => module.id), context, ); } diff --git a/src/features/installed-feature-contracts.ts b/src/features/installed-feature-contracts.ts index 767a2705..2ec8c8a0 100644 --- a/src/features/installed-feature-contracts.ts +++ b/src/features/installed-feature-contracts.ts @@ -1,41 +1,42 @@ -import { PLATFORM_ROUTE_RUNTIME_CONTRACT } from "../contracts/route-runtime-contract.ts"; -import { PLATFORM_ROUTE_REGISTRY } from "../contracts/routes.ts"; -import { - composeSchemaRegistry, - PLATFORM_SCHEMA_REGISTRY, -} from "../contracts/schema-registry.ts"; -import { - INSTALLED_PRODUCT_FEATURES, -} from "./installed-product-manifest.ts"; import { composeApiOperations, validateApiRuntimeBindings, } from "../contracts/api-operations.ts"; -import { validateRestProfileBindings } from "../contracts/rest-profiles.ts"; -import { composeRuntimeSchemaCodecs } from "../contracts/schema-registry.ts"; import { composeBoundaryMapperRegistry } from "../contracts/boundary-mapper.ts"; +import { PLATFORM_ROUTE_RUNTIME_CONTRACT } from "../contracts/route-runtime-contract.ts"; +import { validateRestProfileBindings } from "../contracts/rest-profiles.ts"; +import { PLATFORM_ROUTE_REGISTRY } from "../contracts/routes.ts"; +import { + composeRuntimeSchemaCodecs, + composeSchemaRegistry, + PLATFORM_SCHEMA_REGISTRY, +} from "../contracts/schema-registry.ts"; +import { composeUniqueRecord } from "../platform/cardinality/compose-unique-record.ts"; +import { INSTALLED_PRODUCT_FEATURES } from "./installed-product-manifest.ts"; -/** - * ยง3.5. Composed from the product manifest rather than from a literal list, so - * a feature the build did not select contributes no routes, no operations, no - * schemas and no messages โ€” and is therefore not reachable from any registry. - */ export const INSTALLED_FEATURE_CONTRACTS = INSTALLED_PRODUCT_FEATURES; -export const ROUTE_REGISTRY = Object.freeze( - INSTALLED_FEATURE_CONTRACTS.reduce( - (registry, contract) => ({ ...registry, ...contract.routes }), - { ...PLATFORM_ROUTE_REGISTRY }, - ), -) as typeof PLATFORM_ROUTE_REGISTRY & - (typeof INSTALLED_PRODUCT_FEATURES)[number]["routes"]; -export const ROUTE_RUNTIME_CONTRACT = Object.freeze( - INSTALLED_FEATURE_CONTRACTS.reduce( - (registry, contract) => ({ ...registry, ...contract.routeRuntimeContracts }), - { ...PLATFORM_ROUTE_RUNTIME_CONTRACT }, - ), +type InstalledFeatureContract = (typeof INSTALLED_FEATURE_CONTRACTS)[number]; + +export const ROUTE_REGISTRY = composeUniqueRecord( + [ + PLATFORM_ROUTE_REGISTRY, + ...INSTALLED_FEATURE_CONTRACTS.map((contract) => contract.routes), + ], + () => "route registry", +) as typeof PLATFORM_ROUTE_REGISTRY & InstalledFeatureContract["routes"]; + +export const ROUTE_RUNTIME_CONTRACT = composeUniqueRecord( + [ + PLATFORM_ROUTE_RUNTIME_CONTRACT, + ...INSTALLED_FEATURE_CONTRACTS.map( + (contract) => contract.routeRuntimeContracts, + ), + ], + () => "route runtime contract", ) as typeof PLATFORM_ROUTE_RUNTIME_CONTRACT & - (typeof INSTALLED_PRODUCT_FEATURES)[number]["routeRuntimeContracts"]; + InstalledFeatureContract["routeRuntimeContracts"]; + export const API_OPERATIONS = composeApiOperations( INSTALLED_FEATURE_CONTRACTS.map((contract) => contract.apiOperations), ); @@ -80,13 +81,6 @@ export const API_RUNTIME_BINDINGS_VALID = validateApiRuntimeBindings( MAPPER_REGISTRY, ); -/** - * ยง3.5. Which feature owns each route. - * - * A route contributed by a feature disappears with it at build time, and has to - * be withdrawn from navigation and from the router when the runtime document - * disables that feature. Platform routes have no owner and are always present. - */ export const ROUTE_FEATURE_OWNER: Readonly> = Object.freeze( Object.fromEntries( diff --git a/src/features/installed-feature-messages.ts b/src/features/installed-feature-messages.ts index 50b80b14..b6aa5763 100644 --- a/src/features/installed-feature-messages.ts +++ b/src/features/installed-feature-messages.ts @@ -1,16 +1,38 @@ -import { REFERENCE_MESSAGE_CATALOGS } from "./reference-feature/contracts/reference-message-catalog.ts"; -/** - * ยง3.5. Messages are deliberately *not* gated on the manifest. The catalog's - * key type is what makes `message()` total, so dropping keys would turn every - * lookup partial for the sake of a few unreachable strings. - */ -const reference = REFERENCE_MESSAGE_CATALOGS; +import { INSTALLED_PRODUCT_FEATURE_MODULES } from "./installed-product-manifest.ts"; + +type InstalledModule = (typeof INSTALLED_PRODUCT_FEATURE_MODULES)[number]; +type UnionToIntersection = ( + Union extends unknown ? (value: Union) => void : never +) extends (value: infer Intersection) => void + ? Intersection + : never; +type LocaleCatalog = UnionToIntersection< + InstalledModule extends unknown + ? InstalledModule["messages"] extends Readonly> + ? Catalog + : Readonly> + : never +>; + +function composeLocale(locale: Locale): LocaleCatalog { + const result: Record = {}; + for (const module of INSTALLED_PRODUCT_FEATURE_MODULES) { + const catalogs = module.messages as Readonly< + Record>> + >; + const catalog = catalogs[locale]; + if (!catalog) continue; + for (const [key, value] of Object.entries(catalog)) { + if (Object.hasOwn(result, key)) { + throw new TypeError(`Duplicate ${locale} message key: ${key}`); + } + result[key] = value; + } + } + return Object.freeze(result) as LocaleCatalog; +} export const INSTALLED_MESSAGE_CATALOGS = Object.freeze({ - "ko-KR": Object.freeze({ - ...reference["ko-KR"], - }), - "en-US": Object.freeze({ - ...reference["en-US"], - }), + "ko-KR": composeLocale("ko-KR"), + "en-US": composeLocale("en-US"), } as const); diff --git a/src/features/installed-feature-runtimes.tsx b/src/features/installed-feature-runtimes.tsx index dc53a8c7..5195e6c4 100644 --- a/src/features/installed-feature-runtimes.tsx +++ b/src/features/installed-feature-runtimes.tsx @@ -1,38 +1,28 @@ +import { composeUniqueRecord } from "../platform/cardinality/compose-unique-record.ts"; import { PLATFORM_ROUTE_CODECS } from "../presentation/routes/platform-route-codecs.ts"; import { PLATFORM_ROUTE_RUNTIME } from "../presentation/routes/route-runtime.tsx"; -import { REFERENCE_FEATURE_RUNTIME_CONTRIBUTION } from "./reference-feature/presentation/reference-feature-runtime.tsx"; -import { INSTALLED_PRODUCT_FEATURE_IDS } from "./installed-product-manifest.ts"; +import { INSTALLED_PRODUCT_FEATURE_MODULES } from "./installed-product-manifest.ts"; -const COMPILED_FEATURE_RUNTIME_CONTRIBUTIONS = Object.freeze([ - REFERENCE_FEATURE_RUNTIME_CONTRIBUTION, -] as const); +const INSTALLED_FEATURE_RUNTIME_CONTRIBUTIONS = Object.freeze( + INSTALLED_PRODUCT_FEATURE_MODULES.flatMap((module) => module.runtimes), +); -const INSTALLED_FEATURE_RUNTIME_CONTRIBUTIONS = - COMPILED_FEATURE_RUNTIME_CONTRIBUTIONS.filter((contribution) => - INSTALLED_PRODUCT_FEATURE_IDS.includes(contribution.featureId), - ); - -/** - * Central runtime catalogs only aggregate feature-owned contributions. - * Adding route codecs/components to a feature no longer requires duplicating - * reference-specific selection logic in this composition file. - */ -export const ROUTE_CODECS = Object.freeze( - Object.assign( - {}, +export const ROUTE_CODECS = composeUniqueRecord( + [ PLATFORM_ROUTE_CODECS, ...INSTALLED_FEATURE_RUNTIME_CONTRIBUTIONS.map( (contribution) => contribution.routeCodecs, ), - ), + ], + () => "route codec", ); -export const ROUTE_RUNTIME = Object.freeze( - Object.assign( - {}, +export const ROUTE_RUNTIME = composeUniqueRecord( + [ PLATFORM_ROUTE_RUNTIME, ...INSTALLED_FEATURE_RUNTIME_CONTRIBUTIONS.map( (contribution) => contribution.routeRuntime, ), - ), + ], + () => "route runtime", ); diff --git a/src/features/installed-product-manifest.ts b/src/features/installed-product-manifest.ts index 842f4c0a..22f79029 100644 --- a/src/features/installed-product-manifest.ts +++ b/src/features/installed-product-manifest.ts @@ -1,49 +1,24 @@ +import { + PRODUCT_FEATURE_MODULES, + type ProductFeatureModule, +} from "../.generated/product-feature-index.ts"; import { selectCompiledProductFeatures, type SelectableProductFeature, } from "../contracts/product-features.ts"; -import { REFERENCE_FEATURE_CONTRACT } from "./reference-feature/contracts/reference-feature-contract.ts"; /** - * ยง3.5. The product manifest: the single declaration of which features this - * build contains. - * - * Before this file the reference feature was spread directly into the route, - * API, schema and message registries, so the only way to ship without it was to - * edit five registries by hand and hope nothing still referred to it. The - * removability gate proved that editing worked; nothing made it a decision you - * could express. - * - * Adding an entry here is what installs a feature. `VITE_PRODUCT_FEATURES` may - * then narrow the list at build time โ€” a comma-separated subset, `none` for an - * empty selection, absent meaning "all of them". A narrowed-out feature reaches - * no registry, so it is not routed, not navigable and not callable. - * - * It is not deleted. The import above is static, and a value cannot undo a - * static import; making the import itself conditional on configuration is the - * thing ยง3.5 exists to prevent. FE-GATE-020 is what proves the feature can be - * physically removed, by removing it and rebuilding the whole project. + * Product installation has one generated static source of truth. Feature-owned + * descriptors are discovered at build time; runtime configuration can only + * subtract from that compiled set. */ +export const COMPILED_PRODUCT_FEATURE_MODULES: readonly ProductFeatureModule[] = + PRODUCT_FEATURE_MODULES; -const COMPILED_PRODUCT_FEATURES = Object.freeze([ - REFERENCE_FEATURE_CONTRACT, -] as const); - -/** - * Every feature this source tree declares, selected or not. The platform - * overview reports on this set so an operator can tell a feature that was built - * out from one that never existed. - */ export const COMPILED_PRODUCT_FEATURE_IDS: readonly string[] = Object.freeze( - COMPILED_PRODUCT_FEATURES.map((feature) => feature.featureId), + COMPILED_PRODUCT_FEATURE_MODULES.map((feature) => feature.id), ); -/** - * `import.meta.env` exists in a Vite build and not under Node, and this module - * is read by release scripts as well as by the app. A missing environment means - * "nothing was narrowed", which is the same answer a plain developer build - * gives. - */ function declaredFeatureSelection(): string | undefined { const environment = ( import.meta as unknown as { @@ -53,11 +28,35 @@ function declaredFeatureSelection(): string | undefined { return environment?.["VITE_PRODUCT_FEATURES"]; } -export const INSTALLED_PRODUCT_FEATURES = selectCompiledProductFeatures( - COMPILED_PRODUCT_FEATURES as readonly SelectableProductFeature[], +type CompiledFeatureModule = ProductFeatureModule; +type CompiledFeatureContract = CompiledFeatureModule["contracts"]; +type SelectableFeatureModule = SelectableProductFeature & + Readonly<{ module: CompiledFeatureModule }>; + +const SELECTABLE_PRODUCT_FEATURE_MODULES: readonly SelectableFeatureModule[] = + Object.freeze( + COMPILED_PRODUCT_FEATURE_MODULES.map((module) => + Object.freeze({ featureId: module.id, module }), + ), + ); + +const INSTALLED_SELECTION = selectCompiledProductFeatures( + SELECTABLE_PRODUCT_FEATURE_MODULES, declaredFeatureSelection(), -) as readonly (typeof COMPILED_PRODUCT_FEATURES)[number][]; +); + +export const INSTALLED_PRODUCT_FEATURE_MODULES: readonly CompiledFeatureModule[] = + Object.freeze(INSTALLED_SELECTION.map((entry) => entry.module)); + +/** Backward-compatible projection consumed by the existing contract composer. */ +export const INSTALLED_PRODUCT_FEATURES: readonly CompiledFeatureContract[] = + Object.freeze( + INSTALLED_PRODUCT_FEATURE_MODULES.map((module) => module.contracts), + ); export const INSTALLED_PRODUCT_FEATURE_IDS: readonly string[] = Object.freeze( - INSTALLED_PRODUCT_FEATURES.map((feature) => feature.featureId), + INSTALLED_PRODUCT_FEATURE_MODULES.map((feature) => feature.id), ); + +export const INSTALLED_PRODUCT_FEATURE_ID_SET: ReadonlySet = + new Set(INSTALLED_PRODUCT_FEATURE_IDS); diff --git a/src/features/reference-feature/adapters/create-reference-feature-input.ts b/src/features/reference-feature/adapters/create-reference-feature-input.ts index 536d7126..86621440 100644 --- a/src/features/reference-feature/adapters/create-reference-feature-input.ts +++ b/src/features/reference-feature/adapters/create-reference-feature-input.ts @@ -6,6 +6,7 @@ import { defineFeatureAdapterContribution, } from "../../feature-adapter-contribution.ts"; import { createReferenceFeatureInput } from "../application/reference-feature-api.ts"; +import type { TelemetryPort } from "../../../platform/telemetry/telemetry-port.ts"; import { REFERENCE_FEATURE_ID, } from "../contracts/reference-feature-contract.ts"; @@ -25,6 +26,7 @@ export type InstalledContractOperationExecutor = */ export function createReferenceFeatureInstalledInput(context: Readonly<{ http: InstalledHttpOperationExecutor; + telemetry?: TelemetryPort; }>) { const http = createFeatureHttpBinding( context.http, @@ -33,13 +35,16 @@ export function createReferenceFeatureInstalledInput(context: Readonly<{ return Object.freeze({ featureId: REFERENCE_FEATURE_ID, - input: createReferenceFeatureInput(createReferenceHttpGateway(http)), + input: createReferenceFeatureInput( + createReferenceHttpGateway(http), + context.telemetry === undefined ? {} : { telemetry: context.telemetry }, + ), }); } export const REFERENCE_FEATURE_ADAPTER_CONTRIBUTION = defineFeatureAdapterContribution({ featureId: REFERENCE_FEATURE_ID, - needs: ["http"] as const, + needs: ["http", "telemetry"] as const, createInput: createReferenceFeatureInstalledInput, }); diff --git a/src/features/reference-feature/application/reference-error.ts b/src/features/reference-feature/application/reference-error.ts new file mode 100644 index 00000000..7a84685b --- /dev/null +++ b/src/features/reference-feature/application/reference-error.ts @@ -0,0 +1,71 @@ +import { + defineAppError, + type AppError, +} from "../../../platform/errors/app-error.ts"; +import type { ApiFailure } from "../../../contracts/errors.ts"; + +/** + * Spec ยง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 + * this feature never edits a shared error type. + */ +export type ReferenceError = + | (AppError & { + readonly kind: "reference.not-found"; + readonly category: "domain"; + readonly severity: "warning"; + readonly retryability: "never"; + }) + | (AppError & { + readonly kind: "reference.conflict"; + readonly category: "domain"; + readonly severity: "warning"; + readonly retryability: "never"; + }) + | (AppError & { + readonly kind: "reference.rejected"; + readonly category: "validation"; + readonly severity: "warning"; + readonly retryability: "never"; + }); + +export const REFERENCE_ERRORS = Object.freeze({ + NOT_FOUND: defineAppError({ + kind: "reference.not-found", + category: "domain", + severity: "warning", + retryability: "never", + }), + CONFLICT: defineAppError({ + kind: "reference.conflict", + category: "domain", + severity: "warning", + retryability: "never", + }), + REJECTED: defineAppError({ + kind: "reference.rejected", + category: "validation", + severity: "warning", + retryability: "never", + }), +} satisfies Record); + +/** + * Interprets a transport-normalized failure in this feature's own vocabulary. + * Anything that is not a reference domain outcome stays `null`: the platform + * error mapping, not this feature, owns transport/contract failures. + */ +export function toReferenceError(failure: ApiFailure): ReferenceError | null { + switch (failure.kind) { + case "NOT_FOUND": + return REFERENCE_ERRORS.NOT_FOUND; + case "CONFLICT": + return REFERENCE_ERRORS.CONFLICT; + case "VALIDATION_REJECTED": + return REFERENCE_ERRORS.REJECTED; + default: + return null; + } +} diff --git a/src/features/reference-feature/application/reference-feature-api.ts b/src/features/reference-feature/application/reference-feature-api.ts index 9ea8f216..eadce0fa 100644 --- a/src/features/reference-feature/application/reference-feature-api.ts +++ b/src/features/reference-feature/application/reference-feature-api.ts @@ -6,6 +6,19 @@ import { } from "../contracts/reference-mapper.ts"; import type { ReferenceResource } from "../domain/reference-resource.ts"; import type { MutationIntent } from "../../../contracts/mutation-intent.ts"; +import type { ExecutionContext } from "../../../platform/execution/execution-context.ts"; +import type { TelemetryPort } from "../../../platform/telemetry/telemetry-port.ts"; +import type { ApiFailure } 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 + * operations share one request/retry/concurrency budget and one deadline. + */ +export type ReferenceCallContext = Readonly<{ + signal?: AbortSignal; + execution?: ExecutionContext; +}>; export type ReferenceListFilters = Readonly<{ cursor?: string; @@ -23,18 +36,15 @@ export type ReferenceCreateCommand = Readonly<{ export type ReferenceFeatureInput = Readonly<{ listResources( filters: ReferenceListFilters, - context?: Readonly<{ signal?: AbortSignal }>, + context?: ReferenceCallContext, ): Promise>; createResource( command: ReferenceCreateCommand, - context?: Readonly<{ - signal?: AbortSignal; - intent?: MutationIntent; - }>, + context?: ReferenceCallContext & Readonly<{ intent?: MutationIntent }>, ): Promise>; getResource( resourceId: string, - context?: Readonly<{ signal?: AbortSignal }>, + context?: ReferenceCallContext, ): Promise>; }>; @@ -47,27 +57,62 @@ declare module "../../../application/ports/in/application-api.ts" { export type ReferenceGateway = Readonly<{ list( filters: ReferenceListFilters, - context?: Readonly<{ signal?: AbortSignal }>, + context?: ReferenceCallContext, ): Promise>; create( command: ReferenceCreateCommand, - context?: Readonly<{ - signal?: AbortSignal; - intent?: MutationIntent; - }>, + context?: ReferenceCallContext & Readonly<{ intent?: MutationIntent }>, ): Promise>; get( resourceId: string, - context?: Readonly<{ signal?: AbortSignal }>, + context?: ReferenceCallContext, ): Promise>; }>; +/** + * Spec ยง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<{ + operation: "list" | "detail"; + reason: ApiFailure["kind"]; +}>; + +function reportLoadFailure( + telemetry: TelemetryPort | undefined, + operation: ReferenceLoadFailedPayload["operation"], + failure: ApiFailure, + context: ReferenceCallContext | undefined, +): void { + if (!telemetry || failure.kind === "REQUEST_ABORTED") return; + const payload: ReferenceLoadFailedPayload = { operation, reason: failure.kind }; + try { + // Fire-and-forget: telemetry never changes the business result. + void Promise.resolve( + telemetry.emit({ + kind: "reference.load.failed", + severity: "warning", + featureId: REFERENCE_FEATURE_ID, + ...(context?.execution === undefined + ? {} + : { interactionId: context.execution.interaction.id }), + payload, + }), + ).catch(() => undefined); + } catch { + // A throwing port is contained at the call site (spec ยง26). + } +} + export function createReferenceFeatureInput( gateway: ReferenceGateway, + observability: Readonly<{ telemetry?: TelemetryPort }> = {}, ): ReferenceFeatureInput { + const { telemetry } = observability; return Object.freeze({ async listResources(filters, context) { const result = await gateway.list(filters, context); + if (!result.ok) reportLoadFailure(telemetry, "list", result.error, context); return result.ok ? { ok: true as const, @@ -83,6 +128,7 @@ export function createReferenceFeatureInput( }, async getResource(resourceId, context) { const result = await gateway.get(resourceId, context); + if (!result.ok) reportLoadFailure(telemetry, "detail", result.error, context); return result.ok ? { ok: true as const, value: toReferenceView(result.value) } : result; diff --git a/src/features/reference-feature/context-routes.ts b/src/features/reference-feature/context-routes.ts new file mode 100644 index 00000000..d00f812b --- /dev/null +++ b/src/features/reference-feature/context-routes.ts @@ -0,0 +1,20 @@ +import type { RouteObject } from "react-router-dom"; + +import { REFERENCE_FEATURE_CONTRACT } from "./contracts/reference-feature-contract.ts"; +import { REFERENCE_FEATURE_ROUTE_RUNTIME } from "./presentation/reference-feature-runtime.ts"; + +export const FEATURE_CONTEXT_ROUTES: readonly RouteObject[] = Object.freeze( + Object.values(REFERENCE_FEATURE_CONTRACT.routes).map((definition) => { + const runtime = REFERENCE_FEATURE_ROUTE_RUNTIME[ + definition.routeId as keyof typeof REFERENCE_FEATURE_ROUTE_RUNTIME + ]; + return Object.freeze({ + id: definition.routeId, + path: definition.path, + handle: Object.freeze({ + routeId: definition.routeId, + runtime, + }), + }); + }), +); diff --git a/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts b/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts index 6688829e..48003b2a 100644 --- a/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts +++ b/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts @@ -120,6 +120,12 @@ export const LIST_REFERENCE_RESOURCES_CONTRACT = Object.freeze({ retryBudget: 2 as const, authProfileId: "REFERENCE_EXTERNAL_BEARER", diagnosticsOperation: "reference.list", + traffic: Object.freeze({ + maxPhysicalRequests: 3, + maxRetries: 2, + maxConcurrentRequests: 1, + maxQueuedRequests: 0, + }), }), }) satisfies InstalledHttpContract< z.output, @@ -164,6 +170,12 @@ export const GET_REFERENCE_RESOURCE_CONTRACT = Object.freeze({ retryBudget: 2 as const, authProfileId: "REFERENCE_EXTERNAL_BEARER", diagnosticsOperation: "reference.detail", + traffic: Object.freeze({ + maxPhysicalRequests: 3, + maxRetries: 2, + maxConcurrentRequests: 1, + maxQueuedRequests: 0, + }), }), }) satisfies InstalledHttpContract< z.output, @@ -216,6 +228,12 @@ export const CREATE_REFERENCE_RESOURCE_CONTRACT = Object.freeze({ retryBudget: 0 as const, authProfileId: "REFERENCE_EXTERNAL_BEARER", diagnosticsOperation: "reference.create", + traffic: Object.freeze({ + maxPhysicalRequests: 1, + maxRetries: 0, + maxConcurrentRequests: 1, + maxQueuedRequests: 0, + }), }), }) satisfies InstalledHttpContract< z.output, diff --git a/src/features/reference-feature/feature-module.ts b/src/features/reference-feature/feature-module.ts new file mode 100644 index 00000000..daebe2da --- /dev/null +++ b/src/features/reference-feature/feature-module.ts @@ -0,0 +1,26 @@ +import { defineFeatureModule } from "../feature-module.ts"; +import { REFERENCE_FEATURE_ADAPTER_CONTRIBUTION } from "./adapters/create-reference-feature-input.ts"; +import { + REFERENCE_FEATURE_CONTRACT, + REFERENCE_FEATURE_ID, +} from "./contracts/reference-feature-contract.ts"; +import { REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION } from "./contracts/reference-feature-contract-contribution.ts"; +import { REFERENCE_MESSAGE_CATALOGS } from "./contracts/reference-message-catalog.ts"; +import { REFERENCE_FEATURE_RUNTIME_DESCRIPTOR } from "./presentation/reference-feature-runtime-descriptor.ts"; + +export const FEATURE_MODULE_ID = + "reference-feature" satisfies typeof REFERENCE_FEATURE_ID; +/** Owning bounded context (route root and budget live in its declaration). */ +export const FEATURE_CONTEXT_ID = "reference-context"; + +export const REFERENCE_FEATURE_MODULE = defineFeatureModule({ + id: FEATURE_MODULE_ID, + contracts: REFERENCE_FEATURE_CONTRACT, + routes: REFERENCE_FEATURE_CONTRACT.routes, + adapters: [REFERENCE_FEATURE_ADAPTER_CONTRIBUTION], + runtimes: [REFERENCE_FEATURE_RUNTIME_DESCRIPTOR], + messages: REFERENCE_MESSAGE_CATALOGS, + contractContributions: [REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION], +} as const); + +export const FEATURE_MODULE = REFERENCE_FEATURE_MODULE; diff --git a/src/features/reference-feature/presentation/reference-feature-runtime-descriptor.ts b/src/features/reference-feature/presentation/reference-feature-runtime-descriptor.ts new file mode 100644 index 00000000..ea240867 --- /dev/null +++ b/src/features/reference-feature/presentation/reference-feature-runtime-descriptor.ts @@ -0,0 +1,21 @@ +import { REFERENCE_FEATURE_ID } from "../contracts/reference-feature-contract.ts"; +import { + referenceResourceListQuerySchema, + referenceResourceParamsSchema, +} from "../contracts/reference-schemas.ts"; + +export const REFERENCE_FEATURE_ROUTE_CODECS = { + ReferenceResourceListQuery: referenceResourceListQuerySchema, + ReferenceResourceParams: referenceResourceParamsSchema, +} as const; + +/** + * Boot-safe feature runtime metadata. Page components are deliberately absent: + * executable route chunks are owned and loaded by the bounded context route + * module, so Node-side composition and app boot do not pull the page graph in. + */ +export const REFERENCE_FEATURE_RUNTIME_DESCRIPTOR = Object.freeze({ + featureId: REFERENCE_FEATURE_ID, + routeCodecs: REFERENCE_FEATURE_ROUTE_CODECS, + routeRuntime: Object.freeze({}), +}); diff --git a/src/features/reference-feature/presentation/reference-feature-runtime.ts b/src/features/reference-feature/presentation/reference-feature-runtime.ts new file mode 100644 index 00000000..86ed6e35 --- /dev/null +++ b/src/features/reference-feature/presentation/reference-feature-runtime.ts @@ -0,0 +1,32 @@ +import { lazy } from "react"; + +import { REFERENCE_FEATURE_ID } from "../contracts/reference-feature-contract.ts"; +import { REFERENCE_FEATURE_ROUTE_CODECS } from "./reference-feature-runtime-descriptor.ts"; + +export { REFERENCE_FEATURE_ROUTE_CODECS } from "./reference-feature-runtime-descriptor.ts"; + +export const REFERENCE_FEATURE_ROUTE_RUNTIME = { + REFERENCE_RESOURCE_LIST: Object.freeze({ + moduleId: "reference-resource-page", + Component: lazy(() => import("./reference-resource-page.tsx")), + }), + REFERENCE_RESOURCE_DETAIL: Object.freeze({ + moduleId: "reference-resource-detail-page", + Component: lazy(() => import("./reference-resource-detail-page.tsx")), + }), + REFERENCE_RESOURCE_FORM: Object.freeze({ + moduleId: "reference-resource-form-page", + Component: lazy(() => import("./reference-resource-form-page.tsx")), + }), + REFERENCE_RESOURCE_STATUS: Object.freeze({ + moduleId: "reference-resource-status-page", + Component: lazy(() => import("./reference-resource-status-page.tsx")), + }), +} as const; + +/** Context-owned lazy route modules consume this executable contribution. */ +export const REFERENCE_FEATURE_RUNTIME_CONTRIBUTION = Object.freeze({ + featureId: REFERENCE_FEATURE_ID, + routeCodecs: REFERENCE_FEATURE_ROUTE_CODECS, + routeRuntime: REFERENCE_FEATURE_ROUTE_RUNTIME, +}); diff --git a/src/features/reference-feature/presentation/reference-feature-runtime.tsx b/src/features/reference-feature/presentation/reference-feature-runtime.tsx index ca385519..4f9fe72b 100644 --- a/src/features/reference-feature/presentation/reference-feature-runtime.tsx +++ b/src/features/reference-feature/presentation/reference-feature-runtime.tsx @@ -1,37 +1,5 @@ -import { lazy } from "react"; - -import { REFERENCE_FEATURE_ID } from "../contracts/reference-feature-contract.ts"; -import { - referenceResourceListQuerySchema, - referenceResourceParamsSchema, -} from "../contracts/reference-schemas.ts"; - -export const REFERENCE_FEATURE_ROUTE_CODECS = { - ReferenceResourceListQuery: referenceResourceListQuerySchema, - ReferenceResourceParams: referenceResourceParamsSchema, -} as const; - -export const REFERENCE_FEATURE_ROUTE_RUNTIME = { - REFERENCE_RESOURCE_LIST: Object.freeze({ - moduleId: "reference-resource-page", - Component: lazy(() => import("./reference-resource-page.tsx")), - }), - REFERENCE_RESOURCE_DETAIL: Object.freeze({ - moduleId: "reference-resource-detail-page", - Component: lazy(() => import("./reference-resource-detail-page.tsx")), - }), - REFERENCE_RESOURCE_FORM: Object.freeze({ - moduleId: "reference-resource-form-page", - Component: lazy(() => import("./reference-resource-form-page.tsx")), - }), - REFERENCE_RESOURCE_STATUS: Object.freeze({ - moduleId: "reference-resource-status-page", - Component: lazy(() => import("./reference-resource-status-page.tsx")), - }), -} as const; - -export const REFERENCE_FEATURE_RUNTIME_CONTRIBUTION = Object.freeze({ - featureId: REFERENCE_FEATURE_ID, - routeCodecs: REFERENCE_FEATURE_ROUTE_CODECS, - routeRuntime: REFERENCE_FEATURE_ROUTE_RUNTIME, -}); +export { + REFERENCE_FEATURE_ROUTE_CODECS, + REFERENCE_FEATURE_ROUTE_RUNTIME, + REFERENCE_FEATURE_RUNTIME_CONTRIBUTION, +} from "./reference-feature-runtime.ts"; diff --git a/src/platform/cardinality/cardinality-budget.ts b/src/platform/cardinality/cardinality-budget.ts new file mode 100644 index 00000000..e6b2a31f --- /dev/null +++ b/src/platform/cardinality/cardinality-budget.ts @@ -0,0 +1,29 @@ +export class CardinalityBudgetExceededError extends RangeError { + readonly scope: string; + readonly actual: number; + readonly maximum: number; + + constructor(scope: string, actual: number, maximum: number) { + super(`${scope} cardinality ${actual} exceeds budget ${maximum}`); + this.name = "CardinalityBudgetExceededError"; + this.scope = scope; + this.actual = actual; + this.maximum = maximum; + } +} + +export function assertWithinCardinalityBudget( + scope: string, + actual: number, + maximum: number, +): void { + if (!Number.isSafeInteger(actual) || actual < 0) { + throw new TypeError(`Invalid cardinality for ${scope}: ${actual}`); + } + if (!Number.isSafeInteger(maximum) || maximum < 0) { + throw new TypeError(`Invalid cardinality budget for ${scope}: ${maximum}`); + } + if (actual > maximum) { + throw new CardinalityBudgetExceededError(scope, actual, maximum); + } +} diff --git a/src/platform/cardinality/compose-unique-record.ts b/src/platform/cardinality/compose-unique-record.ts new file mode 100644 index 00000000..e803d10b --- /dev/null +++ b/src/platform/cardinality/compose-unique-record.ts @@ -0,0 +1,23 @@ +type UnionToIntersection = ( + Union extends unknown ? (value: Union) => void : never +) extends (value: infer Intersection) => void + ? Intersection + : never; + +type ComposedRecord>[]> = + Readonly>; + +export function composeUniqueRecord< + const Records extends readonly Readonly>[], +>(records: Records, describeScope: () => string): ComposedRecord { + const result: Record = {}; + for (const record of records) { + for (const [key, value] of Object.entries(record)) { + if (Object.hasOwn(result, key)) { + throw new TypeError(`Duplicate ${describeScope()} key: ${key}`); + } + result[key] = value; + } + } + return Object.freeze(result) as ComposedRecord; +} diff --git a/src/platform/cardinality/growth-regression.ts b/src/platform/cardinality/growth-regression.ts new file mode 100644 index 00000000..e743b699 --- /dev/null +++ b/src/platform/cardinality/growth-regression.ts @@ -0,0 +1,87 @@ +/** + * Spec ยง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 + * (cost ~ n^k) and fails when any segment grows faster than `maxExponent`. + * A quadratic implementation (k ~ 2) therefore fails even while its absolute + * times are still small, and a linear one (k ~ 1) passes even when absolute + * times are large. + * + * Costs below `noiseFloor` are clamped to it, so scheduler noise on tiny + * measurements cannot fabricate a steep segment; a real super-linear cost + * still shows up in the segments measured above the floor. + */ +export type GrowthSample = Readonly<{ n: number; cost: number }>; + +export type GrowthOptions = Readonly<{ + /** Largest tolerated per-segment exponent. Default 1.5 (between n and n^2). */ + maxExponent?: number; + /** Measurements below this cost are treated as this cost. Default 0. */ + noiseFloor?: number; +}>; + +export class GrowthRegressionError extends Error { + readonly exponent: number; + readonly from: GrowthSample; + readonly to: GrowthSample; + + constructor(exponent: number, from: GrowthSample, to: GrowthSample) { + super( + `super-linear growth: exponent ${exponent.toFixed(2)} between n=${from.n} (cost ${from.cost}) and n=${to.n} (cost ${to.cost})`, + ); + this.name = "GrowthRegressionError"; + this.exponent = exponent; + this.from = from; + this.to = to; + } +} + +export function growthExponents( + samples: readonly GrowthSample[], + noiseFloor = 0, +): readonly number[] { + const sorted = [...samples].sort((left, right) => left.n - right.n); + const exponents: number[] = []; + for (let index = 1; index < sorted.length; index += 1) { + const from = sorted[index - 1] as GrowthSample; + const to = sorted[index] as GrowthSample; + const fromCost = Math.max(from.cost, noiseFloor, Number.MIN_VALUE); + const toCost = Math.max(to.cost, noiseFloor, Number.MIN_VALUE); + exponents.push(Math.log(toCost / fromCost) / Math.log(to.n / from.n)); + } + return exponents; +} + +export function assertLinearOrBetter( + samples: readonly GrowthSample[], + options: GrowthOptions = {}, +): void { + const maxExponent = options.maxExponent ?? 1.5; + const noiseFloor = options.noiseFloor ?? 0; + if (samples.length < 2) { + throw new TypeError("growth check needs at least two measurements"); + } + for (const sample of samples) { + if (!Number.isFinite(sample.n) || sample.n <= 0) { + throw new TypeError(`growth sample n must be positive: ${sample.n}`); + } + if (!Number.isFinite(sample.cost) || sample.cost < 0) { + throw new TypeError(`growth sample cost must be finite: ${sample.cost}`); + } + } + const sorted = [...samples].sort((left, right) => left.n - right.n); + if (new Set(sorted.map((sample) => sample.n)).size !== sorted.length) { + throw new TypeError("growth samples need distinct n values"); + } + const exponents = growthExponents(sorted, noiseFloor); + exponents.forEach((exponent, index) => { + if (exponent > maxExponent) { + throw new GrowthRegressionError( + exponent, + sorted[index] as GrowthSample, + sorted[index + 1] as GrowthSample, + ); + } + }); +} diff --git a/src/platform/cardinality/topology-capacity.ts b/src/platform/cardinality/topology-capacity.ts new file mode 100644 index 00000000..8eb2ae20 --- /dev/null +++ b/src/platform/cardinality/topology-capacity.ts @@ -0,0 +1,71 @@ +export type TopologyCapacityInput = Readonly<{ + featureCount: number; + maxFeaturesPerContext: number; + maxContextsPerApp: number; +}>; + +export type TopologyCapacityPlan = Readonly<{ + featureCount: number; + contextCount: number; + appCount: number; + maxFeaturesInAnyContext: number; + maxContextsInAnyApp: number; + totalFeatureCapacity: number; +}>; + +function assertSafeCount(name: string, value: number, allowZero: boolean): void { + const minimum = allowZero ? 0 : 1; + if (!Number.isSafeInteger(value) || value < minimum) { + throw new TypeError(`${name} must be a safe integer >= ${minimum}: ${value}`); + } +} + +function multiplySafe(name: string, left: number, right: number): number { + if (left !== 0 && right > Number.MAX_SAFE_INTEGER / left) { + throw new RangeError(`${name} exceeds Number.MAX_SAFE_INTEGER`); + } + return left * right; +} + +/** + * Computes the minimum hierarchy needed to keep direct-child cardinality + * bounded. It deliberately works from counts instead of materializing every + * feature descriptor, so million-feature CI fixtures do not become memory + * benchmarks themselves. + */ +export function planTopologyCapacity( + input: TopologyCapacityInput, +): TopologyCapacityPlan { + assertSafeCount("featureCount", input.featureCount, true); + assertSafeCount("maxFeaturesPerContext", input.maxFeaturesPerContext, false); + assertSafeCount("maxContextsPerApp", input.maxContextsPerApp, false); + + const contextCount = Math.ceil( + input.featureCount / input.maxFeaturesPerContext, + ); + const appCount = + contextCount === 0 ? 1 : Math.ceil(contextCount / input.maxContextsPerApp); + const capacityPerApp = multiplySafe( + "capacityPerApp", + input.maxFeaturesPerContext, + input.maxContextsPerApp, + ); + const totalFeatureCapacity = multiplySafe( + "totalFeatureCapacity", + appCount, + capacityPerApp, + ); + + return Object.freeze({ + featureCount: input.featureCount, + contextCount, + appCount, + maxFeaturesInAnyContext: + input.featureCount === 0 + ? 0 + : Math.min(input.featureCount, input.maxFeaturesPerContext), + maxContextsInAnyApp: + contextCount === 0 ? 0 : Math.min(contextCount, input.maxContextsPerApp), + totalFeatureCapacity, + }); +} diff --git a/src/platform/errors/app-error.ts b/src/platform/errors/app-error.ts new file mode 100644 index 00000000..c344cecd --- /dev/null +++ b/src/platform/errors/app-error.ts @@ -0,0 +1,83 @@ +/** + * Spec ยง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) + * that raises them; there is deliberately no union enumerating every feature + * error, so a new feature never edits a central error type. + */ +export type ErrorCategory = + | "transport" + | "contract" + | "validation" + | "domain" + | "application" + | "platform"; + +export type ErrorSeverity = "info" | "warning" | "error" | "critical"; + +export type Retryability = "never" | "safe" | "policy"; + +export interface AppError { + /** Stable machine-readable `owner.reason` kind, e.g. `payment.declined`. */ + readonly kind: string; + readonly category: ErrorCategory; + readonly severity: ErrorSeverity; + readonly retryability: Retryability; +} + +export const ERROR_CATEGORIES: ReadonlySet = new Set([ + "transport", + "contract", + "validation", + "domain", + "application", + "platform", +]); + +export const ERROR_SEVERITIES: ReadonlySet = new Set([ + "info", + "warning", + "error", + "critical", +]); + +const RETRYABILITIES: ReadonlySet = new Set([ + "never", + "safe", + "policy", +]); + +/** Bounded, low-cardinality `owner.reason` identifier. */ +const ERROR_KIND = /^[a-z][a-z0-9-]{0,39}(?:\.[a-z][a-z0-9-]{0,39}){1,3}$/u; + +export function isErrorKind(value: unknown): value is string { + return typeof value === "string" && ERROR_KIND.test(value); +} + +/** + * Structural recognition only: reads four own data fields and never invokes + * accessors, so an untrusted object cannot run code while being classified. + */ +export function isAppError(value: unknown): value is AppError { + if (value === null || typeof value !== "object") return false; + const read = (key: string): unknown => { + const descriptor = Object.getOwnPropertyDescriptor(value, key); + return descriptor && "value" in descriptor ? descriptor.value : undefined; + }; + return ( + isErrorKind(read("kind")) && + ERROR_CATEGORIES.has(read("category") as ErrorCategory) && + ERROR_SEVERITIES.has(read("severity") as ErrorSeverity) && + RETRYABILITIES.has(read("retryability") as Retryability) + ); +} + +export function defineAppError( + error: Envelope, +): Readonly { + if (!isAppError(error)) { + throw new TypeError("Invalid AppError envelope"); + } + return Object.freeze({ ...error }); +} diff --git a/src/platform/errors/context-error-boundary.tsx b/src/platform/errors/context-error-boundary.tsx new file mode 100644 index 00000000..d6655b8a --- /dev/null +++ b/src/platform/errors/context-error-boundary.tsx @@ -0,0 +1,33 @@ +import type { ReactNode } from "react"; + +import { + ScopedErrorBoundary, + type ScopedErrorBoundaryProps, +} from "./scoped-error-boundary.tsx"; + +/** + * Spec ยง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. + */ +export function ContextErrorBoundary( + props: Readonly<{ + contextId?: string; + children: ReactNode; + fallback?: ReactNode; + resetKey?: string; + onError?: ScopedErrorBoundaryProps["onError"]; + }>, +) { + return ( + + {props.children} + + ); +} diff --git a/src/platform/errors/feature-error-boundary.tsx b/src/platform/errors/feature-error-boundary.tsx new file mode 100644 index 00000000..e68f9cfb --- /dev/null +++ b/src/platform/errors/feature-error-boundary.tsx @@ -0,0 +1,32 @@ +import type { ReactNode } from "react"; + +import { + ScopedErrorBoundary, + type ScopedErrorBoundaryProps, +} from "./scoped-error-boundary.tsx"; + +/** + * Spec ยง30. Contains a feature-local render failure inside the feature's own + * subtree. The enclosing context boundary is the next escalation. + */ +export function FeatureErrorBoundary( + props: Readonly<{ + featureId: string; + children: ReactNode; + fallback?: ReactNode; + resetKey?: string; + onError?: ScopedErrorBoundaryProps["onError"]; + }>, +) { + return ( + + {props.children} + + ); +} diff --git a/src/platform/errors/platform-errors.ts b/src/platform/errors/platform-errors.ts new file mode 100644 index 00000000..40a80b04 --- /dev/null +++ b/src/platform/errors/platform-errors.ts @@ -0,0 +1,90 @@ +import { defineAppError, type AppError } from "./app-error.ts"; + +/** + * Spec ยง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. + */ +export const PLATFORM_ERRORS = Object.freeze({ + NETWORK_UNAVAILABLE: defineAppError({ + kind: "network.unavailable", + category: "transport", + severity: "warning", + retryability: "policy", + }), + REQUEST_TIMEOUT: defineAppError({ + kind: "request.timeout", + category: "transport", + severity: "warning", + retryability: "policy", + }), + REQUEST_CANCELLED: defineAppError({ + kind: "request.cancelled", + category: "transport", + severity: "info", + retryability: "never", + }), + RESPONSE_TOO_LARGE: defineAppError({ + kind: "response.too-large", + category: "contract", + severity: "error", + retryability: "never", + }), + RESPONSE_INVALID: defineAppError({ + kind: "response.invalid", + category: "contract", + severity: "error", + retryability: "never", + }), + TRAFFIC_BUDGET_EXCEEDED: defineAppError({ + kind: "traffic.budget-exceeded", + category: "platform", + severity: "warning", + retryability: "never", + }), +}); + +export type PlatformError = + (typeof PLATFORM_ERRORS)[keyof typeof PLATFORM_ERRORS]; + +export type PlatformErrorKind = PlatformError["kind"]; + +function errorName(error: unknown): string | undefined { + if (error === null || typeof error !== "object") return undefined; + const descriptor = Object.getOwnPropertyDescriptor(error, "name"); + if (descriptor && "value" in descriptor) { + return typeof descriptor.value === "string" ? descriptor.value : undefined; + } + // `name` normally lives on the prototype of Error subclasses. + return error instanceof Error ? error.name : undefined; +} + +/** + * Maps a raw failure thrown by a transport (fetch, a lease wait, a budget + * check) to a platform error. An abort is a timeout only when the caller + * states that the deadline, not an owner, caused it. + */ +export function mapTransportFailure( + error: unknown, + context: Readonly<{ deadlineExpired: boolean }>, +): AppError { + const name = errorName(error); + if (name === "AbortError" || name === "TimeoutError") { + return context.deadlineExpired || name === "TimeoutError" + ? PLATFORM_ERRORS.REQUEST_TIMEOUT + : PLATFORM_ERRORS.REQUEST_CANCELLED; + } + if (name === "DeadlineExceededError") return PLATFORM_ERRORS.REQUEST_TIMEOUT; + if ( + name === "RequestBudgetExceededError" || + name === "ConcurrencyQueueFullError" || + name === "RequestFanoutExceededError" + ) { + return PLATFORM_ERRORS.TRAFFIC_BUDGET_EXCEEDED; + } + if (name === "JsonBudgetExceededError") { + return PLATFORM_ERRORS.RESPONSE_TOO_LARGE; + } + if (name === "SyntaxError") return PLATFORM_ERRORS.RESPONSE_INVALID; + return PLATFORM_ERRORS.NETWORK_UNAVAILABLE; +} diff --git a/src/platform/errors/scoped-error-boundary.tsx b/src/platform/errors/scoped-error-boundary.tsx new file mode 100644 index 00000000..e1f569b1 --- /dev/null +++ b/src/platform/errors/scoped-error-boundary.tsx @@ -0,0 +1,63 @@ +import { Component, type ReactNode } from "react"; + +/** + * Spec ยง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; + * siblings outside the scope keep rendering. Reporting is best-effort and can + * never recurse into another render failure. + */ +export type ErrorBoundaryScope = "context" | "feature"; + +export type ScopedErrorBoundaryProps = Readonly<{ + scope: ErrorBoundaryScope; + ownerId: string; + children: ReactNode; + fallback?: ReactNode; + /** Changing the key clears a caught failure (e.g. on navigation). */ + resetKey?: string; + onError?: (report: Readonly<{ scope: ErrorBoundaryScope; ownerId: string }>) => void; +}>; + +type ScopedErrorBoundaryState = Readonly<{ failed: boolean }>; + +export class ScopedErrorBoundary extends Component< + ScopedErrorBoundaryProps, + ScopedErrorBoundaryState +> { + state: ScopedErrorBoundaryState = { failed: false }; + + static getDerivedStateFromError(): ScopedErrorBoundaryState { + return { failed: true }; + } + + componentDidCatch(): void { + try { + this.props.onError?.( + Object.freeze({ scope: this.props.scope, ownerId: this.props.ownerId }), + ); + } catch { + // Observability is outside the render authority. + } + } + + componentDidUpdate(previous: Readonly): void { + if (this.state.failed && previous.resetKey !== this.props.resetKey) { + this.setState({ failed: false }); + } + } + + render(): ReactNode { + if (!this.state.failed) return this.props.children; + return ( +
+ {this.props.fallback ?? null} +
+ ); + } +} diff --git a/src/platform/execution/execution-context.ts b/src/platform/execution/execution-context.ts new file mode 100644 index 00000000..84efd8f0 --- /dev/null +++ b/src/platform/execution/execution-context.ts @@ -0,0 +1,131 @@ +import { remainingDeadlineMs } from "../resilience/deadline.ts"; +import type { TraceContext } from "../telemetry/trace-context.ts"; +import { + createTrafficRuntime, + type TrafficBudget, + type TrafficRuntime, +} from "../traffic/traffic-budget.ts"; + +/** + * Spec ยง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 + * leases) and the cancellation controller, both private to this interaction and + * shared by every child operation it starts. + */ +export type InteractionId = string & { readonly __brand: "InteractionId" }; + +const INTERACTION_ID = /^[A-Za-z0-9._:-]{1,128}$/u; + +export function toInteractionId(value: string): InteractionId { + if (!INTERACTION_ID.test(value)) { + throw new TypeError("interaction id must be 1-128 safe characters"); + } + return value as InteractionId; +} + +export type TrafficBudgetInput = Omit & + Readonly<{ maxQueuedRequests?: number }>; + +export interface ExecutionContext { + readonly interaction: Readonly<{ + id: InteractionId; + startedAt: number; + deadlineAt: number; + }>; + readonly cancellation: Readonly<{ + signal: AbortSignal; + cancel(): void; + }>; + readonly traffic: TrafficRuntime; + /** + * Spec ยง29. The interaction trace identity. Present only when the + * interaction opted into propagation; every child request then carries the + * same `traceparent` and correlation id. + */ + readonly trace?: TraceContext; + /** The monotonic clock `startedAt`/`deadlineAt` were measured against. */ + readonly clock: () => number; + /** Time left before the absolute interaction deadline; never negative. */ + remainingMs(): number; +} + +export type ExecutionContextOptions = Readonly<{ + interactionId: string; + deadlineMs: number; + traffic: TrafficBudgetInput; + /** Defaults to `clock()`. */ + startedAt?: number; + /** Monotonic clock. Defaults to `performance.now`. */ + clock?: () => number; + /** An owner signal (route, scope, caller) that also cancels the interaction. */ + signal?: AbortSignal; + trace?: TraceContext; +}>; + +/** Absolute ceiling for one interaction; matches the HTTP hard total deadline. */ +export const MAX_INTERACTION_DEADLINE_MS = 60_000; + +export function createExecutionContext( + options: ExecutionContextOptions, +): ExecutionContext { + const clock = options.clock ?? (() => performance.now()); + if ( + !Number.isSafeInteger(options.deadlineMs) || + options.deadlineMs < 1 || + options.deadlineMs > MAX_INTERACTION_DEADLINE_MS + ) { + throw new TypeError( + `interaction deadlineMs must be 1..${MAX_INTERACTION_DEADLINE_MS}: ${options.deadlineMs}`, + ); + } + const startedAt = options.startedAt ?? clock(); + const traffic = createTrafficRuntime({ + ...options.traffic, + // A bounded default: at most one waiter per concurrent slot. + maxQueuedRequests: + options.traffic.maxQueuedRequests ?? options.traffic.maxConcurrentRequests, + }); + const interaction = Object.freeze({ + id: toInteractionId(options.interactionId), + startedAt, + deadlineAt: startedAt + options.deadlineMs, + }); + + const controller = new AbortController(); + const parent = options.signal; + if (parent) { + if (parent.aborted) controller.abort(); + else { + const forward = () => controller.abort(); + parent.addEventListener("abort", forward, { once: true }); + // The interaction must not keep the parent's listener alive after it ends. + controller.signal.addEventListener( + "abort", + () => parent.removeEventListener("abort", forward), + { once: true }, + ); + } + } + + return Object.freeze({ + interaction, + cancellation: Object.freeze({ + signal: controller.signal, + cancel() { + controller.abort(); + }, + }), + traffic, + ...(options.trace === undefined ? {} : { trace: options.trace }), + clock, + remainingMs() { + try { + return remainingDeadlineMs(interaction.deadlineAt, clock()); + } catch { + return 0; + } + }, + }); +} diff --git a/src/platform/release/release-coherence.ts b/src/platform/release/release-coherence.ts new file mode 100644 index 00000000..b24060db --- /dev/null +++ b/src/platform/release/release-coherence.ts @@ -0,0 +1,104 @@ +/** + * Spec ยง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 + * runtime config and the release manifest. Every boot-critical identity field + * that two sources both carry must agree; a single disagreement is a release + * mismatch and there is no partial-success state. + */ +export type ReleaseIdentity = Readonly<{ + buildId?: string; + releaseId?: string; + configSchemaVersion?: string; + assetManifestHash?: string; +}>; + +export type ReleaseIdentityField = keyof ReleaseIdentity; + +export type ReleaseIdentitySource = "html" | "config" | "manifest"; + +/** The precedence the boot loaders have always reported mismatches in. */ +export const RELEASE_IDENTITY_FIELDS: readonly ReleaseIdentityField[] = Object.freeze([ + "buildId", + "configSchemaVersion", + "releaseId", + "assetManifestHash", +]); + +export type ReleaseCoherenceResult = + | Readonly<{ coherent: true }> + | Readonly<{ + coherent: false; + field: ReleaseIdentityField; + sources: readonly [ReleaseIdentitySource, ReleaseIdentitySource]; + }>; + +export class ReleaseMismatchError extends Error { + readonly field: ReleaseIdentityField; + readonly sources: readonly [ReleaseIdentitySource, ReleaseIdentitySource]; + + constructor( + field: ReleaseIdentityField, + sources: readonly [ReleaseIdentitySource, ReleaseIdentitySource], + ) { + super(`release identity mismatch: ${field} differs between ${sources[0]} and ${sources[1]}`); + this.name = "ReleaseMismatchError"; + this.field = field; + this.sources = sources; + } +} + +function present(value: string | undefined): value is string { + return typeof value === "string" && value.length > 0; +} + +export function checkReleaseCoherence( + identities: Readonly>>, + fields: readonly ReleaseIdentityField[] = RELEASE_IDENTITY_FIELDS, +): ReleaseCoherenceResult { + const sources: readonly ReleaseIdentitySource[] = ["html", "config", "manifest"]; + for (const field of fields) { + let reference: Readonly<{ source: ReleaseIdentitySource; value: string }> | null = null; + for (const source of sources) { + const value = identities[source]?.[field]; + if (!present(value)) continue; + if (reference === null) { + reference = { source, value }; + continue; + } + if (value !== reference.value) { + return Object.freeze({ + coherent: false as const, + field, + sources: Object.freeze([reference.source, source] as const), + }); + } + } + } + return Object.freeze({ coherent: true as const }); +} + +/** + * Throws `ReleaseMismatchError` (message contains "release ... mismatch") on + * the first incoherent field. The HTML and manifest build identities are + * mandatory: a boot that cannot name its own build is never coherent. + */ +export function assertReleaseCoherent( + htmlIdentity: ReleaseIdentity, + configIdentity: ReleaseIdentity, + manifestIdentity: ReleaseIdentity, +): void { + if (!present(htmlIdentity.buildId)) { + throw new ReleaseMismatchError("buildId", ["html", "manifest"]); + } + if (!present(manifestIdentity.buildId)) { + throw new ReleaseMismatchError("buildId", ["manifest", "html"]); + } + const result = checkReleaseCoherence({ + html: htmlIdentity, + config: configIdentity, + manifest: manifestIdentity, + }); + if (!result.coherent) throw new ReleaseMismatchError(result.field, result.sources); +} diff --git a/src/platform/release/release-mismatch-recovery.ts b/src/platform/release/release-mismatch-recovery.ts new file mode 100644 index 00000000..ead3e5e7 --- /dev/null +++ b/src/platform/release/release-mismatch-recovery.ts @@ -0,0 +1,79 @@ +/** + * Spec ยง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 + * lands on a coherent tuple, so exactly one automatic reload is allowed per + * stable mismatch key. A second occurrence of the same key shows the failure; + * it never reloads again, so a persistently mixed deployment cannot loop. + * + * The marker is a single bounded value. It clears after a coherent boot and + * expires after `ttlMs`, so an old marker cannot suppress recovery forever. + */ +/** + * The single persisted marker, kept by whatever session-scoped store the host + * composes (the approved browser storage adapter in production). `write` must + * throw when the marker was not persisted. + */ +export type RecoveryMarkerStore = Readonly<{ + read(): string | null; + write(value: string): void; + clear(): void; +}>; + +export type ReleaseMismatchDecision = "reload-once" | "show-failure"; + +export interface ReleaseMismatchRecovery { + decide(mismatchKey: string): ReleaseMismatchDecision; + markCoherentBoot(): void; +} + +const MAX_KEY_LENGTH = 256; + +export function createReleaseMismatchRecovery( + store: RecoveryMarkerStore | null, + options: Readonly<{ + now?: () => number; + ttlMs?: number; + }> = {}, +): ReleaseMismatchRecovery { + const now = options.now ?? (() => Date.now()); + const ttlMs = options.ttlMs ?? 10 * 60_000; + + function read(): Readonly<{ key: string; at: number }> | null { + const raw = store?.read() ?? null; + if (raw === null) return null; + const separator = raw.lastIndexOf("@"); + const at = Number(raw.slice(separator + 1)); + if (separator <= 0 || !Number.isFinite(at)) return null; + return { key: raw.slice(0, separator), at }; + } + + return Object.freeze({ + decide(mismatchKey: string): ReleaseMismatchDecision { + const key = mismatchKey.slice(0, MAX_KEY_LENGTH); + try { + if (!store) return "show-failure"; + const previous = read(); + const current = now(); + if (previous && previous.key === key && current - previous.at < ttlMs) { + return "show-failure"; + } + store.write(`${key}@${current}`); + // Only a marker that is really persisted may authorize a reload; + // otherwise the next boot could not know it already reloaded. + return read()?.key === key ? "reload-once" : "show-failure"; + } catch { + // Fail closed: without a working marker, never reload automatically. + return "show-failure"; + } + }, + markCoherentBoot(): void { + try { + store?.clear(); + } catch { + // A stale marker only means the next mismatch shows the failure. + } + }, + }); +} diff --git a/src/platform/resilience/deadline.ts b/src/platform/resilience/deadline.ts new file mode 100644 index 00000000..9d7305e8 --- /dev/null +++ b/src/platform/resilience/deadline.ts @@ -0,0 +1,28 @@ +/** + * Spec ยง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: + * the caller supplies `now` from the same monotonic (or fake) clock that + * produced `deadlineAt`. + */ +export class DeadlineExceededError extends Error { + readonly deadlineAt: number; + readonly now: number; + + constructor(deadlineAt: number, now: number) { + super(`request.timeout: interaction deadline exceeded by ${now - deadlineAt}ms`); + this.name = "DeadlineExceededError"; + this.deadlineAt = deadlineAt; + this.now = now; + } +} + +export function remainingDeadlineMs(deadlineAt: number, now: number): number { + if (!Number.isFinite(deadlineAt) || !Number.isFinite(now)) { + throw new TypeError("deadline and clock values must be finite"); + } + const remaining = deadlineAt - now; + if (remaining < 0) throw new DeadlineExceededError(deadlineAt, now); + return remaining; +} diff --git a/src/platform/resilience/retry-budget.ts b/src/platform/resilience/retry-budget.ts new file mode 100644 index 00000000..bfd90895 --- /dev/null +++ b/src/platform/resilience/retry-budget.ts @@ -0,0 +1,34 @@ +import { assertFiniteBudget } from "../traffic/request-budget.ts"; + +/** + * Spec ยง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 + * requests cannot each claim their own full retry allowance during an outage. + */ +export interface RetryBudget { + readonly maximum: number; + readonly consumed: number; + /** + * `requestId` is a bounded diagnostic label only. It never partitions the + * budget; recording it per request would recreate a request-scoped budget. + */ + tryConsume(requestId: string): boolean; +} + +export function createRetryBudget(maxRetries: number): RetryBudget { + assertFiniteBudget("maxRetries", maxRetries, 0); + let consumed = 0; + return Object.freeze({ + maximum: maxRetries, + get consumed() { + return consumed; + }, + tryConsume(_requestId: string) { + if (consumed >= maxRetries) return false; + consumed += 1; + return true; + }, + }); +} diff --git a/src/platform/routing/context-route-module.ts b/src/platform/routing/context-route-module.ts new file mode 100644 index 00000000..a3791119 --- /dev/null +++ b/src/platform/routing/context-route-module.ts @@ -0,0 +1,54 @@ +import type { RouteObject } from "react-router-dom"; +import type { DeployableAppModule } from "../../apps/deployable-app-module.ts"; + +export type ContextRouteModule = Readonly<{ + id: string; + path: string; + loadRoutes(): Promise; +}>; + +function createCachedContextRouteLoader( + loadRoutes: () => Promise, +): () => Promise { + let loadedRoutes: readonly RouteObject[] | undefined; + let pendingLoad: Promise | undefined; + + return () => { + if (loadedRoutes) return Promise.resolve(loadedRoutes); + if (pendingLoad) return pendingLoad; + + pendingLoad = Promise.resolve() + .then(loadRoutes) + .then( + (routes) => { + loadedRoutes = Object.freeze([...routes]); + return loadedRoutes; + }, + (error: unknown) => { + pendingLoad = undefined; + throw error; + }, + ); + return pendingLoad; + }; +} + +export function createAppRouteModules( + app: DeployableAppModule, +): readonly ContextRouteModule[] { + return Object.freeze( + app.contexts.flatMap((context) => + context.route + ? [ + Object.freeze({ + id: context.id, + path: context.route.path, + loadRoutes: createCachedContextRouteLoader( + context.route.loadRoutes, + ), + }), + ] + : [], + ), + ); +} diff --git a/src/platform/telemetry/redact-telemetry.ts b/src/platform/telemetry/redact-telemetry.ts new file mode 100644 index 00000000..ad9257d3 --- /dev/null +++ b/src/platform/telemetry/redact-telemetry.ts @@ -0,0 +1,144 @@ +/** + * Spec ยง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 + * payloads. Traversal is iterative and capped by a structural budget, so an + * adversarial payload cannot make telemetry itself unbounded. + */ +export type TelemetryPayloadBudget = Readonly<{ + maxDepth: number; + maxKeys: number; + maxArrayItems: number; + maxStringLength: number; +}>; + +export const DEFAULT_TELEMETRY_PAYLOAD_BUDGET: TelemetryPayloadBudget = + Object.freeze({ + maxDepth: 6, + maxKeys: 64, + maxArrayItems: 32, + maxStringLength: 256, + }); + +export const REDACTED = "[redacted]"; +export const TRUNCATED = "[truncated]"; + +/** + * Case/separator-insensitive secret key detection. `accessToken`, + * `access_token` and `ACCESS-TOKEN` all normalize to `accesstoken`. + */ +const SECRET_KEY_FRAGMENTS = Object.freeze([ + "password", + "passwd", + "secret", + "authorization", + "cookie", + "token", + "apikey", + "credential", + "session", + "privatekey", + "signature", +]); + +export function isSecretTelemetryKey(key: string): boolean { + const normalized = key.toLowerCase().replace(/[^a-z0-9]/gu, ""); + return SECRET_KEY_FRAGMENTS.some((fragment) => normalized.includes(fragment)); +} + +/** Values that look like bearer credentials are redacted wherever they occur. */ +const SECRET_VALUE = /^(?:bearer|basic)\s+\S+|^eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\./iu; + +function readOwnData( + source: object, + key: string, +): Readonly<{ ok: true; value: unknown }> | Readonly<{ ok: false }> { + const descriptor = Object.getOwnPropertyDescriptor(source, key); + if (!descriptor || !("value" in descriptor)) return { ok: false }; + return { ok: true, value: descriptor.value }; +} + +function sanitizeLeaf(value: unknown, budget: TelemetryPayloadBudget): unknown { + switch (typeof value) { + case "string": + if (SECRET_VALUE.test(value)) return REDACTED; + return value.length > budget.maxStringLength + ? `${value.slice(0, budget.maxStringLength)}${TRUNCATED}` + : value; + case "number": + return Number.isFinite(value) ? value : null; + case "boolean": + return value; + default: + return null; + } +} + +type Pending = Readonly<{ + source: unknown; + depth: number; + assign: (value: unknown) => void; +}>; + +export function redactTelemetryPayload( + payload: unknown, + budget: TelemetryPayloadBudget = DEFAULT_TELEMETRY_PAYLOAD_BUDGET, +): unknown { + let result: unknown = null; + const stack: Pending[] = [ + { + source: payload, + depth: 0, + assign: (value) => { + result = value; + }, + }, + ]; + while (stack.length > 0) { + const { source, depth, assign } = stack.pop() as Pending; + if (source === null || typeof source !== "object") { + assign(source === undefined ? null : sanitizeLeaf(source, budget)); + continue; + } + if (depth >= budget.maxDepth) { + assign(TRUNCATED); + continue; + } + if (Array.isArray(source)) { + const length = Math.min(source.length, budget.maxArrayItems); + const copy: unknown[] = new Array(length).fill(null); + assign(copy); + for (let index = 0; index < length; index += 1) { + const item = readOwnData(source, String(index)); + if (!item.ok) continue; + stack.push({ + source: item.value, + depth: depth + 1, + assign: (value) => { + copy[index] = value; + }, + }); + } + continue; + } + const copy: Record = {}; + assign(copy); + for (const key of Object.keys(source).slice(0, budget.maxKeys)) { + if (key === "__proto__" || key === "constructor" || key === "prototype") { + continue; + } + if (isSecretTelemetryKey(key)) continue; + const entry = readOwnData(source, key); + if (!entry.ok) continue; + stack.push({ + source: entry.value, + depth: depth + 1, + assign: (value) => { + copy[key] = value; + }, + }); + } + } + return result; +} diff --git a/src/platform/telemetry/telemetry-buffer.ts b/src/platform/telemetry/telemetry-buffer.ts new file mode 100644 index 00000000..5d3b9cda --- /dev/null +++ b/src/platform/telemetry/telemetry-buffer.ts @@ -0,0 +1,125 @@ +import { + TELEMETRY_SEVERITY_RANK, + type TelemetryEvent, +} from "./telemetry-event.ts"; + +/** + * Spec ยง25 / ยง27. Bounded, severity-aware telemetry buffer. + * + * The buffer never exceeds `maxEvents` or `maxBytes`. When full, the lowest + * severity (oldest first) event is evicted; an incoming event that is not more + * important than everything buffered is dropped instead. Buffer growth is + * never used as backpressure. + */ +export type BufferedTelemetryEvent = Readonly<{ + event: TelemetryEvent; + bytes: number; + /** Deduplication key assigned by the pipeline, when there is one. */ + fingerprint?: string; +}>; + +export interface TelemetryBuffer { + readonly size: number; + readonly bytes: number; + readonly dropped: number; + readonly items: readonly TelemetryEvent[]; + push( + event: TelemetryEvent, + bytes?: number, + fingerprint?: string, + ): boolean; + take(maxEvents: number): readonly BufferedTelemetryEvent[]; + clear(): void; +} + +const UTF8 = new TextEncoder(); + +export function estimateTelemetryBytes(event: TelemetryEvent): number { + try { + return UTF8.encode(JSON.stringify(event)).byteLength; + } catch { + return Number.POSITIVE_INFINITY; + } +} + +export function createTelemetryBuffer( + options: Readonly<{ maxEvents: number; maxBytes: number }>, +): TelemetryBuffer { + const { maxEvents, maxBytes } = options; + if (!Number.isSafeInteger(maxEvents) || maxEvents < 1) { + throw new TypeError(`telemetry buffer maxEvents must be positive: ${maxEvents}`); + } + if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) { + throw new TypeError(`telemetry buffer maxBytes must be positive: ${maxBytes}`); + } + const entries: BufferedTelemetryEvent[] = []; + let bytes = 0; + let dropped = 0; + + function lowestIndex(): number { + let index = -1; + let rank = Number.POSITIVE_INFINITY; + for (let i = 0; i < entries.length; i += 1) { + const candidate = TELEMETRY_SEVERITY_RANK[(entries[i] as BufferedTelemetryEvent).event.severity]; + if (candidate < rank) { + rank = candidate; + index = i; + } + } + return index; + } + + return { + get size() { + return entries.length; + }, + get bytes() { + return bytes; + }, + get dropped() { + return dropped; + }, + get items() { + return entries.map((entry) => entry.event); + }, + push(event, size = estimateTelemetryBytes(event), fingerprint) { + if (!Number.isFinite(size) || size > maxBytes) { + dropped += 1; + return false; + } + const incomingRank = TELEMETRY_SEVERITY_RANK[event.severity]; + while (entries.length >= maxEvents || bytes + size > maxBytes) { + const victim = lowestIndex(); + const victimEntry = entries[victim]; + if ( + !victimEntry || + TELEMETRY_SEVERITY_RANK[victimEntry.event.severity] > incomingRank + ) { + dropped += 1; + return false; + } + entries.splice(victim, 1); + bytes -= victimEntry.bytes; + dropped += 1; + } + entries.push( + Object.freeze( + fingerprint === undefined + ? { event, bytes: size } + : { event, bytes: size, fingerprint }, + ), + ); + bytes += size; + return true; + }, + take(count) { + const batch = entries.splice(0, Math.max(0, count)); + for (const entry of batch) bytes -= entry.bytes; + return batch; + }, + clear() { + entries.length = 0; + bytes = 0; + }, + }; +} diff --git a/src/platform/telemetry/telemetry-deduplicator.ts b/src/platform/telemetry/telemetry-deduplicator.ts new file mode 100644 index 00000000..a99acafe --- /dev/null +++ b/src/platform/telemetry/telemetry-deduplicator.ts @@ -0,0 +1,73 @@ +/** + * Spec ยง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 + * `maxEntries` fingerprints: expired entries are evicted first, then the + * least recently seen one (Map insertion order is maintained as LRU order). + */ +export type TelemetryDeduplicatorOptions = Readonly<{ + maxEntries: number; + windowMs: number; +}>; + +type Entry = { firstSeenAt: number; count: number }; + +export class TelemetryDeduplicator { + readonly maxEntries: number; + readonly windowMs: number; + readonly #entries = new Map(); + + constructor(options: TelemetryDeduplicatorOptions) { + if (!Number.isSafeInteger(options.maxEntries) || options.maxEntries < 1) { + throw new TypeError(`dedup maxEntries must be a positive safe integer: ${options.maxEntries}`); + } + if (!Number.isSafeInteger(options.windowMs) || options.windowMs < 1) { + throw new TypeError(`dedup windowMs must be a positive safe integer: ${options.windowMs}`); + } + this.maxEntries = options.maxEntries; + this.windowMs = options.windowMs; + } + + get size(): number { + return this.#entries.size; + } + + /** + * Records one occurrence. Returns `true` when this is the first occurrence + * in the current window (the event should continue down the pipeline) and + * `false` when it is a duplicate. + */ + record(fingerprint: string, now: number): boolean { + const existing = this.#entries.get(fingerprint); + if (existing && now - existing.firstSeenAt < this.windowMs) { + existing.count += 1; + // Refresh LRU position. + this.#entries.delete(fingerprint); + this.#entries.set(fingerprint, existing); + return false; + } + if (existing) this.#entries.delete(fingerprint); + this.#evict(now); + this.#entries.set(fingerprint, { firstSeenAt: now, count: 1 }); + return true; + } + + count(fingerprint: string): number { + return this.#entries.get(fingerprint)?.count ?? 0; + } + + #evict(now: number): void { + if (this.#entries.size < this.maxEntries) return; + for (const [fingerprint, entry] of this.#entries) { + if (now - entry.firstSeenAt >= this.windowMs) { + this.#entries.delete(fingerprint); + } + } + while (this.#entries.size >= this.maxEntries) { + const oldest = this.#entries.keys().next(); + if (oldest.done) break; + this.#entries.delete(oldest.value); + } + } +} diff --git a/src/platform/telemetry/telemetry-event.ts b/src/platform/telemetry/telemetry-event.ts new file mode 100644 index 00000000..9ee6fd1a --- /dev/null +++ b/src/platform/telemetry/telemetry-event.ts @@ -0,0 +1,52 @@ +import type { ErrorSeverity } from "../errors/app-error.ts"; + +/** + * Spec ยง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 + * union of every feature's telemetry payload. + */ +export type TelemetrySeverity = ErrorSeverity; + +export interface TelemetryEvent { + /** Stable low-cardinality `owner.event` identifier. */ + readonly kind: string; + readonly severity: TelemetrySeverity; + readonly contextId?: string; + readonly featureId?: string; + /** + * Request-cardinality correlation. Used as the deterministic sampling key + * and never as a fingerprint dimension. + */ + readonly interactionId?: string; + readonly traceId?: string; + readonly payload?: TPayload; +} + +export const TELEMETRY_SEVERITY_RANK: Readonly> = + Object.freeze({ + info: 0, + warning: 1, + error: 2, + critical: 3, + }); + +const TELEMETRY_KIND = /^[a-z][a-z0-9-]{0,39}(?:\.[a-z][a-z0-9-]{0,39}){1,4}$/u; +const TELEMETRY_OWNER_ID = /^[a-z][a-z0-9-]{0,63}$/u; +const TELEMETRY_CORRELATION = /^[A-Za-z0-9._:-]{1,128}$/u; + +/** Envelope-level admission: bounded identifiers only, payload checked later. */ +export function isTelemetryEnvelopeValid(event: TelemetryEvent): boolean { + return ( + typeof event === "object" && + event !== null && + TELEMETRY_KIND.test(event.kind) && + Object.hasOwn(TELEMETRY_SEVERITY_RANK, event.severity) && + (event.contextId === undefined || TELEMETRY_OWNER_ID.test(event.contextId)) && + (event.featureId === undefined || TELEMETRY_OWNER_ID.test(event.featureId)) && + (event.interactionId === undefined || + TELEMETRY_CORRELATION.test(event.interactionId)) && + (event.traceId === undefined || /^[0-9a-f]{32}$/u.test(event.traceId)) + ); +} diff --git a/src/platform/telemetry/telemetry-fingerprint.ts b/src/platform/telemetry/telemetry-fingerprint.ts new file mode 100644 index 00000000..f70e69bc --- /dev/null +++ b/src/platform/telemetry/telemetry-fingerprint.ts @@ -0,0 +1,89 @@ +import type { TelemetryEvent } from "./telemetry-event.ts"; + +/** + * Spec ยง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 + * one fingerprint. The payload contributes through a stable key-sorted + * serialization of its (already redacted) value. + */ + +/** Structural punctuation, kept distinct from any payload string. */ +class Token { + readonly text: string; + constructor(text: string) { + this.text = text; + } +} + +const CLOSE_ARRAY = new Token("]"); +const CLOSE_OBJECT = new Token("}"); +const COMMA = new Token(","); + +export function stableSerialize(value: unknown): string { + const parts: string[] = []; + const stack: unknown[] = [value]; + while (stack.length > 0) { + const current = stack.pop(); + if (current instanceof Token) { + parts.push(current.text); + continue; + } + if (current === null || typeof current !== "object") { + parts.push(JSON.stringify(current ?? null) ?? "null"); + continue; + } + if (Array.isArray(current)) { + parts.push("["); + stack.push(CLOSE_ARRAY); + for (let index = current.length - 1; index >= 0; index -= 1) { + stack.push(current[index]); + if (index > 0) stack.push(COMMA); + } + continue; + } + parts.push("{"); + stack.push(CLOSE_OBJECT); + const keys = Object.keys(current).sort(); + for (let index = keys.length - 1; index >= 0; index -= 1) { + const key = keys[index] as string; + stack.push((current as Record)[key]); + stack.push(new Token(`${index > 0 ? "," : ""}${JSON.stringify(key)}:`)); + } + } + return parts.join(""); +} + +function fnv1a32(text: string, seed: number): number { + let hash = seed >>> 0; + for (let index = 0; index < text.length; index += 1) { + hash ^= text.charCodeAt(index); + hash = Math.imul(hash, 0x01000193) >>> 0; + } + return hash >>> 0; +} + +/** + * Two independently seeded 32-bit FNV-1a hashes rendered as 16 hex + * characters. Not cryptographic; collision resistance only needs to keep + * distinct low-cardinality failures apart. + */ +export function stableHash64(text: string): string { + return ( + fnv1a32(text, 0x811c9dc5).toString(16).padStart(8, "0") + + fnv1a32(text, 0x01000193 ^ 0x9e3779b9).toString(16).padStart(8, "0") + ); +} + +export function fingerprintTelemetryEvent(event: TelemetryEvent): string { + return stableHash64( + stableSerialize({ + kind: event.kind, + severity: event.severity, + contextId: event.contextId ?? null, + featureId: event.featureId ?? null, + payload: event.payload ?? null, + }), + ); +} diff --git a/src/platform/telemetry/telemetry-pipeline.ts b/src/platform/telemetry/telemetry-pipeline.ts new file mode 100644 index 00000000..d2733451 --- /dev/null +++ b/src/platform/telemetry/telemetry-pipeline.ts @@ -0,0 +1,283 @@ +import { + createTelemetryBuffer, + estimateTelemetryBytes, +} from "./telemetry-buffer.ts"; +import { TelemetryDeduplicator } from "./telemetry-deduplicator.ts"; +import { + isTelemetryEnvelopeValid, + TELEMETRY_SEVERITY_RANK, + type TelemetryEvent, +} from "./telemetry-event.ts"; +import { fingerprintTelemetryEvent } from "./telemetry-fingerprint.ts"; +import type { TelemetryPort } from "./telemetry-port.ts"; +import { + DEFAULT_TELEMETRY_PAYLOAD_BUDGET, + redactTelemetryPayload, + type TelemetryPayloadBudget, +} from "./redact-telemetry.ts"; +import { createDeterministicSampler } from "./telemetry-sampler.ts"; + +/** + * Spec ยง25โ€“ยง28. The bounded, fail-open telemetry pipeline: + * + * redact -> fingerprint -> deduplicate -> sample -> buffer + * -> rate limit -> batch -> transport + * + * Every stage has an explicit ceiling, and no stage can throw or reject into + * the business caller: internal failures become dropped-event counters. + */ +export type TelemetryBatchItem = Readonly<{ + event: TelemetryEvent; + fingerprint: string; + /** Occurrences collapsed into this fingerprint in the current window. */ + occurrences: number; +}>; + +export interface TelemetryTransport { + send(batch: readonly TelemetryBatchItem[]): void | Promise; +} + +export interface TelemetryPipelineBudget { + readonly maxBufferedEvents: number; + readonly maxBufferedBytes: number; + readonly maxBatchEvents: number; + readonly maxSendsPerMinute: number; + readonly dedupWindowMs: number; + readonly maxFingerprints: number; + /** Sampling rate for `info`/`warning`; `error`/`critical` are never sampled out. */ + readonly sampleRate: number; + readonly payload?: TelemetryPayloadBudget; +} + +export const DEFAULT_TELEMETRY_PIPELINE_BUDGET: TelemetryPipelineBudget = + Object.freeze({ + maxBufferedEvents: 200, + maxBufferedBytes: 256 * 1024, + maxBatchEvents: 50, + maxSendsPerMinute: 20, + dedupWindowMs: 60_000, + maxFingerprints: 500, + sampleRate: 1, + }); + +export type TelemetryPipelineStats = Readonly<{ + accepted: number; + invalid: number; + deduplicated: number; + sampledOut: number; + dropped: number; + sends: number; + failedSends: number; + buffered: number; + bufferedBytes: number; + peakBuffered: number; + fingerprints: number; +}>; + +export interface TelemetryPipeline extends TelemetryPort { + emit(event: TelemetryEvent): Promise; + flush(): Promise; + stats(): TelemetryPipelineStats; + dispose(): void; +} + +const RATE_WINDOW_MS = 60_000; + +function assertPositive(name: string, value: number): void { + if (!Number.isSafeInteger(value) || value < 1) { + throw new TypeError(`telemetry budget ${name} must be a positive safe integer: ${value}`); + } +} + +export function createTelemetryPipeline( + options: Readonly<{ + transport: TelemetryTransport; + budget?: TelemetryPipelineBudget; + /** Monotonic clock. */ + now?: () => number; + /** Schedules a flush soon (default: microtask). */ + schedule?: (callback: () => void) => void; + /** Schedules a flush after a rate window reopens (default: setTimeout). */ + setTimer?: (callback: () => void, ms: number) => unknown; + clearTimer?: (handle: unknown) => void; + }>, +): TelemetryPipeline { + const budget = options.budget ?? DEFAULT_TELEMETRY_PIPELINE_BUDGET; + assertPositive("maxBufferedEvents", budget.maxBufferedEvents); + assertPositive("maxBufferedBytes", budget.maxBufferedBytes); + assertPositive("maxBatchEvents", budget.maxBatchEvents); + assertPositive("maxSendsPerMinute", budget.maxSendsPerMinute); + const payloadBudget = budget.payload ?? DEFAULT_TELEMETRY_PAYLOAD_BUDGET; + const now = options.now ?? (() => performance.now()); + const schedule = options.schedule ?? queueMicrotask; + const setTimer = + options.setTimer ?? + ((callback: () => void, ms: number) => setTimeout(callback, ms)); + const clearTimer = + options.clearTimer ?? + ((handle: unknown) => clearTimeout(handle as ReturnType)); + + const dedup = new TelemetryDeduplicator({ + maxEntries: budget.maxFingerprints, + windowMs: budget.dedupWindowMs, + }); + const sampler = createDeterministicSampler({ rate: budget.sampleRate }); + const buffer = createTelemetryBuffer({ + maxEvents: budget.maxBufferedEvents, + maxBytes: budget.maxBufferedBytes, + }); + /** Send timestamps inside the current rate window; never above the limit. */ + const sendTimes: number[] = []; + + let disposed = false; + let flushScheduled = false; + let rateTimer: unknown = null; + let activeFlush: Promise | null = null; + const counters = { + accepted: 0, + invalid: 0, + deduplicated: 0, + sampledOut: 0, + sends: 0, + failedSends: 0, + peakBuffered: 0, + }; + + function rateAllows(at: number): boolean { + while (sendTimes.length > 0 && at - (sendTimes[0] as number) >= RATE_WINDOW_MS) { + sendTimes.shift(); + } + return sendTimes.length < budget.maxSendsPerMinute; + } + + function armRateTimer(at: number): void { + if (rateTimer !== null || disposed) return; + const reopenIn = Math.max(1, (sendTimes[0] ?? at) + RATE_WINDOW_MS - at); + rateTimer = setTimer(() => { + rateTimer = null; + void flush(); + }, reopenIn); + } + + function scheduleFlush(): void { + if (flushScheduled || disposed) return; + flushScheduled = true; + schedule(() => { + flushScheduled = false; + void flush(); + }); + } + + async function drain(): Promise { + while (!disposed && buffer.size > 0) { + const at = now(); + if (!rateAllows(at)) { + armRateTimer(at); + return; + } + const batch = buffer.take(budget.maxBatchEvents).map((entry) => + Object.freeze({ + event: entry.event, + fingerprint: entry.fingerprint ?? "", + occurrences: Math.max(1, dedup.count(entry.fingerprint ?? "")), + }), + ); + sendTimes.push(at); + counters.sends += 1; + try { + await options.transport.send(batch); + } catch { + // Best effort: a failed batch is counted, never retried unboundedly. + counters.failedSends += batch.length; + } + } + } + + function flush(): Promise { + if (activeFlush) return activeFlush; + if (disposed || buffer.size === 0) return Promise.resolve(); + activeFlush = drain() + .catch(() => undefined) + .finally(() => { + activeFlush = null; + }); + return activeFlush; + } + + function admit(event: TelemetryEvent): void { + if (disposed) return; + if (!isTelemetryEnvelopeValid(event)) { + counters.invalid += 1; + return; + } + // 1. redact (before anything is retained) + const redacted: TelemetryEvent = Object.freeze({ + kind: event.kind, + severity: event.severity, + ...(event.contextId === undefined ? {} : { contextId: event.contextId }), + ...(event.featureId === undefined ? {} : { featureId: event.featureId }), + ...(event.interactionId === undefined + ? {} + : { interactionId: event.interactionId }), + ...(event.traceId === undefined ? {} : { traceId: event.traceId }), + ...(event.payload === undefined + ? {} + : { payload: redactTelemetryPayload(event.payload, payloadBudget) }), + }); + // 2. fingerprint 3. deduplicate + const fingerprint = fingerprintTelemetryEvent(redacted); + if (!dedup.record(fingerprint, now())) { + counters.deduplicated += 1; + return; + } + // 4. sample (deterministic by interaction; severe events always kept) + if ( + TELEMETRY_SEVERITY_RANK[redacted.severity] < TELEMETRY_SEVERITY_RANK.error && + !sampler.keep(redacted.interactionId ?? fingerprint) + ) { + counters.sampledOut += 1; + return; + } + // 5. buffer + if (buffer.push(redacted, estimateTelemetryBytes(redacted), fingerprint)) { + counters.accepted += 1; + counters.peakBuffered = Math.max(counters.peakBuffered, buffer.size); + } + // 6-8. rate limit, batch and transport happen on flush. + scheduleFlush(); + } + + return Object.freeze({ + emit(event: TelemetryEvent): Promise { + try { + admit(event); + } catch { + counters.invalid += 1; + } + return Promise.resolve(); + }, + flush, + stats(): TelemetryPipelineStats { + return Object.freeze({ + accepted: counters.accepted, + invalid: counters.invalid, + deduplicated: counters.deduplicated, + sampledOut: counters.sampledOut, + dropped: buffer.dropped + counters.failedSends + counters.invalid, + sends: counters.sends, + failedSends: counters.failedSends, + buffered: buffer.size, + bufferedBytes: buffer.bytes, + peakBuffered: counters.peakBuffered, + fingerprints: dedup.size, + }); + }, + dispose(): void { + if (disposed) return; + disposed = true; + if (rateTimer !== null) clearTimer(rateTimer); + rateTimer = null; + buffer.clear(); + }, + }); +} diff --git a/src/platform/telemetry/telemetry-port.ts b/src/platform/telemetry/telemetry-port.ts new file mode 100644 index 00000000..d2f1d655 --- /dev/null +++ b/src/platform/telemetry/telemetry-port.ts @@ -0,0 +1,35 @@ +import type { TelemetryEvent } from "./telemetry-event.ts"; + +/** + * Spec ยง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 + * in feature code. + */ +export interface TelemetryPort { + emit(event: TelemetryEvent): void | Promise; +} + +export const NO_OP_TELEMETRY_PORT: TelemetryPort = Object.freeze({ + emit() {}, +}); + +/** + * Wraps any port so that a synchronous throw or an asynchronous rejection is + * contained at the call site (spec ยง26). + */ +export function failOpenTelemetryPort(port: TelemetryPort): TelemetryPort { + return Object.freeze({ + emit(event: TelemetryEvent): Promise { + try { + return Promise.resolve(port.emit(event)).then( + () => undefined, + () => undefined, + ); + } catch { + return Promise.resolve(); + } + }, + }); +} diff --git a/src/platform/telemetry/telemetry-sampler.ts b/src/platform/telemetry/telemetry-sampler.ts new file mode 100644 index 00000000..07900a8d --- /dev/null +++ b/src/platform/telemetry/telemetry-sampler.ts @@ -0,0 +1,32 @@ +import { stableHash64 } from "./telemetry-fingerprint.ts"; + +/** + * Spec ยง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. + */ +export interface TelemetrySampler { + readonly rate: number; + keep(key: string): boolean; +} + +export function createDeterministicSampler( + options: Readonly<{ rate: number }>, +): TelemetrySampler { + const { rate } = options; + if (!Number.isFinite(rate) || rate < 0 || rate > 1) { + throw new TypeError(`sampling rate must be within [0, 1]: ${rate}`); + } + // 32-bit bucket from the stable hash; exact at the 0 and 1 edges. + const threshold = Math.floor(rate * 0x1_0000_0000); + return Object.freeze({ + rate, + keep(key: string): boolean { + if (rate >= 1) return true; + if (rate <= 0) return false; + const bucket = Number.parseInt(stableHash64(key).slice(0, 8), 16); + return bucket < threshold; + }, + }); +} diff --git a/src/platform/telemetry/trace-context.ts b/src/platform/telemetry/trace-context.ts new file mode 100644 index 00000000..a22baff1 --- /dev/null +++ b/src/platform/telemetry/trace-context.ts @@ -0,0 +1,103 @@ +/** + * Spec ยง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 + * the `x-correlation-id` the HTTP runtime already reads back from responses. + * No second, competing correlation header is introduced. + */ +export const TRACEPARENT_HEADER = "traceparent"; +export const CORRELATION_ID_HEADER = "x-correlation-id"; + +export type TraceContext = Readonly<{ + traceId: string; + spanId: string; + sampled: boolean; + traceparent: string; +}>; + +const TRACE_ID = /^[0-9a-f]{32}$/u; +const SPAN_ID = /^[0-9a-f]{16}$/u; +const CORRELATION_ID = /^[A-Za-z0-9._:-]{1,128}$/u; + +export function isValidTraceId(value: string): boolean { + return TRACE_ID.test(value) && !/^0+$/u.test(value); +} + +export function isValidSpanId(value: string): boolean { + return SPAN_ID.test(value) && !/^0+$/u.test(value); +} + +function randomHex(bytes: number, random: () => number): string { + let out = ""; + for (let index = 0; index < bytes; index += 1) { + out += Math.floor(random() * 256) + .toString(16) + .padStart(2, "0"); + } + return out; +} + +function secureRandomHex(bytes: number): string { + const buffer = new Uint8Array(bytes); + globalThis.crypto.getRandomValues(buffer); + return Array.from(buffer, (byte) => byte.toString(16).padStart(2, "0")).join(""); +} + +export function createTraceContext( + options: Readonly<{ + traceId?: string; + spanId?: string; + sampled?: boolean; + /** Test seam; production uses `crypto.getRandomValues`. */ + random?: () => number; + }> = {}, +): TraceContext { + const generate = (bytes: number) => + options.random ? randomHex(bytes, options.random) : secureRandomHex(bytes); + let traceId = options.traceId ?? generate(16); + let spanId = options.spanId ?? generate(8); + if (!isValidTraceId(traceId)) { + if (options.traceId !== undefined) { + throw new TypeError("traceId must be 32 lowercase hex characters, not all zero"); + } + traceId = `${traceId.slice(0, 31)}1`; + } + if (!isValidSpanId(spanId)) { + if (options.spanId !== undefined) { + throw new TypeError("spanId must be 16 lowercase hex characters, not all zero"); + } + spanId = `${spanId.slice(0, 15)}1`; + } + const sampled = options.sampled ?? true; + return Object.freeze({ + traceId, + spanId, + sampled, + traceparent: `00-${traceId}-${spanId}-${sampled ? "01" : "00"}`, + }); +} + +/** + * The trace/correlation headers for one physical request. Every child request + * of the same interaction carries the same `traceparent` and correlation id. + */ +export function buildTraceHeaders( + context: Readonly<{ + interaction: Readonly<{ id: string }>; + trace?: TraceContext; + }>, +): Readonly> { + const headers: Record = {}; + if (CORRELATION_ID.test(context.interaction.id)) { + headers[CORRELATION_ID_HEADER] = context.interaction.id; + } + if (context.trace) headers[TRACEPARENT_HEADER] = context.trace.traceparent; + return Object.freeze(headers); +} + +export function buildRequestHeaders( + context: Parameters[0], +): Headers { + return new Headers(buildTraceHeaders(context)); +} diff --git a/src/platform/traffic/concurrency-budget.ts b/src/platform/traffic/concurrency-budget.ts new file mode 100644 index 00000000..0925df4a --- /dev/null +++ b/src/platform/traffic/concurrency-budget.ts @@ -0,0 +1,114 @@ +import { assertFiniteBudget } from "./request-budget.ts"; + +/** + * Spec ยง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 + * immediately instead of growing the queue (queue growth is not + * backpressure). + * - An aborted waiter leaves the queue at once and never receives a lease. + * - A lease is idempotently releasable, so a double release cannot inflate + * capacity. + */ +export class ConcurrencyQueueFullError extends RangeError { + readonly maxQueued: number; + + constructor(maxQueued: number) { + super(`traffic.budget-exceeded: concurrency queue full (${maxQueued})`); + this.name = "ConcurrencyQueueFullError"; + this.maxQueued = maxQueued; + } +} + +export interface ConcurrencyLease { + release(): void; +} + +export interface ConcurrencyBudget { + readonly maximum: number; + readonly maxQueued: number; + readonly active: number; + readonly queued: number; + acquire(signal: AbortSignal): Promise; +} + +type Waiter = { + grant(lease: ConcurrencyLease): void; + settled: boolean; +}; + +function abortError(): DOMException { + return new DOMException("concurrency wait aborted", "AbortError"); +} + +export function createConcurrencyBudget( + options: Readonly<{ maximum: number; maxQueued: number }>, +): ConcurrencyBudget { + assertFiniteBudget("maxConcurrentRequests", options.maximum, 1); + assertFiniteBudget("maxQueuedRequests", options.maxQueued, 0); + const { maximum, maxQueued } = options; + let active = 0; + const waiters: Waiter[] = []; + + function createLease(): ConcurrencyLease { + let released = false; + return Object.freeze({ + release() { + if (released) return; + released = true; + active -= 1; + drain(); + }, + }); + } + + function drain(): void { + while (active < maximum && waiters.length > 0) { + const next = waiters.shift(); + if (!next || next.settled) continue; + active += 1; + next.grant(createLease()); + } + } + + return Object.freeze({ + maximum, + maxQueued, + get active() { + return active; + }, + get queued() { + return waiters.length; + }, + acquire(signal: AbortSignal): Promise { + if (signal.aborted) return Promise.reject(abortError()); + if (active < maximum && waiters.length === 0) { + active += 1; + return Promise.resolve(createLease()); + } + if (waiters.length >= maxQueued) { + return Promise.reject(new ConcurrencyQueueFullError(maxQueued)); + } + return new Promise((resolve, reject) => { + const onAbort = () => { + if (waiter.settled) return; + waiter.settled = true; + const index = waiters.indexOf(waiter); + if (index >= 0) waiters.splice(index, 1); + reject(abortError()); + }; + const waiter: Waiter = { + settled: false, + grant(lease) { + waiter.settled = true; + signal.removeEventListener("abort", onAbort); + resolve(lease); + }, + }; + waiters.push(waiter); + signal.addEventListener("abort", onAbort, { once: true }); + }); + }, + }); +} diff --git a/src/platform/traffic/request-budget.ts b/src/platform/traffic/request-budget.ts new file mode 100644 index 00000000..6205d7c8 --- /dev/null +++ b/src/platform/traffic/request-budget.ts @@ -0,0 +1,54 @@ +/** + * Spec ยง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 + * number of dispatches. + */ +export class RequestBudgetExceededError extends RangeError { + readonly maximum: number; + + constructor(maximum: number) { + super(`traffic.budget-exceeded: physical request budget ${maximum} exhausted`); + this.name = "RequestBudgetExceededError"; + this.maximum = maximum; + } +} + +export interface RequestBudget { + readonly maximum: number; + readonly consumed: number; + readonly remaining: number; + tryConsume(): boolean; +} + +export function assertFiniteBudget( + name: string, + value: number, + minimum: number, +): void { + if (!Number.isSafeInteger(value) || value < minimum) { + throw new TypeError( + `traffic budget ${name} must be a finite safe integer >= ${minimum}: ${value}`, + ); + } +} + +export function createRequestBudget(maxPhysicalRequests: number): RequestBudget { + assertFiniteBudget("maxPhysicalRequests", maxPhysicalRequests, 1); + let consumed = 0; + return Object.freeze({ + maximum: maxPhysicalRequests, + get consumed() { + return consumed; + }, + get remaining() { + return maxPhysicalRequests - consumed; + }, + tryConsume() { + if (consumed >= maxPhysicalRequests) return false; + consumed += 1; + return true; + }, + }); +} diff --git a/src/platform/traffic/request-fanout.ts b/src/platform/traffic/request-fanout.ts new file mode 100644 index 00000000..4c2cb6c7 --- /dev/null +++ b/src/platform/traffic/request-fanout.ts @@ -0,0 +1,31 @@ +/** + * Spec ยง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. + */ +export class RequestFanoutExceededError extends RangeError { + readonly physicalRequests: number; + readonly maximum: number; + + constructor(physicalRequests: number, maximum: number) { + super(`Request fan-out ${physicalRequests} exceeds ${maximum}`); + this.name = "RequestFanoutExceededError"; + this.physicalRequests = physicalRequests; + this.maximum = maximum; + } +} + +export function assertRequestFanoutWithinBudget( + physicalRequests: number, + maximum: number, +): void { + if (!Number.isSafeInteger(maximum) || maximum < 1) { + throw new TypeError(`Invalid request fan-out budget: ${maximum}`); + } + if (!Number.isSafeInteger(physicalRequests) || physicalRequests < 0) { + throw new TypeError(`Invalid physical request count: ${physicalRequests}`); + } + if (physicalRequests > maximum) { + throw new RequestFanoutExceededError(physicalRequests, maximum); + } +} diff --git a/src/platform/traffic/traffic-budget.ts b/src/platform/traffic/traffic-budget.ts new file mode 100644 index 00000000..bbe9975e --- /dev/null +++ b/src/platform/traffic/traffic-budget.ts @@ -0,0 +1,88 @@ +import { + createRetryBudget, + type RetryBudget, +} from "../resilience/retry-budget.ts"; +import { + createConcurrencyBudget, + type ConcurrencyBudget, +} from "./concurrency-budget.ts"; +import { + assertFiniteBudget, + createRequestBudget, + type RequestBudget, +} from "./request-budget.ts"; + +/** + * Spec ยง11. Immutable traffic policy. Every field is a finite safe integer; + * there is no "unlimited" sentinel. + */ +export interface TrafficBudget { + readonly maxPhysicalRequests: number; + readonly maxRetries: number; + readonly maxConcurrentRequests: number; + readonly maxQueuedRequests: number; +} + +/** + * The mutable, interaction-local counters derived from one `TrafficBudget`. + * One runtime is created per interaction and shared by every child operation. + */ +export interface TrafficRuntime { + readonly policy: TrafficBudget; + readonly requests: RequestBudget; + readonly retries: RetryBudget; + readonly concurrency: ConcurrencyBudget; +} + +export const TRAFFIC_BUDGET_KEYS = [ + "maxPhysicalRequests", + "maxRetries", + "maxConcurrentRequests", + "maxQueuedRequests", +] as const satisfies readonly (keyof TrafficBudget)[]; + +/** Hard ceilings a policy may lower but never raise. */ +export const TRAFFIC_BUDGET_CEILINGS = Object.freeze({ + maxPhysicalRequests: 64, + maxRetries: 16, + maxConcurrentRequests: 16, + maxQueuedRequests: 256, +}); + +export function defineTrafficBudget(policy: TrafficBudget): TrafficBudget { + if (policy === null || typeof policy !== "object") { + throw new TypeError("traffic budget must be an object"); + } + assertFiniteBudget("maxPhysicalRequests", policy.maxPhysicalRequests, 1); + assertFiniteBudget("maxRetries", policy.maxRetries, 0); + assertFiniteBudget("maxConcurrentRequests", policy.maxConcurrentRequests, 1); + assertFiniteBudget("maxQueuedRequests", policy.maxQueuedRequests, 0); + for (const key of TRAFFIC_BUDGET_KEYS) { + if (policy[key] > TRAFFIC_BUDGET_CEILINGS[key]) { + throw new RangeError( + `traffic budget ${key} ${policy[key]} exceeds ceiling ${TRAFFIC_BUDGET_CEILINGS[key]}`, + ); + } + } + // Every retry is also a physical request, so the effective retry count is + // min(maxRetries, maxPhysicalRequests - 1); both budgets are enforced. + return Object.freeze({ + maxPhysicalRequests: policy.maxPhysicalRequests, + maxRetries: policy.maxRetries, + maxConcurrentRequests: policy.maxConcurrentRequests, + maxQueuedRequests: policy.maxQueuedRequests, + }); +} + +export function createTrafficRuntime(policy: TrafficBudget): TrafficRuntime { + const budget = defineTrafficBudget(policy); + return Object.freeze({ + policy: budget, + requests: createRequestBudget(budget.maxPhysicalRequests), + retries: createRetryBudget(budget.maxRetries), + concurrency: createConcurrencyBudget({ + maximum: budget.maxConcurrentRequests, + maxQueued: budget.maxQueuedRequests, + }), + }); +} diff --git a/src/platform/validation/bounded-json.ts b/src/platform/validation/bounded-json.ts new file mode 100644 index 00000000..91d9d5cb --- /dev/null +++ b/src/platform/validation/bounded-json.ts @@ -0,0 +1,117 @@ +import type { ValidationBudget } from "./validation-budget.ts"; + +/** + * Spec ยง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 + * adversarially nested payload cannot overflow the call stack or make the + * mapper/validator do unbounded work. + */ +export type JsonBudgetViolation = + | "too-large" + | "too-many-items" + | "too-deep" + | "string-too-long" + | "invalid-json"; + +export class JsonBudgetExceededError extends RangeError { + readonly violation: JsonBudgetViolation; + + constructor(violation: JsonBudgetViolation, detail: string) { + super(`response.${violation}: ${detail}`); + this.name = "JsonBudgetExceededError"; + this.violation = violation; + } +} + +const UTF8 = new TextEncoder(); + +function utf8Length(text: string, ceiling: number): number { + // Each UTF-16 unit encodes to at most 3 UTF-8 bytes, so only text that could + // exceed the ceiling pays for an exact encode. + if (text.length * 3 <= ceiling) return text.length; + return UTF8.encode(text).byteLength; +} + +export function parseBoundedJson(text: string, budget: ValidationBudget): unknown { + if (text.length > budget.maxBytes || utf8Length(text, budget.maxBytes) > budget.maxBytes) { + throw new JsonBudgetExceededError( + "too-large", + `payload exceeds ${budget.maxBytes} bytes`, + ); + } + let value: unknown; + try { + value = JSON.parse(text); + } catch { + throw new JsonBudgetExceededError("invalid-json", "payload is not JSON"); + } + validateJsonStructure(value, budget); + return value; +} + +export type JsonStructureResult = + | Readonly<{ ok: true; nodes: number }> + | Readonly<{ ok: false; violation: JsonBudgetViolation; detail: string }>; + +/** + * Non-throwing structural check over an already-parsed JSON value. Plain data + * only: prototypes and accessors are never consulted. + */ +export function checkJsonStructure( + value: unknown, + budget: ValidationBudget, +): JsonStructureResult { + const stack: Array = [[value, 1]]; + let nodes = 0; + while (stack.length > 0) { + const [current, depth] = stack.pop() as readonly [unknown, number]; + nodes += 1; + if (nodes > budget.maxItems) { + return fail("too-many-items", `more than ${budget.maxItems} nodes`); + } + if (typeof current === "string") { + if (current.length > budget.maxStringLength) { + return fail( + "string-too-long", + `string longer than ${budget.maxStringLength}`, + ); + } + continue; + } + if (current === null || typeof current !== "object") continue; + if (depth > budget.maxDepth) { + return fail("too-deep", `nesting deeper than ${budget.maxDepth}`); + } + if (Array.isArray(current)) { + if (current.length > budget.maxItems) { + return fail("too-many-items", `array longer than ${budget.maxItems}`); + } + for (let index = current.length - 1; index >= 0; index -= 1) { + stack.push([current[index], depth + 1]); + } + continue; + } + const keys = Object.keys(current); + if (keys.length > budget.maxItems) { + return fail("too-many-items", `object wider than ${budget.maxItems}`); + } + for (const key of keys) { + if (key.length > budget.maxStringLength) { + return fail("string-too-long", "object key too long"); + } + stack.push([(current as Record)[key], depth + 1]); + } + } + return Object.freeze({ ok: true as const, nodes }); +} + +export function validateJsonStructure(value: unknown, budget: ValidationBudget): void { + const result = checkJsonStructure(value, budget); + if (!result.ok) throw new JsonBudgetExceededError(result.violation, result.detail); +} + +function fail(violation: JsonBudgetViolation, detail: string): JsonStructureResult { + return Object.freeze({ ok: false as const, violation, detail }); +} diff --git a/src/platform/validation/validation-budget.ts b/src/platform/validation/validation-budget.ts new file mode 100644 index 00000000..c918f9f4 --- /dev/null +++ b/src/platform/validation/validation-budget.ts @@ -0,0 +1,51 @@ +/** + * Spec ยง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 + * never replace backend validation. + */ +export interface ValidationBudget { + readonly maxBytes: number; + readonly maxItems: number; + readonly maxDepth: number; + readonly maxStringLength: number; +} + +const VALIDATION_BUDGET_KEYS = [ + "maxBytes", + "maxItems", + "maxDepth", + "maxStringLength", +] as const satisfies readonly (keyof ValidationBudget)[]; + +export function defineValidationBudget(budget: ValidationBudget): ValidationBudget { + for (const key of VALIDATION_BUDGET_KEYS) { + const value = budget[key]; + if (!Number.isSafeInteger(value) || value < 1) { + throw new TypeError( + `validation budget ${key} must be a finite positive safe integer: ${value}`, + ); + } + } + return Object.freeze({ + maxBytes: budget.maxBytes, + maxItems: budget.maxItems, + maxDepth: budget.maxDepth, + maxStringLength: budget.maxStringLength, + }); +} + +/** + * The structure budget applied to an HTTP response already bounded by its + * operation's `responseByteLimit`. `maxItems` bounds every array/object + * member count and the total node count; `maxDepth` bounds nesting. + */ +export function responseValidationBudget(responseByteLimit: number): ValidationBudget { + return defineValidationBudget({ + maxBytes: responseByteLimit, + maxItems: 100_000, + maxDepth: 64, + maxStringLength: responseByteLimit, + }); +} diff --git a/src/presentation/adapters/query/application-query.ts b/src/presentation/adapters/query/application-query.ts index 1d5a1494..48bca904 100644 --- a/src/presentation/adapters/query/application-query.ts +++ b/src/presentation/adapters/query/application-query.ts @@ -170,7 +170,7 @@ export function useApplicationQuery( const retry = useCallback(async () => { setStaleFailure(false); - await query.refetch(); + await query.refetch({ cancelRefetch: false }); }, [query]); return Object.freeze({ @@ -428,11 +428,30 @@ export function useApplicationMutation( }); } const active = mutationExecutions(queryClient).get(identity) as - | Promise> + | RuntimeMutationExecution | undefined; if (active && duplicatePolicy === "JOIN_IDENTICAL") { + if ( + active.joinedWaiters >= + MUTATION_COORDINATOR_BOUNDS.waitersPerJoinedIntent + ) { + identityLease?.release(); + return Promise.resolve({ + ok: false, + error: createFailure( + "DUPLICATE_IN_FLIGHT", + definitionId, + 0, + { + code: "JOIN_WAITER_LIMIT_EXCEEDED", + effect: "NOT_STARTED", + }, + ), + }); + } + active.joinedWaiters += 1; identityLease?.release(); - return active; + return active.promise; } if (active && duplicatePolicy === "REJECT_WHILE_ACTIVE") { identityLease?.release(); @@ -481,6 +500,7 @@ export function useApplicationMutation( setConflict(null); mutation.reset(); + let runtimeExecution: RuntimeMutationExecution | undefined; const pending = (async (): Promise> => { let execution: MutationExecution; if (scope) { @@ -588,12 +608,16 @@ export function useApplicationMutation( }) .finally(() => { identityLease?.release(); - if (mutationExecutions(queryClient).get(identity) === pending) { + if ( + runtimeExecution && + mutationExecutions(queryClient).get(identity) === runtimeExecution + ) { mutationExecutions(queryClient).delete(identity); } }); if (duplicatePolicy !== "ALLOW_PARALLEL") { - mutationExecutions(queryClient).set(identity, pending); + runtimeExecution = { promise: pending, joinedWaiters: 0 }; + mutationExecutions(queryClient).set(identity, runtimeExecution); } return pending; }, @@ -813,17 +837,22 @@ function removeAdmissionOptimisticQuery( }); } +type RuntimeMutationExecution = { + promise: Promise>; + joinedWaiters: number; +}; + const RUNTIME_MUTATION_EXECUTIONS = new WeakMap< object, - Map>> + Map >(); function mutationExecutions( owner: object, -): Map>> { +): Map { const existing = RUNTIME_MUTATION_EXECUTIONS.get(owner); if (existing) return existing; - const created = new Map>>(); + const created = new Map(); RUNTIME_MUTATION_EXECUTIONS.set(owner, created); return created; } diff --git a/src/presentation/routes/app-router.tsx b/src/presentation/routes/app-router.tsx index 0c505b45..7bb878ea 100644 --- a/src/presentation/routes/app-router.tsx +++ b/src/presentation/routes/app-router.tsx @@ -1,4 +1,5 @@ import { + type ElementType, type ReactNode, Suspense, useEffect, @@ -8,6 +9,7 @@ import { } from "react"; import { createBrowserRouter, + matchRoutes, RouterProvider, type RouteObject, useLocation, @@ -19,14 +21,23 @@ import { import { getRoute, ROUTE_FEATURE_OWNER, - ROUTE_REGISTRY, } from "../../features/installed-feature-contracts.ts"; -import type { RouteDefinition } from "../../contracts/routes.ts"; +import { + PLATFORM_ROUTE_REGISTRY, + type RouteDefinition, +} from "../../contracts/routes.ts"; +import { TEMPLATE_APP_MODULE } from "../../apps/template-app.ts"; +import { + createAppRouteModules, + type ContextRouteModule, +} from "../../platform/routing/context-route-module.ts"; import { FeatureBoundary, RouteBoundary, } from "../boundaries/render-error-boundary.tsx"; import { ChunkRecoveryBoundary } from "../boundaries/chunk-recovery-boundary.tsx"; +import { ContextErrorBoundary } from "../../platform/errors/context-error-boundary.tsx"; +import { FeatureErrorBoundary } from "../../platform/errors/feature-error-boundary.tsx"; import { Button, PageHeader } from "../design-system/index.ts"; import { LocaleProvider, useLocale } from "../i18n/index.ts"; import { AppShell } from "../layouts/app-shell.tsx"; @@ -262,15 +273,25 @@ function ProtectedRoute({ ); } +type ExecutableRouteRuntime = Readonly<{ + moduleId: string; + Component: ElementType; +}>; + function RegisteredRoute({ routeId, buildId, + runtimeOverride, + paramsOverride, }: { routeId: RouteId; buildId: string; + runtimeOverride?: ExecutableRouteRuntime; + paramsOverride?: Readonly>; }) { const definition = getRoute(routeId); - const params = useParams(); + const routerParams = useParams(); + const params = paramsOverride ?? routerParams; const [search] = useSearchParams(); const location = useLocation(); const diagnostics = useApplicationDiagnostics(); @@ -283,10 +304,11 @@ function RegisteredRoute({ if (owner !== undefined && !platformRuntime.isFeatureActive(owner)) { return ; } - // The registry and the runtime table are composed from the same manifest, so - // a route without a component means the two disagree โ€” refuse rather than - // crash the shell. - const runtime = ROUTE_RUNTIME[routeId]; + // Feature executable runtimes are loaded by their bounded context. Platform + // routes still use the boot-safe global runtime table. + const platformRuntimes: Readonly> = + ROUTE_RUNTIME; + const runtime = runtimeOverride ?? platformRuntimes[routeId]; if (!runtime) return ; const parsed = parseRouteInput(routeId, params, search); if (!parsed.success) return ; @@ -326,8 +348,103 @@ function RegisteredRoute({ ); } +type ContextRouteHandle = Readonly<{ + routeId: RouteId; + runtime: ExecutableRouteRuntime; +}>; + +function isContextRouteHandle(value: unknown): value is ContextRouteHandle { + if (!value || typeof value !== "object") return false; + const handle = value as Readonly>; + const runtime = handle["runtime"]; + return ( + typeof handle["routeId"] === "string" && + !!runtime && + typeof runtime === "object" && + typeof (runtime as Readonly>)["moduleId"] === "string" && + "Component" in runtime + ); +} + +function ContextRouteGateway({ + routeModule, + buildId, +}: Readonly<{ routeModule: ContextRouteModule; buildId: string }>) { + const location = useLocation(); + const { message } = useLocale(); + const [routes, setRoutes] = useState(null); + const [failed, setFailed] = useState(false); + + useEffect(() => { + let active = true; + setRoutes(null); + setFailed(false); + void routeModule.loadRoutes().then( + (loaded) => { + if (active) setRoutes(loaded); + }, + () => { + if (active) setFailed(true); + }, + ); + return () => { + active = false; + }; + }, [routeModule]); + + const resetKey = `${location.pathname}${location.search}`; + const withinContext = (content: ReactNode) => ( + } + > + {content} + + ); + + if (failed) return ; + if (routes === null) { + return ( +
+
+ ); + } + + const selectedMatch = matchRoutes([...routes], location.pathname)?.at(-1); + if (!isContextRouteHandle(selectedMatch?.route.handle)) { + return ; + } + const handle = selectedMatch.route.handle; + // The owning feature's render failures stay inside its own boundary. + const featureId = ROUTE_FEATURE_OWNER[handle.routeId]; + const route = ( + + ); + return withinContext( + featureId === undefined ? ( + route + ) : ( + } + > + {route} + + ), + ); +} + function createRegisteredRoutes(buildId: string): RouteObject[] { - const children = Object.values(ROUTE_REGISTRY).map((definition) => { + const platformChildren = Object.values(PLATFORM_ROUTE_REGISTRY).map((definition) => { const routeId = definition.routeId as RouteId; if (definition.path === "/") { return { @@ -345,13 +462,22 @@ function createRegisteredRoutes(buildId: string): RouteObject[] { element: , }; }); + const contextChildren = createAppRouteModules(TEMPLATE_APP_MODULE).map( + (routeModule) => ({ + id: `CONTEXT:${routeModule.id}`, + path: routeModule.path, + element: ( + + ), + }), + ); return [ { id: "APP_SHELL", path: "/", element: , errorElement: , - children, + children: [...platformChildren, ...contextChildren], }, ]; } diff --git a/tests/architecture/app-build-input.test.ts b/tests/architecture/app-build-input.test.ts new file mode 100644 index 00000000..6c28bbe5 --- /dev/null +++ b/tests/architecture/app-build-input.test.ts @@ -0,0 +1,93 @@ +import { spawnSync } from "node:child_process"; +import { mkdtemp, readdir, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; + +import { afterAll, describe, expect, it } from "vitest"; + +import { inspectAppBuildInput } from "../../scripts/check-app-build-input.ts"; +import { renderContextIndex, renderFeatureIndex } from "../../scripts/generate-product-feature-index.ts"; +import { APP_A, writeFilesystemTopology } from "../scale/filesystem-topology.ts"; + +/** + * Deployable-app isolation regression gate: the build input of one app must + * never contain another app's features, whether through the generated index + * or through the production bundle. + */ +const GENERATOR = path.resolve("scripts/generate-product-feature-index.ts"); +const roots: string[] = []; + +afterAll(async () => { + await Promise.all(roots.map((root) => rm(root, { recursive: true, force: true }))); +}); + +async function multiAppRepo() { + const root = await mkdtemp(path.join(tmpdir(), "app-build-input-")); + roots.push(root); + await writeFilesystemTopology(root, { globalFeatures: 1_100 }); + const run = spawnSync(process.execPath, [GENERATOR, `--root=${root}`, `--app=${APP_A.id}`], { + encoding: "utf8", + }); + if (run.status !== 0) throw new Error(run.stderr); + return root; +} + +async function inventory(root: string, modules: readonly string[]) { + const file = path.join(root, "inventory.json"); + await writeFile(file, JSON.stringify({ schemaVersion: 1, chunks: [{ fileName: "a.js", modules }] })); + return file; +} + +describe("app build input isolation gate", () => { + it("accepts the production generator's output and an app-local bundle", async () => { + const root = await multiAppRepo(); + const bundle = await inventory(root, [ + "src/features/app-a-ctx0-f0/feature-module.ts", + "src/features/app-a-ctx1-f49/presentation/page.ts", + "src/platform/traffic/request-budget.ts", + ]); + const report = await inspectAppBuildInput(root, { bundleInventory: bundle }); + expect(report.violations).toEqual([]); + expect(report.appId).toBe(APP_A.id); + expect(report.generatedFeatureImports).toHaveLength(APP_A.contexts * APP_A.featuresPerContext); + expect(report.bundle.checked).toBe(true); + }); + + it("rejects a generator regression that imports every discovered feature", async () => { + const root = await multiAppRepo(); + const everyFeature = (await readdir(path.join(root, "src/features"))).map((directory) => ({ + id: directory, + importPath: `../features/${directory}/feature-module.ts`, + directory, + contextId: directory.replace(/-f\d+$/u, ""), + contextRoutePath: "x/*", + contextMaxFeatures: 200, + })); + await writeFile(path.join(root, "src/.generated/product-feature-index.ts"), renderFeatureIndex(everyFeature)); + await writeFile(path.join(root, "src/.generated/product-context-index.ts"), renderContextIndex(everyFeature)); + + const report = await inspectAppBuildInput(root, { bundleInventory: null }); + expect(report.violations.length).toBeGreaterThan(0); + expect(report.violations.join("\n")).toMatch(/imports feature "other-0-ctx0-f0" not owned by app app-a/); + expect(report.violations.join("\n")).toMatch(/declares context "other-0-ctx0" not owned/); + }); + + it("rejects a production bundle that contains another app's feature", async () => { + const root = await multiAppRepo(); + const bundle = await inventory(root, [ + "src/features/app-a-ctx0-f0/feature-module.ts", + "src/features/other-0-ctx3-f7/feature-module.ts", + ]); + const report = await inspectAppBuildInput(root, { bundleInventory: bundle }); + expect(report.violations).toEqual([ + 'production bundle contains feature "other-0-ctx3-f7" not owned by app app-a', + ]); + }); + + it("holds for this repository's generated indexes", async () => { + // The bundle side is gated after a fresh build (check:app-build-input:bundle). + const report = await inspectAppBuildInput(path.resolve("."), { bundleInventory: null }); + expect(report.violations).toEqual([]); + expect(report.generatedFeatureImports).toEqual(report.ownedFeatureDirectories); + }); +}); diff --git a/tests/architecture/context-lazy-loading.test.ts b/tests/architecture/context-lazy-loading.test.ts new file mode 100644 index 00000000..9673b82b --- /dev/null +++ b/tests/architecture/context-lazy-loading.test.ts @@ -0,0 +1,45 @@ +import { describe, expect, it } from "vitest"; + +import { defineDeployableAppModule } from "../../src/apps/deployable-app-module.ts"; +import { defineBoundedContextModule } from "../../src/contexts/bounded-context-module.ts"; +import { createAppRouteModules } from "../../src/platform/routing/context-route-module.ts"; + +const MAX_CONTEXTS_PER_APP = 20; + +describe("context executable lazy loading", () => { + it("does no context route composition at boot and loads only the entered context", async () => { + const loadCounts = Array.from({ length: MAX_CONTEXTS_PER_APP }, () => 0); + const contexts = loadCounts.map((_, index) => + defineBoundedContextModule({ + id: `context-${index}`, + features: [], + budget: { maxFeatures: 200 }, + route: { + path: `context-${index}/*`, + loadRoutes: async () => { + loadCounts[index] += 1; + return Object.freeze([]); + }, + }, + }), + ); + const app = defineDeployableAppModule({ + id: "scale-app", + contexts, + budget: { maxContexts: MAX_CONTEXTS_PER_APP }, + }); + + const routeModules = createAppRouteModules(app); + + expect(routeModules).toHaveLength(MAX_CONTEXTS_PER_APP); + expect(loadCounts.every((count) => count === 0)).toBe(true); + + await routeModules[7]!.loadRoutes(); + + expect(loadCounts[7]).toBe(1); + expect(loadCounts.filter((count) => count !== 0)).toEqual([1]); + + await routeModules[7]!.loadRoutes(); + expect(loadCounts[7]).toBe(1); + }); +}); diff --git a/tests/architecture/module-hierarchy.test.ts b/tests/architecture/module-hierarchy.test.ts new file mode 100644 index 00000000..e6da1f76 --- /dev/null +++ b/tests/architecture/module-hierarchy.test.ts @@ -0,0 +1,20 @@ +import { describe, expect, it } from "vitest"; +import { defineFeatureModule } from "../../src/features/feature-module.ts"; +import { defineBoundedContextModule } from "../../src/contexts/bounded-context-module.ts"; +import { defineDeployableAppModule } from "../../src/apps/deployable-app-module.ts"; + +const feature = defineFeatureModule({ id:"f", contracts:{featureId:"f"}, routes:{}, adapters:[], runtimes:[], messages:{}, contractContributions:[] }); +describe("module hierarchy", () => { + it("exposes only direct children and freezes copied arrays", () => { + const features = [feature]; + const context = defineBoundedContextModule({ id:"commerce", features, budget:{maxFeatures:200} }); + features.length = 0; + const contexts = [context]; + const app = defineDeployableAppModule({ id:"customer", contexts, budget:{maxContexts:20} }); + contexts.length = 0; + expect(context.features).toEqual([feature]); + expect(app.contexts).toEqual([context]); + expect("features" in app).toBe(false); + expect(Object.isFrozen(app.contexts)).toBe(true); + }); +}); diff --git a/tests/architecture/observability-boundaries.test.ts b/tests/architecture/observability-boundaries.test.ts new file mode 100644 index 00000000..d1e7cc98 --- /dev/null +++ b/tests/architecture/observability-boundaries.test.ts @@ -0,0 +1,114 @@ +import { readFile, readdir } from "node:fs/promises"; +import path from "node:path"; + +import { describe, expect, it } from "vitest"; + +/** + * Spec ยง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. + */ + +const ROOT = path.resolve("."); + +async function productionSources(directory = path.join(ROOT, "src")): Promise { + const files: string[] = []; + for (const entry of await readdir(directory, { withFileTypes: true })) { + const target = path.join(directory, entry.name); + if (entry.isDirectory()) files.push(...(await productionSources(target))); + else if (/\.tsx?$/u.test(entry.name) && !/\.d\.ts$/u.test(entry.name)) { + files.push(target); + } + } + return files; +} + +async function readProductionSources(): Promise { + const files = await productionSources(); + const sources = await Promise.all(files.map((file) => readFile(file, "utf8"))); + return sources.join("\n"); +} + +type DependencyRule = Readonly<{ + name: string; + from: Readonly<{ path?: string; pathNot?: string }>; + to: Readonly<{ path?: string }>; +}>; + +async function dependencyRules(): Promise { + const config = JSON.parse( + await readFile(path.join(ROOT, ".dependency-cruiser.json"), "utf8"), + ) as { forbidden: DependencyRule[] }; + return config.forbidden; +} + +const VENDOR_SDKS = [ + "@sentry/browser", + "@sentry/react", + "@datadog/browser-rum", + "@datadog/browser-logs", + "@opentelemetry/api", + "@newrelic/browser-agent", + "logrocket", + "posthog-js", +]; + +describe("observability boundaries", () => { + it("configures a rule that rejects vendor SDK imports outside adapters", async () => { + const rule = (await dependencyRules()).find( + ({ name }) => name === "observability-vendors-live-behind-adapters", + ); + expect(rule).toBeDefined(); + const from = new RegExp(rule?.from.path ?? "$^", "u"); + const fromNot = new RegExp(rule?.from.pathNot ?? "$^", "u"); + const to = new RegExp(rule?.to.path ?? "$^", "u"); + + const applies = (source: string, target: string) => + from.test(source) && !fromNot.test(source) && to.test(target); + + for (const vendor of VENDOR_SDKS) { + expect(applies("src/features/catalog/application/x.ts", vendor), vendor).toBe(true); + expect(applies("src/platform/telemetry/x.ts", vendor), vendor).toBe(true); + expect(applies("src/adapters/telemetry/vendor-transport.ts", vendor), vendor).toBe(false); + } + expect(applies("src/features/a/x.ts", "react")).toBe(false); + expect(applies("src/features/a/x.ts", "@sentry-like/other")).toBe(false); + }); + + it("finds no vendor telemetry SDK import in production sources outside adapters", async () => { + const offenders: string[] = []; + const vendorImport = + /from\s+["'](@sentry|@datadog|@opentelemetry|@newrelic|newrelic|logrocket|posthog-js|mixpanel-browser|@amplitude|@bugsnag)(\/[^"']*)?["']/u; + for (const file of await productionSources()) { + const relative = path.relative(ROOT, file).split(path.sep).join("/"); + if (relative.startsWith("src/adapters/")) continue; + if (vendorImport.test(await readFile(file, "utf8"))) offenders.push(relative); + } + expect(offenders).toEqual([]); + }); + + it("does not define installed/global unions of all feature errors or telemetry payloads", async () => { + const source = await readProductionSources(); + expect(source).not.toMatch( + /AllFeatureErrors|GlobalFeatureErrors|GlobalApplicationError|InstalledFeatureErrors|AllTelemetryEvents|AllFeatureTelemetry/u, + ); + }); + + it("keeps the platform kernel independent of concrete product modules", async () => { + const rule = (await dependencyRules()).find( + ({ name }) => name === "platform-kernel-is-product-neutral", + ); + expect(rule).toBeDefined(); + const offenders: string[] = []; + for (const file of await productionSources(path.join(ROOT, "src/platform"))) { + const relative = path.relative(ROOT, file).split(path.sep).join("/"); + if (relative.startsWith("src/platform/routing/")) continue; + const source = await readFile(file, "utf8"); + if (/from\s+["']\.\.\/\.\.\/(features|contexts|apps|adapters|bootstrap|presentation|application)\//u.test(source)) { + offenders.push(relative); + } + } + expect(offenders).toEqual([]); + }); +}); diff --git a/tests/architecture/request-fanout.test.ts b/tests/architecture/request-fanout.test.ts new file mode 100644 index 00000000..c764fc96 --- /dev/null +++ b/tests/architecture/request-fanout.test.ts @@ -0,0 +1,43 @@ +import path from "node:path"; + +import { describe, expect, it } from "vitest"; + +import { + findRequestFanout, + scanRequestFanout, +} from "../../scripts/check-request-fanout.ts"; + +describe("no per-row transport loop (frontend N+1 source gate)", () => { + it("finds no per-row dispatch in feature code or application use cases", async () => { + const result = await scanRequestFanout(path.resolve(".")); + expect(result.files).toBeGreaterThan(0); + expect(result.violations).toEqual([]); + }); + + it("rejects every forbidden fixture and accepts the bulk-read fixture", async () => { + const root = path.resolve("."); + const forbidden = await scanRequestFanout(root, ["tests/fixtures/architecture/request-fanout/forbidden"]); + const allowed = await scanRequestFanout(root, ["tests/fixtures/architecture/request-fanout/allowed"]); + expect(new Set(forbidden.violations.map((violation) => violation.file)).size).toBe(forbidden.files); + expect(forbidden.files).toBe(3); + expect(allowed.violations).toEqual([]); + }); + + it("names the dispatch and the repeating construct", async () => { + const violations = await findRequestFanout( + "inline.ts", + "export const load = (api: { get(id: string): Promise }, ids: string[]) =>\n Promise.all(ids.map((id) => api.get(id)));\n", + ); + expect(violations).toEqual([ + { file: "inline.ts", line: 2, call: "api.get()", context: ".map() callback" }, + ]); + }); + + it("honours an explicit reviewed exception on the call line", async () => { + const violations = await findRequestFanout( + "reviewed.ts", + "export async function f(http: { execute(): Promise }) {\n for (let i = 0; i < 2; i += 1) await http.execute(); // fanout-reviewed: bounded 2-step handshake\n}\n", + ); + expect(violations).toEqual([]); + }); +}); diff --git a/tests/architecture/topology-cardinality.test.ts b/tests/architecture/topology-cardinality.test.ts new file mode 100644 index 00000000..2f71aa7f --- /dev/null +++ b/tests/architecture/topology-cardinality.test.ts @@ -0,0 +1,116 @@ +import { describe, expect, it } from "vitest"; + +import { defineDeployableAppModule } from "../../src/apps/deployable-app-module.ts"; +import { defineBoundedContextModule } from "../../src/contexts/bounded-context-module.ts"; +import { defineFeatureModule } from "../../src/features/feature-module.ts"; +import { planTopologyCapacity } from "../../src/platform/cardinality/topology-capacity.ts"; + +const MAX_FEATURES_PER_CONTEXT = 200; +const MAX_CONTEXTS_PER_APP = 20; + +function fakeFeature(id: string) { + return defineFeatureModule({ + id, + contracts: { featureId: id }, + routes: {}, + adapters: [], + runtimes: [], + messages: {}, + contractContributions: [], + }); +} + +describe("topology cardinality", () => { + it("accepts direct children at the configured ceilings", () => { + const features = Array.from({ length: MAX_FEATURES_PER_CONTEXT }, (_, index) => + fakeFeature(`feature-${index}`), + ); + const contexts = Array.from({ length: MAX_CONTEXTS_PER_APP }, (_, index) => + defineBoundedContextModule({ + id: `context-${index}`, + features, + budget: { maxFeatures: MAX_FEATURES_PER_CONTEXT }, + }), + ); + + expect(() => + defineDeployableAppModule({ + id: "scale-ceiling-app", + contexts, + budget: { maxContexts: MAX_CONTEXTS_PER_APP }, + }), + ).not.toThrow(); + }); + + it("rejects a context above its feature budget", () => { + expect(() => + defineBoundedContextModule({ + id: "commerce", + features: Array.from({ length: 201 }, (_, index) => fakeFeature(`f${index}`)), + budget: { maxFeatures: MAX_FEATURES_PER_CONTEXT }, + }), + ).toThrow(/commerce.*201.*200/); + }); + + it("rejects duplicate direct child ids", () => { + const context = defineBoundedContextModule({ + id: "commerce", + features: [], + budget: { maxFeatures: MAX_FEATURES_PER_CONTEXT }, + }); + + expect(() => + defineDeployableAppModule({ + id: "customer", + contexts: [context, context], + budget: { maxContexts: MAX_CONTEXTS_PER_APP }, + }), + ).toThrow(/Duplicate.*commerce/); + }); +}); + +describe("extreme-scale topology capacity", () => { + const cases = [ + { featureCount: 100, expectedContexts: 1, expectedApps: 1 }, + { featureCount: 1_000, expectedContexts: 5, expectedApps: 1 }, + { featureCount: 10_000, expectedContexts: 50, expectedApps: 3 }, + { featureCount: 100_000, expectedContexts: 500, expectedApps: 25 }, + { featureCount: 1_000_000, expectedContexts: 5_000, expectedApps: 250 }, + ] as const; + + it.each(cases)( + "partitions $featureCount features without exceeding direct-child budgets", + ({ featureCount, expectedContexts, expectedApps }) => { + const plan = planTopologyCapacity({ + featureCount, + maxFeaturesPerContext: MAX_FEATURES_PER_CONTEXT, + maxContextsPerApp: MAX_CONTEXTS_PER_APP, + }); + + expect(plan.contextCount).toBe(expectedContexts); + expect(plan.appCount).toBe(expectedApps); + expect(plan.maxFeaturesInAnyContext).toBeLessThanOrEqual(MAX_FEATURES_PER_CONTEXT); + expect(plan.maxContextsInAnyApp).toBeLessThanOrEqual(MAX_CONTEXTS_PER_APP); + expect(plan.totalFeatureCapacity).toBeGreaterThanOrEqual(featureCount); + expect(plan.totalFeatureCapacity - featureCount).toBeLessThan( + MAX_FEATURES_PER_CONTEXT * MAX_CONTEXTS_PER_APP, + ); + }, + ); + + it("keeps a zero-feature product as one deployable app with no contexts", () => { + expect( + planTopologyCapacity({ + featureCount: 0, + maxFeaturesPerContext: MAX_FEATURES_PER_CONTEXT, + maxContextsPerApp: MAX_CONTEXTS_PER_APP, + }), + ).toMatchObject({ + featureCount: 0, + contextCount: 0, + appCount: 1, + maxFeaturesInAnyContext: 0, + maxContextsInAnyApp: 0, + }); + }); +}); diff --git a/tests/component/application-mutation-admission.test.tsx b/tests/component/application-mutation-admission.test.tsx index afe60ded..64d7c43e 100644 --- a/tests/component/application-mutation-admission.test.tsx +++ b/tests/component/application-mutation-admission.test.tsx @@ -8,6 +8,7 @@ import { useApplicationMutation, } from "../../src/presentation/adapters/query/application-query.ts"; import type { MutationIntentFactory } from "../../src/application/ports/mutation-intent-factory.ts"; +import { MUTATION_COORDINATOR_BOUNDS } from "../../src/contracts/server-state.ts"; import { RESOURCE_INVALIDATION_TOPIC, deterministicMutationIntentFactory, @@ -160,6 +161,62 @@ describe("application mutation intent admission", () => { await act(() => first); }); + it("bounds JOIN_IDENTICAL waiters without starting another mutation", async () => { + const client = queryClient(); + const scope = scopeSnapshot(); + let complete: (value: ApplicationResult) => void = () => {}; + const execute = vi.fn( + () => + new Promise>((resolve) => { + complete = resolve; + }), + ); + const hook = renderHook( + () => + useApplicationMutation({ + definitionId: "joined-waiter-budget-v1", + definitionVersion: 1, + operationId: "CREATE_JOINED_BOUNDED", + requiresIdempotencyKey: true, + owner: "platform-test", + duplicatePolicy: "JOIN_IDENTICAL", + scope, + execute, + invalidate: [], + }), + { wrapper: wrapper(client) }, + ); + + let admitted: Promise> | null = null; + let joined: readonly Promise>[] = []; + let overflow: Promise> | null = null; + act(() => { + admitted = hook.result.current.submit("same-input"); + joined = Array.from( + { length: MUTATION_COORDINATOR_BOUNDS.waitersPerJoinedIntent }, + () => hook.result.current.submit("same-input"), + ); + overflow = hook.result.current.submit("same-input"); + }); + + expect(joined.every((waiter) => waiter === admitted)).toBe(true); + expect(overflow).not.toBe(admitted); + if (!overflow) throw new Error("expected overflow result"); + await expect(overflow).resolves.toMatchObject({ + ok: false, + error: { + kind: "DUPLICATE_IN_FLIGHT", + code: "JOIN_WAITER_LIMIT_EXCEEDED", + effect: "NOT_STARTED", + }, + }); + await waitFor(() => expect(execute).toHaveBeenCalledOnce()); + + complete({ ok: true, value: "same-input" }); + if (!admitted) throw new Error("expected admitted mutation"); + await act(() => admitted); + }); + it("keeps the legacy raw mutation path outside the intent factory", async () => { const client = queryClient(); const createIntent = vi.fn(); diff --git a/tests/component/application-query-bridge.test.tsx b/tests/component/application-query-bridge.test.tsx index e76bed99..c22f766d 100644 --- a/tests/component/application-query-bridge.test.tsx +++ b/tests/component/application-query-bridge.test.tsx @@ -47,6 +47,68 @@ describe("application query inbound bridge", () => { expect(execute).toHaveBeenCalledTimes(3); }); + it("coalesces repeated manual retries while stale data is refetching", async () => { + const client = queryClient(); + const pending: Array< + (value: ApplicationResult) => void + > = []; + const execute = vi.fn( + ({ signal }: Readonly<{ signal: AbortSignal }>) => { + if (execute.mock.calls.length === 1) { + return Promise.resolve({ ok: true as const, value: ["first"] }); + } + return new Promise>((resolve) => { + pending.push(resolve); + signal.addEventListener( + "abort", + () => resolve({ ok: true, value: ["aborted"] }), + { once: true }, + ); + }); + }, + ); + const hook = renderHook( + () => + useApplicationQuery({ + queryKey: ["resource", "manual-retry-coalescing"], + execute, + }), + { wrapper: wrapper(client) }, + ); + + await waitFor(() => expect(hook.result.current.data).toEqual(["first"])); + + let firstRetry: Promise = Promise.resolve(); + act(() => { + firstRetry = hook.result.current.retry(); + }); + await waitFor(() => expect(execute).toHaveBeenCalledTimes(2)); + + let secondRetry: Promise = Promise.resolve(); + act(() => { + secondRetry = hook.result.current.retry(); + }); + await act(async () => { + await Promise.resolve(); + await Promise.resolve(); + }); + + const callsWhileActive = execute.mock.calls.length; + const physicalRefetches = pending.length; + act(() => { + for (const resolve of pending) { + resolve({ ok: true, value: ["recovered"] }); + } + }); + await act(() => Promise.all([firstRetry, secondRetry])); + await waitFor(() => + expect(hook.result.current.data).toEqual(["recovered"]), + ); + + expect(callsWhileActive).toBe(2); + expect(physicalRefetches).toBe(1); + }); + it("projects an initial application failure into terminal state", async () => { const client = queryClient(); const failure = createFailure("FORBIDDEN", "LIST", 0); diff --git a/tests/features/feature-installation-surface.test.ts b/tests/features/feature-installation-surface.test.ts new file mode 100644 index 00000000..7c3fcb1d --- /dev/null +++ b/tests/features/feature-installation-surface.test.ts @@ -0,0 +1,8 @@ +import { readFile } from "node:fs/promises"; +import { describe, expect, it } from "vitest"; +const files=["installed-product-manifest.ts","installed-feature-adapters.ts","installed-feature-runtimes.tsx","installed-feature-messages.ts","installed-contract-contributions.ts","installed-feature-contracts.ts"]; +describe("feature installation surface", () => { + it("contains no reference-specific central imports", async () => { + for(const name of files){const source=await readFile(new URL(`../../src/features/${name}`,import.meta.url),"utf8"); expect(source).not.toMatch(/REFERENCE_FEATURE_(ADAPTER|RUNTIME|CONTRACT)/); expect(source).not.toMatch(/REFERENCE_MESSAGE_CATALOGS/);} + }); +}); diff --git a/tests/features/feature-module.test.ts b/tests/features/feature-module.test.ts new file mode 100644 index 00000000..807e7302 --- /dev/null +++ b/tests/features/feature-module.test.ts @@ -0,0 +1,14 @@ +import { describe, expect, it } from "vitest"; +import { defineFeatureModule } from "../../src/features/feature-module.ts"; + +describe("defineFeatureModule", () => { + it("keeps one stable feature id and freezes the descriptor", () => { + const module = defineFeatureModule({ + id: "feature-a", + contracts: { featureId: "feature-a" }, + routes: {}, adapters: [], runtimes: [], messages: {}, contractContributions: [], + }); + expect(module.id).toBe("feature-a"); + expect(Object.isFrozen(module)).toBe(true); + }); +}); diff --git a/tests/features/product-features-scale.test.ts b/tests/features/product-features-scale.test.ts new file mode 100644 index 00000000..e9646707 --- /dev/null +++ b/tests/features/product-features-scale.test.ts @@ -0,0 +1,11 @@ +import { describe, expect, it } from "vitest"; +import { resolveProductFeatures, selectCompiledProductFeatures } from "../../src/contracts/product-features.ts"; +describe("product feature membership", () => { + it("preserves selection semantics", () => { + const compiled = [{featureId:"reference"},{featureId:"local-draft"}] as const; + expect(selectCompiledProductFeatures(compiled,"reference").map(x=>x.featureId)).toEqual(["reference"]); + }); + it("resolves installed state", () => { + expect(resolveProductFeatures(["reference","local-draft"],["reference"]).map(x=>x.state)).toEqual(["NOT_INSTALLED","ACTIVE"]); + }); +}); diff --git a/tests/features/reference-feature/feature-module.test.ts b/tests/features/reference-feature/feature-module.test.ts new file mode 100644 index 00000000..2fd238c8 --- /dev/null +++ b/tests/features/reference-feature/feature-module.test.ts @@ -0,0 +1,14 @@ +import { describe, expect, it } from "vitest"; +import { REFERENCE_FEATURE_MODULE } from "../../../src/features/reference-feature/feature-module.ts"; + +describe("REFERENCE_FEATURE_MODULE", () => { + it("owns every install-time contribution under one feature id", () => { + expect(REFERENCE_FEATURE_MODULE.id).toBe("reference-feature"); + expect(REFERENCE_FEATURE_MODULE.contracts).toBeDefined(); + expect(REFERENCE_FEATURE_MODULE.routes).toBeDefined(); + expect(REFERENCE_FEATURE_MODULE.adapters.length).toBeGreaterThan(0); + expect(REFERENCE_FEATURE_MODULE.runtimes.length).toBeGreaterThan(0); + expect(REFERENCE_FEATURE_MODULE.messages).toBeDefined(); + expect(REFERENCE_FEATURE_MODULE.contractContributions.length).toBeGreaterThan(0); + }); +}); diff --git a/tests/features/reference-feature/installed-context-routing.test.ts b/tests/features/reference-feature/installed-context-routing.test.ts new file mode 100644 index 00000000..64b98ec1 --- /dev/null +++ b/tests/features/reference-feature/installed-context-routing.test.ts @@ -0,0 +1,24 @@ +import { describe, expect, it } from "vitest"; + +import { TEMPLATE_APP_MODULE } from "../../../src/apps/template-app.ts"; +import { createAppRouteModules } from "../../../src/platform/routing/context-route-module.ts"; + +describe("installed context routing", () => { + it("boots one bounded-context entry instead of flattening feature routes", () => { + const modules = createAppRouteModules(TEMPLATE_APP_MODULE); + expect(modules.map((module) => module.id)).toEqual(["reference-context"]); + expect(modules.some((module) => module.id === "REFERENCE_RESOURCE_LIST")).toBe(false); + }); + + it("loads the reference feature routes lazily without changing public URLs", async () => { + const [context] = createAppRouteModules(TEMPLATE_APP_MODULE); + expect(context).toBeDefined(); + const routes = await context!.loadRoutes(); + expect(routes.map((route) => [route.id, route.path])).toEqual([ + ["REFERENCE_RESOURCE_LIST", "/examples/reference-resources"], + ["REFERENCE_RESOURCE_DETAIL", "/examples/reference-resources/:resourceId"], + ["REFERENCE_RESOURCE_FORM", "/examples/reference-resources/new"], + ["REFERENCE_RESOURCE_STATUS", "/examples/reference-resources/status"], + ]); + }); +}); diff --git a/tests/features/reference-feature/reference-error.test.ts b/tests/features/reference-feature/reference-error.test.ts new file mode 100644 index 00000000..9d459448 --- /dev/null +++ b/tests/features/reference-feature/reference-error.test.ts @@ -0,0 +1,62 @@ +import { readFile, readdir } from "node:fs/promises"; +import path from "node:path"; + +import { describe, expect, it } from "vitest"; + +import { createFailure } from "../../../src/contracts/errors.ts"; +import { isAppError } from "../../../src/platform/errors/app-error.ts"; +import { + REFERENCE_ERRORS, + toReferenceError, + type ReferenceError, +} from "../../../src/features/reference-feature/application/reference-error.ts"; + +describe("reference feature-local errors", () => { + it("keeps concrete error kinds feature-local", () => { + const error: ReferenceError = { + kind: "reference.not-found", + category: "domain", + severity: "warning", + retryability: "never", + }; + + expect(isAppError(error)).toBe(true); + for (const known of Object.values(REFERENCE_ERRORS)) { + expect(isAppError(known)).toBe(true); + } + }); + + it("interprets only its own domain outcomes", () => { + expect(toReferenceError(createFailure("NOT_FOUND", "GET_REFERENCE_RESOURCE", 0))).toBe( + REFERENCE_ERRORS.NOT_FOUND, + ); + expect(toReferenceError(createFailure("CONFLICT", "CREATE_REFERENCE_RESOURCE", 0))).toBe( + REFERENCE_ERRORS.CONFLICT, + ); + expect( + toReferenceError(createFailure("NETWORK_UNREACHABLE", "GET_REFERENCE_RESOURCE", 0)), + ).toBeNull(); + }); + + it("is not referenced by any global or central error union", async () => { + const offenders: string[] = []; + const walk = async (directory: string): Promise => { + for (const entry of await readdir(directory, { withFileTypes: true })) { + const target = path.join(directory, entry.name); + if (entry.isDirectory()) { + if (!target.endsWith(path.join("features", "reference-feature"))) { + await walk(target); + } + continue; + } + if (!/\.tsx?$/u.test(entry.name)) continue; + const source = await readFile(target, "utf8"); + if (/reference-error\.ts|ReferenceError\b(?!Boundary)/u.test(source)) { + offenders.push(target); + } + } + }; + await walk(path.resolve("src")); + expect(offenders).toEqual([]); + }); +}); diff --git a/tests/features/reference-feature/reference-request-deduplication.test.ts b/tests/features/reference-feature/reference-request-deduplication.test.ts new file mode 100644 index 00000000..409ea898 --- /dev/null +++ b/tests/features/reference-feature/reference-request-deduplication.test.ts @@ -0,0 +1,78 @@ +import { describe, expect, it, vi } from "vitest"; + +import { + createQueryClient, + QUERY_CACHE_DEFAULTS, +} from "../../../src/adapters/query-cache/tanstack-query-cache.ts"; +import { + jsonRows, + networkFailure, + type Transport, +} from "../../helpers/traffic-test-kit.ts"; +import { referenceFeatureOver } from "./reference-traffic-kit.ts"; + +/** + * Spec ยง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. + */ +describe("request deduplication and coalescing", () => { + function loadSameQuery( + client: ReturnType, + reference: ReturnType, + key: readonly unknown[] = ["reference", "list", { limit: 20 }], + ) { + return client.fetchQuery({ + queryKey: key, + queryFn: ({ signal }) => reference.listResources({ limit: 20 }, { signal }), + }); + } + + it("coalesces concurrent consumers of the same query identity", async () => { + const transport = vi.fn(async () => jsonRows(3)); + const reference = referenceFeatureOver(transport); + const client = createQueryClient(); + + const results = await Promise.all([ + loadSameQuery(client, reference), + loadSameQuery(client, reference), + loadSameQuery(client, reference), + ]); + + expect(transport).toHaveBeenCalledTimes(1); + expect(results.every((result) => result.ok)).toBe(true); + client.clear(); + }); + + it("keeps distinct query identities as distinct physical requests", async () => { + const transport = vi.fn(async () => jsonRows(1)); + const reference = referenceFeatureOver(transport); + const client = createQueryClient(); + + await Promise.all([ + loadSameQuery(client, reference, ["reference", "list", 1]), + loadSameQuery(client, reference, ["reference", "list", 2]), + ]); + + expect(transport).toHaveBeenCalledTimes(2); + client.clear(); + }); + + it("does not stack a query-layer retry on top of the executor retry budget", async () => { + expect(QUERY_CACHE_DEFAULTS.retry).toBe(false); + expect(QUERY_CACHE_DEFAULTS.mutationRetry).toBe(false); + + const transport = vi.fn(networkFailure); + const reference = referenceFeatureOver(transport, { maxRetryAttempts: 2 }); + const client = createQueryClient(); + + await Promise.all([ + loadSameQuery(client, reference), + loadSameQuery(client, reference), + ]); + + // One coalesced logical execution: 1 attempt + at most 2 executor retries. + expect(transport.mock.calls.length).toBeLessThanOrEqual(3); + client.clear(); + }); +}); diff --git a/tests/features/reference-feature/reference-request-fanout.test.ts b/tests/features/reference-feature/reference-request-fanout.test.ts new file mode 100644 index 00000000..0d5e759f --- /dev/null +++ b/tests/features/reference-feature/reference-request-fanout.test.ts @@ -0,0 +1,86 @@ +import { describe, expect, it, vi } from "vitest"; + +import { + assertRequestFanoutWithinBudget, + RequestFanoutExceededError, +} from "../../../src/platform/traffic/request-fanout.ts"; +import { + jsonRows, + paginatedCollection, + testExecutionContext, + type Transport, +} from "../../helpers/traffic-test-kit.ts"; +import { referenceFeatureOver } from "./reference-traffic-kit.ts"; + +/** Physical requests one representative collection load may cost. */ +const COLLECTION_LOAD_FANOUT_BUDGET = 1; + +describe("request fan-out budget", () => { + it.each([10, 50, 100, 1_000])( + "loads the first page of a %i-row collection with one physical request", + async (totalRows) => { + const transport = paginatedCollection(totalRows); + const reference = referenceFeatureOver(transport); + + const result = await reference.listResources({ limit: 100 }); + + expect(result).toMatchObject({ ok: true }); + expect(result.ok && result.value).toHaveLength(Math.min(totalRows, 100)); + expect(() => + assertRequestFanoutWithinBudget(transport.calls, COLLECTION_LOAD_FANOUT_BUDGET), + ).not.toThrow(); + }, + ); + + it("walks a 1,000-row collection in page-sized bulk requests, never one per row", async () => { + const transport = paginatedCollection(1_000); + const reference = referenceFeatureOver(transport); + const rows: unknown[] = []; + for (let cursor = 0; ; cursor += 100) { + const page = await reference.listResources({ + limit: 100, + ...(cursor === 0 ? {} : { cursor: String(cursor) }), + }); + expect(page.ok).toBe(true); + if (!page.ok || page.value.length === 0) break; + rows.push(...page.value); + if (page.value.length < 100) break; + } + expect(rows).toHaveLength(1_000); + // ceil(N / pageSize) + one empty terminal page, versus N per-row calls. + expect(transport.calls).toBeLessThanOrEqual(Math.ceil(1_000 / 100) + 1); + }); + + it("rejects a single oversized response in one request without row-proportional fan-out", async () => { + const transport = vi.fn(async () => jsonRows(1_000)); + const reference = referenceFeatureOver(transport); + + const result = await reference.listResources({ limit: 100 }); + + expect(result.ok).toBe(false); + expect(transport).toHaveBeenCalledTimes(1); + }); + + it("keeps a whole interaction's request count bounded while cardinality grows", async () => { + const counts: number[] = []; + for (const rows of [10, 100, 1_000]) { + const transport = vi.fn(paginatedCollection(rows)); + const reference = referenceFeatureOver(transport); + const execution = testExecutionContext({ maxPhysicalRequests: 3 }); + await reference.listResources({ limit: 100 }, { execution }); + counts.push(transport.mock.calls.length); + expect(execution.traffic.requests.consumed).toBe(transport.mock.calls.length); + } + expect(new Set(counts)).toEqual(new Set([1])); + }); + + it("fails loudly when a flow exceeds its fan-out budget", () => { + expect(() => assertRequestFanoutWithinBudget(4, 3)).toThrow( + RequestFanoutExceededError, + ); + expect(() => assertRequestFanoutWithinBudget(4, 3)).toThrow( + /fan-out 4 exceeds 3/, + ); + expect(() => assertRequestFanoutWithinBudget(1, 0)).toThrow(TypeError); + }); +}); diff --git a/tests/features/reference-feature/reference-telemetry.test.ts b/tests/features/reference-feature/reference-telemetry.test.ts new file mode 100644 index 00000000..d238297d --- /dev/null +++ b/tests/features/reference-feature/reference-telemetry.test.ts @@ -0,0 +1,69 @@ +import { describe, expect, it, vi } from "vitest"; + +import { createReferenceFeatureInput } from "../../../src/features/reference-feature/application/reference-feature-api.ts"; +import { createFailure } from "../../../src/contracts/errors.ts"; +import type { TelemetryPort } from "../../../src/platform/telemetry/telemetry-port.ts"; +import { createTelemetryPipeline } from "../../../src/platform/telemetry/telemetry-pipeline.ts"; +import { REFERENCE_FEATURE_ADAPTER_CONTRIBUTION } from "../../../src/features/reference-feature/adapters/create-reference-feature-input.ts"; + +function failingGateway() { + const failure = Object.freeze({ + ok: false as const, + error: createFailure("REQUEST_TIMEOUT", "LIST_REFERENCE_RESOURCES", 0), + }); + return Object.freeze({ + list: vi.fn(async () => failure), + get: vi.fn(async () => failure), + create: vi.fn(async () => failure), + }); +} + +describe("reference feature telemetry through the platform port", () => { + it("declares the provider-neutral telemetry capability", () => { + expect(REFERENCE_FEATURE_ADAPTER_CONTRIBUTION.needs).toContain("telemetry"); + }); + + it("emits a feature-owned event with a bounded payload on load failure", async () => { + const emit = vi.fn(); + const input = createReferenceFeatureInput(failingGateway(), { telemetry: { emit } }); + + const result = await input.listResources({ limit: 20 }); + + expect(result.ok).toBe(false); + expect(emit).toHaveBeenCalledWith({ + kind: "reference.load.failed", + severity: "warning", + featureId: "reference-feature", + payload: { operation: "list", reason: "REQUEST_TIMEOUT" }, + }); + }); + + it("returns the business result even when the port throws or rejects", async () => { + const throwing = createReferenceFeatureInput(failingGateway(), { + telemetry: { + emit() { + throw new Error("port broken"); + }, + }, + }); + const rejecting = createReferenceFeatureInput(failingGateway(), { + telemetry: { emit: () => Promise.reject(new Error("collector down")) }, + }); + + await expect(throwing.getResource("id-1")).resolves.toMatchObject({ ok: false }); + await expect(rejecting.getResource("id-1")).resolves.toMatchObject({ ok: false }); + }); + + it("collapses a failure storm into bounded sends via the pipeline", async () => { + const send = vi.fn(); + const pipeline = createTelemetryPipeline({ transport: { send } }); + const input = createReferenceFeatureInput(failingGateway(), { telemetry: pipeline }); + + for (let i = 0; i < 500; i += 1) await input.listResources({ limit: 20 }); + await pipeline.flush(); + + expect(send).toHaveBeenCalledTimes(1); + expect(pipeline.stats().deduplicated).toBe(499); + pipeline.dispose(); + }); +}); diff --git a/tests/features/reference-feature/reference-traffic-kit.ts b/tests/features/reference-feature/reference-traffic-kit.ts new file mode 100644 index 00000000..8ba9f024 --- /dev/null +++ b/tests/features/reference-feature/reference-traffic-kit.ts @@ -0,0 +1,36 @@ +import { createReferenceFeatureInstalledInput } from "../../../src/features/reference-feature/adapters/create-reference-feature-input.ts"; +import { + scopeSnapshot, + testExecutor, + type Transport, +} from "../../helpers/traffic-test-kit.ts"; + +/** + * The reference feature's real application input, wired to the real V3 + * executor over an injected transport. Used to prove collection loads and + * multi-operation interactions stay bounded end to end. + */ +export function referenceFeatureOver( + transport: Transport, + options: Parameters[1] = {}, +) { + const executor = testExecutor(transport, { + credentialHeaders: { authorization: "Bearer traffic-test-token" }, + ...options, + }); + return createReferenceFeatureInstalledInput({ + http: Object.freeze({ + execute(operation, input, context) { + return executor.execute(operation, input, { + routeId: context.routeId, + scope: scopeSnapshot(), + ...(context.signal === undefined ? {} : { signal: context.signal }), + ...(context.intent === undefined ? {} : { intent: context.intent }), + ...(context.execution === undefined + ? {} + : { execution: context.execution }), + }); + }, + }), + }).input; +} diff --git a/tests/features/reference-feature/reference-traffic-policy.test.ts b/tests/features/reference-feature/reference-traffic-policy.test.ts new file mode 100644 index 00000000..18256539 --- /dev/null +++ b/tests/features/reference-feature/reference-traffic-policy.test.ts @@ -0,0 +1,26 @@ +import { describe, expect, it } from "vitest"; + +import { composeContractContributions } from "../../../src/contracts/external-contract-runtime.ts"; +import { REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION } from "../../../src/features/reference-feature/contracts/reference-feature-contract-contribution.ts"; + +describe("reference operation traffic policy", () => { + it("declares explicit bounded traffic on every representative reference operation", () => { + const composed = composeContractContributions([ + REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION, + ]); + for (const operationId of [ + "LIST_REFERENCE_RESOURCES", + "GET_REFERENCE_RESOURCE", + "CREATE_REFERENCE_RESOURCE", + ]) { + const traffic = composed.httpByOperationId.get(operationId)?.frontend.traffic; + expect(traffic, operationId).toBeDefined(); + expect(Number.isSafeInteger(traffic?.maxPhysicalRequests)).toBe(true); + } + // A KEYED command never retries automatically; its policy says so too. + expect( + composed.httpByOperationId.get("CREATE_REFERENCE_RESOURCE")?.frontend + .traffic, + ).toMatchObject({ maxPhysicalRequests: 1, maxRetries: 0 }); + }); +}); diff --git a/tests/fixtures/architecture/dependency-graph/cross-boundary/contexts/admin/value.ts b/tests/fixtures/architecture/dependency-graph/cross-boundary/contexts/admin/value.ts new file mode 100644 index 00000000..9f4f272e --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/cross-boundary/contexts/admin/value.ts @@ -0,0 +1 @@ +export const adminValue = 1; diff --git a/tests/fixtures/architecture/dependency-graph/cross-boundary/contexts/customer/read-admin.ts b/tests/fixtures/architecture/dependency-graph/cross-boundary/contexts/customer/read-admin.ts new file mode 100644 index 00000000..607d2b25 --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/cross-boundary/contexts/customer/read-admin.ts @@ -0,0 +1,2 @@ +import { adminValue } from "../admin/value.ts"; +export const customerValue = adminValue; diff --git a/tests/fixtures/architecture/dependency-graph/cross-boundary/features/alpha/read-beta.ts b/tests/fixtures/architecture/dependency-graph/cross-boundary/features/alpha/read-beta.ts new file mode 100644 index 00000000..eb010512 --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/cross-boundary/features/alpha/read-beta.ts @@ -0,0 +1,2 @@ +import { betaValue } from "../beta/value.ts"; +export const alphaValue = betaValue; diff --git a/tests/fixtures/architecture/dependency-graph/cross-boundary/features/beta/value.ts b/tests/fixtures/architecture/dependency-graph/cross-boundary/features/beta/value.ts new file mode 100644 index 00000000..2bb129e9 --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/cross-boundary/features/beta/value.ts @@ -0,0 +1 @@ +export const betaValue = 1; diff --git a/tests/fixtures/architecture/request-fanout/allowed/bulk-read.ts b/tests/fixtures/architecture/request-fanout/allowed/bulk-read.ts new file mode 100644 index 00000000..6074b9d8 --- /dev/null +++ b/tests/fixtures/architecture/request-fanout/allowed/bulk-read.ts @@ -0,0 +1,12 @@ +// Allowed: one bulk request, then per-row work is local mapping only. +type Gateway = { list(filters: { limit: number }): Promise }; + +export async function loadPage(gateway: Gateway) { + const rows = await gateway.list({ limit: 100 }); + return rows.map((row) => ({ ...row, label: row.id.toUpperCase() })); +} + +export function bindHandlers(gateway: Gateway, ids: readonly string[]) { + // Declaring a function per row is fine; it dispatches only when a user acts. + return ids.map((id) => () => gateway.list({ limit: id.length })); +} diff --git a/tests/fixtures/architecture/request-fanout/forbidden/fetch-in-foreach.ts b/tests/fixtures/architecture/request-fanout/forbidden/fetch-in-foreach.ts new file mode 100644 index 00000000..108d0aa5 --- /dev/null +++ b/tests/fixtures/architecture/request-fanout/forbidden/fetch-in-foreach.ts @@ -0,0 +1,6 @@ +// Forbidden: raw fetch per element. +export function prefetch(urls: readonly string[]) { + urls.forEach((url) => { + void fetch(url); + }); +} diff --git a/tests/fixtures/architecture/request-fanout/forbidden/loop-dispatch.ts b/tests/fixtures/architecture/request-fanout/forbidden/loop-dispatch.ts new file mode 100644 index 00000000..fc2dfb47 --- /dev/null +++ b/tests/fixtures/architecture/request-fanout/forbidden/loop-dispatch.ts @@ -0,0 +1,10 @@ +// Forbidden: a dispatch inside a loop over rows. +type Http = { execute(operation: string, input: unknown): Promise }; + +export async function loadEach(http: Http, rows: readonly { id: string }[]) { + const results: unknown[] = []; + for (const row of rows) { + results.push(await http.execute("GET_ROW", { id: row.id })); + } + return results; +} diff --git a/tests/fixtures/architecture/request-fanout/forbidden/per-row-detail.ts b/tests/fixtures/architecture/request-fanout/forbidden/per-row-detail.ts new file mode 100644 index 00000000..dc8fe0b8 --- /dev/null +++ b/tests/fixtures/architecture/request-fanout/forbidden/per-row-detail.ts @@ -0,0 +1,6 @@ +// Forbidden: one physical request per collection row (frontend N+1). +type Gateway = { get(id: string): Promise }; + +export async function loadDetails(gateway: Gateway, ids: readonly string[]) { + return Promise.all(ids.map((id) => gateway.get(id))); +} diff --git a/tests/helpers/traffic-test-kit.ts b/tests/helpers/traffic-test-kit.ts new file mode 100644 index 00000000..261fafdc --- /dev/null +++ b/tests/helpers/traffic-test-kit.ts @@ -0,0 +1,136 @@ +import { createContractHttpExecutor } from "../../src/adapters/http/http-execution-v3.ts"; +import { + createExecutionContext, + type ExecutionContext, +} from "../../src/platform/execution/execution-context.ts"; + +/** + * Shared kit for traffic-budget integration tests (Phase 2) and the scale / + * chaos scenarios (Phase 4). It drives the real V3 executor with an injected + * transport so request counts are physical dispatch counts. + */ + +export function scopeSnapshot() { + return Object.freeze({ + generation: 1, + fingerprint: "traffic-scope", + identities: Object.freeze({}) as never, + signal: new AbortController().signal, + isCurrent: () => true, + }); +} + +export type ManualClock = Readonly<{ + now(): number; + advance(ms: number): void; +}>; + +export function manualClock(start = 0): ManualClock { + let current = start; + return Object.freeze({ + now: () => current, + advance(ms: number) { + current += ms; + }, + }); +} + +/** A clock that answers the listed readings in order, then keeps the last. */ +export function fakeClock(readings: readonly number[]): () => number { + let index = 0; + return () => { + const value = readings[Math.min(index, readings.length - 1)] ?? 0; + index += 1; + return value; + }; +} + +export function testExecutionContext( + options: Readonly<{ + interactionId?: string; + deadlineMs?: number; + maxPhysicalRequests?: number; + maxRetries?: number; + maxConcurrentRequests?: number; + maxQueuedRequests?: number; + clock?: () => number; + signal?: AbortSignal; + }> = {}, +): ExecutionContext { + return createExecutionContext({ + interactionId: options.interactionId ?? "interaction-test", + deadlineMs: options.deadlineMs ?? 10_000, + traffic: { + maxPhysicalRequests: options.maxPhysicalRequests ?? 4, + maxRetries: options.maxRetries ?? 2, + maxConcurrentRequests: options.maxConcurrentRequests ?? 2, + maxQueuedRequests: options.maxQueuedRequests ?? 4, + }, + ...(options.clock === undefined ? {} : { clock: options.clock }), + ...(options.signal === undefined ? {} : { signal: options.signal }), + }); +} + +export type Transport = (input: RequestInfo | URL, init?: RequestInit) => Promise; + +export function testExecutor( + transport: Transport, + options: Readonly<{ + maxRetryAttempts?: number; + monotonicNow?: () => number; + sleep?: (ms: number, signal: AbortSignal) => Promise; + random?: () => number; + credentialHeaders?: Readonly>; + }> = {}, +) { + const headers = options.credentialHeaders ?? {}; + return createContractHttpExecutor({ + baseUrl: "https://api.test", + maxRetryAttempts: options.maxRetryAttempts ?? 2, + attachCredentials: () => ({ kind: "READY" as const, headers }), + fetcher: transport as typeof fetch, + // Backoff is not what these tests measure; resolve it immediately unless a + // scenario supplies its own sleep. + sleep: options.sleep ?? (async () => {}), + random: options.random ?? (() => 0.5), + ...(options.monotonicNow === undefined + ? {} + : { monotonicNow: options.monotonicNow }), + }); +} + +export function networkFailure(): Promise { + return Promise.reject(new TypeError("network")); +} + +export function jsonRows(count: number): Response { + return Response.json( + Array.from({ length: count }, (_, index) => ({ + id: `entity-${index}`, + name: `Entity ${index}`, + })), + ); +} + +/** + * A server-side collection of `totalRows` rows behind a bounded page API: each + * request returns at most `limit` rows starting at the numeric `cursor`. The + * collection's cardinality is independent of how many rows one page carries. + */ +export function paginatedCollection(totalRows: number): Transport & { calls: number } { + const transport = (async (input: RequestInfo | URL) => { + transport.calls += 1; + const url = new URL(String(input instanceof Request ? input.url : input)); + const limit = Number(url.searchParams.get("limit") ?? "20"); + const offset = Number(url.searchParams.get("cursor") ?? "0"); + const count = Math.max(0, Math.min(limit, totalRows - offset)); + return Response.json( + Array.from({ length: count }, (_, index) => ({ + id: `entity-${offset + index}`, + name: `Entity ${offset + index}`, + })), + ); + }) as unknown as Transport & { calls: number }; + transport.calls = 0; + return transport; +} diff --git a/tests/platform/cardinality/cardinality-budget.test.ts b/tests/platform/cardinality/cardinality-budget.test.ts new file mode 100644 index 00000000..06083291 --- /dev/null +++ b/tests/platform/cardinality/cardinality-budget.test.ts @@ -0,0 +1,7 @@ +import { describe, expect, it } from "vitest"; +import { CardinalityBudgetExceededError, assertWithinCardinalityBudget } from "../../../src/platform/cardinality/cardinality-budget.ts"; +describe("assertWithinCardinalityBudget", () => { + it("accepts the exact ceiling", () => expect(() => assertWithinCardinalityBudget("commerce.features", 200, 200)).not.toThrow()); + it("rejects values above the ceiling", () => expect(() => assertWithinCardinalityBudget("commerce.features", 201, 200)).toThrow(CardinalityBudgetExceededError)); + it("rejects invalid ceilings", () => expect(() => assertWithinCardinalityBudget("x", 0, Infinity)).toThrow(TypeError)); +}); diff --git a/tests/platform/cardinality/compose-unique-record.test.ts b/tests/platform/cardinality/compose-unique-record.test.ts new file mode 100644 index 00000000..66105591 --- /dev/null +++ b/tests/platform/cardinality/compose-unique-record.test.ts @@ -0,0 +1,6 @@ +import { describe, expect, it } from "vitest"; +import { composeUniqueRecord } from "../../../src/platform/cardinality/compose-unique-record.ts"; +describe("composeUniqueRecord", () => { + it("composes entries", () => expect(composeUniqueRecord([{a:1},{b:2}], () => "test")).toEqual({a:1,b:2})); + it("rejects duplicate keys", () => expect(() => composeUniqueRecord([{a:1},{a:2}], () => "routes")).toThrow(/Duplicate routes key: a/)); +}); diff --git a/tests/platform/cardinality/extreme-scale-registry.test.ts b/tests/platform/cardinality/extreme-scale-registry.test.ts new file mode 100644 index 00000000..255b459f --- /dev/null +++ b/tests/platform/cardinality/extreme-scale-registry.test.ts @@ -0,0 +1,112 @@ +import { performance } from "node:perf_hooks"; + +import { describe, expect, it } from "vitest"; + +import { + resolveProductFeatures, + selectCompiledProductFeatures, +} from "../../../src/contracts/product-features.ts"; +import { composeUniqueRecord } from "../../../src/platform/cardinality/compose-unique-record.ts"; + +const SMALL_REGISTRY_SIZE = 10_000; +const LARGE_REGISTRY_SIZE = 100_000; +const FEATURE_SCALE_SIZE = 100_000; +const LOOKUP_OPERATIONS = 1_000_000; +const MEASUREMENT_RUNS = 3; + +const MAX_COMPOSE_GROWTH_RATIO = 30; +const MAX_LARGE_COMPOSE_MS = 3_000; +const MAX_MEMBERSHIP_MS = 3_000; +const MAX_LOOKUP_MS = 1_500; + +function syntheticRecords(count: number): readonly Readonly>[] { + return Array.from({ length: count }, (_, index) => ({ [`key-${index}`]: index })); +} + +function median(values: readonly number[]): number { + const sorted = [...values].sort((left, right) => left - right); + return sorted[Math.floor(sorted.length / 2)] ?? Number.POSITIVE_INFINITY; +} + +function measureMedianElapsedMs(action: () => void): number { + action(); + const samples = Array.from({ length: MEASUREMENT_RUNS }, () => { + const startedAt = performance.now(); + action(); + return performance.now() - startedAt; + }); + return median(samples); +} + +function measureCompose(records: readonly Readonly>[]): Readonly<{ + elapsedMs: number; + registry: Readonly>; +}> { + let registry: Readonly> = {}; + const elapsedMs = measureMedianElapsedMs(() => { + registry = composeUniqueRecord(records, () => "synthetic registry"); + }); + return Object.freeze({ elapsedMs, registry }); +} + +describe("extreme-scale registry composition", () => { + it("keeps 10k -> 100k composition growth below a quadratic regression budget", () => { + const smallRecords = syntheticRecords(SMALL_REGISTRY_SIZE); + const largeRecords = syntheticRecords(LARGE_REGISTRY_SIZE); + const small = measureCompose(smallRecords); + const large = measureCompose(largeRecords); + const growthRatio = large.elapsedMs / Math.max(small.elapsedMs, 1); + + expect(Object.keys(small.registry)).toHaveLength(SMALL_REGISTRY_SIZE); + expect(Object.keys(large.registry)).toHaveLength(LARGE_REGISTRY_SIZE); + expect(large.elapsedMs).toBeLessThan(MAX_LARGE_COMPOSE_MS); + expect(growthRatio).toBeLessThan(MAX_COMPOSE_GROWTH_RATIO); + }); + + it("keeps one million lookups bounded on a 100k-entry runtime registry", () => { + const { registry } = measureCompose(syntheticRecords(LARGE_REGISTRY_SIZE)); + let checksum = 0; + const elapsedMs = measureMedianElapsedMs(() => { + let currentChecksum = 0; + for (let index = 0; index < LOOKUP_OPERATIONS; index += 1) { + currentChecksum += registry[`key-${index % LARGE_REGISTRY_SIZE}`] ?? -1; + } + checksum = currentChecksum; + }); + + expect(checksum).toBeGreaterThan(0); + expect(elapsedMs).toBeLessThan(MAX_LOOKUP_MS); + }); +}); + +describe("extreme-scale product feature membership", () => { + it("selects and resolves 100k feature ids within the membership budget", () => { + const compiled = Array.from({ length: FEATURE_SCALE_SIZE }, (_, index) => + Object.freeze({ featureId: `feature-${index.toString().padStart(6, "0")}` }), + ); + const requestedIds = compiled + .filter((_, index) => index % 10 === 0) + .map((feature) => feature.featureId); + const declared = requestedIds.join(","); + + let selected = compiled.slice(0, 0); + const selectionElapsedMs = measureMedianElapsedMs(() => { + selected = [...selectCompiledProductFeatures(compiled, declared)]; + }); + + let statuses = resolveProductFeatures([], []); + const installedIds = selected.map((feature) => feature.featureId); + const compiledIds = compiled.map((feature) => feature.featureId); + const resolveElapsedMs = measureMedianElapsedMs(() => { + statuses = resolveProductFeatures(compiledIds, installedIds); + }); + + expect(selected).toHaveLength(FEATURE_SCALE_SIZE / 10); + expect(statuses).toHaveLength(FEATURE_SCALE_SIZE); + expect(statuses.filter((status) => status.state === "ACTIVE")).toHaveLength( + FEATURE_SCALE_SIZE / 10, + ); + expect(selectionElapsedMs).toBeLessThan(MAX_MEMBERSHIP_MS); + expect(resolveElapsedMs).toBeLessThan(MAX_MEMBERSHIP_MS); + }); +}); diff --git a/tests/platform/errors/app-error.test.ts b/tests/platform/errors/app-error.test.ts new file mode 100644 index 00000000..8274e123 --- /dev/null +++ b/tests/platform/errors/app-error.test.ts @@ -0,0 +1,57 @@ +import { describe, expect, it } from "vitest"; + +import { + defineAppError, + isAppError, +} from "../../../src/platform/errors/app-error.ts"; + +describe("AppError envelope", () => { + it("recognizes feature-owned errors through the platform envelope", () => { + const error = { + kind: "payment.declined", + category: "domain", + severity: "warning", + retryability: "never", + } as const; + + expect(isAppError(error)).toBe(true); + }); + + it("represents an unknown feature kind without extending a central union", () => { + const unknownFeatureError = defineAppError({ + kind: "brand-new-feature.quota-reached", + category: "application", + severity: "error", + retryability: "policy", + }); + expect(isAppError(unknownFeatureError)).toBe(true); + expect(Object.isFrozen(unknownFeatureError)).toBe(true); + }); + + it.each([ + [{ kind: "no-owner", category: "domain", severity: "warning", retryability: "never" }], + [{ kind: "a.b", category: "vendor", severity: "warning", retryability: "never" }], + [{ kind: "a.b", category: "domain", severity: "fatal", retryability: "never" }], + [{ kind: "a.b", category: "domain", severity: "warning", retryability: "always" }], + [{ kind: `a.${"x".repeat(80)}`, category: "domain", severity: "info", retryability: "never" }], + [null], + ["payment.declined"], + ])("rejects a malformed envelope %#", (candidate) => { + expect(isAppError(candidate)).toBe(false); + }); + + it("never invokes accessors while classifying untrusted objects", () => { + let invoked = false; + const hostile = { + category: "domain", + severity: "warning", + retryability: "never", + get kind() { + invoked = true; + return "payment.declined"; + }, + }; + expect(isAppError(hostile)).toBe(false); + expect(invoked).toBe(false); + }); +}); diff --git a/tests/platform/errors/failure-boundary.test.tsx b/tests/platform/errors/failure-boundary.test.tsx new file mode 100644 index 00000000..34e40cfe --- /dev/null +++ b/tests/platform/errors/failure-boundary.test.tsx @@ -0,0 +1,84 @@ +// @vitest-environment jsdom + +import { render, screen } from "@testing-library/react"; +import { describe, expect, it, vi } from "vitest"; + +import { ContextErrorBoundary } from "../../../src/platform/errors/context-error-boundary.tsx"; +import { FeatureErrorBoundary } from "../../../src/platform/errors/feature-error-boundary.tsx"; + +function ThrowsOnRender(): never { + throw new Error("feature render failed"); +} + +describe("ownership-aligned failure boundaries", () => { + it("keeps sibling feature UI mounted when one feature throws during render", () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + render( + + + + +
healthy-feature
+
, + ); + + expect(screen.getByText("healthy-feature")).toBeInTheDocument(); + expect(screen.getByTestId("feature-fallback-broken")).toBeInTheDocument(); + }); + + it("keeps sibling contexts mounted when one context fails outside any feature boundary", () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + render( +
+ + + + +

account-context

+
+ +
, + ); + + expect(screen.getByTestId("context-fallback-commerce")).toBeInTheDocument(); + expect(screen.getByText("account-context")).toBeInTheDocument(); + expect(screen.getByText("app-shell")).toBeInTheDocument(); + }); + + it("reports once per contained failure and survives a throwing reporter", () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + const onError = vi.fn(() => { + throw new Error("diagnostics down"); + }); + render( + fallback

}> + +
, + ); + expect(onError).toHaveBeenCalledWith({ scope: "feature", ownerId: "broken" }); + expect(screen.getByText("fallback")).toBeInTheDocument(); + }); + + it("clears a contained failure when its reset key changes", () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + let shouldThrow = true; + function Flaky() { + if (shouldThrow) throw new Error("flaky"); + return

recovered

; + } + const view = render( + + + , + ); + expect(screen.getByTestId("feature-fallback-flaky")).toBeInTheDocument(); + + shouldThrow = false; + view.rerender( + + + , + ); + expect(screen.getByText("recovered")).toBeInTheDocument(); + }); +}); diff --git a/tests/platform/errors/platform-errors.test.ts b/tests/platform/errors/platform-errors.test.ts new file mode 100644 index 00000000..8e9422f7 --- /dev/null +++ b/tests/platform/errors/platform-errors.test.ts @@ -0,0 +1,125 @@ +import { describe, expect, it, vi } from "vitest"; + +import { platformErrorForOutcome } from "../../../src/adapters/http/platform-error-mapping.ts"; +import type { InstalledHttpContract } from "../../../src/contracts/external-contract-runtime.ts"; +import { + mapTransportFailure, + PLATFORM_ERRORS, +} from "../../../src/platform/errors/platform-errors.ts"; +import { isAppError } from "../../../src/platform/errors/app-error.ts"; +import { RequestBudgetExceededError } from "../../../src/platform/traffic/request-budget.ts"; +import { ConcurrencyQueueFullError } from "../../../src/platform/traffic/concurrency-budget.ts"; +import { DeadlineExceededError } from "../../../src/platform/resilience/deadline.ts"; +import { JsonBudgetExceededError } from "../../../src/platform/validation/bounded-json.ts"; +import { TEST_LIST_HTTP_CONTRACT } from "../../helpers/external-contract-fixture.ts"; +import { + networkFailure, + scopeSnapshot, + testExecutionContext, + testExecutor, + type Transport, +} from "../../helpers/traffic-test-kit.ts"; + +const abortError = () => new DOMException("aborted", "AbortError"); + +describe("platform error normalization", () => { + it("maps an abort caused by interaction cancellation to request.cancelled", () => { + const error = mapTransportFailure(abortError(), { deadlineExpired: false }); + + expect(error).toMatchObject({ + kind: "request.cancelled", + category: "transport", + retryability: "never", + }); + }); + + it("maps an abort caused by the deadline to request.timeout", () => { + expect(mapTransportFailure(abortError(), { deadlineExpired: true }).kind).toBe( + "request.timeout", + ); + expect( + mapTransportFailure(new DeadlineExceededError(10, 11), { + deadlineExpired: false, + }).kind, + ).toBe("request.timeout"); + }); + + it.each([ + [new TypeError("Failed to fetch"), "network.unavailable"], + [new RequestBudgetExceededError(2), "traffic.budget-exceeded"], + [new ConcurrencyQueueFullError(0), "traffic.budget-exceeded"], + [new JsonBudgetExceededError("too-large", "x"), "response.too-large"], + [new SyntaxError("Unexpected token"), "response.invalid"], + ["not even an error", "network.unavailable"], + ] as const)("maps %s to %s", (error, kind) => { + expect(mapTransportFailure(error, { deadlineExpired: false }).kind).toBe(kind); + }); + + it("keeps every platform error a valid, stable envelope", () => { + for (const error of Object.values(PLATFORM_ERRORS)) { + expect(isAppError(error)).toBe(true); + } + expect(Object.values(PLATFORM_ERRORS).map((error) => error.kind)).toEqual([ + "network.unavailable", + "request.timeout", + "request.cancelled", + "response.too-large", + "response.invalid", + "traffic.budget-exceeded", + ]); + }); +}); + +describe("V3 outcome normalization at the adapter boundary", () => { + const TEST_QUERY = TEST_LIST_HTTP_CONTRACT as InstalledHttpContract< + unknown, + unknown, + unknown + >; + + it("classifies a traffic-budget rejection as traffic.budget-exceeded", async () => { + const transport = vi.fn(networkFailure); + const execution = testExecutionContext({ maxPhysicalRequests: 1, maxRetries: 0 }); + const executor = testExecutor(transport); + const context = { routeId: "TEST_ROUTE", scope: scopeSnapshot(), execution }; + await executor.execute(TEST_QUERY, { limit: 1 }, context); + const rejected = await executor.execute(TEST_QUERY, { limit: 1 }, context); + + expect(platformErrorForOutcome(rejected)?.kind).toBe("traffic.budget-exceeded"); + }); + + it.each([ + [{ kind: "CANCELLED", effect: "NOT_STARTED" }, "request.cancelled"], + [ + { kind: "TRANSPORT_FAILURE", failure: { kind: "TIMEOUT", retryable: false }, effect: "NOT_STARTED" }, + "request.timeout", + ], + [ + { kind: "TRANSPORT_FAILURE", failure: { kind: "NETWORK_FAILURE", retryable: false }, effect: "NOT_STARTED" }, + "network.unavailable", + ], + [ + { kind: "CONTRACT_VIOLATION", violation: { kind: "RESPONSE_TOO_LARGE", operation: "RESPONSE" }, effect: "NOT_APPLICABLE" }, + "response.too-large", + ], + [ + { kind: "CONTRACT_VIOLATION", violation: { kind: "JSON_INVALID", operation: "RESPONSE" }, effect: "NOT_APPLICABLE" }, + "response.invalid", + ], + ] as const)("maps outcome %# to %s", (outcome, kind) => { + expect(platformErrorForOutcome(outcome)?.kind).toBe(kind); + }); + + it("leaves owner-interpreted outcomes to their owner", () => { + expect( + platformErrorForOutcome({ kind: "UNAUTHENTICATED", effect: "NOT_APPLICABLE" }), + ).toBeNull(); + expect( + platformErrorForOutcome({ + kind: "CONTRACT_VIOLATION", + violation: { kind: "SCOPE_FENCED", operation: "RESPONSE" }, + effect: "NOT_APPLICABLE", + }), + ).toBeNull(); + }); +}); diff --git a/tests/platform/execution/execution-context.test.ts b/tests/platform/execution/execution-context.test.ts new file mode 100644 index 00000000..aabd421d --- /dev/null +++ b/tests/platform/execution/execution-context.test.ts @@ -0,0 +1,94 @@ +import { describe, expect, it } from "vitest"; + +import { createExecutionContext } from "../../../src/platform/execution/execution-context.ts"; + +const TRAFFIC = { + maxPhysicalRequests: 4, + maxConcurrentRequests: 2, + maxRetries: 1, +} as const; + +describe("createExecutionContext", () => { + it("creates one immutable root context with one abort signal and absolute deadline", () => { + const now = 1_000; + const context = createExecutionContext({ + interactionId: "interaction-1", + startedAt: now, + deadlineMs: 5_000, + traffic: TRAFFIC, + }); + + expect(context.interaction.deadlineAt).toBe(6_000); + expect(context.cancellation.signal.aborted).toBe(false); + expect(Object.isFrozen(context.interaction)).toBe(true); + expect(Object.isFrozen(context)).toBe(true); + }); + + it("derives a finite queue bound when the caller omits one", () => { + const context = createExecutionContext({ + interactionId: "interaction-2", + deadlineMs: 1_000, + traffic: TRAFFIC, + }); + + expect(context.traffic.concurrency.maxQueued).toBe(2); + }); + + it("reports only the time left before the absolute deadline", () => { + let now = 0; + const context = createExecutionContext({ + interactionId: "interaction-3", + deadlineMs: 1_000, + traffic: TRAFFIC, + clock: () => now, + }); + + now = 400; + expect(context.remainingMs()).toBe(600); + now = 1_500; + expect(context.remainingMs()).toBe(0); + }); + + it("propagates an owner abort and cancel() to the interaction signal", () => { + const owner = new AbortController(); + const linked = createExecutionContext({ + interactionId: "interaction-4", + deadlineMs: 1_000, + traffic: TRAFFIC, + signal: owner.signal, + }); + owner.abort(); + expect(linked.cancellation.signal.aborted).toBe(true); + + const direct = createExecutionContext({ + interactionId: "interaction-5", + deadlineMs: 1_000, + traffic: TRAFFIC, + }); + direct.cancellation.cancel(); + expect(direct.cancellation.signal.aborted).toBe(true); + }); + + it.each([0, -1, Number.POSITIVE_INFINITY, 60_001, 1.5])( + "rejects an unbounded or invalid deadline %s", + (deadlineMs) => { + expect(() => + createExecutionContext({ + interactionId: "interaction-6", + deadlineMs, + traffic: TRAFFIC, + }), + ).toThrow(/deadline/); + }, + ); + + it("rejects an unsafe interaction id", () => { + expect(() => + createExecutionContext({ + interactionId: "has spaces", + deadlineMs: 1_000, + traffic: TRAFFIC, + }), + ).toThrow(/interaction id/); + }); +}); diff --git a/tests/platform/release/cache-policy.test.ts b/tests/platform/release/cache-policy.test.ts new file mode 100644 index 00000000..8e23764b --- /dev/null +++ b/tests/platform/release/cache-policy.test.ts @@ -0,0 +1,86 @@ +import { readFile } from "node:fs/promises"; +import path from "node:path"; + +import { describe, expect, it, vi } from "vitest"; + +import { loadRuntimeConfig } from "../../../src/bootstrap/load-runtime-config.ts"; +import { loadReleaseManifest } from "../../../src/bootstrap/load-release-manifest.ts"; + +type Surfaces = Record; + +async function json(relative: string): Promise { + return JSON.parse(await readFile(path.resolve(relative), "utf8")) as T; +} + +const policy = (await json<{ surfaces: Surfaces }>("config/hosting/cache-policy.json")).surfaces; +const fixtureHeaders = ( + await json<{ responses: Record> }>( + "config/hosting/response-headers.fixture.json", + ) +).responses; + +function directives(value: string | undefined): Set { + return new Set( + (value ?? "") + .split(",") + .map((entry) => entry.trim().toLowerCase()) + .filter(Boolean), + ); +} + +describe("cache-policy contract for rolling releases", () => { + it("serves hashed assets as immutable, year-long public cache entries", () => { + expect(policy["hashedAsset"]?.cacheControl).toBe("public, max-age=31536000, immutable"); + expect(policy["hashedAsset"]?.pathPattern).toBe("/assets/*"); + expect(fixtureHeaders["hashedAsset"]?.["cache-control"]).toBe( + "public, max-age=31536000, immutable", + ); + }); + + it("revalidates HTML and never marks it immutable", () => { + for (const value of [policy["index"]?.cacheControl, fixtureHeaders["index"]?.["cache-control"]]) { + const parsed = directives(value); + expect(parsed.has("immutable")).toBe(false); + expect(parsed.has("no-cache") || parsed.has("no-store") || parsed.has("max-age=0")).toBe(true); + } + }); + + it.each(["runtimeConfig", "releaseManifest"])( + "never lets %s be reused across release identity changes", + (surface) => { + expect(directives(policy[surface]?.cacheControl).has("no-store")).toBe(true); + expect(directives(fixtureHeaders[surface]?.["cache-control"]).has("no-store")).toBe(true); + expect(directives(policy[surface]?.cacheControl).has("immutable")).toBe(false); + }, + ); + + it("requests runtime config and the release manifest with cache: no-store", async () => { + const seen: RequestInit[] = []; + const fetcher = vi.fn(async (_input: RequestInfo | URL, init?: RequestInit) => { + seen.push(init ?? {}); + return new Response("{}", { headers: { "content-type": "application/json" } }); + }); + const buildConfig = Object.freeze({ + buildId: "build-a", + commitSha: "abc", + routerBasePath: "/", + runtimeConfigUrl: "/config.json", + }); + await loadRuntimeConfig({ buildConfig, fetcher }).catch(() => undefined); + await loadReleaseManifest( + { + build: buildConfig, + config: { + RELEASE_MANIFEST_URL: "/release-manifest.json", + CONFIG_SCHEMA_VERSION: "2.0", + } as never, + configSchema: "V2", + validationDurationMs: 0, + }, + { fetcher }, + ).catch(() => undefined); + + expect(seen).toHaveLength(2); + expect(seen.every((init) => init.cache === "no-store")).toBe(true); + }); +}); diff --git a/tests/platform/release/release-coherence.test.ts b/tests/platform/release/release-coherence.test.ts new file mode 100644 index 00000000..862b6be6 --- /dev/null +++ b/tests/platform/release/release-coherence.test.ts @@ -0,0 +1,87 @@ +import { describe, expect, it } from "vitest"; + +import { + assertReleaseCoherent, + checkReleaseCoherence, + ReleaseMismatchError, +} from "../../../src/platform/release/release-coherence.ts"; + +function identity(release: string) { + return Object.freeze({ + buildId: `build-${release}`, + releaseId: `release-${release}`, + configSchemaVersion: "2.0", + assetManifestHash: `assets-${release}`, + }); +} + +describe("assertReleaseCoherent", () => { + it.each([ + ["R10", "R10", "R10", true], + ["R10", "R11", "R10", false], + ["R10", "R10", "R11", false], + ["R11", "R11", "R11", true], + ["R11", "R10", "R10", false], + ["R10", "R11", "R11", false], + ])( + "HTML %s config %s manifest %s => coherent=%s", + (html, config, manifest, coherent) => { + const run = () => + assertReleaseCoherent( + identity(html), + identity(config), + identity(manifest), + ); + + if (coherent) expect(run).not.toThrow(); + else expect(run).toThrow(/release.*mismatch/i); + }, + ); + + it("reports the first incoherent field in the boot precedence order", () => { + const result = checkReleaseCoherence({ + html: { buildId: "b1", assetManifestHash: "a1" }, + config: { buildId: "b1", configSchemaVersion: "2.0", releaseId: "r2" }, + manifest: { + buildId: "b1", + configSchemaVersion: "2.1", + releaseId: "r1", + assetManifestHash: "a2", + }, + }); + expect(result).toEqual({ + coherent: false, + field: "configSchemaVersion", + sources: ["config", "manifest"], + }); + }); + + it("compares only fields that two sources both carry", () => { + expect( + checkReleaseCoherence({ + html: { buildId: "b1" }, + config: { buildId: "b1" }, + manifest: { buildId: "b1", releaseId: "r1", assetManifestHash: "a" }, + }), + ).toEqual({ coherent: true }); + }); + + it("fails closed when HTML or manifest cannot name its build", () => { + expect(() => + assertReleaseCoherent({}, identity("R10"), identity("R10")), + ).toThrow(ReleaseMismatchError); + expect(() => + assertReleaseCoherent(identity("R10"), identity("R10"), { releaseId: "release-R10" }), + ).toThrow(ReleaseMismatchError); + }); + + it("exposes which field and sources disagreed", () => { + try { + assertReleaseCoherent(identity("R10"), identity("R11"), identity("R10")); + expect.unreachable(); + } catch (error) { + expect(error).toBeInstanceOf(ReleaseMismatchError); + expect(error).toMatchObject({ field: "buildId", sources: ["html", "config"] }); + } + }); +}); diff --git a/tests/platform/release/release-mismatch-recovery.test.ts b/tests/platform/release/release-mismatch-recovery.test.ts new file mode 100644 index 00000000..01a7c4e2 --- /dev/null +++ b/tests/platform/release/release-mismatch-recovery.test.ts @@ -0,0 +1,166 @@ +import { describe, expect, it } from "vitest"; + +import { + createReleaseMismatchRecovery, + type RecoveryMarkerStore, +} from "../../../src/platform/release/release-mismatch-recovery.ts"; +import { + createBootReleaseRecovery, + decideBootFailure, + releaseMismatchKey, +} from "../../../src/bootstrap/boot-release-recovery.ts"; +import { ReleaseManifestError } from "../../../src/bootstrap/load-release-manifest.ts"; +import { BootConfigError } from "../../../src/bootstrap/load-runtime-config.ts"; +import { STORAGE_REGISTRY } from "../../../src/contracts/storage-keys.ts"; + +/** A Web Storage stand-in for the host's `sessionStorage`. */ +function sessionStorageLike() { + const values = new Map(); + return { + values, + getItem: (key: string) => values.get(key) ?? null, + setItem: (key: string, value: string) => void values.set(key, value), + removeItem: (key: string) => void values.delete(key), + }; +} + +function markerStore(): RecoveryMarkerStore & { values: Map } { + const values = new Map(); + return { + values, + read: () => values.get("marker") ?? null, + write: (value) => void values.set("marker", value), + clear: () => void values.delete("marker"), + }; +} + +describe("release mismatch recovery", () => { + it("allows at most one automatic recovery attempt per release mismatch key", () => { + const recovery = createReleaseMismatchRecovery(markerStore()); + + expect(recovery.decide("R10->R11")).toBe("reload-once"); + expect(recovery.decide("R10->R11")).toBe("show-failure"); + }); + + it("never reloads more than once however often the same mismatch repeats", () => { + const recovery = createReleaseMismatchRecovery(markerStore()); + const decisions = Array.from({ length: 50 }, () => recovery.decide("R10->R11")); + expect(decisions.filter((decision) => decision === "reload-once")).toHaveLength(1); + }); + + it("clears the marker after a coherent boot", () => { + const storage = markerStore(); + const recovery = createReleaseMismatchRecovery(storage); + recovery.decide("R10->R11"); + recovery.markCoherentBoot(); + expect(storage.values.size).toBe(0); + expect(recovery.decide("R10->R11")).toBe("reload-once"); + }); + + it("keeps a single bounded marker and scopes it to the mismatch key", () => { + const storage = markerStore(); + const recovery = createReleaseMismatchRecovery(storage); + expect(recovery.decide("R10->R11")).toBe("reload-once"); + expect(recovery.decide("R11->R12")).toBe("reload-once"); + expect(storage.values.size).toBe(1); + expect(recovery.decide("x".repeat(10_000))).toBe("reload-once"); + expect([...storage.values.values()][0]?.length).toBeLessThan(300); + }); + + it("lets an expired marker recover again instead of blocking forever", () => { + let now = 0; + const recovery = createReleaseMismatchRecovery(markerStore(), { + now: () => now, + ttlMs: 1_000, + }); + expect(recovery.decide("k")).toBe("reload-once"); + now = 500; + expect(recovery.decide("k")).toBe("show-failure"); + now = 5_000; + expect(recovery.decide("k")).toBe("reload-once"); + }); + + it("fails closed without working storage", () => { + expect(createReleaseMismatchRecovery(null).decide("k")).toBe("show-failure"); + const throwing: RecoveryMarkerStore = { + read: () => { + throw new Error("denied"); + }, + write: () => { + throw new Error("denied"); + }, + clear: () => { + throw new Error("denied"); + }, + }; + const recovery = createReleaseMismatchRecovery(throwing); + expect(recovery.decide("k")).toBe("show-failure"); + expect(() => recovery.markCoherentBoot()).not.toThrow(); + const dropping: RecoveryMarkerStore = { + read: () => null, + write: () => {}, + clear: () => {}, + }; + expect(createReleaseMismatchRecovery(dropping).decide("k")).toBe("show-failure"); + }); +}); + +describe("boot release recovery wiring", () => { + it("keys only release mismatches, never other boot failures", () => { + const mismatch = new ReleaseManifestError("MANIFEST_RELEASE_MISMATCH", { + buildId: "build-R10", + releaseId: "release-R11", + }); + expect(releaseMismatchKey(mismatch)).toBe( + "build-R10:MANIFEST_RELEASE_MISMATCH:release-R11", + ); + expect( + releaseMismatchKey(new BootConfigError("CONFIG_BUILD_MISMATCH", { buildId: "build-R10" })), + ).toBe("build-R10:CONFIG_BUILD_MISMATCH:-"); + expect( + releaseMismatchKey(new ReleaseManifestError("MANIFEST_TIMEOUT", { buildId: "b" })), + ).toBeNull(); + expect( + releaseMismatchKey(new BootConfigError("CONFIG_FETCH_FAILED", { buildId: "b" })), + ).toBeNull(); + expect(releaseMismatchKey(new Error("boom"))).toBeNull(); + }); + + it("uses the registered RELEASE_MISMATCH_RECOVERY session key", () => { + const storage = sessionStorageLike(); + const recovery = createBootReleaseRecovery({ sessionStorage: storage }); + const mismatch = new ReleaseManifestError("MANIFEST_BUILD_MISMATCH", { buildId: "build-R10" }); + + expect(decideBootFailure(mismatch, recovery)).toBe("reload-once"); + expect([...storage.values.keys()]).toEqual([ + STORAGE_REGISTRY.RELEASE_MISMATCH_RECOVERY.physicalKey, + ]); + expect(decideBootFailure(mismatch, recovery)).toBe("show-failure"); + expect( + decideBootFailure(new ReleaseManifestError("MANIFEST_TIMEOUT", { buildId: "b" }), recovery), + ).toBe("show-failure"); + }); + + it("remembers the attempt across the reload itself (a fresh boot, same session)", () => { + const storage = sessionStorageLike(); + const mismatch = new ReleaseManifestError("MANIFEST_BUILD_MISMATCH", { buildId: "build-R10" }); + + expect(decideBootFailure(mismatch, createBootReleaseRecovery({ sessionStorage: storage }))).toBe( + "reload-once", + ); + const afterReload = createBootReleaseRecovery({ sessionStorage: storage }); + expect(decideBootFailure(mismatch, afterReload)).toBe("show-failure"); + afterReload.markCoherentBoot(); + expect(storage.values.size).toBe(0); + }); + + it("degrades to show-failure when the host has no session storage", () => { + const recovery = createBootReleaseRecovery({}); + expect( + decideBootFailure( + new ReleaseManifestError("MANIFEST_BUILD_MISMATCH", { buildId: "b" }), + recovery, + ), + ).toBe("show-failure"); + }); +}); diff --git a/tests/platform/resilience/deadline.test.ts b/tests/platform/resilience/deadline.test.ts new file mode 100644 index 00000000..1cf66d34 --- /dev/null +++ b/tests/platform/resilience/deadline.test.ts @@ -0,0 +1,23 @@ +import { describe, expect, it } from "vitest"; + +import { + DeadlineExceededError, + remainingDeadlineMs, +} from "../../../src/platform/resilience/deadline.ts"; + +describe("remainingDeadlineMs", () => { + it("returns only time remaining from the original absolute deadline", () => { + expect(remainingDeadlineMs(6_000, 1_000)).toBe(5_000); + expect(remainingDeadlineMs(6_000, 5_500)).toBe(500); + expect(() => remainingDeadlineMs(6_000, 6_001)).toThrow(DeadlineExceededError); + }); + + it("treats the exact deadline instant as zero remaining", () => { + expect(remainingDeadlineMs(6_000, 6_000)).toBe(0); + }); + + it("rejects non-finite clock values", () => { + expect(() => remainingDeadlineMs(Number.POSITIVE_INFINITY, 0)).toThrow(TypeError); + expect(() => remainingDeadlineMs(10, Number.NaN)).toThrow(TypeError); + }); +}); diff --git a/tests/platform/resilience/retry-budget.test.ts b/tests/platform/resilience/retry-budget.test.ts new file mode 100644 index 00000000..ccb686be --- /dev/null +++ b/tests/platform/resilience/retry-budget.test.ts @@ -0,0 +1,29 @@ +import { describe, expect, it } from "vitest"; + +import { createRetryBudget } from "../../../src/platform/resilience/retry-budget.ts"; + +describe("createRetryBudget", () => { + it("shares retry capacity across independent requests in the same interaction", () => { + const budget = createRetryBudget(1); + + expect(budget.tryConsume("request-a")).toBe(true); + expect(budget.tryConsume("request-b")).toBe(false); + expect(budget.consumed).toBe(1); + }); + + it("does not reset per request id", () => { + const budget = createRetryBudget(2); + expect(budget.tryConsume("a")).toBe(true); + expect(budget.tryConsume("b")).toBe(true); + expect(budget.tryConsume("a")).toBe(false); + expect(budget.tryConsume("c")).toBe(false); + }); + + it("supports a zero-retry interaction", () => { + expect(createRetryBudget(0).tryConsume("a")).toBe(false); + }); + + it.each([-1, Number.POSITIVE_INFINITY, 0.5])("rejects invalid maximum %s", (maximum) => { + expect(() => createRetryBudget(maximum)).toThrow(TypeError); + }); +}); diff --git a/tests/platform/routing/context-route-module.test.ts b/tests/platform/routing/context-route-module.test.ts new file mode 100644 index 00000000..b9331dab --- /dev/null +++ b/tests/platform/routing/context-route-module.test.ts @@ -0,0 +1,91 @@ +import { describe, expect, it } from "vitest"; + +import { defineDeployableAppModule } from "../../../src/apps/deployable-app-module.ts"; +import { defineBoundedContextModule } from "../../../src/contexts/bounded-context-module.ts"; +import { createAppRouteModules } from "../../../src/platform/routing/context-route-module.ts"; + +function contextWithLoader( + id: string, + loadRoutes: () => Promise, +) { + return defineBoundedContextModule({ + id, + features: [], + budget: { maxFeatures: 200 }, + route: { path: `${id}/*`, loadRoutes }, + }); +} + +describe("context route module", () => { + it("creates only direct context entries at app boot without loading routes", () => { + let commerceLoads = 0; + let accountLoads = 0; + const commerce = contextWithLoader("commerce", async () => { + commerceLoads += 1; + return []; + }); + const account = contextWithLoader("account", async () => { + accountLoads += 1; + return []; + }); + const app = defineDeployableAppModule({ + id: "customer", + contexts: [commerce, account], + budget: { maxContexts: 20 }, + }); + + expect(createAppRouteModules(app).map((module) => module.id)).toEqual([ + "commerce", + "account", + ]); + expect(commerceLoads).toBe(0); + expect(accountLoads).toBe(0); + }); + + it("single-flights and caches one context route composition", async () => { + let loadCount = 0; + const context = contextWithLoader("commerce", async () => { + loadCount += 1; + await Promise.resolve(); + return []; + }); + const app = defineDeployableAppModule({ + id: "customer", + contexts: [context], + budget: { maxContexts: 20 }, + }); + const [routeModule] = createAppRouteModules(app); + expect(routeModule).toBeDefined(); + + const [first, second] = await Promise.all([ + routeModule!.loadRoutes(), + routeModule!.loadRoutes(), + ]); + const third = await routeModule!.loadRoutes(); + + expect(loadCount).toBe(1); + expect(first).toBe(second); + expect(third).toBe(first); + expect(Object.isFrozen(first)).toBe(true); + }); + + it("allows a failed context route load to retry", async () => { + let loadCount = 0; + const context = contextWithLoader("commerce", async () => { + loadCount += 1; + if (loadCount === 1) throw new Error("chunk unavailable"); + return []; + }); + const app = defineDeployableAppModule({ + id: "customer", + contexts: [context], + budget: { maxContexts: 20 }, + }); + const [routeModule] = createAppRouteModules(app); + expect(routeModule).toBeDefined(); + + await expect(routeModule!.loadRoutes()).rejects.toThrow("chunk unavailable"); + await expect(routeModule!.loadRoutes()).resolves.toEqual([]); + expect(loadCount).toBe(2); + }); +}); diff --git a/tests/platform/telemetry/redact-telemetry.test.ts b/tests/platform/telemetry/redact-telemetry.test.ts new file mode 100644 index 00000000..10ccb0aa --- /dev/null +++ b/tests/platform/telemetry/redact-telemetry.test.ts @@ -0,0 +1,97 @@ +import { describe, expect, it } from "vitest"; + +import { + REDACTED, + redactTelemetryPayload, + TRUNCATED, +} from "../../../src/platform/telemetry/redact-telemetry.ts"; + +describe("redactTelemetryPayload", () => { + it.each([ + "password", + "authorization", + "cookie", + "accessToken", + "refreshToken", + "access_token", + "Set-Cookie", + "apiKey", + "clientSecret", + ])("redacts %s recursively", (secretKey) => { + const input = { nested: { [secretKey]: "secret", safe: "ok" } }; + const result = redactTelemetryPayload(input); + + expect(JSON.stringify(result)).not.toContain("secret"); + expect(result).toMatchObject({ nested: { safe: "ok" } }); + }); + + it("redacts credential-shaped values under innocent keys", () => { + const result = redactTelemetryPayload({ + note: "Bearer abc.def.ghi", + jwt: "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.sig", + list: ["Basic dXNlcjpwYXNz"], + }); + expect(result).toEqual({ note: REDACTED, jwt: REDACTED, list: [REDACTED] }); + }); + + it("never invokes getters, toJSON or foreign prototypes", () => { + let invoked = false; + class Carrier { + visible = "kept"; + toJSON() { + invoked = true; + return { leaked: true }; + } + } + const hostile = Object.defineProperty(new Carrier(), "computed", { + enumerable: true, + get() { + invoked = true; + return "computed"; + }, + }); + + const result = redactTelemetryPayload({ hostile }); + + expect(invoked).toBe(false); + expect(result).toEqual({ hostile: { visible: "kept" } }); + expect(Object.getPrototypeOf((result as { hostile: object }).hostile)).toBe( + Object.prototype, + ); + }); + + it("bounds depth, width, array length and string length", () => { + let deep: unknown = "leaf"; + for (let depth = 0; depth < 50; depth += 1) deep = { next: deep }; + const wide = Object.fromEntries( + Array.from({ length: 500 }, (_, index) => [`k${index}`, index]), + ); + const result = redactTelemetryPayload( + { deep, wide, list: Array.from({ length: 1_000 }, (_, i) => i), text: "x".repeat(5_000) }, + { maxDepth: 4, maxKeys: 10, maxArrayItems: 5, maxStringLength: 16 }, + ) as Record; + + expect(JSON.stringify(result)).toContain(TRUNCATED); + expect(Object.keys(result["wide"] as object).length).toBeLessThanOrEqual(10); + expect(result["list"]).toHaveLength(5); + expect((result["text"] as string).length).toBeLessThanOrEqual(16 + TRUNCATED.length); + }); + + it("does not let prototype keys pollute the copy", () => { + const payload = JSON.parse('{"__proto__":{"polluted":true},"ok":1}') as unknown; + const result = redactTelemetryPayload(payload) as Record; + expect(result).toEqual({ ok: 1 }); + expect(({} as Record)["polluted"]).toBeUndefined(); + }); + + it("normalizes non-JSON leaves", () => { + expect( + redactTelemetryPayload({ + n: Number.NaN, + f: () => 1, + u: undefined, + b: 10n, + }), + ).toEqual({ n: null, f: null, u: null, b: null }); + }); +}); diff --git a/tests/platform/telemetry/telemetry-buffer.test.ts b/tests/platform/telemetry/telemetry-buffer.test.ts new file mode 100644 index 00000000..4fbd5efa --- /dev/null +++ b/tests/platform/telemetry/telemetry-buffer.test.ts @@ -0,0 +1,89 @@ +import { describe, expect, it } from "vitest"; + +import { createTelemetryBuffer } from "../../../src/platform/telemetry/telemetry-buffer.ts"; +import type { TelemetryEvent } from "../../../src/platform/telemetry/telemetry-event.ts"; +import { createDeterministicSampler } from "../../../src/platform/telemetry/telemetry-sampler.ts"; + +const infoEvent = (id: string): TelemetryEvent => ({ + kind: "test.info", + severity: "info", + payload: { id }, +}); +const criticalEvent = (id: string): TelemetryEvent => ({ + kind: "test.critical", + severity: "critical", + payload: { id }, +}); + +describe("createDeterministicSampler", () => { + it("makes the same sampling decision for the same stable key", () => { + const sampler = createDeterministicSampler({ rate: 0.1 }); + + expect(sampler.keep("interaction-123")).toBe(sampler.keep("interaction-123")); + }); + + it("approximates the configured rate over many keys", () => { + const sampler = createDeterministicSampler({ rate: 0.1 }); + let kept = 0; + for (let i = 0; i < 10_000; i += 1) if (sampler.keep(`interaction-${i}`)) kept += 1; + expect(kept).toBeGreaterThan(700); + expect(kept).toBeLessThan(1_300); + }); + + it("is exact at the edges and rejects invalid rates", () => { + expect(createDeterministicSampler({ rate: 1 }).keep("x")).toBe(true); + expect(createDeterministicSampler({ rate: 0 }).keep("x")).toBe(false); + expect(() => createDeterministicSampler({ rate: 1.5 })).toThrow(TypeError); + expect(() => createDeterministicSampler({ rate: Number.NaN })).toThrow(TypeError); + }); +}); + +describe("createTelemetryBuffer", () => { + it("never exceeds event or byte ceilings", () => { + const buffer = createTelemetryBuffer({ + maxEvents: 2, + maxBytes: 1_024, + }); + + buffer.push(infoEvent("a")); + buffer.push(infoEvent("b")); + buffer.push(criticalEvent("c")); + + expect(buffer.size).toBeLessThanOrEqual(2); + expect(buffer.bytes).toBeLessThanOrEqual(1_024); + expect(buffer.items.some((item) => item.severity === "critical")).toBe(true); + }); + + it("drops an incoming low-severity event rather than evicting a severe one", () => { + const buffer = createTelemetryBuffer({ maxEvents: 1, maxBytes: 1_024 }); + buffer.push(criticalEvent("keep")); + expect(buffer.push(infoEvent("late"))).toBe(false); + expect(buffer.items).toEqual([criticalEvent("keep")]); + expect(buffer.dropped).toBe(1); + }); + + it("enforces the byte ceiling independently of the event count", () => { + const buffer = createTelemetryBuffer({ maxEvents: 100, maxBytes: 200 }); + for (let i = 0; i < 50; i += 1) buffer.push(infoEvent(`event-${i}`)); + expect(buffer.bytes).toBeLessThanOrEqual(200); + expect(buffer.size).toBeLessThan(50); + }); + + it("rejects a single event larger than the byte ceiling", () => { + const buffer = createTelemetryBuffer({ maxEvents: 10, maxBytes: 64 }); + expect(buffer.push(infoEvent("x".repeat(100)))).toBe(false); + expect(buffer.size).toBe(0); + }); + + it("hands batches out in FIFO order and releases their bytes", () => { + const buffer = createTelemetryBuffer({ maxEvents: 10, maxBytes: 10_000 }); + buffer.push(infoEvent("a")); + buffer.push(infoEvent("b")); + buffer.push(infoEvent("c")); + const batch = buffer.take(2); + expect(batch.map((entry) => entry.event)).toEqual([infoEvent("a"), infoEvent("b")]); + expect(buffer.size).toBe(1); + buffer.take(10); + expect(buffer.bytes).toBe(0); + }); +}); diff --git a/tests/platform/telemetry/telemetry-deduplicator.test.ts b/tests/platform/telemetry/telemetry-deduplicator.test.ts new file mode 100644 index 00000000..646b5269 --- /dev/null +++ b/tests/platform/telemetry/telemetry-deduplicator.test.ts @@ -0,0 +1,94 @@ +import { describe, expect, it } from "vitest"; + +import { TelemetryDeduplicator } from "../../../src/platform/telemetry/telemetry-deduplicator.ts"; +import { + fingerprintTelemetryEvent, + stableSerialize, +} from "../../../src/platform/telemetry/telemetry-fingerprint.ts"; + +const FINGERPRINT = fingerprintTelemetryEvent({ + kind: "catalog.load.failed", + severity: "error", + payload: { reason: "timeout" }, +}); + +describe("fingerprintTelemetryEvent", () => { + it("ignores request-cardinality identifiers and key order", () => { + const a = fingerprintTelemetryEvent({ + kind: "catalog.load.failed", + severity: "error", + interactionId: "i-1", + traceId: "4bf92f3577b34da6a3ce929d0e0e4736", + payload: { reason: "timeout", operation: "list" }, + }); + const b = fingerprintTelemetryEvent({ + kind: "catalog.load.failed", + severity: "error", + interactionId: "i-2", + payload: { operation: "list", reason: "timeout" }, + }); + expect(a).toBe(b); + expect(a).toMatch(/^[0-9a-f]{16}$/); + }); + + it("separates distinct failures", () => { + expect( + fingerprintTelemetryEvent({ kind: "a.b", severity: "error", payload: { reason: "x" } }), + ).not.toBe( + fingerprintTelemetryEvent({ kind: "a.b", severity: "error", payload: { reason: "y" } }), + ); + }); + + it("serializes structure unambiguously", () => { + expect(stableSerialize({ b: [1, { c: "x" }], a: null })).toBe( + '{"a":null,"b":[1,{"c":"x"}]}', + ); + expect(stableSerialize(["]", ","])).toBe('["]",","]'); + }); +}); + +describe("TelemetryDeduplicator", () => { + it("collapses repeated identical failures into one active fingerprint entry", () => { + const dedup = new TelemetryDeduplicator({ maxEntries: 100, windowMs: 60_000 }); + + for (let i = 0; i < 10_000; i += 1) { + dedup.record(FINGERPRINT, i); + } + + expect(dedup.size).toBe(1); + expect(dedup.count(FINGERPRINT)).toBe(10_000); + }); + + it("never retains more than maxEntries fingerprints", () => { + const dedup = new TelemetryDeduplicator({ maxEntries: 2, windowMs: 60_000 }); + dedup.record("a", 1); + dedup.record("b", 2); + dedup.record("c", 3); + + expect(dedup.size).toBe(2); + }); + + it("admits a fingerprint again once its window expires", () => { + const dedup = new TelemetryDeduplicator({ maxEntries: 10, windowMs: 1_000 }); + expect(dedup.record("a", 0)).toBe(true); + expect(dedup.record("a", 999)).toBe(false); + expect(dedup.record("a", 1_000)).toBe(true); + expect(dedup.count("a")).toBe(1); + }); + + it("evicts the least recently seen fingerprint under pressure", () => { + const dedup = new TelemetryDeduplicator({ maxEntries: 2, windowMs: 60_000 }); + dedup.record("a", 1); + dedup.record("b", 2); + dedup.record("a", 3); // refresh a + dedup.record("c", 4); // evicts b + expect(dedup.count("a")).toBe(2); + expect(dedup.count("b")).toBe(0); + expect(dedup.count("c")).toBe(1); + }); + + it("rejects unbounded configuration", () => { + expect(() => new TelemetryDeduplicator({ maxEntries: Infinity, windowMs: 1 })).toThrow(TypeError); + expect(() => new TelemetryDeduplicator({ maxEntries: 1, windowMs: 0 })).toThrow(TypeError); + }); +}); diff --git a/tests/platform/telemetry/telemetry-pipeline.test.ts b/tests/platform/telemetry/telemetry-pipeline.test.ts new file mode 100644 index 00000000..7035071b --- /dev/null +++ b/tests/platform/telemetry/telemetry-pipeline.test.ts @@ -0,0 +1,185 @@ +import { describe, expect, it, vi } from "vitest"; + +import { + createTelemetryPipeline, + DEFAULT_TELEMETRY_PIPELINE_BUDGET, + type TelemetryBatchItem, + type TelemetryPipelineBudget, +} from "../../../src/platform/telemetry/telemetry-pipeline.ts"; +import type { TelemetryEvent } from "../../../src/platform/telemetry/telemetry-event.ts"; + +const TEST_TELEMETRY_BUDGET: TelemetryPipelineBudget = { + ...DEFAULT_TELEMETRY_PIPELINE_BUDGET, + maxBufferedEvents: 50, + maxSendsPerMinute: 10, +}; + +const TEST_EVENT: TelemetryEvent = { + kind: "catalog.load.failed", + severity: "error", + featureId: "catalog", + payload: { reason: "REQUEST_TIMEOUT" }, +}; +const REPEATED_ERROR = TEST_EVENT; + +/** Runs scheduled work synchronously-ish and keeps timers in the test's hand. */ +function manualScheduling() { + const timers: Array<() => void> = []; + return { + schedule: (callback: () => void) => queueMicrotask(callback), + setTimer: (callback: () => void) => { + timers.push(callback); + return timers.length; + }, + clearTimer: () => {}, + runTimers() { + for (const callback of timers.splice(0)) callback(); + }, + }; +} + +describe("createTelemetryPipeline", () => { + it("does not reject business flow when telemetry transport fails", async () => { + const pipeline = createTelemetryPipeline({ + transport: { + async send() { + throw new Error("collector unavailable"); + }, + }, + budget: TEST_TELEMETRY_BUDGET, + }); + + await expect(pipeline.emit(TEST_EVENT)).resolves.toBeUndefined(); + await expect(pipeline.flush()).resolves.toBeUndefined(); + expect(pipeline.stats().failedSends).toBe(1); + }); + + it("does not throw when the transport throws synchronously", async () => { + const pipeline = createTelemetryPipeline({ + transport: { + send() { + throw new Error("sdk crashed"); + }, + }, + budget: TEST_TELEMETRY_BUDGET, + }); + await expect(pipeline.emit(TEST_EVENT)).resolves.toBeUndefined(); + await expect(pipeline.flush()).resolves.toBeUndefined(); + }); + + it("bounds network sends during a repeated error storm", async () => { + const send = vi.fn().mockResolvedValue(undefined); + const pipeline = createTelemetryPipeline({ + transport: { send }, + budget: { ...TEST_TELEMETRY_BUDGET, maxSendsPerMinute: 10 }, + }); + + for (let i = 0; i < 100_000; i += 1) { + await pipeline.emit(REPEATED_ERROR); + } + + await pipeline.flush(); + expect(send.mock.calls.length).toBeLessThanOrEqual(10); + expect(pipeline.stats().deduplicated).toBe(99_999); + }); + + it("reports how many occurrences a delivered fingerprint collapsed", async () => { + const batches: TelemetryBatchItem[][] = []; + let now = 0; + const pipeline = createTelemetryPipeline({ + transport: { send: (batch) => void batches.push([...batch]) }, + budget: TEST_TELEMETRY_BUDGET, + now: () => now, + schedule: () => {}, + }); + for (let i = 0; i < 25; i += 1) { + now = i; + await pipeline.emit(REPEATED_ERROR); + } + await pipeline.flush(); + expect(batches.flat()).toHaveLength(1); + expect(batches[0]?.[0]?.occurrences).toBe(25); + }); + + it("rate-limits distinct events and resumes after the window reopens", async () => { + let now = 0; + const scheduling = manualScheduling(); + const send = vi.fn().mockResolvedValue(undefined); + const pipeline = createTelemetryPipeline({ + transport: { send }, + budget: { + ...TEST_TELEMETRY_BUDGET, + maxSendsPerMinute: 2, + maxBatchEvents: 1, + maxBufferedEvents: 100, + }, + now: () => now, + ...scheduling, + }); + for (let i = 0; i < 5; i += 1) { + await pipeline.emit({ ...TEST_EVENT, payload: { reason: `r${i}` } }); + } + await pipeline.flush(); + expect(send).toHaveBeenCalledTimes(2); + expect(pipeline.stats().buffered).toBe(3); + + now = 60_000; + scheduling.runTimers(); + await pipeline.flush(); + expect(send).toHaveBeenCalledTimes(4); + }); + + it("keeps memory bounded when events are all distinct and the collector is down", async () => { + const pipeline = createTelemetryPipeline({ + transport: { send: () => Promise.reject(new Error("down")) }, + budget: { ...TEST_TELEMETRY_BUDGET, maxBufferedEvents: 20, maxFingerprints: 30 }, + schedule: () => {}, + }); + for (let i = 0; i < 5_000; i += 1) { + await pipeline.emit({ ...TEST_EVENT, payload: { reason: `distinct-${i}` } }); + } + const stats = pipeline.stats(); + expect(stats.buffered).toBeLessThanOrEqual(20); + expect(stats.peakBuffered).toBeLessThanOrEqual(20); + expect(stats.fingerprints).toBeLessThanOrEqual(30); + }); + + it("redacts before anything is buffered or sent", async () => { + const batches: TelemetryBatchItem[][] = []; + const pipeline = createTelemetryPipeline({ + transport: { send: (batch) => void batches.push([...batch]) }, + budget: TEST_TELEMETRY_BUDGET, + }); + await pipeline.emit({ + ...TEST_EVENT, + payload: { reason: "x", accessToken: "secret-token", headers: { cookie: "sid=1" } }, + }); + await pipeline.flush(); + expect(JSON.stringify(batches)).not.toMatch(/secret-token|sid=1/); + }); + + it("samples low-severity events deterministically but always keeps errors", async () => { + const pipeline = createTelemetryPipeline({ + transport: { send: () => {} }, + budget: { ...TEST_TELEMETRY_BUDGET, sampleRate: 0 }, + schedule: () => {}, + }); + await pipeline.emit({ kind: "a.info", severity: "info", interactionId: "i-1" }); + await pipeline.emit({ kind: "a.error", severity: "error", interactionId: "i-1" }); + expect(pipeline.stats()).toMatchObject({ sampledOut: 1, buffered: 1 }); + }); + + it("drops invalid envelopes and stops admitting after dispose", async () => { + const send = vi.fn(); + const pipeline = createTelemetryPipeline({ + transport: { send }, + budget: TEST_TELEMETRY_BUDGET, + }); + await pipeline.emit({ kind: "NOT VALID", severity: "error" }); + expect(pipeline.stats().invalid).toBe(1); + pipeline.dispose(); + await pipeline.emit(TEST_EVENT); + await pipeline.flush(); + expect(send).not.toHaveBeenCalled(); + }); +}); diff --git a/tests/platform/telemetry/telemetry-port.test.ts b/tests/platform/telemetry/telemetry-port.test.ts new file mode 100644 index 00000000..16773295 --- /dev/null +++ b/tests/platform/telemetry/telemetry-port.test.ts @@ -0,0 +1,63 @@ +import { describe, expect, it } from "vitest"; + +import type { TelemetryEvent } from "../../../src/platform/telemetry/telemetry-event.ts"; +import { isTelemetryEnvelopeValid } from "../../../src/platform/telemetry/telemetry-event.ts"; +import { + failOpenTelemetryPort, + NO_OP_TELEMETRY_PORT, + type TelemetryPort, +} from "../../../src/platform/telemetry/telemetry-port.ts"; + +describe("TelemetryPort", () => { + it("accepts feature-owned payloads through a generic envelope", async () => { + const seen: TelemetryEvent[] = []; + const port: TelemetryPort = { + emit(event) { + seen.push(event); + }, + }; + + await port.emit({ + kind: "catalog.load.failed", + severity: "error", + contextId: "commerce", + featureId: "catalog", + interactionId: "i-1", + payload: { reason: "timeout" }, + }); + + expect(seen).toHaveLength(1); + }); + + it("contains a throwing or rejecting implementation", async () => { + const throwing = failOpenTelemetryPort({ + emit() { + throw new Error("vendor down"); + }, + }); + const rejecting = failOpenTelemetryPort({ + emit: () => Promise.reject(new Error("vendor down")), + }); + await expect(throwing.emit({ kind: "a.b", severity: "info" })).resolves.toBeUndefined(); + await expect(rejecting.emit({ kind: "a.b", severity: "info" })).resolves.toBeUndefined(); + expect(() => NO_OP_TELEMETRY_PORT.emit({ kind: "a.b", severity: "info" })).not.toThrow(); + }); + + it("admits only bounded envelope identifiers", () => { + expect(isTelemetryEnvelopeValid({ kind: "catalog.load.failed", severity: "warning" })).toBe(true); + expect(isTelemetryEnvelopeValid({ kind: "Free Text Kind", severity: "warning" })).toBe(false); + expect( + isTelemetryEnvelopeValid({ + kind: "a.b", + severity: "warning", + featureId: "/users/123", + }), + ).toBe(false); + expect( + isTelemetryEnvelopeValid({ + kind: "a.b", + severity: "verbose" as never, + }), + ).toBe(false); + }); +}); diff --git a/tests/platform/telemetry/trace-context.test.ts b/tests/platform/telemetry/trace-context.test.ts new file mode 100644 index 00000000..a0b613dd --- /dev/null +++ b/tests/platform/telemetry/trace-context.test.ts @@ -0,0 +1,101 @@ +import { describe, expect, it, vi } from "vitest"; + +import type { InstalledHttpContract } from "../../../src/contracts/external-contract-runtime.ts"; +import { safeTraceparent } from "../../../src/adapters/telemetry/best-effort-telemetry.ts"; +import { + buildRequestHeaders, + createTraceContext, +} from "../../../src/platform/telemetry/trace-context.ts"; +import { createExecutionContext } from "../../../src/platform/execution/execution-context.ts"; +import { TEST_LIST_HTTP_CONTRACT } from "../../helpers/external-contract-fixture.ts"; +import { + jsonRows, + scopeSnapshot, + testExecutor, + type Transport, +} from "../../helpers/traffic-test-kit.ts"; + +const VALID_TRACE_ID = "4bf92f3577b34da6a3ce929d0e0e4736"; + +function testExecutionContext( + options: Readonly<{ interactionId: string; traceId: string }>, +) { + return createExecutionContext({ + interactionId: options.interactionId, + deadlineMs: 5_000, + traffic: { maxPhysicalRequests: 4, maxRetries: 1, maxConcurrentRequests: 2 }, + trace: createTraceContext({ traceId: options.traceId }), + }); +} + +describe("trace and correlation propagation", () => { + it("propagates one interaction trace identity to child requests", () => { + const context = testExecutionContext({ interactionId: "i-1", traceId: VALID_TRACE_ID }); + + const a = buildRequestHeaders(context); + const b = buildRequestHeaders(context); + + expect(a.get("traceparent")).toBe(b.get("traceparent")); + expect(a.get("x-correlation-id")).toBe("i-1"); + }); + + it("emits a W3C traceparent the existing validator accepts", () => { + const trace = createTraceContext({ traceId: VALID_TRACE_ID }); + expect(safeTraceparent(trace.traceparent)).toBe(trace.traceparent); + expect(trace.traceparent.startsWith(`00-${VALID_TRACE_ID}-`)).toBe(true); + expect(safeTraceparent(createTraceContext().traceparent)).not.toBeNull(); + }); + + it("rejects malformed or all-zero trace ids", () => { + expect(() => createTraceContext({ traceId: "0".repeat(32) })).toThrow(TypeError); + expect(() => createTraceContext({ traceId: "XYZ" })).toThrow(TypeError); + }); + + it("sends the same trace headers on every physical request of the interaction", async () => { + const seen: Array = []; + const transport = vi.fn(async (_input, init) => { + seen.push(new Headers(init?.headers)); + return jsonRows(1); + }); + const execution = testExecutionContext({ interactionId: "i-9", traceId: VALID_TRACE_ID }); + const executor = testExecutor(transport); + const operation = TEST_LIST_HTTP_CONTRACT as InstalledHttpContract; + const context = { routeId: "TEST_ROUTE", scope: scopeSnapshot(), execution }; + + await executor.execute(operation, { limit: 1 }, context); + await executor.execute(operation, { limit: 1 }, context); + + expect(seen).toHaveLength(2); + expect(seen[0]?.get("traceparent")).toBe(execution.trace?.traceparent); + expect(seen[1]?.get("traceparent")).toBe(execution.trace?.traceparent); + expect(seen.every((headers) => headers.get("x-correlation-id") === "i-9")).toBe(true); + }); + + it("adds no trace headers to an interaction that did not opt in", async () => { + const seen: Array = []; + const transport = vi.fn(async (_input, init) => { + seen.push(new Headers(init?.headers)); + return jsonRows(1); + }); + await testExecutor(transport).execute( + TEST_LIST_HTTP_CONTRACT as InstalledHttpContract, + { limit: 1 }, + { routeId: "TEST_ROUTE", scope: scopeSnapshot() }, + ); + expect(seen[0]?.get("traceparent")).toBeNull(); + expect(seen[0]?.get("x-correlation-id")).toBeNull(); + }); + + it("does not let a credential collaborator forge the trace headers", async () => { + const transport = vi.fn(async () => jsonRows(1)); + const outcome = await testExecutor(transport, { + credentialHeaders: { traceparent: `00-${VALID_TRACE_ID}-00f067aa0ba902b7-01` }, + }).execute( + TEST_LIST_HTTP_CONTRACT as InstalledHttpContract, + { limit: 1 }, + { routeId: "TEST_ROUTE", scope: scopeSnapshot() }, + ); + expect(outcome.kind).toBe("AUTH_INTEGRATION_FAILURE"); + expect(transport).not.toHaveBeenCalled(); + }); +}); diff --git a/tests/platform/traffic/concurrency-budget.test.ts b/tests/platform/traffic/concurrency-budget.test.ts new file mode 100644 index 00000000..56c7f16d --- /dev/null +++ b/tests/platform/traffic/concurrency-budget.test.ts @@ -0,0 +1,94 @@ +import { describe, expect, it } from "vitest"; + +import { + ConcurrencyQueueFullError, + createConcurrencyBudget, +} from "../../../src/platform/traffic/concurrency-budget.ts"; + +const live = () => new AbortController().signal; + +describe("createConcurrencyBudget", () => { + it("never grants more than maximum simultaneous leases", async () => { + const budget = createConcurrencyBudget({ maximum: 2, maxQueued: 1 }); + const first = await budget.acquire(live()); + const second = await budget.acquire(live()); + + expect(budget.active).toBe(2); + const queued = budget.acquire(live()); + expect(budget.queued).toBe(1); + await expect(budget.acquire(live())).rejects.toThrow(/queue/i); + await expect(budget.acquire(live())).rejects.toBeInstanceOf( + ConcurrencyQueueFullError, + ); + + first.release(); + const third = await queued; + expect(budget.active).toBe(2); + second.release(); + third.release(); + expect(budget.active).toBe(0); + }); + + it("removes an aborted waiter", async () => { + const budget = createConcurrencyBudget({ maximum: 1, maxQueued: 1 }); + const lease = await budget.acquire(live()); + const controller = new AbortController(); + const waiting = budget.acquire(controller.signal); + controller.abort(); + + await expect(waiting).rejects.toMatchObject({ name: "AbortError" }); + expect(budget.queued).toBe(0); + lease.release(); + expect(budget.active).toBe(0); + }); + + it("rejects immediately when the signal is already aborted", async () => { + const budget = createConcurrencyBudget({ maximum: 1, maxQueued: 1 }); + const controller = new AbortController(); + controller.abort(); + await expect(budget.acquire(controller.signal)).rejects.toMatchObject({ + name: "AbortError", + }); + expect(budget.active).toBe(0); + }); + + it("grants waiters in FIFO order", async () => { + const budget = createConcurrencyBudget({ maximum: 1, maxQueued: 3 }); + const holder = await budget.acquire(live()); + const order: string[] = []; + const a = budget.acquire(live()).then((lease) => { + order.push("a"); + return lease; + }); + const b = budget.acquire(live()).then((lease) => { + order.push("b"); + return lease; + }); + holder.release(); + (await a).release(); + (await b).release(); + expect(order).toEqual(["a", "b"]); + }); + + it("treats release as idempotent", async () => { + const budget = createConcurrencyBudget({ maximum: 1, maxQueued: 0 }); + const lease = await budget.acquire(live()); + lease.release(); + lease.release(); + expect(budget.active).toBe(0); + const again = await budget.acquire(live()); + await expect(budget.acquire(live())).rejects.toBeInstanceOf( + ConcurrencyQueueFullError, + ); + again.release(); + }); + + it("rejects an unbounded configuration", () => { + expect(() => + createConcurrencyBudget({ maximum: 1, maxQueued: Number.POSITIVE_INFINITY }), + ).toThrow(TypeError); + expect(() => createConcurrencyBudget({ maximum: 0, maxQueued: 1 })).toThrow( + TypeError, + ); + }); +}); diff --git a/tests/platform/traffic/http-budget-integration.test.ts b/tests/platform/traffic/http-budget-integration.test.ts new file mode 100644 index 00000000..d8a220a6 --- /dev/null +++ b/tests/platform/traffic/http-budget-integration.test.ts @@ -0,0 +1,244 @@ +import { describe, expect, it, vi } from "vitest"; + +import type { InstalledHttpContract } from "../../../src/contracts/external-contract-runtime.ts"; +import { + TEST_CREATE_HTTP_CONTRACT, + TEST_LIST_HTTP_CONTRACT, +} from "../../helpers/external-contract-fixture.ts"; +import { + jsonRows, + manualClock, + networkFailure, + scopeSnapshot, + testExecutionContext, + testExecutor, + type Transport, +} from "../../helpers/traffic-test-kit.ts"; + +const TEST_QUERY = TEST_LIST_HTTP_CONTRACT as InstalledHttpContract< + unknown, + unknown, + unknown +>; +const TEST_COMMAND = TEST_CREATE_HTTP_CONTRACT as InstalledHttpContract< + unknown, + unknown, + unknown +>; +const ROUTE_ID = "TEST_ROUTE"; + +/** A transport that only ever ends when its request is aborted. */ +function hangingTransport(): Transport & { calls: number } { + const transport = ((_input: RequestInfo | URL, init?: RequestInit) => { + transport.calls += 1; + return new Promise((_resolve, reject) => { + init?.signal?.addEventListener( + "abort", + () => reject(new DOMException("aborted", "AbortError")), + { once: true }, + ); + }); + }) as Transport & { calls: number }; + transport.calls = 0; + return transport; +} + +describe("HTTP dispatch under interaction traffic budgets", () => { + it("does not dispatch after the interaction physical-request budget is exhausted", async () => { + const transport = vi.fn(networkFailure); + const execution = testExecutionContext({ + maxPhysicalRequests: 1, + maxRetries: 3, + }); + + const outcome = await testExecutor(transport).execute(TEST_QUERY, { limit: 5 }, { + routeId: ROUTE_ID, + scope: scopeSnapshot(), + execution, + }); + + expect(outcome.kind).toBe("TRANSPORT_FAILURE"); + expect(transport).toHaveBeenCalledTimes(1); + expect(execution.traffic.requests.consumed).toBe(1); + }); + + it("rejects a second operation once the shared request budget is gone", async () => { + const transport = vi.fn(networkFailure); + const execution = testExecutionContext({ + maxPhysicalRequests: 1, + maxRetries: 0, + }); + const executor = testExecutor(transport); + const context = { routeId: ROUTE_ID, scope: scopeSnapshot(), execution }; + + await executor.execute(TEST_QUERY, { limit: 5 }, context); + const second = await executor.execute(TEST_QUERY, { limit: 5 }, context); + + expect(second).toMatchObject({ + kind: "TRANSPORT_FAILURE", + failure: { kind: "OVERLOADED_BEFORE_SEND" }, + }); + expect(transport).toHaveBeenCalledTimes(1); + }); + + it("shares one retry budget across independent failing operations", async () => { + const transport = vi.fn(networkFailure); + const execution = testExecutionContext({ + maxPhysicalRequests: 10, + maxRetries: 1, + }); + const executor = testExecutor(transport); + const context = { routeId: ROUTE_ID, scope: scopeSnapshot(), execution }; + + await executor.execute(TEST_QUERY, { limit: 5 }, context); + await executor.execute(TEST_QUERY, { limit: 5 }, context); + + // First operation: attempt + its one shared retry. Second: attempt only. + expect(transport).toHaveBeenCalledTimes(3); + expect(execution.traffic.retries.consumed).toBe(1); + }); + + it("does not reset the interaction deadline before retry", async () => { + const clock = manualClock(0); + const execution = testExecutionContext({ + deadlineMs: 5_000, + maxPhysicalRequests: 4, + maxRetries: 3, + clock: clock.now, + }); + const transport = vi.fn(() => { + clock.advance(5_001); + return networkFailure(); + }); + + const outcome = await testExecutor(transport).execute(TEST_QUERY, { limit: 5 }, { + routeId: ROUTE_ID, + scope: scopeSnapshot(), + execution, + }); + + expect(outcome.kind).toBe("TRANSPORT_FAILURE"); + expect(transport).toHaveBeenCalledTimes(1); + expect(execution.traffic.retries.consumed).toBe(0); + }); + + it("gives a late operation only the interaction's remaining deadline", async () => { + const clock = manualClock(0); + const execution = testExecutionContext({ + deadlineMs: 1_000, + clock: clock.now, + }); + clock.advance(1_000); + const transport = vi.fn(async () => jsonRows(1)); + + const outcome = await testExecutor(transport).execute(TEST_QUERY, { limit: 5 }, { + routeId: ROUTE_ID, + scope: scopeSnapshot(), + execution, + }); + + expect(outcome).toMatchObject({ + kind: "TRANSPORT_FAILURE", + failure: { kind: "TIMEOUT" }, + }); + expect(transport).not.toHaveBeenCalled(); + }); + + it("rejects instead of queueing beyond the interaction queue bound", async () => { + const transport = hangingTransport(); + const execution = testExecutionContext({ + maxPhysicalRequests: 10, + maxConcurrentRequests: 1, + maxQueuedRequests: 0, + }); + const executor = testExecutor(transport); + const context = { routeId: ROUTE_ID, scope: scopeSnapshot(), execution }; + + const first = executor.execute(TEST_QUERY, { limit: 5 }, context); + await vi.waitFor(() => expect(transport.calls).toBe(1)); + const second = await executor.execute(TEST_QUERY, { limit: 5 }, context); + + expect(second).toMatchObject({ + kind: "TRANSPORT_FAILURE", + failure: { kind: "OVERLOADED_BEFORE_SEND" }, + }); + execution.cancellation.cancel(); + await expect(first).resolves.toMatchObject({ kind: "CANCELLED" }); + expect(transport.calls).toBe(1); + }); + + it("releases every lease and waiting entry when the interaction is aborted", async () => { + const transport = hangingTransport(); + const execution = testExecutionContext({ + maxPhysicalRequests: 10, + maxConcurrentRequests: 1, + maxQueuedRequests: 2, + }); + const executor = testExecutor(transport); + const context = { routeId: ROUTE_ID, scope: scopeSnapshot(), execution }; + + const running = [1, 2, 3].map(() => + executor.execute(TEST_QUERY, { limit: 5 }, context), + ); + await vi.waitFor(() => { + expect(execution.traffic.concurrency.active).toBe(1); + expect(execution.traffic.concurrency.queued).toBe(2); + }); + + execution.cancellation.cancel(); + const outcomes = await Promise.all(running); + + expect(outcomes.map((outcome) => outcome.kind)).toEqual([ + "CANCELLED", + "CANCELLED", + "CANCELLED", + ]); + expect(execution.traffic.concurrency.active).toBe(0); + expect(execution.traffic.concurrency.queued).toBe(0); + expect(transport.calls).toBe(1); + }); + + it("keeps KEYED command replay safety even when the budget allows retries", async () => { + const transport = vi.fn(networkFailure); + const execution = testExecutionContext({ + maxPhysicalRequests: 10, + maxRetries: 5, + }); + + const outcome = await testExecutor(transport).execute( + TEST_COMMAND, + { name: "entity" }, + { + routeId: ROUTE_ID, + scope: scopeSnapshot(), + execution, + intent: Object.freeze({ + intentId: "intent-1", + operationId: "TEST_CREATE_ENTITY", + canonicalInputIdentity: "opaque", + idempotencyKey: "key-1", + createdAtMonotonicMs: 1, + }), + }, + ); + + expect(outcome).toMatchObject({ + kind: "TRANSPORT_FAILURE", + effect: "MAYBE_APPLIED", + }); + expect(transport).toHaveBeenCalledTimes(1); + expect(execution.traffic.retries.consumed).toBe(0); + }); + + it("bounds an execution without an explicit interaction by the default policy", async () => { + const transport = vi.fn(networkFailure); + + await testExecutor(transport, { maxRetryAttempts: 2 }).execute( + TEST_QUERY, + { limit: 5 }, + { routeId: ROUTE_ID, scope: scopeSnapshot() }, + ); + + expect(transport).toHaveBeenCalledTimes(3); + }); +}); diff --git a/tests/platform/traffic/operation-traffic-policy.test.ts b/tests/platform/traffic/operation-traffic-policy.test.ts new file mode 100644 index 00000000..a0fc6b39 --- /dev/null +++ b/tests/platform/traffic/operation-traffic-policy.test.ts @@ -0,0 +1,80 @@ +import { describe, expect, it } from "vitest"; + +import { + composeContractContributions, + ContractContributionError, + type InstalledContractContribution, + type InstalledHttpContract, +} from "../../../src/contracts/external-contract-runtime.ts"; +import type { TrafficBudget } from "../../../src/platform/traffic/traffic-budget.ts"; +import { + TEST_CONTRACT_CONTRIBUTION, + TEST_LIST_HTTP_CONTRACT, +} from "../../helpers/external-contract-fixture.ts"; + +function compositionReason(run: () => unknown): string { + try { + run(); + } catch (error) { + return error instanceof ContractContributionError ? error.reason : String(error); + } + throw new Error("composition unexpectedly succeeded"); +} + +const FINITE: TrafficBudget = Object.freeze({ + maxPhysicalRequests: 3, + maxRetries: 2, + maxConcurrentRequests: 2, + maxQueuedRequests: 2, +}); + +function withTraffic(traffic: unknown): InstalledContractContribution { + const list = { + ...TEST_LIST_HTTP_CONTRACT, + frontend: { ...TEST_LIST_HTTP_CONTRACT.frontend, traffic }, + } as unknown as InstalledHttpContract; + return { + ...TEST_CONTRACT_CONTRIBUTION, + http: [list], + }; +} + +describe("operation traffic policy", () => { + it("requires finite positive traffic limits for an operation", () => { + expect( + compositionReason(() => + composeContractContributions([ + withTraffic({ ...FINITE, maxPhysicalRequests: Number.POSITIVE_INFINITY }), + ]), + ), + ).toMatch(/traffic.*maxPhysicalRequests/i); + }); + + it.each([ + { ...FINITE, maxRetries: -1 }, + { ...FINITE, maxConcurrentRequests: 0 }, + { maxPhysicalRequests: 3, maxRetries: 1, maxConcurrentRequests: 1 }, + { ...FINITE, extra: 1 }, + ])("rejects a malformed traffic policy %#", (traffic) => { + expect( + compositionReason(() => composeContractContributions([withTraffic(traffic)])), + ).toMatch(/traffic|field/i); + }); + + it("installs an immutable snapshot of a finite traffic policy", () => { + const source = { ...FINITE }; + const composed = composeContractContributions([withTraffic(source)]); + source.maxPhysicalRequests = 60; + + const installed = composed.httpByOperationId.get("TEST_LIST_ENTITIES"); + expect(installed?.frontend.traffic).toEqual(FINITE); + expect(Object.isFrozen(installed?.frontend.traffic)).toBe(true); + }); + + it("keeps operations without a traffic policy valid", () => { + const composed = composeContractContributions([TEST_CONTRACT_CONTRIBUTION]); + expect( + composed.httpByOperationId.get("TEST_LIST_ENTITIES")?.frontend.traffic, + ).toBeUndefined(); + }); +}); diff --git a/tests/platform/traffic/request-budget.test.ts b/tests/platform/traffic/request-budget.test.ts new file mode 100644 index 00000000..698088fb --- /dev/null +++ b/tests/platform/traffic/request-budget.test.ts @@ -0,0 +1,28 @@ +import { describe, expect, it } from "vitest"; + +import { createRequestBudget } from "../../../src/platform/traffic/request-budget.ts"; + +describe("createRequestBudget", () => { + it("allows exactly the configured number of physical requests", () => { + const budget = createRequestBudget(2); + expect(budget.tryConsume()).toBe(true); + expect(budget.tryConsume()).toBe(true); + expect(budget.tryConsume()).toBe(false); + expect(budget.consumed).toBe(2); + expect(budget.remaining).toBe(0); + }); + + it("never refills and never over-counts after exhaustion", () => { + const budget = createRequestBudget(1); + budget.tryConsume(); + for (let i = 0; i < 100; i += 1) budget.tryConsume(); + expect(budget.consumed).toBe(1); + }); + + it.each([0, -1, Number.POSITIVE_INFINITY, Number.NaN, 2.5])( + "rejects non-positive or unbounded maximum %s", + (maximum) => { + expect(() => createRequestBudget(maximum)).toThrow(TypeError); + }, + ); +}); diff --git a/tests/platform/traffic/request-deduplication.test.ts b/tests/platform/traffic/request-deduplication.test.ts new file mode 100644 index 00000000..98335ea8 --- /dev/null +++ b/tests/platform/traffic/request-deduplication.test.ts @@ -0,0 +1,89 @@ +import { describe, expect, it, vi } from "vitest"; + +import { + createQueryClient, + QUERY_CACHE_DEFAULTS, +} from "../../../src/adapters/query-cache/tanstack-query-cache.ts"; +import type { InstalledHttpContract } from "../../../src/contracts/external-contract-runtime.ts"; +import { TEST_LIST_HTTP_CONTRACT } from "../../helpers/external-contract-fixture.ts"; +import { + jsonRows, + networkFailure, + scopeSnapshot, + testExecutor, + type Transport, +} from "../../helpers/traffic-test-kit.ts"; + +const TEST_QUERY = TEST_LIST_HTTP_CONTRACT as InstalledHttpContract< + unknown, + unknown, + unknown +>; + +/** + * Spec ยง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. + */ +describe("request deduplication and coalescing", () => { + function loadSameQuery( + client: ReturnType, + executor: ReturnType, + key: readonly unknown[] = ["entities", "list", { limit: 20 }], + ) { + return client.fetchQuery({ + queryKey: key, + queryFn: ({ signal }) => + executor.execute(TEST_QUERY, { limit: 20 }, { + routeId: "TEST_ROUTE", + scope: scopeSnapshot(), + signal, + }), + }); + } + + it("coalesces concurrent consumers of the same query identity", async () => { + const transport = vi.fn(async () => jsonRows(3)); + const executor = testExecutor(transport); + const client = createQueryClient(); + + const results = await Promise.all([ + loadSameQuery(client, executor), + loadSameQuery(client, executor), + loadSameQuery(client, executor), + ]); + + expect(transport).toHaveBeenCalledTimes(1); + expect(results.every((result) => result.kind === "SUCCESS")).toBe(true); + client.clear(); + }); + + it("keeps distinct query identities as distinct physical requests", async () => { + const transport = vi.fn(async () => jsonRows(1)); + const executor = testExecutor(transport); + const client = createQueryClient(); + + await Promise.all([ + loadSameQuery(client, executor, ["entities", "list", 1]), + loadSameQuery(client, executor, ["entities", "list", 2]), + ]); + + expect(transport).toHaveBeenCalledTimes(2); + client.clear(); + }); + + it("does not stack a query-layer retry on top of the executor retry budget", async () => { + expect(QUERY_CACHE_DEFAULTS.retry).toBe(false); + expect(QUERY_CACHE_DEFAULTS.mutationRetry).toBe(false); + + const transport = vi.fn(networkFailure); + const executor = testExecutor(transport, { maxRetryAttempts: 2 }); + const client = createQueryClient(); + + await Promise.all([loadSameQuery(client, executor), loadSameQuery(client, executor)]); + + // One coalesced logical execution: 1 attempt + at most 2 executor retries. + expect(transport.mock.calls.length).toBeLessThanOrEqual(3); + client.clear(); + }); +}); diff --git a/tests/platform/traffic/request-fanout.test.ts b/tests/platform/traffic/request-fanout.test.ts new file mode 100644 index 00000000..1a3ddb79 --- /dev/null +++ b/tests/platform/traffic/request-fanout.test.ts @@ -0,0 +1,74 @@ +import { describe, expect, it, vi } from "vitest"; + +import type { InstalledHttpContract } from "../../../src/contracts/external-contract-runtime.ts"; +import { + assertRequestFanoutWithinBudget, + RequestFanoutExceededError, +} from "../../../src/platform/traffic/request-fanout.ts"; +import { TEST_LIST_HTTP_CONTRACT } from "../../helpers/external-contract-fixture.ts"; +import { + jsonRows, + paginatedCollection, + scopeSnapshot, + testExecutionContext, + testExecutor, + type Transport, +} from "../../helpers/traffic-test-kit.ts"; + +const TEST_QUERY = TEST_LIST_HTTP_CONTRACT as InstalledHttpContract< + unknown, + unknown, + unknown +>; + +/** Physical requests one collection load may cost. */ +const COLLECTION_LOAD_FANOUT_BUDGET = 1; + +/** + * Spec ยง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) { + const execution = testExecutionContext({ maxPhysicalRequests: 3 }); + const outcome = await testExecutor(transport).execute(TEST_QUERY, { limit: 100 }, { + routeId: "TEST_ROUTE", + scope: scopeSnapshot(), + execution, + }); + return { outcome, execution }; +} + +describe("request fan-out budget", () => { + it.each([10, 50, 100, 1_000])( + "loads a page of a %i-row collection with one physical request", + async (totalRows) => { + const transport = paginatedCollection(totalRows); + + const { outcome, execution } = await loadCollection(transport); + + expect(outcome.kind).toBe("SUCCESS"); + expect(outcome.kind === "SUCCESS" && outcome.value).toHaveLength(Math.min(totalRows, 100)); + expect(execution.traffic.requests.consumed).toBe(transport.calls); + expect(() => + assertRequestFanoutWithinBudget(transport.calls, COLLECTION_LOAD_FANOUT_BUDGET), + ).not.toThrow(); + }, + ); + + it("rejects a single oversized response in one request without row-proportional fan-out", async () => { + const transport = vi.fn(async () => jsonRows(1_000)); + const { outcome } = await loadCollection(transport); + expect(outcome.kind).toBe("CONTRACT_VIOLATION"); + expect(transport).toHaveBeenCalledTimes(1); + }); + + it("fails loudly when a flow exceeds its fan-out budget", () => { + expect(() => assertRequestFanoutWithinBudget(4, 3)).toThrow( + RequestFanoutExceededError, + ); + expect(() => assertRequestFanoutWithinBudget(4, 3)).toThrow( + /fan-out 4 exceeds 3/, + ); + expect(() => assertRequestFanoutWithinBudget(1, 0)).toThrow(TypeError); + }); +}); diff --git a/tests/platform/traffic/traffic-amplification.test.ts b/tests/platform/traffic/traffic-amplification.test.ts new file mode 100644 index 00000000..68e91ef1 --- /dev/null +++ b/tests/platform/traffic/traffic-amplification.test.ts @@ -0,0 +1,101 @@ +import { describe, expect, it, vi } from "vitest"; + +import type { InstalledHttpContract } from "../../../src/contracts/external-contract-runtime.ts"; +import { TEST_LIST_HTTP_CONTRACT } from "../../helpers/external-contract-fixture.ts"; +import { + networkFailure, + scopeSnapshot, + testExecutionContext, + testExecutor, + type Transport, +} from "../../helpers/traffic-test-kit.ts"; + +const TEST_QUERY = TEST_LIST_HTTP_CONTRACT as InstalledHttpContract< + unknown, + unknown, + unknown +>; + +/** + * Spec ยง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. + */ +async function runInteraction( + options: Readonly<{ + transport: Transport; + maxPhysicalRequests: number; + maxRetries: number; + operationsPerInteraction?: number; + }>, +) { + const executor = testExecutor(options.transport, { maxRetryAttempts: 2 }); + const execution = testExecutionContext({ + maxPhysicalRequests: options.maxPhysicalRequests, + maxRetries: options.maxRetries, + maxConcurrentRequests: 2, + maxQueuedRequests: 8, + }); + const context = { routeId: "TEST_ROUTE", scope: scopeSnapshot(), execution }; + await Promise.all( + Array.from({ length: options.operationsPerInteraction ?? 1 }, () => + executor.execute(TEST_QUERY, { limit: 5 }, context), + ), + ); + return execution; +} + +describe("traffic amplification invariants", () => { + it("keeps physical requests bounded when every dispatch fails", async () => { + const transport = vi.fn(networkFailure); + const interactions = Array.from({ length: 1_000 }, () => + runInteraction({ transport, maxPhysicalRequests: 2, maxRetries: 1 }), + ); + + await Promise.allSettled(interactions); + + expect(transport.mock.calls.length).toBeLessThanOrEqual(2_000); + }); + + it("does not let parallel operations inside one interaction multiply retries", async () => { + const transport = vi.fn(networkFailure); + const results = await Promise.all( + Array.from({ length: 200 }, () => + runInteraction({ + transport, + maxPhysicalRequests: 4, + maxRetries: 1, + operationsPerInteraction: 5, + }), + ), + ); + + // Without the shared budget: 5 ops x 3 attempts = 15 requests each. + expect(transport.mock.calls.length).toBeLessThanOrEqual(200 * 4); + for (const execution of results) { + expect(execution.traffic.retries.consumed).toBeLessThanOrEqual(1); + expect(execution.traffic.requests.consumed).toBeLessThanOrEqual(4); + expect(execution.traffic.concurrency.active).toBe(0); + expect(execution.traffic.concurrency.queued).toBe(0); + } + }); + + it("amplifies at most maxPhysicalRequests per interaction across budget sizes", async () => { + for (const maxPhysicalRequests of [1, 2, 3]) { + const transport = vi.fn(networkFailure); + await Promise.all( + Array.from({ length: 100 }, () => + runInteraction({ + transport, + maxPhysicalRequests, + maxRetries: 5, + operationsPerInteraction: 3, + }), + ), + ); + expect(transport.mock.calls.length / 100).toBeLessThanOrEqual( + maxPhysicalRequests, + ); + } + }); +}); diff --git a/tests/platform/traffic/traffic-budget.test.ts b/tests/platform/traffic/traffic-budget.test.ts new file mode 100644 index 00000000..699b3767 --- /dev/null +++ b/tests/platform/traffic/traffic-budget.test.ts @@ -0,0 +1,59 @@ +import { describe, expect, it } from "vitest"; + +import { + createTrafficRuntime, + defineTrafficBudget, +} from "../../../src/platform/traffic/traffic-budget.ts"; +import { createExecutionContext } from "../../../src/platform/execution/execution-context.ts"; + +const POLICY = { + maxPhysicalRequests: 4, + maxRetries: 1, + maxConcurrentRequests: 2, + maxQueuedRequests: 2, +} as const; + +describe("createTrafficRuntime", () => { + it("creates one request, retry, and concurrency budget per interaction", () => { + const runtime = createTrafficRuntime(POLICY); + + expect(runtime.requests.maximum).toBe(4); + expect(runtime.retries.maximum).toBe(1); + expect(runtime.concurrency.maximum).toBe(2); + expect(runtime.concurrency.maxQueued).toBe(2); + expect(Object.isFrozen(runtime.policy)).toBe(true); + }); + + it("keeps immutable policy separate from mutable per-interaction counters", () => { + const a = createTrafficRuntime(POLICY); + const b = createTrafficRuntime(POLICY); + a.requests.tryConsume(); + expect(a.requests.consumed).toBe(1); + expect(b.requests.consumed).toBe(0); + }); + + it("shares one runtime with every child of an execution context", () => { + const context = createExecutionContext({ + interactionId: "shared", + deadlineMs: 1_000, + traffic: POLICY, + }); + const childA = context.traffic; + const childB = context.traffic; + childA.retries.tryConsume("a"); + expect(childB.retries.tryConsume("b")).toBe(false); + }); + + it.each([ + ["maxPhysicalRequests", Number.POSITIVE_INFINITY], + ["maxRetries", -1], + ["maxConcurrentRequests", 0], + ["maxQueuedRequests", Number.NaN], + ["maxPhysicalRequests", 65], + ["maxQueuedRequests", 257], + ] as const)("rejects %s=%s", (key, value) => { + expect(() => defineTrafficBudget({ ...POLICY, [key]: value })).toThrow( + new RegExp(key), + ); + }); +}); diff --git a/tests/platform/validation/bounded-json.test.ts b/tests/platform/validation/bounded-json.test.ts new file mode 100644 index 00000000..ad9e1062 --- /dev/null +++ b/tests/platform/validation/bounded-json.test.ts @@ -0,0 +1,139 @@ +import { describe, expect, it, vi } from "vitest"; + +import type { InstalledHttpContract } from "../../../src/contracts/external-contract-runtime.ts"; +import { + checkJsonStructure, + JsonBudgetExceededError, + parseBoundedJson, + validateJsonStructure, +} from "../../../src/platform/validation/bounded-json.ts"; +import { TEST_LIST_HTTP_CONTRACT } from "../../helpers/external-contract-fixture.ts"; +import { + scopeSnapshot, + testExecutor, + type Transport, +} from "../../helpers/traffic-test-kit.ts"; + +const BUDGET = { + maxBytes: 100, + maxItems: 10, + maxDepth: 10, + maxStringLength: 100, +}; + +describe("parseBoundedJson", () => { + it("rejects oversized input before JSON.parse is invoked", () => { + const parse = vi.spyOn(JSON, "parse"); + const payload = "x".repeat(101); + + expect(() => + parseBoundedJson(payload, { + maxBytes: 100, + maxItems: 10, + maxDepth: 10, + maxStringLength: 100, + }), + ).toThrow(/too-large/i); + + expect(parse).not.toHaveBeenCalled(); + }); + + it("counts multi-byte characters against the byte ceiling", () => { + const payload = `"${"ํ•œ".repeat(40)}"`; // 42 UTF-16 units, 122 UTF-8 bytes + expect(() => parseBoundedJson(payload, BUDGET)).toThrow(/too-large/i); + }); + + it("parses a payload inside every limit", () => { + expect(parseBoundedJson('{"a":[1,2,3]}', BUDGET)).toEqual({ a: [1, 2, 3] }); + }); + + it("reports malformed JSON as a budget error, not a raw SyntaxError", () => { + expect(() => parseBoundedJson("{", BUDGET)).toThrow(JsonBudgetExceededError); + }); +}); + +describe("validateJsonStructure", () => { + it("rejects arrays above maxItems", () => { + expect(() => validateJsonStructure([1, 2, 3], { ...BUDGET, maxItems: 2 })) + .toThrow(/items/i); + }); + + it("rejects nesting above maxDepth", () => { + let nested: unknown = 1; + for (let depth = 0; depth < 5; depth += 1) nested = [nested]; + expect(() => + validateJsonStructure(nested, { ...BUDGET, maxDepth: 3 }), + ).toThrow(/deep/i); + }); + + it("rejects strings above maxStringLength", () => { + expect(() => + validateJsonStructure({ name: "x".repeat(11) }, { ...BUDGET, maxStringLength: 10 }), + ).toThrow(/string/i); + }); + + it("rejects objects wider than maxItems and counts total nodes", () => { + const wide = Object.fromEntries( + Array.from({ length: 11 }, (_, index) => [`k${index}`, index]), + ); + expect(checkJsonStructure(wide, BUDGET)).toMatchObject({ ok: false }); + expect(checkJsonStructure([[1, 2], [3, 4]], { ...BUDGET, maxItems: 6 })).toMatchObject({ + ok: false, + violation: "too-many-items", + }); + }); + + it("walks adversarial nesting iteratively without overflowing the stack", () => { + let nested: unknown = 0; + for (let depth = 0; depth < 200_000; depth += 1) nested = [nested]; + expect(() => + validateJsonStructure(nested, { + maxBytes: 1_000_000, + maxItems: 1_000_000, + maxDepth: 1_000_000, + maxStringLength: 10, + }), + ).not.toThrow(); + expect(checkJsonStructure(nested, { ...BUDGET, maxItems: 1_000_000 })).toMatchObject({ + ok: false, + violation: "too-deep", + }); + }); +}); + +describe("response structure budget in the V3 executor", () => { + const TEST_QUERY = TEST_LIST_HTTP_CONTRACT as InstalledHttpContract< + unknown, + unknown, + unknown + >; + + it("rejects a deeply nested response before schema validation runs", async () => { + let nested = "0"; + for (let depth = 0; depth < 100; depth += 1) nested = `[${nested}]`; + const safeParse = vi.fn(() => ({ success: true as const, data: [] })); + const operation = { + ...TEST_QUERY, + contract: { + ...TEST_QUERY.contract, + outputValidator: { schemaId: "SpyPayload", safeParse }, + }, + } as InstalledHttpContract; + const transport = vi.fn( + async () => + new Response(nested, { headers: { "content-type": "application/json" } }), + ); + + const outcome = await testExecutor(transport).execute(operation, { limit: 1 }, { + routeId: "TEST_ROUTE", + scope: scopeSnapshot(), + }); + + expect(outcome).toMatchObject({ + kind: "CONTRACT_VIOLATION", + violation: { kind: "RESPONSE_TOO_LARGE" }, + }); + expect(safeParse).not.toHaveBeenCalled(); + expect(transport).toHaveBeenCalledTimes(1); + }); +}); diff --git a/tests/platform/validation/validation-budget.test.ts b/tests/platform/validation/validation-budget.test.ts new file mode 100644 index 00000000..c3dbe384 --- /dev/null +++ b/tests/platform/validation/validation-budget.test.ts @@ -0,0 +1,43 @@ +import { describe, expect, it } from "vitest"; + +import { + defineValidationBudget, + responseValidationBudget, +} from "../../../src/platform/validation/validation-budget.ts"; + +const BUDGET = { + maxBytes: 1_024, + maxItems: 1_000, + maxDepth: 20, + maxStringLength: 32_768, +}; + +describe("defineValidationBudget", () => { + it("rejects unbounded validation configuration", () => { + expect(() => + defineValidationBudget({ ...BUDGET, maxBytes: Infinity }), + ).toThrow(/maxBytes/); + }); + + it.each(["maxBytes", "maxItems", "maxDepth", "maxStringLength"] as const)( + "rejects a non-positive or fractional %s", + (key) => { + expect(() => defineValidationBudget({ ...BUDGET, [key]: 0 })).toThrow(key); + expect(() => defineValidationBudget({ ...BUDGET, [key]: 1.5 })).toThrow(key); + expect(() => defineValidationBudget({ ...BUDGET, [key]: Number.NaN })).toThrow(key); + }, + ); + + it("returns an immutable copy", () => { + const budget = defineValidationBudget(BUDGET); + expect(budget).toEqual(BUDGET); + expect(Object.isFrozen(budget)).toBe(true); + }); + + it("derives a finite response structure budget from the byte ceiling", () => { + const budget = responseValidationBudget(262_144); + expect(budget.maxBytes).toBe(262_144); + expect(Number.isSafeInteger(budget.maxItems)).toBe(true); + expect(Number.isSafeInteger(budget.maxDepth)).toBe(true); + }); +}); diff --git a/tests/release/fixtures/R10/assets/app.aaaa.js.fixture b/tests/release/fixtures/R10/assets/app.aaaa.js.fixture new file mode 100644 index 00000000..a396f5dd --- /dev/null +++ b/tests/release/fixtures/R10/assets/app.aaaa.js.fixture @@ -0,0 +1 @@ +export const RELEASE = "R10"; diff --git a/tests/release/fixtures/R10/config.json b/tests/release/fixtures/R10/config.json new file mode 100644 index 00000000..d4f781b7 --- /dev/null +++ b/tests/release/fixtures/R10/config.json @@ -0,0 +1,19 @@ +{ + "APP_ENV": "production", + "API_BASE_URL": "https://api.example.test/", + "REQUEST_TIMEOUT_MS": 10000, + "MAX_RETRY_ATTEMPTS": 2, + "TELEMETRY_ENABLED": false, + "AUTH_MODE": "external", + "RELEASE_MANIFEST_URL": "/release-manifest.json", + "RELEASE_ID": "release-R10", + "BUILD_ID": "build-R10", + "CONFIG_SCHEMA_VERSION": "2.0", + "CAPABILITY_OVERRIDES": { + "REALTIME": "DEFAULT", + "WEB_WORKER": "DEFAULT", + "SERVICE_WORKER": "DEFAULT", + "OFFLINE_COMMANDS": "DEFAULT" + }, + "FEATURE_OVERRIDES": {} +} diff --git a/tests/release/fixtures/R10/index.html b/tests/release/fixtures/R10/index.html new file mode 100644 index 00000000..d6278060 --- /dev/null +++ b/tests/release/fixtures/R10/index.html @@ -0,0 +1,10 @@ + + + + + + Release R10 + + +
+ diff --git a/tests/release/fixtures/R10/release-manifest.json b/tests/release/fixtures/R10/release-manifest.json new file mode 100644 index 00000000..d7721d99 --- /dev/null +++ b/tests/release/fixtures/R10/release-manifest.json @@ -0,0 +1,16 @@ +{ + "schemaVersion": 2, + "appVersion": "0.1.0", + "buildId": "build-R10", + "commitSha": "abc123", + "configSchemaVersion": "2.0", + "assetManifestHash": "assets-aaaa", + "releaseId": "release-R10", + "builtAt": "2026-09-23T00:00:00Z", + "routeChunks": { "route-home": "assets/app.aaaa.js" }, + "contractSet": { + "setAlgorithm": "CA_CONTRACT_SET_V1", + "setDigest": "__EMPTY_SET_DIGEST__", + "packages": [] + } +} diff --git a/tests/release/fixtures/R11/assets/app.bbbb.js.fixture b/tests/release/fixtures/R11/assets/app.bbbb.js.fixture new file mode 100644 index 00000000..90ce21cd --- /dev/null +++ b/tests/release/fixtures/R11/assets/app.bbbb.js.fixture @@ -0,0 +1 @@ +export const RELEASE = "R11"; diff --git a/tests/release/fixtures/R11/config.json b/tests/release/fixtures/R11/config.json new file mode 100644 index 00000000..c275a999 --- /dev/null +++ b/tests/release/fixtures/R11/config.json @@ -0,0 +1,19 @@ +{ + "APP_ENV": "production", + "API_BASE_URL": "https://api.example.test/", + "REQUEST_TIMEOUT_MS": 10000, + "MAX_RETRY_ATTEMPTS": 2, + "TELEMETRY_ENABLED": false, + "AUTH_MODE": "external", + "RELEASE_MANIFEST_URL": "/release-manifest.json", + "RELEASE_ID": "release-R11", + "BUILD_ID": "build-R11", + "CONFIG_SCHEMA_VERSION": "2.0", + "CAPABILITY_OVERRIDES": { + "REALTIME": "DEFAULT", + "WEB_WORKER": "DEFAULT", + "SERVICE_WORKER": "DEFAULT", + "OFFLINE_COMMANDS": "DEFAULT" + }, + "FEATURE_OVERRIDES": {} +} diff --git a/tests/release/fixtures/R11/index.html b/tests/release/fixtures/R11/index.html new file mode 100644 index 00000000..b1ea7802 --- /dev/null +++ b/tests/release/fixtures/R11/index.html @@ -0,0 +1,10 @@ + + + + + + Release R11 + + +
+ diff --git a/tests/release/fixtures/R11/release-manifest.json b/tests/release/fixtures/R11/release-manifest.json new file mode 100644 index 00000000..aa80d307 --- /dev/null +++ b/tests/release/fixtures/R11/release-manifest.json @@ -0,0 +1,16 @@ +{ + "schemaVersion": 2, + "appVersion": "0.1.0", + "buildId": "build-R11", + "commitSha": "abc123", + "configSchemaVersion": "2.0", + "assetManifestHash": "assets-bbbb", + "releaseId": "release-R11", + "builtAt": "2026-09-23T00:00:00Z", + "routeChunks": { "route-home": "assets/app.bbbb.js" }, + "contractSet": { + "setAlgorithm": "CA_CONTRACT_SET_V1", + "setDigest": "__EMPTY_SET_DIGEST__", + "packages": [] + } +} diff --git a/tests/release/mixed-replica.test.ts b/tests/release/mixed-replica.test.ts new file mode 100644 index 00000000..6c251f9c --- /dev/null +++ b/tests/release/mixed-replica.test.ts @@ -0,0 +1,104 @@ +import { describe, expect, it } from "vitest"; + +import { createReleaseMismatchRecovery } from "../../src/platform/release/release-mismatch-recovery.ts"; +import { + bootAgainstReplicaSequence, + createReleaseFixture, + memoryStorage, + response, + runBootSession, + type ReleaseName, + type Surface, +} from "./release-fixture.ts"; + +/** A deterministic load balancer that alternates replicas request by request. */ +function alternatingLoadBalancer(replicas: readonly ReleaseName[], offset = 0) { + let request = offset; + return (): readonly Readonly<{ kind: Surface; release: ReleaseName }>[] => + (["html", "config", "manifest"] as const).map((kind) => + response(kind, replicas[request++ % replicas.length] as ReleaseName), + ); +} + +describe("mixed-replica routing during a rolling release", () => { + it("boots when every response comes from R10", async () => { + const result = await bootAgainstReplicaSequence([ + response("html", "R10"), + response("config", "R10"), + response("manifest", "R10"), + ]); + expect(result).toMatchObject({ state: "booted", applicationMounted: true, release: "release-R10" }); + }); + + it("boots when every response comes from R11", async () => { + const result = await bootAgainstReplicaSequence([ + response("html", "R11"), + response("config", "R11"), + response("manifest", "R11"), + ]); + expect(result).toMatchObject({ state: "booted", applicationMounted: true, release: "release-R11" }); + }); + + it("fails closed when HTML and runtime config come from different releases", async () => { + const result = await bootAgainstReplicaSequence([ + response("html", "R10"), + response("config", "R11"), + response("manifest", "R10"), + ]); + + expect(result.state).toBe("release-mismatch"); + expect(result.applicationMounted).toBe(false); + }); + + it("fails closed when the manifest comes from a different release", async () => { + const result = await bootAgainstReplicaSequence([ + response("html", "R10"), + response("config", "R10"), + response("manifest", "R11"), + ]); + expect(result).toMatchObject({ state: "release-mismatch", applicationMounted: false }); + }); + + it("never produces a silently mixed boot under an alternating load balancer", async () => { + for (let offset = 0; offset < 6; offset += 1) { + const next = alternatingLoadBalancer(["R10", "R11"], offset); + for (let boot = 0; boot < 10; boot += 1) { + const sequence = next(); + const releases = new Set(sequence.map((entry) => entry.release)); + const result = await bootAgainstReplicaSequence(sequence); + if (releases.size > 1) { + expect(result.applicationMounted).toBe(false); + } else { + expect(result.state).toBe("booted"); + } + } + } + }); + + it("recovers a stale HTML document with exactly one reload once the rollout converges", async () => { + const deployment = createReleaseFixture(["R10", "R11"]); + const sequences = [ + [response("html", "R10"), response("config", "R11"), response("manifest", "R11")], + [response("html", "R11"), response("config", "R11"), response("manifest", "R11")], + ]; + let boot = 0; + const session = await runBootSession( + () => sequences[Math.min(boot++, sequences.length - 1)] ?? [], + createReleaseMismatchRecovery(memoryStorage()), + deployment, + ); + expect(session.reloads).toBe(1); + expect(session.final).toMatchObject({ state: "booted", release: "release-R11" }); + }); + + it("cannot reload-loop when replicas stay permanently mixed", async () => { + const storage = memoryStorage(); + const session = await runBootSession( + () => [response("html", "R10"), response("config", "R11"), response("manifest", "R10")], + createReleaseMismatchRecovery(storage), + ); + expect(session.reloads).toBe(1); + expect(session.final).toMatchObject({ state: "release-mismatch", applicationMounted: false }); + expect(storage.size()).toBe(1); + }); +}); diff --git a/tests/release/old-asset-reachability.test.ts b/tests/release/old-asset-reachability.test.ts new file mode 100644 index 00000000..2f6dcc62 --- /dev/null +++ b/tests/release/old-asset-reachability.test.ts @@ -0,0 +1,42 @@ +import { describe, expect, it } from "vitest"; + +import { CACHE_POLICY, createReleaseFixture } from "./release-fixture.ts"; + +describe("old hashed-asset reachability", () => { + it("keeps R10 hashed assets reachable after R11 becomes active", async () => { + const deployment = createReleaseFixture(["R10", "R11"]); + deployment.activate("R11"); + + expect(await deployment.fetch("/releases/R10/assets/app.aaaa.js")) + .toMatchObject({ status: 200 }); + expect(await deployment.fetch("/assets/app.aaaa.js")).toMatchObject({ + status: 200, + release: "R10", + }); + }); + + it("serves distinct, never-overwritten hashed names per release", async () => { + const deployment = createReleaseFixture(["R10", "R11"]); + const old = await deployment.fetch("/assets/app.aaaa.js"); + const current = await deployment.fetch("/assets/app.bbbb.js"); + expect(old.body).toContain('"R10"'); + expect(current.body).toContain('"R11"'); + expect(old.headers["cache-control"]).toBe(CACHE_POLICY.surfaces.hashedAsset.cacheControl); + }); + + it("switches mutable surfaces to the active release only", async () => { + const deployment = createReleaseFixture(["R10", "R11"]); + deployment.activate("R11"); + expect((await deployment.fetch("/")).release).toBe("R11"); + expect((await deployment.fetch("/config.json")).release).toBe("R11"); + expect((await deployment.fetch("/release-manifest.json")).release).toBe("R11"); + expect((await deployment.fetch("/config.json")).headers["cache-control"]).toBe("no-store"); + }); + + it("detects an unsafe deploy that removed old assets inside the rolling window", async () => { + const deployment = createReleaseFixture(["R10", "R11"]); + deployment.activate("R11"); + deployment.retireAssets("R10"); + expect(await deployment.fetch("/assets/app.aaaa.js")).toMatchObject({ status: 404 }); + }); +}); diff --git a/tests/release/release-fixture.ts b/tests/release/release-fixture.ts new file mode 100644 index 00000000..ad97d0d6 --- /dev/null +++ b/tests/release/release-fixture.ts @@ -0,0 +1,265 @@ +import { readdirSync, readFileSync } from "node:fs"; +import path from "node:path"; + +import { loadReleaseManifest } from "../../src/bootstrap/load-release-manifest.ts"; +import { loadRuntimeConfig } from "../../src/bootstrap/load-runtime-config.ts"; +import { releaseMismatchKey } from "../../src/bootstrap/boot-release-recovery.ts"; +import { computeContractSetDigest } from "../../src/contracts/contract-set-canonical.ts"; +import type { ReleaseMismatchRecovery } from "../../src/platform/release/release-mismatch-recovery.ts"; + +/** + * A static multi-release deployment built from immutable fixture artifacts + * (tests/release/fixtures//). Responses carry the repository's real + * cache policy (config/hosting/cache-policy.json), and hashed assets of every + * retained release stay addressable after a newer release is activated. + */ +export type ReleaseName = "R10" | "R11"; +export type Surface = "html" | "config" | "manifest"; + +const FIXTURE_ROOT = path.resolve("tests/release/fixtures"); +const EMPTY_SET_DIGEST = await computeContractSetDigest([]); + +type CachePolicy = Readonly<{ + surfaces: Readonly<{ + index: Readonly<{ cacheControl: string }>; + runtimeConfig: Readonly<{ cacheControl: string }>; + releaseManifest: Readonly<{ cacheControl: string }>; + hashedAsset: Readonly<{ cacheControl: string }>; + }>; +}>; + +export const CACHE_POLICY = JSON.parse( + readFileSync(path.resolve("config/hosting/cache-policy.json"), "utf8"), +) as CachePolicy; + +type ReleaseArtifacts = Readonly<{ + html: string; + config: string; + manifest: string; + assets: ReadonlyMap; +}>; + +export function readRelease(release: ReleaseName): ReleaseArtifacts { + const root = path.join(FIXTURE_ROOT, release); + const assets = new Map(); + for (const file of readdirSync(path.join(root, "assets"))) { + // Fixtures are stored as `.js.fixture` so no executable JS lives in tests/. + assets.set( + file.replace(/\.fixture$/u, ""), + readFileSync(path.join(root, "assets", file), "utf8"), + ); + } + return Object.freeze({ + html: readFileSync(path.join(root, "index.html"), "utf8"), + config: readFileSync(path.join(root, "config.json"), "utf8"), + manifest: readFileSync(path.join(root, "release-manifest.json"), "utf8").replace( + "__EMPTY_SET_DIGEST__", + EMPTY_SET_DIGEST, + ), + assets, + }); +} + +export type FixtureResponse = Readonly<{ + status: number; + headers: Readonly>; + body: string; + release?: ReleaseName; +}>; + +function respond( + status: number, + cacheControl: string, + contentType: string, + body: string, + release?: ReleaseName, +): FixtureResponse { + return Object.freeze({ + status, + headers: Object.freeze({ "cache-control": cacheControl, "content-type": contentType }), + body, + ...(release === undefined ? {} : { release }), + }); +} + +const NOT_FOUND = respond(404, "no-store", "text/plain", "not found"); + +export function createReleaseFixture(releases: readonly ReleaseName[]) { + const retained = new Map( + releases.map((release) => [release, readRelease(release)]), + ); + /** Hashed assets have their own retention: the rolling window. */ + const assetStores = new Map>( + [...retained].map(([release, artifacts]) => [release, artifacts.assets]), + ); + let active: ReleaseName = releases[0] as ReleaseName; + const policy = CACHE_POLICY.surfaces; + + function surface(release: ReleaseName, kind: Surface): FixtureResponse { + const artifacts = retained.get(release); + if (!artifacts) return NOT_FOUND; + switch (kind) { + case "html": + return respond(200, policy.index.cacheControl, "text/html; charset=utf-8", artifacts.html, release); + case "config": + return respond(200, policy.runtimeConfig.cacheControl, "application/json", artifacts.config, release); + case "manifest": + return respond(200, policy.releaseManifest.cacheControl, "application/json", artifacts.manifest, release); + } + } + + function asset(file: string, onlyRelease?: string): FixtureResponse { + for (const [release, assets] of assetStores) { + if (onlyRelease !== undefined && release !== onlyRelease) continue; + const body = assets.get(file); + if (body !== undefined) { + return respond(200, policy.hashedAsset.cacheControl, "text/javascript", body, release); + } + } + return NOT_FOUND; + } + + return Object.freeze({ + activate(release: ReleaseName) { + if (!retained.has(release)) { + const artifacts = readRelease(release); + retained.set(release, artifacts); + assetStores.set(release, artifacts.assets); + } + active = release; + }, + /** + * The rolling window closes for a release's hashed assets (an unsafe + * deploy would do this too early). Its mutable surfaces may still be + * served by a lagging replica. + */ + retireAssets(release: ReleaseName) { + assetStores.delete(release); + }, + get active() { + return active; + }, + surface, + /** + * Mutable surfaces come from the active release (or an explicit replica); + * hashed assets come from any retained release, addressed by name or by + * `/releases//assets/`. + */ + async fetch(requestPath: string, replica?: ReleaseName): Promise { + const releaseAddressed = /^\/releases\/(R\d+)\/assets\/([^/]+)$/u.exec(requestPath); + if (releaseAddressed) return asset(releaseAddressed[2] as string, releaseAddressed[1]); + const hashed = /^\/assets\/([^/]+)$/u.exec(requestPath); + if (hashed) return asset(hashed[1] as string); + const release = replica ?? active; + if (requestPath === "/" || requestPath === "/index.html") return surface(release, "html"); + if (requestPath === "/config.json") return surface(release, "config"); + if (requestPath === "/release-manifest.json") return surface(release, "manifest"); + return NOT_FOUND; + }, + }); +} + +export type ReleaseDeployment = ReturnType; + +export function response(kind: Surface, release: ReleaseName) { + return Object.freeze({ kind, release }); +} + +function toFetchResponse(fixture: FixtureResponse): Response { + return new Response(fixture.body, { status: fixture.status, headers: fixture.headers }); +} + +export type BootResult = Readonly<{ + state: "booted" | "release-mismatch" | "asset-missing" | "boot-failed"; + applicationMounted: boolean; + mismatchKey?: string; + release?: string; +}>; + +/** + * Boots the real runtime-config and release-manifest loaders against an + * explicit sequence of replica responses (html, config, manifest), then loads + * the HTML's hashed entry asset. Nothing mounts unless every step is coherent. + */ +export async function bootAgainstReplicaSequence( + sequence: readonly Readonly<{ kind: Surface; release: ReleaseName }>[], + deployment: ReleaseDeployment = createReleaseFixture(["R10", "R11"]), +): Promise { + const pick = (kind: Surface) => { + const entry = sequence.find((candidate) => candidate.kind === kind); + if (!entry) throw new TypeError(`sequence has no ${kind} response`); + return deployment.surface(entry.release, kind); + }; + const html = pick("html"); + const buildId = / toFetchResponse(pick("config")), + }); + const manifest = await loadReleaseManifest(runtime, { + fetcher: async () => toFetchResponse(pick("manifest")), + }); + const asset = await deployment.fetch(entryAsset); + if (asset.status !== 200) { + return { state: "asset-missing", applicationMounted: false }; + } + return { state: "booted", applicationMounted: true, release: manifest.releaseId }; + } catch (error) { + const key = releaseMismatchKey(error); + return key === null + ? { state: "boot-failed", applicationMounted: false } + : { state: "release-mismatch", applicationMounted: false, mismatchKey: key }; + } +} + +/** + * Drives a browser session through repeated boots: a mismatch asks the + * recovery policy, and `reload-once` triggers another boot. Returns how many + * automatic reloads happened before the session settled. + */ +export async function runBootSession( + nextSequence: () => readonly Readonly<{ kind: Surface; release: ReleaseName }>[], + recovery: ReleaseMismatchRecovery, + deployment?: ReleaseDeployment, + maxBoots = 20, +): Promise> { + let reloads = 0; + for (let boot = 0; boot < maxBoots; boot += 1) { + const result = await bootAgainstReplicaSequence(nextSequence(), deployment); + if (result.state === "booted") { + recovery.markCoherentBoot(); + return { reloads, final: result }; + } + if (result.mismatchKey !== undefined && recovery.decide(result.mismatchKey) === "reload-once") { + reloads += 1; + continue; + } + return { reloads, final: result }; + } + throw new Error("boot session did not settle: reload loop"); +} + +/** An in-memory session marker store for simulated browser sessions. */ +export function memoryStorage() { + let marker: string | null = null; + return { + read: () => marker, + write: (value: string) => { + marker = value; + }, + clear: () => { + marker = null; + }, + size: () => (marker === null ? 0 : 1), + }; +} diff --git a/tests/release/release-matrix.test.ts b/tests/release/release-matrix.test.ts new file mode 100644 index 00000000..ab017482 --- /dev/null +++ b/tests/release/release-matrix.test.ts @@ -0,0 +1,91 @@ +import { describe, expect, it } from "vitest"; + +import { createReleaseMismatchRecovery } from "../../src/platform/release/release-mismatch-recovery.ts"; +import { + bootAgainstReplicaSequence, + createReleaseFixture, + memoryStorage, + response, + runBootSession, +} from "./release-fixture.ts"; + +/** + * Spec ยง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. + */ +describe("multi-replica release-coherence matrix", () => { + it("R10/R10/R10 with the old R10 asset => PASS", async () => { + const deployment = createReleaseFixture(["R10", "R11"]); + const result = await bootAgainstReplicaSequence( + [response("html", "R10"), response("config", "R10"), response("manifest", "R10")], + deployment, + ); + expect(result).toMatchObject({ state: "booted", applicationMounted: true }); + }); + + it("R10/R11/R10 => FAIL CLOSED", async () => { + const result = await bootAgainstReplicaSequence([ + response("html", "R10"), + response("config", "R11"), + response("manifest", "R10"), + ]); + expect(result).toMatchObject({ state: "release-mismatch", applicationMounted: false }); + }); + + it("R10/R10/R11 => FAIL CLOSED", async () => { + const result = await bootAgainstReplicaSequence([ + response("html", "R10"), + response("config", "R10"), + response("manifest", "R11"), + ]); + expect(result).toMatchObject({ state: "release-mismatch", applicationMounted: false }); + }); + + it("R10/R10/R10 with only the R11 asset path retained => FAIL", async () => { + const deployment = createReleaseFixture(["R10", "R11"]); + deployment.activate("R11"); + deployment.retireAssets("R10"); + const result = await bootAgainstReplicaSequence( + [response("html", "R10"), response("config", "R10"), response("manifest", "R10")], + deployment, + ); + expect(result).toMatchObject({ state: "asset-missing", applicationMounted: false }); + }); + + it("R11/R11/R11 with the R11 asset => PASS", async () => { + const deployment = createReleaseFixture(["R11"]); + const result = await bootAgainstReplicaSequence( + [response("html", "R11"), response("config", "R11"), response("manifest", "R11")], + deployment, + ); + expect(result).toMatchObject({ state: "booted", applicationMounted: true, release: "release-R11" }); + }); + + it("R10 client after R11 activation with the R10 hashed asset retained => PASS", async () => { + const deployment = createReleaseFixture(["R10", "R11"]); + deployment.activate("R11"); + // The browser still holds R10 HTML and a lagging replica still answers R10. + const result = await bootAgainstReplicaSequence( + [response("html", "R10"), response("config", "R10"), response("manifest", "R10")], + deployment, + ); + expect(result).toMatchObject({ state: "booted", applicationMounted: true, release: "release-R10" }); + }); + + it("no mismatch row can produce more than one automatic reload", async () => { + const mismatches = [ + [response("html", "R10"), response("config", "R11"), response("manifest", "R10")], + [response("html", "R10"), response("config", "R10"), response("manifest", "R11")], + [response("html", "R11"), response("config", "R10"), response("manifest", "R11")], + ] as const; + for (const sequence of mismatches) { + const session = await runBootSession( + () => sequence, + createReleaseMismatchRecovery(memoryStorage()), + ); + expect(session.reloads).toBeLessThanOrEqual(1); + expect(session.final.applicationMounted).toBe(false); + } + }); +}); diff --git a/tests/runtime-schema/http-schema.test.ts b/tests/runtime-schema/http-schema.test.ts index 60c68bc6..61a68ad2 100644 --- a/tests/runtime-schema/http-schema.test.ts +++ b/tests/runtime-schema/http-schema.test.ts @@ -62,6 +62,30 @@ describe("runtime schema codec contribution", () => { }); }); + it("bounds failure issues returned by an installed codec", () => { + const noisyCodec = { + schemaId: "Noisy", + parse: () => ({ + success: false as const, + issues: [ + { path: "p".repeat(121), code: "TOO_LONG_PATH" }, + { path: "field", code: "C".repeat(81) }, + ...Array.from({ length: 100 }, (_, index) => ({ + path: `field.${index}`, + code: "INVALID", + })), + ], + }), + }; + const registry = composeRuntimeSchemaCodecs([{ Noisy: noisyCodec }]); + const result = validateWithRuntimeSchemaRegistry("Noisy", {}, registry); + + expect(result.success).toBe(false); + if (result.success) throw new Error("expected validation failure"); + expect(result.issues).toHaveLength(50); + expect(result.issues[0]).toEqual({ path: "field.0", code: "INVALID" }); + }); + it("rejects duplicate codec contributions", () => { expect(() => composeRuntimeSchemaCodecs([{ Example: codec }, { Example: codec }]), diff --git a/tests/scale/benchmark.test.ts b/tests/scale/benchmark.test.ts new file mode 100644 index 00000000..cfc2dcf4 --- /dev/null +++ b/tests/scale/benchmark.test.ts @@ -0,0 +1,83 @@ +import { describe, expect, it } from "vitest"; + +import { benchmark } from "../../scripts/scale/benchmark.ts"; +import { + assertBenchmarkResult, + median, +} from "../../scripts/scale/benchmark-result.ts"; + +function fakeDurations(values: readonly number[]): () => number { + let index = 0; + return () => values[index++ % values.length] as number; +} + +describe("benchmark runner", () => { + it("records median rather than a single timing sample", async () => { + const result = await benchmark("compose", { + samples: 5, + run: fakeDurations([10, 11, 100, 12, 9]), + }); + + expect(result.medianMs).toBe(11); + expect(result.samples).toHaveLength(5); + }); + + it("runs warm-up iterations that are not sampled", async () => { + let calls = 0; + const result = await benchmark("warm", { + samples: 3, + warmup: 2, + run: () => { + calls += 1; + return calls; + }, + }); + expect(calls).toBe(5); + expect(result.samples).toEqual([3, 4, 5]); + }); + + it("produces the machine-readable result schema", async () => { + const result = await benchmark("registry-composition", { + samples: 3, + profile: "S2", + cardinality: 10_000, + measureHeap: true, + metadata: { implementation: "composeUniqueRecord" }, + run: () => { + Array.from({ length: 1_000 }, (_, i) => i); + }, + }); + expect(result).toMatchObject({ + name: "registry-composition", + profile: "S2", + cardinality: 10_000, + metadata: { implementation: "composeUniqueRecord" }, + }); + expect(result.medianMs).toBeGreaterThanOrEqual(0); + expect(typeof result.heapBytes).toBe("number"); + }); + + it("computes even-length medians and rejects inconsistent results", () => { + expect(median([4, 1, 3, 2])).toBe(2.5); + expect(() => + assertBenchmarkResult({ + name: "x", + profile: "S0", + cardinality: 1, + samples: [1, 2, 3], + medianMs: 3, + metadata: {}, + }), + ).toThrow(/median/); + expect(() => + assertBenchmarkResult({ + name: "x", + profile: "S9" as never, + cardinality: 1, + samples: [1], + medianMs: 1, + metadata: {}, + }), + ).toThrow(/profile/); + }); +}); diff --git a/tests/scale/browser-soak.contract.test.ts b/tests/scale/browser-soak.contract.test.ts new file mode 100644 index 00000000..c84bdef6 --- /dev/null +++ b/tests/scale/browser-soak.contract.test.ts @@ -0,0 +1,153 @@ +import { describe, expect, it } from "vitest"; + +import { + classifyCounterSeries, + classifyMemorySlope, + linearSlope, +} from "../../scripts/scale/memory-slope.ts"; +import { + evaluateSoak, + runBrowserSoak, + summarizeSoak, +} from "../../scripts/scale/browser-soak.ts"; + +describe("soak slope classifier", () => { + it("flags a persistent positive heap slope after warmup", () => { + expect( + classifyMemorySlope([ + { minute: 10, heapMb: 100 }, + { minute: 20, heapMb: 200 }, + { minute: 30, heapMb: 300 }, + ]), + ).toBe("unbounded-growth"); + }); + + it("treats warm-up growth followed by a plateau as stable", () => { + expect( + classifyMemorySlope( + [ + { minute: 0, heapMb: 20 }, + { minute: 5, heapMb: 80 }, + { minute: 10, heapMb: 100 }, + { minute: 20, heapMb: 101 }, + { minute: 30, heapMb: 99 }, + { minute: 40, heapMb: 100.5 }, + ], + { warmupMinutes: 10 }, + ), + ).toBe("stable"); + }); + + it("does not flag GC sawtooth noise around a flat baseline", () => { + const sawtooth = Array.from({ length: 40 }, (_, minute) => ({ + minute, + heapMb: 100 + (minute % 4) * 3, + })); + expect(classifyMemorySlope(sawtooth)).toBe("stable"); + }); + + it("needs enough post-warm-up evidence", () => { + expect(classifyMemorySlope([{ minute: 1, heapMb: 1 }, { minute: 2, heapMb: 2 }])).toBe( + "insufficient-data", + ); + }); + + it("classifies logical counters and computes a least-squares slope", () => { + expect(linearSlope([{ x: 0, y: 1 }, { x: 1, y: 3 }, { x: 2, y: 5 }])).toBeCloseTo(2); + expect(classifyCounterSeries([0, 0, 0, 0, 0])).toBe("stable"); + expect(classifyCounterSeries([1, 2, 3, 4, 5])).toBe("unbounded-growth"); + }); + + it("summarizes a browser series recorded as { elapsedMs, heapBytes, domNodes, activeTimers }", () => { + const mb = 1024 * 1024; + const flat = Array.from({ length: 12 }, (_, index) => ({ + elapsedMs: index * 10_000, + heapBytes: 40 * mb + (index % 2) * mb, + domNodes: 900, + listeners: 120, + activeTimers: 3, + })); + const leaking = flat.map((sample, index) => ({ + ...sample, + heapBytes: 40 * mb + index * 8 * mb, + })); + expect(summarizeSoak(flat, 20_000)).toBe("stable"); + expect(summarizeSoak(leaking, 20_000)).toBe("unbounded-growth"); + }); +}); + +describe("soak evaluation", () => { + const base = (index: number) => ({ + elapsedMs: index * 5_000, + cycles: index * 100, + heapBytes: 40 * 1024 * 1024, + domNodes: 900, + listeners: 120, + activeTimers: 2, + inFlightRequests: 0, + storageKeys: 1, + storageBytes: 100, + }); + const healthySamples = Array.from({ length: 12 }, (_, index) => base(index)); + const totals = { + cycles: 1_200, + navigationFailures: 0, + referenceVisits: 200, + settledReferenceVisits: 40, + finalInFlightRequests: 0, + apiRequests: 240, + telemetryPosts: 5, + telemetryEvents: 6, + telemetryPostTimes: [1_000, 20_000, 40_000, 70_000, 90_000], + }; + + it("passes a healthy long session", () => { + const { checks } = evaluateSoak(healthySamples, totals, 10_000); + expect(checks.filter((check) => !check.passed)).toEqual([]); + }); + + it("fails a vacuous soak that never exercised the backend or telemetry", () => { + const { checks } = evaluateSoak(healthySamples, { ...totals, apiRequests: 0, telemetryEvents: 0 }, 10_000); + expect(checks.find((check) => check.name === "backend failure exercised")?.passed).toBe(false); + }); + + it.each([ + ["timers", healthySamples.map((sample, index) => ({ ...sample, activeTimers: 2 + index * 3 }))], + ["listeners", healthySamples.map((sample, index) => ({ ...sample, listeners: 120 + index * 20 }))], + ["storage growth", healthySamples.map((sample, index) => ({ ...sample, storageKeys: 1 + index }))], + ] as const)("fails a %s leak", (name, samples) => { + const { checks } = evaluateSoak(samples, totals, 10_000); + expect(checks.find((check) => check.name === name)?.passed).toBe(false); + }); + + it("fails request amplification and a telemetry storm", () => { + const { checks } = evaluateSoak( + healthySamples, + { + ...totals, + apiRequests: 1_000, + telemetryPostTimes: Array.from({ length: 100 }, (_, index) => index * 100), + }, + 10_000, + ); + expect(checks.find((check) => check.name === "request amplification")?.passed).toBe(false); + expect(checks.find((check) => check.name === "telemetry rate")?.passed).toBe(false); + }); + + it("fails too short a soak and requests that never settle", () => { + const { checks } = evaluateSoak(healthySamples.slice(0, 3), { ...totals, cycles: 10, finalInFlightRequests: 2 }, 10_000); + expect(checks.find((check) => check.name === "cycles")?.passed).toBe(false); + expect(checks.find((check) => check.name === "in-flight settles")?.passed).toBe(false); + }); + + it("reports skipped (never passed) without a build", async () => { + const result = await runBrowserSoak({ + distRoot: "does-not-exist", + durationMs: 1, + intervalMs: 1, + warmupMs: 0, + routes: ["/"], + }); + expect(result.status).toBe("skipped"); + }); +}); diff --git a/tests/scale/composition-scale.test.ts b/tests/scale/composition-scale.test.ts new file mode 100644 index 00000000..4fb8192b --- /dev/null +++ b/tests/scale/composition-scale.test.ts @@ -0,0 +1,60 @@ +import { describe, expect, it } from "vitest"; + +import { composeUniqueRecord } from "../../src/platform/cardinality/compose-unique-record.ts"; +import { + COMPOSITION_WORKLOADS, + createUniqueRegistryParts, +} from "../../scripts/scale/composition-workloads.ts"; +import { runCompositionScale } from "../../scripts/scale/run-composition-scale.ts"; + +describe("registry/composition scale (S0-S2)", () => { + it.each([100, 1_000, 10_000])( + "composes %i unique entries without duplicates", + (count) => { + const parts = createUniqueRegistryParts(count); + const result = composeUniqueRecord(parts, () => "route"); + + expect(Object.keys(result)).toHaveLength(count); + }, + ); + + it("rejects a duplicate at the largest profile deterministically", () => { + const parts = [...createUniqueRegistryParts(10_000), { "route-42": -1 }]; + expect(() => composeUniqueRecord(parts, () => "route")).toThrow( + "Duplicate route key: route-42", + ); + }); + + it("runs every production workload at every profile", () => { + for (const workload of COMPOSITION_WORKLOADS) { + for (const n of [100, 1_000, 10_000]) { + expect(workload.prepare(n)()).toBeDefined(); + } + } + }); + + it( + "keeps the S0/S1/S2 composition series linear-or-better with machine-readable results", + async () => { + const measure = () => + runCompositionScale(["S0", "S1", "S2"], { + samples: 5, + warmup: 1, + // This suite runs beside other suites; see `statistic` in the runner. + statistic: "min", + }); + // Review focus: one noisy measurement must not fail a linear path. A + // real super-linear path fails every independent re-measurement. + let report = await measure(); + if (!report.passed) report = await measure(); + + expect(report.checks.filter((check) => !check.passed)).toEqual([]); + expect(report.results).toHaveLength(COMPOSITION_WORKLOADS.length * 3); + for (const result of report.results) { + expect(result.samples).toHaveLength(5); + expect(result.metadata["implementation"]).toBeTypeOf("string"); + } + }, + 60_000, + ); +}); diff --git a/tests/scale/filesystem-topology.ts b/tests/scale/filesystem-topology.ts new file mode 100644 index 00000000..0644ec67 --- /dev/null +++ b/tests/scale/filesystem-topology.ts @@ -0,0 +1,139 @@ +import { mkdir, readFile, writeFile } from "node:fs/promises"; +import path from "node:path"; + +/** + * Writes a real multi-app repository layout on disk, using the same ownership + * declarations the production generator reads: + * + * src/apps//app-module.ts + * src/contexts//context-module.ts + * src/features//{feature-module,context-routes}.ts + presentation/ + * + * App A is fixed. Every other logical feature belongs to other apps, so growing + * `globalFeatures` must leave App A's generated output and source graph alone. + */ +export const APP_A = Object.freeze({ id: "app-a", contexts: 2, featuresPerContext: 50 }); +const OTHER_CONTEXTS_PER_APP = 10; +const OTHER_FEATURES_PER_CONTEXT = 100; + +async function write(file: string, content: string): Promise { + await mkdir(path.dirname(file), { recursive: true }); + await writeFile(file, content); +} + +async function writeFeature(root: string, id: string, contextId: string): Promise { + const dir = path.join(root, "src/features", id); + await write( + path.join(dir, "feature-module.ts"), + `import { PAGE } from "./presentation/page.ts";\n` + + `export const FEATURE_MODULE_ID = "${id}";\nexport const FEATURE_CONTEXT_ID = "${contextId}";\n` + + `export const FEATURE_MODULE = Object.freeze({ id: FEATURE_MODULE_ID, page: PAGE });\n`, + ); + await write( + path.join(dir, "context-routes.ts"), + `import { PAGE } from "./presentation/page.ts";\nexport const FEATURE_CONTEXT_ROUTES = [{ id: "${id}", page: PAGE }];\n`, + ); + await write(path.join(dir, "presentation/page.ts"), `export const PAGE = "${id}-page";\n`); +} + +async function writeContext(root: string, id: string, appId: string, maxFeatures: number) { + await write( + path.join(root, "src/contexts", id, "context-module.ts"), + `export const CONTEXT_MODULE_ID = "${id}";\nexport const CONTEXT_APP_ID = "${appId}";\n` + + `export const CONTEXT_ROUTE_PATH = "${id}/*";\nexport const CONTEXT_MAX_FEATURES = ${maxFeatures};\n`, + ); +} + +async function writeApp(root: string, id: string, maxContexts: number) { + await write( + path.join(root, "src/apps", id, "app-module.ts"), + `export const APP_MODULE_ID = "${id}";\nexport const APP_MAX_CONTEXTS = ${maxContexts};\n`, + ); +} + +export async function writeFilesystemTopology( + root: string, + options: Readonly<{ globalFeatures: number }>, +): Promise> { + await writeApp(root, APP_A.id, 20); + let written = 0; + for (let context = 0; context < APP_A.contexts; context += 1) { + const contextId = `${APP_A.id}-ctx${context}`; + await writeContext(root, contextId, APP_A.id, 200); + for (let feature = 0; feature < APP_A.featuresPerContext; feature += 1) { + await writeFeature(root, `${contextId}-f${feature}`, contextId); + written += 1; + } + } + let apps = 1; + for (let appIndex = 0; written < options.globalFeatures; appIndex += 1) { + const appId = `other-${appIndex}`; + await writeApp(root, appId, 20); + apps += 1; + for (let context = 0; context < OTHER_CONTEXTS_PER_APP && written < options.globalFeatures; context += 1) { + const contextId = `${appId}-ctx${context}`; + await writeContext(root, contextId, appId, 200); + for (let feature = 0; feature < OTHER_FEATURES_PER_CONTEXT && written < options.globalFeatures; feature += 1) { + await writeFeature(root, `${contextId}-f${feature}`, contextId); + written += 1; + } + } + } + return { apps, features: written }; +} + +const IMPORT = /(?:import|export)\s[^"'`]*?from\s+["']([^"']+)["']|import\(\s*["']([^"']+)["']\s*\)/gu; + +/** + * Static source graph reachable from the generated indexes: every relative + * import (static and lazy) followed transitively on disk. This is the module + * set the app's bundler and type-checker are given from these entries. + */ +export async function reachableSourceGraph( + root: string, + entries: readonly string[], +): Promise { + const seen = new Set(); + const pending = entries.map((entry) => path.resolve(root, entry)); + while (pending.length > 0) { + const file = pending.pop() as string; + if (seen.has(file)) continue; + let source: string; + try { + source = await readFile(file, "utf8"); + } catch { + continue; // outside this synthetic repository (e.g. platform modules) + } + seen.add(file); + for (const match of source.matchAll(IMPORT)) { + const specifier = match[1] ?? match[2]; + if (specifier?.startsWith(".")) pending.push(path.resolve(path.dirname(file), specifier)); + } + } + return [...seen].map((file) => path.relative(root, file)).sort(); +} + +/** + * Writes the given apps of a synthetic topology as real declarations, so the + * filesystem source and the synthetic declaration source can be compared. + */ +export async function writeSyntheticApps( + root: string, + apps: readonly Readonly<{ + id: string; + maxContexts: number; + contexts: readonly Readonly<{ id: string; routePath: string; maxFeatures: number; featureIds: readonly string[] }>[]; + }>[], +): Promise { + for (const app of apps) { + await writeApp(root, app.id, app.maxContexts); + for (const context of app.contexts) { + await write( + path.join(root, "src/contexts", context.id, "context-module.ts"), + `export const CONTEXT_MODULE_ID = "${context.id}";\nexport const CONTEXT_APP_ID = "${app.id}";\n` + + `export const CONTEXT_ROUTE_PATH = "${context.routePath}";\nexport const CONTEXT_MAX_FEATURES = ${context.maxFeatures};\n`, + ); + for (const featureId of context.featureIds) await writeFeature(root, featureId, context.id); + } + } +} diff --git a/tests/scale/fixtures/typescript/extended-diagnostics.txt b/tests/scale/fixtures/typescript/extended-diagnostics.txt new file mode 100644 index 00000000..62bea2aa --- /dev/null +++ b/tests/scale/fixtures/typescript/extended-diagnostics.txt @@ -0,0 +1,14 @@ +Files: 821 +Lines: 361168 +Identifiers: 428183 +Symbols: 779934 +Types: 277593 +Instantiations: 698528 +Memory used: 511482K +Memory allocs: 2977087 +Config time: 0.002s +Parse time: 0.145s +Bind time: 0.031s +Check time: 0.883s +Emit time: 0.000s +Total time: 1.064s diff --git a/tests/scale/global-local-independence.test.ts b/tests/scale/global-local-independence.test.ts new file mode 100644 index 00000000..0daca96c --- /dev/null +++ b/tests/scale/global-local-independence.test.ts @@ -0,0 +1,172 @@ +import { spawnSync } from "node:child_process"; +import { createHash } from "node:crypto"; +import { mkdtemp, readFile, rm } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; + +import { afterAll, describe, expect, it } from "vitest"; + +import { + generateAppIndexes, + selectAppIndexes, +} from "../../scripts/generate-product-feature-index.ts"; +import { + APP_A, + reachableSourceGraph, + writeFilesystemTopology, + writeSyntheticApps, +} from "./filesystem-topology.ts"; +import { APP_CONTEXT_BUDGET, CONTEXT_FEATURE_BUDGET, SCALE_PROFILES } from "./scale-profile.ts"; +import { + createSyntheticTopology, + declarationSource, + selectAppInputs, +} from "./synthetic-topology.ts"; + +/** + * Spec ยง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 + * app/context/feature ownership declarations. + * - S3/S4: the same production selection (`selectAppIndexes`) over a + * declaration source that models 100k/1M logical features without writing + * them; an equivalence test pins that source to the filesystem one. + */ +const GENERATOR = path.resolve("scripts/generate-product-feature-index.ts"); +const OUTPUTS = [ + "src/.generated/product-feature-index.ts", + "src/.generated/product-context-index.ts", + "src/.generated/product-app.ts", +] as const; +const roots: string[] = []; + +afterAll(async () => { + await Promise.all(roots.map((root) => rm(root, { recursive: true, force: true }))); +}); + +async function productionBuildInputs(globalFeatures: number) { + const root = await mkdtemp(path.join(tmpdir(), `topology-${globalFeatures}-`)); + roots.push(root); + const written = await writeFilesystemTopology(root, { globalFeatures }); + const run = spawnSync(process.execPath, [GENERATOR, `--root=${root}`, `--app=${APP_A.id}`], { + encoding: "utf8", + }); + if (run.status !== 0) throw new Error(`generator failed: ${run.stderr}`); + const generated = await Promise.all( + OUTPUTS.map((file) => readFile(path.join(root, file), "utf8")), + ); + const graph = await reachableSourceGraph(root, OUTPUTS); + return { written, generated, graph }; +} + +describe("global-to-local independence on the production generator path", () => { + it( + "keeps App A's generated indexes and reachable source graph identical from S0 to S2 on disk", + async () => { + const s0 = await productionBuildInputs(SCALE_PROFILES.S0); + const s1 = await productionBuildInputs(SCALE_PROFILES.S1); + const s2 = await productionBuildInputs(SCALE_PROFILES.S2); + + expect(s2.written.features).toBe(SCALE_PROFILES.S2); + expect(s2.written.apps).toBeGreaterThan(s0.written.apps); + expect(s1.generated).toEqual(s0.generated); + expect(s2.generated).toEqual(s0.generated); + expect(s2.graph).toEqual(s0.graph); + const hash = (texts: readonly string[]) => + texts.map((text) => createHash("sha256").update(text).digest("hex")); + expect(hash(s2.generated)).toEqual(hash(s0.generated)); + + const localFeatures = APP_A.contexts * APP_A.featuresPerContext; + // Generated indexes + (feature-module, context-routes, page) per local feature. + expect(s2.graph).toHaveLength(OUTPUTS.length + localFeatures * 3); + expect(s2.graph.some((file) => file.includes("other-"))).toBe(false); + expect(s2.generated[1]?.match(/defineBoundedContextModule\(\{/gu)).toHaveLength(APP_A.contexts); + }, + 120_000, + ); + + it("selects another app from the same repository without App A's features", async () => { + const root = await mkdtemp(path.join(tmpdir(), "topology-select-")); + roots.push(root); + await writeFilesystemTopology(root, { globalFeatures: 1_100 }); + const other = await generateAppIndexes(root, "other-0"); + expect(other.app.id).toBe("other-0"); + expect(other.entries.every((entry) => entry.contextId.startsWith("other-0-"))).toBe(true); + await expect(generateAppIndexes(root, undefined)).rejects.toThrow(/Select a deployable app/); + await expect(generateAppIndexes(root, "missing")).rejects.toThrow(/Unknown deployable app/); + }); + + it("produces the same output from the filesystem source and the S3/S4 declaration source", async () => { + const topology = createSyntheticTopology({ globalFeatures: SCALE_PROFILES.S0 * 3 }); + const root = await mkdtemp(path.join(tmpdir(), "topology-equivalence-")); + roots.push(root); + await writeSyntheticApps( + root, + ["app-0", "app-1", "app-2"].map((id) => ({ + id, + maxContexts: APP_CONTEXT_BUDGET, + contexts: topology.app(id).contexts.map((context) => ({ + ...context, + maxFeatures: CONTEXT_FEATURE_BUDGET, + })), + })), + ); + const fromDisk = await generateAppIndexes(root, "app-0"); + const fromModel = selectAppIndexes(declarationSource(topology), "app-0"); + expect(fromModel.featureIndex).toBe(fromDisk.featureIndex); + expect(fromModel.contextIndex).toBe(fromDisk.contextIndex); + expect(fromModel.appIndex).toBe(fromDisk.appIndex); + }); + + it("keeps one unchanged app's production indexes identical from S0 to S4", () => { + const s0 = selectAppInputs(createSyntheticTopology({ globalFeatures: SCALE_PROFILES.S0 }), "app-0"); + for (const globalFeatures of Object.values(SCALE_PROFILES)) { + const current = selectAppInputs(createSyntheticTopology({ globalFeatures }), "app-0"); + expect(current.contextIds).toEqual(s0.contextIds); + expect(current.featureIds).toEqual(s0.featureIds); + expect(current.routeRootIds).toEqual(s0.routeRootIds); + expect(current.generatedFeatureIndex).toBe(s0.generatedFeatureIndex); + expect(current.generatedContextIndex).toBe(s0.generatedContextIndex); + expect(current.generatedAppIndex).toBe(s0.generatedAppIndex); + expect(current.generatedHashes).toEqual(s0.generatedHashes); + expect(current.compileInputPaths).toEqual(s0.compileInputPaths); + } + // The compile input is App A's own modules only: one feature module and + // one lazy route module per local feature, plus the context descriptor. + const featureOwned = s0.compileInputPaths.filter((file) => /^src\/features\/[^/]+\//u.test(file)); + expect(featureOwned).toHaveLength(s0.featureIds.length * 2); + expect(featureOwned.every((file) => file.startsWith("src/features/app0-"))).toBe(true); + }); + + it("reads only the selected app's declarations, even at 1,000,000 logical features", () => { + const inputs = selectAppInputs( + createSyntheticTopology({ globalFeatures: SCALE_PROFILES.S4 }), + "app-0", + ); + expect(inputs.reads.apps).toBe(1); + expect(inputs.reads.contexts).toBe(inputs.contextIds.length); + expect(inputs.reads.features).toBe(inputs.featureIds.length); + expect(inputs.featureIds.length).toBeLessThan(SCALE_PROFILES.S0 + 1); + }); + + it("boots only direct context roots, never the global feature table", () => { + const inputs = selectAppInputs( + createSyntheticTopology({ globalFeatures: SCALE_PROFILES.S4 }), + "app-0", + ); + expect(inputs.routeRootIds.length).toBe(inputs.contextIds.length); + expect(inputs.routeRootIds.length).toBeLessThanOrEqual(inputs.contextBudget); + // Feature executables sit behind the lazy context loader, not in boot imports. + expect(inputs.generatedContextIndex).toContain("async loadRoutes()"); + expect(inputs.generatedContextIndex).toMatch(/import\("\.\.\/features\//u); + }); + + it("keeps an app deep in the S4 topology within the same local shape", () => { + const topology = createSyntheticTopology({ globalFeatures: SCALE_PROFILES.S4 }); + const first = selectAppInputs(topology, "app-0"); + const last = selectAppInputs(topology, `app-${topology.appCount - 1}`); + expect(last.featureIds.length).toBe(first.featureIds.length); + expect(last.contextIds.length).toBe(first.contextIds.length); + }); +}); diff --git a/tests/scale/growth-regression.test.ts b/tests/scale/growth-regression.test.ts new file mode 100644 index 00000000..2e718ce7 --- /dev/null +++ b/tests/scale/growth-regression.test.ts @@ -0,0 +1,91 @@ +import { describe, expect, it } from "vitest"; + +import { + assertLinearOrBetter, + GrowthRegressionError, + growthExponents, +} from "../../src/platform/cardinality/growth-regression.ts"; + +describe("assertLinearOrBetter", () => { + it("accepts roughly linear growth", () => { + expect(() => + assertLinearOrBetter([ + { n: 100, cost: 1 }, + { n: 1_000, cost: 10 }, + { n: 10_000, cost: 100 }, + ]), + ).not.toThrow(); + }); + + it("rejects quadratic-shaped growth", () => { + expect(() => + assertLinearOrBetter([ + { n: 100, cost: 1 }, + { n: 1_000, cost: 100 }, + { n: 10_000, cost: 10_000 }, + ]), + ).toThrow(/growth/i); + }); + + it("rejects a quadratic implementation even while absolute times are tiny", () => { + expect(() => + assertLinearOrBetter([ + { n: 100, cost: 0.0001 }, + { n: 1_000, cost: 0.01 }, + ]), + ).toThrow(GrowthRegressionError); + }); + + it("accepts sub-linear and n log n growth", () => { + expect(() => + assertLinearOrBetter([ + { n: 100, cost: 100 * Math.log(100) }, + { n: 1_000, cost: 1_000 * Math.log(1_000) }, + { n: 10_000, cost: 10_000 * Math.log(10_000) }, + ]), + ).not.toThrow(); + expect(() => + assertLinearOrBetter([ + { n: 100, cost: 5 }, + { n: 10_000, cost: 5 }, + ]), + ).not.toThrow(); + }); + + it("does not fail a linear series because of noise below the floor", () => { + expect(() => + assertLinearOrBetter( + [ + { n: 100, cost: 0.001 }, + { n: 1_000, cost: 0.2 }, + { n: 10_000, cost: 2 }, + ], + { noiseFloor: 0.2 }, + ), + ).not.toThrow(); + }); + + it("rejects malformed series", () => { + expect(() => assertLinearOrBetter([{ n: 1, cost: 1 }])).toThrow(TypeError); + expect(() => + assertLinearOrBetter([ + { n: 1, cost: 1 }, + { n: 1, cost: 2 }, + ]), + ).toThrow(TypeError); + expect(() => + assertLinearOrBetter([ + { n: 0, cost: 1 }, + { n: 10, cost: 2 }, + ]), + ).toThrow(TypeError); + }); + + it("reports per-segment exponents", () => { + const [exponent] = growthExponents([ + { n: 10, cost: 1 }, + { n: 100, cost: 100 }, + ]); + expect(exponent).toBeCloseTo(2); + }); +}); diff --git a/tests/scale/scale-artifact.ts b/tests/scale/scale-artifact.ts new file mode 100644 index 00000000..fb67c534 --- /dev/null +++ b/tests/scale/scale-artifact.ts @@ -0,0 +1,20 @@ +import { mkdir, writeFile } from "node:fs/promises"; +import path from "node:path"; + +/** + * Scenario suites record their measured counters as machine-readable JSON when + * a scale profile run asks for them (`SCALE_ARTIFACT_DIR`, set by + * scripts/scale/run-scale-profile.ts). Plain test runs write nothing. + */ +export async function recordScaleMetrics( + name: string, + metrics: Readonly>, +): Promise { + const directory = process.env["SCALE_ARTIFACT_DIR"]; + if (!directory) return; + await mkdir(directory, { recursive: true }); + await writeFile( + path.join(directory, `${name}.json`), + `${JSON.stringify({ schemaVersion: 1, name, recordedAt: new Date().toISOString(), metrics }, null, 2)}\n`, + ); +} diff --git a/tests/scale/scale-baseline.test.ts b/tests/scale/scale-baseline.test.ts new file mode 100644 index 00000000..ad506d35 --- /dev/null +++ b/tests/scale/scale-baseline.test.ts @@ -0,0 +1,173 @@ +import { readFile } from "node:fs/promises"; +import path from "node:path"; + +import { describe, expect, it } from "vitest"; + +import { + approveBaseline, + compareToBaseline, + metricsDigest, + type ScaleBaseline, + type ScaleEnvironment, + type ScaleMetrics, +} from "../../scripts/scale/scale-baseline.ts"; +import { COMPOSITION_WORKLOADS } from "../../scripts/scale/composition-workloads.ts"; +import { BASELINE_PATH, LOCAL_TSC_SIZES } from "../../scripts/scale/check-scale-baseline.ts"; + +const ENVIRONMENT: ScaleEnvironment = { + nodeMajor: 24, + platform: "linux", + arch: "x64", + cpuModel: "Test CPU", + cpuCount: 8, + typescript: "7.0.2", +}; + +const METRICS: ScaleMetrics = { + timing: [ + { workload: "registry-composition", profile: "S1", cardinality: 1_000, medianMs: 0.5, minMs: 0.4 }, + { workload: "registry-composition", profile: "S2", cardinality: 10_000, medianMs: 5, minMs: 4 }, + ], + compiler: [{ fixture: "app", files: 800, types: 270_000, symbols: 770_000, instantiations: 690_000 }], +}; + +function baseline(metrics: ScaleMetrics = METRICS, environment = ENVIRONMENT): ScaleBaseline { + return approveBaseline(environment, metrics, { + owner: "frontend-platform", + reason: "test", + approvedAt: "2026-09-23T00:00:00.000Z", + }); +} + +function withTiming(minMs: number): ScaleMetrics { + return { + ...METRICS, + timing: METRICS.timing.map((entry) => + entry.profile === "S2" ? { ...entry, minMs, medianMs: minMs } : entry, + ), + }; +} + +function withTypes(types: number): ScaleMetrics { + return { ...METRICS, compiler: [{ ...METRICS.compiler[0]!, types }] }; +} + +describe("relative regression gate against the stored baseline", () => { + it("passes an unchanged run on all three axes", () => { + const result = compareToBaseline(baseline(), ENVIRONMENT, METRICS); + expect(result.status).toBe("passed"); + expect(result.passed).toBe(true); + expect(result.absolute.passed).toBe(true); + expect(result.growth.passed).toBe(true); + expect(result.compiler.length).toBe(4); + expect(result.timing.length).toBe(2); + }); + + it("fails a compiler-cost regression above 10% even when the growth shape is fine", () => { + expect(compareToBaseline(baseline(), ENVIRONMENT, withTypes(290_000)).passed).toBe(true); + const regressed = compareToBaseline(baseline(), ENVIRONMENT, withTypes(300_000)); + expect(regressed.passed).toBe(false); + expect(regressed.failures.join("\n")).toMatch(/tsc:app:types 300000 exceeds 297000/); + }); + + it("fails a timing regression beyond 2.5x on a compatible machine", () => { + expect(compareToBaseline(baseline(), ENVIRONMENT, withTiming(9.9)).passed).toBe(true); + const regressed = compareToBaseline(baseline(), ENVIRONMENT, withTiming(12)); + expect(regressed.passed).toBe(false); + expect(regressed.failures.join("\n")).toMatch(/time:registry-composition\/S2/); + }); + + it("never fails timing differences inside the absolute noise floor", () => { + const tiny: ScaleMetrics = { + ...METRICS, + timing: [{ workload: "w", profile: "S0", cardinality: 100, medianMs: 0.02, minMs: 0.02 }], + }; + const noisy: ScaleMetrics = { ...tiny, timing: [{ ...tiny.timing[0]!, minMs: 0.9 }] }; + expect(compareToBaseline(baseline(tiny), ENVIRONMENT, noisy).passed).toBe(true); + }); + + it("reports timings from a different machine as incomplete, never as passed, but still gates compiler counts", () => { + const otherMachine = { ...ENVIRONMENT, cpuModel: "Other CPU" }; + const slow = compareToBaseline(baseline(), otherMachine, withTiming(12)); + expect(slow.status).toBe("incomplete"); + expect(slow.passed).toBe(false); + expect(slow.compatibility.timing.ok).toBe(false); + expect(slow.timing).toEqual([]); + + const heavier = compareToBaseline(baseline(), otherMachine, withTypes(400_000)); + expect(heavier.status).toBe("failed"); + }); + + it("enforces machine-agnostic absolute ceilings on every run", () => { + const tooSlow = compareToBaseline(baseline(), { ...ENVIRONMENT, cpuModel: "Other CPU" }, withTiming(151)); + expect(tooSlow.status).toBe("failed"); + expect(tooSlow.failures.join("\n")).toMatch(/ceiling:time:registry-composition\/S2 151 exceeds 150/); + const tooHeavy = compareToBaseline(baseline(), ENVIRONMENT, withTypes(600_001)); + expect(tooHeavy.absolute.passed).toBe(false); + }); + + it("fails a super-linear growth shape even when relative and absolute limits hold", () => { + const quadratic: ScaleMetrics = { + ...METRICS, + timing: [ + { workload: "registry-composition", profile: "S1", cardinality: 1_000, medianMs: 0.6, minMs: 0.6 }, + { workload: "registry-composition", profile: "S2", cardinality: 10_000, medianMs: 60, minMs: 60 }, + ], + }; + const result = compareToBaseline(baseline(quadratic), ENVIRONMENT, quadratic); + expect(result.growth.passed).toBe(false); + expect(result.status).toBe("failed"); + expect(result.failures.join("\n")).toMatch(/growth:time:registry-composition/); + }); + + it("requires re-approval when the compiler changes", () => { + const result = compareToBaseline(baseline(), { ...ENVIRONMENT, typescript: "7.1.0" }, METRICS); + expect(result.passed).toBe(false); + expect(result.compatibility.compiler.ok).toBe(false); + expect(result.failures.join("\n")).toMatch(/re-approve with update:scale-baseline/); + }); + + it("rejects a hand-edited baseline whose metrics no longer match the approved digest", () => { + const tampered: ScaleBaseline = { + ...baseline(), + metrics: withTypes(900_000), + }; + const result = compareToBaseline(tampered, ENVIRONMENT, METRICS); + expect(result.passed).toBe(false); + expect(result.compatibility.structural.reasons.join("\n")).toMatch(/digest/); + }); + + it("rejects a run measuring something the baseline does not cover", () => { + const extra: ScaleMetrics = { + ...METRICS, + compiler: [...METRICS.compiler, { fixture: "local-9999", files: 1, types: 1, symbols: 1, instantiations: 1 }], + }; + const result = compareToBaseline(baseline(), ENVIRONMENT, extra); + expect(result.passed).toBe(false); + expect(result.failures.join("\n")).toMatch(/no baseline for compiler fixture local-9999/); + }); +}); + +describe("stored benchmark baseline", () => { + it("is approved, digest-consistent and covers every measured workload and fixture", async () => { + const stored = JSON.parse( + await readFile(path.resolve(BASELINE_PATH), "utf8"), + ) as ScaleBaseline; + + expect(stored.schemaVersion).toBe(1); + expect(stored.approval.owner).toBeTruthy(); + expect(stored.approval.reason).toBeTruthy(); + expect(metricsDigest(stored.metrics)).toBe(stored.approval.metricsDigest); + + const timing = new Set(stored.metrics.timing.map((entry) => `${entry.workload}/${entry.profile}`)); + for (const workload of COMPOSITION_WORKLOADS) { + for (const profile of ["S0", "S1", "S2"]) { + expect(timing.has(`${workload.name}/${profile}`), `${workload.name}/${profile}`).toBe(true); + } + } + const fixtures = new Set(stored.metrics.compiler.map((entry) => entry.fixture)); + expect(fixtures).toEqual( + new Set(["app", ...LOCAL_TSC_SIZES.map((size) => `local-${size}`)]), + ); + }); +}); diff --git a/tests/scale/scale-profile.ts b/tests/scale/scale-profile.ts new file mode 100644 index 00000000..4b2e7bae --- /dev/null +++ b/tests/scale/scale-profile.ts @@ -0,0 +1,27 @@ +/** + * Spec ยง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({ + S0: 100, + S1: 1_000, + S2: 10_000, + S3: 100_000, + S4: 1_000_000, +}); + +export type ScaleProfileId = keyof typeof SCALE_PROFILES; + +/** Direct-child ceilings, matching the deployable app/context descriptors. */ +export const APP_CONTEXT_BUDGET = 20; +export const CONTEXT_FEATURE_BUDGET = 200; +export const APP_LOCAL_FEATURE_BUDGET = APP_CONTEXT_BUDGET * CONTEXT_FEATURE_BUDGET; + +/** + * The fixed shape one synthetic app is given. Global growth adds apps; it + * never widens an existing app. + */ +export const SYNTHETIC_APP_SHAPE = Object.freeze({ + contextsPerApp: 10, + featuresPerContext: 10, +}); diff --git a/tests/scale/session/long-session.test.ts b/tests/scale/session/long-session.test.ts new file mode 100644 index 00000000..516c88cf --- /dev/null +++ b/tests/scale/session/long-session.test.ts @@ -0,0 +1,154 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; + +import { createQueryClient } from "../../../src/adapters/query-cache/tanstack-query-cache.ts"; +import { createTelemetryPipeline } from "../../../src/platform/telemetry/telemetry-pipeline.ts"; +import type { InstalledHttpContract } from "../../../src/contracts/external-contract-runtime.ts"; +import { TEST_CREATE_HTTP_CONTRACT } from "../../helpers/external-contract-fixture.ts"; +import { + jsonRows, + networkFailure, + testExecutionContext, + testExecutor, + type Transport, +} from "../../helpers/traffic-test-kit.ts"; +import { classifyCounterSeries } from "../../../scripts/scale/memory-slope.ts"; +import { TEST_QUERY } from "../traffic/synthetic-traffic.ts"; +import { recordScaleMetrics } from "../scale-artifact.ts"; + +const TEST_COMMAND = TEST_CREATE_HTTP_CONTRACT as InstalledHttpContract< + unknown, + unknown, + unknown +>; + +afterEach(() => { + vi.useRealTimers(); +}); + +/** + * A long-lived scope signal that counts its listeners, standing in for the + * session-wide server-state scope every execution subscribes to. + */ +function countingScope() { + const controller = new AbortController(); + let listeners = 0; + const signal = controller.signal; + const add = signal.addEventListener.bind(signal); + const remove = signal.removeEventListener.bind(signal); + Object.defineProperty(signal, "addEventListener", { + value: (...args: Parameters) => { + listeners += 1; + add(...args); + }, + }); + Object.defineProperty(signal, "removeEventListener", { + value: (...args: Parameters) => { + listeners -= 1; + remove(...args); + }, + }); + let generation = 1; + return { + scope: () => + Object.freeze({ + generation, + fingerprint: `scope-${generation}`, + identities: Object.freeze({}) as never, + signal, + isCurrent: () => true, + }), + listeners: () => listeners, + nextGeneration() { + generation += 1; + }, + generation: () => generation, + }; +} + +/** + * Spec ยง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. + */ +describe("long-session logical leak checks", () => { + it("returns timers, listeners, leases, buffers and cache entries to a stable bound", async () => { + vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] }); + const session = countingScope(); + let cycle = 0; + const transport: Transport = () => (cycle % 7 === 0 ? networkFailure() : Promise.resolve(jsonRows(2))); + const executor = testExecutor(transport, { maxRetryAttempts: 1 }); + const telemetry = createTelemetryPipeline({ + transport: { send: () => {} }, + schedule: () => {}, + setTimer: () => 0, + clearTimer: () => {}, + }); + const queryClient = createQueryClient(); + + const series = { timers: [] as number[], listeners: [] as number[], buffered: [] as number[], cache: [] as number[] }; + const CYCLES = 3_000; + for (cycle = 0; cycle < CYCLES; cycle += 1) { + // login: a new session scope generation every 250 cycles + if (cycle % 250 === 0) session.nextGeneration(); + const execution = testExecutionContext({ + maxPhysicalRequests: 3, + maxRetries: 1, + maxConcurrentRequests: 2, + }); + const context = { routeId: "TEST_ROUTE", scope: session.scope(), execution }; + // navigation + query through the query cache (bounded key cardinality) + const queryKey = ["session", session.generation(), cycle % 25]; + const query = queryClient.fetchQuery({ + queryKey, + queryFn: () => executor.execute(TEST_QUERY, { limit: 1 }, context), + }); + // mutation + const mutation = executor.execute(TEST_COMMAND, { name: `c${cycle}` }, { + ...context, + intent: Object.freeze({ + intentId: `intent-${cycle}`, + operationId: "TEST_CREATE_ENTITY", + canonicalInputIdentity: `input-${cycle}`, + idempotencyKey: `key-${cycle.toString().padStart(6, "0")}`, + createdAtMonotonicMs: cycle, + }), + }); + const [queryOutcome, mutationOutcome] = await Promise.all([query, mutation]); + if (queryOutcome.kind !== "SUCCESS" || mutationOutcome.kind !== "SUCCESS") { + await telemetry.emit({ + kind: "session.operation.failed", + severity: "warning", + interactionId: execution.interaction.id, + payload: { query: queryOutcome.kind, mutation: mutationOutcome.kind }, + }); + } + // logout: the interaction ends + execution.cancellation.cancel(); + expect(execution.traffic.concurrency.active).toBe(0); + + if (cycle % 100 === 99) { + await telemetry.flush(); + series.timers.push(vi.getTimerCount()); + series.listeners.push(session.listeners()); + series.buffered.push(telemetry.stats().buffered); + series.cache.push(queryClient.getQueryCache().getAll().length); + } + if (cycle % 250 === 249) { + // Scope generation changed: the previous generation's entries are garbage. + queryClient.removeQueries({ queryKey: ["session", session.generation()] }); + } + } + + await recordScaleMetrics("long-session", { cycles: CYCLES, ...series }); + + expect(vi.getTimerCount()).toBe(0); + expect(session.listeners()).toBe(0); + expect(classifyCounterSeries(series.timers, { warmupSamples: 3 })).toBe("stable"); + expect(classifyCounterSeries(series.listeners, { warmupSamples: 3 })).toBe("stable"); + expect(classifyCounterSeries(series.buffered, { warmupSamples: 3 })).toBe("stable"); + expect(Math.max(...series.cache)).toBeLessThanOrEqual(25); + expect(Math.max(...series.buffered)).toBeLessThanOrEqual(200); + queryClient.clear(); + telemetry.dispose(); + }, 120_000); +}); diff --git a/tests/scale/session/network-flap.test.ts b/tests/scale/session/network-flap.test.ts new file mode 100644 index 00000000..ff0710e9 --- /dev/null +++ b/tests/scale/session/network-flap.test.ts @@ -0,0 +1,128 @@ +import { describe, expect, it, vi } from "vitest"; + +import type { InstalledHttpContract } from "../../../src/contracts/external-contract-runtime.ts"; +import { TEST_CREATE_HTTP_CONTRACT } from "../../helpers/external-contract-fixture.ts"; +import { + jsonRows, + scopeSnapshot, + testExecutionContext, + testExecutor, + type Transport, +} from "../../helpers/traffic-test-kit.ts"; +import { TEST_QUERY } from "../traffic/synthetic-traffic.ts"; + +const TEST_COMMAND = TEST_CREATE_HTTP_CONTRACT as InstalledHttpContract< + unknown, + unknown, + unknown +>; + +/** + * Spec ยง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. + */ +function flappingNetwork() { + let online = true; + const commandDispatches = new Map(); + const inFlight = new Set(); + const transport: Transport = (_input, init) => { + const key = new Headers(init?.headers).get("idempotency-key"); + if (key) commandDispatches.set(key, (commandDispatches.get(key) ?? 0) + 1); + if (!online) return Promise.reject(new TypeError("offline")); + if (key) { + return Promise.resolve( + Response.json({ id: key, name: "created" }, { status: 201 }), + ); + } + return Promise.resolve(jsonRows(1)); + }; + return { + transport, + commandDispatches, + inFlight, + setOnline(value: boolean) { + online = value; + }, + }; +} + +function intent(index: number) { + return Object.freeze({ + intentId: `intent-${index}`, + operationId: "TEST_CREATE_ENTITY", + canonicalInputIdentity: `input-${index}`, + idempotencyKey: `key-${index.toString().padStart(6, "0")}`, + createdAtMonotonicMs: index, + }); +} + +describe("network flap", () => { + it("never replays an unsafe mutation and keeps queues bounded across flaps", async () => { + const network = flappingNetwork(); + const executor = testExecutor(network.transport, { maxRetryAttempts: 2 }); + let peakQueued = 0; + + for (let cycle = 0; cycle < 400; cycle += 1) { + network.setOnline(cycle % 2 === 0); + const execution = testExecutionContext({ + maxPhysicalRequests: 4, + maxRetries: 2, + maxConcurrentRequests: 1, + maxQueuedRequests: 2, + }); + const context = { routeId: "TEST_ROUTE", scope: scopeSnapshot(), execution }; + const work = Promise.all([ + executor.execute(TEST_COMMAND, { name: `n${cycle}` }, { ...context, intent: intent(cycle) }), + executor.execute(TEST_QUERY, { limit: 1 }, context), + executor.execute(TEST_QUERY, { limit: 1 }, context), + ]); + peakQueued = Math.max(peakQueued, execution.traffic.concurrency.queued); + await work; + expect(execution.traffic.concurrency.active).toBe(0); + expect(execution.traffic.concurrency.queued).toBe(0); + } + + expect(Math.max(...network.commandDispatches.values())).toBe(1); + expect(network.commandDispatches.size).toBe(400); + expect(peakQueued).toBeLessThanOrEqual(2); + }); + + it("completes cancellation of stale interactions when the network drops", async () => { + const pendingSignals: AbortSignal[] = []; + const transport: Transport = (_input, init) => + new Promise((_resolve, reject) => { + if (init?.signal) pendingSignals.push(init.signal); + init?.signal?.addEventListener( + "abort", + () => reject(new DOMException("aborted", "AbortError")), + { once: true }, + ); + }); + const executor = testExecutor(transport); + const interactions = Array.from({ length: 50 }, () => + testExecutionContext({ maxConcurrentRequests: 1, maxQueuedRequests: 2 }), + ); + const running = interactions.flatMap((execution) => + [0, 1, 2].map(() => + executor.execute(TEST_QUERY, { limit: 1 }, { + routeId: "TEST_ROUTE", + scope: scopeSnapshot(), + execution, + }), + ), + ); + await vi.waitFor(() => expect(pendingSignals).toHaveLength(50)); + + // "offline" event: the session cancels every interaction started online. + for (const execution of interactions) execution.cancellation.cancel(); + const outcomes = await Promise.all(running); + + expect(outcomes.every((outcome) => outcome.kind === "CANCELLED")).toBe(true); + expect(pendingSignals.every((signal) => signal.aborted)).toBe(true); + for (const execution of interactions) { + expect(execution.traffic.concurrency.active).toBe(0); + expect(execution.traffic.concurrency.queued).toBe(0); + } + }); +}); diff --git a/tests/scale/synthetic-topology.test.ts b/tests/scale/synthetic-topology.test.ts new file mode 100644 index 00000000..b7932bd6 --- /dev/null +++ b/tests/scale/synthetic-topology.test.ts @@ -0,0 +1,58 @@ +import { describe, expect, it } from "vitest"; + +import { + APP_CONTEXT_BUDGET, + APP_LOCAL_FEATURE_BUDGET, + CONTEXT_FEATURE_BUDGET, + SCALE_PROFILES, +} from "./scale-profile.ts"; +import { createSyntheticTopology } from "./synthetic-topology.ts"; + +describe("scale profiles and synthetic topology", () => { + it("defines the exact S0-S4 profiles", () => { + expect(SCALE_PROFILES).toEqual({ + S0: 100, + S1: 1_000, + S2: 10_000, + S3: 100_000, + S4: 1_000_000, + }); + }); + + it("grows global topology without growing a selected local app beyond its budgets", () => { + const small = createSyntheticTopology({ globalFeatures: 100 }); + const huge = createSyntheticTopology({ globalFeatures: 1_000_000 }); + + expect(huge.apps[0]?.contexts.length).toBeLessThanOrEqual(APP_CONTEXT_BUDGET); + expect(huge.apps[0]?.localFeatureCount).toBeLessThanOrEqual(APP_LOCAL_FEATURE_BUDGET); + expect(huge.apps[0]?.localFeatureCount).toBe(small.apps[0]?.localFeatureCount); + }); + + it.each(Object.entries(SCALE_PROFILES))( + "%s partitions %i features into budget-respecting apps and contexts", + (_profile, globalFeatures) => { + const topology = createSyntheticTopology({ globalFeatures }); + expect(topology.appCount * APP_CONTEXT_BUDGET * CONTEXT_FEATURE_BUDGET).toBeGreaterThanOrEqual( + globalFeatures, + ); + for (const index of [0, topology.appCount - 1]) { + const app = topology.apps[index]; + expect(app?.contexts.length).toBeLessThanOrEqual(APP_CONTEXT_BUDGET); + for (const context of app?.contexts ?? []) { + expect(context.featureIds.length).toBeLessThanOrEqual(CONTEXT_FEATURE_BUDGET); + } + } + }, + ); + + it("models S4 compactly instead of materializing a million features", () => { + const before = process.memoryUsage().heapUsed; + const topology = createSyntheticTopology({ globalFeatures: 1_000_000 }); + const after = process.memoryUsage().heapUsed; + + expect(topology.appCount).toBe(10_000); + expect(after - before).toBeLessThan(16 * 1024 * 1024); + expect(topology.apps[10_000]).toBeUndefined(); + expect(() => topology.app("app-10000")).toThrow(RangeError); + }); +}); diff --git a/tests/scale/synthetic-topology.ts b/tests/scale/synthetic-topology.ts new file mode 100644 index 00000000..e0174043 --- /dev/null +++ b/tests/scale/synthetic-topology.ts @@ -0,0 +1,207 @@ +import { createHash } from "node:crypto"; + +import { planTopologyCapacity } from "../../src/platform/cardinality/topology-capacity.ts"; +import { + selectAppIndexes, + type ContextDeclaration, + type FeatureDeclaration, + type TopologyDeclarationSource, +} from "../../scripts/generate-product-feature-index.ts"; +import { + APP_CONTEXT_BUDGET, + CONTEXT_FEATURE_BUDGET, + SYNTHETIC_APP_SHAPE, +} from "./scale-profile.ts"; + +/** + * Spec ยง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 + * numbers plus whatever single app a test actually inspects. + */ +export type SyntheticContext = Readonly<{ + id: string; + routePath: string; + featureIds: readonly string[]; +}>; + +export type SyntheticApp = Readonly<{ + id: string; + localFeatureCount: number; + contexts: readonly SyntheticContext[]; +}>; + +export type SyntheticTopology = Readonly<{ + globalFeatures: number; + appCount: number; + contextCount: number; + apps: Readonly<{ length: number; [index: number]: SyntheticApp }>; + app(id: string): SyntheticApp; +}>; + +function contextFor(appIndex: number, contextIndex: number, features: number): SyntheticContext { + const id = `app${appIndex}-ctx${contextIndex}`; + return Object.freeze({ + id, + routePath: `ctx${contextIndex}/*`, + featureIds: Object.freeze( + Array.from({ length: features }, (_, featureIndex) => `${id}-f${featureIndex}`), + ), + }); +} + +export function createSyntheticTopology( + options: Readonly<{ globalFeatures: number }>, +): SyntheticTopology { + const { contextsPerApp, featuresPerContext } = SYNTHETIC_APP_SHAPE; + const plan = planTopologyCapacity({ + featureCount: options.globalFeatures, + maxFeaturesPerContext: featuresPerContext, + maxContextsPerApp: contextsPerApp, + }); + const featuresPerApp = contextsPerApp * featuresPerContext; + const cache = new Map(); + + function build(appIndex: number): SyntheticApp { + const cached = cache.get(appIndex); + if (cached) return cached; + const firstFeature = appIndex * featuresPerApp; + const localFeatureCount = Math.max( + 0, + Math.min(featuresPerApp, options.globalFeatures - firstFeature), + ); + const contextCount = Math.ceil(localFeatureCount / featuresPerContext); + const app = Object.freeze({ + id: `app-${appIndex}`, + localFeatureCount, + contexts: Object.freeze( + Array.from({ length: contextCount }, (_, contextIndex) => + contextFor( + appIndex, + contextIndex, + Math.min(featuresPerContext, localFeatureCount - contextIndex * featuresPerContext), + ), + ), + ), + }); + // Inspecting an app is local work; the cache never exceeds what the test + // itself asked for. + cache.set(appIndex, app); + return app; + } + + const apps = new Proxy(Object.freeze({ length: plan.appCount }), { + get(target, property) { + if (typeof property === "string" && /^\d+$/u.test(property)) { + const index = Number(property); + return index < plan.appCount ? build(index) : undefined; + } + return Reflect.get(target, property); + }, + }) as SyntheticTopology["apps"]; + + return Object.freeze({ + globalFeatures: options.globalFeatures, + appCount: plan.appCount, + contextCount: plan.contextCount, + apps, + app(id: string) { + const match = /^app-(\d+)$/u.exec(id); + const index = match ? Number(match[1]) : Number.NaN; + if (!Number.isSafeInteger(index) || index >= plan.appCount) { + throw new RangeError(`unknown synthetic app ${id}`); + } + return build(index); + }, + }); +} + +export type DeclarationReads = { apps: number; contexts: number; features: number }; + +/** + * The synthetic topology as a production `TopologyDeclarationSource`: the same + * ownership-indexed interface the filesystem source implements. It counts how + * many declarations the production selection actually reads, which is the + * locality evidence at 1,000,000 logical features. + */ +export function declarationSource( + topology: SyntheticTopology, +): TopologyDeclarationSource & Readonly<{ reads: DeclarationReads }> { + const reads: DeclarationReads = { apps: 0, contexts: 0, features: 0 }; + const appIndex = (appId: string) => { + const match = /^app-(\d+)$/u.exec(appId); + const index = match ? Number(match[1]) : Number.NaN; + return Number.isSafeInteger(index) && index < topology.appCount ? index : -1; + }; + const contextOwner = (contextId: string) => { + const match = /^app(\d+)-ctx(\d+)$/u.exec(contextId); + return match ? { app: `app-${match[1]}`, context: Number(match[2]) } : null; + }; + return Object.freeze({ + reads, + appIds() { + // Listing app ids is O(apps), never O(features); the generator only + // needs it when no app is selected explicitly. + return Array.from({ length: topology.appCount }, (_, index) => `app-${index}`); + }, + app(appId: string) { + if (appIndex(appId) < 0) return undefined; + reads.apps += 1; + return { id: appId, maxContexts: APP_CONTEXT_BUDGET }; + }, + contextsOf(appId: string): readonly ContextDeclaration[] { + if (appIndex(appId) < 0) return []; + const contexts = topology.app(appId).contexts; + reads.contexts += contexts.length; + return contexts.map((context) => ({ + id: context.id, + appId, + routePath: context.routePath, + maxFeatures: CONTEXT_FEATURE_BUDGET, + })); + }, + featuresOf(contextId: string): readonly FeatureDeclaration[] { + const owner = contextOwner(contextId); + if (!owner || appIndex(owner.app) < 0) return []; + const context = topology.app(owner.app).contexts[owner.context]; + if (!context) return []; + reads.features += context.featureIds.length; + return context.featureIds.map((id) => ({ id, contextId, directory: id })); + }, + }); +} + +/** + * Everything one deployable app compiles and boots with, produced by the + * production generator's own app selection (`selectAppIndexes`). + */ +export function selectAppInputs(topology: SyntheticTopology, appId: string) { + const source = declarationSource(topology); + const selected = selectAppIndexes(source, appId); + const contextIds = [...new Set(selected.entries.map((entry) => entry.contextId))]; + const generated = [selected.featureIndex, selected.contextIndex, selected.appIndex]; + // Every module the generated entries hand to the compiler/bundler (static + // and lazy imports), resolved from `src/.generated/`. + const compileInputPaths = [ + ...new Set( + generated.flatMap((text) => + [...text.matchAll(/(?:from\s+|import\()\s*"(\.\.\/[^"]+)"/gu)].map((match) => + `src/${(match[1] as string).slice("../".length)}`, + ), + ), + ), + ].sort(); + return Object.freeze({ + contextIds, + featureIds: selected.entries.map((entry) => entry.id), + routeRootIds: [...new Set(selected.entries.map((entry) => entry.contextRoutePath))], + generatedFeatureIndex: selected.featureIndex, + generatedContextIndex: selected.contextIndex, + generatedAppIndex: selected.appIndex, + generatedHashes: generated.map((text) => createHash("sha256").update(text).digest("hex")), + compileInputPaths, + contextBudget: APP_CONTEXT_BUDGET, + reads: { ...source.reads }, + }); +} diff --git a/tests/scale/telemetry/telemetry-storm.test.ts b/tests/scale/telemetry/telemetry-storm.test.ts new file mode 100644 index 00000000..7d4b9bf3 --- /dev/null +++ b/tests/scale/telemetry/telemetry-storm.test.ts @@ -0,0 +1,165 @@ +import { describe, expect, it, vi } from "vitest"; + +import { + createTelemetryPipeline, + DEFAULT_TELEMETRY_PIPELINE_BUDGET, +} from "../../../src/platform/telemetry/telemetry-pipeline.ts"; +import type { TelemetryEvent } from "../../../src/platform/telemetry/telemetry-event.ts"; +import { telemetryAmplification } from "../traffic/amplification-metrics.ts"; +import { recordScaleMetrics } from "../scale-artifact.ts"; + +const IDENTICAL: TelemetryEvent = { + kind: "catalog.load.failed", + severity: "error", + featureId: "catalog", + payload: { operation: "list", reason: "NETWORK_UNREACHABLE" }, +}; + +/** + * Spec ยง43. Many logical failures -> fingerprint/dedup/sample -> a bounded + * number of buffered and sent telemetry events. + */ +async function runTelemetryStorm( + options: Readonly<{ + identicalEvents: number; + distinctKinds?: number; + maxSendsPerMinute: number; + maxBufferedEvents: number; + collector?: "up" | "down"; + }>, +) { + let networkSends = 0; + let now = 0; + const pipeline = createTelemetryPipeline({ + transport: { + async send() { + networkSends += 1; + if (options.collector === "down") throw new Error("collector unavailable"); + }, + }, + budget: { + ...DEFAULT_TELEMETRY_PIPELINE_BUDGET, + maxSendsPerMinute: options.maxSendsPerMinute, + maxBufferedEvents: options.maxBufferedEvents, + }, + now: () => now, + setTimer: () => 0, + clearTimer: () => {}, + }); + let peakBufferedEvents = 0; + const distinct = options.distinctKinds ?? 1; + // The whole storm lands inside one rate/dedup window (0.5ms apart). + for (let i = 0; i < options.identicalEvents; i += 1) { + now += 0.5; + await pipeline.emit({ + ...IDENTICAL, + payload: { operation: "list", reason: `R${i % distinct}` }, + interactionId: `interaction-${i}`, + }); + if (i % 1_000 === 0) { + await pipeline.flush(); + peakBufferedEvents = Math.max(peakBufferedEvents, pipeline.stats().buffered); + } + } + await pipeline.flush(); + const stats = pipeline.stats(); + peakBufferedEvents = Math.max(peakBufferedEvents, stats.peakBuffered); + pipeline.dispose(); + return { networkSends, peakBufferedEvents, stats }; +} + +describe("telemetry storm", () => { + it("does not turn 100000 identical failures into 100000 sends", async () => { + const result = await runTelemetryStorm({ + identicalEvents: 100_000, + maxSendsPerMinute: 20, + maxBufferedEvents: 200, + }); + + expect(result.networkSends).toBeLessThanOrEqual(20); + expect(result.peakBufferedEvents).toBeLessThanOrEqual(200); + expect(result.stats.deduplicated).toBe(99_999); + expect( + telemetryAmplification({ logicalEvents: 100_000, telemetrySends: result.networkSends }), + ).toBeLessThanOrEqual(0.0002); + await recordScaleMetrics("telemetry-storm-identical", { + emitted: 100_000, + deduplicated: result.stats.deduplicated, + sampledOut: result.stats.sampledOut, + dropped: result.stats.dropped, + transmitted: result.networkSends, + peakBuffered: result.peakBufferedEvents, + }); + }); + + it("bounds sends and buffer when a storm has many distinct fingerprints", async () => { + const result = await runTelemetryStorm({ + identicalEvents: 100_000, + distinctKinds: 5_000, + maxSendsPerMinute: 20, + maxBufferedEvents: 200, + }); + expect(result.networkSends).toBeLessThanOrEqual(20); + expect(result.peakBufferedEvents).toBeLessThanOrEqual(200); + expect(result.stats.fingerprints).toBeLessThanOrEqual( + DEFAULT_TELEMETRY_PIPELINE_BUDGET.maxFingerprints, + ); + await recordScaleMetrics("telemetry-storm-distinct", { + emitted: 100_000, + deduplicated: result.stats.deduplicated, + dropped: result.stats.dropped, + transmitted: result.networkSends, + peakBuffered: result.peakBufferedEvents, + }); + }); +}); + +/** + * A feature-shaped business operation: it reports its failure through the + * telemetry port fire-and-forget and returns its own result regardless. + */ +function createCatalogLoader( + telemetry: Readonly<{ emit(event: TelemetryEvent): unknown }>, + upstream: () => Promise, +) { + return async (): Promise> => { + const ok = await upstream(); + if (!ok) { + try { + void Promise.resolve( + telemetry.emit({ ...IDENTICAL, severity: "warning" }), + ).catch(() => undefined); + } catch { + // Contained at the call site. + } + } + return { ok }; + }; +} + +describe("collector outage", () => { + it("keeps business promises fulfilled and buffers bounded while every send fails", async () => { + const pipeline = createTelemetryPipeline({ + transport: { send: () => Promise.reject(new Error("collector unavailable")) }, + budget: { ...DEFAULT_TELEMETRY_PIPELINE_BUDGET, maxBufferedEvents: 50 }, + }); + let call = 0; + const load = createCatalogLoader(pipeline, async () => call++ % 2 === 1); + + const results = await Promise.all(Array.from({ length: 5_000 }, () => load())); + await pipeline.flush(); + + expect(results).toHaveLength(5_000); + expect(results.filter((result) => result.ok)).toHaveLength(2_500); + expect(pipeline.stats().buffered).toBeLessThanOrEqual(50); + expect(pipeline.stats().peakBuffered).toBeLessThanOrEqual(50); + pipeline.dispose(); + }); + + it("keeps the business result when the port itself throws", async () => { + const throwing = { emit: vi.fn(() => { throw new Error("port broken"); }) }; + const load = createCatalogLoader(throwing, async () => false); + await expect(load()).resolves.toEqual({ ok: false }); + expect(throwing.emit).toHaveBeenCalledOnce(); + }); +}); diff --git a/tests/scale/traffic/amplification-metrics.test.ts b/tests/scale/traffic/amplification-metrics.test.ts new file mode 100644 index 00000000..eb8f75b1 --- /dev/null +++ b/tests/scale/traffic/amplification-metrics.test.ts @@ -0,0 +1,46 @@ +import { describe, expect, it } from "vitest"; + +import { + requestAmplification, + retryAmplification, + telemetryAmplification, +} from "./amplification-metrics.ts"; + +describe("amplification metrics", () => { + it("computes exact request and retry amplification", () => { + expect(requestAmplification({ + interactions: 1_000, + physicalRequests: 1_150, + })).toBe(1.15); + + expect(retryAmplification({ + initialRequests: 1_000, + totalRequests: 1_200, + })).toBe(1.2); + + expect(telemetryAmplification({ logicalEvents: 100_000, telemetrySends: 20 })).toBe( + 0.0002, + ); + }); + + it.each([0, -1, Number.NaN, Number.POSITIVE_INFINITY])( + "rejects an invalid denominator %s", + (denominator) => { + expect(() => + requestAmplification({ interactions: denominator, physicalRequests: 1 }), + ).toThrow(RangeError); + expect(() => + retryAmplification({ initialRequests: denominator, totalRequests: 1 }), + ).toThrow(RangeError); + expect(() => + telemetryAmplification({ logicalEvents: denominator, telemetrySends: 1 }), + ).toThrow(RangeError); + }, + ); + + it("rejects a negative numerator", () => { + expect(() => + requestAmplification({ interactions: 1, physicalRequests: -1 }), + ).toThrow(RangeError); + }); +}); diff --git a/tests/scale/traffic/amplification-metrics.ts b/tests/scale/traffic/amplification-metrics.ts new file mode 100644 index 00000000..c3ca76ab --- /dev/null +++ b/tests/scale/traffic/amplification-metrics.ts @@ -0,0 +1,34 @@ +/** + * Spec ยง34. Operational amplification metrics. + * + * - request amplification = physical requests / logical interactions + * - retry amplification = total physical attempts / initial requests + * - telemetry amplification = telemetry sends / logical failures or events + */ +function ratio(numerator: number, denominator: number, name: string): number { + if (!Number.isFinite(denominator) || denominator <= 0) { + throw new RangeError(`${name} denominator must be positive: ${denominator}`); + } + if (!Number.isFinite(numerator) || numerator < 0) { + throw new RangeError(`${name} numerator must be non-negative: ${numerator}`); + } + return Math.round((numerator / denominator) * 1e9) / 1e9; +} + +export function requestAmplification( + input: Readonly<{ interactions: number; physicalRequests: number }>, +): number { + return ratio(input.physicalRequests, input.interactions, "request amplification"); +} + +export function retryAmplification( + input: Readonly<{ initialRequests: number; totalRequests: number }>, +): number { + return ratio(input.totalRequests, input.initialRequests, "retry amplification"); +} + +export function telemetryAmplification( + input: Readonly<{ logicalEvents: number; telemetrySends: number }>, +): number { + return ratio(input.telemetrySends, input.logicalEvents, "telemetry amplification"); +} diff --git a/tests/scale/traffic/failure-scenarios.test.ts b/tests/scale/traffic/failure-scenarios.test.ts new file mode 100644 index 00000000..c7a2a7c0 --- /dev/null +++ b/tests/scale/traffic/failure-scenarios.test.ts @@ -0,0 +1,165 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; + +import { + manualClock, + scopeSnapshot, + testExecutionContext, + testExecutor, + type Transport, +} from "../../helpers/traffic-test-kit.ts"; +import { + requestAmplification, + retryAmplification, +} from "./amplification-metrics.ts"; +import { runSyntheticTraffic, TEST_QUERY, upstream } from "./synthetic-traffic.ts"; + +afterEach(() => { + vi.useRealTimers(); +}); + +describe("total outage", () => { + it("bounds physical requests when all upstream calls fail", async () => { + const result = await runSyntheticTraffic({ + interactions: 10_000, + upstream: "always-fail", + maxPhysicalRequestsPerInteraction: 2, + maxRetriesPerInteraction: 1, + }); + + expect(result.physicalRequests).toBeLessThanOrEqual(20_000); + expect(result.succeeded).toBe(0); + expect(requestAmplification(result)).toBeLessThanOrEqual(2); + expect( + retryAmplification({ + initialRequests: result.initialRequests, + totalRequests: result.physicalRequests, + }), + ).toBeLessThanOrEqual(2); + }, 60_000); + + it("keeps amplification bounded when one interaction fans out into many operations", async () => { + const result = await runSyntheticTraffic({ + interactions: 1_000, + upstream: "always-fail", + maxPhysicalRequestsPerInteraction: 3, + maxRetriesPerInteraction: 1, + operationsPerInteraction: 6, + }); + // Unbudgeted: 6 operations x 3 attempts = 18 per interaction. + expect(requestAmplification(result)).toBeLessThanOrEqual(3); + }, 60_000); + + it("stays at 1x amplification when upstream is healthy", async () => { + const result = await runSyntheticTraffic({ + interactions: 2_000, + upstream: "healthy", + maxPhysicalRequestsPerInteraction: 2, + maxRetriesPerInteraction: 1, + }); + expect(result.succeeded).toBe(2_000); + expect(requestAmplification(result)).toBe(1); + }, 60_000); +}); + +describe("partial outage", () => { + it("lets healthy contexts complete while one context fails completely", async () => { + const transports = { + payment: upstream("always-fail"), + order: upstream("healthy"), + catalog: upstream("healthy"), + }; + const executors = Object.fromEntries( + Object.entries(transports).map(([contextId, transport]) => [ + contextId, + testExecutor(transport, { maxRetryAttempts: 2 }), + ]), + ) as Record>; + + const successes: Record = { payment: 0, order: 0, catalog: 0 }; + await Promise.all( + Array.from({ length: 300 }, async (_, index) => { + const contextId = (["payment", "order", "catalog"] as const)[index % 3] as + | "payment" + | "order" + | "catalog"; + const execution = testExecutionContext({ maxPhysicalRequests: 2, maxRetries: 1 }); + const outcome = await executors[contextId].execute(TEST_QUERY, { limit: 1 }, { + routeId: "TEST_ROUTE", + scope: scopeSnapshot(), + execution, + }); + if (outcome.kind === "SUCCESS") successes[contextId] = (successes[contextId] ?? 0) + 1; + }), + ); + + expect(successes).toEqual({ payment: 0, order: 100, catalog: 100 }); + expect(transports.payment.calls).toBeLessThanOrEqual(200); + expect(transports.order.calls).toBe(100); + expect(transports.catalog.calls).toBe(100); + }); +}); + +describe("slow upstream", () => { + it("bounds active and queued work, drains waiters at the deadline, and never retries after it", async () => { + vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] }); + const clock = manualClock(0); + let active = 0; + let peakActive = 0; + let calls = 0; + const transport: Transport = (_input, init) => { + calls += 1; + active += 1; + peakActive = Math.max(peakActive, active); + return new Promise((_resolve, reject) => { + init?.signal?.addEventListener( + "abort", + () => { + active -= 1; + reject(new DOMException("aborted", "AbortError")); + }, + { once: true }, + ); + }); + }; + const execution = testExecutionContext({ + deadlineMs: 1_000, + maxPhysicalRequests: 20, + maxRetries: 5, + maxConcurrentRequests: 2, + maxQueuedRequests: 3, + clock: clock.now, + }); + const executor = testExecutor(transport, { monotonicNow: clock.now }); + const context = { routeId: "TEST_ROUTE", scope: scopeSnapshot(), execution }; + + const pending = Array.from({ length: 10 }, () => + executor.execute(TEST_QUERY, { limit: 1 }, context), + ); + await vi.advanceTimersByTimeAsync(0); + expect(execution.traffic.concurrency.active).toBe(2); + expect(execution.traffic.concurrency.queued).toBe(3); + + clock.advance(1_000); + await vi.advanceTimersByTimeAsync(1_000); + const outcomes = await Promise.all(pending); + + expect(peakActive).toBeLessThanOrEqual(2); + expect(execution.traffic.concurrency.active).toBe(0); + expect(execution.traffic.concurrency.queued).toBe(0); + expect(calls).toBe(2); + expect(execution.traffic.retries.consumed).toBe(0); + expect( + outcomes.filter( + (outcome) => + outcome.kind === "TRANSPORT_FAILURE" && + outcome.failure.kind === "OVERLOADED_BEFORE_SEND", + ), + ).toHaveLength(5); + expect( + outcomes.filter( + (outcome) => + outcome.kind === "TRANSPORT_FAILURE" && outcome.failure.kind === "TIMEOUT", + ), + ).toHaveLength(5); + }); +}); diff --git a/tests/scale/traffic/retry-after-jitter.test.ts b/tests/scale/traffic/retry-after-jitter.test.ts new file mode 100644 index 00000000..62177cf7 --- /dev/null +++ b/tests/scale/traffic/retry-after-jitter.test.ts @@ -0,0 +1,73 @@ +import { describe, expect, it } from "vitest"; + +import { retryDelayFor } from "../../../src/adapters/http/http-retry-lifecycle.ts"; + +/** Deterministic per-client PRNG (mulberry32), seeded by client index. */ +function seededRandom(seed: number): () => number { + let state = seed >>> 0; + return () => { + state = (state + 0x6d2b79f5) >>> 0; + let value = state; + value = Math.imul(value ^ (value >>> 15), value | 1); + value ^= value + Math.imul(value ^ (value >>> 7), value | 61); + return ((value ^ (value >>> 14)) >>> 0) / 4_294_967_296; + }; +} + +function calculateRetryDelay( + options: Readonly<{ retryAfterMs: number; jitterSeed: number; attempt: number }>, +): number { + const delay = retryDelayFor( + options.retryAfterMs, + options.attempt - 1, + seededRandom(options.jitterSeed), + ); + if (delay === null) throw new Error("Retry-After above the ceiling is not retried"); + return delay; +} + +describe("Retry-After jitter distribution", () => { + it("spreads retries around Retry-After instead of synchronizing all clients", () => { + const delays = Array.from({ length: 10_000 }, (_, seed) => + calculateRetryDelay({ + retryAfterMs: 3_000, + jitterSeed: seed, + attempt: 1, + }), + ); + + expect(new Set(delays).size).toBeGreaterThan(100); + expect(Math.max(...delays) - Math.min(...delays)).toBeGreaterThan(500); + }); + + it("never retries earlier than the server asked", () => { + for (let seed = 0; seed < 1_000; seed += 1) { + expect( + calculateRetryDelay({ retryAfterMs: 1_000, jitterSeed: seed, attempt: 1 }), + ).toBeGreaterThanOrEqual(1_000); + } + }); + + it("keeps the jitter window bounded", () => { + const delays = Array.from({ length: 5_000 }, (_, seed) => + calculateRetryDelay({ retryAfterMs: 5_000, jitterSeed: seed, attempt: 3 }), + ); + expect(Math.max(...delays)).toBeLessThan(5_000 + 2_000); + }); + + it("spreads a cohort into many small buckets rather than one spike", () => { + const perBucket = new Map(); + for (let seed = 0; seed < 10_000; seed += 1) { + const bucket = Math.floor( + calculateRetryDelay({ retryAfterMs: 3_000, jitterSeed: seed, attempt: 1 }) / 50, + ); + perBucket.set(bucket, (perBucket.get(bucket) ?? 0) + 1); + } + // No 50ms slice receives more than ~10% of the cohort. + expect(Math.max(...perBucket.values())).toBeLessThan(1_000); + }); + + it("does not retry when Retry-After exceeds the ceiling", () => { + expect(retryDelayFor(10_000, 0, () => 0.5)).toBeNull(); + }); +}); diff --git a/tests/scale/traffic/synthetic-traffic.ts b/tests/scale/traffic/synthetic-traffic.ts new file mode 100644 index 00000000..588e1893 --- /dev/null +++ b/tests/scale/traffic/synthetic-traffic.ts @@ -0,0 +1,92 @@ +import type { InstalledHttpContract } from "../../../src/contracts/external-contract-runtime.ts"; +import { TEST_LIST_HTTP_CONTRACT } from "../../helpers/external-contract-fixture.ts"; +import { + jsonRows, + networkFailure, + scopeSnapshot, + testExecutionContext, + testExecutor, + type Transport, +} from "../../helpers/traffic-test-kit.ts"; + +export const TEST_QUERY = TEST_LIST_HTTP_CONTRACT as InstalledHttpContract< + unknown, + unknown, + unknown +>; + +export type UpstreamMode = "always-fail" | "healthy" | "fail-first"; + +export function upstream(mode: UpstreamMode): Transport & { calls: number } { + let seen = 0; + const transport = (async () => { + transport.calls += 1; + seen += 1; + if (mode === "always-fail") return networkFailure(); + if (mode === "fail-first" && seen % 2 === 1) return networkFailure(); + return jsonRows(1); + }) as unknown as Transport & { calls: number }; + transport.calls = 0; + return transport; +} + +export type SyntheticTrafficResult = Readonly<{ + interactions: number; + physicalRequests: number; + initialRequests: number; + succeeded: number; + failed: number; +}>; + +/** + * Spec ยง32 / ยง42. Drives many independent interactions through the real V3 + * executor, each with its own interaction budget, and counts physical + * dispatches at the transport. + */ +export async function runSyntheticTraffic( + options: Readonly<{ + interactions: number; + upstream: UpstreamMode; + maxPhysicalRequestsPerInteraction: number; + maxRetriesPerInteraction: number; + operationsPerInteraction?: number; + batchSize?: number; + }>, +): Promise { + const transport = upstream(options.upstream); + const executor = testExecutor(transport, { maxRetryAttempts: 2 }); + const operations = options.operationsPerInteraction ?? 1; + const batchSize = options.batchSize ?? 500; + let succeeded = 0; + let failed = 0; + for (let start = 0; start < options.interactions; start += batchSize) { + const size = Math.min(batchSize, options.interactions - start); + const outcomes = await Promise.all( + Array.from({ length: size }, async () => { + const execution = testExecutionContext({ + maxPhysicalRequests: options.maxPhysicalRequestsPerInteraction, + maxRetries: options.maxRetriesPerInteraction, + maxConcurrentRequests: 2, + maxQueuedRequests: 8, + }); + const context = { routeId: "TEST_ROUTE", scope: scopeSnapshot(), execution }; + return Promise.all( + Array.from({ length: operations }, () => + executor.execute(TEST_QUERY, { limit: 1 }, context), + ), + ); + }), + ); + for (const outcome of outcomes.flat()) { + if (outcome.kind === "SUCCESS") succeeded += 1; + else failed += 1; + } + } + return Object.freeze({ + interactions: options.interactions, + physicalRequests: transport.calls, + initialRequests: options.interactions * operations, + succeeded, + failed, + }); +} diff --git a/tests/scale/tsc-diagnostics-parser.test.ts b/tests/scale/tsc-diagnostics-parser.test.ts new file mode 100644 index 00000000..83e0d1ba --- /dev/null +++ b/tests/scale/tsc-diagnostics-parser.test.ts @@ -0,0 +1,45 @@ +import { readFile } from "node:fs/promises"; +import path from "node:path"; + +import { describe, expect, it } from "vitest"; + +import { parseTscExtendedDiagnostics } from "../../scripts/scale/collect-tsc-diagnostics.ts"; + +describe("parseTscExtendedDiagnostics", () => { + it("parses the documented diagnostic fields", () => { + const text = ` +Files: 321 +Types: 12000 +Symbols: 18000 +Instantiations: 5000 +Memory used: 128000K +Total time: 4.20s +`; + + expect(parseTscExtendedDiagnostics(text)).toMatchObject({ + files: 321, + types: 12_000, + symbols: 18_000, + instantiations: 5_000, + memoryKb: 128_000, + totalTimeSeconds: 4.2, + }); + }); + + it("parses real TypeScript 7 output captured from this repository", async () => { + const text = await readFile( + path.resolve("tests/scale/fixtures/typescript/extended-diagnostics.txt"), + "utf8", + ); + const parsed = parseTscExtendedDiagnostics(text); + expect(parsed.files).toBeGreaterThan(0); + expect(parsed.types).toBeGreaterThan(0); + expect(parsed.instantiations).toBeGreaterThan(0); + }); + + it("fails loudly when a required metric is missing", () => { + expect(() => parseTscExtendedDiagnostics("Files: 1\nTypes: 2\n")).toThrow( + /symbols/, + ); + }); +}); diff --git a/tests/scripts/generate-product-feature-index.test.ts b/tests/scripts/generate-product-feature-index.test.ts new file mode 100644 index 00000000..60164d9b --- /dev/null +++ b/tests/scripts/generate-product-feature-index.test.ts @@ -0,0 +1,151 @@ +import { describe, expect, it } from "vitest"; + +import { + generateAppIndexes, + renderContextIndex, + renderFeatureIndex, +} from "../../scripts/generate-product-feature-index.ts"; + +describe("feature index generator", () => { + it("is deterministic by normalized id", () => { + const first = renderFeatureIndex([ + { id: "zeta", importPath: "../features/zeta/feature-module.ts" }, + { id: "alpha", importPath: "../features/alpha/feature-module.ts" }, + ]); + const second = renderFeatureIndex([ + { id: "alpha", importPath: "../features/alpha/feature-module.ts" }, + { id: "zeta", importPath: "../features/zeta/feature-module.ts" }, + ]); + + expect(first).toBe(second); + expect(first.indexOf("alpha")).toBeLessThan(first.indexOf("zeta")); + }); + + it("emits a base feature module fallback for an empty product", () => { + const rendered = renderFeatureIndex([]); + + expect(rendered).toContain( + 'import type { FeatureModule } from "../features/feature-module.ts";', + ); + expect(rendered).toContain("type GeneratedProductFeatureModule ="); + expect(rendered).toContain( + "[GeneratedProductFeatureModule] extends [never]", + ); + expect(rendered).toContain("? FeatureModule"); + }); + + it("groups feature route executables behind one lazy context loader", () => { + const rendered = renderContextIndex([ + { + id: "catalog-search", + importPath: "../features/catalog-search/feature-module.ts", + directory: "catalog-search", + contextId: "catalog", + contextRoutePath: "catalog/*", + contextMaxFeatures: 200, + }, + { + id: "catalog-detail", + importPath: "../features/catalog-detail/feature-module.ts", + directory: "catalog-detail", + contextId: "catalog", + contextRoutePath: "catalog/*", + contextMaxFeatures: 200, + }, + ]); + + expect(rendered.match(/defineBoundedContextModule\(\{/gu)).toHaveLength(1); + expect(rendered).toContain( + 'import("../features/catalog-search/context-routes.ts")', + ); + expect(rendered).toContain( + 'import("../features/catalog-detail/context-routes.ts")', + ); + expect(rendered).not.toContain( + 'from "../features/catalog-search/context-routes.ts"', + ); + expect(rendered).not.toContain( + 'from "../features/catalog-detail/context-routes.ts"', + ); + }); + + it("emits no context loader for an empty product", () => { + expect(renderContextIndex([])).toBe( + "// Generated by scripts/generate-product-feature-index.ts. Do not edit by hand.\n" + + "export const PRODUCT_CONTEXT_MODULES = Object.freeze([] as const);\n", + ); + }); +}); + +describe("app-scoped selection from ownership declarations", () => { + async function repo(files: Record) { + const { mkdtemp, mkdir, writeFile } = await import("node:fs/promises"); + const { tmpdir } = await import("node:os"); + const path = await import("node:path"); + const root = await mkdtemp(path.join(tmpdir(), "generator-")); + for (const [file, content] of Object.entries(files)) { + await mkdir(path.dirname(path.join(root, file)), { recursive: true }); + await writeFile(path.join(root, file), content); + } + return root; + } + const app = (id: string, max = 20) => + `export const APP_MODULE_ID = "${id}";\nexport const APP_MAX_CONTEXTS = ${max};\n`; + const context = (id: string, appId: string, max = 200) => + `export const CONTEXT_MODULE_ID = "${id}";\nexport const CONTEXT_APP_ID = "${appId}";\n` + + `export const CONTEXT_ROUTE_PATH = "${id}/*";\nexport const CONTEXT_MAX_FEATURES = ${max};\n`; + const feature = (id: string, contextId: string) => + `export const FEATURE_MODULE_ID = "${id}";\nexport const FEATURE_CONTEXT_ID = "${contextId}";\n`; + + it("rejects a feature owned by an undeclared context", async () => { + const root = await repo({ + "src/apps/a/app-module.ts": app("a"), + "src/features/f/feature-module.ts": feature("f", "missing"), + }); + await expect(generateAppIndexes(root, "a")).rejects.toThrow(/undeclared context missing/); + }); + + it("rejects a context owned by an undeclared app", async () => { + const root = await repo({ + "src/apps/a/app-module.ts": app("a"), + "src/contexts/c/context-module.ts": context("c", "ghost"), + }); + await expect(generateAppIndexes(root, "a")).rejects.toThrow(/undeclared app ghost/); + }); + + it("enforces the context feature budget and the app context budget", async () => { + const overFeatures = await repo({ + "src/apps/a/app-module.ts": app("a"), + "src/contexts/c/context-module.ts": context("c", "a", 1), + "src/features/f1/feature-module.ts": feature("f1", "c"), + "src/features/f2/feature-module.ts": feature("f2", "c"), + }); + await expect(generateAppIndexes(overFeatures, "a")).rejects.toThrow(/c feature cardinality 2 exceeds budget 1/); + + const overContexts = await repo({ + "src/apps/a/app-module.ts": app("a", 1), + "src/contexts/c1/context-module.ts": context("c1", "a"), + "src/contexts/c2/context-module.ts": context("c2", "a"), + "src/features/f1/feature-module.ts": feature("f1", "c1"), + "src/features/f2/feature-module.ts": feature("f2", "c2"), + }); + await expect(generateAppIndexes(overContexts, "a")).rejects.toThrow(/App a context cardinality 2 exceeds budget 1/); + }); + + it("skips contexts without features and never imports another app's features", async () => { + const root = await repo({ + "src/apps/a/app-module.ts": app("a"), + "src/apps/b/app-module.ts": app("b"), + "src/contexts/empty/context-module.ts": context("empty", "a"), + "src/contexts/ca/context-module.ts": context("ca", "a"), + "src/contexts/cb/context-module.ts": context("cb", "b"), + "src/features/fa/feature-module.ts": feature("fa", "ca"), + "src/features/fb/feature-module.ts": feature("fb", "cb"), + }); + const selected = await generateAppIndexes(root, "a"); + expect(selected.entries.map((entry) => entry.id)).toEqual(["fa"]); + expect(selected.contextIndex).not.toContain("empty"); + expect(selected.featureIndex).not.toContain("features/fb/"); + expect(selected.appIndex).toContain('id: "a"'); + }); +}); diff --git a/tests/scripts/verify-extreme-scale.test.ts b/tests/scripts/verify-extreme-scale.test.ts new file mode 100644 index 00000000..0241a09c --- /dev/null +++ b/tests/scripts/verify-extreme-scale.test.ts @@ -0,0 +1,81 @@ +import { describe, expect, it } from "vitest"; + +import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; + +import { + EXTREME_SCALE_GATES, + satisfiesEngine, + sourceDigest, + vitestCounts, +} from "../../scripts/verify-extreme-scale.ts"; + +describe("extreme-scale verification runner", () => { + it.each([ + ["v24.11.0", true], + ["24.14.0", true], + ["v22.23.2", false], + ["24.10.9", false], + ["25.0.0", false], + ])("checks %s against the repository engine range (%s)", (version, supported) => { + expect(satisfiesEngine(version, ">=24.11.0 <25.0.0")).toBe(supported); + }); + + it("runs every scale gate and builds before the browser soak tier", () => { + for (const gate of [ + "check:types:app", + "check:types:test", + "check:feature-index", + "check:architecture", + "check:app-build-input", + "check:app-build-input:bundle", + "check:request-fanout", + "test:extreme-scale:focused", + "check:topology", + "check:traffic", + "check:observability", + "check:release-coherence", + "check:scale:pr", + "check:scale:main", + "check:scale:nightly", + "check:scale:release", + "check:scale:baseline", + ]) { + expect(EXTREME_SCALE_GATES).toContain(gate); + } + expect(EXTREME_SCALE_GATES.indexOf("build")).toBeLessThan( + EXTREME_SCALE_GATES.indexOf("check:scale:nightly"), + ); + expect(EXTREME_SCALE_GATES.indexOf("build")).toBeLessThan( + EXTREME_SCALE_GATES.indexOf("check:app-build-input:bundle"), + ); + }); +}); + +describe("evidence helpers", () => { + it("sums vitest test counts from coloured multi-run logs", () => { + const esc = String.fromCharCode(27); + const log = + `${esc}[2m Tests ${esc}[22m ${esc}[1m${esc}[32m68 passed${esc}[39m (68)\n` + + " Test Files 3 passed (3)\n" + + " Tests 1 failed | 10 passed | 2 skipped (13)\n"; + expect(vitestCounts(log)).toEqual({ passed: 78, failed: 1, skipped: 2, files: 3 }); + }); + + it("changes the source digest when any source file changes", async () => { + const root = await mkdtemp(path.join(tmpdir(), "digest-")); + try { + await mkdir(path.join(root, "src"), { recursive: true }); + await writeFile(path.join(root, "src/a.ts"), "export const a = 1;\n"); + await writeFile(path.join(root, "package.json"), "{}\n"); + const first = await sourceDigest(root); + expect(await sourceDigest(root)).toEqual(first); + await writeFile(path.join(root, "src/a.ts"), "export const a = 2;\n"); + expect((await sourceDigest(root)).digest).not.toBe(first.digest); + expect(first.files).toBe(2); + } finally { + await rm(root, { recursive: true, force: true }); + } + }); +}); diff --git a/tests/unit/diagnostics.test.ts b/tests/unit/diagnostics.test.ts index b4c428f4..4347ada7 100644 --- a/tests/unit/diagnostics.test.ts +++ b/tests/unit/diagnostics.test.ts @@ -139,3 +139,34 @@ describe("structured diagnostics contract", () => { ).not.toThrow(); }); }); + +describe("bounded diagnostic dimensions", () => { + it.each([ + ["component_boundary", "route", true], + ["component_boundary", "feature", true], + ["component_boundary", "boot", true], + ["component_boundary", "SomeComponentName", false], + ["component_boundary", 1, false], + ["queue_size_bucket", "0", true], + ["queue_size_bucket", "1-10", true], + ["queue_size_bucket", "51+", true], + ["queue_size_bucket", "4096", false], + ["queue_size_bucket", 3, false], + ] as const)("admits %s=%s only from its finite set (%s)", (key, value, admitted) => { + const projected = projectDiagnosticRecord( + { level: "warn", eventId: "ui.render.failed", context: { [key]: value } }, + () => 0, + ); + expect(projected.success).toBe(admitted); + }); +}); + +describe("open-ended bucket labels", () => { + it("records the top buckets that contain a plus sign", () => { + for (const context of [{ queue_size_bucket: "51+" }, { attempt_count_bucket: "5+" }]) { + expect( + projectDiagnosticRecord({ level: "warn", eventId: "ui.render.failed", context }, () => 0), + ).toMatchObject({ success: true, record: { context } }); + } + }); +}); diff --git a/tests/unit/error-classification.test.ts b/tests/unit/error-classification.test.ts index aaa525e3..e13c2661 100644 --- a/tests/unit/error-classification.test.ts +++ b/tests/unit/error-classification.test.ts @@ -6,6 +6,8 @@ import { kindForStatus, normalizeUnknownFailure, } from "../../src/contracts/errors.ts"; +import { DIAGNOSTIC_EVENT_REGISTRY } from "../../src/contracts/diagnostics.ts"; +import { TELEMETRY_REGISTRY } from "../../src/contracts/telemetry.ts"; describe("frontend failure classification", () => { it("defines all stable error kinds with the seven contract fields", () => { @@ -25,6 +27,17 @@ describe("frontend failure classification", () => { } }); + it("references only registered observability events", () => { + const registeredEvents = new Set([ + ...Object.keys(DIAGNOSTIC_EVENT_REGISTRY), + ...Object.keys(TELEMETRY_REGISTRY), + ]); + + for (const definition of Object.values(ERROR_REGISTRY)) { + expect(registeredEvents.has(definition.telemetryEvent)).toBe(true); + } + }); + it.each([ [401, "AUTH_REQUIRED"], [403, "FORBIDDEN"], @@ -63,6 +76,31 @@ describe("frontend failure classification", () => { expect(JSON.stringify(result)).not.toMatch(/stack|body|Bearer|secret/); }); + it("bounds validation metadata even for direct failure callers", () => { + const oversizedPath = "p".repeat(121); + const oversizedCode = "C".repeat(81); + const validationIssues = [ + { path: oversizedPath, code: "TOO_LONG_PATH" }, + { path: "field", code: oversizedCode }, + ...Array.from({ length: 100 }, (_, index) => ({ + path: `field.${index}`, + code: "INVALID", + })), + ]; + + const result = createFailure("VALIDATION_REJECTED", "SAVE_ENTITY", 0, { + validationIssues, + }); + + expect(result.validationIssues).toHaveLength(50); + expect(result.validationIssues?.[0]).toEqual({ + path: "field.0", + code: "INVALID", + }); + expect(JSON.stringify(result.validationIssues)).not.toContain(oversizedPath); + expect(JSON.stringify(result.validationIssues)).not.toContain(oversizedCode); + }); + it("normalizes any thrown value without leaking it", () => { const secret = { token: "sensitive", nested: { rawBody: "private" } }; const result = normalizeUnknownFailure(secret); diff --git a/tests/unit/http-retry-lifecycle.test.ts b/tests/unit/http-retry-lifecycle.test.ts index 3e27f63f..9841e443 100644 --- a/tests/unit/http-retry-lifecycle.test.ts +++ b/tests/unit/http-retry-lifecycle.test.ts @@ -42,7 +42,10 @@ describe("HTTP retry lifecycle policy", () => { expect(jitteredDelay(8, () => 0.5)).toBe(1_000); expect(retryDelayFor(null, 0, () => 0.5)).toBe(125); - expect(retryDelayFor(400, 0, () => 0.5)).toBe(400); + // ยง13.3: Retry-After is a floor plus bounded jitter, never an exact + // synchronized instant (400 + floor(0.5 * max(250, 100))). + expect(retryDelayFor(400, 0, () => 0.5)).toBe(525); + expect(retryDelayFor(400, 0, () => 0)).toBe(400); expect(retryDelayFor(5_001, 0, () => 0.5)).toBeNull(); }); }); diff --git a/tests/unit/observability-cardinality.test.ts b/tests/unit/observability-cardinality.test.ts new file mode 100644 index 00000000..a897e7d0 --- /dev/null +++ b/tests/unit/observability-cardinality.test.ts @@ -0,0 +1,58 @@ +import { describe, expect, it } from "vitest"; + +import { + DIAGNOSTIC_CONTEXT_ALLOWLIST, + DIAGNOSTIC_CONTEXT_CARDINALITY, + projectDiagnosticRecord, +} from "../../src/contracts/diagnostics.ts"; +import { TELEMETRY_ATTRIBUTE_ALLOWLIST } from "../../src/contracts/telemetry.ts"; + +describe("observability cardinality policy", () => { + it("classifies every diagnostic context key exactly once", () => { + expect(Object.keys(DIAGNOSTIC_CONTEXT_CARDINALITY).sort()).toEqual( + [...DIAGNOSTIC_CONTEXT_ALLOWLIST].sort(), + ); + expect(DIAGNOSTIC_CONTEXT_CARDINALITY.correlation_id).toBe("request"); + expect(DIAGNOSTIC_CONTEXT_CARDINALITY.route_id).toBe("topology"); + expect(DIAGNOSTIC_CONTEXT_CARDINALITY.operation_id).toBe("topology"); + expect(DIAGNOSTIC_CONTEXT_CARDINALITY.duration_bucket).toBe("bounded"); + }); + + it("keeps request-cardinality keys out of telemetry dimensions", () => { + for (const key of TELEMETRY_ATTRIBUTE_ALLOWLIST) { + expect(DIAGNOSTIC_CONTEXT_CARDINALITY[key]).not.toBe("request"); + } + expect(TELEMETRY_ATTRIBUTE_ALLOWLIST).not.toContain("correlation_id"); + }); + + it("rejects free-form values for bounded diagnostic dimensions", () => { + expect( + projectDiagnosticRecord({ + level: "info", + eventId: "http.request.completed", + context: { + outcome: "customer-123", + http_status_group: "599", + attempt_count_bucket: "37", + duration_bucket: "12345ms", + }, + }), + ).toEqual({ success: false, reason: "invalid-context" }); + }); + + it("allows request correlation only in bounded diagnostics evidence", () => { + const projected = projectDiagnosticRecord({ + level: "info", + eventId: "http.request.completed", + context: { + correlation_id: "request-a1b2c3", + outcome: "success", + http_status_group: "2xx", + attempt_count_bucket: "1", + duration_bucket: "lt100ms", + }, + }); + + expect(projected.success).toBe(true); + }); +}); diff --git a/tests/unit/product-features.test.ts b/tests/unit/product-features.test.ts index 422fd22a..d2b353ae 100644 --- a/tests/unit/product-features.test.ts +++ b/tests/unit/product-features.test.ts @@ -191,9 +191,18 @@ describe("every installed registry consults the manifest", () => { for (const registry of registries) { if (exempt.has(registry)) continue; const source = await readFile(nodePath.join(root, registry), "utf8"); + const manifestImport = source.match( + /import\s*\{([\s\S]*?)\}\s*from\s*["']\.\/installed-product-manifest\.ts["']/u, + ); expect( - /INSTALLED_PRODUCT_FEATURE(S|_IDS)/u.test(source), - `${registry} must compose from the product manifest`, + manifestImport, + `${registry} must import its selection from the product manifest`, + ).not.toBeNull(); + expect( + /\bINSTALLED_PRODUCT_FEATURE(?:S|_IDS|_MODULES)\b/u.test( + manifestImport?.[1] ?? "", + ), + `${registry} must compose from a selected product-feature projection`, ).toBe(true); } }); diff --git a/tests/unit/route-runtime.test.ts b/tests/unit/route-runtime.test.ts index 5a2bf8f1..5e4b3475 100644 --- a/tests/unit/route-runtime.test.ts +++ b/tests/unit/route-runtime.test.ts @@ -5,6 +5,7 @@ import { ROUTE_RUNTIME_CONTRACT, } from "../../src/features/installed-feature-contracts.ts"; import { ROUTE_RUNTIME } from "../../src/features/installed-feature-runtimes.tsx"; +import { PLATFORM_ROUTE_REGISTRY } from "../../src/contracts/routes.ts"; import { parseRouteInput } from "../../src/presentation/routes/route-codecs.ts"; describe("typed installed route catalog", () => { @@ -13,7 +14,7 @@ describe("typed installed route catalog", () => { Object.keys(ROUTE_REGISTRY).sort(), ); expect(Object.keys(ROUTE_RUNTIME).sort()).toEqual( - Object.keys(ROUTE_REGISTRY).sort(), + Object.keys(PLATFORM_ROUTE_REGISTRY).sort(), ); }); diff --git a/tests/unit/telemetry.test.ts b/tests/unit/telemetry.test.ts index 95ed7437..4d501f6f 100644 --- a/tests/unit/telemetry.test.ts +++ b/tests/unit/telemetry.test.ts @@ -356,3 +356,80 @@ describe("best-effort telemetry adapter", () => { }, ); }); + +describe("telemetry adapter send-rate limit (spec ยง27)", () => { + function harness(maxSendsPerMinute = 3) { + let now = 0; + const timers: Array<() => void> = []; + const lifecycle = new EventTarget(); + const fetcher = vi.fn(async () => new Response(null, { status: 204 })); + const adapter = createTelemetryAdapter({ + enabled: true, + endpoint: "https://telemetry.test/events", + schedule: () => {}, + fetcher, + lifecycle, + maxSendsPerMinute, + monotonicNow: () => now, + setTimer: (callback) => { + timers.push(callback); + return timers.length; + }, + clearTimer: () => {}, + }); + return { + adapter, + fetcher, + lifecycle, + timers, + advance(ms: number) { + now += ms; + }, + }; + } + + it("caps collector sends per minute during a sustained failure storm", async () => { + const { adapter, fetcher } = harness(3); + for (let i = 0; i < 25; i += 1) { + adapter.emit("api.request.failed", validAttributes); + await adapter.flush(); + } + expect(fetcher).toHaveBeenCalledTimes(3); + expect(adapter.pendingCount()).toBeLessThanOrEqual(100); + }); + + it("delivers held events once the window reopens", async () => { + const { adapter, fetcher, timers, advance } = harness(1); + adapter.emit("api.request.failed", validAttributes); + await adapter.flush(); + adapter.emit("api.request.failed", validAttributes); + await adapter.flush(); + expect(fetcher).toHaveBeenCalledTimes(1); + expect(timers).toHaveLength(1); + + advance(60_000); + timers.shift()?.(); + await vi.waitFor(() => expect(fetcher).toHaveBeenCalledTimes(2)); + expect(adapter.pendingCount()).toBe(0); + }); + + it("still delivers once on page exit when the window is exhausted", async () => { + const { adapter, fetcher, lifecycle } = harness(1); + adapter.emit("api.request.failed", validAttributes); + await adapter.flush(); + adapter.emit("api.request.failed", validAttributes); + lifecycle.dispatchEvent(new Event("pagehide")); + await vi.waitFor(() => expect(fetcher).toHaveBeenCalledTimes(2)); + adapter.dispose(); + }); + + it("rejects an unbounded send rate", () => { + expect(() => + createTelemetryAdapter({ + enabled: true, + endpoint: "https://telemetry.test/events", + maxSendsPerMinute: Number.POSITIVE_INFINITY, + }), + ).toThrow(TypeError); + }); +});