Merge pull request 'chore: 운영 이미지에만 있던 커밋 넷을 main에 넣는다' (#3) from chore/sync-production-7a4e201 into main

This commit was merged in pull request #3.
This commit is contained in:
2026-11-12 01:13:39 +00:00
743 changed files with 55134 additions and 13570 deletions
+139 -30
View File
@@ -2,6 +2,7 @@
"forbidden": [
{
"name": "domain-is-framework-neutral",
"comment": "domain holds framework-neutral models and pure policies. Keep the dependency out: move the code to application, or pass the value in from there.",
"severity": "error",
"from": {
"path": "^src/domain"
@@ -12,6 +13,7 @@
},
{
"name": "application-does-not-know-concrete-runtime",
"comment": "application owns use cases and the ports they need. Declare a port under src/application/ports and let src/bootstrap pass the concrete adapter.",
"severity": "error",
"from": {
"path": "^src/application"
@@ -22,6 +24,7 @@
},
{
"name": "presentation-does-not-know-adapters",
"comment": "§4. Presentation talks to application ports, not concrete adapters, the composition root or the TanStack runtime. Exception: src/presentation/adapters/query is the TanStack Query binding, the one place @tanstack is imported (docs/architecture/frontend-ports-adapters-and-boundaries.md). It needs @tanstack only; concrete-adapters-compose-only-in-bootstrap still keeps it off src/adapters. Owner: frontend-platform. Revisit if the binding moves out of presentation.",
"severity": "error",
"from": {
"path": "^src/presentation/(?!adapters/query)"
@@ -32,6 +35,7 @@
},
{
"name": "page-templates-own-layout-only",
"comment": "Page templates own layout only. Take data and actions as props from the page that uses the template.",
"severity": "error",
"from": {
"path": "^src/presentation/templates"
@@ -42,6 +46,7 @@
},
{
"name": "icon-vendor-is-facade-only",
"comment": "VD-05. lucide-react is imported by the icon vendor facade only; product code uses the semantic icons from the design-system index, so replacing the vendor touches one file.",
"severity": "error",
"from": {
"path": "^src",
@@ -51,8 +56,34 @@
"path": "^lucide-react$"
}
},
{
"name": "zod-is-reached-through-contracts-zod",
"comment": "F-7 (13-08). src/contracts/zod.ts sets zod jitless before any schema is built, so the production CSP never sees zod's Function probe. Schema code imports z from there.",
"severity": "error",
"from": {
"path": "^src",
"pathNot": "^src/contracts/zod\\.ts$"
},
"to": {
"path": "^zod$"
}
},
{
"name": "design-system-is-reached-through-its-index",
"comment": "VD-05, 12-08. Code outside src/presentation/design-system imports its public index.ts only, so the primitives can change behind it. Named facades: src/presentation/components/ui/*.ts re-export the canonical primitives under their pre-VD-05 paths (VD-05 Rollback). Exception: src/presentation/templates/page-templates.tsx reads PaginationLandmarkContext, which index.ts does not export. Owner: frontend-platform. Revisit: export it from index.ts or move the page templates into the design system.",
"severity": "error",
"from": {
"path": "^src/",
"pathNot": "^src/presentation/(design-system/|components/ui/[^/]+\\.ts$|templates/page-templates\\.tsx$)"
},
"to": {
"path": "^src/presentation/design-system/",
"pathNot": "^src/presentation/design-system/index\\.ts$"
}
},
{
"name": "adapters-do-not-know-presentation",
"comment": "An adapter implements an application port. It never imports UI or the composition root; pass what it needs through the port or its factory arguments.",
"severity": "error",
"from": {
"path": "^src/adapters"
@@ -63,6 +94,7 @@
},
{
"name": "feature-domain-is-framework-neutral",
"comment": "A feature's domain is framework-neutral, like src/domain. Move the code to the feature's application, or pass the value in from there.",
"severity": "error",
"from": {
"path": "^src/features/[^/]+/domain"
@@ -73,6 +105,7 @@
},
{
"name": "feature-application-does-not-know-runtime",
"comment": "A feature's application declares the ports it needs. Put the port in the feature's application and implement it in the feature's adapters/; bootstrap wires the two.",
"severity": "error",
"from": {
"path": "^src/features/[^/]+/application"
@@ -83,6 +116,7 @@
},
{
"name": "feature-presentation-does-not-know-outbound-adapters",
"comment": "Feature presentation calls its application API. The feature's adapters/ are wired by bootstrap, so import the application facade instead.",
"severity": "error",
"from": {
"path": "^src/features/[^/]+/presentation"
@@ -93,6 +127,7 @@
},
{
"name": "feature-adapters-do-not-know-presentation",
"comment": "A feature adapter implements the feature's ports and never imports UI or the composition root. Pass what it needs through the port.",
"severity": "error",
"from": {
"path": "^src/features/[^/]+/adapters"
@@ -103,6 +138,7 @@
},
{
"name": "concrete-adapters-compose-only-in-bootstrap",
"comment": "Only src/bootstrap constructs concrete adapters. Depend on the application port or facade; bootstrap composes the adapter behind it.",
"severity": "error",
"from": {
"path": "^src/(domain|application|presentation|contracts)"
@@ -113,7 +149,7 @@
},
{
"name": "external-contract-package-single-import-path",
"comment": "§4.1: a generated service package may only be imported from src/features/<feature>/contracts/*-contract-contribution.ts",
"comment": "§4.1: a generated service package may only be imported from src/features/<feature>/contracts/*-contract-contribution.ts. Owner: frontend-platform.",
"severity": "error",
"from": {
"path": "^src",
@@ -125,7 +161,7 @@
},
{
"name": "presentation-does-not-fetch-directly",
"comment": "§9.2 / appendix B: a page or hook never opens a socket, worker or HTTP adapter itself",
"comment": "§9.2 / appendix B: a page or hook never opens a socket, worker or HTTP adapter itself. Call the application API; bootstrap composes the adapter behind it.",
"severity": "error",
"from": {
"path": "^src/(presentation|features/[^/]+/presentation)"
@@ -134,9 +170,20 @@
"path": "^src/adapters/(http|realtime|service-worker|web-worker|storage)"
}
},
{
"name": "unselected-realtime-runtime-is-not-composed",
"comment": "§9.2 / 12-10. Realtime and Web Push are NOT_SELECTED in the template (src/features/installed-runtime-capabilities.ts), so the composition root and the installed-feature registries do not import their concrete adapters. A project that selects one replaces this rule when it wires the runtime. Owner: frontend-platform.",
"severity": "error",
"from": {
"path": "^src/(bootstrap/|features/installed-feature-)"
},
"to": {
"path": "^src/adapters/(realtime|web-push)/"
}
},
{
"name": "generic-worker-has-no-network-or-credentials",
"comment": "§16.13 / §21.10: a CPU worker never imports HTTP, realtime or auth",
"comment": "§16.13 / §21.10: a CPU worker never imports HTTP, realtime or auth. Do the network call on the page side and post the data to the worker.",
"severity": "error",
"from": {
"path": "^src/adapters/web-worker"
@@ -167,9 +214,20 @@
"path": "^src/(application|features)"
}
},
{
"name": "contracts-do-not-know-presentation-or-bootstrap",
"comment": "Q-6.7-12. `src/contracts` is shared vocabulary read by every layer, including the service worker and web worker builds. Importing presentation or the composition root from it would pull React and the whole app into those builds. There is no such import today; this keeps it that way.",
"severity": "error",
"from": {
"path": "^src/contracts"
},
"to": {
"path": "^src/(presentation|bootstrap)"
}
},
{
"name": "generic-presentation-does-not-compose-the-product",
"comment": "§4 / §9. Which features are installed is a product decision that belongs to bootstrap. Generic presentation reads the installed registries directly today; the paths below are the exact set that does so, frozen so the coupling cannot spread while the assembly is lifted into bootstrap.",
"comment": "§4 / §9. Which features are installed is a product decision that belongs to bootstrap. Exception: the generic presentation modules in pathNot read the installed registries today. The list names exact files, so a new module that reads a registry fails the gate. Owner: frontend-platform. Revisit when the assembly is lifted into bootstrap; remove each file from the list as it stops reading the registries.",
"severity": "error",
"from": {
"path": "^src/presentation/",
@@ -181,7 +239,7 @@
},
{
"name": "adapters-do-not-know-other-concrete-adapters",
"comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. Only the adapter kernel is shared — `src/adapters/platform` (clock, abort primitive, capacity guard) and the browser-data result helpers. `query-cache` still reads two collaborator types from `cross-context-invalidation`; that edge is named here rather than left silent, and closes when those types are lifted to a port.",
"comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (clock, abort primitive, capacity guard), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.",
"severity": "error",
"from": {
"path": "^src/adapters/([^/]+)/"
@@ -193,7 +251,7 @@
},
{
"name": "adapter-groups-are-reached-through-their-barrel",
"comment": "어댑터 그룹의 공개 표면은 그 그룹의 index.ts다. 그룹 바깥(bootstrap, features, presentation)은 배럴만 import한다. 배럴이 없던 시절 bootstrap은 어댑터 내부 파일 15곳을 직접 겨눴고, 그래서 어떤 파일이 공개이고 어떤 파일이 내부 헬퍼인지 아무 데도 적혀 있지 않았다. 출발점에서 src/adapters를 뺀 이유는 어댑터끼리의 간선은 바로 위 adapters-do-not-know-other-concrete-adapters가 이미 담당하고, 커널(platform/**)은 파일 단위로 공유되기 때문이다 — scripts/check-adapter-inventory.ts가 네 소비자에게 platform/abortable-operation.ts로 해석되는 specifier를 직접 요구한다. 도착점에서 1단계 중첩 index.ts를 허용한 이유는 storage/indexeddb와 storage/opfs가 각자 독립적으로 제거 가능한 런타임이고(scripts/test-browser-file-storage-runtime-removal.ts), 그래서 각자의 배럴이 곧 경계이기 때문이다.",
"comment": "어댑터 그룹의 공개 표면은 그 그룹의 index.ts다. 그룹 바깥(bootstrap, features, presentation)은 배럴만 import한다. 배럴이 없던 시절 bootstrap은 어댑터 내부 파일 15곳을 직접 겨눴고, 그래서 어떤 파일이 공개이고 어떤 파일이 내부 헬퍼인지 아무 데도 적혀 있지 않았다. 출발점에서 src/adapters를 뺀 이유는 어댑터끼리의 간선은 바로 위 adapters-do-not-know-other-concrete-adapters가 이미 담당하고, 커널(platform/**)은 파일 단위로 공유되기 때문이다 — scripts/check-adapter-inventory.ts가 네 소비자에게 platform/abortable-operation.ts로 해석되는 specifier를 직접 요구한다. 예외: 도착점에서 storage/indexeddb/index.ts와 storage/opfs/index.ts만 서브배럴로 허용한다. 두 폴더는 browser-file-storage 번들의 런타임이고, 제거 드릴(scripts/test-browser-file-storage-runtime-removal.ts)은 그 번들 전체(browser-file-storage, browser-files, browser-transfer, cache-storage, storage/indexeddb, storage/opfs)를 함께 지운다. 최상위 storage 배럴(Web Storage)은 그 뒤에도 남아야 하므로 두 폴더를 재수출하지 않고, 그래서 각 서브배럴이 그 런타임의 공개 경계다. 다른 2단계 index.ts는 공개 배럴이 아니다(리뷰 12-07). 담당: frontend-platform. 재검토: 새 런타임을 따로 제거할 수 있게 만들 때 그 서브배럴을 이 목록에 추가한다.",
"severity": "error",
"from": {
"path": "^src/",
@@ -201,38 +259,89 @@
},
"to": {
"path": "^src/adapters/[^/]+/",
"pathNot": "^src/adapters/[^/]+/index\\.ts$|^src/adapters/[^/]+/[^/]+/index\\.ts$"
"pathNot": "^src/adapters/[^/]+/index\\.ts$|^src/adapters/storage/(indexeddb|opfs)/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": "feature-and-app-roots-do-not-reach-adapters",
"comment": "12-03. The graph checks one edge at a time, so a module that presentation may import must not re-export a concrete adapter: presentation would then reach it with every direct rule passing. That covers the files outside a feature's layer folders (src/features/*.ts, src/features/<feature>/*.ts), src/contexts and src/apps. Inside a feature, only its adapters/ folder reaches src/adapters; the product composes adapters in bootstrap. Exception: src/features/feature-adapter-contribution.ts imports the InstalledHttpOperationExecutor type that bootstrap hands to feature adapters (type only). Owner: frontend-platform. Revisit when that type moves to an application port.",
"severity": "error",
"from": {
"path": "^src/(features/[^/]+\\.tsx?$|features/[^/]+/[^/]+\\.tsx?$|contexts/|apps/)",
"pathNot": "^src/features/feature-adapter-contribution\\.ts$"
},
"to": {
"path": "^src/adapters/"
}
},
{
"name": "presentation-does-not-import-apps-or-contexts",
"comment": "12-03. Apps and contexts compose features, including their runtime, so presentation importing them is a path around presentation-does-not-know-adapters. Exception: src/presentation/routes/app-router.tsx mounts the deployable app's route tree (src/apps/template-app.ts). Owner: frontend-platform. Revisit when the router is assembled in bootstrap together with the frozen generic-presentation-does-not-compose-the-product list.",
"severity": "error",
"from": {
"path": "^src/(presentation/|features/[^/]+/presentation/)",
"pathNot": "^src/presentation/routes/app-router\\.tsx$"
},
"to": {
"path": "^src/(apps|contexts)/"
}
},
{
"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. Exception: src/platform/routing composes deployable-app descriptors by type. Owner: frontend-platform. Revisit if routing gains a product-specific import.",
"severity": "error",
"from": {
"path": "^src/platform/",
"pathNot": "^src/platform/routing/"
},
"to": {
"path": "^src/(features|contexts|apps|adapters|bootstrap|presentation|application)/"
}
},
{
"name": "no-circular-dependencies",
"comment": "A cycle makes the modules impossible to load or remove one at a time. Move the shared part into a lower module that both import.",
"severity": "error",
"from": {},
"to": {
"circular": true
}
}
],
"options": {
"doNotFollow": {
"path": "node_modules"
},
"exclude": {
"path": "^(dist|artifacts|tests/fixtures)"
},
"enhancedResolveOptions": {
"exportsFields": [
"exports"
],
"conditionNames": [
"import",
"require",
"node",
"default"
]
},
"tsConfig": {
"fileName": "tsconfig.app.json"
}
}
]
}
+1 -1
View File
@@ -6,7 +6,7 @@
# Runtime configuration — API endpoints, auth mode, telemetry, capability
# switches — is NOT here. It lives in `config/runtime/<profile>.json` and is
# materialized into `dist/config.json` at build time, so it can be changed
# without rebuilding. See docs/architecture/layers.md.
# without rebuilding. See the "Runtime configuration" section of README.md.
#
# Copy to `.env.local` (git-ignored) to override locally.
+15 -5
View File
@@ -83,16 +83,14 @@ jobs:
if: ${{ startsWith(gitea.ref, 'refs/tags/v') || (gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'release' || inputs.stage == 'production' || inputs.stage == 'field')) }}
runs-on: ubuntu-latest
timeout-minutes: 45
env:
HOSTING_BASE_URL: "${{ vars.HOSTING_BASE_URL }}"
strategy:
fail-fast: false
matrix:
include:
- { gate: FE-GATE-012, name: bundle, browser: false }
- { gate: FE-GATE-014, name: config-compatibility, browser: false }
- { gate: FE-GATE-019, name: hosting-header, browser: false }
- { gate: FE-GATE-026, name: lab-performance, browser: true }
- { gate: FE-GATE-028, name: manual-accessibility-review, browser: false }
steps:
- uses: https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
with:
@@ -142,6 +140,8 @@ jobs:
corepack pnpm install --frozen-lockfile --ignore-scripts
- name: Build candidate once and verify local evidence
run: corepack pnpm ci:gate -- FE-GATE-015
- name: Admit the candidate to the declared release target
run: corepack pnpm ci:gate -- FE-GATE-027
- name: Archive and validate the exact candidate file set
id: candidate
run: |
@@ -369,15 +369,18 @@ jobs:
production_gate:
name: "${{ matrix.gate }} / ${{ matrix.name }}"
needs: promotion
needs: [immutable_build, promotion]
if: ${{ gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'production' || inputs.stage == 'field') }}
runs-on: ubuntu-latest
timeout-minutes: 45
env:
HOSTING_BASE_URL: "${{ vars.HOSTING_BASE_URL }}"
CANDIDATE_ARCHIVE_SHA256: "${{ needs.immutable_build.outputs.archive_sha256 }}"
strategy:
fail-fast: false
matrix:
include:
- { gate: FE-GATE-016, name: rollback-drill }
- { gate: FE-GATE-019, name: hosting-header }
- { gate: FE-GATE-021, name: runbook-boot-config }
- { gate: FE-GATE-022, name: runbook-chunk-mismatch }
- { gate: FE-GATE-023, name: runbook-api-degradation }
@@ -394,6 +397,13 @@ jobs:
run: |
corepack enable
corepack pnpm install --frozen-lockfile --ignore-scripts
- name: Download promoted release
uses: https://github.com/ChristopherHX/gitea-download-artifact@75635f32b4c1c41c4b3d64e8f85210112ed4c9c7
with:
name: "promoted-release-${{ gitea.run_id }}-${{ gitea.run_attempt }}"
path: .release/promoted
- name: Verify and extract the candidate through one inode-bound operation
run: node scripts/verify-ci-candidate-archive.ts --archive ".release/promoted/release-candidate.tar.gz" --extract-to ".release/promoted-release"
- name: Run blocking gate
run: corepack pnpm ci:gate -- ${{ matrix.gate }}
- name: Upload production gate evidence
+3
View File
@@ -37,3 +37,6 @@ artifacts/tests/visual/
# 다시 들어오지 못하게 막는다. 시험 기준 그림(tests/visual/**)과
# 화면에 쓰는 그림(public/**)은 각자 자리에 있으므로 여기 걸리지 않는다.
/*.png
# graphify knowledge-graph output (local analysis, not part of the product).
graphify-out/
+2 -2
View File
@@ -1,2 +1,2 @@
engine-strict=true
save-exact=true
# pnpm 11 reads engineStrict and saveExact from pnpm-workspace.yaml, not from
# this file (review 13-09). Keep only npm-level settings such as registry auth here.
+180 -7
View File
@@ -25,8 +25,54 @@ corepack pnpm install --frozen-lockfile
corepack pnpm dev
```
Runtime-public settings live in `public/config.json` and are validated before
the product tree mounts. Client secrets are forbidden.
## Runtime configuration
Runtime-public settings are validated against one schema before the product
tree mounts (`runtimeConfigV2ArtifactSchema` in
`src/contracts/release-artifacts.ts`). Client secrets are forbidden.
The source of truth is `config/runtime/<profile>.json`, one file per
environment: `local`, `development`, `staging`, `production`. `corepack pnpm
build` writes `dist/config.json` from the selected profile
(`scripts/generate-runtime-config.ts`). `public/config.json` is only the local
profile for `corepack pnpm dev`; the build replaces it, so settings put there
never reach a deployment. Keep it equal to `config/runtime/local.json` plus
`BUILD_ID: local-build` and `RELEASE_ID: local-release`;
`tests/unit/deployment-admission.test.ts` fails when the two differ.
Build and deploy variables, lowest precedence first:
| Variable | Sets | Default |
| --- | --- | --- |
| `APP_PROFILE` | which `config/runtime/<profile>.json` is used | `local`; an empty value fails the build |
| `RUNTIME_API_BASE_URL` | `API_BASE_URL`, overriding the profile | the profile value |
| `RUNTIME_TELEMETRY_ENDPOINT` | `TELEMETRY_ENDPOINT`, overriding the profile | the profile value |
| `VITE_BUILD_ID` | `BUILD_ID` in the runtime config and the release manifest | `local-build` |
| `RELEASE_ID` | `RELEASE_ID` in the runtime config and the release manifest | `local-release` |
| `RELEASE_TARGET` | the environment FE-GATE-027 admits the build to; must equal `APP_PROFILE` | none; admission refuses without it |
`verify:documentation` fails if this table stops naming a variable the build or
admission reads (`scripts/verify-documentation-readiness.ts`).
Only the two `RUNTIME_*` values can differ from the reviewed profile. Anything
else changes by editing the profile file. Staging and production reject demo
auth and non-HTTPS endpoints.
A production build and its admission check:
```bash
APP_PROFILE=production \
RUNTIME_API_BASE_URL=https://api.example.com/ \
RUNTIME_TELEMETRY_ENDPOINT=https://telemetry.example.com/v1/events \
VITE_BUILD_ID=<unique build id> RELEASE_ID=<unique release id> \
corepack pnpm build
APP_PROFILE=production RELEASE_TARGET=production corepack pnpm check:release-admission
```
With `CI=true` the gate runner (`corepack pnpm ci:gate`) also requires
`VITE_COMMIT_SHA`, `SOURCE_DATE_EPOCH` and `CI_RUNNER_IMAGE` before it runs a
gate (`scripts/lib/build-environment.ts`, `scripts/run-ci-gate.ts`). The CI variable
list is in [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md).
## TechLog experience
@@ -130,6 +176,46 @@ hand-written:
this sandbox. Run it any time to confirm the vendored contract has not
drifted from what was last generated.
## Support scope
Four tiers. The status words on the right are the ones the catalogs and
design documents use; the next table maps them.
| Tier | What it covers | Status words |
| --- | --- | --- |
| Default | In the default build and covered by the merge gates: the TechLog Public and Studio shells and routes, the REST HTTP executor, TanStack Query server state, Local/Session Storage registries, cross-tab invalidation, runtime config profiles and the release manifest check, `AUTH_MODE=external` (`demo` only in local/development), and the typed message catalog. `dist/` is served by a static host ([`docs/architecture/static-delivery.md`](docs/architecture/static-delivery.md)) | `COMPOSED` |
| Optional (recipe) | Not installed. A project copies one of the recipes in `config/recipes/frontend-capability-recipes.json` and narrows it ([`docs/architecture/optional-adapter-recipes.md`](docs/architecture/optional-adapter-recipes.md)). `realtime`, `offline-indexeddb`, `service-worker-pwa` and `file-transfer` also ship a tested reference runtime that the default build leaves out | `RECIPE_AVAILABLE`, `NOT_INSTALLED`, `AVAILABLE_NOT_COMPOSED` |
| Experimental | Designed and decided, but the runtime is missing or unfinished; finish it before building on it. GraphQL, gRPC-Web, Connect-Web and Protobuf adapters, Range resumable download, IndexedDB query persistence, the local preview decode-safety probe. `src/features/local-draft-feature` is an architecture sample, not installed; so is `src/features/reference-feature`, the template's removable sample, whose screens this product deleted | `DESIGNED_NOT_IMPLEMENTED` |
| Not supported | Deliberately not selected, or browsers cannot guarantee it: SSR, app-managed background upload and download, directory selection, persistent file handles, product query persistence, exactly-once delivery between tabs | `NOT_SELECTED`, `PLATFORM_LIMITED` |
The rows come from
[`docs/architecture/browser-data-capability-completion-ledger.md`](docs/architecture/browser-data-capability-completion-ledger.md),
[`docs/architecture/client-cache-and-storage.md`](docs/architecture/client-cache-and-storage.md)
and
[`docs/architecture/api-contract-schema-mapper-and-server-state.md`](docs/architecture/api-contract-schema-mapper-and-server-state.md).
| Status word | Where it appears | Meaning | Tier |
| --- | --- | --- | --- |
| `COMPOSED` | capability ledger, design documents | wired into the default production path | Default |
| `INSTALLED` | a project's own recipe catalog (step 10 of the recipe procedure) | the project added the recipe | Default, for that project |
| `RECIPE_AVAILABLE` | recipe catalog `status` | a recipe exists to copy; nothing is installed | Optional |
| `NOT_INSTALLED` | recipe catalog `defaultStatus`; a `src/features/<id>/NOT_INSTALLED` marker file | not part of the build | Optional (recipe) or Experimental (feature) |
| `AVAILABLE_NOT_COMPOSED` | capability ledger; recipe `referenceRuntime.status` | code and tests exist; the default build leaves it out | Optional |
| `DESIGNED_NOT_IMPLEMENTED` | capability ledger, design documents | design approved, runtime missing | Experimental |
| `NOT_SELECTED` | capability ledger, design documents | deliberately not chosen | Not supported |
| `PLATFORM_LIMITED` | capability ledger | browsers cannot guarantee it; offered only behind a probe and a fallback, if at all | Not supported as a guarantee |
Gate results (`PASS`, `PASS_SCOPED`, `UNVERIFIED`, `FAIL_UNVERIFIED`) are
verdicts on evidence, not support tiers.
Browsers: the build targets Chrome and Edge 111, Firefox 128, and Safari and
iOS 16.4. That is the higher of Vite 8's default JavaScript target
(`baseline-widely-available`; `vite.config.ts` sets no `build.target`) and
the CSS targets of Tailwind CSS 4. There is no browserslist. The end-to-end
suite runs on the desktop Chromium, Firefox and WebKit builds that Playwright
1.62 pins, plus one Chromium phone-size smoke (`playwright.config.ts`). Older
versions inside the target range and real mobile browsers are not tested.
## Architecture
This repository is a **Frontend Application Foundation**: a starter/composition
@@ -184,6 +270,31 @@ project-owned integrations. They are target designs and review findings; a
capability is not treated as implemented until its branch acceptance criteria
and executable gates pass.
## Documentation
[`docs/README.md`](docs/README.md) sorts the documents into current contracts,
target designs and work history.
### Files you can delete after copying
These record how the template and this product were built. Nothing in the
build or the gates reads them, except the one file noted below
(`tests/unit/deletable-history-documents.test.ts` checks this).
| Path | Contents |
| --- | --- |
| `docs/superpowers/` | past plans and specs |
| `docs/reviews/` | reviews. Keep `docs/reviews/adapters/INVENTORY.md`: `check:adapter-inventory` (FE-GATE-010) reads it |
The template's own `SPEC.md`, `tasks/` and `CLAUDE.md` were never carried
into this repository (`docs/operations/template-sync-2026-09-29.md`).
The reference feature is not in this list: deleting its directory alone
leaves tests, policy entries and CI scripts behind that fail the gates.
`scripts/test-sample-removal.ts` removes it from a copy of
the repository and lists everything that has to go with it (its header comment
and `SAMPLE_EXTRAS`); do the same in your project and run the gates.
## Verification
Common local checks:
@@ -212,6 +323,11 @@ corepack pnpm exec playwright test tests/e2e/tech-log-public-discovery.spec.ts t
corepack pnpm test:visual
```
`drill:runbooks` stops at the first drill that is not `PASS`. Without provider
evidence every drill ends `UNVERIFIED` (exit 3), because a drill never reports
a check it could not run locally as `PASS`; see "Runbook jobs" in
[`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md).
`test:all` is the ordinary product-development loop and intentionally excludes
host-level CI-runner assurance. Run `corepack pnpm test:system` only on the
compatible Linux assurance host described in
@@ -241,8 +357,8 @@ corepack pnpm exec playwright install --with-deps chromium firefox webkit
Two gates intentionally need external evidence:
- `review:a11y-manual` needs a signed human keyboard/focus/screen-reader review
for all 27 registered routes:
- `review:a11y-manual` (release gate FE-GATE-028) needs a signed human
keyboard/focus/screen-reader review for all 27 registered routes:
`NOT_FOUND`, `TECH_LOG_CASE`, `TECH_LOG_EXPLORE`, `TECH_LOG_EXPLORE_KIND`,
`TECH_LOG_HOME`, `TECH_LOG_PROFILE`, `TECH_LOG_PROJECT`,
`TECH_LOG_PROJECTS`, `TECH_LOG_PROJECT_ACTIVITY`,
@@ -255,15 +371,19 @@ Two gates intentionally need external evidence:
`TECH_LOG_STUDIO_NOT_FOUND`, `TECH_LOG_STUDIO_PUBLICATIONS`,
`TECH_LOG_STUDIO_PUBLICATION_PREVIEW`, `TECH_LOG_TOPIC`.
`verify:documentation` derives that list from the route registry and fails if
this paragraph falls behind it.
this paragraph falls behind it. The merge gate FE-GATE-009 runs only
`review:a11y-manual -- --format-only`, which checks that every route record
keeps the template's fields, reviewed or still pending.
- `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until a reviewed minimum
eligible-sample threshold and 28 days of production data exist.
Live release verification additionally requires `HOSTING_BASE_URL`.
Live hosting verification (FE-GATE-019, production stage) requires
`HOSTING_BASE_URL` and a deployed promoted release; without it the result is
`UNVERIFIED`, not `PASS`.
## CI and evidence
The 27-gate registry is `config/ci/gates.json`; the Gitea workflow is
The gate registry is `config/ci/gates.json`; the Gitea workflow is
`.gitea/workflows/quality-gates.yml`. It follows:
```text
@@ -271,8 +391,61 @@ MERGE_READY -> RELEASE_READY -> PROD_PROMOTION_READY -> FIELD_SLO_READY
```
`DOCUMENTATION_READY` is independent. No gate is downgraded to a warning.
The workflow runs on pull requests, pushes to `main`, and `v*` tags. The Git host of this repository may not have Actions enabled, so a pull
request can show no gate status at all; no status is not a pass. Until the
host runs the workflow and marks the merge gates as required checks, run the 13
merge gates locally before merging (FE-GATE-008 and 009 need Playwright
browsers):
```bash
for gate in 001 002 003 004 005 006 007 008 009 010 011 013 020; do
corepack pnpm ci:gate -- "FE-GATE-$gate" || break
done
```
Machine-readable evidence is written below `artifacts/`; generated evidence is
ignored by Git while `.gitkeep` files preserve the taxonomy.
Operational details are in `docs/operations/`, with incident procedures in
`docs/runbooks/`.
## Updating a copied project
Template versions are Git tags `vX.Y.Z`. The template repository's
`CHANGELOG.md` lists the changes between tags, marks security fixes **[보안]** and contract changes
**[계약]** (backend, deployment, CI or feature code must change too), and names
the affected paths.
Record where you started. The template suggests a one-line `.template-origin`
file; this repository records the same thing, more precisely, in
`template.lock.json` (`sourceRevision` and `sourceTree`), and every sync is
written up in `docs/operations/template-sync-*.md`.
Take a template fix with Git. `cherry-pick` works even when your repository
does not share the template's history, because it merges against the picked
commit's parent:
```bash
git remote add template <template repository URL>
git fetch template --tags
git log --oneline <your origin>..template/main # what changed since you copied
git cherry-pick -x <commit> # one fix; -x records its origin
```
When the files have moved or diverged too far for a clean pick, read the
change as a diff and apply it by hand:
```bash
git diff <commit>^ <commit> -- <paths from CHANGELOG>
```
Afterwards run the local merge gates from "CI and evidence", apply the
backend or deployment change a **[계약]** row names, and update
`template.lock.json` once you have caught up to a tag. `git revert` undoes a pick.
Defects: if a problem reproduces on an unmodified checkout of the template at
`template.lock.json`'s `sourceRevision`, it is a template defect. Report it on the template
repository with that commit and the reproduction; the template maintainer
classifies it and ships the fix with a CHANGELOG entry. A problem that needs
your changes to reproduce belongs to your project, and applying a template fix
to your copy is your project's job.
-38
View File
@@ -1,38 +0,0 @@
{
"schemaVersion": 1,
"layers": {
"domain": {
"root": "src/domain",
"mayImport": ["src/domain"]
},
"application": {
"root": "src/application",
"mayImport": ["src/application", "src/domain", "src/contracts"]
},
"presentation": {
"root": "src/presentation",
"mayImport": ["src/presentation", "src/application", "src/domain", "src/contracts"]
},
"adapters": {
"root": "src/adapters",
"mayImport": ["src/adapters", "src/application", "src/domain", "src/contracts"]
},
"bootstrap": {
"root": "src/bootstrap",
"mayImport": ["src"]
}
},
"forbidden": [
["domain", "application"],
["domain", "presentation"],
["domain", "adapters"],
["domain", "bootstrap"],
["application", "presentation"],
["application", "adapters"],
["application", "bootstrap"],
["presentation", "adapters"],
["presentation", "bootstrap"],
["adapters", "presentation"],
["adapters", "bootstrap"]
]
}
+11
View File
@@ -0,0 +1,11 @@
{
"schemaVersion": 1,
"owner": "tech-log-frontend",
"reason": "Template sync ebea300..af3d8e6: the merged gate set (template's four new commands and FE-GATE-028, this product's three TechLog commands and per-route manual a11y evidence)",
"gates": 27,
"commands": 101,
"commandReferences": 106,
"artifacts": 141,
"stages": 5,
"gateShapeSha256": "c9adcf85701156097262d8f88203fe42f8be003033e1b6c296a0062e56f10324"
}
+149 -86
View File
@@ -177,9 +177,14 @@
{
"id": "check-types-fixture-diagnostics",
"script": "check:types:fixture:diagnostics",
"expect": "pass"
},
{
"id": "check-types-fixture-image-resolve-signal",
"script": "check:types:fixture:image-resolve-signal",
"expect": "fail",
"expectedExitCode": 1,
"expectedDiagnosticId": "UNKNOWN_DIAGNOSTIC_EVENT"
"expectedDiagnosticId": "error TS2741:"
},
{
"id": "test-runtime-schema",
@@ -208,6 +213,11 @@
"expectedExitCode": 1,
"expectedDiagnosticId": "Risk coverage failed:"
},
{
"id": "check-scale-pr",
"script": "check:scale:pr",
"expect": "pass"
},
{
"id": "test-component",
"script": "test:component",
@@ -290,11 +300,30 @@
"script": "review:a11y-manual",
"expect": "pass"
},
{
"id": "check-a11y-manual-format",
"script": "review:a11y-manual",
"args": [
"--",
"--format-only"
],
"expect": "pass"
},
{
"id": "check-architecture",
"script": "check:architecture",
"expect": "pass"
},
{
"id": "check-request-fanout",
"script": "check:request-fanout",
"expect": "pass"
},
{
"id": "check-app-build-input",
"script": "check:app-build-input",
"expect": "pass"
},
{
"id": "check-design-system",
"script": "check:design-system",
@@ -397,6 +426,11 @@
"script": "check:dev-release-manifest",
"expect": "pass"
},
{
"id": "check-adapter-inventory",
"script": "check:adapter-inventory",
"expect": "pass"
},
{
"id": "build",
"script": "build",
@@ -412,6 +446,11 @@
"script": "check:bundle",
"expect": "pass"
},
{
"id": "check-app-build-input-bundle",
"script": "check:app-build-input:bundle",
"expect": "pass"
},
{
"id": "check-optional-recipes",
"script": "check:optional-recipes",
@@ -462,7 +501,9 @@
"script": "drill:runbook",
"args": [
"--",
"FE-RB-005"
"FE-RB-005",
"--release-root",
".release/promoted-release"
],
"expect": "pass"
},
@@ -506,7 +547,9 @@
"script": "drill:runbook",
"args": [
"--",
"FE-RB-001"
"FE-RB-001",
"--release-root",
".release/promoted-release"
],
"expect": "pass"
},
@@ -515,7 +558,9 @@
"script": "drill:runbook",
"args": [
"--",
"FE-RB-002"
"FE-RB-002",
"--release-root",
".release/promoted-release"
],
"expect": "pass"
},
@@ -524,7 +569,9 @@
"script": "drill:runbook",
"args": [
"--",
"FE-RB-003"
"FE-RB-003",
"--release-root",
".release/promoted-release"
],
"expect": "pass"
},
@@ -533,7 +580,9 @@
"script": "drill:runbook",
"args": [
"--",
"FE-RB-004"
"FE-RB-004",
"--release-root",
".release/promoted-release"
],
"expect": "pass"
},
@@ -1691,12 +1740,6 @@
"build-release-candidate"
]
},
{
"id": "artifact-artifacts-quality-gates-FE-GATE-016-txt",
"path": "artifacts/quality/gates/FE-GATE-016.txt",
"schemaId": "text",
"production": "runner-generated"
},
{
"id": "artifact-artifacts-runbooks-FE-RB-005-record-json",
"path": "artifacts/runbooks/FE-RB-005/record.json",
@@ -1897,6 +1940,12 @@
"path": "artifacts/quality/gates/FE-GATE-027.txt",
"schemaId": "text",
"production": "runner-generated"
},
{
"id": "artifact-artifacts-quality-gates-FE-GATE-028-txt",
"path": "artifacts/quality/gates/FE-GATE-028.txt",
"schemaId": "text",
"production": "runner-generated"
}
],
"gates": [
@@ -1952,7 +2001,8 @@
"check-types-fixture-icon-button",
"check-types-fixture-i18n-key",
"check-types-fixture-i18n-params",
"check-types-fixture-diagnostics"
"check-types-fixture-diagnostics",
"check-types-fixture-image-resolve-signal"
],
"logArtifactId": "artifact-artifacts-quality-check-types-txt",
"evidenceArtifactIds": [
@@ -1979,7 +2029,8 @@
"test-unit",
"test-contract",
"test-coverage",
"check-coverage-fixture"
"check-coverage-fixture",
"check-scale-pr"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-005-txt",
"evidenceArtifactIds": [
@@ -2058,49 +2109,11 @@
"name": "accessibility",
"commandIds": [
"test-a11y",
"review-a11y-manual"
"check-a11y-manual-format"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-009-txt",
"evidenceArtifactIds": [
"artifact-artifacts-tests-a11y-json",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-HOME-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-EXPLORE-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-EXPLORE-KIND-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-CASE-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-REFERENCE-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-CONCEPT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-SETUP-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-QUESTION-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-TOPICS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-TOPIC-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-TOPIC-VARIANT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-PROJECTS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-PROJECT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-PROJECT-RECORDS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-PROJECT-DECISIONS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-PROJECT-ACTIVITY-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-RELEASES-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-RELEASE-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-PROFILE-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-SEARCH-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-HOME-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-DOCUMENTS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-DOCUMENT-NEW-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-DOCUMENT-EDIT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-DOCUMENT-VALIDATION-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-DOCUMENT-PREVIEW-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-DOCUMENT-PUBLISH-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-PUBLICATIONS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-PUBLICATION-PREVIEW-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-ASSETS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-TAXONOMY-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-PROJECT-EDIT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-TOPIC-EDIT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-RELEASES-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-RELEASE-EDIT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-NOT-FOUND-md",
"artifact-artifacts-tests-a11y-manual-NOT-FOUND-md",
"artifact-artifacts-tests-a11y-manual-report-json"
"artifact-artifacts-tests-a11y-json"
],
"retentionClassId": "merge-cycle"
},
@@ -2109,6 +2122,8 @@
"name": "architecture",
"commandIds": [
"check-architecture",
"check-request-fanout",
"check-app-build-input",
"check-design-system",
"check-design-system-fixture",
"check-i18n",
@@ -2127,6 +2142,7 @@
"check-routes-fixture",
"check-tech-log-contract",
"check-dev-release-manifest",
"check-adapter-inventory",
"check-ci"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-010-txt",
@@ -2171,6 +2187,7 @@
"commandIds": [
"build",
"check-bundle",
"check-app-build-input-bundle",
"check-optional-recipes"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-012-txt",
@@ -2238,19 +2255,6 @@
],
"retentionClassId": "release-coherence"
},
{
"id": "FE-GATE-016",
"name": "rollback-drill",
"commandIds": [
"build",
"drill-runbook"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-016-txt",
"evidenceArtifactIds": [
"artifact-artifacts-runbooks-FE-RB-005-record-json"
],
"retentionClassId": "prod-drill"
},
{
"id": "FE-GATE-017",
"name": "diagram-review",
@@ -2290,7 +2294,7 @@
"evidenceArtifactIds": [
"artifact-artifacts-release-hosting-headers-json"
],
"retentionClassId": "release-coherence",
"retentionClassId": "prod-drill",
"requiresEnvironment": [
"HOSTING_BASE_URL"
]
@@ -2317,7 +2321,6 @@
"id": "FE-GATE-021",
"name": "runbook-boot-config",
"commandIds": [
"build",
"drill-runbook-2"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-021-txt",
@@ -2330,7 +2333,6 @@
"id": "FE-GATE-022",
"name": "runbook-chunk-mismatch",
"commandIds": [
"build",
"drill-runbook-3"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-022-txt",
@@ -2343,7 +2345,6 @@
"id": "FE-GATE-023",
"name": "runbook-api-degradation",
"commandIds": [
"build",
"drill-runbook-4"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-023-txt",
@@ -2356,7 +2357,6 @@
"id": "FE-GATE-024",
"name": "runbook-telemetry",
"commandIds": [
"build",
"drill-runbook-5"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-024-txt",
@@ -2369,7 +2369,6 @@
"id": "FE-GATE-025",
"name": "runbook-release-rollback",
"commandIds": [
"build",
"drill-runbook"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-025-txt",
@@ -2402,6 +2401,55 @@
"artifact-artifacts-release-deployment-admission-json"
],
"retentionClassId": "release-coherence"
},
{
"id": "FE-GATE-028",
"name": "manual-accessibility-review",
"commandIds": [
"review-a11y-manual"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-028-txt",
"evidenceArtifactIds": [
"artifact-artifacts-tests-a11y-manual-TECH-LOG-HOME-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-EXPLORE-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-EXPLORE-KIND-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-CASE-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-REFERENCE-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-CONCEPT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-SETUP-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-QUESTION-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-TOPICS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-TOPIC-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-TOPIC-VARIANT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-PROJECTS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-PROJECT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-PROJECT-RECORDS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-PROJECT-DECISIONS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-PROJECT-ACTIVITY-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-RELEASES-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-RELEASE-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-PROFILE-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-SEARCH-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-HOME-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-DOCUMENTS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-DOCUMENT-NEW-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-DOCUMENT-EDIT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-DOCUMENT-VALIDATION-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-DOCUMENT-PREVIEW-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-DOCUMENT-PUBLISH-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-PUBLICATIONS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-PUBLICATION-PREVIEW-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-ASSETS-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-TAXONOMY-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-PROJECT-EDIT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-TOPIC-EDIT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-RELEASES-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-RELEASE-EDIT-md",
"artifact-artifacts-tests-a11y-manual-TECH-LOG-STUDIO-NOT-FOUND-md",
"artifact-artifacts-tests-a11y-manual-NOT-FOUND-md",
"artifact-artifacts-tests-a11y-manual-report-json"
],
"retentionClassId": "release-coherence"
}
],
"stages": [
@@ -2435,9 +2483,9 @@
"FE-GATE-012",
"FE-GATE-014",
"FE-GATE-015",
"FE-GATE-019",
"FE-GATE-026",
"FE-GATE-027"
"FE-GATE-027",
"FE-GATE-028"
]
},
{
@@ -2447,7 +2495,7 @@
"release"
],
"gateIds": [
"FE-GATE-016",
"FE-GATE-019",
"FE-GATE-021",
"FE-GATE-022",
"FE-GATE-023",
@@ -2541,18 +2589,13 @@
"gateIds": [
"FE-GATE-012",
"FE-GATE-014",
"FE-GATE-019",
"FE-GATE-026"
"FE-GATE-026",
"FE-GATE-028"
],
"browserGateIds": [
"FE-GATE-026"
],
"environment": [
{
"name": "HOSTING_BASE_URL",
"value": "${{ vars.HOSTING_BASE_URL }}"
}
],
"environment": [],
"steps": [
{
"kind": "checkout"
@@ -2973,12 +3016,13 @@
"displayName": "${{ matrix.gate }} / ${{ matrix.name }}",
"kind": "gate-matrix",
"needs": [
"immutable_build",
"promotion"
],
"condition": "production",
"timeoutMinutes": 45,
"gateIds": [
"FE-GATE-016",
"FE-GATE-019",
"FE-GATE-021",
"FE-GATE-022",
"FE-GATE-023",
@@ -2986,7 +3030,16 @@
"FE-GATE-025"
],
"browserGateIds": [],
"environment": [],
"environment": [
{
"name": "HOSTING_BASE_URL",
"value": "${{ vars.HOSTING_BASE_URL }}"
},
{
"name": "CANDIDATE_ARCHIVE_SHA256",
"value": "${{ needs.immutable_build.outputs.archive_sha256 }}"
}
],
"steps": [
{
"kind": "checkout"
@@ -2997,6 +3050,16 @@
{
"kind": "frozen-install"
},
{
"kind": "download",
"transferId": "promoted-release",
"path": ".release/promoted"
},
{
"kind": "extract",
"archivePath": ".release/promoted/release-candidate.tar.gz",
"targetRoot": ".release/promoted-release"
},
{
"kind": "run-gate"
},
+77
View File
@@ -0,0 +1,77 @@
{
"schemaVersion": 1,
"entries": [
{
"script": "check:feature-index",
"reason": "The generated indexes (src/.generated/) are not committed, and every gate script regenerates them first (generate-product-feature-index.ts), so --check can only tell a developer that the local copy is stale."
},
{
"script": "check:http-scenario-evidence",
"reason": "Run by scripts/run-http-scenario-evidence.ts, which is test:http-scenario-evidence in FE-GATE-007; that runner calls it by name after the scenario catalog."
},
{
"script": "check:http-scenario-evidence:fixture",
"reason": "Negative fixture run by scripts/run-http-scenario-evidence.ts (test:http-scenario-evidence, FE-GATE-007), which requires it to fail with TEST-EVIDENCE-EXECUTION-ID-MISSING."
},
{
"script": "check:remediation-ledger",
"reason": "Checks the prose ledger of the 2026-08-14 adapter re-review (docs/operations/adapter-remediation-ledger.md) against test-file markers and the file-transfer bundle budget. Later fixes removed those markers and the budget is re-set at integration, so the check reports stale claims at this commit. It is a history record run by hand, not a current contract; wiring it into a gate first needs the ledger or the markers brought up to date."
},
{
"script": "check:scale:baseline",
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"script": "check:scale:main",
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"script": "check:scale:nightly",
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"script": "check:scale:release",
"reason": "Scale tier outside CI (scripts/scale/run-scale-profile.ts): it includes baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run it on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"script": "check:test-evidence",
"reason": "Local all-in-one run. CI splits it: check:test-evidence:browser (--skip-scenario-executions) in FE-GATE-008 after the browser suites, and the scenario part through test:http-scenario-evidence in FE-GATE-007."
},
{
"script": "check:test-evidence:source",
"reason": "--source-only is a subset of check:test-evidence:browser (FE-GATE-008), for a quick local run without browser results."
},
{
"script": "drill:runbooks",
"reason": "Local shortcut for all five drills. CI runs each drill as its own production gate (FE-GATE-021 to FE-GATE-025) through drill:runbook."
},
{
"script": "test:all",
"reason": "Local aggregate of suites the gates run one by one (FE-GATE-004 to FE-GATE-007). The removal checks in FE-GATE-020 run it inside their fixtures through scripts/lib/removal-fixture.ts, not through the package script graph."
},
{
"script": "test:e2e:dev",
"reason": "Runs tests/e2e against the Vite dev server (playwright.dev.config.ts) for local debugging. FE-GATE-008 runs the same specs against the production build (test:e2e)."
},
{
"script": "test:extreme-scale:focused",
"reason": "Part of verify:extreme-scale. All its paths run in FE-GATE-005 except tests/scale/global-local-independence.test.ts, which belongs to the main scale tier (see config/ci/ungated-tests.json)."
},
{
"script": "test:visual:update",
"reason": "Rewrites the visual snapshots; it is an update command, not a check. FE-GATE-008 runs test:visual."
},
{
"script": "verify:extreme-scale",
"reason": "Local aggregate of 24 scripts (scripts/verify-extreme-scale.ts). Its CPU-independent parts run in gates; the main, nightly and release scale tiers need the baseline CPU (see check:scale:main)."
},
{
"script": "verify:promotion",
"reason": "Re-verifies a promotion bundle archived by an earlier run (13-04, --archived) with provider trust keys and EXPECTED_PROMOTION_* inputs of that run. In CI the promotion job verifies the same bundle through scripts/stage-verified-promotion.ts before it uploads it."
},
{
"script": "verify:tech-log-source-parity",
"reason": "Compares the TechLog build against the read-only original TechLog source served from a temp copy on another port (README \"TechLog experience\"). No CI runner has that source server, so the comparison is run by hand when the UI migration baseline is re-checked (docs/operations/techlog-ui-migration-baseline.md)."
}
]
}
+29
View File
@@ -0,0 +1,29 @@
{
"schemaVersion": 1,
"entries": [
{
"path": "tests/scale/composition-scale.test.ts",
"reason": "Scale suite in the main or nightly tier (scripts/scale/run-scale-profile.ts). No CI job runs those tiers: both include baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run check:scale:main or check:scale:nightly on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"path": "tests/scale/global-local-independence.test.ts",
"reason": "Scale suite in the main or nightly tier (scripts/scale/run-scale-profile.ts). No CI job runs those tiers: both include baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run check:scale:main or check:scale:nightly on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"path": "tests/scale/session/long-session.test.ts",
"reason": "Scale suite in the main or nightly tier (scripts/scale/run-scale-profile.ts). No CI job runs those tiers: both include baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run check:scale:main or check:scale:nightly on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"path": "tests/scale/session/network-flap.test.ts",
"reason": "Scale suite in the main or nightly tier (scripts/scale/run-scale-profile.ts). No CI job runs those tiers: both include baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run check:scale:main or check:scale:nightly on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"path": "tests/scale/telemetry/telemetry-storm.test.ts",
"reason": "Scale suite in the main or nightly tier (scripts/scale/run-scale-profile.ts). No CI job runs those tiers: both include baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run check:scale:main or check:scale:nightly on that machine. The CPU-independent pr tier runs in FE-GATE-005."
},
{
"path": "tests/scale/tsc-diagnostics-parser.test.ts",
"reason": "Scale suite in the main or nightly tier (scripts/scale/run-scale-profile.ts). No CI job runs those tiers: both include baseline-regression, which compares timings only on the CPU model that recorded config/scale/benchmark-baseline.json and reports incomplete elsewhere (review 11-03). Run check:scale:main or check:scale:nightly on that machine. The CPU-independent pr tier runs in FE-GATE-005."
}
]
}
+57 -53
View File
@@ -1,63 +1,67 @@
{
"schemaVersion": 1,
"families": {
"api": {
"additive": {
"before": { "required": ["id"], "properties": { "id": {} } },
"after": {
"required": ["id"],
"properties": { "id": {}, "displayName": {} }
}
},
"breaking": {
"before": { "required": ["id"], "properties": { "id": {} } },
"after": {
"required": ["id", "name"],
"properties": { "id": {}, "name": {} }
}
"schemaVersion": 2,
"cases": [
{
"id": "tolerant-reader-optional-field",
"expected": "additive",
"before": { "required": ["id"], "properties": { "id": {} } },
"after": {
"required": ["id"],
"properties": { "id": {}, "displayName": {} }
}
},
"config": {
"additive": {
"before": { "required": ["APP_ENV"], "properties": { "APP_ENV": {} } },
"after": {
"required": ["APP_ENV"],
"properties": { "APP_ENV": {}, "OPTIONAL_FLAG": {} }
}
{
"id": "strict-reader-optional-field",
"expected": "breaking",
"before": {
"required": ["APP_ENV"],
"properties": { "APP_ENV": {} },
"additionalProperties": false
},
"breaking": {
"before": { "required": ["APP_ENV"], "properties": { "APP_ENV": {} } },
"after": {
"required": ["APP_ENV", "NEW_REQUIRED"],
"properties": { "APP_ENV": {}, "NEW_REQUIRED": {} }
}
"after": {
"required": ["APP_ENV"],
"properties": { "APP_ENV": {}, "OPTIONAL_FLAG": {} },
"additionalProperties": false
}
},
"storage": {
"additive": {
"before": { "properties": { "theme": {} } },
"after": { "properties": { "theme": {}, "contrast": {} } }
},
"breaking": {
"before": { "properties": { "theme": {} } },
"after": { "properties": {} }
{
"id": "required-field-added",
"expected": "breaking",
"before": { "required": ["buildId"], "properties": { "buildId": {} } },
"after": {
"required": ["buildId", "assetManifestHash"],
"properties": { "buildId": {}, "assetManifestHash": {} }
}
},
"release": {
"additive": {
"before": { "required": ["buildId"], "properties": { "buildId": {} } },
"after": {
"required": ["buildId"],
"properties": { "buildId": {}, "builtAt": {} }
}
},
"breaking": {
"before": { "required": ["buildId"], "properties": { "buildId": {} } },
"after": {
"required": ["buildId", "assetManifestHash"],
"properties": { "buildId": {}, "assetManifestHash": {} }
}
}
{
"id": "field-removed",
"expected": "breaking",
"before": { "properties": { "theme": {} } },
"after": { "properties": {} }
},
{
"id": "type-changed",
"expected": "breaking",
"before": { "properties": { "id": { "type": "string" } } },
"after": { "properties": { "id": { "type": "number" } } }
},
{
"id": "enum-narrowed",
"expected": "breaking",
"before": { "properties": { "state": { "enum": ["A", "B"] } } },
"after": { "properties": { "state": { "enum": ["A"] } } }
},
{
"id": "nullable-added",
"expected": "breaking",
"before": { "properties": { "note": { "type": "string" } } },
"after": { "properties": { "note": { "type": ["string", "null"] } } }
},
{
"id": "unchanged",
"expected": "none",
"before": { "required": ["id"], "properties": { "id": { "type": "string" } } },
"after": { "properties": { "id": { "type": "string" } }, "required": ["id"] }
}
}
]
}
@@ -0,0 +1,158 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"APP_ENV": {
"type": "string",
"enum": [
"local",
"development",
"staging",
"production"
]
},
"API_BASE_URL": {
"type": "string",
"format": "uri"
},
"REQUEST_TIMEOUT_MS": {
"default": 10000,
"type": "integer",
"minimum": 100,
"maximum": 60000
},
"MAX_RETRY_ATTEMPTS": {
"default": 2,
"type": "integer",
"minimum": 0,
"maximum": 2
},
"TELEMETRY_ENABLED": {
"type": "boolean"
},
"TELEMETRY_ENDPOINT": {
"type": "string",
"format": "uri"
},
"AUTH_MODE": {
"type": "string",
"enum": [
"external",
"demo"
]
},
"RELEASE_MANIFEST_URL": {
"default": "/release-manifest.json",
"type": "string",
"minLength": 1
},
"RELEASE_ID": {
"type": "string",
"minLength": 1
},
"BUILD_ID": {
"type": "string",
"minLength": 1
},
"CONFIG_SCHEMA_VERSION": {
"type": "string",
"const": "2.0"
},
"CAPABILITY_OVERRIDES": {
"default": {
"REALTIME": "DEFAULT",
"WEB_WORKER": "DEFAULT",
"SERVICE_WORKER": "DEFAULT",
"OFFLINE_COMMANDS": "DEFAULT"
},
"type": "object",
"properties": {
"REALTIME": {
"default": "DEFAULT",
"type": "string",
"enum": [
"DEFAULT",
"DISABLED"
]
},
"WEB_WORKER": {
"default": "DEFAULT",
"type": "string",
"enum": [
"DEFAULT",
"DISABLED"
]
},
"SERVICE_WORKER": {
"default": "DEFAULT",
"type": "string",
"enum": [
"DEFAULT",
"DISABLED"
]
},
"OFFLINE_COMMANDS": {
"default": "DEFAULT",
"type": "string",
"enum": [
"DEFAULT",
"DISABLED"
]
}
},
"required": [
"REALTIME",
"WEB_WORKER",
"SERVICE_WORKER",
"OFFLINE_COMMANDS"
],
"additionalProperties": false
},
"FEATURE_OVERRIDES": {
"default": {},
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,63}$"
},
"additionalProperties": {
"type": "string",
"enum": [
"DEFAULT",
"DISABLED"
]
}
},
"TECH_LOG_STUDIO_SOURCE": {
"default": "MOCK",
"type": "string",
"enum": [
"MOCK",
"HTTP"
]
},
"TECH_LOG_PUBLIC_SOURCE": {
"default": "MOCK",
"type": "string",
"enum": [
"MOCK",
"HTTP"
]
}
},
"required": [
"APP_ENV",
"API_BASE_URL",
"REQUEST_TIMEOUT_MS",
"MAX_RETRY_ATTEMPTS",
"TELEMETRY_ENABLED",
"AUTH_MODE",
"RELEASE_MANIFEST_URL",
"CONFIG_SCHEMA_VERSION",
"CAPABILITY_OVERRIDES",
"FEATURE_OVERRIDES",
"TECH_LOG_STUDIO_SOURCE",
"TECH_LOG_PUBLIC_SOURCE"
],
"additionalProperties": false
}
@@ -1,7 +1,7 @@
{
"schemaVersion": 1,
"snapshotDigest": "428479ac5845374a82dd7d02a0c59a713106405f031cdc153789174f14c1405b",
"snapshotDigest": "2dc6c3a36a5e06c5b4736a0e2bc556d74437f061e6adb71c4e4fb96293170def",
"owner": "tech-log-frontend",
"reason": "Install approved TechLog Public and Studio route contract",
"approvedAt": "2026-08-15T16:32:32.042Z"
"reason": "Template sync ebea300..af3d8e6: three-way merge of this product's approved baseline (428479ac…) with the template's approved changes (83d11f84…). No row is taken from the current tree, so the pending TechLog route changes stay unapproved.",
"approvedAt": "2026-09-29T06:10:02.000Z"
}
+43 -473
View File
@@ -1107,7 +1107,7 @@
"registryId": "FE-REG-ENV",
"owner": "feature-frontend-env-runtime-config-contract",
"source": "src/contracts/env.ts",
"rowCount": 14,
"rowCount": 16,
"contract": {
"requiredFields": [
"phase",
@@ -1173,6 +1173,12 @@
"phase": "runtime",
"required": true
},
"FEATURE_OVERRIDES": {
"classification": "public",
"defaultValue": null,
"phase": "runtime",
"required": false
},
"MAX_RETRY_ATTEMPTS": {
"classification": "public",
"defaultValue": 2,
@@ -1215,6 +1221,12 @@
"phase": "build",
"required": false
},
"VITE_PRODUCT_FEATURES": {
"classification": "compile-time",
"defaultValue": null,
"phase": "build",
"required": false
},
"VITE_ROUTER_BASE_PATH": {
"classification": "compile-time",
"defaultValue": "/",
@@ -1233,7 +1245,7 @@
"registryId": "FE-REG-STORAGE",
"owner": "feature-frontend-storage-registry-contract",
"source": "src/contracts/storage-keys.ts",
"rowCount": 5,
"rowCount": 7,
"contract": {
"requiredFields": [
"logicalName",
@@ -1353,6 +1365,19 @@
"ttl": null,
"valueCodec": "color-scheme-v1"
},
"LOCALE": {
"backend": "localStorage",
"classification": "public-preference",
"logicalName": "LOCALE",
"migration": "discard",
"name": "locale",
"physicalKey": "ca-frontend:preference:v1:locale",
"quotaFallback": "memory",
"schemaVersion": 1,
"scope": "preference",
"ttl": null,
"valueCodec": "opaque-string-v1"
},
"QUERY_PERSISTENCE": {
"backend": "disabled",
"classification": "sensitive-forbidden",
@@ -1365,6 +1390,19 @@
"scope": "cache",
"ttl": null,
"valueCodec": "none"
},
"RELEASE_MISMATCH_RECOVERY": {
"backend": "sessionStorage",
"classification": "opaque-cache",
"logicalName": "RELEASE_MISMATCH_RECOVERY",
"migration": "discard",
"name": "boot-mismatch-recovery",
"physicalKey": "ca-frontend:release:v1:boot-mismatch-recovery",
"quotaFallback": "no-persist",
"schemaVersion": 1,
"scope": "release",
"ttl": "session",
"valueCodec": "opaque-string-v1"
}
}
},
@@ -1377,30 +1415,19 @@
"requiredFields": [
"kind",
"defaultRetryable",
"severity",
"userMessageKey",
"action",
"telemetryEvent",
"redaction"
"action"
],
"fieldTypes": {
"kind": "string",
"defaultRetryable": "boolean",
"severity": "string",
"userMessageKey": "string",
"action": "string",
"telemetryEvent": "string",
"redaction": "array"
"action": "string"
},
"uniqueFields": [
"kind"
],
"allowedValues": {
"severity": [
"info",
"warning",
"error"
],
"action": [
"retry",
"reauth",
@@ -1415,8 +1442,7 @@
"breakingFields": [
"kind",
"userMessageKey",
"action",
"telemetryEvent"
"action"
]
},
"rows": {
@@ -1424,684 +1450,228 @@
"action": "contact-support",
"defaultRetryable": false,
"kind": "API_CONTRACT_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "app.boot.failed",
"userMessageKey": "error.api_contract_mismatch"
},
"ASSET_MISMATCH": {
"action": "reload-once",
"defaultRetryable": false,
"kind": "ASSET_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "release.mismatch.detected",
"userMessageKey": "error.asset_mismatch"
},
"AUTH_INTEGRATION_FAILURE": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "AUTH_INTEGRATION_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.auth_integration_failure"
},
"AUTH_REQUIRED": {
"action": "reauth",
"defaultRetryable": false,
"kind": "AUTH_REQUIRED",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "info",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.auth_required"
},
"BOOT_CONFIG_FAILURE": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "BOOT_CONFIG_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "app.boot.failed",
"userMessageKey": "error.boot_config_failure"
},
"BUILD_MISMATCH": {
"action": "reload-once",
"defaultRetryable": false,
"kind": "BUILD_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "release.mismatch.detected",
"userMessageKey": "error.build_mismatch"
},
"CHUNK_LOAD_FAILURE": {
"action": "reload-once",
"defaultRetryable": false,
"kind": "CHUNK_LOAD_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "release.mismatch.detected",
"userMessageKey": "error.chunk_load_failure"
},
"CONFIG_MISMATCH": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "CONFIG_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "app.boot.failed",
"userMessageKey": "error.config_mismatch"
},
"CONFLICT": {
"action": "retry",
"defaultRetryable": false,
"kind": "CONFLICT",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.conflict"
},
"CONTENT_TYPE_MISMATCH": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "CONTENT_TYPE_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.content_type_mismatch"
},
"DEPLOY_MISMATCH": {
"action": "reload-once",
"defaultRetryable": false,
"kind": "DEPLOY_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "release.mismatch.detected",
"userMessageKey": "error.deploy_mismatch"
},
"DUPLICATE_IN_FLIGHT": {
"action": "none",
"defaultRetryable": false,
"kind": "DUPLICATE_IN_FLIGHT",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "info",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.duplicate_in_flight"
},
"ENVELOPE_MISMATCH": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "ENVELOPE_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.envelope_mismatch"
},
"FORBIDDEN": {
"action": "navigate",
"defaultRetryable": false,
"kind": "FORBIDDEN",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.forbidden"
},
"IDENTITY_INTERN_LIMIT_EXCEEDED": {
"action": "retry",
"defaultRetryable": false,
"kind": "IDENTITY_INTERN_LIMIT_EXCEEDED",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.identity_intern_limit_exceeded"
},
"MALFORMED_JSON": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "MALFORMED_JSON",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.malformed_json"
},
"MAPPING_CONTRACT_VIOLATION": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "MAPPING_CONTRACT_VIOLATION",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.mapping_contract_violation"
},
"NETWORK_UNREACHABLE": {
"action": "retry",
"defaultRetryable": true,
"kind": "NETWORK_UNREACHABLE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.network_unreachable"
},
"NOT_FOUND": {
"action": "navigate",
"defaultRetryable": false,
"kind": "NOT_FOUND",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "info",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.not_found"
},
"PAGINATION_CONTRACT_VIOLATION": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "PAGINATION_CONTRACT_VIOLATION",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.pagination_contract_violation"
},
"QUERY_CACHE_FAILURE": {
"action": "retry",
"defaultRetryable": false,
"kind": "QUERY_CACHE_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "query.cache.failed",
"userMessageKey": "error.query_cache_failure"
},
"RATE_LIMITED": {
"action": "retry",
"defaultRetryable": true,
"kind": "RATE_LIMITED",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.rate_limited"
},
"RELEASE_MANIFEST_FAILURE": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "RELEASE_MANIFEST_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "app.boot.failed",
"userMessageKey": "error.release_manifest_failure"
},
"RELEASE_MISMATCH": {
"action": "reload-once",
"defaultRetryable": false,
"kind": "RELEASE_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "release.mismatch.detected",
"userMessageKey": "error.release_mismatch"
},
"RENDER_FAILURE": {
"action": "reload-once",
"defaultRetryable": false,
"kind": "RENDER_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "ui.render.failed",
"userMessageKey": "error.render_failure"
},
"REQUEST_ABORTED": {
"action": "none",
"defaultRetryable": false,
"kind": "REQUEST_ABORTED",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "info",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.request_aborted"
},
"REQUEST_TIMEOUT": {
"action": "retry",
"defaultRetryable": true,
"kind": "REQUEST_TIMEOUT",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.request_timeout"
},
"RESPONSE_BODY_LIMIT": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "RESPONSE_BODY_LIMIT",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.response_body_limit"
},
"RESULT_LIMIT_EXCEEDED": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "RESULT_LIMIT_EXCEEDED",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.result_limit_exceeded"
},
"SCHEMA_MISMATCH": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "SCHEMA_MISMATCH",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.schema_mismatch"
},
"SCOPE_GENERATION_CHANGED": {
"action": "none",
"defaultRetryable": false,
"kind": "SCOPE_GENERATION_CHANGED",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "info",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.scope_generation_changed"
},
"SERVER_FAILURE": {
"action": "retry",
"defaultRetryable": true,
"kind": "SERVER_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.server_failure"
},
"STORAGE_QUOTA_EXCEEDED": {
"action": "none",
"defaultRetryable": false,
"kind": "STORAGE_QUOTA_EXCEEDED",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "storage.operation.failed",
"userMessageKey": "error.storage_quota_exceeded"
},
"STORAGE_UNAVAILABLE": {
"action": "none",
"defaultRetryable": false,
"kind": "STORAGE_UNAVAILABLE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "storage.operation.failed",
"userMessageKey": "error.storage_unavailable"
},
"TELEMETRY_FAILURE": {
"action": "none",
"defaultRetryable": false,
"kind": "TELEMETRY_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "info",
"telemetryEvent": "telemetry.delivery.dropped",
"userMessageKey": "error.telemetry_failure"
},
"UNKNOWN_CLIENT_FAILURE": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "UNKNOWN_CLIENT_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "warning",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.unknown_client_failure"
},
"UNKNOWN_FAILURE": {
"action": "contact-support",
"defaultRetryable": false,
"kind": "UNKNOWN_FAILURE",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "error",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.unknown_failure"
},
"VALIDATION_REJECTED": {
"action": "none",
"defaultRetryable": false,
"kind": "VALIDATION_REJECTED",
"redaction": [
"authorization",
"body",
"cause",
"headers",
"query",
"stack",
"storageValue",
"url"
],
"severity": "info",
"telemetryEvent": "api.request.failed",
"userMessageKey": "error.validation_rejected"
}
}
+274 -146
View File
@@ -1,6 +1,206 @@
{
"schemaVersion": 1,
"changes": [
{
"changeId": "FE-REG-ENV:API_CONTRACT_VERSION:*:removed",
"versionBump": "Runtime Config V2 (CONFIG_SCHEMA_VERSION 2.0) removes the scalar API contract version.",
"migration": "Release Manifest V2 contractSet replaces the scalar: the compiled external contract package set is canonicalized and digested, and boot compares it against the manifest.",
"compatibilityWindow": "The V1 config and V1 manifest readers stay in place for one release. A V1 document may still carry the scalar; a V2 document is rejected if it does.",
"rollback": "Restore the V1 writer in scripts/generate-build-manifest.ts and the scalar key in public/config.json; the V1 reader is still present.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-QUERY:*:*:removed",
"versionBump": "Query invalidation composition moves from the legacy flat query registry to the bounded many-to-many invalidation graph.",
"migration": "Installed feature contracts now contribute topics, namespace identities, edges, and separate wire versions; bootstrap validates and indexes those contributions before constructing coordinators.",
"compatibilityWindow": "Cross-context envelopes remain opaque topic/version pairs and release cache epochs isolate mixed releases; no query keys or cached values cross contexts.",
"rollback": "Restore the flat QUERY_REGISTRY composition and its coordinator adapter together with the prior governance entry.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-QUERY:$contract:allowedValues:contract-field-changed",
"versionBump": "Cross-context invalidation wire protocol starts at version 1.",
"migration": "Every installed query row declares invalidate-only; older tabs remain local-only.",
"compatibilityWindow": "Mixed releases are isolated by release cacheEpoch and never exchange query keys or values.",
"rollback": "Remove the coordinator composition and the two query registry fields.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-QUERY:$contract:breakingFields:contract-field-changed",
"versionBump": "Cross-context invalidation wire protocol starts at version 1.",
"migration": "Every installed query row declares its opaque topic and transport policy.",
"compatibilityWindow": "A release cacheEpoch rejects messages from a different deployed contract.",
"rollback": "Remove the coordinator composition and restore the prior query registry contract.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-QUERY:$contract:fieldTypes:contract-field-changed",
"versionBump": "Cross-context invalidation wire protocol starts at version 1.",
"migration": "The installed reference query row and all consumers were updated atomically.",
"compatibilityWindow": "Old clients do not consume the new fields; new clients validate them before boot.",
"rollback": "Restore the previous query registry field types and local-only invalidation.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-QUERY:$contract:requiredFields:contract-field-changed",
"versionBump": "Cross-context invalidation wire protocol starts at version 1.",
"migration": "Missing topics now fail registry validation instead of silently degrading at runtime.",
"compatibilityWindow": "Only a fully built release consumes its own installed registry snapshot.",
"rollback": "Remove the newly required fields and cross-context composition together.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-QUERY:$contract:uniqueFields:contract-field-changed",
"versionBump": "Cross-context invalidation wire protocol starts at version 1.",
"migration": "Existing query namespaces received unique registry-issued opaque topics.",
"compatibilityWindow": "Topics are scoped by release cacheEpoch, so mixed releases cannot collide.",
"rollback": "Drop invalidationTopic uniqueness after removing the transport consumer.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-RELEASE:apiContractVersion:compatibilityRole:field-changed",
"versionBump": "The release token registry adds contractSetDigest and demotes apiContractVersion to a legacy V1 scalar.",
"migration": "compareReleaseToRuntime no longer sources the scalar from Runtime Config; when neither side declares it there is nothing to compare and contractSet verification owns contract coherence.",
"compatibilityWindow": "A V1 manifest still supplies apiContractVersion and is still compared against a V1 config that declares one.",
"rollback": "Restore the previous compatibilityRole text and remove the contractSetDigest token together with the V2 manifest writer.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-STORAGE:$contract:allowedValues:contract-field-changed",
"versionBump": "Web Storage value codec contracts start at version 1.",
"migration": "Existing keys retain their physical schema version; values outside the selected codec are discarded.",
"compatibilityWindow": "Valid existing color-scheme and opaque-string records remain readable.",
"rollback": "Restore the previous registry contract; no physical key deletion is required.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-STORAGE:$contract:breakingFields:contract-field-changed",
"versionBump": "Web Storage value codec contracts start at version 1.",
"migration": "Each existing row received an explicit codec; executable migration was never consumed and is now forbidden.",
"compatibilityWindow": "Schema-versioned physical keys and the envelope shape remain unchanged.",
"rollback": "Remove valueCodec enforcement and restore the prior metadata declaration.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-STORAGE:$contract:fieldTypes:contract-field-changed",
"versionBump": "Web Storage value codec contracts start at version 1.",
"migration": "The dead function migration union was narrowed to the only implemented discard policy.",
"compatibilityWindow": "All installed definitions already used discard before this contract change.",
"rollback": "Restore the former type metadata without rewriting persisted records.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-STORAGE:$contract:requiredFields:contract-field-changed",
"versionBump": "Web Storage value codec contracts start at version 1.",
"migration": "All installed storage rows now declare their closed value codec.",
"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-ROUTE:TECH_LOG_STUDIO_HOME:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_DOCUMENTS:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_DOCUMENT_NEW:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_DOCUMENT_EDIT:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_DOCUMENT_VALIDATION:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_DOCUMENT_PREVIEW:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_DOCUMENT_PUBLISH:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_PUBLICATIONS:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_PUBLICATION_PREVIEW:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_NOT_FOUND:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"owner": "tech-log-frontend"
},
{
"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"
},
{
"changeId": "FE-REG-ENV:VITE_BUILD_ID:defaultValue:field-type-changed",
"versionBump": "F-6 (13-15): the registry now records the local-build fallback that getBuildConfig and the build scripts already applied; the value itself did not change.",
"migration": "None for local builds. A staging or production build without VITE_BUILD_ID now fails in scripts/generate-runtime-config.ts instead of shipping the placeholder that admission refused.",
"compatibilityWindow": "No runtime document or wire format changes: BUILD_ID was already local-build whenever VITE_BUILD_ID was unset.",
"rollback": "Restore defaultValue null on VITE_BUILD_ID in src/contracts/env.ts and drop the public-target check in scripts/generate-runtime-config.ts.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-ROUTE:REFERENCE_RESOURCE_DETAIL:path:field-changed",
"versionBump": "The reference detail route moves from /examples/reference-resources/:resourceId to /examples/reference-resources/items/:resourceId (maturity review 08-13), so a server id equal to the static segments new or status opens its detail instead of the form or status screen.",
"migration": "The only in-app link (reference-resource-page.tsx) builds the new path from the contract route. The reference feature is a sample; downstream features that copied it keep their own paths.",
"compatibilityWindow": "None for bookmarked sample detail URLs: an old /examples/reference-resources/<id> URL no longer matches the detail route; new and status keep opening the form and status screens.",
"rollback": "Restore the previous path in src/features/reference-feature/contracts/reference-feature-contract.ts and the link in reference-resource-page.tsx, then drop this entry.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-ROUTE:$contract:allowedValues:contract-field-changed",
"versionBump": "TechLog route contract v1 replaces the starter and reference-resource route set.",
@@ -186,179 +386,107 @@
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ENV:API_CONTRACT_VERSION:*:removed",
"versionBump": "Runtime Config V2 (CONFIG_SCHEMA_VERSION 2.0) removes the scalar API contract version.",
"migration": "Release Manifest V2 contractSet replaces the scalar: the compiled external contract package set is canonicalized and digested, and boot compares it against the manifest.",
"compatibilityWindow": "The V1 config and V1 manifest readers stay in place for one release. A V1 document may still carry the scalar; a V2 document is rejected if it does.",
"rollback": "Restore the V1 writer in scripts/generate-build-manifest.ts and the scalar key in public/config.json; the V1 reader is still present.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-QUERY:*:*:removed",
"versionBump": "Query invalidation composition moves from the legacy flat query registry to the bounded many-to-many invalidation graph.",
"migration": "Installed feature contracts now contribute topics, namespace identities, edges, and separate wire versions; bootstrap validates and indexes those contributions before constructing coordinators.",
"compatibilityWindow": "Cross-context envelopes remain opaque topic/version pairs and release cache epochs isolate mixed releases; no query keys or cached values cross contexts.",
"rollback": "Restore the flat QUERY_REGISTRY composition and its coordinator adapter together with the prior governance entry.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-QUERY:$contract:allowedValues:contract-field-changed",
"versionBump": "Cross-context invalidation wire protocol starts at version 1.",
"migration": "Every installed query row declares invalidate-only; older tabs remain local-only.",
"compatibilityWindow": "Mixed releases are isolated by release cacheEpoch and never exchange query keys or values.",
"rollback": "Remove the coordinator composition and the two query registry fields.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-QUERY:$contract:breakingFields:contract-field-changed",
"versionBump": "Cross-context invalidation wire protocol starts at version 1.",
"migration": "Every installed query row declares its opaque topic and transport policy.",
"compatibilityWindow": "A release cacheEpoch rejects messages from a different deployed contract.",
"rollback": "Remove the coordinator composition and restore the prior query registry contract.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-QUERY:$contract:fieldTypes:contract-field-changed",
"versionBump": "Cross-context invalidation wire protocol starts at version 1.",
"migration": "The installed reference query row and all consumers were updated atomically.",
"compatibilityWindow": "Old clients do not consume the new fields; new clients validate them before boot.",
"rollback": "Restore the previous query registry field types and local-only invalidation.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-QUERY:$contract:requiredFields:contract-field-changed",
"versionBump": "Cross-context invalidation wire protocol starts at version 1.",
"migration": "Missing topics now fail registry validation instead of silently degrading at runtime.",
"compatibilityWindow": "Only a fully built release consumes its own installed registry snapshot.",
"rollback": "Remove the newly required fields and cross-context composition together.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-QUERY:$contract:uniqueFields:contract-field-changed",
"versionBump": "Cross-context invalidation wire protocol starts at version 1.",
"migration": "Existing query namespaces received unique registry-issued opaque topics.",
"compatibilityWindow": "Topics are scoped by release cacheEpoch, so mixed releases cannot collide.",
"rollback": "Drop invalidationTopic uniqueness after removing the transport consumer.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-RELEASE:apiContractVersion:compatibilityRole:field-changed",
"versionBump": "The release token registry adds contractSetDigest and demotes apiContractVersion to a legacy V1 scalar.",
"migration": "compareReleaseToRuntime no longer sources the scalar from Runtime Config; when neither side declares it there is nothing to compare and contractSet verification owns contract coherence.",
"compatibilityWindow": "A V1 manifest still supplies apiContractVersion and is still compared against a V1 config that declares one.",
"rollback": "Restore the previous compatibilityRole text and remove the contractSetDigest token together with the V2 manifest writer.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-STORAGE:$contract:allowedValues:contract-field-changed",
"versionBump": "Web Storage value codec contracts start at version 1.",
"migration": "Existing keys retain their physical schema version; values outside the selected codec are discarded.",
"compatibilityWindow": "Valid existing color-scheme and opaque-string records remain readable.",
"rollback": "Restore the previous registry contract; no physical key deletion is required.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-STORAGE:$contract:breakingFields:contract-field-changed",
"versionBump": "Web Storage value codec contracts start at version 1.",
"migration": "Each existing row received an explicit codec; executable migration was never consumed and is now forbidden.",
"compatibilityWindow": "Schema-versioned physical keys and the envelope shape remain unchanged.",
"rollback": "Remove valueCodec enforcement and restore the prior metadata declaration.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-STORAGE:$contract:fieldTypes:contract-field-changed",
"versionBump": "Web Storage value codec contracts start at version 1.",
"migration": "The dead function migration union was narrowed to the only implemented discard policy.",
"compatibilityWindow": "All installed definitions already used discard before this contract change.",
"rollback": "Restore the former type metadata without rewriting persisted records.",
"owner": "frontend-platform"
},
{
"changeId": "FE-REG-STORAGE:$contract:requiredFields:contract-field-changed",
"versionBump": "Web Storage value codec contracts start at version 1.",
"migration": "All installed storage rows now declare their closed value codec.",
"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-ROUTE:TECH_LOG_STUDIO_HOME:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"changeId": "FE-REG-API:CREATE_REFERENCE_RESOURCE:*:removed",
"versionBump": "Template sync ebea300..af3d8e6 leaves the template's reference-feature sample uninstalled (src/features/reference-feature/NOT_INSTALLED): the template now installs a feature only through feature-module.ts and context-routes.ts, which load the sample screens this product deleted in the TechLog UI migration.",
"migration": "Nothing in this product consumes these rows: no TechLog screen, gateway or query calls a reference-resource operation, reads its schemas or listens on its invalidation topic. They were composed only because the sample stayed installed without its screens.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; the rows leave the registries, the bundle and the contract set in one release.",
"rollback": "Revert the template sync commit (rollback ref backup/main-before-template-af3d8e6), or reinstall the sample with its presentation, feature-module.ts and context-routes.ts.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_DOCUMENTS:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"changeId": "FE-REG-API:GET_REFERENCE_RESOURCE:*:removed",
"versionBump": "Template sync ebea300..af3d8e6 leaves the template's reference-feature sample uninstalled (src/features/reference-feature/NOT_INSTALLED): the template now installs a feature only through feature-module.ts and context-routes.ts, which load the sample screens this product deleted in the TechLog UI migration.",
"migration": "Nothing in this product consumes these rows: no TechLog screen, gateway or query calls a reference-resource operation, reads its schemas or listens on its invalidation topic. They were composed only because the sample stayed installed without its screens.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; the rows leave the registries, the bundle and the contract set in one release.",
"rollback": "Revert the template sync commit (rollback ref backup/main-before-template-af3d8e6), or reinstall the sample with its presentation, feature-module.ts and context-routes.ts.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_DOCUMENT_NEW:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"changeId": "FE-REG-API:LIST_REFERENCE_RESOURCES:*:removed",
"versionBump": "Template sync ebea300..af3d8e6 leaves the template's reference-feature sample uninstalled (src/features/reference-feature/NOT_INSTALLED): the template now installs a feature only through feature-module.ts and context-routes.ts, which load the sample screens this product deleted in the TechLog UI migration.",
"migration": "Nothing in this product consumes these rows: no TechLog screen, gateway or query calls a reference-resource operation, reads its schemas or listens on its invalidation topic. They were composed only because the sample stayed installed without its screens.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; the rows leave the registries, the bundle and the contract set in one release.",
"rollback": "Revert the template sync commit (rollback ref backup/main-before-template-af3d8e6), or reinstall the sample with its presentation, feature-module.ts and context-routes.ts.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_DOCUMENT_EDIT:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"changeId": "FE-REG-QUERY-INVALIDATION:invalidation-graph:edges:allowed-value-removed",
"versionBump": "Template sync ebea300..af3d8e6 leaves the template's reference-feature sample uninstalled (src/features/reference-feature/NOT_INSTALLED): the template now installs a feature only through feature-module.ts and context-routes.ts, which load the sample screens this product deleted in the TechLog UI migration.",
"migration": "Nothing in this product consumes these rows: no TechLog screen, gateway or query calls a reference-resource operation, reads its schemas or listens on its invalidation topic. They were composed only because the sample stayed installed without its screens.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; the rows leave the registries, the bundle and the contract set in one release.",
"rollback": "Revert the template sync commit (rollback ref backup/main-before-template-af3d8e6), or reinstall the sample with its presentation, feature-module.ts and context-routes.ts.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_DOCUMENT_VALIDATION:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"changeId": "FE-REG-QUERY-INVALIDATION:invalidation-graph:namespaces:allowed-value-removed",
"versionBump": "Template sync ebea300..af3d8e6 leaves the template's reference-feature sample uninstalled (src/features/reference-feature/NOT_INSTALLED): the template now installs a feature only through feature-module.ts and context-routes.ts, which load the sample screens this product deleted in the TechLog UI migration.",
"migration": "Nothing in this product consumes these rows: no TechLog screen, gateway or query calls a reference-resource operation, reads its schemas or listens on its invalidation topic. They were composed only because the sample stayed installed without its screens.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; the rows leave the registries, the bundle and the contract set in one release.",
"rollback": "Revert the template sync commit (rollback ref backup/main-before-template-af3d8e6), or reinstall the sample with its presentation, feature-module.ts and context-routes.ts.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_DOCUMENT_PREVIEW:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"changeId": "FE-REG-QUERY-INVALIDATION:invalidation-graph:topics:allowed-value-removed",
"versionBump": "Template sync ebea300..af3d8e6 leaves the template's reference-feature sample uninstalled (src/features/reference-feature/NOT_INSTALLED): the template now installs a feature only through feature-module.ts and context-routes.ts, which load the sample screens this product deleted in the TechLog UI migration.",
"migration": "Nothing in this product consumes these rows: no TechLog screen, gateway or query calls a reference-resource operation, reads its schemas or listens on its invalidation topic. They were composed only because the sample stayed installed without its screens.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; the rows leave the registries, the bundle and the contract set in one release.",
"rollback": "Revert the template sync commit (rollback ref backup/main-before-template-af3d8e6), or reinstall the sample with its presentation, feature-module.ts and context-routes.ts.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_DOCUMENT_PUBLISH:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"changeId": "FE-REG-QUERY-INVALIDATION-TOPIC-VERSION:[\"qinv.01k10f7m3w9p6r2c8v5n4x\"]:*:removed",
"versionBump": "Template sync ebea300..af3d8e6 leaves the template's reference-feature sample uninstalled (src/features/reference-feature/NOT_INSTALLED): the template now installs a feature only through feature-module.ts and context-routes.ts, which load the sample screens this product deleted in the TechLog UI migration.",
"migration": "Nothing in this product consumes these rows: no TechLog screen, gateway or query calls a reference-resource operation, reads its schemas or listens on its invalidation topic. They were composed only because the sample stayed installed without its screens.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; the rows leave the registries, the bundle and the contract set in one release.",
"rollback": "Revert the template sync commit (rollback ref backup/main-before-template-af3d8e6), or reinstall the sample with its presentation, feature-module.ts and context-routes.ts.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_PUBLICATIONS:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"changeId": "FE-REG-SCHEMA:CreateReferenceResourceCommand:*:removed",
"versionBump": "Template sync ebea300..af3d8e6 leaves the template's reference-feature sample uninstalled (src/features/reference-feature/NOT_INSTALLED): the template now installs a feature only through feature-module.ts and context-routes.ts, which load the sample screens this product deleted in the TechLog UI migration.",
"migration": "Nothing in this product consumes these rows: no TechLog screen, gateway or query calls a reference-resource operation, reads its schemas or listens on its invalidation topic. They were composed only because the sample stayed installed without its screens.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; the rows leave the registries, the bundle and the contract set in one release.",
"rollback": "Revert the template sync commit (rollback ref backup/main-before-template-af3d8e6), or reinstall the sample with its presentation, feature-module.ts and context-routes.ts.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_PUBLICATION_PREVIEW:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"changeId": "FE-REG-SCHEMA:NoRequest:*:removed",
"versionBump": "Template sync ebea300..af3d8e6 leaves the template's reference-feature sample uninstalled (src/features/reference-feature/NOT_INSTALLED): the template now installs a feature only through feature-module.ts and context-routes.ts, which load the sample screens this product deleted in the TechLog UI migration.",
"migration": "Nothing in this product consumes these rows: no TechLog screen, gateway or query calls a reference-resource operation, reads its schemas or listens on its invalidation topic. They were composed only because the sample stayed installed without its screens.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; the rows leave the registries, the bundle and the contract set in one release.",
"rollback": "Revert the template sync commit (rollback ref backup/main-before-template-af3d8e6), or reinstall the sample with its presentation, feature-module.ts and context-routes.ts.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-ROUTE:TECH_LOG_STUDIO_NOT_FOUND:access:field-changed",
"versionBump": "Studio routes move from access \"public\" to \"session-required\". Every route was registered public, so the router's auth gate was a no-op and a production build served the Studio shell to signed-out visitors.",
"migration": "None for callers. The route ids, paths, params, and search schemas are unchanged; only the access classification moves, and the SPA resolves it from the route's own layoutGroup rather than a per-route literal.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; a signed-out visitor is redirected to the public shell instead of rendering Studio chrome.",
"rollback": "Roll back the atomic release to 93ce86e; the route contract derives access from layoutGroup in one expression, so the previous value returns with the release.",
"changeId": "FE-REG-SCHEMA:ReferenceResourceListPayload:*:removed",
"versionBump": "Template sync ebea300..af3d8e6 leaves the template's reference-feature sample uninstalled (src/features/reference-feature/NOT_INSTALLED): the template now installs a feature only through feature-module.ts and context-routes.ts, which load the sample screens this product deleted in the TechLog UI migration.",
"migration": "Nothing in this product consumes these rows: no TechLog screen, gateway or query calls a reference-resource operation, reads its schemas or listens on its invalidation topic. They were composed only because the sample stayed installed without its screens.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; the rows leave the registries, the bundle and the contract set in one release.",
"rollback": "Revert the template sync commit (rollback ref backup/main-before-template-af3d8e6), or reinstall the sample with its presentation, feature-module.ts and context-routes.ts.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-SCHEMA:ReferenceResourceListQuery:*:removed",
"versionBump": "Template sync ebea300..af3d8e6 leaves the template's reference-feature sample uninstalled (src/features/reference-feature/NOT_INSTALLED): the template now installs a feature only through feature-module.ts and context-routes.ts, which load the sample screens this product deleted in the TechLog UI migration.",
"migration": "Nothing in this product consumes these rows: no TechLog screen, gateway or query calls a reference-resource operation, reads its schemas or listens on its invalidation topic. They were composed only because the sample stayed installed without its screens.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; the rows leave the registries, the bundle and the contract set in one release.",
"rollback": "Revert the template sync commit (rollback ref backup/main-before-template-af3d8e6), or reinstall the sample with its presentation, feature-module.ts and context-routes.ts.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-SCHEMA:ReferenceResourceParams:*:removed",
"versionBump": "Template sync ebea300..af3d8e6 leaves the template's reference-feature sample uninstalled (src/features/reference-feature/NOT_INSTALLED): the template now installs a feature only through feature-module.ts and context-routes.ts, which load the sample screens this product deleted in the TechLog UI migration.",
"migration": "Nothing in this product consumes these rows: no TechLog screen, gateway or query calls a reference-resource operation, reads its schemas or listens on its invalidation topic. They were composed only because the sample stayed installed without its screens.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; the rows leave the registries, the bundle and the contract set in one release.",
"rollback": "Revert the template sync commit (rollback ref backup/main-before-template-af3d8e6), or reinstall the sample with its presentation, feature-module.ts and context-routes.ts.",
"owner": "tech-log-frontend"
},
{
"changeId": "FE-REG-SCHEMA:ReferenceResourcePayload:*:removed",
"versionBump": "Template sync ebea300..af3d8e6 leaves the template's reference-feature sample uninstalled (src/features/reference-feature/NOT_INSTALLED): the template now installs a feature only through feature-module.ts and context-routes.ts, which load the sample screens this product deleted in the TechLog UI migration.",
"migration": "Nothing in this product consumes these rows: no TechLog screen, gateway or query calls a reference-resource operation, reads its schemas or listens on its invalidation topic. They were composed only because the sample stayed installed without its screens.",
"compatibilityWindow": "The deployed release consumes only its same-release registry snapshot; the rows leave the registries, the bundle and the contract set in one release.",
"rollback": "Revert the template sync commit (rollback ref backup/main-before-template-af3d8e6), or reinstall the sample with its presentation, feature-module.ts and context-routes.ts.",
"owner": "tech-log-frontend"
}
]
+156 -48
View File
@@ -40,10 +40,20 @@
"navigationLabel": "string|null",
"navigationOrder": "integer|null"
},
"uniqueFields": ["routeId", "path", "chunkId"],
"uniqueFields": [
"routeId",
"path",
"chunkId"
],
"allowedValues": {
"access": ["public", "session-required"],
"layoutGroup": ["PUBLIC", "STUDIO"],
"access": [
"public",
"session-required"
],
"layoutGroup": [
"PUBLIC",
"STUDIO"
],
"paramsSchema": [
null,
"NotFoundSplat",
@@ -130,7 +140,10 @@
"paramsCodec": "string",
"searchCodec": "string"
},
"uniqueFields": ["routeId", "moduleId"],
"uniqueFields": [
"routeId",
"moduleId"
],
"references": [
{
"field": "routeId",
@@ -193,13 +206,35 @@
"responseSchema": "string",
"owner": "string"
},
"uniqueFields": ["operationId"],
"uniqueFields": [
"operationId"
],
"allowedValues": {
"method": ["GET", "POST", "PUT", "PATCH", "DELETE"],
"auth": ["none", "external-session"],
"idempotency": ["safe", "keyed", "none"],
"retry": ["runtime", "never"],
"requestSource": ["none", "search", "body"]
"method": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
],
"auth": [
"none",
"external-session"
],
"idempotency": [
"safe",
"keyed",
"none"
],
"retry": [
"runtime",
"never"
],
"requestSource": [
"none",
"search",
"body"
]
},
"references": [
{
@@ -215,8 +250,8 @@
],
"consumerIdentityField": "operationId",
"consumerDirectories": [
"src/features/reference-feature/adapters",
"src/features/reference-feature/application"
"src/features/*/adapters",
"src/features/*/application"
],
"breakingFields": [
"method",
@@ -235,14 +270,21 @@
"exportName": "SCHEMA_REGISTRY",
"owner": "feature-frontend-contract-schema-registry",
"keyField": "schemaId",
"requiredFields": ["schemaId", "boundary", "owner", "runtime"],
"requiredFields": [
"schemaId",
"boundary",
"owner",
"runtime"
],
"fieldTypes": {
"schemaId": "string",
"boundary": "string",
"owner": "string",
"runtime": "string"
},
"uniqueFields": ["schemaId"],
"uniqueFields": [
"schemaId"
],
"allowedValues": {
"boundary": [
"route-params",
@@ -251,22 +293,34 @@
"api-request",
"api-response"
],
"runtime": ["zod"]
"runtime": [
"zod"
]
},
"consumerIdentityField": "schemaId",
"consumerDirectories": [
"src/presentation/routes",
"src/features/tech-log/presentation",
"src/features/reference-feature/contracts"
"src/features/*/presentation",
"src/features/*/contracts"
],
"breakingFields": ["schemaId", "boundary", "runtime"]
"breakingFields": [
"schemaId",
"boundary",
"runtime"
]
},
{
"registryId": "FE-REG-ENV",
"path": "src/contracts/env.ts",
"exportName": "ENV_REGISTRY",
"owner": "feature-frontend-env-runtime-config-contract",
"requiredFields": ["phase", "classification", "required", "defaultValue"],
"requiredFields": [
"phase",
"classification",
"required",
"defaultValue"
],
"fieldTypes": {
"phase": "string",
"classification": "string",
@@ -274,7 +328,10 @@
"defaultValue": "string|integer|boolean|null"
},
"allowedValues": {
"phase": ["build", "runtime"],
"phase": [
"build",
"runtime"
],
"classification": [
"public",
"public-sensitive",
@@ -292,7 +349,11 @@
"token": "getBuildConfig"
}
],
"breakingFields": ["phase", "classification", "required"]
"breakingFields": [
"phase",
"classification",
"required"
]
},
{
"registryId": "FE-REG-STORAGE",
@@ -322,7 +383,10 @@
"migration": "string",
"quotaFallback": "string"
},
"uniqueFields": ["logicalName", "physicalKey"],
"uniqueFields": [
"logicalName",
"physicalKey"
],
"allowedValues": {
"backend": [
"memory",
@@ -341,12 +405,24 @@
"opaque-string-v1",
"none"
],
"migration": ["discard"],
"quotaFallback": ["memory", "no-persist", "feature-disable"]
"migration": [
"discard"
],
"quotaFallback": [
"memory",
"no-persist",
"feature-disable"
]
},
"consumerIdentityField": "logicalName",
"consumerDirectories": ["src", "tests"],
"orphanExemptRows": ["QUERY_PERSISTENCE", "AUTH_TOKEN"],
"consumerDirectories": [
"src",
"tests"
],
"orphanExemptRows": [
"QUERY_PERSISTENCE",
"AUTH_TOKEN"
],
"breakingFields": [
"logicalName",
"physicalKey",
@@ -366,24 +442,19 @@
"requiredFields": [
"kind",
"defaultRetryable",
"severity",
"userMessageKey",
"action",
"telemetryEvent",
"redaction"
"action"
],
"fieldTypes": {
"kind": "string",
"defaultRetryable": "boolean",
"severity": "string",
"userMessageKey": "string",
"action": "string",
"telemetryEvent": "string",
"redaction": "array"
"action": "string"
},
"uniqueFields": ["kind"],
"uniqueFields": [
"kind"
],
"allowedValues": {
"severity": ["info", "warning", "error"],
"action": [
"retry",
"reauth",
@@ -399,7 +470,11 @@
"token": "failure("
}
],
"breakingFields": ["kind", "userMessageKey", "action", "telemetryEvent"]
"breakingFields": [
"kind",
"userMessageKey",
"action"
]
},
{
"registryId": "FE-REG-QUERY-INVALIDATION",
@@ -432,8 +507,13 @@
"snapshotProjection": {
"singletonRowKey": "invalidation-graph",
"canonicalArrayKeyFields": {
"topics": ["$value"],
"namespaces": ["namespaceId", "namespaceVersion"],
"topics": [
"$value"
],
"namespaces": [
"namespaceId",
"namespaceVersion"
],
"edges": [
"topicId",
"namespace.namespaceId",
@@ -447,27 +527,41 @@
"token": "indexInvalidationRegistry(INVALIDATION_REGISTRY)"
}
],
"breakingFields": ["topics", "namespaces", "edges"]
"breakingFields": [
"topics",
"namespaces",
"edges"
]
},
{
"registryId": "FE-REG-QUERY-INVALIDATION-TOPIC-VERSION",
"path": "src/features/installed-feature-contracts.ts",
"exportName": "INVALIDATION_TOPIC_VERSIONS",
"rowKeyFields": ["topicId"],
"rowKeyFields": [
"topicId"
],
"owner": "feature-frontend-server-state-caching-contract",
"requiredFields": ["topicId", "topicVersion"],
"requiredFields": [
"topicId",
"topicVersion"
],
"fieldTypes": {
"topicId": "string",
"topicVersion": "integer"
},
"uniqueFields": ["topicId"],
"uniqueFields": [
"topicId"
],
"consumers": [
{
"path": "src/bootstrap/runtime-adapters.ts",
"token": "indexInvalidationTopicVersions("
}
],
"breakingFields": ["topicId", "topicVersion"]
"breakingFields": [
"topicId",
"topicVersion"
]
},
{
"registryId": "FE-REG-TELEMETRY",
@@ -493,9 +587,13 @@
"sampling": "string",
"delivery": "string"
},
"uniqueFields": ["eventName"],
"uniqueFields": [
"eventName"
],
"allowedValues": {
"delivery": ["best-effort"]
"delivery": [
"best-effort"
]
},
"consumers": [
{
@@ -516,20 +614,30 @@
"exportName": "RELEASE_TOKEN_REGISTRY",
"owner": "feature-frontend-release-cache-rollback-contract",
"keyField": "token",
"requiredFields": ["token", "source", "compatibilityRole"],
"requiredFields": [
"token",
"source",
"compatibilityRole"
],
"fieldTypes": {
"token": "string",
"source": "string",
"compatibilityRole": "string"
},
"uniqueFields": ["token"],
"uniqueFields": [
"token"
],
"consumers": [
{
"path": "src/bootstrap/load-release-manifest.ts",
"token": "assetManifestHash"
}
],
"breakingFields": ["token", "source", "compatibilityRole"]
"breakingFields": [
"token",
"source",
"compatibilityRole"
]
}
]
}
-3
View File
@@ -27,9 +27,6 @@
},
"sourceMap": {
"public": false
},
"serviceWorker": {
"enabled": false
}
}
}
@@ -67,7 +67,7 @@
"lifecycleMethods": ["close-or-dispose", "unsubscribe", "cancel-via-AbortSignal", "bounded-poll-lease", "revoke-push-association"],
"owner": "project-owner-required",
"securityPrivacy": ["Validate every event envelope and closed transport frame before application effects.", "Bind stream state to the current opaque scope generation and advance checkpoints only after committed effects or authoritative recovery.", "Use fixed same-origin endpoints and an exact WebSocket subprotocol; never place credentials, cursors, subscription material or scope bindings in URLs or telemetry.", "Treat Web Push as a notification hint, fence registration and revocation with one durable compare-and-swap control record, and allow only registry-owned notification and route intents.", "Keep every queue, parser, reconnect, poll, notification and storage operation bounded and abortable."],
"bundleBudgetGzipBytes": 40000,
"bundleBudgetGzipBytes": 40900,
"fallback": "Bounded polling or explicitly stale UI.",
"removal": ["Disable admission and close active readers, sockets, poll leases and worker handlers.", "Revoke and purge only the owned Web Push association and notification state.", "Remove composition, registries, adapters and any selected vendor dependency.", "Run realtime boundary, runtime-removal and production-bundle gates."],
"serverStatePolicy": "query-cache-owned"
@@ -109,7 +109,7 @@
"lifecycleMethods": ["close", "cancel-via-AbortSignal", "enforce-bounded-lifecycle-batch", "prune-expired-receipts", "reconcile", "enforcePolicies-with-composition-authority"],
"owner": "project-owner-required",
"securityPrivacy": ["Classify every persisted field and binary namespace.", "Encrypting in the same client is not a credential protection boundary.", "Keep database schema and record codec versions separate.", "Derive the physical IndexedDB name only from registry-issued authority, namespace and partition tokens; readable namespace, business and account IDs are forbidden.", "Persist and revalidate an immutable scope plus full BrowserStoragePolicy binding during upgrade, post-open and maintenance; missing or mismatched existing bindings fail closed.", "Use the actual IndexedDB wire split: StoredRecord contains only key, codecVersion, revision and payload; writtenAtEpochMs, synchronization, measuredBytes and eligibleAtEpochMs belong to the retention sidecar, while idempotency receipts and governance binding/budget use separate stores.", "Include every store registered in lifecycleMetadataStores in bounded full-partition purge while retaining immutable governance identity.", "Measure conservative logical bytes through the codec and atomically enforce dataset usedBytes plus receiptCount with record, lifecycle and migration writes.", "Enforce TTL before sweep visibility, delete UNTIL_SYNCED only after explicit confirmation, and require a composition-authorized short-lived proof for every deleting IndexedDB lifecycle batch.", "Bound idempotency receipt retention to 31 days and configured count to the implementation ceiling of 1000000; bound migration to old-writer-drained batches no larger than 500 rows or 30000ms.", "Bind OPFS readable and physical scopes in both directions and use only /ca-frontend-opfs-v1/authorities/<authorityToken>/<namespaceToken>/<partitionToken>/ for physical dataset layout.", "For OPFS LOGOUT, UNTIL_SYNCED and ACCOUNT_DELETION maintenance, composition must provide both requestMaintenanceAuthority and consumeMaintenanceAuthority; issue a fresh proof bound to the exact frozen reason, scope and policy for at most five minutes, then atomically consume it to reject replay.", "Never expose an OPFS authority proof through the application request, persistence, diagnostics or telemetry.", "Never place user file names or identifiers in OPFS paths or diagnostics."],
"bundleBudgetGzipBytes": 36000,
"bundleBudgetGzipBytes": 36900,
"fallback": "Read-only or online-only query path; OPFS may degrade to a size-capped IndexedDB Blob only when the product policy approves it.",
"removal": ["Stop writes and background migration.", "Reconcile or export unsynced data, then purge only governance-bound owned partitions and OPFS namespaces through authorized bounded lifecycle operations.", "Close all database, channel, worker and file handles.", "Remove repository composition and dependency."],
"serverStatePolicy": "reference-or-command-only"
@@ -192,10 +192,10 @@
"port": "FilePickerPort / FileContentPort / TransientPreviewPort / DownloadDeliveryPort / PresignedDownloadSourcePort / PresignedUploadPartPort / ResumableUploadPort / ImageCdnPresentationPort",
"fake": "Memory file/preview/download adapters plus injected deterministic capability, upload-control-plane, part-executor and image-verifier test doubles",
"failureKinds": ["dismissed", "permission-denied", "count-or-size-rejection", "type-or-signature-rejection", "file-changed", "abort", "integrity-failure", "partial-save", "expired-or-revoked-capability", "part-or-session-conflict", "checkpoint-conflict", "quarantined", "image-policy-rejection"],
"lifecycleMethods": ["release-file-ref", "release-or-dispose-preview-leases", "cancel-via-AbortSignal", "reconcile-or-explicitly-abort-upload", "close-checkpoint-store", "dispose-capability-and-image-runtime"],
"lifecycleMethods": ["release-file-ref", "release-or-dispose-preview-leases", "cancel-via-AbortSignal", "reconcile-or-explicitly-abort-upload", "close-checkpoint-store", "dispose-capability-and-image-runtime", "dispose-browser-file-runtime-on-logout-or-account-switch"],
"owner": "project-owner-required",
"securityPrivacy": ["Treat file name, extension, MIME and lastModified as untrusted metadata.", "Resolve only exact composition-issued file and image policy object identities; callers cannot raise byte, candidate, pixel, quality, format, lifetime or origin ceilings.", "Use opaque file references and verification receipts bound to an inspected immutable file snapshot and the exact registered profile; reject replay through another profile even when an inspection rule ID matches.", "Treat presigned URLs as bearer capabilities; bind exact method, resource or upload part, offset, length, media type, checksum, origin, path, query, headers and expiry in an in-memory identity vault.", "Use credentials omit, redirect error, no-referrer and no-store for direct data-plane fetch; never persist or observe URL, query, signed header, capability, file name or raw backend message, and never emit digest, raw ETag or receipt values to diagnostics or telemetry.", "A strict account-partitioned upload checkpoint may persist only the protocol-defined SHA-256 file fingerprint, per-part checksum and bounded opaque non-authorizing part receipt token required for server reconciliation; no bearer token or raw signed capability is allowed.", "Persist only strict non-authorizing upload checkpoints and reconcile them with server-authoritative status and re-hashed local parts before completion.", "Require a synchronous server-issued browser-managed download capability whose receipt exactly equals the caller's branded capability receipt and whose resource, media type, safe extension, maximum bytes, optional digest and expiry all match before handoff.", "Expose File, OPFS, Cache and transfer byte streams only as chunk-level closed Results; stop after the first failure, cancel native readers and never throw a raw native exception across the port.", "Accept Image CDN assets only through immutable allowlisted or signature-verified descriptors and registered preset identities; reject active formats, arbitrary transforms, pixel/decode-budget overflow and unsafe cache policy.", "Upload completion remains QUARANTINED until backend scan and promotion; client capability checks are not an authorization boundary.", "Active content preview requires isolation or download-only treatment."],
"bundleBudgetGzipBytes": 54600,
"bundleBudgetGzipBytes": 55700,
"fallback": "Accessible native file input, same-origin authorized server upload/download and a single bounded server-selected image rendition; generated artifacts above the buffer budget move to server-side generation.",
"removal": ["Stop new capability and upload-session issuance, then cancel active reads and transfers.", "Reconcile or explicitly abort active multipart sessions and let backend TTL cleanup remove ambiguous orphans.", "Remove non-secret checkpoints according to account and retention policy.", "Release file references, revoke preview object-URL leases and dispose file, capability and image runtimes.", "Remove transfer/image feature facades and composition, then prove browser-transfer sources are absent from the production module inventory."],
"serverStatePolicy": "query-cache-metadata-only"
+1 -3
View File
@@ -15,7 +15,5 @@
},
"TECH_LOG_STUDIO_SOURCE": "HTTP",
"TECH_LOG_PUBLIC_SOURCE": "HTTP",
"FEATURE_OVERRIDES": {
"reference-feature": "DEFAULT"
}
"FEATURE_OVERRIDES": {}
}
+1 -3
View File
@@ -15,7 +15,5 @@
},
"TECH_LOG_STUDIO_SOURCE": "MOCK",
"TECH_LOG_PUBLIC_SOURCE": "MOCK",
"FEATURE_OVERRIDES": {
"reference-feature": "DEFAULT"
}
"FEATURE_OVERRIDES": {}
}
+1 -3
View File
@@ -15,7 +15,5 @@
},
"TECH_LOG_STUDIO_SOURCE": "HTTP",
"TECH_LOG_PUBLIC_SOURCE": "HTTP",
"FEATURE_OVERRIDES": {
"reference-feature": "DEFAULT"
}
"FEATURE_OVERRIDES": {}
}
+1 -3
View File
@@ -16,7 +16,5 @@
},
"TECH_LOG_STUDIO_SOURCE": "HTTP",
"TECH_LOG_PUBLIC_SOURCE": "HTTP",
"FEATURE_OVERRIDES": {
"reference-feature": "DEFAULT"
}
"FEATURE_OVERRIDES": {}
}
+135
View File
@@ -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"
}
}
+41
View File
@@ -0,0 +1,41 @@
{
"schemaVersion": 1,
"baseline": "config/scale/feature-shape-growth.json",
"ceilings": {
"contextMaxFeatures": 200,
"appMaxContexts": 20
},
"summary": "The ceilings bound the count; they are not a verified capacity. The practical limit of one app is the initial JavaScript budget, then typecheck memory. 400 features were not measured (D-18 makes it optional).",
"axes": [
{
"axis": "Typecheck of one app",
"verified": "Linear, about 115k instantiations and 37 MB of tsc memory per feature, up to 100 features",
"condition": "Reference-shaped features, tsconfig.app.json, the host recorded in the baseline",
"notVerified": "200 features (one full context) and beyond; 4,000 (20 x 200) would need on the order of 150 GB by the same slope"
},
{
"axis": "Production build",
"verified": "Completes at 100 features in seconds",
"condition": "Same",
"notVerified": "Beyond 100"
},
{
"axis": "Initial JavaScript",
"verified": "Grows by about 2.9 KB gzip and one file per feature: every installed feature's contracts and module load at boot",
"condition": "Same",
"notVerified": "The initial budget (204,800 B, config/performance/budgets.json) is exceeded after a few more reference-shaped features, far below the context ceiling"
},
{
"axis": "Lazy JavaScript",
"verified": "About 6.8 KB gzip and six files per feature, every file far below the 120 KiB lazy-chunk budget",
"condition": "Same",
"notVerified": "Download cost of many lazy files"
},
{
"axis": "Routes",
"verified": "4 per feature, composed without conflict",
"condition": "Same",
"notVerified": "Router matching cost at runtime"
}
]
}
+210
View File
@@ -0,0 +1,210 @@
{
"schemaVersion": 1,
"measuredAt": "2026-09-27T04:03:00.821Z",
"command": "node scripts/scale/measure-feature-shape-growth.ts --sizes=0,25,100 --repeats=2",
"environment": {
"node": "24.14.0",
"platform": "linux",
"arch": "x64",
"cpuModel": "Intel(R) Core(TM) i5-10400F CPU @ 2.90GHz",
"logicalCpus": 12,
"availableParallelism": 12,
"typescript": "Version 7.0.2",
"vite": "vite/8.1.5 linux-x64 node-v24.14.0"
},
"sourceFeature": "src/features/reference-feature",
"runs": [
{
"repeat": 1,
"addedFeatures": 0,
"routes": 10,
"tsc": {
"passed": true,
"firstError": null,
"files": 840,
"types": 284678,
"symbols": 802946,
"instantiations": 712089,
"memoryKb": 520454,
"wallMs": 3408
},
"build": {
"wallMs": 1208,
"initialJavascriptFiles": 13,
"initialJavascriptGzipBytes": 200001,
"lazyJavascriptFiles": 14,
"lazyJavascriptGzipBytes": 24938
},
"loadBefore": [
25.05,
16.88,
7.75
],
"loadAfter": [
26.4,
17.3,
7.93
]
},
{
"repeat": 2,
"addedFeatures": 0,
"routes": 10,
"tsc": {
"passed": true,
"firstError": null,
"files": 840,
"types": 284678,
"symbols": 802946,
"instantiations": 712089,
"memoryKb": 520395,
"wallMs": 3930
},
"build": {
"wallMs": 1526,
"initialJavascriptFiles": 13,
"initialJavascriptGzipBytes": 200001,
"lazyJavascriptFiles": 14,
"lazyJavascriptGzipBytes": 24938
},
"loadBefore": [
26.4,
17.3,
7.93
],
"loadAfter": [
27.65,
17.71,
8.12
]
},
{
"repeat": 1,
"addedFeatures": 25,
"routes": 110,
"tsc": {
"passed": true,
"firstError": null,
"files": 1366,
"types": 1055723,
"symbols": 2831441,
"instantiations": 3579093,
"memoryKb": 1422337,
"wallMs": 8121
},
"build": {
"wallMs": 1676,
"initialJavascriptFiles": 39,
"initialJavascriptGzipBytes": 274493,
"lazyJavascriptFiles": 165,
"lazyJavascriptGzipBytes": 171638
},
"loadBefore": [
27.65,
17.71,
8.12
],
"loadAfter": [
27.17,
17.93,
8.29
]
},
{
"repeat": 2,
"addedFeatures": 25,
"routes": 110,
"tsc": {
"passed": true,
"firstError": null,
"files": 1366,
"types": 1055723,
"symbols": 2831441,
"instantiations": 3579093,
"memoryKb": 1422431,
"wallMs": 8714
},
"build": {
"wallMs": 2140,
"initialJavascriptFiles": 39,
"initialJavascriptGzipBytes": 274493,
"lazyJavascriptFiles": 165,
"lazyJavascriptGzipBytes": 171638
},
"loadBefore": [
27.17,
17.93,
8.29
],
"loadAfter": [
27.55,
18.46,
8.62
]
},
{
"repeat": 1,
"addedFeatures": 100,
"routes": 410,
"tsc": {
"passed": true,
"firstError": null,
"files": 2941,
"types": 3349868,
"symbols": 8940533,
"instantiations": 12157304,
"memoryKb": 4195900,
"wallMs": 31315
},
"build": {
"wallMs": 6010,
"initialJavascriptFiles": 114,
"initialJavascriptGzipBytes": 490658,
"lazyJavascriptFiles": 615,
"lazyJavascriptGzipBytes": 704938
},
"loadBefore": [
27.43,
18.59,
8.71
],
"loadAfter": [
29.72,
20.12,
9.64
]
},
{
"repeat": 2,
"addedFeatures": 100,
"routes": 410,
"tsc": {
"passed": true,
"firstError": null,
"files": 2941,
"types": 3349868,
"symbols": 8940533,
"instantiations": 12157304,
"memoryKb": 4195704,
"wallMs": 43234
},
"build": {
"wallMs": 3702,
"initialJavascriptFiles": 114,
"initialJavascriptGzipBytes": 490658,
"lazyJavascriptFiles": 615,
"lazyJavascriptGzipBytes": 704938
},
"loadBefore": [
29.72,
20.12,
9.64
],
"loadAfter": [
35.75,
22.97,
11.09
]
}
]
}
@@ -1,6 +1,6 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "ART-FE-RUNBOOK-DRILL@1",
"$id": "ART-FE-RUNBOOK-DRILL@2",
"type": "object",
"required": [
"schemaVersion",
@@ -14,29 +14,39 @@
"recoveryAssertions",
"negativeFixtureFailedAsExpected",
"windowObservedBucket",
"passed"
"providerVerificationRequired",
"result"
],
"$defs": {
"verdict": { "enum": ["PASS", "FAIL", "UNVERIFIED"] }
},
"properties": {
"schemaVersion": { "const": 1 },
"schemaVersion": { "const": 2 },
"runbookId": { "pattern": "^FE-RB-00[1-5]$" },
"releaseId": { "type": "string", "minLength": 1 },
"drillTimestamp": { "type": "string", "format": "date-time" },
"triggerInjected": { "type": "string" },
"triggerAsserted": { "type": "boolean" },
"containmentAsserted": { "type": "boolean" },
"escalationPathAsserted": { "type": "boolean" },
"triggerAsserted": { "$ref": "#/$defs/verdict" },
"containmentAsserted": { "$ref": "#/$defs/verdict" },
"escalationPathAsserted": { "$ref": "#/$defs/verdict" },
"recoveryAssertions": {
"type": "array",
"minItems": 4,
"items": {
"type": "object",
"required": ["assertion", "evidence", "passed"]
"required": ["assertion", "evidence", "result"],
"properties": {
"assertion": { "type": "string", "minLength": 1 },
"evidence": { "type": "string", "minLength": 1 },
"result": { "$ref": "#/$defs/verdict" }
},
"additionalProperties": false
}
},
"negativeFixtureFailedAsExpected": { "type": "boolean" },
"negativeFixtureFailedAsExpected": { "$ref": "#/$defs/verdict" },
"windowObservedBucket": { "type": "string" },
"providerVerificationRequired": { "type": "boolean" },
"passed": { "type": "boolean" }
"result": { "$ref": "#/$defs/verdict" }
},
"additionalProperties": false
}
+34 -23
View File
@@ -119,26 +119,6 @@
"branches": 75
}
},
{
"path": "src/application/policies/performance-budgets.ts",
"owner": "application-policy",
"minimum": {
"lines": 80,
"statements": 80,
"functions": 80,
"branches": 40
}
},
{
"path": "src/application/policies/promotion-readiness.ts",
"owner": "release-runtime",
"minimum": {
"lines": 95,
"statements": 95,
"functions": 95,
"branches": 95
}
},
{
"path": "src/application/use-cases/decide-chunk-recovery.ts",
"owner": "application-runtime",
@@ -198,6 +178,36 @@
"functions": 90,
"branches": 80
}
},
{
"path": "src/adapters/http/http-contract-bridge.ts",
"owner": "http-runtime",
"minimum": {
"lines": 85,
"statements": 79,
"functions": 100,
"branches": 73
}
},
{
"path": "src/adapters/http/http-retry-lifecycle.ts",
"owner": "http-runtime",
"minimum": {
"lines": 100,
"statements": 100,
"functions": 100,
"branches": 100
}
},
{
"path": "src/adapters/storage/indexeddb/indexeddb-runtime.ts",
"owner": "storage-runtime",
"minimum": {
"lines": 79,
"statements": 76,
"functions": 73,
"branches": 72
}
}
],
"highRiskPaths": [
@@ -212,14 +222,15 @@
"src/adapters/telemetry/best-effort-telemetry.ts",
"src/application/create-application.ts",
"src/contracts/compatibility.ts",
"src/application/policies/performance-budgets.ts",
"src/application/policies/promotion-readiness.ts",
"src/application/use-cases/decide-chunk-recovery.ts",
"src/bootstrap/load-release-manifest.ts",
"src/bootstrap/read-bounded-boot-json.ts",
"src/contracts/diagnostics.ts",
"src/features/reference-feature/adapters/reference-http-gateway.ts",
"src/presentation/adapters/query/application-query.ts"
"src/presentation/adapters/query/application-query.ts",
"src/adapters/http/http-contract-bridge.ts",
"src/adapters/http/http-retry-lifecycle.ts",
"src/adapters/storage/indexeddb/indexeddb-runtime.ts"
],
"waivers": []
}
+71
View File
@@ -0,0 +1,71 @@
# 문서 색인
`docs/`의 문서를 세 묶음으로 나눈다.
```text
1. 현재 계약 지금 코드가 지키는 규칙. 게이트가 검사한다
2. 목표 설계 앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
3. 작업 이력 리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다
```
문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는
문서 안의 상태 값(`COMPOSED`, `AVAILABLE_NOT_COMPOSED`, `DESIGNED_NOT_IMPLEMENTED` 등)으로
확인한다. 상태 값의 뜻은 `README.md`의 "Support scope" 절에 있다.
README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.
## 1. 현재 계약
처음 읽을 입구 문서 6개다.
| 문서 | 정하는 것 |
|---|---|
| [`README.md`](../README.md) | 시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영 |
| [`architecture/frontend-application-foundation.md`](architecture/frontend-application-foundation.md) | 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계 |
| [`architecture/layers.md`](architecture/layers.md), [`architecture/overview.md`](architecture/overview.md) | 계층과 import 방향. `check:architecture`가 검사한다 |
| [`architecture/starter-experience.md`](architecture/starter-experience.md) | 기본 라우트, 인증 모드, 기능 추가·제거 절차 |
| [`architecture/optional-adapter-recipes.md`](architecture/optional-adapter-recipes.md) | 선택 기능(recipe)을 넣고 빼는 절차 |
| [`operations/ci-quality-gates.md`](operations/ci-quality-gates.md), [`testing/taxonomy.md`](testing/taxonomy.md) | 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선 |
입구 문서가 가리키는 세부 규칙:
- 계약 소유와 호환성: [`architecture/contract-ownership.md`](architecture/contract-ownership.md), [`contracts/compatibility.md`](contracts/compatibility.md)
- 정적 배포와 런타임 설정: [`architecture/static-delivery.md`](architecture/static-delivery.md)
- 기능 개발자가 알아야 하는 양: [`architecture/capability-consumer-experience.md`](architecture/capability-consumer-experience.md)
- 운영·복구: [`operations/`](operations/), [`runbooks/`](runbooks/)
- 보안과 공급망: [`security/browser-boundary.md`](security/browser-boundary.md), [`security/supply-chain.md`](security/supply-chain.md)
- 디자인 토큰과 수동 접근성 검토: [`styling/design-tokens.md`](styling/design-tokens.md), [`accessibility/manual-checklist.md`](accessibility/manual-checklist.md)
- 버전별 변경: 템플릿 저장소의 `CHANGELOG.md`. 이 저장소가 받은 템플릿 변경은 [`operations/template-sync-*.md`](operations/)에 동기화마다 적는다
게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.
| 파일 | 읽는 명령 |
|---|---|
| `architecture/review-ledger.json`, `architecture/review-evidence.md`, `accessibility/manual-checklist.md` | `verify:documentation` (FE-GATE-017) |
| `reviews/adapters/INVENTORY.md` | `check:adapter-inventory` (FE-GATE-010) |
| `operations/adapter-remediation-ledger.md`, `operations/adapter-remediation-dispositions.json` | `check:remediation-ledger` (게이트 밖. 이유는 `config/ci/ungated-scripts.json`) |
## 2. 목표 설계
설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.
- 런타임 capability 결정의 정본: [`architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md`](architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)
- 상태 원장: [`architecture/browser-data-capability-completion-ledger.md`](architecture/browser-data-capability-completion-ledger.md)
- 전체 검토와 로드맵: [`architecture/frontend-platform-capability-review.md`](architecture/frontend-platform-capability-review.md), [`architecture/frontend-platform-implementation-roadmap.md`](architecture/frontend-platform-implementation-roadmap.md)
- 포트·경계·데이터 흐름: [`architecture/frontend-ports-adapters-and-boundaries.md`](architecture/frontend-ports-adapters-and-boundaries.md), [`architecture/typescript-state-and-data-flow.md`](architecture/typescript-state-and-data-flow.md), [`architecture/routing-pages-and-patterns.md`](architecture/routing-pages-and-patterns.md)
- API와 서버 상태: [`architecture/api-contract-schema-mapper-and-server-state.md`](architecture/api-contract-schema-mapper-and-server-state.md), [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md), [`architecture/protobuf-browser-transport-and-rest-gateway.md`](architecture/protobuf-browser-transport-and-rest-gateway.md)
- 브라우저 데이터: [`architecture/client-cache-and-storage.md`](architecture/client-cache-and-storage.md), [`architecture/browser-file-and-origin-storage.md`](architecture/browser-file-and-origin-storage.md), [`architecture/presigned-transfer-and-image-cdn.md`](architecture/presigned-transfer-and-image-cdn.md), [`architecture/server-file-capability-infrastructure.md`](architecture/server-file-capability-infrastructure.md)
- 실시간: [`architecture/realtime-events-web-push-and-bounded-polling.md`](architecture/realtime-events-web-push-and-bounded-polling.md)
- 디자인 시스템과 테스트 전략: [`styling/design-system-platform.md`](styling/design-system-platform.md), [`testing/frontend-platform-testing-strategy.md`](testing/frontend-platform-testing-strategy.md)
- 결정 기록(ADR): [`architecture/decisions/`](architecture/decisions/) `VD-*.md`
## 3. 작업 이력·리뷰
템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다.
복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 `README.md`의
"Files you can delete after copying" 절에 있다.
| 경로 | 내용 |
|---|---|
| [`superpowers/`](superpowers/) | 과거 작업 계획과 스펙 |
| [`reviews/`](reviews/) | 리뷰 결과. `reviews/adapters/INVENTORY.md`만 게이트가 읽는다 |
+6
View File
@@ -18,6 +18,12 @@ fields, pending verdicts, and mismatched release IDs. The scope is:
`TECH_LOG_STUDIO_NOT_FOUND`, `TECH_LOG_STUDIO_PUBLICATIONS`,
`TECH_LOG_STUDIO_PUBLICATION_PREVIEW`, `TECH_LOG_TOPIC`.
The signed review is the release gate FE-GATE-028 (`review:a11y-manual`), so
it is required once per release candidate, not on every merge. The merge gate
FE-GATE-009 runs `review:a11y-manual -- --format-only`: each record must keep
the fields below with `pending`, `pass` or `not-applicable (<reason>)` verdicts,
and a record marked `reviewed` must be complete.
This list is not maintained by hand: `verify:documentation` compares it against
the installed route registry and fails when a registered route is absent. The
template carried the same rule for its own example screens; the route set is
@@ -206,7 +206,7 @@ src/shared/api
### 1.2 계층 방향
현재 `config/architecture/layers.json`의 방향을 유지한다.
현재 방향을 유지한다. 기준은 `.dependency-cruiser.json` 하나이고 `check:architecture`가 강제한다(`config/architecture/layers.json`은 아무도 읽지 않는 낡은 사본이라 지웠다, 리뷰 12-09).
```text
domain -> domain only
@@ -635,6 +635,7 @@ export interface CommandEffectDescriptor<Problem> {
status: number;
problem: Problem;
}>): "NOT_APPLIED" | "APPLIED_CONFIRMED" | "MAYBE_APPLIED";
classifyStatus?(status: 401 | 403 | 429): "NOT_APPLIED" | "MAYBE_APPLIED";
}
```
@@ -647,6 +648,8 @@ export interface CommandEffectDescriptor<Problem> {
- frontend는 inspect request/response wire shape나 problem effect meaning을 작성하지 않는다;
- `classifyProblem`은 package가 제공한 pure bounded classifier다;
- classifier가 throw/unknown을 반환하면 effect는 fail-safe `MAYBE_APPLIED`이고 contract runtime failure를 기록한다;
- 401·403·429는 본문을 읽기 전에 판정하므로 `classifyProblem`을 거치지 않는다. package가 `classifyStatus`를 주면 그 판정을 쓰고, 없거나 `NOT_APPLIED` 외 값·throw면 전송 뒤 `MAYBE_APPLIED`다(`src/adapters/http/http-effect-certainty.ts` `classifyStatusEffect`);
- `AUTH_REQUIRED`는 effect가 `MAYBE_APPLIED`여도 action이 `reauth`다(`src/contracts/errors.ts` `unknownEffectAction`);
- feature gateway가 package의 inspect operation을 application-safe outcome으로 mapping한다.
### 4.5 event contribution
@@ -2604,7 +2607,7 @@ export const DEFAULT_REALTIME_RECONNECT_POLICY = Object.freeze({
- remaining episode budget 초과 hint: reconnect 종료;
- attempts/exhausted: `DEGRADED`, explicit recovery action;
- automatic new episode cooldown: 300,000ms;
- valid event/heartbeat 또는 60s stable open 후 attempt counter reset;
- valid event/heartbeat를 받고 60s stable open도 지난 뒤에만 attempt counter reset;
- offline state에서는 timer 대신 `online` signal을 기다림.
### 14.4 error classification
@@ -253,7 +253,9 @@ Cross-origin bearer provider 최소 CORS:
- exact allow-origin 목록과 bounded preflight cache
- `Authorization`, `Content-Type`, `Idempotency-Key`,
`X-Correlation-ID`, 향후 `If-None-Match`, `If-Match` 허용
- 필요한 경우 `ETag`, `Retry-After`, request/trace header만 expose
- 필요한 경우 `ETag`, `Retry-After`, request/trace header만 expose.
`X-Correlation-ID`를 expose하면 V3 실패의 `AppFailure.requestId`가 된다
(`src/adapters/http/feature-http-binding.ts`)
- redirect login page, HTML error body와 wildcard credential 금지
## 6. Command와 idempotency
@@ -593,6 +595,21 @@ query invalidate hint로만 쓸지 operation별 reducer contract가 필요하다
- rate limit key는 principal/tenant/operation과 abuse policy에 binding하며 raw
credential/IP를 metric label에 넣지 않는다.
### 16.1 전송별 재시도·타임아웃 규칙 (2026-09-25 코드 기준)
같은 이름의 정책이라도 전송마다 동작이 다르다. operation을 다른 전송으로 옮기면
이 표로 동작 변화를 확인한다.
| 규칙 | V3 contract executor (기본 경로) | V2 client (기본 조합에 없음) | Browser RPC |
|---|---|---|---|
| KEYED 명령 자동 재시도 | 전송 전 실패만 재시도한다. 전송 뒤 실패는 재시도하지 않고 `MAYBE_APPLIED`다. 응답(5xx·429)으로는 재시도하지 않는다 (`src/adapters/http/http-retry-lifecycle.ts` `canRetryTransport`, `isRetryableSemantics`) | 네트워크·타임아웃·429·408/425/502/503/504 뒤 같은 키로 다시 보낸다. 전송 여부를 보지 않는다 (`src/adapters/http/retry-policy.ts` `shouldRetry`) | `KEYED_COMMAND`는 유효한 키가 있고 profile `retryOwner`가 `FRONTEND_ADAPTER`면 `retryableFailures`에서 같은 키로 다시 보낸다 (`src/adapters/browser-rpc/browser-rpc-runtime.ts` `shouldRetry`) |
| 재시도 횟수 상한 | min(계약 `retryBudget`, `MAX_RETRY_ATTEMPTS`, 2) (`http-execution-v3.ts` `retryCeiling`) | `MAX_RETRY_ATTEMPTS`, 기본 2 (`client.ts` `maxRetryAttempts`) | profile `maxAttempts`(시도 횟수), 하드 상한 4 (`src/contracts/browser-rpc.ts` `BROWSER_RPC_HARD_LIMITS`) |
| `Retry-After` | 5초를 넘으면 재시도하지 않는다. 이하면 hint에 jitter를 더해 기다린다 (`http-retry-lifecycle.ts` `retryDelayFor`) | 30초를 넘으면 재시도하지 않는다. 이하면 max(backoff, hint)만큼 기다린다 (`retry-policy.ts`) | profile `maxRetryAfterMs`로 잘라 max(backoff, hint)만큼 기다린다. 하드 상한 60초 (`browser-rpc-runtime.ts` `retryDelay`) |
| `REQUEST_TIMEOUT_MS` | 상한이다. 계약 `totalDeadlineMs`를 줄이기만 한다 (`runtime-adapters.ts` `requestDeadlineCeilingMs`) | 기본값이다. operation `timeoutMs`가 있으면 그 값을 쓰고, 더 길 수도 있다 (`client.ts` `defaultTimeoutMs`) | 쓰지 않는다. operation `totalDeadlineMs`만 쓴다. 하드 상한 30분 |
결과 불명 뒤 사용자 재전송은 전송과 무관하게 같은 intent·같은 키를 쓴다
(`src/presentation/adapters/query/application-query.ts` `resendUnknownEffect`).
## 17. Observability와 privacy
허용되는 공통 dimension:
@@ -353,8 +353,23 @@ digest 또는 별도 검토된 streaming hash adapter를 사용한다.
- one-shot 작은 download는 click handoff 뒤 cross-engine scheduling을 위해 기본
30초 grace를 두고 revoke한다. feature/runtime dispose는 grace를 기다리지 않고
모든 active lease를 즉시 revoke한다.
- preview와 download는 runtime 하나의 lease registry를 같이 쓴다
(`src/adapters/browser-files/create-browser-file-runtime.ts:154`, `:163`).
lease 개수나 합계 바이트 한도가 차면 둘 다 `LIMIT_EXCEEDED`를
`retryable: true`, `recovery: "RETRY"`로 반환한다
(`src/adapters/browser-files/object-url-lease.ts:48-73`, `:131-139`). download
lease는 grace(`download-delivery-adapter.ts:149`)가 끝나면 풀리므로 잠시 뒤
다시 시도하면 된다. Blob 하나가 단일 lease 상한을 넘으면 재시도 불가다.
- URL을 global state, IndexedDB, query cache, log, analytics에 보관하지 않는다.
- Service Worker에서 object URL을 사용하지 않는다.
- 로그아웃·계정 전환에서는 runtime 전체를 dispose한다. browser file runtime은
세션을 모른다(`src/adapters/browser-files/create-browser-file-runtime.ts:93`).
`runtime.dispose()`(`:177-185`)가 이전 사용자가 고른 File 참조, preview lease,
진행 중 download(`download-delivery-adapter.ts:385-391`)를 한 번에 닫는다.
runtime을 route·feature보다 오래 사는 곳에서 만들었다면 server-state scope
reset participant(`src/adapters/query-cache/server-state-scope-runtime.ts:19`,
등록 예 `src/bootstrap/runtime-adapters.ts:410-416`)로 `dispose()`를 등록하고
다음 세대에서 새 runtime을 만든다. dispose한 runtime은 다시 쓸 수 없다.
- SVG, HTML, untrusted PDF 같은 active content를 same-origin object URL iframe에
직접 preview하지 않는다. 별도 격리 origin 또는 안전한 decode/re-encode 결과,
아니면 attachment-only 정책을 사용한다.
@@ -525,6 +540,14 @@ recipe의 feature-facing `StoredRecord<T>` view model과 혼동하지 않는다.
`writtenAtEpochMs`, synchronization, `measuredBytes`, `eligibleAtEpochMs`는 record
envelope에 중복 저장하지 않고 `retentionStore` sidecar에 둔다.
revision은 살아 있는 record 하나 안에서만 순서를 매긴다(D-13). `remove`는 행을
tombstone 없이 지우므로 같은 key를 다시 만들면 revision이 1부터 다시 시작한다.
그래서 `(key, revision)`은 key의 전체 수명에서 유일하지 않다. 삭제 전에
revision N을 읽은 writer는 재생성된 record가 N에 도달하면 `expectedRevision: N`
CAS로 그 record를 덮어쓸 수 있다. 이 구분이 필요한 호출자는 revision과 함께
자기가 소유한 값(server version, payload 안의 ID)을 비교한다. tombstone으로
번호를 이어 가는 방식은 저장 스키마 변경이라 이 템플릿 범위 밖이다.
- structured clone 성공을 업무 schema 검증으로 간주하지 않는다.
- 모든 read는 `unknown`에서 runtime codec으로 envelope와 payload version을
검증한 뒤 domain value로 mapping한다.
@@ -751,8 +774,10 @@ CLEANED -> journal 제거
- journal row와 budget reservation은 physical cleanup effect가
`CLEANED` 또는 `ALREADY_CLEAN`으로 확인된 뒤에만 해제한다. timeout, crash,
malformed response, `EFFECT_UNKNOWN`은 성공이 아니며 `PREPARING`/`FILES_READY`를
그대로 남기고 `OBJECT_RECONCILE`로 반환한다.
malformed response, worker cleanup 실패는 성공이 아니며 `PREPARING`/`FILES_READY`를
그대로 남긴다. 이때 put은 자기 실패 코드(취소면 `ABORTED`, 쿼터 초과면
`QUOTA_EXCEEDED` 등)를 그대로 반환하고 recovery만 `RECONCILE`로 바꾼다
(Q-6.5-9). journal rollback이 실패해도 같다.
- coordinator가 `abortPreparedPut()` 하나만 소유한다. worker client는 prepare 실패
시 별도의 fire-and-forget abort를 발행하지 않는다. 중복 보상은 아직 남아 있어야
할 journal row를 조기에 지우는 경로였다.
@@ -771,6 +796,11 @@ CLEANED -> journal 제거
`STORAGE_EVICTED`; reconstructable만 rehydrate한다.
- delete는 logical row tombstone을 먼저 commit해 신규 open을 막고 physical bytes를
나중에 정리한다.
- delete가 끝나면 logical row가 없어지므로 같은 object ID의 다음 put은
generation 1부터 다시 시작한다(D-13). 삭제 전에 기억한 generation이나
`expectedGeneration`은 다른 객체와 일치할 수 있다. `(objectId, generation)`을
객체 수명 전체의 식별자로 쓰지 않고, 필요하면 integrity root digest를 함께
비교한다.
- operation ID로 replay를 deduplicate한다.
`Web Locks`를 쓰면 고정된 origin mutation lock과 AbortSignal/timeout을 사용한다.
@@ -15,15 +15,16 @@ The existing reference feature is the executable REST consumer.
It covers list/detail/create behavior, mapping, typed operation inputs,
application ports and an optimistic mutation path.
Current source size:
The feature-owned boundary and application source is these four files:
| Feature-owned area | LOC |
| --- | ---: |
| `application/reference-feature-api.ts` | 91 |
| `contracts/reference-mapper.ts` | 109 |
| `adapters/reference-http-gateway.ts` | 65 |
| `adapters/create-reference-feature-input.ts` | 41 |
| Total measured boundary/application source | 306 |
- `application/reference-feature-api.ts`
- `contracts/reference-mapper.ts`
- `adapters/reference-http-gateway.ts`
- `adapters/create-reference-feature-input.ts`
This document does not keep their line counts; a hand-typed count drifted
from the code (review 14-07). Measure them with
`wc -l src/features/reference-feature/{application/reference-feature-api.ts,contracts/reference-mapper.ts,adapters/reference-http-gateway.ts,adapters/create-reference-feature-input.ts}`.
The important boundary metric is not the raw total. It is what those files need
to know about the platform.
@@ -48,20 +49,19 @@ its business requirement.
## Scenario B — IndexedDB local draft
The original executable consumer probe remains at:
The executable consumer probe is:
`tests/contract/consumer-experience/indexeddb-local-draft.test.ts`
with its isolated fixture:
It runs and reads the one Local Draft implementation under
`src/features/local-draft-feature`; the isolated fixture copy it used to probe
had drifted from `src` and was removed (09-12).
`tests/contract/consumer-experience/fixtures/local-draft-feature.ts`
The architecture is now also exercised by a real vertical slice under:
`src/features/local-draft-feature`
It owns the Local Draft domain/application API and binds an
`IndexedDbRepositoryPort<LocalDraft, never>` in its feature adapter. The
The feature owns the Local Draft domain/application API and declares the slice
of the repository it calls (`LocalDraftRepository` in
`src/features/local-draft-feature/adapters/local-draft-indexeddb-store.ts`). The
host hands in an `IndexedDbRepositoryPort<LocalDraft, never>` through the
`indexedDb` capability; the port satisfies that slice structurally. The
cross-capability composition contract lives at:
`tests/contract/reusable-capability/feature-adapter-composition.test.ts`
@@ -80,25 +80,24 @@ It runs against native browser IndexedDB. The test creates the platform
save/find/remove through the feature API. The Local Draft feature still does
not import the IndexedDB runtime or native browser API.
Measured probe result:
Measured on `src/features/local-draft-feature` (09-12):
| Metric | Result |
| --- | ---: |
| feature-owned fixture LOC | 97 |
| platform import statements | 1 |
| feature LOC (all `.ts` files) | 295 |
| import statements leaving the feature (`contracts/errors`, `contracts/result`, `application-api`, `feature-adapter-contribution`) | 7 |
| native IndexedDB API references | 0 |
| `src/adapters/storage/indexeddb/**` imports | 0 |
| runtime-internal IndexedDB types imported by feature | 0 |
| `src/application/ports/browser-file-storage/**` imports | 0 |
The feature depends only on the public application boundary:
`src/application/ports/browser-file-storage/index.ts`
and specifically `IndexedDbRepositoryPort<LocalDraft, never>`.
The feature does not import the storage runtime or its port, so removing the
browser file/storage runtime (`test:browser-file-storage-removal`) leaves it
compiling.
The contract test rejects feature source that reaches for
`globalThis.indexedDB`, `IDBFactory`, `IDBDatabase`, `IDBTransaction`,
`IDBObjectStore` or the concrete IndexedDB adapter directory.
`IDBObjectStore`, the concrete IndexedDB adapter directory or the
browser-file-storage port.
## What this does and does not prove
+23 -10
View File
@@ -41,8 +41,8 @@
| `NOT_SELECTED` | 제품 요구·owner·policy가 승인되지 않았다. |
| `PLATFORM_LIMITED` | browser/platform이 요구 의미를 cross-browser로 보장하지 못한다. |
현재 `src/adapters/query-cache/tanstack-query-cache.ts`는 한 runtime당
`QueryClient`를 만들고, query retry를 끄며, 30초 `staleTime`과 5분 `gcTime`을
현재 `src/adapters/query-cache/tanstack-query-cache.ts`는 server-state
generation마다 `QueryClient`를 만들고, query retry를 끄며, 30초 `staleTime`과 5분 `gcTime`을
기본값으로 사용한다. `src/bootstrap/runtime-adapters.ts`와
`src/bootstrap/runtime-application.tsx`가 이 client를 실제 provider tree에
조립한다.
@@ -79,13 +79,26 @@ native two-page browser spec은 BroadcastChannel primary와 localStorage fallbac
delivery/cleanup을 검증한다. 다만 production QueryClient/coordinator까지 연결한
account transition, bfcache/StrictMode lifecycle E2E는 없고, 현재 보존 artifact도
Chromium/Firefox만 통과해 WebKit을 포함한 promotion evidence는 충족하지 않는다.
localStorage fallback physical key는 아직 storage registry 밖의 상수이고 native
`StorageEvent.storageArea`도 facade에서 검증하지 않는다.
localStorage fallback physical key는 storage registry의
`CACHE_INVALIDATION_PULSE` 항목에서 온다(`src/contracts/storage-keys.ts:102`,
`src/adapters/cross-context-invalidation/browser-cross-context-host.ts:36-37`).
host facade는 native `StorageEvent.storageArea`를 캡처한 `localStorage` 객체와
동일성으로 비교하고(`browser-cross-context-host.ts:286-296`), core는
`EXPECTED_LOCAL_STORAGE`로 표시된 pulse만 받는다
(`browser-cross-context-invalidation.ts:197-201`).
현재 epoch 구현은 `release.<releaseId>` 하나다. session/account epoch, opaque
account partition, scope 전환 시 새 QueryClient 생성과 durable namespace epoch는
아직 구현되지 않았다. 따라서 현재 cross-tab event는 같은 release의 등록 query
topic을 빠르게 stale 처리하는 용도에 한정된다.
현재 epoch는 release 하나다. `cacheEpoch`는 release ID의 64-bit FNV-1a digest를
`release.<16자리 hex>`로 쓴 값이다(`browser-cross-context-host.ts:45-51`, 조립
`src/bootstrap/runtime-adapters.ts:364-366`). 세션 identity가 바뀌면 scope
runtime이 다음 server-state generation을 열고
(`src/adapters/query-cache/server-state-scope-runtime.ts:148`), generation마다
새 `QueryClient`와 새 cross-context transport(새 `sourceId`·`sourceEpoch`)를
만든다(`src/bootstrap/server-state-generation-store.ts:50-57`,
`runtime-adapters.ts:359-372`). 이전 generation의 transport는 coordinator
dispose에서 닫힌다(`src/adapters/query-cache/tanstack-cache-coordinator.ts:276-280`).
session/account epoch, opaque account partition과 durable namespace epoch는
아직 없다. wire event에 사용자·세션 scope가 없으므로 현재 cross-tab event는 같은
release의 등록 query topic을 빠르게 stale 처리하는 용도에 한정된다.
`QUERY_REGISTRY`의 모든 현재 entry와
`createTanStackCacheCoordinator()`는 `persistence: "disabled"`만 허용한다.
@@ -113,10 +126,10 @@ blocked/versionchange를 다루는 reference runtime이 있다. 이 설계는
| capability | primary current status | current implementation | target delta | delta implementation status |
| --- | --- | --- | --- | --- |
| memory QueryClient | `COMPOSED` | runtime별 생성, global stale/gc/retry default | session/account scope owner, generation fence, per-query policy | `DESIGNED_NOT_IMPLEMENTED` |
| memory QueryClient | `COMPOSED` | server-state generation별 생성(session identity 변경 시 FENCED 뒤 새 client), global stale/gc/retry default | per-query policy | `DESIGNED_NOT_IMPLEMENTED` |
| application query bridge | `COMPOSED` | AbortSignal, stale error, optimistic rollback/conflict surface | old-generation query/mutation callback 폐기 | `DESIGNED_NOT_IMPLEMENTED` |
| Web Storage | `COMPOSED` | 두 key, strict v1 envelope/codec, lazy TTL, global 16 KiB cap | per-key cap, HIT/MISS, durability, v2 scope, migration, sweep/logout | `DESIGNED_NOT_IMPLEMENTED` |
| cross-tab invalidation | `COMPOSED` | release epoch, versioned hint, duplicate/gap, BC→localStorage | composite scope epoch, registered pulse, storageArea, durable ledger hook | `DESIGNED_NOT_IMPLEMENTED` |
| cross-tab invalidation | `COMPOSED` | release epoch(FNV-1a digest), versioned hint, duplicate/gap, BC→localStorage, registry pulse key, storageArea 동일성 검사, generation별 transport | composite scope epoch, durable ledger hook | `DESIGNED_NOT_IMPLEMENTED` |
| generic IndexedDB | `AVAILABLE_NOT_COMPOSED` | reusable repository/maintenance runtime | product dataset schema/codec/query/policy composition | product selection `NOT_SELECTED` |
| query persistence facade | `DESIGNED_NOT_IMPLEMENTED` | 없음, registry가 disabled 강제 | stable per-query record, bounded restore, namespace epoch/CAS | `DESIGNED_NOT_IMPLEMENTED` |
| product persistence | `NOT_SELECTED` | owner/query allowlist 없음 | measured need와 explicit composition | `NOT_SELECTED` |
@@ -50,7 +50,10 @@ architecture/security/type negative input으로 전환했다. 이는 7번 결정
- `check:types`는 app, Node scripts/config, tests project를 모두 검사한다.
- TS invalid-call, invalid port, discriminated-union fixture는 실패해야 한다.
- ESLint와 dependency-cruiser는 TS/TSX architecture fixture를 검사한다.
- ESLint와 `check:architecture`의 import 그래프(`scripts/check-architecture.ts`)가
TS/TSX architecture fixture를 검사한다. dependency-cruiser 18은 TypeScript 7을
해석하지 못해 0개 모듈을 검사하고 통과했으므로 실행하지 않는다(리뷰 12-05).
`.dependency-cruiser.json`은 이름만 남은 규칙 파일이고 그래프가 읽는다.
- registry scanner는 TS registry의 required field, uniqueness와 reference를
검증한다.
- browser security gate는 TSX의 금지된 raw HTML fixture를 거절한다.
@@ -18,7 +18,8 @@ field orchestration까지 플랫폼 기본값으로 고정하게 된다.
2. Zod presentation schema, application command mapper와 domain invariant는 서로
다른 소유물로 유지한다.
3. page와 feature는 `useAppForm`, `Form`, `FormField`, `ErrorSummary`,
`mapValidationFailureToFields`, `useDirtyNavigationGuard`만 사용한다.
`FormFailureStatus`, `mapValidationFailureToFields`, `useDirtyNavigationGuard`만
사용한다.
4. 422 details는 승인된 `path`와 `code`만 HTTP 경계에서 투영한다. backend
message와 알 수 없는 field는 field에 전달하지 않고 안전한 form-level
error로 이동한다.
@@ -27,6 +28,16 @@ field orchestration까지 플랫폼 기본값으로 고정하게 된다.
dirty 상태를 해제한다.
7. `StandardPage`, `CollectionPage`, `DetailPage`, `FormPage`, `StatusPage`는
layout과 state slot만 소유하며 application/query/HTTP를 import하지 않는다.
8. (2026-09-25, 08-01) 입력 오류가 아닌 저장 실패는 ErrorSummary에 넣지 않는다.
`useAppForm`은 `action: "reauth"`를 `reauth-required`, `FORBIDDEN`을 `forbidden`,
`action: "retry"`를 `retry-later`로, 나머지 입력 외 실패를 `unavailable`로 구분하고
그 실패를 `failure`로 낸다(F-10). 화면은
`FormFailureStatus`로 문구와 행동(로그인·이동·다시 시도)을 보여 준다. 재로그인은
입력을 지운다는 안내를 버튼 앞에 둔다(`src/presentation/forms/use-app-form.ts`,
`form-components.tsx`).
9. (2026-09-25, 03-01) 결과 불명 저장은 사용자가 "변경되지 않음"을 판정하지 않는다.
`resendUnknown(mutation.resendUnknownEffect)`로 같은 intent·같은
`Idempotency-Key`를 다시 보낸다(`src/presentation/adapters/query/application-query.ts`).
## React Hook Form 도입 조건
@@ -38,9 +38,18 @@
## 경계와 검증
- 제품 코드는 `presentation/design-system/index`만 import한다.
- design-system 검사기는 direct icon/headless import, deep import, raw palette,
undefined token과 tooltip-only required information fixture를 거절한다.
- 제품 코드는 `presentation/design-system/index`만 import한다. 예외는 규칙에
이름으로 적는다. `presentation/components/ui/*.ts`는 아래 Rollback의 재수출
facade이고, `presentation/templates/page-templates.tsx`는 index가 내보내지
않는 `PaginationLandmarkContext`를 읽는다.
- deep import와 direct icon import는 `check:architecture` 그래프 규칙
`design-system-is-reached-through-its-index`, `icon-vendor-is-facade-only`
(`.dependency-cruiser.json`)가 거절한다. 경로 해석이 끝난 간선을 보므로
presentation 안의 상대 경로 import도 잡는다(리뷰 12-08). 음성 fixture는
`tests/fixtures/architecture/dependency-graph/import-boundaries`다.
- design-system 검사기(`scripts/check-design-system.ts`)는 headless vendor
import, raw palette, undefined token과 tooltip-only required information
fixture를 거절한다.
- type negative fixture는 accessible name 없는 `IconButton`을 거절한다.
- component test는 decorative icon, form control, Menu, Tabs, Drawer와 Toast를
검증한다.
@@ -66,9 +66,15 @@ route/form/failure 의미 값
## 검증
- `check:i18n`은 catalog key와 placeholder parity, common UI의 한국어 literal,
backend message JSX 렌더링과 raw HTML 사용을 검사한다.
- `check:i18n:fixture`는 세 금지 사례를 실제로 거절해야 성공으로 인정된다.
- `check:i18n`은 catalog key와 placeholder parity, 화면 코드의 한국어 literal,
backend message JSX 렌더링과 raw HTML 사용을 검사한다. 검사 범위는 공통 UI
디렉터리, `src/presentation/pages`, 모든 `src/features/*/presentation`이다.
컴포넌트 갤러리 `src/presentation/examples`는 일부러 뺐다
(`scripts/check-i18n.ts`의 `commonDirectories`, `featurePresentationDirectories`).
- `check:i18n:fixture`는 같은 탐색 규칙을 `tests/fixtures/i18n/forbidden` 트리에
돌린다. fixture 파일 하나라도 거절되지 않으면 종료 코드 2로 실패한다.
- `tests/unit/i18n-contract.test.ts`는 `ERROR_REGISTRY`의 모든 `userMessageKey`가
ko-KR·en-US catalog에 있는지 확인한다.
- type negative fixture는 unknown key와 잘못된 parameter shape를 거절한다.
- unit test는 fallback, alias, pseudo 확장, direction과 timezone/number/relative/
list/plural/select의 결정성을 검증한다.
@@ -43,13 +43,17 @@ vendor 결정 전에는 안전한 기본값이 아니다.
`createHttpObservationProjector`가 유일한 projection authority다. observation은
arbitrary context map이 아니며 projector는 `route_id`, `operation_id`,
`operation`, `outcome`, `error_kind`, `http_status_group`,
`attempt_count_bucket`, `duration_bucket`만 사용한다. raw attempt count,
`attempt_count_bucket`, `duration_bucket`만 사용한다. diagnostics에만
`correlation_id`(서버가 돌려준 `x-correlation-id`, 없으면 실행이 보낸 요청 ID)를
더한다. telemetry에는 넣지 않는다(03-03, `createHttpObservationProjector`). raw attempt count,
duration, status, URL, intent, key, input identity와 내부 `terminalReason`은
sink로 나가지 않는다. effect certainty가 운영상 필요해지면 `effect_certainty`
key와 닫힌 value policy를 contract·fixture·이 ADR에 동시에 추가한 뒤에만
전달한다.
5-2. caller cancellation과 scope fence는 API failure가 아니다. diagnostics는 한
번 남기고 `api.request.failed`는 발행하지 않는다.
번 남기고 `api.request.failed`는 발행하지 않는다. 자격증명이 없어 한 번도
보내지 않은 `UNAUTHENTICATED`(응답 status 없음)도 같다(03-07,
`src/bootstrap/runtime-adapters.ts` `isTerminalNonAbortFailure`).
5-3. `routeId`는 installed operation-executor 경계의 필수 입력이다. feature
gateway가 소유한 low-cardinality route identity를 URL에서 재구성하지 않는다.
6. `app.boot.failed`, `ui.render.failed`, `release.mismatch.detected`,
@@ -72,6 +76,11 @@ vendor 결정 전에는 안전한 기본값이 아니다.
아니거나 1 미만이거나 문서화된 ceiling(각각 `MAX_TELEMETRY_QUEUE`,
`MAX_DIAGNOSTIC_ENTRIES` = 10,000)을 넘으면 `TypeError`로 거절한다. NaN/Infinity가
조용히 eviction을 비활성화하는 경로를 남기지 않는다.
7-5. (2026-09-25) 두 telemetry port는 collector 하나로 보낸다
(`src/adapters/telemetry/telemetry-collector.ts`). collector는 본문을 60KiB 아래로
나누고, 진행 중인 keepalive 본문 합이 64KiB를 넘으면 그 부분은 keepalive 없이
보낸다(03-05). 조합 루트가 release manifest의 `buildId`·`releaseId`를 넘기면 모든
이벤트에 `build_id`·`release_id`를 붙인다(13-11, `src/bootstrap/runtime-adapters.ts`).
8. diagnostics와 telemetry failure는 제품 흐름, HTTP 결과, route transition,
storage/cache fallback과 React error surface를 바꾸지 않는다.
9. mount 전 bootstrap failure는 안전한 build/config/error kind만 별도 evidence로
@@ -255,15 +255,20 @@ reconnect는 capped full-jitter exponential backoff를 사용한다. base/max de
max attempts와 max elapsed는 immutable registry/implementation ceiling으로
제한한다.
- stable-open window 또는 valid heartbeat/event 뒤에만 attempt reset
- valid heartbeat/event와 stable-open window를 둘 다 충족한 뒤에만 attempt와
elapsed budget reset. session의 모든 종료 경로(server close, offline,
`waitClosed` throw)에서 확인한다
- valid server hint는 local delay보다 이른 retry를 금지하는 not-before bound
- server hint가 implementation max/remaining elapsed budget을 넘으면 낮춰
clamp하지 않고 degraded/stale로 종료
- offline에서는 timer retry를 멈춤
- offline에서는 timer retry를 멈춤. offline 대기 시간은 elapsed budget에 넣지
않고 online 복귀 시 elapsed budget을 다시 시작한다. attempt 상한은 유지한다
- auth expiry는 session owner single-flight recovery 한 번
- forbidden/protocol/schema failure는 terminal
- 외부 rate/provider failure는 exact bounded server not-before hint가 있을 때만
retry하고, hint가 없으면 terminal
- retry 여부는 transport가 보고한 `retryable`이 정한다. retryable 실패는 hint가
없어도 bounded retry한다. hint가 꼭 필요한 실패(SSE `429`/`503`, WebSocket
`OVERLOADED`)는 hint가 없으면 transport가 terminal로 보고한다. SSE
`502`/`504`와 WebSocket `RESTART`·`NETWORK_LOST`는 hint 없이 bounded retry
- retry budget 소진 뒤 declared Polling fallback 또는 stale UI
- reconnect는 realtime coordinator, auth는 session owner, Poll cadence는 poll
coordinator가 소유하고 Poll-bound HTTP/Query retry는 비활성
@@ -456,7 +461,7 @@ push hint와 worker deadline을 제한한다. 제품 config는 더 작게만 설
2026-07-28 reference-runtime amendment로, RT-01~RT-04 source 전체를
tree-shaking 없이 합성하는 optional-recipe gzip 예산을 40,000 bytes로
고정한다. 이는 production bundle 허용량이 아니며 미선택 production asset의
고정한다(2026-09-27 성숙도 리뷰 반영으로 40,900 bytes로 올림. 근거는 `config/recipes/frontend-capability-recipes.json` 변경 커밋). 이는 production bundle 허용량이 아니며 미선택 production asset의
realtime module 허용량은 계속 0이다. SSE replay-open과 WebSocket
`SUBSCRIBED`가 exact recovery checkpoint를 증명하고 common barrier가 확인될
때까지 event admission을 막는 readiness gate는 attempt당 최대 30초다.
@@ -138,6 +138,17 @@ browser-capability test composes the feature over the real
`createIndexedDbRuntime` and native IndexedDB, proving that this seam is not
limited to an in-memory contract fixture.
The bootstrap does not build `indexedDb`: IndexedDB is an opt-in reference
runtime (`productionComposition: false` in
`config/recipes/frontend-capability-recipes.json`). The composition example is
`recipes/frontend-capabilities/indexeddb-feature-capability.ts`
(`createLocalDraftIndexedDbCapability`, exercised by
`tests/recipes/indexeddb-feature-capability.test.ts`). A product that installs a
feature with `needs: ["indexedDb"]` copies it and adds `indexedDb` to the feature
capabilities in `src/bootstrap/runtime-adapters.ts`. Until it does, that object
fails the app typecheck, and `composeFeatureAdapterInputs()` rejects the
composition with `feature <id> needs indexedDb, which the host did not provide`.
## Presentation consumer surface
`ApplicationProvider` remains the composition root for presentation, but new
@@ -65,7 +65,7 @@ P0/P1 acceptance와 P2 recipe 기본값은 `LOCAL_TEMPLATE_READY`다. 다만 실
| 영역 | 현재 판정 | 근거 | 필요한 다음 상태 |
| --- | --- | --- | --- |
| 부트·런타임 설정 | 준비됨 | `src/bootstrap`, runtime schema, release 검사 | 현 상태 유지, TS 전환 시 동일 게이트 유지 |
| 계층 의존 방향 | 준비됨 | dependency-cruiser + TS-aware static graph, unresolved/parse/layer/cycle negative fixture | 새 rule shape와 source extension도 같은 fail-closed graph에 추가 |
| 계층 의존 방향 | 준비됨 | TS-aware static graph(`scripts/check-architecture.ts`, 규칙 `.dependency-cruiser.json`), unresolved/parse/layer/cycle negative fixture. dependency-cruiser 자체는 TS 7을 해석하지 못해 실행하지 않음(12-05) | 새 rule shape와 source extension도 같은 fail-closed graph에 추가 |
| application facade | 준비됨 | module-augmented feature input registry, typed output catalog, provider, production composition test | feature별 input contribution과 제거 gate 유지 |
| REST HTTP client | 준비됨 + hardening delta | reference vertical의 path/search/body projection, attempt timeout/retry, abort/cleanup은 `COMPOSED` | auth fail-close/final invariant, total deadline, bounded decoder, status/media/CSRF/conditional/pagination은 `DESIGNED_NOT_IMPLEMENTED` |
| Browser RPC 공통 계약/runtime | 준비됨/미조립 | V3 operation/profile registry, typed application port, bounded unary/server-stream lifecycle와 unavailable adapter는 `AVAILABLE_NOT_COMPOSED` | actual descriptor/generated client, protocol transport, proxy/provider/browser conformance |
+40 -13
View File
@@ -25,6 +25,15 @@ The following edges are forbidden:
- an adapter to presentation, bootstrap internals, or another concrete adapter
- feature domain/application to its presentation or outbound adapter, and
feature presentation to its outbound adapter
- a module presentation may import to a concrete adapter: files outside a
feature's layer folders (`src/features/*.ts`, `src/features/<id>/*.ts`),
`src/contexts` and `src/apps` (`feature-and-app-roots-do-not-reach-adapters`).
The graph checks one edge at a time, so a re-export there would carry an
adapter into presentation with every other rule passing. The one exception is
the type-only `src/features/feature-adapter-contribution.ts`
- presentation to `src/apps` or `src/contexts`, except
`src/presentation/routes/app-router.tsx`, which mounts the app's route tree
(`presentation-does-not-import-apps-or-contexts`)
## The adapter kernel
@@ -35,14 +44,25 @@ purpose and is the only adapter code an adapter may reach across a group for:
the bounded-capacity guard
- `src/adapters/browser-file-storage/result.ts` — the browser-data result and
failure constructors
- `src/adapters/cross-context-invalidation/index.ts` — the cross-context
invalidation transport and its types. Any adapter may import it; today
`query-cache` does
Each rule above is enforced by `check:architecture`, including the kernel
carve-out, so this table and the executable rules cannot drift apart. Two edges
are still open and are named explicitly in `.dependency-cruiser.json` rather
than left silent: the generic presentation modules that read the installed
registries today, and the two collaborator types `query-cache` reads from
`cross-context-invalidation`. Both lists are frozen — a new edge of either kind
fails the gate.
carve-out, so this table and the executable rules cannot drift apart.
Every exception is written in the rule itself (`.dependency-cruiser.json`): the
exempted path in `pathNot`, and the reason, owner and revisit condition in
`comment` (review 12-07). Besides the kernel, the exceptions are:
- the generic presentation modules that read the installed registries today
(`generic-presentation-does-not-compose-the-product`). The list names exact
files, so a new module that reads a registry fails the gate
- `src/presentation/adapters/query`, the TanStack Query binding
(`presentation-does-not-know-adapters`)
- `src/presentation/routes/app-router.tsx` importing the app
(`presentation-does-not-import-apps-or-contexts`)
- the design-system facades (`design-system-is-reached-through-its-index`)
## 어댑터 그룹의 공개 경계
@@ -63,10 +83,15 @@ fails the gate.
위한 것이다.
`storage`는 최상위 배럴이 `indexeddb/`·`opfs/` 서브배럴을 재수출하지
않는다. 두 런타임이 각자 독립적으로 제거 가능하고
(`test:browser-file-storage-removal`), 그래서 각 서브배럴이 곧 경계다.
규칙의 도착점 정규식이 1단계 중첩 `index.ts`를 배럴로 인정하는 이유가
이것이다.
않는다. 두 폴더는 browser-file-storage 번들의 런타임이다. 제거 드릴
(`test:browser-file-storage-removal`)은 그 번들 전체(`browser-file-storage`,
`browser-files`, `browser-transfer`, `cache-storage`, `storage/indexeddb`,
`storage/opfs`)를 함께 지운다. 최상위 `storage` 배럴(Web Storage)은 그 뒤에도
남아야 하므로 두 폴더를 재수출하지 않고, 그래서 각 서브배럴이 그 런타임의 공개
경계다.
규칙의 도착점 정규식은 이 두 서브배럴만 배럴로 인정한다. 다른 그룹의 2단계
`index.ts`(예: `http/internals/index.ts`)는 공개 배럴이 아니고, 그룹 바깥에서
import하면 실패한다(리뷰 12-07, `dependency-graph/barrel` fixture).
`service-worker/index.ts`는 `tsconfig.service-worker.json`의 `exclude`에
들어 있다. 그 설정이 그룹 폴더를 통째로 WebWorker lib로 컴파일하면서 페이지
@@ -83,8 +108,9 @@ application APIs augment the generic typed input registry. Concrete output
ports are composed in bootstrap and stay hidden behind the application facade.
Project-selected capabilities still implement the same output boundaries.
`check:architecture` keeps dependency-cruiser's report and adds the
authoritative TypeScript-aware graph below it:
`check:architecture` writes the TypeScript-aware graph below. It reads the rules
from `.dependency-cruiser.json` but does not run dependency-cruiser, which cannot
parse TypeScript 7 and checked zero modules (review 12-05):
```json
{
@@ -103,7 +129,8 @@ authoritative TypeScript-aware graph below it:
```
The graph scans TypeScript and TSX, including static, dynamic, type, CommonJS
and JSDoc import references. It applies the path rules from
and JSDoc import references. `import.meta.glob` is a parse failure: it loads
modules without naming one, so no edge rule could see them (review 12-06). It applies the path rules from
`.dependency-cruiser.json`, requires explicit TypeScript extensions for local
source imports, and fails closed on JavaScript-family source/specifiers,
unsupported rule shapes, unresolved imports, parse failures, error-severity
@@ -106,6 +106,30 @@ type은 facade 밖으로 노출하지 않는다.
SSOT다. 문서와 catalog가 다르면 gate가 검사하는 catalog를 우선 고치고 이 표도
같이 갱신한다.
Service Worker를 켤 때 확인할 것(06-05). 템플릿은 1·6과 2의 시작 실패
이벤트만 갖고 있다.
1. `src/features/installed-runtime-capabilities.ts`의 `SERVICE_WORKER`를
`ACTIVE`로 바꾼다. `scripts/build-frontend.ts`가 worker 빌드를 추가로 돈다.
2. 관측: `createRuntimeComposition`이 텔레메트리 포트를 optional host에 넘긴다
(`src/bootstrap/create-runtime-composition.ts`). 시작 결과가 `FAILED`나
`INCOMPATIBLE`이면 `service-worker.start.failed`가 1건 남는다
(`src/bootstrap/optional-runtime-host.ts`). 실제 composition에서 첫 설치가
실패하면 이벤트가 1건 나가는 것은
`tests/component/runtime-composition-service-worker-telemetry.test.ts`가
확인한다. 템플릿이 연결하지 않은 것은 셋이다. 업데이트 설치 실패
(`watchForUpdates`, `src/adapters/service-worker/service-worker-page-controller.ts`)는
이벤트를 남기지 않는다. page controller의 `observe`는 composition이 넘기지
않는다. `OptionalRuntimeHost.health()`는 `src` 안에서 읽는 코드가 없다.
필요하면 다운스트림이 `createRuntimeComposition`에서 연결한다.
3. blockers: 저장하지 않은 편집이 있는 탭이 활성화를 거절하게
`createOptionalRuntimeHost`에 `blockers`를 넘긴다. 템플릿은 넘기지 않는다.
4. 활성화 UI: `ServiceWorkerRuntimeHost.onUpdateWaiting`을 구독하고, 사용자가
동의하면 `requestActivation()`을 부른다(`src/contracts/service-worker.ts`).
5. reload 처리: `onReloadRequired`를 구독해 reload를 안내한다.
6. 끄기·롤백·제거: `docs/operations/release-cache-rollback.md`의 Service Worker
절차. `service-worker.js`는 `Cache-Control: no-cache`로 서빙한다.
Web Push target은 현재 13번째 설치 recipe가 아니다. 기존 `realtime`,
`service-worker-pwa`, `browser-permission`의 인접 경계를 조합해야 하는 별도
`NOT_SELECTED` capability다. 실제 선택 전 VD-10 amendment와 machine-readable
@@ -130,6 +154,15 @@ Web Push를 함께 설치하지 않는다.
integration test를 작성한다.
9. runtime config schema, dependency inventory/approval, SBOM, bundle budget,
browser support와 runbook을 갱신한다.
운영 CSP(`config/hosting/security-headers.json`)도 여기서 넓힌다. 기본 CSP는
아래 기능을 막는다(리뷰 13-08).
- 다른 origin의 realtime: `connect-src`에 `wss://<realtime origin>`을 더한다.
`https:`는 `wss:`를 허용하지 않는다(CSP3 scheme 비교).
- 파일 preview(`src/adapters/browser-files/object-url-lease.ts`의 object URL):
`img-src`에 `blob:`을 더한다.
- 이미지 CDN: `img-src`에 CDN origin을 더한다.
바꾼 CSP 아래에서 `tests/e2e/production-csp.spec.ts`가 그 기능의 화면을 열도록
smoke를 늘린다.
10. 실제 provider integration과 negative behavior가 통과한 뒤에만 catalog 상태를
별도 project catalog에서 `INSTALLED`로 바꾼다.
+3 -2
View File
@@ -53,8 +53,9 @@ and exact input type.
Route contracts/codecs, the route-input provider, and lazy runtime modules are
separate modules so feature pages do not import the router that loads them.
Expected application failures use the shared `Result`/`AppFailure` contract.
The architecture gate analyzes TS/TSX imports independently of
dependency-cruiser, rejects local JavaScript-family specifiers and executable
The architecture gate analyzes TS/TSX imports with its own graph (the rules
live in `.dependency-cruiser.json`; dependency-cruiser itself cannot parse
TypeScript 7 and does not run), rejects local JavaScript-family specifiers and executable
JavaScript-family files, and fails on unresolved imports, parse failures,
forbidden layer edges, or cycles. The remaining project-owned work includes
selecting and verifying real hosting, identity, telemetry, vulnerability and
@@ -164,8 +164,24 @@ URL을 발급하면 안 된다.
- capability를 async 대기하는 동안 caller 입력과 dependency method를 snapshot한다.
- 사용 전에 만료뿐 아니라 최소 잔여 lifetime도 검사한다.
- 기기 시계가 서버보다 `maxClockSkewMs`(기본 60초)까지 늦어도 수명 상한 검사는
거절하지 않는다. 서버는 session 수명을 `maxSessionLifetimeMs` 이하, capability
수명을 `maxCapabilityTtlMs` 이하로 주면 된다(`upload-response-validation.ts`
`validateSession`, `presigned-capability-http-provider.ts` `maxClockSkewMs`).
하한은 느슨하게 하지 않는다. 기기 시계가 빠르면 수명이 그만큼 짧아 보이므로
서버 capability 수명은 `minimumRemainingLifetimeMs + maxClockSkewMs`와
`capabilityRefreshSkewMs + maxClockSkewMs`보다 길어야 한다. 기기 시계가 이보다
더 빠르면 그 기기에서는 capability가 만료로 보인다.
- 만료/403은 임의 retry가 아니라 control plane의 새 capability 발급으로 복구한다.
- ambiguous network failure 뒤 upload part를 새 bytes로 덮어쓰지 않는다.
- 실행기의 `put()`·`open()`은 받은 capability를 어떤 경로로 끝나든 vault에서
뺀다. 성공하면 `consume()`이 빼고, 그 밖의 모든 경로(잘못된 입력, 이미 중단된
signal, 바이트 길이 불일치, 바인딩 거절, 만료, replay claim 실패, digest 중단이나
불일치, 전송 실패)는 공개 메서드의 `finally`가 `revoke()`로 뺀다
(`presigned-transfer-executor.ts`의 `release`). 실행기에 닿기 전에
버려진 capability(runtime 응답 검증 실패, part 실행기 사전 검사 실패, fail-fast로
`put()` 전에 멈춘 형제 worker)는 만료까지 `maxActiveCapabilities` 자리를
차지하고, 다음 `register()`가 만료 항목을 정리한다.
- client-side single-use map은 UX 최적화일 뿐이다. cross-tab/replay authority는
server 또는 composition-owned atomic consumer다.
- signed response의 URL, query, raw header와 exception text를 관측성에 남기지 않는다.
@@ -198,6 +214,15 @@ capability는 앞 절의 별도 fixed BFF endpoint를 redirect 금지로 사용
response envelope 및 request/response의 `UPLOAD_PART` binding protocol이
`PRESIGNED_MULTIPART_V1`인지 대조한다.
part 수 상한과 byte cap은 서로 맞아야 한다. complete 요청과 status 응답에는 part
receipt가 모두 들어간다. 조립할 때 runtime 정책의 `maxPartCount`를 전송의
`maxPartCount`로 넘기면, 전송 factory가 최악의 receipt(모든 필드가 문법 최대,
token 512자, part당 691바이트)로 계산해 들어가지 않는 조합을 `TypeError`로
거절한다(`fetch-json-transport.ts` `MAX_RECEIPT_JSON_BYTES`). 기본값(1,024 part,
요청 1MiB, 응답 2MiB)은 들어간다. 요청 1MiB로는 약 1,500 part, 최대치 4MiB로는
약 6,000 part까지다. 넘기지 않으면 검사하지 않고, 넘치는 upload는 모든 part를
보낸 뒤 complete에서 `LIMIT_EXCEEDED`로 끝난다.
Session은 적어도 opaque ID, protocol version, exact total bytes, media type,
part size, part count, concurrency ceiling, checksum algorithm과 expiry를 묶는다.
part number는 1부터 연속적이어야 하고 마지막 part를 제외한 part length는
@@ -261,6 +286,16 @@ session state 검사를 대체하지 않는다.
- 429/모든 `5xx`/network retry는 composition의 bounded attempt, bounded
`Retry-After`와 abortable backoff 안에서만 수행한다.
- 만료/authorization failure는 최대 정책 범위 안에서 capability를 재발급한다.
object store PUT의 401/403/409/410과 실행기의 만료 판정(`REISSUE_CAPABILITY`)은
`maxRetries` 안에서 다음 시도가 새 capability로 다시 보낸다. BFF 발급 단계의
401/403은 재시도하지 않는다(`resumable-upload-runtime.ts` `uploadPartWithRetry`).
- part PUT 한 번의 제한 시간은 `providerAttemptTimeoutMs + part 바이트 /
minTransferBytesPerSecond`다. 기본값은 30초 + 5MiB ÷ 64KiB/s = 110초다
(`runtime-policy.ts`). 즉 지원하는 최저 업링크는 기본 약 0.5Mbit/s이고, 이보다
느리면 정책의 `minTransferBytesPerSecond`를 낮춘다. fetch는 업로드 진행을 알려
주지 않으므로 PUT에는 idle 제한이 없고 이 크기 비례 제한이 멈춘 연결을 끊는다.
presigned 실행기도 `timeoutMs`에 같은 식의 바이트 몫을 더한다
(`presigned-transfer-executor.ts`, `http-common.ts` `transferAllowanceMs`).
- upload response의 opaque receipt/ETag를 whole-file digest로 해석하지 않는다.
- PUT capability는 성공 status, receipt header와
`expectedResponseByteLength`를 묶는다. runtime은 exact `Content-Length`를
@@ -299,6 +334,12 @@ resume 시 checkpoint만 신뢰하지 않는다.
전환한다.
5. 새 part만 업로드한 뒤 전체 ordered set을 다시 reconcile한다.
재개 때 서버 session은 저장된 checkpoint 값(session ID, 동시성, 만료 시각)과
일치하는지만 본다. 정책 상한(`maxConcurrency`, `maxSessionLifetimeMs`)은 새
session을 만들 때만 검사한다. 그래서 정책을 낮춘 빌드도 이전 빌드가 시작한
업로드를 이어 간다. worker 수는 `min(현재 정책, session 동시성)`이다
(`upload-response-validation.ts` `validateSession`의 `stage`).
`GET_STATUS`가 HTTP `404` 또는 `410`을 반환하거나 decoded status가
`NOT_FOUND`/`EXPIRED`이면 해당 session은 terminal이다. runtime은 CAS revision을
확인해 checkpoint를 제거하고 새 session으로 restart하거나
@@ -324,6 +365,42 @@ signed URL이나 receipt를 포함하거나 저장하지 않으며 server state
reconcile에서 server 상태를 확인한다. backend는 만료된 orphan multipart를
정리하는 TTL job을 가져야 한다.
complete 결과를 모를 때 클라이언트는 다음처럼 동작한다.
- complete 응답을 잃으면(시간 초과, 연결 끊김) `upload()`는 같은 COMPLETE key로
`maxRetries`번 다시 보낸 뒤 `UNAVAILABLE/UPLOAD_COMPLETE, retryable:true`를
돌려준다. 모든 part가 수락된 checkpoint는 남는다
(`resumable-upload-runtime.ts` `completeUpload`).
- 같은 파일로 `upload()`를 다시 부르면 `GET_STATUS`가 `QUARANTINED`일 때
resourceId와 `replayed:true`를 돌려준다. `ACTIVE`이면 같은 key로 complete를
다시 보낸다.
- `abort()`에 서버가 `ALREADY_COMPLETED`로 답하면 checkpoint를 지우기 전에
`GET_STATUS`로 resourceId를 읽어 `{ state: "ALREADY_COMPLETED", resourceId }`로
돌려준다. status 조회가 일시적으로 실패하면 `ABORT_PENDING` checkpoint를 남기고
실패를 돌려준다. `abort()`를 다시 부르면 된다. 서버가 session을 모르면(404/410)
resourceId 없이 닫는다(`resumable-upload-runtime.ts` `readCompletedResourceId`).
- 서버가 complete를 반영한 뒤 로컬 checkpoint 삭제가 실패해도(IndexedDB 오류,
complete 직후 caller abort) `upload()`는 성공을 돌려준다. 남은 행은 다음
`upload()`나 `abort()`가 같은 자원으로 정리한다.
서버 계약 — complete 진행 중(`ResumableUploadControlPlane.complete` 주석):
- 같은 COMPLETE key의 complete가 아직 끝나지 않았으면 서버는 `429`와
`Retry-After`로 답한다. 값은 전송과 runtime의 `maxRetryAfterMs`(기본 30초)
이하여야 한다. 클라이언트는 이것을 `UNAVAILABLE, retryable:true`로 읽고 그만큼
기다린 뒤 같은 key로 다시 보낸다(`fetch-json-transport.ts` `statusFailure`).
`Retry-After`가 없거나 상한을 넘으면 재시도하지 않는다. `503`도 재시도되지만
`Retry-After`는 읽지 않는다.
- `409`는 쓰지 않는다. 클라이언트는 `409`를 `CONFLICT, retryable:false`로 읽고
멈춘다.
- 그동안 `GET_STATUS`는 `ACTIVE`(모든 part 수락)를 유지하고, 자원이 확정된 뒤에만
`QUARANTINED`와 resourceId를 준다. 클라이언트 status 계약(`UploadSessionStatus`)에는
"완료 중" 값이 없고, 모르는 state는 `INTEGRITY_FAILED`로 거절한다.
- 서버 문서의 `OPERATION_IN_PROGRESS`(`server-file-capability-infrastructure.md`
8.2, 11.1)는 이 wire 표현으로 내보낸다.
- 재시도가 모두 끝나도 진행 중이면 `upload()`는 `UNAVAILABLE/RESUME`을 돌려주고
checkpoint가 남는다. 다음 `upload()`나 `abort()`가 위 순서로 조정한다.
application-facing upload 성공값은 `state`, opaque `resourceId`, `byteLength`,
`replayed`만 반환한다. control-plane 검증에 사용한 `sessionId`,
`requestBindingSha256`와 file fingerprint는 public outcome에 노출하지 않는다.
@@ -360,7 +437,10 @@ resume through upload()
정한 `schemaVersion: 2`가 필요하다. 기존 schema에 필드를 몰래 추가하지 않는다.
현재 checkpoint store도 single-key `read/CAS/remove`와 account partition 전체
삭제만 제공한다. abandoned upload가 같은 `uploadKey`로 다시 열리지 않으면 local
삭제만 제공한다. 예외로 읽을 수 없는 행(손상, 또는 이 빌드가 모르는
`schemaVersion`)은 명시적 `abort()`가 `removeUnreadable`로 지우고 `ORPHANED`로
보고한다. 그 행에서는 session을 알 수 없으므로 server session은 만료에 맡긴다.
`upload()`는 같은 행에서 계속 `CORRUPT_DATA`로 fail-closed한다. abandoned upload가 같은 `uploadKey`로 다시 열리지 않으면 local
checkpoint를 retention 기준으로 자동 발견·정리하지 못한다. 향후 admin lifecycle은
다음을 제공한다.
@@ -397,6 +477,11 @@ Streaming download는 server resource를 전체 `Blob`/`ArrayBuffer`로 material
- abort/consumer early return에서 reader를 cancel하고 lock/capability lease를
해제한다.
- byte source는 기본 one-shot이며 두 번째 stream 소비를 거절한다.
- 전체 제한과 idle 제한을 따로 둔다. 전체 제한은 `timeoutMs + byteLength /
minTransferBytesPerSecond`(기본 64KiB/s)라 느리지만 진행하는 큰 download는
끝까지 받는다. chunk 하나를 기다리는 시간은 `idleTimeoutMs`(기본 `timeoutMs`)가
상한이고, 진행이 멈추면 여기서 `UNAVAILABLE/REISSUE_CAPABILITY`로 끝난다
(`presigned-transfer-executor.ts` `readChunk`, `http-common.ts` `readWithSignal`).
File System Access save picker가 있으면 user activation 안에서 destination을 먼저
열고 stream을 쓴다. close와 integrity verification이 끝난 경우만 `SAVED`다.
@@ -545,6 +630,9 @@ DOM, persisted state, telemetry 또는 query cache에 장기 보관하지 않는
private delivery는 `PRIMARY_REQUIRED` browser probe가 필수이며 이를 `NONE`으로
낮출 수 없다. probe는 `credentials: omit`, redirect 금지, exact response URL과
`Cache-Control: no-store`를 실제 response에서 확인한다.
probe는 decode 크기가 primary 후보의 pixel 크기와 정확히 같아야 통과하므로
`PRIMARY_REQUIRED` preset의 `fit`은 `cover`/`contain`/`fill`만 허용한다(D-12).
원본 비율을 유지하는 `inside`/`outside`는 probe를 쓰지 않는 preset에서만 쓴다.
실제 `<img crossorigin="anonymous">`는 same-origin일 때 cookie를 보낼 수
있으므로 registry는 CDN origin이 composition의 application origin과 같으면
생성 단계에서 거절한다. private CDN 응답은 cookie나 ambient authorization에
@@ -559,6 +647,14 @@ private delivery는 `PRIMARY_REQUIRED` browser probe가 필수이며 이를 `NON
- private rendition은 짧은 expiry와 필수 `no-store`를 쓴다.
- CDN cache hit 여부는 authorization이나 asset safety proof가 아니다.
`PRIMARY_REQUIRED` preset(private asset은 항상)의 `resolve()`는 primary candidate를
preset의 encoded·decoded 예산까지 내려받아 decode한다. private 응답은 `no-store`라
`<img>`가 같은 URL을 한 번 더 받는다. 그래서 runtime은 같은 asset reference와
preset에 대해 통과한 probe를 capability가 유효한 동안 재사용하고, 동시에 도는
probe를 `maxConcurrentProbes`(기본 4, 최대 32)개로 제한한다. 넘는 호출은 자리를
기다리며, 기다리다 abort하면 자리를 차지하지 않는다(`image-cdn-runtime.ts`
`passedProbes`, `acquireProbeSlot`).
image probe의 단일 bounded deadline은 response header fetch, streamed body read와
native decode 전체를 포함한다. timeout/cancel/error 시 reader를 cancel하고,
abort 뒤 늦게 resolve한 response body도 cancel하며 늦게 생성된 `ImageBitmap`도
@@ -624,12 +720,31 @@ analytics는 제품 presentation이 소유한다.
| image capability verification concurrency ceiling | `LIMIT_EXCEEDED` | 진행 작업 종료 대기 또는 runtime 부하 조사 |
| closed Image CDN runtime 사용 | `UNAVAILABLE` | 새 runtime composition |
| network/429/모든 5xx | `UNAVAILABLE` | bounded retry/backoff |
| complete 응답 유실·진행 중 | `UNAVAILABLE`(`UPLOAD_COMPLETE`, retryable) | 같은 파일로 `upload()` 재호출, 또는 `abort()`가 resourceId와 함께 `ALREADY_COMPLETED` 반환(4.3) |
관측성에는 operation, safe outcome, byte/part/candidate bucket, retry bucket과
`ResumableUploadPort.upload()` 실패의 `recovery`는 호출자가 할 행동 하나를
가리킨다(`resumable-upload.ts` port 주석, `resumable-upload-runtime.ts`
`toUploadAction`). 이 다섯 값 밖의 값은 `upload()`에서 나오지 않는다.
| recovery | 호출자 행동 |
| --- | --- |
| `RESUME` | 같은 파일·key로 `upload()`를 다시 부른다. `retryable:true`면 자동 재시도해도 된다. capability 재발급이 필요한 실패도 여기로 온다 |
| `RECONCILE` | `upload()`를 다시 부른다. 서버 상태를 먼저 읽는다(예: 다른 문맥이 checkpoint를 먼저 씀) |
| `RESTART` | `abort()` 뒤 `upload()`로 새 session을 연다. abort가 남아 있음(operation `UPLOAD_ABORT`), 읽을 수 없는 checkpoint 행, 서버 part가 파일과 다름 |
| `RESELECT` | 파일을 다시 고르거나, 다른 파일이면 새 key를 쓴다 |
| `NONE` | 이 요청으로 할 행동이 없다. 잘못된 입력, 상한·정책·권한 거절, 호출자 자신의 abort, 다시 불러도 같은 답이 오는 서버 응답(정책보다 긴 session 등) |
관측성에는 operation, safe outcome, byte/candidate bucket, retry bucket과
failure code만 기록한다. capability ID, URL, query, asset/resource/session ID,
file name, digest, raw ETag, receipt와 backend message는 log/diagnostics/telemetry에
기록하지 않는다. 앞 절의 strict checkpoint allowlist만 durable 예외다.
같은 observer를 두 계층에 넘겨도 한 사건은 한 번만 센다. resumable runtime은
part마다 최종 결과 하나를 `UPLOAD_PART`로 남기고, 그 part에 쓴 시도 수를
`countBucket`에 넣는다(retry bucket). presigned 실행기의 PUT 시도 하나하나는
`PRESIGNED_TRANSFER`로 따로 남는다(`resumable-upload-runtime.ts`
`transferMissingParts`, `presigned-transfer-executor.ts` `uploadParts.put`).
## 8. 조합 조건
현재 `src/adapters/browser-transfer/index.ts`는 개별 presigned, upload와 Image CDN
@@ -618,7 +618,8 @@ stream + epoch별 `lastAppliedSequence`를 기준으로 처리한다.
| `sequence == lastApplied + 1` | 순차 적용 |
| `sequence > lastApplied + 1` | gap; delta 적용 중지, `RESYNC_REQUIRED` |
| unknown `streamEpoch` | old/new epoch를 섞지 않고 registered snapshot 또는 session rebuild |
| dedupe/queue ceiling 초과 | 임의 eviction 후 계속 적용하지 않고 registered recovery |
| dedupe window 가득 참 | 가장 오래된 항목부터 제거(FIFO)하고 계속 적용. 창에서 밀려난 재전송은 `sequence <= lastApplied`로 drop |
| queue ceiling 초과 | 임의 eviction 후 계속 적용하지 않고 registered recovery |
| captured old runtime generation | late callback safe drop + aggregate diagnostic |
| current connection의 `scopeBinding` mismatch | effect/sequence/cursor 0, freshness `UNKNOWN`, close + session revalidation + registered recovery |
@@ -763,21 +764,39 @@ effectiveDelay = max(localDelay, validServerNotBefore)
bound로 취급한다. `effectiveDelay`가 implementation max delay나 남은 elapsed
budget을 넘으면 낮춰 clamp하지 않고 reconnect/poll을 종료해
`DEGRADED`/`STALE`로 전환한다.
- connection이 잠깐 열렸다는 이유로 attempt를 0으로 만들지 않는다. stable-open
window 또는 valid heartbeat/event 뒤에만 reset한다.
- connection이 잠깐 열렸다는 이유로 attempt를 0으로 만들지 않는다. valid
heartbeat/event를 받았고 stable-open window도 지났을 때만 attempt 수와
elapsed budget을 reset한다(둘 중 하나만으로는 reset하지 않는다,
`reconnect-policy.ts:131-149`). 이 확인은 server close뿐 아니라 offline과
`waitClosed` throw를 포함한 session의 모든 종료 경로에서 한다
(`reconnect-coordinator.ts:886-900`). valid heartbeat는 SSE `onComment`와
WebSocket `HEARTBEAT_ACK` 관측이다. 조합 코드가 이를
`markValidHeartbeatOrEvent`로 넘긴다.
- stream reconnect는 realtime recovery coordinator, credential recovery는
session owner, Poll attempt 사이 cadence는 poll coordinator가 각각 소유한다.
Poll-bound REST transport retry와 Query retry는 끈다. 같은 logical recovery의
effect writer나 timer가 둘 이상 활성화되지 않게 generation으로 배타화한다.
- `offline` 상태에서는 timer로 재시도하지 않고 online hint를 기다린다.
`navigator.onLine`은 실제 backend reachability authority가 아니다.
offline 대기 시간은 elapsed budget에 넣지 않는다. online으로 돌아오면
elapsed budget을 다시 시작하고 attempt 상한은 유지한다
(`reconnect-coordinator.ts:550-559`).
- auth expiry는 session owner의 single-flight recovery를 한 번 요청한다.
실패하면 `AUTH_REQUIRED`로 멈춘다.
- protocol/schema/forbidden/policy failure는 retry하지 않는다.
- 외부 close/result의 rate limit/provider unavailable은 유효한 bounded server
not-before hint가 있을 때만 재시도한다. hint가 없거나 ceiling 밖이면
terminal이다. adapter 내부 provider throw처럼 server 응답이 아닌 실패만
남은 retry budget 안에서 local full-jitter를 사용할 수 있다.
- 재시도 여부는 transport가 보고한 `retryable`이 정한다. reconnect
coordinator는 retryable인 `CONNECT_TIMEOUT`·`IDLE_TIMEOUT`·`OFFLINE`·
`PROVIDER_UNAVAILABLE`·`RATE_LIMITED`를 server hint가 없어도 남은 budget
안에서 local full-jitter로 재시도한다(`reconnect-coordinator.ts:1582-1593`).
server hint가 꼭 필요한 실패는 transport가 hint 없을 때 `retryable: false`로
보고해 terminal이 된다. SSE `429`/`503`에 유효한 `Retry-After`가 없을 때
(`sse/fetch-sse-connection.ts:592-616`)와 WebSocket `OVERLOADED`
(`websocket/websocket-connection.ts:1818-1823`)가 여기 해당한다. SSE
`502`/`504`와 WebSocket `RESTART`·`NETWORK_LOST`는 hint 없이 bounded
재시도한다. hint가 있으면 not-before bound이고, ceiling을 넘으면 terminal이다.
SSE `Retry-After`는 `onRetryHint`로만 나오므로 `readSseForReconnect`로 읽어야
reconnect coordinator의 `serverNotBeforeMs`에 닿는다
(`sse/fetch-sse-connection.ts:488-506`).
- budget을 소진하면 infinite reconnect가 아니라 `DEGRADED`와 명시된 fallback
또는 stale UI로 전환한다.
@@ -801,6 +820,17 @@ attempt당 상한은 30초다.
### 5.4 Visibility, page lifecycle와 network
5.4~5.6의 "기본 동작"은 조합 코드가 해야 하는 일이다. reference runtime은 이
동작을 강제하지 않는다.
- reconnect coordinator가 따르는 환경 신호는 online 하나다
(`reconnect-coordinator.ts:106-113`). SSE와 WebSocket 연결에는 visibility 입력이
없다. visibility를 직접 듣는 것은 polling뿐이다
(`polling/bounded-poll-coordinator.ts:202-205`).
- registry의 `hiddenPolicy`, `killSwitchId`, `fallback`은 검증만 하고 읽지 않는다
(`src/contracts/realtime-streams.ts:74-79`). hidden·`pagehide`·logout 때 닫기,
kill switch, fallback 전환은 조합 코드가 한다.
| signal | 기본 동작 |
| --- | --- |
| `visibilitychange -> hidden` | 새 Polling 중지, configured grace 뒤 live connection pause/close |
@@ -844,10 +874,17 @@ session authority announces local transition
late socket event, poll response, auth recovery, snapshot, notification handoff와
Service Worker message는 old generation/scope면 적용하지 않는다.
reference runtime에서 위 흐름의 "close SSE/WebSocket"은 조합 코드가 reconnect
coordinator의 `close()`를 불러야 일어난다. `isCurrent`는 attempt·sleep·waitClosed
경계에서만 확인하므로, 열린 채 조용한 session은 다음 event나 server close까지
남는다(`reconnect-coordinator.ts:175-181`). 그동안 도착한 event는 stream
coordinator의 scope fence가 막는다.
long-lived connection은 connect-time authorization만 신뢰하지 않는다. backend는
active subscription의 permission/session revoke를 control event 또는 close로
전파하고, registry-owned `maxConnectionAge`/reauth deadline 안에 current
credential로 재연결하게 한다. SSE처럼 별도 subscribe command가 없는 transport는
credential로 재연결하게 한다. `maxConnectionAge`는 아직 registry 필드가 아니다.
채택하는 제품이 조합 코드에서 정한다. SSE처럼 별도 subscribe command가 없는 transport는
권한 변경 시 server가 stream을 종료해야 한다. server hint는 client hard
connection-age ceiling을 늘릴 수 없다.
@@ -873,7 +910,7 @@ best-effort hint다.
- tab 하나당 selected primary transport physical connection 1개
- WebSocket logical subscription multiplexing 또는 SSE single-feed local dispatch
- hidden tab close/pause 정책
- hidden tab close/pause 정책(조합 코드가 적용한다. 5.4 참조)
- visible 복귀 시 authoritative snapshot
SharedWorker나 leader election으로 origin 전체 connection을 하나로 만드는 기능은
@@ -1004,8 +1041,8 @@ Last-Event-ID = approved current cursor, CURSOR profile only
| `401` | session recovery 한 번, 실패 시 `AUTH_REQUIRED` |
| `403` | `FORBIDDEN`, retry 금지 |
| `409`/`410` with exact reset contract | cursor expired, snapshot resync |
| `429` | bounded `Retry-After`, retry budget 소비 |
| `502`/`503`/`504` | bounded provider backoff |
| `429`/`503` | 유효한 `Retry-After`가 있으면 그 시각 이후 bounded 재시도, retry budget 소비. 없거나 상한 밖이면 terminal |
| `502`/`504` | hint 없이 bounded provider backoff |
| redirect, wrong type, malformed stream | protocol/policy failure, fail-closed |
generic HTTP client의 전체-body decoder와 retry를 우회하되 credential, diagnostics,
@@ -1148,7 +1185,7 @@ closed category로 mapping한다.
| --- | --- | --- |
| `NORMAL` | intentional close/drain | 아니오 |
| `RESTART` | server deploy/restart | bounded |
| `OVERLOADED` | server capacity/rate | exact server hint가 있을 때만 bounded; 없으면 terminal |
| `OVERLOADED` | server capacity/rate | exact server hint가 있을 때만 bounded; 없으면 terminal. 현재 closed protocol에는 hint 필드가 없어 항상 terminal이다 |
| `AUTH_REQUIRED` | session expired | single-flight recovery 뒤 한 번 |
| `FORBIDDEN` | policy/authorization | 아니오 |
| `PROTOCOL_MISMATCH` | version/schema/subprotocol | 아니오 |
@@ -1279,6 +1316,16 @@ user opt-in
`matchAll()`이 signal을 따르지 않거나 `waitUntil()`이 동기 예외를 내도 늦은
`postMessage`를 허용하지 않고 degraded observation으로 닫는다.
- re-subscribe가 실패하면 notification을 끄고 foreground fallback을 유지한다.
- 여러 tab은 native subscription(worker registration당 1개)과 origin의 fence
record를 공유한다. 그래서 `enable`·`reconcile`·`revoke`는 origin 단위 Web Lock
`web-push-control` 안에서 하나씩 실행한다. `inspect`는 읽기만 하므로 lock을
잡지 않는다. composition이 `navigator.locks`를 `lockManager`로 넘기고, Web
Locks가 없으면 `PUSH_UNSUPPORTED`로 보고한다
(`src/adapters/web-push/push-subscription-adapter.ts`의 `exclusive`,
`supportReadiness`). activate 실패나 session binding 불일치의 보상은 backend
association을 revoke하지만 native `unsubscribe()`는 그 호출이 새로 만든
subscription에만 한다. 이미 있던 subscription은 다른 tab의 association일 수
있다(`activateCommit`, 06-02).
`associationEpoch`은 backend registration authority가 발급한다.
`releaseEpoch`은 signed/verified release manifest에서 온다. backend registration
@@ -1298,6 +1345,26 @@ logout/account switch:
찾아 best-effort close한다.
6. 새 account opt-in은 기존 consent와 association 정책을 다시 평가한다.
logout 없이 account가 바뀐 경우(session 만료, cookie 삭제, logout 중 crash)에는
새 session이 이전 authority를 모른다. 그래서 `revoke`를 부를 수 없고, `enable`과
`reconcile`은 `STALE_AUTHORITY`로 막힌다. 이때는 `revokeForeign({ nextAuthority })`
를 한 번 부른다(`src/application/ports/out/web-push-control.ts`). 다른
`fenceGeneration`이 가진 fence를 `nextAuthority`의 `REVOKED`로 회전하고, 그 fence가
갖던 association을 revoke하고, native subscription과 그 association의 notification을
위 1~5 순서로 정리한다. 그 뒤 새 account의 opt-in이 가능하다. `nextAuthority`의
`fenceGeneration`이 이미 가진 fence(같은 session의 다른 tab이 opt-in한 경우 등)는
건드리지 않고 `inspect` 결과를 돌려준다(`push-subscription-adapter.ts`
`revokeForeign`, 06-06). 이 연산은 저장된 authority를 증명으로 요구하지 않는다.
그래서 BFF가 방금 확인한 현재 session의 authority로만 부른다. 오래된 session을 가진
tab이 부르면 현재 account의 association을 revoke하게 된다.
Web Push를 채택하려면 server 쪽에 다음 두 가지가 있어야 한다. 비정상 전환에서
client revoke가 늦거나 실패해도 이전 account의 push를 막는 것은 이 둘뿐이다.
- 짧은 association TTL: 갱신되지 않은 association은 server가 스스로 만료시킨다.
- send-time authorization: 보낼 때마다 association의 account와 session binding이
아직 유효한지 확인한다.
backend revoke가 ambiguous하면 server subscription은 짧은 association TTL,
session/account epoch 확인과 send-time authorization으로 추가 방어한다.
local `REVOKED` transaction이 실패하면 “late push를 반드시 drop했다”고 주장하지
@@ -1411,6 +1478,20 @@ Service Worker는 언제든 종료될 수 있다. in-memory cursor, queue, auth
timer를 authority로 사용하지 않는다. `waitUntil`도 무제한 lifetime을 보장하지
않으므로 large fetch, retry loop, data migration을 넣지 않는다.
**조용한 drop은 설계 의도다(D-14).** 검증에 실패한 push(EXPIRED,
RELEASE_MISMATCH, association mismatch, fence 읽기 실패, handler deadline 초과,
malformed/unknown)는 알림을 띄우지 않고 끝난다. 계정 정보가 없는 generic
알림으로 대신 띄우지 않는 이유는 logout·계정 전환 뒤에 도착한 push가 어떤
형태로든 사용자에게 보이면 안 되기 때문이다. 대가는 두 가지다.
- Chrome은 `userVisibleOnly` push가 알림 없이 끝나면 "This site has been updated
in the background" 같은 기본 알림을 대신 띄울 수 있다.
- Safari(WebKit)는 알림 없는 push가 반복되면 구독을 취소할 수 있다.
그래서 drop은 드물어야 한다. backend는 ACTIVE association에만 보내고, 짧은
server TTL을 쓰고, release를 바꾼 직후에는 이전 release epoch로 보내지 않는다.
drop은 `web_push_hint_processed`의 `FAILED` + reason으로 관측한다.
### 8.5 Notification content와 click
- title/body/icon/action은 closed notification registry가 만든다.
@@ -1438,8 +1519,17 @@ type NotificationClickDataV1 = Readonly<{
worker가 종료·재시작된 뒤에도 click을 처리할 수 있도록 이 bounded, non-sensitive
envelope만 `NotificationOptions.data`에 넣는다. click handler는 codec/size/expiry,
current local `ACTIVE` fence와 release epoch를 다시 검증한다. unknown/mismatch는
route를 열지 않고 notification을 닫는다. 이미 표시된 notification은 logout 뒤
current local `ACTIVE` fence와 release epoch를 다시 검증한다. unknown/mismatch
(만료, fence·release 불일치, fence 읽기 실패, 모르는 route)는 notification을 닫고
요청한 route 대신 **앱 루트를 handoff 데이터 없이 연다**(D-14). 앱 루트는 worker의
`registration.scope`, 즉 router base path다(예: `/app/`). scope를 모르면
`<origin>/`을 쓴다(`src/adapters/web-push/service-worker-scope-host.ts`,
`inbound/notification-click-adapter.ts`의 `appRootUrl`, 06-09).
사용자의 탭이 아무 반응 없이 사라지지 않게 하되, 거절된 click의 route와
notification 정보는 페이지로 넘기지 않는다. 결과는 여전히 실패로 보고하고
(`web_push_click_dispatched` `FAILED` + reason, `nativeEffect`는 루트 창의
확실성), 브라우저가 창 열기를 거절한 native 실패나 deadline/abort 뒤에는 루트를
다시 시도하지 않는다. 이미 표시된 notification은 logout 뒤
OS notification center에 남을 수 있으므로 copy는 항상 account-neutral하고
민감하지 않아야 하며, `getNotifications()` cleanup 성공을 privacy 보장으로
과장하지 않는다.
@@ -1709,7 +1799,7 @@ task는 run을 fail-closed로 끝내되 underlying task가 settle할 때까지 l
`DRAINING`으로 유지하여 다음 physical connection을 허용하지 않는다.
미선택 reference source 전체를 tree-shaking 없이 합성하는 optional-recipe
측정의 gzip 상한은 40,000 bytes다. 이 값은 production bundle 허용량이 아니라
측정의 gzip 상한은 40,900 bytes다(2026-09-27 성숙도 리뷰 04-x·06-x 반영 뒤 측정값 40,886을 100바이트 단위로 올림). 이 값은 production bundle 허용량이 아니라
RT-01~RT-04 reference runtime의 회귀 예산이며, production asset에는 계속
미선택 realtime module이 0이어야 한다.
@@ -1828,6 +1918,13 @@ drop-only malformed 처리는 명시적으로 non-state-bearing heartbeat/contro
허용하며, threshold를 넘으면 protocol close한다. state-bearing event나 unknown
event type을 버리고 freshness를 `CURRENT`로 유지하지 않는다.
stream을 찾은 뒤 decode가 실패하면 consumer가 그 stream의 freshness를 `UNKNOWN`으로
바꾼다. 다음 event는 recovery부터 한다(`event-consumer.ts:89-90`,
`stream-coordinator.ts:998-1001`). registry에 없는 event type은 `MALFORMED_EVENT`가
아니라 `PROTOCOL_MISMATCH`(operation `REGISTRY`)로 닫는다(`event-codec.ts:172-175`).
event type 추가는 이전 bundle에는 호환 변경이 아니다. 조합 코드는 operation
`REGISTRY` 실패를 "구버전 client"로 보고 reload를 유도한다.
### 13.2 Effect certainty
| effect | certainty |
@@ -1883,6 +1980,23 @@ push:
- `web_push_click_dispatched`
- `web_push_association_revoked`
reference runtime의 관측 지점은 다음과 같다. 조합 코드는 attempt나 session을
감싸지 않고 이 관측을 위 event로 옮긴다.
| runtime 관측 | 만들 수 있는 event |
| --- | --- |
| reconnect `ATTEMPT_STARTED` | `realtime_connect_attempted` |
| reconnect `SESSION_OPENED`, 또는 open 전의 `RETRY_SCHEDULED`·`RUN_ENDED` | `realtime_connect_finished` |
| reconnect `SESSION_CLOSED` | `realtime_connection_closed` |
| reconnect `RETRY_SCHEDULED`(실패 kind, 대기 bucket), `RUN_ENDED`(`EXHAUSTED`·`TERMINAL`·`ABORTED`·`COMPLETED`) | 14.2 재연결 시도·대기·소진 비율 |
| WebSocket `HEARTBEAT_ACK` | `realtime_heartbeat_observed` |
| polling `LEASE_STARTED`, `ATTEMPT_FINISHED`(`VALUE`·`UNCHANGED`·실패 kind), `LEASE_STOPPED` | `bounded_poll_*` |
근거는 `reconnect-coordinator.ts:128-182`,
`polling/bounded-poll-coordinator.ts:87-113`,
`websocket/websocket-connection.ts:376-378`이다. sink가 throw해도 제어 흐름은
바뀌지 않는다(`result.ts`의 `observeRealtime`).
모든 event는 semantic registry에 등록하고 arbitrary payload를 받지 않는다.
diagnostics sink failure는 connection, worker handler, poll lease와 cleanup을
실패시키지 않으며 재귀 telemetry를 만들지 않는다.
@@ -1919,7 +2033,7 @@ server-side metric을 함께 사용한다.
- CURSOR/non-CURSOR discriminated codec와 conditional cursor commit
- effect failure 뒤 cursor 미commit
- deterministic fake clock/random의 full-jitter backoff
- stable-open 이후에만 retry attempt reset
- valid heartbeat/event와 stable-open을 둘 다 충족한 뒤에만 retry attempt reset
- queue/dedupe/reorder ceiling
- old-generation late callback drop와 current scope-binding protocol violation 분리
- effect/recovery callback lease의 `isCurrent()` commit 직전 확인과 callback
@@ -280,6 +280,18 @@ chunk recovery 순서:
4. 안전한 support surface와 trace/build ID를 표시한다.
5. recovery 결과를 redacted diagnostics에 기록한다.
지원 참조는 사용자가 문의할 때 말하는 값이고, 진단 이벤트에서 같은 값을 찾을
수 있다.
- 라우트 렌더 실패: `buildId:incidentId`. 같은 incident ID가 `ui.render.failed`
진단의 `correlation_id`에 남는다(`render-error-boundary.tsx`의
`newIncidentId`, `create-application.ts`의 `reportRenderFailure`). 화면에는
"한 번 새로고침" 버튼이 있다(`app-router.tsx`의 `RouteFailureSurface`).
- 복구하지 못한 청크 실패: 같은 형식이다. `ChunkRecoveryBoundary`의
`onUnrecovered`가 같은 ID로 `ui.render.failed`를 기록한다.
- 조회 실패: `AppFailure.requestId`. HTTP 진단의 `correlation_id`와 같은 값이다
(`async-surface.tsx`의 `TerminalErrorSurface`).
custom fallback을 넘겨 retry/reset 기능을 잃지 않게 한다. boundary는
`location.key` 또는 route ID가 바뀌면 적절히 reset된다.
@@ -289,9 +301,15 @@ custom fallback을 넘겨 retry/reset 기능을 잃지 않게 한다. boundary
- mouse 사용자가 불필요한 focus ring을 보지 않게 할 수는 있지만 keyboard focus
indication을 전역으로 제거하지 않음
- modal/drawer가 닫히면 opener에 focus 복원
- backward/forward navigation은 저장한 scroll 복원
- backward/forward navigation은 저장한 scroll 복원. 복원은 브라우저가 하고,
`RouteLifecycle`은 POP이 아닐 때만 top으로 보낸다(`app-router.tsx`).
`PageHeader`의 heading focus는 `preventScroll`이라 복원된 위치를 옮기지 않는다
- 새 primary route는 top으로 이동
- hash target은 fixed header offset과 focus 가능 여부를 처리
- hash target은 fixed header offset과 focus 가능 여부를 처리. 페이지가 그려진 뒤
`PageHeader`가 대상으로 스크롤하고, 대상이 focus 가능하면 대상에, 아니면
heading에 focus한다(`page-header.tsx`). header 높이는 `html`의
`scroll-padding-top`으로 뺀다(`shell.css`). 브라우저 검증은
`tests/e2e/scroll-restoration.spec.ts`
- screen reader용 route title/live announcement는 중복 발표를 피함
### 6.4 취소와 dirty form
+103 -25
View File
@@ -26,14 +26,10 @@ remain stable in the shell.
## Registered routes
| ID | Path | Access | Surface |
| --- | --- | --- | --- |
| `APP_HOME` | `/` | public | readiness dashboard |
| `EXAMPLES_UI` | `/examples/ui` | public | interactive primitives and tokens |
| `EXAMPLES_STATES` | `/examples/states` | public | async and access state matrix |
| `EXAMPLES_AUTH` | `/examples/auth` | public | session integration controls |
| `REFERENCE_RESOURCE_LIST` | `/examples/reference-resources` | session-required | removable vertical slice |
| `NOT_FOUND` | `*` | public | safe navigation recovery |
The route list is `ROUTE_REGISTRY` (`src/features/installed-feature-contracts.ts`):
the platform routes of `src/contracts/routes.ts` plus the routes of every
installed feature. The platform overview page (`/examples/platform`) shows the
composed list at runtime, so this document does not keep a copy of it.
Navigation labels and order come from `ROUTE_REGISTRY`; the sidebar does not
maintain a second route list. The client access decision never claims to be
@@ -49,31 +45,113 @@ remain opaque to the application and presentation layers.
- `external`: delegates to `globalThis.__CA_FRONTEND_AUTH_OWNER__`
- missing/invalid external owner: fails closed as `integration-failed`
An external owner implements `readState`, `subscribe`, `beginSignIn`,
`signOut`, `attachCredential`, `recoverSession`, and
`notifyUnauthenticated`. It owns token acquisition and storage.
An external owner implements `readState`, `readSubject`, `subscribe`,
`beginSignIn`, `signOut`, `attachCredential`, `recoverSession`, and
`notifyUnauthenticated`. It owns token acquisition and storage. An owner that
lacks any of these methods is rejected, and the session fails closed as
`integration-failed`.
`readSubject()` is required. The server-state cache is cleared only when the
session state or the subject changes, so a token refresh for the same user
keeps cached data. `readSubject()` must return:
- an opaque, non-empty string that stays the same for one user across token
refreshes and differs between users: the OIDC `sub` claim, Supabase
`session.user.id`, or Firebase `user.uid`
- `null` when nobody is signed in
- never an access token, refresh token, or any other credential
If `readSubject()` returns `null` or `""` while the owner reports
`authenticated`, the runtime cannot tell a refresh from an account switch. It
fails closed: every such notification clears server state, and each one records
the `cache.operation.failed` diagnostic with `operation: SCOPE_FENCE` and
`reason: SUBJECT_MISSING`. Seeing that diagnostic means the owner is not
reporting its subject. The `demo` adapter reports one fixed demo user as its
subject.
Migration: `readSubject()` used to be optional. An owner written for an earlier
release must add it; without it the owner is rejected at startup (the session
becomes `integration-failed`) and a TypeScript owner no longer compiles
against `ExternalSessionOwner`. A code path that implements `AuthSessionPort`
or `SessionGateway` directly must add `getSubject()` the same way.
## Extending the starter
The steps below describe the current extension path. New platform work should follow
New platform work should follow
[routing, page templates, and reusable patterns](./routing-pages-and-patterns.md)
and the
[TypeScript, state, and data-flow target](./typescript-state-and-data-flow.md)
rather than adding another independent route or data-loading convention.
1. Add a serializable contribution under the feature ownership boundary and
install it through `src/features/installed-feature-contracts.ts`.
2. Add the lazy component and route codecs through
`src/features/installed-feature-runtimes.tsx`.
3. Compose feature application inputs and outbound gateways only through
`src/features/installed-feature-adapters.ts`.
4. Use the semantic tokens, UI primitives, and state surfaces before adding a
project-specific variant.
5. Add component behavior, all-engine E2E, automated axe, and signed manual
route evidence.
6. Run `test:sample-removal` to prove the generic starter typechecks, passes
architecture/registry/tests/coverage/source-evidence/home smoke, and builds
without the complete reference feature.
### Ownership declarations
Features, contexts and apps are discovered by
`scripts/generate-product-feature-index.ts`. Each boundary declares only its
parent, as exported string or integer literals the generator reads:
| File | Exports |
| --- | --- |
| `src/apps/<app>/app-module.ts` | `APP_MODULE_ID`, `APP_MAX_CONTEXTS` |
| `src/contexts/<context>/context-module.ts` | `CONTEXT_MODULE_ID`, `CONTEXT_APP_ID`, `CONTEXT_ROUTE_PATH`, `CONTEXT_MAX_FEATURES` |
| `src/features/<feature>/feature-module.ts` | `FEATURE_MODULE_ID`, `FEATURE_CONTEXT_ID`, `FEATURE_MODULE` |
| `src/features/<feature>/context-routes.ts` | `FEATURE_CONTEXT_ROUTES` |
The generator writes `src/.generated/` (git-ignored): the feature index the
installed catalogs import, the context index the router loads lazily, and the
selected app. Every build and check script runs it first; run it yourself with
`corepack pnpm generate:feature-index`. It fails, naming the file, when:
- a directory under `src/features/` has no `feature-module.ts` and no
`NOT_INSTALLED` marker file (`src/features/local-draft-feature/NOT_INSTALLED`
is the one intentional example);
- a feature names an undeclared context, or a context an undeclared app;
- a context or app exceeds its declared budget;
- `VITE_PRODUCT_FEATURES` names a feature the app does not declare. The
variable narrows the installed set here, before anything is compiled.
### Adding a feature
1. Create `src/features/<feature>/feature-module.ts`. Build `FEATURE_MODULE`
with `defineFeatureModule` (`src/features/feature-module.ts`): the feature's
contract (routes, route runtime contracts, API operations, invalidation,
schemas, runtime schemas, mappers), its adapter contributions
(`defineFeatureAdapterContribution`, with `needs` naming the platform
capabilities it receives), its runtime descriptor (route codecs), its message
catalogs and its contract contributions.
`src/features/reference-feature/feature-module.ts` is the complete example.
2. Create `src/features/<feature>/context-routes.ts` exporting
`FEATURE_CONTEXT_ROUTES`. Page components are imported lazily here; the
owning context loads this file only when its route root is visited
(`src/features/reference-feature/context-routes.ts`).
3. Name the owning context in `FEATURE_CONTEXT_ID`. Use an existing context or
add `src/contexts/<context>/context-module.ts` owned by the app.
4. If the feature has application input, augment `ApplicationFeatureInputs`
from the feature (`src/features/local-draft-feature/application/local-draft-api.ts`).
5. Run `corepack pnpm check:architecture`, `corepack pnpm check:types`,
`corepack pnpm check:registries` and the tests. `tests/unit/two-feature-install-typecheck.test.ts`
keeps the installed catalogs compiling with more than one feature.
6. Run `corepack pnpm test:sample-removal -- --feature=<feature id>` to prove
the product still builds and passes its gates without the feature.
Files outside the feature directory:
| File | Change |
| --- | --- |
| `src/.generated/*` | regenerated automatically |
| `src/contexts/<context>/context-module.ts` | only when the feature needs a new context |
| `config/runtime/<profile>.json` | optional `FEATURE_OVERRIDES` entry to switch the feature off |
| `src/bootstrap/runtime-adapters.ts` | only when `needs` includes `indexedDb`: add the capability, built as in `recipes/frontend-capabilities/indexeddb-feature-capability.ts` |
The central catalogs (`src/features/installed-*.ts`) and the registry
governance file do not change: consumer directories there are globs over every
feature (`src/features/*/adapters`, `config/contracts/registry-governance.json`).
### Before shipping
- Use the semantic tokens, UI primitives, and state surfaces before adding a
project-specific variant.
- Add component behavior, all-engine E2E, automated axe, and signed manual
route evidence.
Theme preference is the public `COLOR_SCHEME` storage contract. Authentication
tokens and other secrets remain forbidden storage keys.
+5
View File
@@ -29,5 +29,10 @@ sequenceDiagram
CI->>Browser: boot, route, API, and reload-loop smoke
```
In this repository the workflow stops at promotion. The upload, pointer switch
and smoke steps above belong to the project's provider adapter; after it has
deployed the promoted release, FE-GATE-019 probes the live headers (review
13-05, [`release-cache-rollback.md`](../operations/release-cache-rollback.md)).
Rollback changes the active pointer only after confirming that the prior
immutable release has a coherent HTML/assets/config/API/manifest tuple.
@@ -52,7 +52,9 @@ TypeScript 전환 목적은 확장자 변경이 아니라 이 계약을 컴파
1. ESLint가 product와 negative fixture의 `ts`/`tsx`를 모두 검사한다.
2. React Hooks 규칙을 추가하고 TypeScript/ESLint parser와 JSX accessibility
도구는 설치된 compiler/linter의 공식 peer 범위 안에서 선택한다.
3. dependency-cruiser의 extension과 resolver가 TS/TSX를 포함한다.
3. `check:architecture`의 import 그래프가 TS/TSX를 해석한다. 규칙은
`.dependency-cruiser.json`에 있지만 dependency-cruiser는 실행하지 않는다.
TypeScript 7을 해석하지 못해 0개 모듈을 검사했기 때문이다(리뷰 12-05).
4. `scripts/check-registries.ts`가 TS/TSX를 검색한다.
5. `config/contracts/registry-governance.json`과 승인 baseline은 `.ts/.tsx`
source 경로를 사용한다.
@@ -597,6 +599,7 @@ Form 또는 TanStack Form adapter를 평가한다.
- `Description`
- `FieldError`
- `ErrorSummary`
- `FormFailureStatus` (재로그인·권한 없음·잠시 후 재시도·그 밖의 저장 불가 실패)
- `useAppForm`
- `mapValidationFailureToFields`
- `useDirtyNavigationGuard`
@@ -620,6 +623,7 @@ backend message와 알 수 없는 path는 field copy로 사용하지 않는다.
3. submitting 중 중복 제출 방지
4. 422 응답의 알려진 field만 표시하고 나머지는 form-level failure로 처리
5. 409 conflict는 validation error로 위장하지 않음
5a. 401·403·429와 404 같은 입력 외 실패는 ErrorSummary가 아니라 `FormFailureStatus`로 표시(`use-app-form.ts`의 `STATUS_RESULTS`)
6. 취소와 route 이탈 시 dirty policy 적용
7. form value → application command mapper를 별도 함수로 둠
8. browser autofill, IME composition, paste, password manager를 방해하지 않음
+55 -2
View File
@@ -3,13 +3,66 @@
The blocking tuple is `(buildId, configSchemaVersion, apiContractVersion,
assetManifestHash, releaseId)`. Versions are parsed numerically.
1. additive changes preserve current required fields
2. breaking changes require a major version bump
1. a change is additive only when it adds an optional field that every
reader of the previous version tolerates; see the boundary table below
2. breaking changes require a major version bump or a reader-first deployment
3. persisted cache is discarded unless an explicit tested migration exists
4. an incompatible config or API contract blocks product mount
5. rollback restores HTML, assets, runtime config, API compatibility, and
release manifest as one coherent set
## Per-boundary rules
Whether "add a field" is safe depends on the reader, not on the writer. Old
readers stay alive: several tabs, cached app shells and rollbacks are all
supported. At a `REJECT_UNKNOWN` boundary an added field is breaking, so the
reader that accepts it must ship before any writer sends it.
| Boundary | Reader policy | Adding a field or value | Code |
|---|---|---|---|
| Runtime config V2 (`/config.json`) | strict object; `CONFIG_SCHEMA_VERSION` is the literal `"2.0"` | breaking | `src/contracts/release-artifacts.ts:163-171` |
| `CAPABILITY_OVERRIDES` | strict; unknown capability rejected | breaking | `src/contracts/release-artifacts.ts:50-63` |
| `FEATURE_OVERRIDES` | record; unknown feature id ignored | additive | `src/contracts/release-artifacts.ts:65-80` |
| Release manifest V2 | strict object | breaking | `src/contracts/release-artifacts.ts:200-208` |
| HTTP V2 success/failure envelope | strict object (`meta` strips) | breaking | `src/adapters/http/schema-registry.ts:12-34` |
| HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `src/features/reference-feature/contracts/reference-schemas.ts:29-35` |
| Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `src/adapters/realtime/event-codec.ts:126,149` |
| Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `src/adapters/browser-rpc/browser-rpc-runtime.ts:1473` |
| Persisted client storage | versioned key; incompatible value discarded | use a new key version | `src/contracts/storage-keys.ts:138-140` |
`CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` differ on purpose. Feature ids
vary per build because each downstream project installs its own features, and
one shared config document may cover several builds. The capability set is
fixed by the platform version, so an unknown capability means the config was
written for a newer platform; it is treated like any other strict config
addition.
## Schema change classifier and FE-GATE-014
`classifyObjectSchemaChange` (`src/contracts/compatibility.ts:110`) answers
for a reader built against `before`. It is fail-closed: only a new property
under a reader without `additionalProperties: false` is `additive`. A removed
or changed property (type, enum, nullable, format, ...), a different required
set, or any other changed keyword is `breaking`. Nothing differs: `none`.
FE-GATE-014 (`config-compatibility`, `corepack pnpm verify:compatibility`)
runs `scripts/check-compatibility.ts`. It does two things:
1. Classifies the hand-written cases in `config/compatibility/fixtures.json`
and fails if any result differs from `expected`.
2. Compares the committed baseline
`config/compatibility/runtime-config.schema.baseline.json` with the current
runtime config schema, which is the same `z.toJSONSchema` output the build
writes to `dist/runtime-config.schema.json`
(`scripts/generate-build-manifest.ts`). A `breaking` result fails the gate.
The baseline stands for the schema that readers of the previous release
accept. When a breaking config change is intended, deploy the reader first (or
bump the config major version), then run
`corepack pnpm verify:compatibility --update-baseline` and commit the new
baseline with the change. The result is recorded in
`artifacts/release/compatibility.json`.
The current `apiContractVersion` check proves release/config coherence, not
provider conformance by itself. The target multi-protocol contract set binds
REST/OpenAPI artifacts, GraphQL schema and persisted-operation manifests,
@@ -4,7 +4,7 @@
schema/cache 절차 분리
- backend 구조와 handoff:
[Backend API와 Server State contract](../architecture/backend-api-and-server-state-contract.md)
- 기준일: 2026-07-28
- 기준일: 2026-07-28, 1절·5.1·6.0·6.3은 2026-09-25 V3 코드 기준으로 갱신
- 설계:
[API contract, Schema, Mapper와 Server State](../architecture/api-contract-schema-mapper-and-server-state.md)
- browser Protobuf/gateway 설계:
@@ -12,18 +12,28 @@
## 1. 적용 범위
현재 reference REST → Schema → Mapper → TanStack Query vertical은 `COMPOSED`다.
하지만 다음 target delta는 아직 `DESIGNED_NOT_IMPLEMENTED`다.
현재 reference REST → Schema → Mapper → TanStack Query vertical은 V3 contract
executor(`src/adapters/http/http-execution-v3.ts`)로 `COMPOSED`다. 조합 위치는
`src/bootstrap/runtime-adapters.ts`의 `createContractHttpExecutor`다. 이 문서의
"current v1"은 V2 client(`src/adapters/http/client.ts`) 시절에 쓴 말이다. V2는
기본 조합에 없다(`createRuntimeHttpClient` 호출처 없음).
- REST v2 auth fail-close/final invariant
- total logical deadline와 bounded response decoder
- complete cursor/conditional request
- typed schema/mapper registry
- strict query/mutation definition과 concurrency coordinator
- GraphQL reference adapter
- Connect-Web reference adapter
- gRPC-Web reference adapter
- Protobuf REST Gateway
2026-09-25 코드 기준 상태:
| 항목 | 상태 | 코드 위치 |
| --- | --- | --- |
| auth fail-close / final request invariant | 구현됨. 자격증명 없음·owner 장애·scope 불일치면 fetch 0회. 전송 직전 최종 요청을 다시 검사 | `runtime-adapters.ts` `attachCredentials`, `http-execution-v3.ts` credential patch 처리, `src/adapters/http/http-contract-bridge.ts` `checkFinalInvariants` |
| total logical deadline | 구현됨. 자격증명·lease·fetch·본문·backoff가 마감 하나를 공유. `REQUEST_TIMEOUT_MS`는 상한 | `http-execution-v3.ts` `effectiveDeadlineMs`, lifetime signal |
| bounded response decoder | 구현됨. 선언 길이 → 스트림 바이트 → JSON 구조 → 스키마 순 | `src/adapters/http/bounded-body-reader.ts`, `bounded-json.ts`, `http-execution-v3.ts` `admitResponse` |
| typed schema/mapper | 구현됨. 계약별 input/output/problem validator와 feature mapper | `src/contracts/external-contract-runtime.ts`, `src/adapters/http/feature-http-binding.ts` |
| strict query/mutation definition과 concurrency coordinator | 구현됨 | `src/contracts/server-state.ts` `bindQuery`·`BoundMutation`, `src/presentation/adapters/query/application-query.ts` |
| 결과 불명 command의 같은 키 재전송 | 구현됨. 사용자가 누를 때만 보낸다 | `application-query.ts` `resendUnknownEffect` (6.3) |
| cursor pagination | runtime만 있다. 설치된 operation이 쓰지 않는다 | `src/adapters/query-cache/cursor-pagination-runtime.ts` |
| conditional request | validator store만 조합됐다. V3는 `If-None-Match`/`If-Match`를 보내지 않는다 | `src/adapters/query-cache/conditional-validator-store.ts` |
| GraphQL reference adapter | 구현 안 됨 | 없음 |
| Connect-Web / gRPC-Web reference adapter | provider 중립 Browser RPC runtime만 있다. 조합되지 않았다 | `src/adapters/browser-rpc/` |
| Protobuf REST Gateway | 구현 안 됨 | 없음 |
| operation별 `TrafficAdmission` switch | 구현 안 됨 | 없음 |
GraphQL/Connect/gRPC-Web/REST Gateway 절차는 해당 runtime과 actual provider가
구현·조합된 뒤에만 운영 gate로 활성화한다. 문서나 fake fixture만으로 capability를
@@ -142,11 +152,14 @@ artifact에서 access-controlled하게 비교한다.
### 5.1 Auth-required request가 무자격으로 전송됨
현재 v1은 external auth integration이 unavailable이어도 unchanged request가
전송될 수 있으므로 target v2 전까지 제품 auth-required traffic을 provider
evidence 없이 활성화하지 않는다.
V3는 자격증명이 없거나(`UNAUTHENTICATED`), auth owner가 장애거나
(`integration-failed` → `CREDENTIAL_OWNER_UNAVAILABLE`), scope가 준비되지 않았으면
fetch 없이 끝난다(`src/bootstrap/runtime-adapters.ts` `attachCredentials`,
`src/adapters/http/http-execution-v3.ts` credential patch 처리). 전송 0회 미인증은
diagnostics에만 남고 `api.request.failed`에는 세지 않는다(03-07). 그래도 무자격
전송이 보이면 V3가 아닌 경로(V2 client 직접 조합, 외부 SDK)를 먼저 의심한다.
target 점검:
점검:
1. session state가 authenticated인지 확인한다.
2. auth owner가 `CredentialPatch`만 반환하는지 또는 final request invariant를
@@ -168,26 +181,37 @@ target 점검:
3. cross-origin allow-origin/credentials/method/header/expose가 exact한지 확인한다.
4. wildcard credential, redirect와 unexpected origin을 복구한다.
5. CSRF token/header 값을 ticket에 기록하지 않는다.
6. V3 요청은 논리 실행마다 `x-correlation-id` 하나를 보낸다(재시도도 같은 값,
`src/adapters/http/http-execution-v3.ts` `createRequestId`). cross-origin API면
preflight `Access-Control-Allow-Headers`에 `x-correlation-id`가 있어야 요청이
나간다. 응답의 `x-correlation-id`를 `AppFailure.requestId`와 diagnostics
`correlation_id`로 쓰려면 `Access-Control-Expose-Headers`에도 넣는다
(`src/adapters/http/feature-http-binding.ts` `projectExecutionOutcome`,
`src/bootstrap/runtime-adapters.ts` `createHttpObservationProjector`). telemetry에는
넣지 않는다.
## 6. REST incident
### 6.0 Current v1 available checks
### 6.0 V3에서 바로 쓸 수 있는 점검
1. current per-attempt timeout/bounded retry, Query retry off, AbortSignal과 401
recovery observation을 확인한다.
2. installed request/envelope/payload Zod schema와 mapper failure kind를 확인하되
current `Response.json()`이 body cap 증거가 아님을 기록한다.
1. 전체 마감 하나와 재시도 상한 min(계약 `retryBudget`, `MAX_RETRY_ATTEMPTS`, 2)을
확인한다. TanStack Query 재시도는 꺼져 있다(`http-execution-v3.ts`,
`src/adapters/query-cache/tanstack-query-cache.ts`). 전송별 차이는
[backend contract 16.1절](../architecture/backend-api-and-server-state-contract.md)
표를 본다.
2. 본문은 `bounded-body-reader.ts`가 상한을 적용한 뒤 계약 validator와 feature
mapper를 거친다. 실패 kind로 어느 단계인지 좁힌다.
3. QueryClient/coordinator로 affected read를 cancel/invalidate/clear한다.
4. cursor response/page runtime, APP_ETAG와 total deadline은 아직 없으므로 해당
control을 실행했다고 기록하지 않는다.
5. command effect는 backend와 reconcile한다. basic optimistic snapshot 문제가
의심되면 runtime switch를 가정하지 말고 no-optimistic/known-good release로
rollback한다.
4. cursor runtime과 conditional request는 설치된 operation에 조합되지 않았으므로
해당 control을 실행했다고 기록하지 않는다(1절 표).
5. 문의 식별자는 `AppFailure.requestId`와 diagnostics `correlation_id`로 서버 로그와
잇는다(5.2절 6항).
아래 6.1~6.5는 target v2 coordinator가 해당 operation에 composed된 뒤에만
운영 절차로 활성화한다.
6.1·6.2는 V3 operation에 적용한다. 항목 중 V3에 없는 control은 실행했다고
기록하지 않는다. 6.4·6.5는 해당 runtime이 operation에 조합된 뒤에만 운영 절차로
활성화한다.
### 6.1 Timeout/retry storm — target v2
### 6.1 Timeout/retry storm
1. Query retry가 꺼지고 REST transport 하나만 network retry하는지 확인한다.
2. total logical deadline 안에 auth, fetch, body, mapper, recovery와 sleep이 모두
@@ -202,7 +226,7 @@ target 점검:
7. timer/listener/reader leak가 있는 cohort는 traffic을 닫는다.
8. keyed command는 backend dedupe evidence 없이는 retry를 끈다.
### 6.2 Body/media/schema failure — target v2
### 6.2 Body/media/schema failure
1. final URL/status/content type을 확인한다.
2. present/valid Content-Length advisory preflight와 actual browser-visible decoded
@@ -219,15 +243,24 @@ target 점검:
10. backend/frontend artifact가 coherent하지 않으면 operation traffic을 닫고
N/N-1 compatible set으로 rollback한다.
### 6.3 Idempotency/ambiguous command — target v2
### 6.3 Idempotency/ambiguous command
1. principal/operation/payload digest/key tuple과 backend TTL/status를
access-controlled evidence에서 확인한다.
2. 같은 key + 다른 payload가 거절되는지 확인한다.
3. concurrent same-key request가 duplicate commit을 만들지 않았는지 확인한다.
4. `UNKNOWN` effect에 새 key를 생성해 retry하지 않는다.
5. backend status/receipt로 `COMMITTED`면 cache reconcile/invalidate한다.
6. `NOT_APPLIED`가 증명된 경우만 정책에 따라 retry한다.
4. `UNKNOWN` effect에 새 key를 생성해 retry하지 않는다. 클라이언트는 결과 불명
admission의 intent를 보관하고, 같은 canonical input의 재저장과 "같은 요청으로
다시 보내기"는 그 intent와 같은 `Idempotency-Key`로 보낸다. 입력이 바뀌면 새
key다. 자동 재전송은 없다(`src/presentation/adapters/query/application-query.ts`
`submit`·`resendUnknownEffect`, 화면 `src/presentation/components/async-surface.tsx`).
5. backend status/receipt로 `COMMITTED`면 cache reconcile/invalidate한다. 화면의
"변경됨으로 확인"이 이 경로다.
6. `NOT_APPLIED`가 증명된 경우만 정책에 따라 retry한다. 화면은 근거 없는
"변경되지 않음" 확정을 주지 않고 목록 새로고침 링크를 준다.
7. 한계: 결과 불명 admission은 메모리에만 있다. 새로고침·로그아웃·계정 전환 뒤
같은 입력의 저장은 새 key다. 서버 key 보관 기간이 지난 뒤의 재전송도 중복될
수 있다. 두 경우는 backend 도메인 유일성 제약이나 status 조회로 막는다.
### 6.4 Cursor loop — target v2
+104 -18
View File
@@ -16,15 +16,24 @@ primitive를 coordinator 완료 증거로 사용하지 않는다.
## OPFS 보상 실패와 reconcile (STO-01)
`put()`이 실패했는데 보상 cleanup effect가 확인되지 않으면 runtime은 실패를
`OBJECT_RECONCILE` / `CONFLICT`(recovery `RETRY`)로 보고하고 journal row를 남긴다.
이는 결함이 아니라 설계된 상태다.
`put()`이 commit 전에 실패하면 coordinator가 그 transaction의 staging을 지우고
journal row를 되돌린다(보상). 보상의 worker cleanup이나 journal rollback이 끝나지
않으면 put은 자기 실패 코드(`QUOTA_EXCEEDED`, `ABORTED` 등)와 operation
`OBJECT_WRITE`를 그대로 두고 recovery만 `RECONCILE`로 바꿔 반환한다. journal
row(`PREPARING`/`FILES_READY`)는 남는다(`opfs-byte-store-adapter.ts`
`compensatePreparedPut`, Q-6.5-9). 이는 결함이 아니라 설계된 상태다. worker가
cleanup 결과를 확인하지 못하면 성공 값이 아니라 실패로 답한다. 별도의 "결과 불명"
값은 없다(05-09).
1. journal에 `PREPARING` 또는 `FILES_READY` row가 남아 있는지 확인한다. 남아
있다면 staging bytes가 아직 존재할 수 있다는 뜻이다.
2. `maintenance.reconcile()`을 실행한다. reconcile은 같은 exact physical
generation token만 삭제하고, effect가 여전히 `EFFECT_UNKNOWN`이면 journal을
유지한 채 다시 `OBJECT_RECONCILE`을 반환한다.
2. `maintenance.reconcile()`을 실행한다. reconcile은 exact physical generation
token만 삭제한다. report에서 다음을 본다.
- `skippedLiveTransactions`: 어느 tab에서든 아직 진행 중인 put/delete의 row다.
reconcile은 transaction별 Web Lock을 `ifAvailable`로 잡지 못한 row를 건드리지
않는다(05-01, `reconcile`의 `holdTransactionLock`). 결함이 아니다.
- `failedTransactions`: 이번에 정리하지 못해 journal에 남긴 row 수다. 나머지
row와 orphan GC는 계속 돈다(05-02). 같은 row가 계속 실패하면 §7을 본다.
3. journal row를 수동으로 삭제하지 않는다. row가 사라지면 stale staging을 추적할
근거가 사라지고 quota만 누수된다.
4. OPFS root나 journal database를 통째로 삭제하거나 schema를 downgrade하지
@@ -36,6 +45,9 @@ primitive를 coordinator 완료 증거로 사용하지 않는다.
incident 중에도 다음 작업은 금지한다.
- 자동 또는 일괄 `deleteDatabase()`
- 예외는 하나다. authority가 승인한 LOGOUT/ACCOUNT_DELETION이 손상된
governance 때문에 dataset을 열 수 없을 때, runtime이 그 partition의 DB
하나만 지운다(§5 "database 전체 삭제" 참고).
- origin의 모든 `caches.keys()` 삭제
- user-authored/unsynced IndexedDB 또는 OPFS data 자동 purge
- schema version downgrade
@@ -154,6 +166,12 @@ read-only나 online-only가 사용자 작성 내용을 잃게 한다면 먼저 e
- `versionchange` 뒤 connection이 남음
- repeated reload/update loop
- open/maintenance의 `POLICY_REJECTED`: immutable dataset binding missing/mismatch
- open의 `UNSUPPORTED` / `ONLINE_ONLY`와 status `INCOMPATIBLE`: 더 새 release가
schema를 올린 DB를 이전 bundle이 열었다(05-06). migration 실패가 아니므로 §5로
가지 않는다. 이 bundle은 그 dataset을 읽지도 쓰지도 않고 online-only로
동작하며, 새 release로 reload하면 풀린다
(`indexeddb-runtime.ts` open의 `VersionError` 분기). OPFS journal도 같은 답을
낸다(`indexeddb-opfs-journal.ts` `translateFor`)
### 확인 순서
@@ -170,7 +188,8 @@ read-only나 online-only가 사용자 작성 내용을 잃게 한다면 먼저 e
6. 모든 connection에 `versionchange`/forced-close handler가 설치됐는지 확인한다.
7. BroadcastChannel prepare hint는 참고만 하고 실제 open/connection registry를
확인한다.
8. N-1 bundle이 future schema를 read-only/online-only로 처리하는지 확인한다.
8. N-1 bundle이 future schema를 `INCOMPATIBLE` / `ONLINE_ONLY`로 처리하는지
확인한다. reference runtime은 read-only가 아니라 online-only로 닫는다.
### 안전한 조치
@@ -196,6 +215,12 @@ remote tab 강제 종료, database 삭제, 무한 reload는 금지한다.
- `MIGRATION_FAILED`, unknown codec, schema postcondition failure
- `CORRUPT_DATA`, `NOT_READABLE`, forced close
- `RETENTION_SWEEP`(`INDEXEDDB_WRITE`)과 `pruneExpiredReceipts`
(`INDEXEDDB_MIGRATE`)의 `CORRUPT_DATA` 관측은 실패가 아니다. 손상 행을 지우지
않고 건너뛴 수이고, 나머지 정상 행은 정리된다(05-05,
`indexeddb-runtime.ts` `purgeEligibleRecords`,
`indexeddb-maintenance.ts` `pruneExpiredReceipts`). budget이 삭제 bytes나
receipt 수를 감당하지 못하면 그 값은 내리지 않고 둔다
- transaction request success 후 commit failure
- `LIMIT_EXCEEDED`: dataset logical byte/receipt budget 초과
- lifecycle batch가 proof 없이 실행되거나 TTL/UNTIL_SYNCED record가 잘못 노출·삭제
@@ -248,7 +273,21 @@ remote tab 강제 종료, database 삭제, 무한 reload는 금지한다.
proof를 운영자가 수동 생성·재사용하지 않음
database 전체 삭제는 data owner가 export/recovery와 영향 scope를 승인한 별도
action이다.
action이다. runtime이 스스로 DB를 지우는 경우는 하나뿐이다(05-03).
- 조건: `enforceLifecycleBatch`의 action이 `LOGOUT` 또는 `ACCOUNT_DELETION`이고,
`authorizeLifecycle`이 proof를 내준 뒤, open이 `POLICY_REJECTED` 또는
`CORRUPT_DATA`로 실패했을 때(budget/binding 행 손상, 바뀐 policy). 행 단위
purge는 open이 필요해서 이 상태에서는 영영 돌 수 없다
(`src/adapters/storage/indexeddb/indexeddb-runtime.ts` `deleteUnadmittedDataset`).
- 범위: 세 opaque token에서 만든 그 partition의 DB 이름 하나
(`indexeddb-governance.ts` `indexedDbPhysicalDatabaseName`). 다른 partition과
origin의 다른 DB는 건드리지 않는다.
- 결과: 지워지면 receipt `COMPLETE`와 `datasetDeleted: true`(행 수는 세지
않는다). 다른 context가 연결을 닫지 않아 blocked deadline이 지나면 `BLOCKED`
/ `RELOAD_OTHER_CONTEXTS`를 반환한다. 이때 삭제 요청은 브라우저에 살아 있어
나중에 적용될 수 있으므로 다른 tab을 닫고 같은 purge를 다시 호출한다.
- governance가 정상이면 지금처럼 행 단위 purge만 하고 DB는 지우지 않는다.
성공 판정:
@@ -336,6 +375,11 @@ VD-15 목표 runtime을 먼저 구현한다.
- committed logical row와 physical manifest/file 불일치
- digest/length mismatch
- worker crash, handle lock timeout, `NoModificationAllowedError`
- put의 retryable `NOT_READABLE`: source가 `putIdleTimeoutMs`(기본 2분) 동안 다음
bytes를 주지 않아 put을 끝내고 origin mutation lock을 풀었다(05-07,
`opfs-worker-client.ts` `preparePut`, `opfs-policy.ts`). OPFS 쓰기는 origin
전체에서 한 번에 하나라서, 이 bound가 없으면 멈춘 source 하나가 모든 tab의 쓰기를
`mutationLockWaitTimeoutMs` 뒤 `BLOCKED`로 만든다
- sensitive policy maintenance의 `POLICY_REJECTED`, proof replay/expiry 또는
authority provider/consumer unavailable
@@ -371,12 +415,25 @@ VD-15 목표 runtime을 먼저 구현한다.
### recovery
- `PREPARING`: partial staging 검증 후 idempotent resume 또는 purge
- `FILES_READY`: expected generation/digest 일치 시 logical commit, 아니면
quarantine
- `PREPARING`: reconcile은 resume하지 않는다. staging receipt가 가리키는 그
transaction의 physical generation과 staging을 지우고 journal row를 rollback한다.
receipt가 없거나 0바이트면(첫 receipt 쓰기가 quota나 crash로 끝나지 못함) 지울
generation이 없으므로 staging만 지운다(05-02). 읽을 수 없는 receipt는 지우지
않고 그 row를 `failedTransactions`로 남긴다
(`opfs-byte-store-adapter.ts` `reconcileTransaction`,
`opfs-worker-runtime.ts` `cleanupTransactionLocked`)
- `FILES_READY`: worker가 manifest와 모든 chunk digest를 다시 검증한다. 맞으면
logical commit 뒤 finalize한다. 맞지 않으면 quarantine하지 않고 그 generation과
staging을 지운 뒤 rollback한다. 지워지는 것은 commit 전 staging뿐이다
- `COMMITTED` + file missing/corrupt: reconstructable만 server rehydrate;
user-created private는 read-only/export/recovery
- stale staging/orphan chunk는 grace period와 bounded mark/sweep 후 제거
- `LOGOUT`/`ACCOUNT_DELETION` purge는 객체를 모두 지운 뒤 그 partition의 chunk를
grace 없이 sweep한다(05-04, `opfs-byte-store-adapter.ts` `enforcePolicies`).
journal이나 staging receipt가 참조하는 chunk는 이때도 지우지 않는다. report의
`chunkSweep`이 `COMPLETED`여야 bytes가 지워진 것이다. `DEADLINE_REACHED`면 같은
purge를 다시 호출하고, `STAGING_STATE_UNREADABLE`이면 읽을 수 없는 staging부터
처리한다
- lock/worker 문제면 OPFS write off → approved capped fallback 또는 online-only
- scope binding mismatch면 affected scope를 read-only로 격리하고 registry/
composition을 forward fix; 다른 token path로 bytes를 이동하거나 추측 복구 금지
@@ -403,8 +460,11 @@ committed object를 sync handle로 in-place repair하지 않는다. 새 generati
## 8. Cache Storage/Service Worker stale or poisoned release
public static Cache release runtime은 존재하지만 cursor/count/deadline이 있는
bounded inspect/cleanup과 Service Worker waiting/client-drain controller는 아직
없다. Service Worker는 제품이 PWA/offline fetch를 별도로 선택한 경우에만 아래
bounded inspect/cleanup은 아직 없다. Service Worker의 waiting/client-drain
활성화는 page controller의 `requestActivation()` 핸드셰이크로 구현돼 있다
(`src/adapters/service-worker/service-worker-page-controller.ts`). 템플릿에는 이를
부르는 화면이 없다. Service Worker는 제품이 static selection
(`src/features/installed-runtime-capabilities.ts`)을 `ACTIVE`로 바꾼 경우에만 아래
worker 절차를 적용한다.
### 신호
@@ -449,12 +509,38 @@ static Cache-only 조합:
invocation을 추가 budget으로 반복 실행하지 않는다. VD-15 bounded cursor
runtime 구현 전에는 큰 namespace를 자동 sweep하지 않는다.
Service Worker를 별도 선택한 조합에서만 추가:
Service Worker를 별도 선택한 조합에서만 추가. 워커의 fetch 가로채기만 끄는
스위치는 없다. 끄는 경로는 아래 둘이다.
- fetch interception을 network-only kill switch로 전환
- new worker activation 중지
- 필요하면 unregister + 다음 navigation cleanup migration
- old controlled client가 drain되기 전 해당 release cleanup 금지
- 페이지가 부팅하면: runtime config에 `CAPABILITY_OVERRIDES.SERVICE_WORKER:
"DISABLED"`를 넣는다. 재빌드는 필요 없다. 다음 부팅 때 page controller가 scope와
script가 정확히 일치하는 등록만 unregister하고, 새 등록은 하지 않는다
(`src/contracts/runtime-capabilities.ts` `resolveRuntimeCapabilities`,
`service-worker-page-controller.ts` `start()`의 `disabledCleanup` 분기). 소유
캐시는 지우지 않는다. unregister는 이미 열린 탭의 제어를 끊지 않으므로, 그 탭은
닫히거나 다시 load될 때까지 현재 워커를 쓴다.
- 워커 때문에 페이지가 부팅하지 못하면: static selection을
`{ mode: "REMOVE_REGISTRATION", scriptPath: "service-worker.js" }`로 바꾼
release를 배포한다. 이 release는 같은 URL에 자기 해제 `service-worker.js`를 낸다
(`scripts/build-frontend.ts`, `scripts/lib/self-unregistering-service-worker.ts`).
페이지 코드가 돌지 않아도 브라우저 update 검사(내비게이션 때, 등록은
`updateViaCache: "none"`)가 이 파일을 받아 설치한다. 설치 즉시
`skipWaiting()`하고, 활성화 때 `registration.unregister()`한다. fetch handler가
없어서 그동안의 요청은 모두 네트워크로 간다. 다음 load부터는 제어받지 않는다.
브라우저 확인: `tests/e2e/service-worker-recovery.spec.ts`.
- 이 경로가 동작하려면 `service-worker.js`를 `Cache-Control: no-cache`로 서빙해야
한다. `verify:hosting-headers`는 파일이 있는지만 보고 이 헤더는 보지 않는다
(`scripts/lib/hosting-probe.ts` `checkPublicServiceWorkers`).
- 새 워커는 install에서 `skipWaiting()`하지 않는다(`service-worker-entry.ts`).
활성화는 페이지의 `requestActivation()`으로만 일어나므로, 새 worker 활성화를
멈추려고 따로 할 일은 없다.
- 제거는 `ACTIVE → REMOVE_REGISTRATION → PURGE_OWNED_RESOURCES → null` 순서로
release를 나눈다(`src/contracts/service-worker.ts`
`InstalledServiceWorkerSelection`). 소유 캐시는 `PURGE_OWNED_RESOURCES` release의
page controller가 지운다(`service-worker-removal.ts` `purgeOwnedResources`).
old controlled client가 drain되기 전에는 이 release를 배포하지 않는다. 캐시가
사라지면 그 탭의 워커는 요청을 네트워크로 넘기고(`service-worker-entry.ts`
fetch 리스너의 `cached ?? fetch(request)`), 서버에 없는 옛 청크는 404가 된다.
hosting/CDN purge는 두 branch와 분리된 provider 절차로 실행한다.
+120 -6
View File
@@ -1,6 +1,6 @@
# CI quality-gate orchestration
`config/ci/gates.json` is the executable registry for all 26 gates and the sole
`config/ci/gates.json` is the executable registry for every gate and the sole
workflow model. `.gitea/workflows/quality-gates.yml` is generated from that
strict v2 contract; it is not an independent configuration authority. Update
the registry, run `corepack pnpm generate:ci-workflow`, and commit the generated
@@ -10,6 +10,65 @@ checking, the typed contract checker, and this workflow drift check. The Gitea
adapter runs each gate as an independent matrix check with full fan-out and no
soft-fail wiring.
## 기준선 갱신과 새 프로젝트 시작 시 초기화할 기준선
게이트 계약의 크기와 모양은 코드 상수가 아니라 `config/ci/contract-baseline.json`에
있다. 이 파일에는 게이트 수, 명령 정의 수, 명령 참조 수, 산출물 수, stage 수,
게이트 모양 SHA-256과 함께 `owner`·`reason`이 들어 있다. 계약을 불러올 때 현재
`gates.json`과 이 파일이 다르면 실패한다(`scripts/contracts/ci-gates.ts`의
`assertCiContractBaseline`). 그래서 게이트·명령·산출물을 추가하거나 지운 뒤에는
다음 순서로 커밋한다.
```
# 1. config/ci/gates.json 수정
CI_CONTRACT_BASELINE_OWNER=<팀> CI_CONTRACT_BASELINE_REASON=<이유> corepack pnpm update:ci-contract-baseline
corepack pnpm generate:ci-workflow
corepack pnpm check:ci
```
`update:ci-contract-baseline`은 `scripts/update-ci-contract-baseline.ts`를 실행한다.
리뷰는 `contract-baseline.json`의 diff로 변경을 승인한다. 샘플·recipe·런타임 제거
검증(`test:*-removal`)도 같은 절차를 쓴다. 줄인 계약을 기준선으로 기록한 뒤
canonical `check:ci`를 돌린다(`scripts/lib/removal-fixture.ts`의
`pruneRemovalFixtureCiContract`). 완화 모드는 없다.
`check:ci`는 `tests/` 아래 테스트 파일(`tests/fixtures` 제외)이 모두 CI 게이트
명령에서 실행되는지도 확인한다. 게이트 명령이 닿는 package script의 Vitest 경로와
Playwright 설정의 `testDir`를 모아 비교한다(`scripts/lib/ungated-tests.ts`).
`run-scale-profile.ts <tier>`를 부르는 명령은 그 tier의 Vitest 경로로 센다.
게이트가 돌리지 않는 테스트는 `config/ci/ungated-tests.json`에 이유와 함께 적어야
한다. 게이트가 이미 돌리는 파일을 이 목록에 남겨 두면 실패한다.
package script도 같은 방식으로 확인한다(`scripts/lib/ungated-scripts.ts`).
`check:*`·`verify:*`·`test:*`·`drill:*`·`review:*` 스크립트는 게이트 명령에서
package script 그래프로 닿거나, 게이트가 이미 돌리는 Vitest 경로만 다시 돌려야
한다. 둘 다 아니면 `config/ci/ungated-scripts.json`에 이유와 함께 적는다. 게이트가
닿는 스크립트를 이 목록에 남겨 두면 실패한다. 두 목록에 남은 항목과 이유는 각
파일에 있다.
규모 테스트는 이렇게 나뉜다(리뷰 11-03, `scripts/scale/run-scale-profile.ts`).
- `check:scale:pr`은 merge gate `FE-GATE-005`에서 돈다. 개수·상한·증가 모양만
검사하므로 CPU가 달라도 결과가 같다. S0~S2 조합 증가 검사가 여기 있다. S0/S1만
재면 모든 workload가 noise floor 아래라 이차 누적을 놓친다. 조합 timing은
산출물(`artifacts/scale/pr/composition-s0-s2.json`)에 기록만 한다.
- `main`·`nightly`·`release` tier는 CI에서 돌지 않는다. 이 tier들은
`baseline-regression`을 포함한다. 이 단계는 `config/scale/benchmark-baseline.json`을
기록한 CPU 모델에서만 timing을 비교하고, 다른 CPU에서는 `incomplete`로 끝난다.
이 tier에만 있는 테스트는 `ungated-tests.json`에, tier를 실행하는 `check:scale:*`
스크립트는 `ungated-scripts.json`에 이유와 함께 남아 있다.
템플릿을 복사해 새 프로젝트를 시작하면 아래 기준선은 템플릿의 값이다. 샘플을
지우거나 구조를 바꾸면 프로젝트 값으로 다시 찍는다.
| 기준선 | 파일 | 갱신 방법 | 검사 위치 |
|---|---|---|---|
| CI 계약 크기·게이트 모양 | `config/ci/contract-baseline.json` | `update:ci-contract-baseline` (`CI_CONTRACT_BASELINE_OWNER`·`_REASON` 필수) | `scripts/contracts/ci-gates.ts` `assertCiContractBaseline` |
| registry 스냅샷과 승인 | `config/contracts/registry-baseline.json`, `registry-baseline.approval.json` | `update:registry-baseline` (`REGISTRY_BASELINE_OWNER`·`_REASON` 필수). 기준선을 새로 찍지 않고 breaking 변경을 유지하려면 `config/contracts/registry-change-evidence.json`에 항목을 추가 | `scripts/check-registries.ts`의 baseline 비교 |
| 커버리지 모듈 수 하한 | `config/testing/risk-coverage.json`의 `repositoryBaseline` | 직접 수정. 지운 production 모듈 수만큼 줄인다(`scripts/test-sample-removal.ts`가 같은 계산을 한다) | `scripts/lib/risk-coverage.ts` "repository module baseline" |
| 기능 끄기 설정 | `config/runtime/<profile>.json`의 `FEATURE_OVERRIDES` | 직접 수정. 지운 기능의 키를 뺀다(`scripts/test-sample-removal.ts`가 같은 일을 한다) | 없음. 남은 키는 조용히 무시된다(리뷰 09-09) |
| 의존성 목록 | `config/security/dependency-baseline.json`, `dependency-baseline.approval.json` | `update:dependency-baseline` (`DEPENDENCY_BASELINE_OWNER`·`_REASON` 필수) | `scripts/generate-supply-chain.ts` |
Contract loading validates every registered command entry against the
authoritative root package-script graph and lifecycle/install policy before the
runner enters its execution callback. Foreign cwd/workspace script dispatch,
@@ -43,6 +102,16 @@ The gate runner checks the same inherited environment names before loading the
contract or entering the execution callback, so they cannot reach a child gate
process.
이 셸 파서(`scripts/lib/package-script-graph.ts`)는 리뷰 12-10에서 줄일 수
있는지 확인했고 남겼다. workflow 설치의 `--ignore-scripts`와
`pnpm-workspace.yaml`의 `allowBuilds`로는 막히지 않는 위험이 있기 때문이다.
첫째, 게이트 명령이 직접 설치를 돈다(`verify:lockfile`, 제거 fixture).
`allowBuilds`는 pnpm의 의존성 build script만 제한한다. 루트 프로젝트의 install
hook과 npm/yarn 설치는 `--ignore-scripts`가 없으면 그대로 돈다. 둘째, 게이트가
부르는 이름이 다른 manifest의 script로 바뀌는 경로다(`--prefix`, `--filter`,
`-C`, npm pre/post hook, `npm_config_*`). 이것은 설치 옵션과 관계가 없다. 이유는
파일 머리 주석에도 있다.
The dependency graph is:
```text
@@ -54,9 +123,22 @@ MERGE_READY
DOCUMENTATION_READY (off-chain)
```
`check:architecture`는 dependency-cruiser 결과와 별도로 Babel parser/Node
resolver 기반 `staticImportGraph`를 `artifacts/quality/dependency-report.json`에
기록한다. TS/TSX의 static, dynamic, type, CommonJS 및 JSDoc import를 검사하고,
`DOCUMENTATION_READY`(`verify:documentation`)가 검사하는 범위는 좁다
(`scripts/verify-documentation-readiness.ts`).
- diagram 리뷰 ledger(`docs/architecture/review-ledger.json`)와
`review-evidence.md`가 같은 경로·해시·점수를 담는지
- README와 `docs/accessibility/manual-checklist.md`가 설치된 route ID를 모두
적는지
- README가 빌드와 승인 단계가 읽는 환경 변수를 모두 적는지
문서의 다른 내용(수치, 목록, 설명)이 코드와 맞는지는 검사하지 않는다(리뷰 14-07).
`check:architecture`는 Babel parser/Node resolver 기반 `staticImportGraph`를
`artifacts/quality/dependency-report.json`에 기록한다. 규칙은
`.dependency-cruiser.json`에서 읽지만 dependency-cruiser는 실행하지 않는다.
dependency-cruiser 18은 TypeScript 7을 해석하지 못해 0개 모듈을 검사하고
통과했다(리뷰 12-05). TS/TSX의 static, dynamic, type, CommonJS 및 JSDoc import를 검사하고,
로컬 source import에는 실제 TypeScript 확장자를 요구한다. 실행 source나 로컬
specifier에 `.js/.jsx/.mjs/.cjs`가 있거나 unresolved dependency, parse failure,
error-severity layer violation, cycle 또는 지원하지 않는 architecture rule
@@ -229,7 +311,28 @@ promotion, and field evidence through aggregation.
Runbook jobs write to the stable path
`artifacts/runbooks/<runbook-id>/record.json`; the dynamic release identity is
stored inside the record. This keeps gate evidence lookup independent from
stored inside the record.
A runbook drill (`drill:runbook`, FE-GATE-021..025) records each verdict as
`PASS`, `FAIL` or `UNVERIFIED` (`scripts/drill-runbook.ts`, record schema in
`scripts/contracts/release-artifacts.ts`). `PASS`/`FAIL` means the drill checked
it against a built `dist/`; it reads no `public/` placeholder, so a missing build
fails. In CI the production stage does not rebuild: `production_gate` downloads
the `promoted-release` artifact of the promotion job, extracts its
`release-candidate.tar.gz` to `.release/promoted-release` after checking it
against the `archive_sha256` of `immutable_build`
(`scripts/verify-ci-candidate-archive.ts`), and each drill command passes
`--release-root .release/promoted-release` (`config/ci/gates.json`). The CI
contract rejects a production drill gate that builds or omits the release root
(`scripts/contracts/ci-gates.ts`, 13-03). Run locally without `--release-root`,
a drill checks the local build. Browser boot, live API traffic, smoke after a provider
switch, and anything the runbook marks as needing provider verification are
`UNVERIFIED`. One `FAIL` makes the drill `FAIL` (exit 1). Otherwise any
`UNVERIFIED` makes it `UNVERIFIED` (exit 3), and the gate is not `PASS`. So
without provider evidence the production stage stays open. That is the intended
result: a local drill cannot show that the promoted release can be rolled back.
FE-GATE-016 (`rollback-drill`) is retired because it ran the same FE-RB-005
drill as FE-GATE-025 (`RETIRED_GATE_IDS` in `scripts/contracts/ci-gates.ts`). This keeps gate evidence lookup independent from
slashes or other provider-specific characters in `RELEASE_ID`, while each
workflow artifact remains scoped to its own run.
@@ -295,7 +398,18 @@ Repository variables required by higher tiers:
- `RUNNER_IMAGE_DIGEST` for the immutable job-container image digest used by the
`ubuntu-latest` runner label; the workflow exposes it to gates as
`CI_RUNNER_IMAGE` (required by every tier)
- `HOSTING_BASE_URL` for live header verification
- `HOSTING_BASE_URL` for live header verification of the deployed promoted
release (FE-GATE-019, production stage). Without it the gate fails; the
local fixture result is `UNVERIFIED`
- `APP_PROFILE` for the runtime profile the release candidate is built from
(`local`, `development`, `staging`, `production`;
`scripts/generate-runtime-config.ts`). An unset value builds `local`; an empty
value fails the build.
- `RELEASE_TARGET` for the environment FE-GATE-027 admits the candidate to
(`scripts/check-release-admission.ts`). It has no default. The immutable_build
job runs FE-GATE-015 and then FE-GATE-027, and FE-GATE-027 refuses the
candidate when `APP_PROFILE` is set and differs from `RELEASE_TARGET`. Both are
repository-wide variables, so set them together for each release.
- `FIELD_WEB_VITALS_INPUT` for the privacy-approved field sample document
- `MIN_ELIGIBLE_SAMPLES` after the baseline decision
- `VULNERABILITY_PROVIDER_COMMAND` and `PROVENANCE_PROVIDER_COMMAND` for the
@@ -31,6 +31,12 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle
`allowedResponseHeaderNames`에 `vary`를 포함해야 한다. 아니면 composition이
`TypeError`로 즉시 실패한다. 저장된 variant가 같은 key로 충돌하는 상태를 만들지
않기 위한 cross-field invariant다.
- `allowedResponseHeaderNames`에 `content-type`이 없는 policy도 composition에서
`TypeError`로 실패한다. activation이 저장된 `content-type`을 다시 검증하기
때문이다.
- `Vary: Accept-Encoding`은 policy 없이 항상 허용한다. `Accept-Encoding`은
script가 만든 Request에 들어가지 않는 금지 헤더라 저장과 조회 요청 모두 이
값이 없다. nginx `gzip_vary`와 대부분의 CDN이 이 헤더를 붙인다.
## 1. 변경할 수 없는 복구 원칙
@@ -54,7 +60,9 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle
2. `cache.operation.failed`와 `storage.operation.failed`의 allowlisted
operation/outcome/reason만으로 범위를 좁힌다.
3. runtime status가 `ACTIVE_BROADCAST`, `ACTIVE_STORAGE_FALLBACK`,
`DEGRADED_LOCAL_ONLY`, `CLOSED` 중 무엇인지 확인한다.
`DEGRADED_STORAGE_FALLBACK`, `DEGRADED_LOCAL_ONLY`, `CLOSED` 중 무엇인지
확인한다. `DEGRADED_STORAGE_FALLBACK`은 BroadcastChannel open에 실패한 tab이다.
다른 tab이 broadcast로만 보낸 event를 받지 못한다.
4. 현재 tab의 mutation 성공 후 local namespace가 stale 처리되는지 확인한다.
5. 다른 tab의 오래된 화면이 단순 stale 표시인지, 실제 server authorization
우회인지 분리한다. authorization 우회는 cache incident가 아니라 P1 security
@@ -70,7 +78,9 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle
- `BROADCAST_PUBLISH_FAILED`
- `STORAGE_LISTENER_FAILED`
- `STORAGE_PUBLISH_FAILED`
- runtime status `DEGRADED_LOCAL_ONLY`
- `INVALID_CACHE_EPOCH`, `SECURE_RANDOM_UNAVAILABLE`(OPEN FAILED): runtime을
만들지 못해 이 tab은 cross-tab 무효화 없이 `DEGRADED_LOCAL_ONLY`로 동작한다
- runtime status `DEGRADED_STORAGE_FALLBACK` 또는 `DEGRADED_LOCAL_ONLY`
### 확인
+54
View File
@@ -10,6 +10,60 @@ Performance evidence is deliberately split by measurement context:
release-specific production samples over 28 days and evaluates p75 LCP, CLS,
and INP against 2.5 s, 0.10, and 200 ms.
## 번들 예산의 기준선과 여유
리뷰 13-14. 예산은 `config/performance/budgets.json`에 있고
`scripts/check-bundle.ts`가 강제한다. 템플릿 기본 화면만으로 초기 JS 예산의
96%를 쓴다. 첫 기능을 추가하기 전에 아래 숫자를 보고 예산을 정한다.
| 항목 | 값 |
|---|---|
| 초기 JS 예산 | 204,800 gzip bytes(200 KiB) |
| 템플릿 기준선(2026-09-25 측정) | 196,573 gzip bytes. 빌드 ID가 번들에 들어가므로 빌드마다 수백 바이트 달라진다(196,386~196,623 관측) |
| 여유 | 약 8,200 bytes(4%) |
| lazy chunk 예산 | 파일마다 122,880 gzip bytes(120 KiB). 기준선의 가장 큰 lazy chunk는 약 8 KB |
초기 JS 9개 파일 중 세 개가 대부분이다. `index` 93.5 KB, `design-system`
65.6 KB, `preload-helper` 28.5 KB(zod 포함). 나머지 여섯은 합쳐 9 KB 정도다.
측정 조건:
- 초기 파일은 Vite manifest의 entry와 그 static import다
(`scripts/lib/classify-vite-bundle.ts`). dynamic import chunk는 lazy다.
- 합계는 JavaScript만 센다. CSS(`index-*.css`, 8.5 KB gzip)는 예산에 들어가지
않는다.
- gzip은 Node `zlib.gzipSync` 기본 수준(6)으로 잰다
(`scripts/lib/release-candidate.ts`). 호스팅이 brotli로 보내면 전송 크기는 더
작다. 예산은 gzip 기준 그대로 둔다.
- Node·pnpm·runner 이미지는 `artifacts/performance/bundle.json`의 `context`에
기록된다.
예산을 올릴 때는 이 표의 기준선과 새 측정값, 이유를 같은 변경에 적는다.
lab 측정(`scripts/test-performance.ts`, FE-GATE-026)은 local 프로필 build를
`vite preview --strictPort`로 띄워 잰다(리뷰 11-07).
- 포트는 `LAB_PERFORMANCE_PORT`(기본 4173)다. 서버를 띄우기 전에 그 포트가
이미 응답하면 실패하고, 응답하는 `/release-manifest.json`의 build·release가
로컬 `dist/release-manifest.json`과 다르면 실패한다
(`scripts/lib/lab-performance.ts`, `tests/unit/lab-performance.test.ts`).
- 새 브라우저 context에서 `--runs=N`(기본 5)번 재고, 예산은 중앙값으로
판정한다. 모든 측정값과 최소·최대는 `lab.json`의 `context.sampling`에 남는다.
- named interaction은 페이지 안의 시계로 잰다. 클릭 이벤트의 `timeStamp`부터
대상 heading이 DOM에 들어온 시각까지다. Playwright 왕복 시간은 들어가지 않고,
lazy chunk 다운로드(200 KB/s 제한)는 들어간다. 클릭의 Event Timing entry
길이(INP의 입력값)는 `context.sampling.clickEventDurationMs`에 따로 남는다.
- CPU 모델, 논리 CPU 수, 측정 전후 loadavg를 `context.runner`에 남긴다.
- preview 서버는 자기 프로세스 그룹으로 띄우고 끝날 때 그룹 전체를 멈춘다.
`corepack`에만 신호를 보내던 때는 vite가 포트를 계속 잡고 있었다.
2026-09-27 한 빌드를 10회 잰 결과(i5-10400F 12 CPU, loadavg 11~17): 중앙값
LCP 2,386ms, interaction 184.5ms로 통과했다. 한 번씩 판정했다면 interaction
10회 중 4회(최대 274ms), LCP 10회 중 2회(최대 2,644ms)가 실패였다. 같은
빌드를 loadavg 7~9에서 다시 10회 재면 interaction 120~148ms, LCP
1,968~2,072ms로 모두 통과했다. 한 번 측정한 판정은 호스트 부하에 따라
뒤집히고, 중앙값 판정은 두 번 모두 통과였다.
The field minimum eligible-sample threshold is intentionally unresolved until
a privacy-approved telemetry baseline exists. Therefore the field command
fails closed with `FAIL_UNVERIFIED` when run against the example input. Provide
+84 -7
View File
@@ -12,21 +12,98 @@ cache action, and repeats the smoke checks. Rebuilding an old commit, replacing
HTML alone, or declaring recovery from cache-purge completion is prohibited.
Recovery is established by old/new reachability probes.
Before deploying a promoted release later, or rolling back to one, re-verify
its promoted bundle (the five files uploaded by the `promotion` job) with the
archived mode (review 13-04). Provider evidence expires two hours after issue,
so the normal mode refuses any release promoted before that. The archived mode
still checks signatures, digests and the exact five members, and judges
freshness at the release's recorded promotion time
(`promotion-verification.json` `verifiedAt`, which may not lie in the future).
New promotion never uses it (`scripts/lib/exact-promotion-bundle.ts`).
```bash
VULNERABILITY_PUBLIC_KEY_PATH=... VULNERABILITY_KEY_ID=... \
PROVENANCE_PUBLIC_KEY_PATH=... PROVENANCE_KEY_ID=... \
EXPECTED_PROMOTION_RUN_ID=<run id> EXPECTED_PROMOTION_RUN_ATTEMPT=<attempt> \
EXPECTED_PROMOTION_SOURCE_REVISION=<commit> \
EXPECTED_PROMOTION_ARCHIVE_SHA256=<archive sha256> \
corepack pnpm verify:promotion -- --root <promoted bundle directory> --archived
mkdir <release dir> && tar -xzf <promoted bundle directory>/release-candidate.tar.gz -C <release dir>
corepack pnpm drill:runbook -- FE-RB-005 --release-root <release dir>
```
The expected values come from the release record, not from the bundle. The
drill then checks that release's build/config/manifest tuple and its assets,
not the local build. It ends `UNVERIFIED` until the provider switch and smoke
are recorded, because those happen outside this repository.
The provider-independent cache defaults are:
- hashed assets: `public, max-age=31536000, immutable`
- HTML: `no-cache`
- runtime config and release manifest: `no-store`
- public source maps: disabled
- service worker/offline cache: disabled
- service worker/offline cache: disabled, unless the static selection in
`src/features/installed-runtime-capabilities.ts` is `ACTIVE` or
`REMOVE_REGISTRATION`; then `dist` holds exactly the selected
`service-worker.js`, served `no-cache` so the browser's update check sees
each release's worker
HTML, JSON config/manifest, and hashed JavaScript MIME types are also compared
to the declared allowlist; a cache-correct response with a mismatched
`Content-Type` still fails the hosting gate.
`corepack pnpm verify:hosting-headers` uses a deterministic fixture locally.
Set `HOSTING_BASE_URL` to probe deployed responses; production promotion
requires the artifact to report `mode: "live"`. The live target must be its
canonical, non-loopback HTTPS root URL. Each required surface must return HTTP
200 without leaving that origin before its cache, content-type, and security
headers can count as deployment evidence.
`corepack pnpm verify:hosting-headers` compares the declared headers with a
deterministic fixture when `HOSTING_BASE_URL` is unset. That only shows the
declarations agree with each other, so its result is `UNVERIFIED` (exit 3), not
`PASS` (review 13-05, `scripts/lib/hosting-probe.ts` `hostingVerdict`). Only
`mode: "live"` can pass. The live target must be its canonical, non-loopback
HTTPS root URL. Each required surface must return HTTP 200 without leaving that
origin before its cache, content-type, and security headers can count as
deployment evidence. The hashed asset it requests is the entry script named by
the served `index.html`, so it checks the release that is actually deployed.
FE-GATE-019 is therefore a production-stage gate (`production_gate` job,
`PROD_PROMOTION_READY`). It runs after `promotion` and after the project has
deployed the promoted release. This repository's workflow stops at promotion:
uploading the release, switching the active pointer, and the post-switch smoke
are the project's provider adapter, chosen with the hosting provider.
Keep a retired release's hashed assets reachable while any open tab may still
request them. The minimum is the previous release while the next one is
active (the rolling window modeled in `tests/release/release-fixture.ts`).
Size it to the longest session the product supports; a tab older than that
depends on the reload-once recovery (FE-RB-002).
## Service Worker steps (only when the static selection is not `null`)
The worker is part of the release tuple: `service-worker.js` comes from the
same build as the HTML and assets it caches.
1. **Rollback N+1 → N.** Switching the tuple serves N's `service-worker.js`.
The browser's update check installs it; the worker never calls
`skipWaiting()` on install (`src/adapters/service-worker/service-worker-entry.ts`),
so it waits until every tab of the scope closes or a page calls
`requestActivation()`. The template has no page that calls it. The cache
name is the asset-set digest, so if N's cache is still there as the
retained previous cache, the install reuses it and never deletes it on
failure (`service-worker-static-assets.ts` `installStaticAssets`). Tabs still on N+1 keep worker N+1, so N+1's assets
stay reachable for the rolling window above.
2. **Turn the worker off without a rebuild.** Set
`CAPABILITY_OVERRIDES.SERVICE_WORKER: "DISABLED"` in the runtime config. The
next boot unregisters the owned registration and registers nothing; owned
caches stay (`src/contracts/runtime-capabilities.ts`
`resolveRuntimeCapabilities`, `service-worker-page-controller.ts` `start()`).
This needs a page that boots.
3. **A worker stops the page from booting.** Deploy a release whose static
selection is `REMOVE_REGISTRATION`. It ships a self-unregistering
`service-worker.js` (`scripts/build-frontend.ts`,
`scripts/lib/self-unregistering-service-worker.ts`): the update check
installs it over the broken worker, it skips waiting, unregisters on
activation and answers no fetch. The next load is uncontrolled
(`tests/e2e/service-worker-recovery.spec.ts`). Runbook:
`docs/operations/browser-file-storage-recovery.md` §8.
4. **Removing the worker** takes three releases:
`REMOVE_REGISTRATION` → `PURGE_OWNED_RESOURCES` (deletes owned caches) →
`null` (`src/contracts/service-worker.ts` `InstalledServiceWorkerSelection`).
+537
View File
@@ -0,0 +1,537 @@
# Template sync — `ebea300` → `af3d8e6`
Record of how the frontend template's 359 pending commits (tag `v0.2.0` plus
one documentation commit) were transplanted into this product, and of every
decision taken where the two trees disagreed.
## Starting state
| | |
| --- | --- |
| template pin before | `ebea300` (`template.lock.json`) |
| template pin after | `af3d8e6` (tree `bbcb6dd`) |
| template commits carried | 359 (`ebea300..af3d8e6`) |
| template delta | 824 files: 371 added, 439 modified, 8 renamed, 6 deleted; +68,835 / −13,207 |
| this product's divergence since the last sync | 182 files (`afde2b1..8210d48`) |
| files touched by both since `ebea300` | 90 |
| template paths applied verbatim | 606 |
| template paths applied with product changes | 85 |
| template paths not carried | 127 (listed below) |
Rollback ref created before touching anything:
```
backup/main-before-template-af3d8e6 → 8210d48
```
The histories share no commit, so this is again a patch transplant. It was
done as a three-way merge against an explicit base:
`git merge-recursive ebea300 -- HEAD template/main`, which left 67 conflicts
in the working tree (49 content, 17 modify/delete, 1 rename/delete).
### Pre-transplant baseline
Captured in a clean worktree at `8210d48`, so a pre-existing failure could not
be mistaken for a transplant regression.
| Gate | Result at `8210d48` |
| --- | --- |
| `check:types`, `lint`, `check:architecture`, `check:adapter-inventory`, `check:ci`, `check:i18n`, `check:remediation-ledger`, `check:design-system`, `check:diagnostics`, `check:browser-security`, `check:dev-release-manifest`, `check:tech-log-contract`, `build` | pass |
| `check:registries` | fail — 5 structure errors (three TechLog schema ids unregistered), 6 breaking changes without evidence |
| `test:unit` | 1792 passed (140 files) |
| `test:component` | 154 passed |
| `test:integration` | 102 passed |
| `test:contract` | 7 passed |
| `test:runtime-schema` | 44 passed / 1 failed (`release-manifest.test.ts` expects Studio contract 3.0.0; it is 3.1.0) |
| `test:tech-log` | 417 passed |
| `test:reference-feature` | 19 passed |
| `test:recipes` | 17 passed |
| `test:coverage` | 2535 passed / 1 failed (the runtime-schema test above), so the risk-coverage check is never reached |
| `verify:documentation` | `FAIL_UNVERIFIED`: `routeScopeDocumented: false` |
| `test:sample-removal` | fails: `typecheck`, `registry-structure`, `unit-integration`, `coverage` |
## What the template brought
| Group | Substance |
| --- | --- |
| Domain-scalable structure (`e59994a`) | Features are declared by `src/features/<id>/feature-module.ts`, owned by a bounded context (`src/contexts/<id>/context-module.ts`) inside a deployable app (`src/apps/<id>/app-module.ts`). `scripts/generate-product-feature-index.ts` writes `src/.generated/` from those declarations, and every composer (`installed-*`) is a projection of the generated index. New `src/platform/` kernel (cardinality, errors, telemetry pipeline, traffic, resilience, release coherence) and the scale tooling under `scripts/scale/` |
| 2026-09-24 src review (`4626b73`) | HTTP 408/425/503 handling, abort kernel reuse, SSE parsing, demo subject |
| 2026-09-25 maturity review (`f1002fd`) | The 0.2.0 CHANGELOG rows: correlation ids, idempotency-key reuse on unknown-effect resend, 422 field issues, `readSubject` required, `VITE_*` only through `ENV_REGISTRY`, zod only through `src/contracts/zod.ts`, generator-applied `VITE_PRODUCT_FEATURES`, `feature-module.ts` or `NOT_INSTALLED` per feature directory, CI contract baseline file, every test file gated or listed, FE-GATE-028 for the signed manual accessibility review, runtime-config schema baseline, `noUnusedLocals`, boot error shell for module-evaluation failures, and a long list of adapter fixes |
| Other | WebKit wording fix for the old-tab chunk spec, deferred-decision records |
## What was deliberately not carried
| Path | Why |
| --- | --- |
| `artifacts/phase5/**` (4), `artifacts/quality/extreme-scale-gates/**` (24), `artifacts/scale/**` (35) | Logs of the template's own runs. `scripts/scale/run-scale-profile.ts` and `scripts/verify-extreme-scale.ts` *write* them; `verify-extreme-scale` reads only `summary.json`, `browser-soak.json` and `baseline-comparison.json`, which are regenerated and gitignored. Nothing reads the committed `.log` files. |
| `CLAUDE.md`, `SPEC.md`, `tasks/**` | The template repository's own review instructions and the task tracking of its 2026-09-25 fix round (branch states, lanes). False here. `tests/unit/deletable-history-documents.test.ts` confirms no code reads them. |
| `CHANGELOG.md` | The template's release notes (`version 0.2.0`). This product's version is its own; the README and `docs/README.md` now point at the template repository's changelog instead. |
| `docs/reviews/2026-09-2{3,4,5}-*` (28 files), `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` | Reviews of the template repository at its own commits, with its own file:line findings, and the guide those reviews follow. Only `CHANGELOG.md` linked to them. |
| `src/features/reference-feature/{feature-module,context-routes}.ts` and `…/presentation/**` (9 paths) | Installing the sample now requires its screens, which this product deleted (see the reference-feature decision below). |
| `src/presentation/{pages/home-page,pages/not-found-page,examples/auth-example-page,examples/platform-overview-page}.tsx` | Deleted by this product's UI migration; the template modified them. The deletions stand. |
| `tests/e2e/reference-{form,route,save}.spec.ts`, `tests/features/reference-feature/{reference-page,reference-production-vertical,feature-module,installed-context-routing}.test.tsx?`, `tests/visual/platform.visual.spec.ts` and its three PNGs | Assert the deleted sample screens, the uninstalled sample's descriptor or the template's own pages. |
| `tests/component/app-shell.test.tsx` | Drives the template `AppShell` through `AppRouter`. This product never mounts `AppShell`. |
| `tests/component/context-route-gateway.test.tsx`, `tests/component/route-status-surfaces.test.tsx` | Drive the template's bounded-context route gateway and its example pages, which this product's router does not mount (see the router decision below). |
Template tests that asserted a platform behaviour on deleted template screens
were ported onto TechLog routes instead of being dropped — see "Template tests
ported onto TechLog".
## Conflicts and how each was decided
The rule is the one the previous two syncs wrote down: **keep the template's
mechanism, keep the product's content, and never invent a third state that
neither branch would accept.**
### The generated feature index — `src/features/*/NOT_INSTALLED`
The substantive change of this sync. The template no longer lists features by
hand anywhere: the generator scans `src/features/<id>/`, and a directory must
either declare itself with `feature-module.ts` (and `context-routes.ts` for its
screens) or carry a `NOT_INSTALLED` marker, or the first build step fails.
Every `installed-*` composer is now a projection of the generated index.
This product has three feature directories:
- `local-draft-feature` — the template itself now marks it `NOT_INSTALLED`.
Previous follow-up 5 ("carried but not installed") is settled upstream.
- `tech-log` — this product's domain. The previous two syncs recorded that
TechLog is composed directly rather than as a selectable feature, and that
decision stands. Its routes are served by the product's grouped
PUBLIC/STUDIO router, not by a bounded-context route module, so a
`feature-module.ts` would be a second, unused description of it. It carries
a `NOT_INSTALLED` marker whose text says exactly that: the generator must
leave the directory alone; TechLog is composed by the composition root.
- `reference-feature` — the template's removable sample. See the next section.
With no generator-installed feature, `src/.generated/` declares none, the
deployable app is the template's `template-app` declaration with no populated
context, and `COMPILED_PRODUCT_FEATURE_IDS` is empty.
### `reference-feature` is no longer installed
Until now the sample stayed half-installed: its operations, schemas, adapter
input, contract contribution and messages were composed, and its routes were
filtered out because this product deleted its screens. The template's new
mechanism has no such state. A feature is installed by `feature-module.ts`,
whose `context-routes.ts` imports the page components, and whose contract's
routes enter the route registry. Recreating the half-installed state would need
a product-only `context-routes.ts` with no routes and the old route filter back
in `installed-feature-contracts.ts` — a third state neither side has.
So the directory carries `NOT_INSTALLED`, with the reason. Its code and its own
tests stay (they compile and pass), so reinstalling it or deleting it outright
remain open, and the next sync merges cleanly. What changes at runtime: the
three `REFERENCE_RESOURCE` operations, their six schemas and the one
invalidation topic leave the registries and the bundle. Nothing in this
product called them. The removal is recorded as 13 evidence entries in
`config/contracts/registry-change-evidence.json` (owner `tech-log-frontend`),
the same way the product recorded removing the template's routes, and
`FEATURE_OVERRIDES.reference-feature` is dropped from the four runtime
profiles and `public/config.json` — what the template's own removal procedure
does, and what keeps boot from reporting an override for an undeclared
feature (09-09). Whether to delete the directory is an open question below.
### Composers — `src/features/installed-*.ts(x)`
All five take the template's version, then add TechLog directly:
- `installed-feature-adapters.ts` — the template's module projection and its
`activeFeatureIds` parameter (Q-6.9-5, the kill switch now withholds a
switched-off feature's input). TechLog's input is composed on top and stays
total; neither the index nor `activeFeatureIds` governs it.
- `installed-contract-contributions.ts` — the descriptors' contributions, then
TechLog's three.
- `installed-feature-contracts.ts` — `composeUniqueRecord` over platform,
TechLog and installed routes (a duplicate route id now throws). The
previous sync's route filter and its ownership filter are gone: with the
sample uninstalled no registered route lacks a component.
- `installed-feature-messages.ts` — `composeInstalledMessageCatalogs` over the
installed modules plus TechLog's catalogs, so a key defined twice for one
locale throws for TechLog too. The type is keyed by TechLog's locales.
- `installed-feature-runtimes.tsx` — `composeUniqueRecord` over platform,
TechLog and installed runtime descriptors. The previous sync kept an object
spread because the template's `Object.assign` widened the catalogs to
`any`; `composeUniqueRecord` keeps them typed, so that reason is gone.
### Router — `src/presentation/routes/app-router.tsx`
Taken from the template: the shared `LoadingSurface` and `StatusPage` for the
loading, failure, invalid-address, disabled-feature and integration-failed
surfaces; the support reference `build:incident` on route failures (08-07);
route lifecycle (title, telemetry) for every answer a route gives, with the
title effect split from the navigation effect; no scroll-to-top on back and
forward (08-08); a query on a route without search is kept in the URL (D-16,
here expressed as `searchSchema === null`); `useSessionAction`; the keyed
`ChunkRecoveryBoundary` with `buildId` and `onUnrecovered`; and the router
created in the effect that disposes it, below `PreferenceProviders`.
Kept from the product: the grouped PUBLIC/STUDIO layouts, the registered
not-found descriptor, the sign-in card with its return address, and no route
focus on `#main-content` (removed in `6c2780b` for UI parity; the shells own
focus).
Not carried: the template's bounded-context route gateway
(`ContextRouteGateway`). It mounts generator-installed features' routes, and
none is installed here. `AppRouter` now mounts `MOUNTED_ROUTE_REGISTRY` —
platform plus TechLog — rather than the whole installed registry, which is
also what keeps the app typecheck green when a generator feature is installed
(`tests/unit/two-feature-install-typecheck.test.ts`). The day one is installed,
`tests/component/product-feature-switch.test.tsx` ("registers no route that
cannot be mounted") fails until the gateway is wired in. Follow-up.
### Boot — `src/bootstrap/main.tsx`, `create-runtime-composition.ts`, `runtime-adapters.ts`
`main.tsx` is the template's entry that imports `boot.tsx` dynamically
(09-03), with this product's font and TechLog stylesheet imports kept in the
entry. The composition keeps the BFF session-owner installation and takes the
template's telemetry hand-off to the optional host (06-05). The feature
capabilities object carries both the template's `telemetry` and TechLog's
source switches and CSRF provider.
### Design system and forms
- `Pagination` (`primitives/navigation.tsx`) — the template's version (landmark
context for `CollectionPage`, links that keep the other search parameters,
modified clicks left to the browser, a single hidden page shown instead of an
ellipsis) with this product's options added back: `pageControl: "button"`,
`pageAccessibleLabel`, `className`, `around`, and the `ol.ui-pagination__pages`
list the Studio stylesheet and tests target. The product's "show every page
when there are few" rule is replaced by the template's window with `around`
neighbours; `StudioPagination` keeps `around={2}` and its tests pass
unchanged.
- `Dialog` (`primitives/core.tsx`) — the template's "restore focus only if the
dialog still owns it" guard on this product's synchronous restore.
- `StatusPage` — the template's `surface` prop beside this product's
`className`, `headingNode` and `visualPolicy`; `children` renders once, under
the actions, as upstream.
- `application-query.ts` — the template's idempotency-key reuse on resend
(03-01) written against this product's lazily acquired `submissionChannel`.
- `feature-http-binding.ts` — both the product's `detail` and the template's
422 `validationIssues` pass through.
- `platform-route-codecs.ts` — the template's non-strict `none` codec (D-16)
with this product's non-empty splat.
### Messages — `src/presentation/i18n/catalog.ts`
Both sides wrote copy for the 22 failure kinds that had none (07-01). This
product's copy is kept; the template's boot keys come in through
`BOOT_MESSAGES` (09-03). The template's `home.*` keys belong to its home page,
which this product deleted, so they and their parameter entry are not carried.
### Build and CI
- `vite.config.ts` — the template's declared-`VITE_*` check (13-06) and
config-under-base check (13-07); one `manualChunks` under `rolldownOptions`
that splits the template's preload helper first (09-03) and then this
product's named TechLog route chunks, plus this product's Studio
`modulePreload` filter.
- `scripts/build-frontend.ts` — the template's self-unregistering worker and
dist permissions steps around this product's serving-boundary step.
- `scripts/check-i18n.ts` — the template's discovery of every feature's
`presentation/`, with TechLog's held to this product's behavioural-literal
policy instead of the whole-file Korean rule.
- `scripts/check-design-system.ts` — deep-import and icon checks moved to the
import graph upstream; this product's palette rule is kept.
- `scripts/generate-ci-workflow.ts` and the workflow — pushes to `main` only,
as this product already had (the template also lists `develop`).
- `config/ci/gates.json` — merged per id. The template moved the signed manual
accessibility review out of FE-GATE-009 into release gate FE-GATE-028
(08-06); this product's per-route evidence moved with it, and the template's
five records for its own routes stay deleted. `scripts/contracts/ci-gates.ts`
now pins that one-record-per-mounted-route rule on FE-GATE-028.
- `scripts/test-performance.ts` — the template's median-of-runs measurement
(11-07). Its named interaction is a click on a navigation link to the target
heading; this product had measured the landing heading without a click, which
that clock cannot express, so the interaction is now landing → Explore
(`TECH_LOG_EXPLORE`). Not run here (Playwright). Open question below.
- `scripts/test-sample-removal.ts` — the template's `--feature=<id>` version.
It locates a `NOT_INSTALLED` directory directly, and this product's two
extra owned paths (`studio-csrf-composition.test.ts`, and now the sample's
bounded context) and two excluded tests are kept.
- `package.json` — the template's scripts with the generator prefix; this
product's name, version and scripts. The generator prefix is also added to
`check:dev-release-manifest`, `generate:dev-release-manifest`,
`check:tech-log-contract` and `generate:tech-log-contract`, which reach the
generated index (`tests/unit/product-index-entrypoints.test.ts`).
### Documents
`README.md` takes the template's runtime-configuration, support-scope,
documentation, CI and "Updating a copied project" sections, edited where they
would be false here: the support scope names TechLog's shells instead of the
example routes and lists the reference sample as not installed; the deletable
history table drops `SPEC.md`, `tasks/` and `CLAUDE.md`; the workflow runs on
`main`; and the origin record is `template.lock.json`, which already says
more than the suggested one-line `.template-origin`. `docs/README.md` (the
template's document index) is carried with its links to the uncarried files
removed. `docs/accessibility/manual-checklist.md` keeps this product's route
list and takes the FE-GATE-028 paragraph; the template's description of its own
accessibility spec is not carried, because this product's spec differs.
### Derived baselines — recomputed, not chosen
Each was recomputed with the template's own command or function, after first
reproducing both sides' committed value from their own input.
| Value | This product | The template | Merged |
| --- | --- | --- | --- |
| CI contract (`config/ci/contract-baseline.json`, `update:ci-contract-baseline`) | 27 / 94 / 106 / 141 / 5, `629e5898…` | 27 / 98 / 103 / 109 / 5, `630e8012…` | **27 gates / 101 commands / 106 references / 141 artifacts / 5 stages, `c9adcf85701156097262d8f88203fe42f8be003033e1b6c296a0062e56f10324`** |
| evidence artifact references (`ci-workflow-generation.test.ts`) | 120 | 87 | **119** |
| registry baseline approval digest (`registrySnapshotDigest`) | `428479ac…` | `83d11f84…` | **`2dc6c3a36a5e06c5b4736a0e2bc556d74437f061e6adb71c4e4fb96293170def`** |
| runtime-config schema baseline (`check-compatibility.ts --update-baseline`) | — | template's schema | **this product's schema, byte-identical to the one at `8210d48`** |
The CI contract's hard-coded counts moved upstream into the baseline file
(14-02), so `scripts/contracts/ci-gates.ts` no longer carries them. The
registry baseline is a per-registry, per-row three-way merge of both approved
snapshots; its new approval takes no row from the current tree, so this
product's six pending TechLog route changes stay unapproved. The runtime-config
baseline stands for "the schema the previous release's reader accepts"; the
previous release is `8210d48`, and the schema did not change.
### Template tests ported onto TechLog
Where a template test pinned a platform behaviour on a screen this product
deleted, the test was moved onto a TechLog route rather than dropped:
| Test | Upstream subject | Here |
| --- | --- | --- |
| `tests/component/router.test.tsx` | D-16 query on `/examples/ui`; route lifecycle on fixture-feature surfaces | `/projects?utm_source=mail`; the sign-in gate on `/studio` |
| `tests/component/chunk-recovery-boundary.test.tsx` (2 cases) | states example page | Explore page; sibling move to Topics |
| `tests/component/render-boundary.test.tsx` | states example page | Explore page |
| `tests/component/locale-platform.test.tsx` | the app shell's language selector | the file's own locale harness |
| `tests/component/runtime-application.test.tsx` | shell language selector and session button | stored preference; the Studio sign-in gate |
| `tests/e2e/old-tab-chunk-recovery.spec.ts` | platform and UI example pages | Explore and Topics (not run here) |
| `tests/component/product-feature-switch.test.tsx` | — | the owner is a fixture id and the feature port reports it active or off, since no feature is generator-installed |
Template tests whose invariant is "every feature comes from the generated
index" now also account for TechLog composed directly
(`installed-feature-messages`, `route-runtime`, `product-feature-selection-build`).
Tests that hard-coded template copy or template route ids now use this
product's (`form-foundation`, `manual-a11y-evidence`, `ci-workflow-generation`,
`feature-override-diagnostics`).
## Fixes the transplant required
### `readSubject` on the TechLog session owner — `bff-session-owner.ts`
The template now closes an external session owner without `readSubject` as
`integration-failed` (c6300e9). The HTTP Studio's only owner is
`createBffSessionOwner`, which had none — so every Studio session in
production would have closed. It now has one. `getStudioSession` returns a
display name and roles but no identifier that is stable for one user and
distinct between users, so the owner reports `null`: the runtime then treats a
change of state as a possible user switch and clears server state, recording
`SUBJECT_MISSING`. The owner only notifies when the probed state changes, so
that is one fence per sign-in. `tests/features/tech-log/bff-session-owner.test.ts`
pins that the owner is complete. A real subject needs the backend (open
question below).
### zod through `src/contracts/zod.ts` (F-7)
Nine TechLog files imported `zod` directly; the architecture gate now refuses
that. They import `z` from the facade, which sets `jitless` before any schema
is built, so the production CSP sees no eval probe.
### `noUnusedLocals` (12-12)
The flag found 22 unused imports and locals in TechLog source, one unused
helper in `scripts/generate-nginx-config.ts`, and nine in tests (eight under
`tests/features/tech-log`). All were removed except three compile-time
assertions in `tests/features/tech-log/feature-input.test.ts` and
`studio-contract.test.ts`, which are exported instead: removing them would
remove the check.
### Runtime profiles and `public/config.json`
The template requires `public/config.json` to equal the local profile plus
`BUILD_ID` and `RELEASE_ID` (F-5). It lacked this product's two
`TECH_LOG_*_SOURCE` keys, whose defaults it relied on; they are now written
out, with the same values. `FEATURE_OVERRIDES.reference-feature` left every
profile with the sample (above). `public/release-manifest.json` keeps this
product's `appVersion` 0.1.0; the merge had taken the template's 0.2.0.
### Scripts that reach the generated index
`tests/unit/product-index-entrypoints.test.ts` requires every script that
imports `src/.generated/` to run the generator first. This product's
`check:dev-release-manifest`, `generate:dev-release-manifest`,
`check:tech-log-contract` and `generate:tech-log-contract` do, and are
prefixed. `scripts/lib/manual-a11y-evidence.ts` did too, through the CI
contract parser, which would have forced a prefix on `check:ci` — and the
template requires `check:ci` to be its exact canonical command. The manual
accessibility scope is now read from the platform and TechLog route
registries directly: the set `AppRouter` mounts.
### `verify:tech-log-source-parity` is listed as ungated
Every verification script must run in a gate or be listed with a reason
(12-04). This one needs the original TechLog source served on another port,
which no CI runner has; it is listed in `config/ci/ungated-scripts.json`.
### Idempotency-key reuse (03-01) in two TechLog tests
`studio-save-navigation` and `studio-publication-flow` asserted that a retry
after a 503 uses a new key. The template now resends a write whose outcome is
unknown with its original key, so the backend can apply it once; the TechLog
contracts already declare `IDEMPOTENCY_REPLAY`. The two assertions now expect
the original key. The backend guarantee is an open question below.
### Chunk failures are recorded (08-07)
An unrecovered chunk failure is now recorded as `ui.render.failed` with the
incident id its support reference shows. `public-discovery-screens.test.tsx`
asserted that nothing was recorded for a failed not-found chunk; it now
asserts the one record, under `NOT_FOUND`. Its render helper also waits out
data loading only, since the route's own loading surface is now the shared
`LoadingSurface`.
### Release fixtures carry this build's contract set
`tests/release/fixtures/R10`/`R11` stand for releases of this repository.
Upstream the compiled contract set is empty and the fixtures write
`__EMPTY_SET_DIGEST__`; here it holds TechLog's three packages, so
`tests/release/release-fixture.ts` substitutes the set this build compiles.
### The sample's own composition test installs the sample
`tests/features/reference-feature/reference-runtime-composition.test.ts`
exercises the production graph with a real feature. With the sample
uninstalled it installs it for itself through the generated index, the way the
template's platform tests install their test-only feature.
## Gates on the transplanted tree
Run on the working tree after `corepack pnpm install` (no lockfile change).
Another agent was running gates on the same machine; every failure that
looked timing-sensitive was re-run alone (see below).
| Gate | `8210d48` | After the sync | |
| --- | --- | --- | --- |
| `check:types` | pass | pass (6 projects, `noUnusedLocals` on) | |
| `lint` | pass | pass, `--max-warnings=0` | |
| `check:architecture` | 507 modules, 14 fixtures | 565 modules, 2059 dependencies, 28 graph fixtures, TechLog route source of truth | pass |
| `check:adapter-inventory` | 133 files, 21/21 ratchet | 145 files, 22 abort-primitive importers, 13/13 ratchet | pass |
| `check:ci` | pass | 27 gates, baseline file, workflow bytes | pass |
| `check:registries` | fail | fail, **byte-identical output** | pre-existing |
| `check:i18n` | 460 keys | 455 keys (template's home-page copy not carried) | pass |
| `check:remediation-ledger` | pass | fail (budget statement) | template, escalated |
| `check:design-system` | 48 tokens | 48 tokens | pass |
| `check:diagnostics` | 8 / 5 | 9 diagnostics / 6 telemetry producers | pass |
| `check:browser-security` | pass | pass | |
| `check:dev-release-manifest` | pass | pass | |
| `check:request-fanout` | — (new) | fail: `collect-catalog.ts:30` | template, escalated |
| `check:tech-log-contract` | pass | pass | |
| `build` | pass | pass | |
| `test:unit` | 1792 | 2381 passed / 2 failed (174 files) | template, escalated |
| `test:component` | 154 | 220 passed | pass |
| `test:integration` | 102 | 155 passed | pass |
| `test:contract` | 7 | 15 passed | pass |
| `test:runtime-schema` | 44 / 1 failed | 60 / 1 failed, same test and assertion | pre-existing |
| `test:tech-log` | 417 | 418 passed | pass |
| `test:reference-feature` | 19 | 43 passed | pass |
| `test:recipes` | 17 | 18 passed | pass |
| `test:platform` | — (new) | 247 passed / 1 failed (request fan-out) | template, escalated |
| `check:release-coherence` | — (new) | 46 passed | pass |
| `test:coverage` | 1 failed | 3599 passed / 4 failed: the runtime-schema test and the three escalated tests; risk-coverage not reached on either side | pre-existing + escalated |
| `verify:documentation` | `FAIL_UNVERIFIED` | `FAIL_UNVERIFIED`, same cause; the template's new README variable check passes | pre-existing |
| `test:sample-removal` | fail (4 checks) | fail earlier, at the registry re-baseline | pre-existing cause, escalated |
`tests/component/boot-unexpected-failure.test.tsx` failed once in a full run
while the other agent's gates were running (its boot graph did not settle
inside the default one-second wait) and passed four times alone and in the
final full run; it is load-sensitive, not introduced.
Not run: Playwright e2e, visual and lab-performance
(`test:e2e`, `test:visual`, `test:a11y`, `test:performance`), so the ported
`old-tab-chunk-recovery.spec.ts` and the new lab interaction are unverified.
No visual snapshot was touched: the three template PNGs belong to the
platform spec this product deleted.
## Failures this sync did not cause, and did not fix
Each was reproduced at `8210d48` in the baseline worktree first.
| Gate | State |
| --- | --- |
| `check:registries` | Same five structure errors and six unevidenced TechLog route changes; output byte-identical. |
| `test:runtime-schema` | `release-manifest.test.ts` expects the vendored Studio contract at 3.0.0; it is 3.1.0. |
| `verify:documentation` | `routeScopeDocumented: false`, as recorded by the previous sync. |
| `test:coverage` | Fails on the runtime-schema test on both sides, so `check-risk-coverage` never runs; after the sync it also carries the escalated failures below. |
## Failures the template brought, escalated rather than fixed
Each fails because of something the template introduced, and each was left
failing rather than made green by weakening a check.
| Gate / test | Cause | Why not fixed here |
| --- | --- | --- |
| `check:request-fanout` (FE-GATE-010), and `tests/architecture/request-fanout.test.ts` in `test:platform` and `test:coverage` (FE-GATE-005) | The template's new N+1 source gate flags `gateway.getCatalog()` inside the loop at `src/features/tech-log/application/collect-catalog.ts:30`. That loop is cursor pagination — one request per page of 100, bounded at 50 pages, each needing the previous page's cursor — not one request per row. | The gate's own escape is a `// fanout-reviewed: <reason>` comment on the call's line: a reviewed suppression. Adding one is a reviewer's call, not a merge's. Open question 1. |
| `tests/unit/build-environment-bundle.test.ts` ("keeps the values the app reads and nothing else") | 09-03 expects the shared application chunk to keep its hash when only `VITE_BUILD_ID` changes. This product's `manualChunks` (named TechLog route chunks) leaves one shared chunk that also holds the build-id reader, so every chunk changes hash on every build. That was already true before the sync — then the whole app was one entry chunk. The test now names the product's shared chunk (`render-boot-failure-*`; upstream it is `design-system-*`) and fails on the property itself. | Needs a chunking change in `vite.config.ts` that keeps the route chunk names the build manifest requires; one attempt (isolating the boot-failure module) did not separate the shared code. Follow-up. |
| `tests/unit/second-api-feature-registries.test.ts` | Adds a feature to a copy of the tree and expects `check:registries` to pass there. It inherits this product's registry defect (previous follow-up 2). | Fixing that defect registers TechLog schema ids and approves six TechLog route changes: product work. |
| `test:sample-removal` (FE-GATE-020) | The template's removal now re-baselines the registries in the fixture with `update:registry-baseline`, which runs `check:registries --no-baseline` and stops on the same registry defect. The script throws there, before its other checks run. At `8210d48` it failed later, on four named checks, for the same root cause. | Same as above. |
| `check:remediation-ledger` | The ledger does not state the file-transfer budget the template later ratcheted to 55,700 bytes. Reproduced on an unmodified export of the template at `af3d8e6`, which fails it with four findings (this product's evidence-path fixes from the previous sync remove three). The template moved the script to `config/ci/ungated-scripts.json` with that reason; no gate runs it on either side. | Editing a history record to state a later number is the template's call, and it declined. |
## Follow-ups
The previous sync left five. Their state now:
1. **TechLog's HTTP gateways address operations by id through a shim.**
Closed before this sync, by `aaa384c` (`tech-log-http-binding.ts` builds
every gateway on `createFeatureHttpBinding`; the composition-root shim is
gone). This sync did not change it.
2. **The schema registry defect keeps gates red.** Still open, and it now
blocks more: besides `check:registries`, it stops `test:sample-removal`
earlier and fails the template's new `second-api-feature-registries` test.
`check:registries` output is byte-identical to `8210d48`.
3. **`tests/mocks` is feature-owned but TechLog imports it.** Unchanged. It
cannot be re-checked until `test:sample-removal` gets past the registry step.
4. **`check:i18n` cannot tell a comment from a literal.** Closed before this
sync, by `aaa384c` (TechLog presentation is held to a behavioural-literal
policy). This sync kept that policy while taking the template's per-feature
discovery; `check:i18n` passes.
5. **`local-draft-feature` carried but not installed.** Settled upstream: the
template marks it `NOT_INSTALLED` itself.
New:
6. **TechLog is not a generator-installed feature.** It carries a
`NOT_INSTALLED` marker because it is composed directly. The template's shape
for it would be `feature-module.ts` in a bounded context whose route module
serves TechLog's routes — which means moving the grouped PUBLIC/STUDIO router
onto context route modules. Its own change.
7. **The bounded-context route gateway is not mounted.** `AppRouter` mounts
platform and TechLog routes only. The day a generator-installed feature
arrives (the sample reinstalled, or TechLog moved per item 6), the
template's `ContextRouteGateway` has to be wired into a layout group, and
the template tests not carried for that reason
(`context-route-gateway`, `route-status-surfaces`, `app-shell`) come back.
8. **Shared chunk hash changes with every build.** See the
`build-environment-bundle` row above.
9. **`template-app` is the deployable app's id.** The generator requires one
app declaration; the template's (`src/apps/template-app/`) is carried as is.
Renaming it is cosmetic and touches no behaviour.
10. **Lab performance measures landing → Explore.** Not run here; the budget
(200 ms named interaction) has not been checked against it.
## Open questions for the product owner
1. **Cursor pagination and the N+1 gate.** Approve
`// fanout-reviewed: cursor pagination, one request per 100-row page, at most 50 pages`
on `src/features/tech-log/application/collect-catalog.ts:30`, or give the
Studio catalog a bulk read. Until then FE-GATE-010 and FE-GATE-005 are red.
2. **Delete `src/features/reference-feature`?** It is now uninstalled, with its
code and tests kept so the next sync merges cleanly and its own tests keep
running. Deleting it is what the template's removal gate proves possible;
reinstalling it means bringing its screens back.
3. **Studio session subject.** `getStudioSession` has no stable user
identifier, so the BFF owner reports none and every sign-in clears server
state once. A `subject` (for example the OIDC `sub`) in the session response
would let a token refresh keep the cache. Backend contract change.
4. **Same-key resend.** The client now resends a write whose outcome is
unknown with its original idempotency key (template 03-01). The TechLog
Studio and management contracts declare `IDEMPOTENCY_REPLAY`; confirm the
backend applies a repeated key once and returns the first result.
5. **Lab performance interaction.** The template's lab gate times a click on a
navigation link to the target heading. This product now uses landing →
Explore. Confirm that is the interaction to budget, or name another.
@@ -16,7 +16,7 @@ No Critical issue was found. Five High findings are implementation blockers or n
4. N-04: telemetry dispose only removes pagehide; queued callbacks, future emit calls, and in-flight delivery survive runtime teardown.
5. N-05: the conditional-validator key codec is delimiter-ambiguous and lets two valid bindings overwrite each other. It is not composed into HTTP yet, so this is a rollout blocker rather than a current request-path incident.
The current reference feature uses V3. The older createHttpClient path remains exported and is still the documented rollback/compatibility seam, so its replay and cancellation defects cannot be dismissed as dead code.
The current reference feature uses V3. The older createHttpClient path remains exported and is still the documented rollback/compatibility seam, so its replay and cancellation defects cannot be dismissed as dead code. (2026-09-24, Q-6.3-11: the comments no longer call it a rollback seam; V2 and V3 use different wire shapes, so a rollback also needs a V2-envelope server.)
## 2. Method, severity, and confidence
@@ -60,16 +60,19 @@ All 24 files below were read in full.
| src/adapters/diagnostics/bounded-diagnostics.ts | Bounded in-memory diagnostics projection/sink and safe pre-mount boot evidence | DiagnosticsPort; contracts/diagnostics.ts and telemetry.ts; bootstrap | Preserve fail-isolated projection and cloning. Harden non-finite capacity. V3 producer fix belongs primarily in bootstrap. |
| src/adapters/http/bounded-body-reader.ts | Declared-length and streamed byte ceilings, stream cancellation/release isolation, forbidden-body probing, strict UTF-8/JSON decode | V3 executor; bounded-body-reader tests | Keep as the single bounded response primitive. It already contains the cleanup behavior missing from bounded-json.ts. |
| src/adapters/http/bounded-json.ts | Legacy response stream reader and JSON decoder | legacy client.ts | Replace internals with bounded-body-reader delegation, then remove with V2 retirement. Current cancel/release failures can reject. |
| src/adapters/http/client.ts | Legacy/V2 operation lookup, profiles, auth recovery, retries, total deadline, response validation/mapping, diagnostics and telemetry | legacy contracts and ports; runtime-adapters createRuntimeHttpClient | Compatibility-only but exported. Fix empty keyed replay, cooperative auth cancellation, and common body-reader use before relying on it for rollback. Deprecate after callers are migrated. |
| src/adapters/http/client.ts | Legacy/V2 operation lookup, profiles, auth recovery, retries, total deadline, response validation/mapping, diagnostics and telemetry | legacy contracts and ports; runtime-adapters createRuntimeHttpClient | Compatibility-only but exported. Fix empty keyed replay, cooperative auth cancellation, and common body-reader use before relying on it for rollback. Not a drop-in rollback for V3: V2 validates the `{success,data,meta}` envelope and V3 the bare DTO, so a rollback needs the four slots and a V2-envelope server (Q-6.3-11). 401 recovery is a single replay outside the retry budget. Deprecate after callers are migrated. |
| src/adapters/http/http-contract-bridge.ts | V3 request projection, URL/body bounds, credential patch type, final request invariant | external-contract-runtime.ts; V3 executor | Preserve descriptor-owned request projection. Change credential authority: patch cannot own credentials or transport headers; final invariant must compare exact resolved profile. |
| src/adapters/http/http-effect-certainty.ts | Converts physical-attempt state and problem descriptors into mutation certainty/UI projection | V3 executor; contracts | Preserve explicit certainty vocabulary. Add a monotonic logical-execution certainty join used across retries. |
| src/adapters/http/http-execution-v3.ts | Descriptor-driven V3 lifetime: validation, projection, credentials, deadline, retry, fetch, response admission, effect verdict and observation | external contracts, scope, mutation intent, bridge, bounded reader, certainty, retry policy | Main correction site for N-01, N-02, N-03 and cooperative cancellation. Keep one retry authority and closed result union. |
| src/adapters/http/request-builder.ts | Legacy path/query construction and origin/base-prefix checks | legacy client; ApiOperation | Keep while V2 remains. Do not reuse it to weaken V3 descriptor projection. |
| src/adapters/http/resource-mapper.ts | Thin legacy operation-payload mapper delegation | boundary-mapper; legacy client | No standalone defect. Remove only with V2, not as part of the correctness patch. |
| src/adapters/http/retry-policy.ts | Legacy retry decision/backoff plus parseRetryAfter reused by V3 | legacy client and V3 executor | Keep deterministic parse/backoff seam. V2 must additionally prove a valid key before keyed replay. |
| src/adapters/http/retry-policy.ts | Legacy retry decision/backoff plus parseRetryAfter reused by V3; parsing delegates to kernel platform/retry-after.ts (Q-6.4-8) | legacy client and V3 executor; platform/retry-after.ts | Keep deterministic parse/backoff seam. V2 must additionally prove a valid key before keyed replay. |
| src/adapters/http/platform-error-mapping.ts | Maps feature-less V3 transport outcomes (cancel, timeout, network, response-invalid) to the platform AppError envelope; feature-owned outcomes return null | http-execution-v3.ts outcomes; platform/errors; feature HTTP binding | Keep. Registered 2026-09-24 (added in 6f6c48e without a ledger row). |
| src/adapters/http/schema-registry.ts | Legacy Zod envelope/request/payload validation and clone | legacy client/tests | No standalone defect. Remains V2-only and should not be merged with installed external validators. |
| src/adapters/platform/browser-lifecycle.ts | Single owner of visibility/network/focus/page/beforeunload listeners and lifecycle snapshots | optional-runtime-host.ts | Preserve centralized listener ownership and idempotent dispose. Clarify or redesign dirty-source attachment semantics; selection item O-02. |
| src/adapters/platform/browser-mutation-intent-factory.ts | Secure intent/idempotency UUIDs plus monotonic creation time, normalized by defineMutationIntent | MutationIntentFactory port; bootstrap | Keep. Share one idempotency-key validator so external inputs and generated values have identical bounds. |
| src/adapters/platform/json-member-scanner.ts | Non-recursive duplicate-member and structure-budget scan before `JSON.parse`; moved from realtime in 2nd round (Q-6.4-8) | realtime event codec and WS protocol; web-push hint codec | Keep. Single scanner; web-push now checks every depth, not only top-level keys. |
| src/adapters/platform/retry-after.ts | Strict Retry-After parser: delta-seconds or IMF-fixdate, no guessed delays (Q-6.4-8) | realtime reconnect policy / SSE; http retry-policy.ts | Keep. Rejects blank, decimal and exponent values the old http copy accepted. |
| src/adapters/platform/system-clock.ts | Wall clock and abortable sleep with listener/timer cleanup | ClockPort; legacy HTTP | Keep. Existing unit test covers abort cleanup behavior. |
| src/adapters/query-cache/conditional-validator-store.ts | In-memory ETag CAS sidecar keyed by scope, definition, identity, representation and cache revision | bootstrap scope reset; future conditional HTTP/query join | Fix tuple codec before composition. Preserve validator grammar, generation/revision checks and bounded capacity. |
| src/adapters/query-cache/cursor-pagination-runtime.ts | Bounded cursor chain, page/snapshot/loop/item/byte validation | cursor pagination contract; currently available but not composed | Add post-await abort admission or an abort race. Current pre-await-only check can admit a late page. |
@@ -77,6 +80,8 @@ All 24 files below were read in full.
| src/adapters/query-cache/tanstack-cache-coordinator.ts | Maps registry topics to query namespace invalidation, coalesces remote hints, defers under mutation leases, resets/disposes | TanStack Query, invalidation contracts, cross-context runtime | Keep invalidate-only remote authority, generation guard, reset serialization and bounded registry validation. Add teardown characterization if dispose becomes async. |
| src/adapters/query-cache/tanstack-query-cache.ts | Creates QueryClient defaults and QueryCachePort read/write/invalidate adapter with diagnostics | TanStack Query, QueryCachePort, errors/diagnostics | Keep retry disabled and clone-on-write. Clone-on-read is an optional port-semantics decision, not a confirmed production defect. |
| src/adapters/telemetry/best-effort-telemetry.ts | Allowlisted bounded oldest-drop telemetry queue, scheduled/pagehide flush, sink isolation and evidence | TelemetryPort, telemetry/diagnostic contracts, bootstrap | Add terminal lifecycle state, joined flush promise and in-flight abort; ensure runtime composition disposes it. |
| src/adapters/telemetry/feature-telemetry.ts | Feature TelemetryPort adapter over the platform telemetry pipeline; fetch transport to the collector endpoint | platform/telemetry pipeline; TelemetryPort; bootstrap | Keep. Registered 2026-09-24 (added in 6f6c48e without a ledger row); shares the collector with best-effort-telemetry (review 6.9-4). |
| src/adapters/telemetry/telemetry-collector.ts | The one collector transport behind both telemetry ports: shared send-rate window, `credentials: "omit"`, `cache: "no-store"`, per-request deadline through the kernel abort primitive, one `pagehide` fan-out | platform/telemetry send rate; adapters/platform abort and capacity kernel; bootstrap | Keep. Added 2026-09-24 for review 6.9-4 / 6.3-10: a hung collector no longer stalls later flushes, and the two ports no longer send 20+20 per minute. |
## 4. Traced boundary inventory
@@ -6,9 +6,9 @@
- 방식: 코드 리뷰만 수행했다. 이 문서 외 구현 파일은 수정하지 않았다.
- 결론: **Critical 0, High 4, Medium 3**이다. R-01~R-06은 코드상 확정된 lifecycle/immutability/resource 문제이고, R-07은 문서에도 미완료라고 명시된 production promotion blocker다. 두 runtime 모두 현재 `AVAILABLE_NOT_COMPOSED`이므로 production traffic 사고로 과장하지 않는다.
## 1. 21/21 파일 inventory와 책임
## 1. 20/20 파일 inventory와 책임
아래 경로는 모두 저장소 루트 기준 full path이며, 범위의 구현 파일 21개를 모두 읽었다.
아래 경로는 모두 저장소 루트 기준 full path이며, 범위의 구현 파일 21개를 모두 읽었다. 2차 라운드(Q-6.4-8)에서 `json-member-scanner.ts`는 kernel `src/adapters/platform/`로 옮겨 [Network/state](./01-network-and-state.md) 표에서 다룬다.
| # | full path | 책임 | 주요 의존성 / downstream | 판정 |
|---:|---|---|---|---|
@@ -16,23 +16,22 @@
| 2 | `src/adapters/browser-rpc/index.ts` | Browser RPC public adapter export surface | runtime, transport, unavailable adapter | 새 lease/install type export 필요 |
| 3 | `src/adapters/browser-rpc/transport.ts` | provider-neutral unary/stream transport result와 runtime identity 계약 | `src/contracts/browser-rpc.ts` | R-01, R-07 |
| 4 | `src/adapters/browser-rpc/unavailable-browser-rpc-transport.ts` | 선택되지 않은 runtime의 명시적 fail-closed Null Object | `transport.ts` | 유지; 새 stream lease shape만 맞춤 |
| 5 | `src/adapters/realtime/event-codec.ts` | raw JSON byte/shape/registry/schema 검증, immutable DTO와 semantic fingerprint 생성 | realtime contracts, schema registry, JSON scanner, result codec | 유지 |
| 5 | `src/adapters/realtime/event-codec.ts` | raw JSON byte/shape/registry/schema 검증, immutable DTO와 semantic fingerprint 생성 | realtime contracts, schema registry, kernel JSON scanner, result codec | 유지 |
| 6 | `src/adapters/realtime/event-consumer.ts` | SSE/WS cursor 규칙을 codec 결과와 결합하고 common stream coordinator outcome으로 투영 | realtime ports/contracts, event codec, stream coordinator | 유지 |
| 7 | `src/adapters/realtime/index.ts` | common realtime adapter public export surface | codec, consumer, reconnect, handoff, stream, sub-index | R-02/R-03 lifecycle type export 필요 |
| 8 | `src/adapters/realtime/json-member-scanner.ts` | `JSON.parse` 전 duplicate member와 structure budget을 비재귀적으로 검사 | 독립 utility | 유지 |
| 9 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | LIVE/POLL 단일 effect writer, generation fence, quiescence/checkpoint, probe buffer와 전환 | `ClockPort`, realtime result/ports | R-03 |
| 10 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | visible/online finite lease, single-flight poll, retry hint, response/apply deadline, non-cooperative task drain | bounded polling policy, `ClockPort`, realtime result | 유지 |
| 11 | `src/adapters/realtime/polling/index.ts` | polling public exports | bounded poll coordinator | 유지 |
| 12 | `src/adapters/realtime/reconnect-coordinator.ts` | 단일 reconnect owner, online gate, retry budget, session close authority, exact recovery proof, post-abort DRAINING | reconnect policy, `ClockPort`, realtime ports/result | 유지 |
| 13 | `src/adapters/realtime/reconnect-policy.ts` | immutable reconnect policy, full jitter, elapsed budget, Retry-After 계산/검증 | 독립 policy | 유지 |
| 14 | `src/adapters/realtime/result.ts` | hostile/mutable collaborator result를 exact own-data snapshot으로 canonicalize | realtime ports/contracts | 유지; R-04의 기준 패턴 |
| 15 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | fixed same-origin fetch-stream SSE, response/media/open gate, read/event deadline, cursor rule, bounded reader cancel | `ClockPort`, event authority/result, parser, reconnect policy | 유지; R-02 common drain과 함께 검증 |
| 16 | `src/adapters/realtime/sse/index.ts` | SSE public exports | fetch connection, parser | 유지 |
| 17 | `src/adapters/realtime/sse/sse-parser.ts` | strict incremental UTF-8 SSE parser, BOM/line ending/id/retry/event buffer ceiling | realtime contracts/result | 유지 |
| 18 | `src/adapters/realtime/stream-coordinator.ts` | per-stream sequential effect, dedupe/order, recovery, checkpoint/barrier, scope generation fence | event authority port, realtime contracts, mapper registry, codec/result | R-02 |
| 19 | `src/adapters/realtime/websocket/index.ts` | WebSocket connection/protocol public exports | connection, protocol | 유지 |
| 20 | `src/adapters/realtime/websocket/websocket-connection.ts` | 한 physical WS의 handshake/subscription/tombstone/FIFO/heartbeat/apply gate/recovery close | `ClockPort`, realtime contracts/result, WS protocol | 유지; R-02 upstream timeout과 함께 검증 |
| 21 | `src/adapters/realtime/websocket/websocket-protocol.ts` | exact closed JSON frame decode/encode, duplicate key/structure/sequence/frame byte 검증 | realtime contracts, JSON scanner | R-05 |
| 8 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | LIVE/POLL 단일 effect writer, generation fence, quiescence/checkpoint, probe buffer와 전환 | `ClockPort`, realtime result/ports | R-03 |
| 9 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | visible/online finite lease, single-flight poll, retry hint, response/apply deadline, non-cooperative task drain | bounded polling policy, `ClockPort`, realtime result | 유지 |
| 10 | `src/adapters/realtime/polling/index.ts` | polling public exports | bounded poll coordinator | 유지 |
| 11 | `src/adapters/realtime/reconnect-coordinator.ts` | 단일 reconnect owner, online gate, retry budget, session close authority, exact recovery proof, post-abort DRAINING | reconnect policy, `ClockPort`, realtime ports/result | 유지 |
| 12 | `src/adapters/realtime/reconnect-policy.ts` | immutable reconnect policy, full jitter, elapsed budget; Retry-After 파서는 kernel `platform/retry-after.ts`를 re-export | kernel retry-after | 유지 |
| 13 | `src/adapters/realtime/result.ts` | hostile/mutable collaborator result를 exact own-data snapshot으로 canonicalize | realtime ports/contracts | 유지; R-04의 기준 패턴 |
| 14 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | fixed same-origin fetch-stream SSE, response/media/open gate, read/event deadline, cursor rule, bounded reader cancel | `ClockPort`, event authority/result, parser, reconnect policy | 유지; R-02 common drain과 함께 검증 |
| 15 | `src/adapters/realtime/sse/index.ts` | SSE public exports | fetch connection, parser | 유지 |
| 16 | `src/adapters/realtime/sse/sse-parser.ts` | strict incremental UTF-8 SSE parser, BOM/line ending/id/retry/event buffer ceiling | realtime contracts/result | 유지 |
| 17 | `src/adapters/realtime/stream-coordinator.ts` | per-stream sequential effect, dedupe/order, recovery, checkpoint/barrier, scope generation fence | event authority port, realtime contracts, mapper registry, codec/result | R-02 |
| 18 | `src/adapters/realtime/websocket/index.ts` | WebSocket connection/protocol public exports | connection, protocol | 유지 |
| 19 | `src/adapters/realtime/websocket/websocket-connection.ts` | 한 physical WS의 handshake/subscription/tombstone/FIFO/heartbeat/apply gate/recovery close | `ClockPort`, realtime contracts/result, WS protocol | 유지; R-02 upstream timeout과 함께 검증 |
| 20 | `src/adapters/realtime/websocket/websocket-protocol.ts` | exact closed JSON frame decode/encode, duplicate key/structure/sequence/frame byte 검증 | realtime contracts, kernel JSON scanner | R-05 |
## 2. 추적한 contracts, ports, bootstrap, tests, docs
@@ -31,7 +31,7 @@
| 파일 | 책임 | 주요 의존성 / 리뷰 결과 |
| --- | --- | --- |
| `src/adapters/browser-file-storage/index.ts` | browser data 공통 Result와 StorageManager adapter barrel export | 내부 두 모듈만 export. 경계가 작고 유지 대상. |
| `src/adapters/browser-file-storage/result.ts` | native 예외를 closed `BrowserDataFailure`로 정규화하고 안전한 observation 제공 | `application/ports/browser-file-storage/shared.ts`; raw path/name/message 비노출, observer 예외 격리가 좋다. |
| `src/adapters/browser-file-storage/result.ts` | native 예외를 closed `BrowserDataFailure`로 정규화하고 안전한 observation 제공. IndexedDB 예외 표 `mapIndexedDbException`도 여기 있다(05-11, 옛 `storage/indexeddb/indexeddb-failure.ts`) | `application/ports/browser-file-storage/shared.ts`; raw path/name/message 비노출, observer 예외 격리가 좋다. |
| `src/adapters/browser-file-storage/storage-manager-adapter.ts` | `estimate/persisted/persist` snapshot, pressure bucket, user-activation-bound persistence 요청 | storage durability port/result. estimate를 예약량으로 오인하지 않고 irreversible `persist()` truth를 보존한다. origin coordinator는 의도적으로 없음(GAP-03). |
### 1.2 `browser-files`
@@ -43,6 +43,7 @@
| `src/adapters/browser-files/browser-file-vault.ts` | transient native File/handle 보관, opaque ref, inspection receipt, bounded range/source | file port/shared/result/policy registry. File이 application 경계를 넘지 않고 receipt가 exact file/profile에 묶이는 설계가 좋다. |
| `src/adapters/browser-files/create-browser-file-runtime.ts` | vault/picker/preview/download를 선택적으로 조립하고 일괄 dispose | 위 adapters 및 application contracts. optional capability를 제품 선택 없이 bootstrap에 암묵 조립하지 않는 점을 유지. preview 조립 전 GAP-01 gate 필요. |
| `src/adapters/browser-files/download-delivery-adapter.ts` | browser handoff, foreground save stream, bounded object URL download, integrity/progress/cancellation | file/authorized-download ports, policy registry, object URL lease, Result. STO-02와 STO-08; stream close truth/backpressure는 유지. |
| `src/adapters/browser-files/download-input-validation.ts` | download 요청 snapshot, policy/limit/activation 검증, presigned·browser-managed capability 검증, canonical handoff target 해석 | file/authorized-download ports, policy registry, `file-policy.ts`, Result. Q-6.2-11에서 adapter에서 그대로 옮겼다(동작 불변). |
| `src/adapters/browser-files/file-observer.ts` | file-safe observation DTO를 공통 browser observation으로 변환 | shared port/result. raw filename/ref 비노출 유지. |
| `src/adapters/browser-files/file-policy.ts` | policy input validation, MIME/extension/signature/hard byte caps, immutable resolved policy | file/shared contracts. closed allowlist 및 absolute ceiling을 유지. |
| `src/adapters/browser-files/index.ts` | browser-file public exports | 위 모듈. native implementation detail export 확장을 피한다. |
@@ -53,7 +54,9 @@
| 파일 | 책임 | 주요 의존성 / 리뷰 결과 |
| --- | --- | --- |
| `src/adapters/cache-storage/index.ts` | public cache policy/adapter barrel | optional public static cache만 export; private/range cache로 일반화하지 않는다. |
| `src/adapters/cache-storage/public-cache-codec.ts` | manifest 정규화·canonical digest 입력, marker/active pointer 검증, bounded control JSON 읽기, owned cache 이름, 검증 실패 → Result 매핑 | cache ports/result/policy. Q-6.2-11에서 adapter에서 그대로 옮겼다(동작 불변). |
| `src/adapters/cache-storage/public-cache-policy.ts` | same-origin/public-only release 정책, URL/header/query/size/retention hard limits | cache ports/shared. STO-03 policy cross-field invariant 누락. 기본 policy에는 `vary`가 있어 기본-path 테스트는 통과한다. |
| `src/adapters/cache-storage/public-cache-response-validation.ts` | network/cached response 수용 검증: status, cache directive, Content-Type, Vary, bounded body, digest | `public-cache-codec.ts`, policy, Result. Q-6.2-11에서 adapter에서 그대로 옮겼다(동작 불변). |
| `src/adapters/cache-storage/public-response-cache-adapter.ts` | manifest canonicalization/digest, anonymous fetch, bounded body 검증, candidate marker-last staging, explicit activation, exact lookup/reverify, owned cleanup/inspect | cache ports/result/policy, CacheStorage/fetch/Crypto/Web Lock snapshot. STO-03~05 및 GAP-02. private/auth/opaque/206 거절과 current+previous 보존은 유지. |
### 1.4 `storage` root / IndexedDB
@@ -63,10 +66,10 @@
| `src/adapters/storage/browser-storage-adapter.ts` | registry key별 local/session/memory 저장, TTL, failure overlay/tombstone, quota fallback | `storage-keys`, `StoragePort`, codec, diagnostics. strict registry와 stale persistent suppression을 유지. adjacent physical-key migration/sweep는 문서상 미구현. |
| `src/adapters/storage/browser-storage-codec.ts` | bounded exact JSON envelope, exotic/accessor/unsafe-key/cycle/depth/node 거절 | 독립 codec. prototype pollution/JSON silent coercion 방어가 좋다. |
| `src/adapters/storage/indexeddb/index.ts` | IndexedDB runtime/maintenance/governance/migration export | native IDB type을 application port 밖으로 내보내지 않는 구조 유지. |
| `src/adapters/storage/indexeddb/indexeddb-failure.ts` | IDB/DOM failure를 closed browser failure로 변환 | common Result. raw native detail 비노출 유지. |
| `src/adapters/storage/indexeddb/indexeddb-governance.ts` | opaque dataset scope/physical DB identity 및 frozen policy binding | indexeddb/shared ports. account/business ID를 physical name에 쓰지 않는 양방향 binding 유지. |
| `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | post-open codec migration 및 idempotency receipt prune, keyset checkpoint, budget/revision fencing | IndexedDB port/types/failure/governance. async transform outside tx, row+sidecar+budget+checkpoint atomic commit은 좋다. STO-06 및 temporal drain lease 개선 후보. |
| `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | additive-only contiguous DDL planner/validator | indexeddb types. destructive DDL 거절 유지. |
| `src/adapters/storage/indexeddb/indexeddb-records.ts` | runtime·maintenance·dataset binding이 함께 쓰는 저장 행 타입, 검증기, record 바이트 측정, `countBucket`/`failureOf` | IndexedDB port/shared/types. Q-6.5-7: 복사본 3벌을 하나로 합쳤다. 실패 코드는 호출부가 정한다(runtime `INVALID_INPUT`, maintenance `MIGRATION_FAILED`). budget의 `hardBudgetBytes` 상한은 binding 검증에서만 본다. |
| `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | generic repository open/read/query/CAS/delete, idempotency, retention, lifecycle purge, connection lifecycle | indexeddb ports/types/governance/failure/migrations. transaction `complete` truth, versionchange close, shared open/abort isolation, exact budgets 유지. lifecycle proof는 현재 문서 계약(형식 검증 후 폐기)과 일치하므로 결함으로 분류하지 않았다. |
| `src/adapters/storage/indexeddb/indexeddb-types.ts` | adapter-local codec/query/schema/dependency contracts | application indexeddb/shared ports. `isOldWriterDrainConfirmed()` boolean은 provider가 전체 window를 보장한다는 문서 전제; lease형으로 강화 권고. |
@@ -79,6 +82,7 @@
| `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | logical object/journal/budget/chunk refcount의 IDB authority; begin/files-ready/commit/rollback/reconcile pages | OPFS ports, IDB failure, policy. journal+object+budget CAS atomicity가 좋다. STO-01 수정에서 incomplete row를 cleanup 확인 전 삭제하지 않아야 한다. |
| `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | logical journal과 physical worker를 saga로 조정, put/open/remove, reconcile/policy maintenance | OPFS/shared ports, journal, worker gateway, policy. STO-01의 journal/physical compensation ordering 결함 위치. |
| `src/adapters/storage/opfs/opfs-policy.ts` | root/lock/chunk/object/RPC/reconcile/GC hard limits 및 scope validation | shared/opfs ports. opaque physical path와 absolute caps 유지. |
| `src/adapters/storage/opfs/opfs-prepared-object.ts` | page·journal·worker가 함께 쓰는 prepared-object 검증기 하나 | OPFS/shared ports, opfs-policy scope 검증. R-5.5: 저장된 객체는 자기 manifest의 `chunkSizeBytes`로 검증하고 현재 정책값은 새 쓰기에만 적용. |
| `src/adapters/storage/opfs/opfs-worker-client.ts` | request correlation/timeout/abort/transferable chunking, worker gateway, streamed reads | protocol/policy/shared Result. STO-01의 untracked abort cleanup 및 STO-07의 shallow response parse. |
| `src/adapters/storage/opfs/opfs-worker-protocol.ts` | page↔DedicatedWorker request/response union 및 gateway contract | OPFS/shared ports. STO-07; protocol version/kind/effect certainty 추가 필요. |
| `src/adapters/storage/opfs/opfs-worker-runtime.ts` | DedicatedWorker OPFS physical layout, lock lease, immutable chunk, manifest/staging receipt, abort/finalize/remove/GC | protocol/policy/OPFS ports/Web Lock/Crypto. STO-01의 generation-only cleanup과 lease release 순서. sync handle `finally close` 등은 유지. |
+4 -1
View File
@@ -35,6 +35,7 @@
| --- | --- | --- | --- |
| `browser-transfer/index.ts` | 하위 capability export | KEEP | public export 증가는 각 capability 계획에서만 수행 |
| `presigned/index.ts` | presigned public surface | KEEP | `BT-PRE-04`에서 vault issuer 노출만 축소 검토 |
| `presigned/http-common.ts` | executor·provider 공용 HTTP 메커니즘(abort scope, status 표, Content-Length 파싱, body 취소) | KEEP | Q-6.1-9. 두 벌이던 사본을 합쳤다. status 표는 여기 한 벌만 둔다 |
| `presigned/incremental-sha256.ts` | streaming SHA-256 | KEEP | WebCrypto `digest()`로 바꾸면 전체 buffering이 되므로 교체 금지 |
| `presigned/presigned-capability-http-provider.ts` | BFF capability 발급, strict decode | CONTRACT_GAP | `BT-PRE-02`, `BT-PRE-03`, `BT-X-01` |
| `presigned/presigned-capability-vault.ts` | identity capability 보관/폐기 | REFACTOR | `BT-PRE-04` |
@@ -45,8 +46,10 @@
| `resumable-upload/index.ts` | resumable public surface | KEEP | facade 호환 유지 |
| `resumable-upload/indexeddb-checkpoint-store.ts` | scope-bound CAS store/admin | VERIFIED_DEFECT | `BT-UP-03` |
| `resumable-upload/presigned-upload-part-executor.ts` | multipart와 presigned bridge | VERIFIED_DEFECT | `BT-UP-04` |
| `resumable-upload/resumable-upload-runtime.ts` | session state/retry/part scheduling/commit | REFACTOR | `BT-UP-05`, `BT-UP-06` |
| `resumable-upload/resumable-upload-runtime.ts` | session state/retry/part scheduling/commit | REFACTOR | `BT-UP-05`, `BT-UP-06`. Q-6.1-10에서 검증·snapshot 래퍼를 분리 |
| `resumable-upload/runtime-dependencies.ts` | runtime 주입 의존성 검증과 메서드 snapshot, clock/random guard | KEEP | Q-6.1-10. runtime 파일에서 분리, 동작 불변 |
| `resumable-upload/runtime-policy.ts` | hard bound snapshot | KEEP | 값 변경은 contract migration으로만 수행 |
| `resumable-upload/upload-response-validation.ts` | session/status/part capability/receipt strict decoder | KEEP | Q-6.1-10. runtime 파일에서 분리, 동작 불변 |
| `resumable-upload/upload-byte-source.ts` | stream/range source snapshot과 hashing | KEEP/REFACTOR | runtime에서 source preparation Strategy로 주입 |
| `resumable-upload/upload-cancellation-channel.ts` | best-effort cross-context cancel hint | KEEP | backend/CAS가 authority라는 주석과 동작 유지 |
| `resumable-upload/upload-mutation-lock.ts` | Web Lock exclusive mutation | PLANNED_GAP | `BT-UP-07` |
@@ -30,6 +30,7 @@ Web Push는 현재 `AVAILABLE_NOT_COMPOSED`이고 제품 선택도 `NOT_SELECTED
| `service-worker-protocol.ts` | page-worker strict message codec/nonce | CONTRACT_GAP | `SW-06`, `SW-10` |
| `service-worker-removal.ts` | exact registration/cache ownership cleanup | VERIFIED_DEFECT | `SW-03` |
| `service-worker-static-assets.ts` | static manifest/install/cache policy | KEEP/REFACTOR | `SW-01`, `SW-05`, `SW-09` |
| `web-push/codec-primitives.ts` | 공유 검증 primitive(base64url decode, opaque id, authority, exact record) | KEEP | Q-6.6-12에서 4개 파일의 복사본을 합침. 복사본이 다르던 곳은 더 엄격한 쪽을 유지 |
| `web-push/index.ts` | public exports | KEEP | product selection 전 surface 확대 금지 |
| `web-push/notification-registry.ts` | closed copy/route registry | KEEP | arbitrary copy/URL 허용 금지 |
| `web-push/push-association-fence-store.ts` | durable authority state machine | VERIFIED_DEFECT | `WP-01`, `WP-02` |
+136 -124
View File
@@ -18,131 +18,143 @@
| 8 | `src/adapters/browser-files/browser-file-vault.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 9 | `src/adapters/browser-files/create-browser-file-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 10 | `src/adapters/browser-files/download-delivery-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 11 | `src/adapters/browser-files/file-observer.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 12 | `src/adapters/browser-files/file-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 13 | `src/adapters/browser-files/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 14 | `src/adapters/browser-files/object-url-lease.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 15 | `src/adapters/browser-rpc/browser-rpc-runtime.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 16 | `src/adapters/browser-rpc/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 17 | `src/adapters/browser-rpc/transport.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 18 | `src/adapters/browser-rpc/unavailable-browser-rpc-transport.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 19 | `src/adapters/browser-transfer/image-cdn/README.md` | [Browser transfer](./04-browser-transfer.md) |
| 20 | `src/adapters/browser-transfer/image-cdn/browser-image-probe.ts` | [Browser transfer](./04-browser-transfer.md) |
| 21 | `src/adapters/browser-transfer/image-cdn/image-cdn-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 22 | `src/adapters/browser-transfer/image-cdn/image-cdn-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 23 | `src/adapters/browser-transfer/image-cdn/image-header-metadata.ts` | [Browser transfer](./04-browser-transfer.md) |
| 24 | `src/adapters/browser-transfer/image-cdn/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 25 | `src/adapters/browser-transfer/image-cdn/p256-image-capability-verifier.ts` | [Browser transfer](./04-browser-transfer.md) |
| 26 | `src/adapters/browser-transfer/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 27 | `src/adapters/browser-transfer/presigned/incremental-sha256.ts` | [Browser transfer](./04-browser-transfer.md) |
| 28 | `src/adapters/browser-transfer/presigned/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 29 | `src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts` | [Browser transfer](./04-browser-transfer.md) |
| 30 | `src/adapters/browser-transfer/presigned/presigned-capability-vault.ts` | [Browser transfer](./04-browser-transfer.md) |
| 31 | `src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 32 | `src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts` | [Browser transfer](./04-browser-transfer.md) |
| 33 | `src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts` | [Browser transfer](./04-browser-transfer.md) |
| 34 | `src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts` | [Browser transfer](./04-browser-transfer.md) |
| 35 | `src/adapters/browser-transfer/resumable-upload/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 36 | `src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts` | [Browser transfer](./04-browser-transfer.md) |
| 37 | `src/adapters/browser-transfer/resumable-upload/presigned-upload-part-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 38 | `src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 39 | `src/adapters/browser-transfer/resumable-upload/runtime-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 40 | `src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts` | [Browser transfer](./04-browser-transfer.md) |
| 41 | `src/adapters/browser-transfer/resumable-upload/upload-cancellation-channel.ts` | [Browser transfer](./04-browser-transfer.md) |
| 42 | `src/adapters/browser-transfer/resumable-upload/upload-mutation-lock.ts` | [Browser transfer](./04-browser-transfer.md) |
| 43 | `src/adapters/cache-storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 44 | `src/adapters/cache-storage/public-cache-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 45 | `src/adapters/cache-storage/public-response-cache-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 46 | `src/adapters/cross-context-invalidation/browser-cross-context-host.ts` | [Network/state](./01-network-and-state.md) |
| 47 | `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts` | [Network/state](./01-network-and-state.md) |
| 48 | `src/adapters/cross-context-invalidation/index.ts` | [Network/state](./01-network-and-state.md) |
| 49 | `src/adapters/diagnostics/bounded-diagnostics.ts` | [Network/state](./01-network-and-state.md) |
| 50 | `src/adapters/diagnostics/index.ts` | [Network/state](./01-network-and-state.md) |
| 51 | `src/adapters/http/bounded-body-reader.ts` | [Network/state](./01-network-and-state.md) |
| 52 | `src/adapters/http/bounded-json.ts` | [Network/state](./01-network-and-state.md) |
| 53 | `src/adapters/http/client.ts` | [Network/state](./01-network-and-state.md) |
| 54 | `src/adapters/http/feature-http-binding.ts` | [Network/state](./01-network-and-state.md) |
| 55 | `src/adapters/http/http-contract-bridge.ts` | [Network/state](./01-network-and-state.md) |
| 56 | `src/adapters/http/http-effect-certainty.ts` | [Network/state](./01-network-and-state.md) |
| 57 | `src/adapters/http/http-execution-v3.ts` | [Network/state](./01-network-and-state.md) |
| 58 | `src/adapters/http/http-retry-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 59 | `src/adapters/http/index.ts` | [Network/state](./01-network-and-state.md) |
| 60 | `src/adapters/http/request-builder.ts` | [Network/state](./01-network-and-state.md) |
| 61 | `src/adapters/http/resource-mapper.ts` | [Network/state](./01-network-and-state.md) |
| 62 | `src/adapters/http/retry-policy.ts` | [Network/state](./01-network-and-state.md) |
| 63 | `src/adapters/http/schema-registry.ts` | [Network/state](./01-network-and-state.md) |
| 64 | `src/adapters/platform/abortable-operation.ts` | [Network/state](./01-network-and-state.md) |
| 65 | `src/adapters/platform/bounded-capacity.ts` | [Network/state](./01-network-and-state.md) |
| 66 | `src/adapters/platform/browser-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 67 | `src/adapters/platform/browser-mutation-intent-factory.ts` | [Network/state](./01-network-and-state.md) |
| 68 | `src/adapters/platform/index.ts` | [Network/state](./01-network-and-state.md) |
| 69 | `src/adapters/platform/indexeddb-connection.ts` | [Network/state](./01-network-and-state.md) |
| 70 | `src/adapters/platform/indexeddb-transaction.ts` | [Network/state](./01-network-and-state.md) |
| 71 | `src/adapters/platform/system-clock.ts` | [Network/state](./01-network-and-state.md) |
| 72 | `src/adapters/query-cache/conditional-validator-store.ts` | [Network/state](./01-network-and-state.md) |
| 73 | `src/adapters/query-cache/cursor-pagination-contract.ts` | [Network/state](./01-network-and-state.md) |
| 74 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 75 | `src/adapters/query-cache/index.ts` | [Network/state](./01-network-and-state.md) |
| 76 | `src/adapters/query-cache/server-state-scope-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 77 | `src/adapters/query-cache/tanstack-cache-coordinator.ts` | [Network/state](./01-network-and-state.md) |
| 78 | `src/adapters/query-cache/tanstack-query-cache.ts` | [Network/state](./01-network-and-state.md) |
| 79 | `src/adapters/realtime/event-codec.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 80 | `src/adapters/realtime/event-consumer.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 81 | `src/adapters/realtime/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 82 | `src/adapters/realtime/json-member-scanner.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 83 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 84 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 85 | `src/adapters/realtime/polling/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 86 | `src/adapters/realtime/reconnect-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 87 | `src/adapters/realtime/reconnect-policy.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 88 | `src/adapters/realtime/result.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 89 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 90 | `src/adapters/realtime/sse/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 91 | `src/adapters/realtime/sse/sse-parser.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 92 | `src/adapters/realtime/stream-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 93 | `src/adapters/realtime/websocket/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 94 | `src/adapters/realtime/websocket/websocket-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 95 | `src/adapters/realtime/websocket/websocket-protocol.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 96 | `src/adapters/service-worker/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 97 | `src/adapters/service-worker/service-worker-entry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 98 | `src/adapters/service-worker/service-worker-lifecycle.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 99 | `src/adapters/service-worker/service-worker-page-controller.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 100 | `src/adapters/service-worker/service-worker-protocol.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 101 | `src/adapters/service-worker/service-worker-removal.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 102 | `src/adapters/service-worker/service-worker-static-assets.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 103 | `src/adapters/storage/browser-storage-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 104 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 105 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 106 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 107 | `src/adapters/storage/indexeddb/indexeddb-failure.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 108 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 109 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 110 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 111 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 112 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 113 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 114 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 115 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 122 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 123 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 124 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 125 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 126 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 127 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 128 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 129 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 130 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 131 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 132 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 133 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 11 | `src/adapters/browser-files/download-input-validation.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 12 | `src/adapters/browser-files/file-observer.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 13 | `src/adapters/browser-files/file-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 14 | `src/adapters/browser-files/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 15 | `src/adapters/browser-files/object-url-lease.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 16 | `src/adapters/browser-rpc/browser-rpc-runtime.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 17 | `src/adapters/browser-rpc/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 18 | `src/adapters/browser-rpc/transport.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 19 | `src/adapters/browser-rpc/unavailable-browser-rpc-transport.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 20 | `src/adapters/browser-transfer/image-cdn/README.md` | [Browser transfer](./04-browser-transfer.md) |
| 21 | `src/adapters/browser-transfer/image-cdn/browser-image-probe.ts` | [Browser transfer](./04-browser-transfer.md) |
| 22 | `src/adapters/browser-transfer/image-cdn/image-cdn-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 23 | `src/adapters/browser-transfer/image-cdn/image-cdn-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 24 | `src/adapters/browser-transfer/image-cdn/image-header-metadata.ts` | [Browser transfer](./04-browser-transfer.md) |
| 25 | `src/adapters/browser-transfer/image-cdn/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 26 | `src/adapters/browser-transfer/image-cdn/p256-image-capability-verifier.ts` | [Browser transfer](./04-browser-transfer.md) |
| 27 | `src/adapters/browser-transfer/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 28 | `src/adapters/browser-transfer/presigned/http-common.ts` | [Browser transfer](./04-browser-transfer.md) |
| 29 | `src/adapters/browser-transfer/presigned/incremental-sha256.ts` | [Browser transfer](./04-browser-transfer.md) |
| 30 | `src/adapters/browser-transfer/presigned/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 31 | `src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts` | [Browser transfer](./04-browser-transfer.md) |
| 32 | `src/adapters/browser-transfer/presigned/presigned-capability-vault.ts` | [Browser transfer](./04-browser-transfer.md) |
| 33 | `src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 34 | `src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts` | [Browser transfer](./04-browser-transfer.md) |
| 35 | `src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts` | [Browser transfer](./04-browser-transfer.md) |
| 36 | `src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts` | [Browser transfer](./04-browser-transfer.md) |
| 37 | `src/adapters/browser-transfer/resumable-upload/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 38 | `src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts` | [Browser transfer](./04-browser-transfer.md) |
| 39 | `src/adapters/browser-transfer/resumable-upload/presigned-upload-part-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 40 | `src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 41 | `src/adapters/browser-transfer/resumable-upload/runtime-dependencies.ts` | [Browser transfer](./04-browser-transfer.md) |
| 42 | `src/adapters/browser-transfer/resumable-upload/runtime-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 43 | `src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts` | [Browser transfer](./04-browser-transfer.md) |
| 44 | `src/adapters/browser-transfer/resumable-upload/upload-cancellation-channel.ts` | [Browser transfer](./04-browser-transfer.md) |
| 45 | `src/adapters/browser-transfer/resumable-upload/upload-mutation-lock.ts` | [Browser transfer](./04-browser-transfer.md) |
| 46 | `src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts` | [Browser transfer](./04-browser-transfer.md) |
| 47 | `src/adapters/cache-storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 48 | `src/adapters/cache-storage/public-cache-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 49 | `src/adapters/cache-storage/public-cache-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 50 | `src/adapters/cache-storage/public-cache-response-validation.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 51 | `src/adapters/cache-storage/public-response-cache-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 52 | `src/adapters/cross-context-invalidation/browser-cross-context-host.ts` | [Network/state](./01-network-and-state.md) |
| 53 | `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts` | [Network/state](./01-network-and-state.md) |
| 54 | `src/adapters/cross-context-invalidation/index.ts` | [Network/state](./01-network-and-state.md) |
| 55 | `src/adapters/diagnostics/bounded-diagnostics.ts` | [Network/state](./01-network-and-state.md) |
| 56 | `src/adapters/diagnostics/index.ts` | [Network/state](./01-network-and-state.md) |
| 57 | `src/adapters/http/bounded-body-reader.ts` | [Network/state](./01-network-and-state.md) |
| 58 | `src/adapters/http/bounded-json.ts` | [Network/state](./01-network-and-state.md) |
| 59 | `src/adapters/http/client.ts` | [Network/state](./01-network-and-state.md) |
| 60 | `src/adapters/http/feature-http-binding.ts` | [Network/state](./01-network-and-state.md) |
| 61 | `src/adapters/http/http-contract-bridge.ts` | [Network/state](./01-network-and-state.md) |
| 62 | `src/adapters/http/http-effect-certainty.ts` | [Network/state](./01-network-and-state.md) |
| 63 | `src/adapters/http/http-execution-v3.ts` | [Network/state](./01-network-and-state.md) |
| 64 | `src/adapters/http/http-retry-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 65 | `src/adapters/http/index.ts` | [Network/state](./01-network-and-state.md) |
| 66 | `src/adapters/http/platform-error-mapping.ts` | [Network/state](./01-network-and-state.md) |
| 67 | `src/adapters/http/request-builder.ts` | [Network/state](./01-network-and-state.md) |
| 68 | `src/adapters/http/resource-mapper.ts` | [Network/state](./01-network-and-state.md) |
| 69 | `src/adapters/http/retry-policy.ts` | [Network/state](./01-network-and-state.md) |
| 70 | `src/adapters/http/schema-registry.ts` | [Network/state](./01-network-and-state.md) |
| 71 | `src/adapters/platform/abortable-operation.ts` | [Network/state](./01-network-and-state.md) |
| 72 | `src/adapters/platform/bounded-capacity.ts` | [Network/state](./01-network-and-state.md) |
| 73 | `src/adapters/platform/browser-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 74 | `src/adapters/platform/browser-mutation-intent-factory.ts` | [Network/state](./01-network-and-state.md) |
| 75 | `src/adapters/platform/index.ts` | [Network/state](./01-network-and-state.md) |
| 76 | `src/adapters/platform/indexeddb-connection.ts` | [Network/state](./01-network-and-state.md) |
| 77 | `src/adapters/platform/indexeddb-transaction.ts` | [Network/state](./01-network-and-state.md) |
| 78 | `src/adapters/platform/json-member-scanner.ts` | [Network/state](./01-network-and-state.md) |
| 79 | `src/adapters/platform/retry-after.ts` | [Network/state](./01-network-and-state.md) |
| 80 | `src/adapters/platform/system-clock.ts` | [Network/state](./01-network-and-state.md) |
| 81 | `src/adapters/query-cache/conditional-validator-store.ts` | [Network/state](./01-network-and-state.md) |
| 82 | `src/adapters/query-cache/cursor-pagination-contract.ts` | [Network/state](./01-network-and-state.md) |
| 83 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 84 | `src/adapters/query-cache/index.ts` | [Network/state](./01-network-and-state.md) |
| 85 | `src/adapters/query-cache/server-state-scope-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 86 | `src/adapters/query-cache/tanstack-cache-coordinator.ts` | [Network/state](./01-network-and-state.md) |
| 87 | `src/adapters/query-cache/tanstack-query-cache.ts` | [Network/state](./01-network-and-state.md) |
| 88 | `src/adapters/realtime/event-codec.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 89 | `src/adapters/realtime/event-consumer.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 90 | `src/adapters/realtime/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 91 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 92 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 93 | `src/adapters/realtime/polling/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 94 | `src/adapters/realtime/reconnect-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 95 | `src/adapters/realtime/reconnect-policy.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 96 | `src/adapters/realtime/result.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 97 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 98 | `src/adapters/realtime/sse/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 99 | `src/adapters/realtime/sse/sse-parser.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 100 | `src/adapters/realtime/stream-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 101 | `src/adapters/realtime/websocket/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 102 | `src/adapters/realtime/websocket/websocket-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 103 | `src/adapters/realtime/websocket/websocket-protocol.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 104 | `src/adapters/service-worker/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 105 | `src/adapters/service-worker/service-worker-entry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 106 | `src/adapters/service-worker/service-worker-lifecycle.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 107 | `src/adapters/service-worker/service-worker-page-controller.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 108 | `src/adapters/service-worker/service-worker-protocol.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 109 | `src/adapters/service-worker/service-worker-removal.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 110 | `src/adapters/service-worker/service-worker-static-assets.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 111 | `src/adapters/storage/browser-storage-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 112 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 113 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 114 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 115 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/indexeddb/indexeddb-records.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 122 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 123 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 124 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 125 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 126 | `src/adapters/storage/opfs/opfs-prepared-object.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 127 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 128 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 129 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 130 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 131 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 132 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 133 | `src/adapters/telemetry/telemetry-collector.ts` | [Network/state](./01-network-and-state.md) |
| 134 | `src/adapters/web-push/codec-primitives.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 135 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 136 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 137 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 138 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 139 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 140 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 141 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 142 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 143 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 144 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 145 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
합계: **133/133**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
합계: **145/145**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
## Feature-scoped adapter 리뷰 (`src/adapters/**` 밖)
+5
View File
@@ -11,3 +11,8 @@ Close only when compatibility and release-coherence gates pass, critical smoke
passes, repeated `DEPLOY_MISMATCH` is absent, and the incident timeline records
the restored release ID. Pointer-switch or cache-purge completion alone is not
recovery evidence.
Verify the prior release before switching to it: `verify:promotion -- --root
<bundle> --archived` and `drill:runbook -- FE-RB-005 --release-root <extracted
archive>`. The commands and inputs are in
[`docs/operations/release-cache-rollback.md`](../operations/release-cache-rollback.md).
+16 -1
View File
@@ -7,7 +7,22 @@ maps are prohibited defaults.
`config/hosting/security-headers.json` is the declared header set. Hosting
verification compares that declaration with live responses. CSP deliberately
omits `unsafe-inline` and `unsafe-eval`; production code and built assets must
remain compatible with that baseline.
remain compatible with that baseline. `tests/e2e/production-csp.spec.ts` (part of
`test:e2e`, FE-GATE-008) serves the build with these headers and fails on a
`securitypolicyviolation` event or console error (review 13-08). zod probes
`Function("")` on its first object schema, which the policy would report on
every boot. `src/contracts/zod.ts` sets `jitless` to skip that probe, and every
module that builds a schema imports `z` from there, so the setting is applied
before the first schema whatever order the bundler evaluates chunks in.
`z.config` in the entry module would be too late. Import `z` from
`src/contracts/zod.ts`, not from `zod`, in new schema code. Features that are off by
default need CSP additions when a project selects them; see step 9 in
[optional adapter recipes](../architecture/optional-adapter-recipes.md).
`connect-src 'self' https:` lets script reach any HTTPS origin. Narrowing it to
the runtime config's `API_BASE_URL` and `TELEMETRY_ENDPOINT` origins needs a
header generated per environment at deploy time, because those values are set
per deployment (`scripts/generate-runtime-config.ts`). That generator does not
exist yet; a project that deploys should add it with its provider adapter.
Route guards are UX hints and client validation does not replace backend
authorization or validation.
+69
View File
@@ -39,6 +39,75 @@ Changing it requires `DEPENDENCY_BASELINE_OWNER` and
`DEPENDENCY_BASELINE_REASON`; editing the digest or hardcoding an empty diff is
rejected.
## 무엇을 증명하고 무엇을 증명하지 않는가
리뷰 13-12. 산출물마다 증명 범위가 다르다. 아래 "증명하지 못하는 것"을 증명된
것으로 읽지 않는다.
| 산출물 | 증명하는 것 | 증명하지 못하는 것 |
|---|---|---|
| SBOM(`artifacts/release/sbom.cdx.json`) | lockfile에 고정된 설치 그래프(`pnpm list --depth Infinity`, `scripts/generate-supply-chain.ts`)와 각 패키지의 sha512 integrity, license | 배포물에 실제로 들어간 부분 집합, 취약점 없음 |
| 번들 패키지 목록(`artifacts/quality/vite-module-inventory.json`의 `packages`) | 배포 번들에 모듈이 하나 이상 들어간 패키지의 `name@version`. Vite가 번들에 넣은 모듈에서 바로 만든다(`scripts/lib/vite-module-inventory.ts`) | 패키지 안의 어떤 코드가 실행되는지, 취약점 없음 |
| local provenance(`artifacts/release/provenance.json`) | dist digest, lockfile, source set, SBOM digest가 서로 맞음 | 빌드 과정이 변조되지 않았음, 빌드한 주체. 서명이 없는 자기 보고다(`builder.id`가 `local:`, `invocationId`가 `LOCAL_UNSIGNED`). `predicateType`이 SLSA provenance v1이어도 SLSA 수준을 뜻하지 않는다 |
| 외부 provenance 서명 | 지정 키 보유자가 이 run, source revision, 후보 digest를 보고 서명함 | 빌드 job 자체의 격리, provider가 성실히 검사했음 |
| 외부 vulnerability 서명 | provider가 이 lockfile·dist에 대해 결과를 주장함 | 오프라인 DB의 최신성, 누락 없음 |
번들 패키지 목록은 SBOM의 production 항목에 모두 들어 있어야 한다. 2026-09-25
기준으로 한 건이 어긋난다. `scheduler@0.27.0`은 `react-dom`의 의존성이라 번들에
들어가지만, SBOM과 `config/security/dependency-baseline.json`은 이것을
`development`로 분류한다. `pnpm list` JSON이 production 트리 아래에서 이 패키지를
다시 보여 주지 않고, 그래서 `scripts/lib/supply-chain.ts`의 순회가 development
경로에서만 이것을 만난다. 분류를 고치면 dependency baseline을 다시 승인해야 하므로
(`update:dependency-baseline`) 이 문서에 알려진 차이로 남긴다.
## 최소 구성과 전체 구성
리뷰 13-13. 승격 단계까지 쓰려면 이 문서 아래의 runner 조건(bwrap, prlimit,
systemd-run, systemd user manager 254 이상, cgroup v2 위임)과 오프라인 데이터로
Ed25519 서명 보고서를 내는 provider 두 개가 필요하다. 이 repo는 그 환경에서
workflow 전체를 한 번도 돌리지 않았다. 그래서 두 구성을 나눠 적는다.
| 구성 | 켜는 것 | 보장하는 것 | 보장하지 않는 것 |
|---|---|---|---|
| 최소 구성(provider 없음) | merge·release stage 게이트, `immutable_build`(FE-GATE-015·027). provider 변수는 비워 둔다 | lockfile 무결성과 설치 스크립트 차단, SBOM과 local provenance의 digest 정합, secret scan, 재현 빌드, 후보 archive의 exact member와 digest, release 대상 환경 승인(FE-GATE-027) | 외부 취약점 검사, 서명된 provenance. provider job은 명령과 키가 없어 실패하고, `promotion` job은 두 provider job의 성공을 요구하므로 돌지 않는다. 승격은 사람이 결정한다 |
| 전체 구성 | 위 전부와 `vulnerability_provider`·`provenance_provider`·`promotion` job, 아래 runner 조건과 provider 키 | 위 전부와, 지정 키 보유자가 이 후보 digest·run·source에 서명했다는 것, 승격된 exact-five bundle(`verify:promotion`) | provider가 성실히 검사했는지, 빌드 job 격리(위 "무엇을 증명하고" 표 참고) |
최소 구성으로 운영할 때 승격은 수동 승인이다. 승인자는 `immutable_build`가
올린 후보 archive의 SHA-256(job output `archive_sha256`)과 local evidence를
기록하고, 그 archive를 그대로 배포한다. 다시 빌드하지 않는다. `production_gate`는
`promotion` 뒤에만 돌므로 이 구성의 workflow에서는 실행되지 않는다. 운영
게이트(FE-GATE-019, 021~025)는 배포한 release를 대상으로
`corepack pnpm ci:gate -- FE-GATE-0xx`로 따로 돌려 기록한다.
### provider 신뢰 키 교체와 폐기
신뢰 키는 repo 변수 `VULNERABILITY_PUBLIC_KEY_PATH`·`VULNERABILITY_KEY_ID`,
`PROVENANCE_PUBLIC_KEY_PATH`·`PROVENANCE_KEY_ID`가 가리키는 공개 키 파일이다
(`scripts/lib/provider-trust.ts`). 두 provider는 서로 다른 키를 써야 한다
(`assertDistinctProviderTrust`). 승격 기록은 키 ID·지문과 trust policy
SHA-256을 남긴다.
교체 순서:
1. provider가 새 키 쌍을 만들고 공개 키만 넘긴다.
2. 새 공개 키 파일을 runner가 읽을 수 있는 경로에 두고, 두 변수를 새 경로와 새
key ID로 한꺼번에 바꾼다. 키 ID는 새 값을 쓴다. 이전 ID를 재사용하면 기록만
보고 어느 키였는지 구분할 수 없다.
3. provider 쪽 서명 키를 새 키로 바꾼 뒤 release를 한 번 돌려 `promotion`이
통과하는지 확인한다.
4. 이전 공개 키 파일은 지우지 않고 보관한다. 이전 키로 승격된 release를 나중에
배포하거나 그 release로 롤백할 때 `verify:promotion -- --archived`가 그 키를
요구한다(`docs/operations/release-cache-rollback.md`).
폐기 순서(키 유출 등):
1. 해당 변수에서 그 키를 즉시 뺀다. 그 키로 서명된 새 승격은 이때부터 실패한다.
2. 보관 중인 이전 공개 키 파일도 지운다. 그 키로만 서명된 과거 release는
`verify:promotion -- --archived`를 통과하지 못한다.
3. 그런 release를 다시 써야 하면 새 키로 provider 검증을 다시 받는다. 같은 후보
archive를 대상으로 한 새 provider 실행이 필요하고, 다시 빌드하지 않는다. 이
repo에는 이 재검증 전용 job이 없다. 필요한 프로젝트가 만든다.
## External promotion controls
Promotion reads the provider files named by `VULNERABILITY_REPORT_PATH` and
+5 -3
View File
@@ -57,7 +57,9 @@ RP-07 구현 이후 이 기반은 저장소 내부 디자인 시스템 플랫폼
3. 앱 셸, 예제와 reference feature는 public design-system barrel을 소비한다.
4. 문자 glyph는 semantic Lucide facade로 교체됐다.
5. token은 세 CSS 파일로 분리됐고 `theme.css`는 layout/component styling만
소유한다.
소유한다. `theme.css`는 import 순서만 정하는 진입점이고, 실제 규칙은
`styles/theme/` 아래 파일(base, shell, primitives, templates, pages,
responsive)에 같은 순서로 있다.
6. runtime gallery는 있지만 격리된 story, interaction story, 시각 회귀 기준선이
없다.
7. 사용자 문구가 한국어 literal로 고정되어 locale과 RTL 계약이 없다.
@@ -304,8 +306,8 @@ Pattern은 여러 primitive를 조합해 반복되는 사용자 문제를 해결
| Pattern | 필수 내용 |
| --- | --- |
| `AsyncSurface` | loading, success, empty, terminal error, stale, refresh |
| `AccessSurface` | auth required, forbidden, not found |
| `AsyncSurface` | loading, success, empty, terminal error, stale, refresh. 조회 실패가 `AUTH_REQUIRED`·`FORBIDDEN`·`NOT_FOUND`이면 `AccessSurface`와 같은 화면(`state-surfaces.tsx`)을 그린다(`async-surface.tsx`의 `ACCESS_SURFACES`) |
| `AccessSurface` | auth required, forbidden, not found. 조회 실패와 갤러리가 이 한 벌을 쓴다 |
| `Form` | submit, error summary, first-invalid focus, pending |
| `ConfirmationDialog` | destructive action 설명과 명시적 확인 |
| `ToastRegion` | queue, announcement, dismiss, focus policy |
@@ -142,8 +142,12 @@ rasterization과 실제 device farm은 프로젝트가 요구할 때 연결한
operation별 success/empty/slow/network/timeout/content/envelope/schema/auth/
403/404/409/422/429/retry/terminal을 포함한 19개 scenario catalog와 strict
unhandled-request server를 공유한다. clock/random/scheduler/storage helper와
browser console/page/network failure 정책으로 비결정적 우회를 차단한다.
unhandled-request server(`tests/mocks/server.ts`의
`onUnhandledRequest: "error"`)를 공유한다. browser test는 공용 fixture
(`tests/support/browser/strict-browser-test.ts`)가 console error/warning,
page error, 실패한 request를 test 실패로 만든다. 시간은 각 test가
`vi.useFakeTimers()`로 통제하고, 전역 `afterEach`가 실제 timer로 되돌린다
(`tests/setup.ts`). 공용 clock/random/scheduler helper는 두지 않는다.
#### Built-dist와 compact E2E
@@ -153,11 +157,25 @@ Chromium, Firefox, WebKit과 compact project로 실행한다. 빠른 Vite 개발
#### 위험 기반 coverage
V8 text/JSON/LCOV를 생성하고 전체 기준과 retry/storage/telemetry/application
composition/compatibility/performance/promotion/chunk/diagnostics/reference HTTP
operation/query-mutation/registry compatibility 19개 high-risk module에 80개
scoped threshold를 적용한다. critical module 누락 또는 threshold 미달 fixture는
merge gate를 실패시킨다.
V8 text/JSON/LCOV를 생성하고 `config/testing/risk-coverage.json`의 하한을
적용한다. 하한은 전체 평균 4개(`summary`: lines 75, statements 73, functions 80,
branches 68)와 `criticalModules` 20개의 모듈별 하한 80개(모듈마다 4개)다.
`check-risk-coverage.ts`는 두 종류를 합쳐 "84 thresholds"로 보고한다. 모듈은
HTTP 실행(`http-execution-v3.ts`, live 재시도 규칙 `http-retry-lifecycle.ts`,
계약 경로 규칙 `http-contract-bridge.ts`, legacy V2 `retry-policy.ts`, 요청 조립,
bounded body/JSON), server-state scope, Service Worker lifecycle, 저장소
(`browser-storage-adapter.ts`, `indexeddb-runtime.ts`), telemetry, application
조립, compatibility, chunk recovery, release manifest, boot JSON, diagnostics,
reference HTTP gateway, application query다. 모듈별 하한은 목표치가 아니라
등록할 때 측정값 근처로 둔 ratchet이다(되돌아가지 못하게 막는 하한). 새로
넣은 세 모듈은 2026-09-26 측정값을 내림한 값이다.
critical module 누락 또는 threshold 미달 fixture는 merge gate를 실패시킨다.
realtime(`src/adapters/realtime/`)과 Web Push(`src/adapters/web-push/`)는
`test:realtime-removal`이 통째로 지우는 선택 runtime이라
(`scripts/test-realtime-runtime-removal.ts`의 `runtimePaths`) 모듈별 하한에 넣지
않는다. 넣으면 그 runtime을 지운 다운스트림의 coverage gate가 없는 파일 때문에
실패한다. 두 영역은 전체 평균 하한만 받는다.
Repository inventory의 정적 provenance는 runtime 실행 가능 여부가 아니라 현재
Vitest/V8 producer가 file counter를 생성하는 문장의 존재 여부를 나타낸다. 따라서
@@ -724,15 +742,19 @@ tests/factories/
| `malformed-json` | 파싱 불가능한 JSON |
| `envelope-mismatch` | top-level contract 위반 |
| `schema-mismatch` | data payload contract 위반 |
| `auth-recover-once` | 첫 401 후 복구 성공 |
| `auth-persistent-401` | 복구 뒤에도 401 |
| `response-too-large` | 응답 본문이 크기 상한을 넘어 읽기를 멈춤 |
| `unauthenticated-401` | 401. 명령은 적용되지 않음(`NOT_APPLIED`) |
| `forbidden-403` | 권한 없음 |
| `not-found-404` | 리소스 없음 |
| `conflict-409` | mutation conflict |
| `validation-422` | 승인된 field/global error |
| `rate-limited-429` | Retry-After 포함 |
| `server-retry-success` | bounded retry 뒤 성공 |
| `server-terminal-500` | retry 소진 |
| `server-terminal-503` | 503. 조회는 retry 2회 뒤 소진, 명령은 retry 없이 결과 불명(`MAYBE_APPLIED`) |
이 표는 `tests/mocks/scenarios/catalog.ts`의 `HTTP_SCENARIO_IDS`와 같은 순서다.
401 뒤 인증 복구 흐름은 catalog가 아니라 `tests/integration/auth-recovery.test.ts`가
다룬다.
### 11.3 Catalog 규칙
@@ -951,6 +973,13 @@ fixture로 확인한다.
### 14.2 위험별 목표
아래 표는 올려 갈 **목표**다. 지금 gate가 막는 값은 이 표가 아니라
`config/testing/risk-coverage.json`의 현재값 ratchet이다(2.3절 "위험 기반
coverage"). 예를 들어 `service-worker-lifecycle.ts`의 branch 하한은 43,
`http-execution-v3.ts`는 52로 표의 목표보다 낮다. 테스트를 보강해 측정값이
오르면 그 모듈의 하한을 새 측정값으로 올린다. 하한을 내리는 변경은 이유를
커밋 메시지에 적는다.
| 영역 | Line/statement 참고 | Branch 우선 목표 |
| --- | --- | --- |
| registry/codec/schema | 95~100% | 100%에 가깝게 |
@@ -1103,8 +1132,11 @@ validate한다.
외부 배포 주소나 28일 field evidence가 없는 skeleton 개발 단계에서는 해당 gate가
실제 프로젝트가 채울 계약으로 남는다. 이를 fake data로 통과시키지 않는다.
현재 `FE-GATE-009`의 signed manual accessibility review는 merge gate다. 이
문서는 이를 production/field gate로 이동시키지 않는다.
signed manual accessibility review는 release gate `FE-GATE-028`이다
(`config/ci/gates.json`, 리뷰 08-06). 사람의 서명은 릴리스 후보 하나에 대해
하므로 merge마다 요구할 수 없다. merge gate `FE-GATE-009`는 자동 axe 검사와
기록 형식 검사(`review:a11y-manual -- --format-only`,
`scripts/lib/manual-a11y-evidence.ts`의 `validateManualA11yRecordFormat`)만 한다.
### 16.4 병렬화와 shard
+36 -8
View File
@@ -16,9 +16,11 @@ Each gate is blocking in its declared scope. Failures are not downgraded with
| end-to-end | `pnpm test:e2e` | pinned browser engines | `artifacts/tests/e2e/` |
| accessibility | `pnpm test:a11y` | pinned browser engines | `artifacts/tests/a11y.json` |
`test:all` is the normal product-development loop. It intentionally includes
runtime-schema, unit, capability-contract, component, integration, reference
feature and recipe suites, but does not include `test:system`. CI-runner and
`test:all` is the normal product-development loop. It runs, in order,
`test:runtime-schema`, `test:unit`, `test:contract`, `test:component`,
`test:integration`, `test:reference-feature`, `test:platform` (`tests/platform`
and `tests/architecture`), `check:release-coherence` and `test:recipes`
(`package.json` `test:all`). It does not include `test:system`. CI-runner and
supply-chain assurance has different host prerequisites and is invoked
explicitly in the assurance path.
@@ -37,6 +39,24 @@ That runner:
`vitest.config.ts` also fixes `NODE_ENV=test` so a direct Vitest invocation
cannot accidentally select React's production behavior.
To run one test file, use the same runner:
```sh
node scripts/run-vitest.ts run tests/component/router.test.tsx
```
The runner renders the gitignored `src/.generated/` product index first
(`scripts/run-vitest.ts`), so this works in a fresh clone. A direct
`pnpm exec vitest run <file>` skips that step and fails there with
`Failed to resolve import "../.generated/product-feature-index.ts"`.
`pnpm test:unit -- <file>` does not narrow the run, because the script already
passes the whole `tests/unit` directory.
`vitest.config.ts` collects only `tests/**/*.test.{ts,tsx}`; Playwright
`*.spec.ts` files are not Vitest tests. `tests/system/` is collected only when
the command names it, as `test:system` does, so a bare `vitest` run does not
start the CI-runner suite.
The system suite additionally runs
`scripts/check-system-test-prerequisites.ts` and fails with one prerequisite
report when the CI-runner host does not provide its required Linux facilities.
@@ -64,11 +84,19 @@ CI / release assurance:
A host-level process/sandbox test must not be placed in `tests/unit` merely
because it uses Vitest. The classification follows the system boundary and
prerequisites, not the test framework. Process-heavy tests that spawn child
processes but do not require privileged host facilities belong in
`tests/integration`; for example the provider guardian transaction protocol
lives at `tests/integration/provider-guardian-transaction.test.ts`. Its
handshake timeout is a test watchdog, not a production protocol deadline.
prerequisites, not the test framework:
- Tests that need systemd, bubblewrap, cgroup v2 or CI-provider process
controls belong in `tests/system`.
- Tests of a long-lived child-process protocol belong in `tests/integration`;
for example the provider guardian transaction protocol lives at
`tests/integration/provider-guardian-transaction.test.ts`. Its handshake
timeout is a test watchdog, not a production protocol deadline.
- A script's own tests may start that script, Node or Vitest as a short-lived
child process to check its command-line contract, and stay in `tests/unit`
next to the script's other tests. Such a suite declares its own longer
timeout instead of raising the global one; for example
`tests/unit/risk-coverage.test.ts` uses `PROCESS_HEAVY_TIMEOUT_MS`.
End-to-end and automated accessibility scenarios run on the pinned Chromium,
Firefox, and WebKit engines. The responsive contract explicitly exercises
+121 -43
View File
@@ -6,6 +6,10 @@ import type { Rule } from "eslint";
const sourceExtensions = "{ts,tsx,mts,cts}";
// 12-09. Editor-time aid only: these patterns show a layer violation while
// typing. The layer rules themselves live in .dependency-cruiser.json and are
// enforced by check:architecture, which resolves every import. Change a rule
// there first; these lists cover a subset and may lag behind it.
const layerPatterns = {
domain: [
"**/application/**",
@@ -33,8 +37,21 @@ const layerPatterns = {
adapters: ["**/presentation/**", "**/bootstrap/**"],
};
function restrictedImports(patterns: readonly string[]) {
return ["error", { patterns }];
// 12-11. Each pattern group carries the reason and the way out; the default
// message only named the pattern.
const layerMessages = {
domain:
"domain stays framework-neutral (.dependency-cruiser.json domain-is-framework-neutral). Move the code to application or pass the value in.",
application:
"application declares ports and never imports UI, adapters or bootstrap (application-does-not-know-concrete-runtime). Add a port under application/ports; bootstrap passes the adapter.",
presentation:
"presentation reaches the runtime through the application API (presentation-does-not-know-adapters). Use the application facade; bootstrap composes adapters.",
adapters:
"an adapter implements an application port and never imports UI or bootstrap (adapters-do-not-know-presentation). Pass what it needs through the port.",
} as const;
function restrictedImports(patterns: readonly string[], message: string) {
return ["error", { patterns: [{ group: [...patterns], message }] }];
}
const restrictedBrowserDataProperties = [
@@ -741,7 +758,7 @@ export default [
{
files: [`src/domain/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports(layerPatterns.domain),
"no-restricted-imports": restrictedImports(layerPatterns.domain, layerMessages.domain),
"no-restricted-properties": restrictedBrowserDataProperties,
"no-restricted-globals": [
"error",
@@ -766,7 +783,7 @@ export default [
{
files: [`src/application/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports(layerPatterns.application),
"no-restricted-imports": restrictedImports(layerPatterns.application, layerMessages.application),
"no-restricted-properties": restrictedBrowserDataProperties,
"no-restricted-globals": [
"error",
@@ -791,7 +808,7 @@ export default [
{
files: [`src/presentation/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports(layerPatterns.presentation),
"no-restricted-imports": restrictedImports(layerPatterns.presentation, layerMessages.presentation),
"no-restricted-properties": restrictedBrowserDataProperties,
"no-restricted-globals": [
"error",
@@ -815,24 +832,30 @@ export default [
`src/presentation/adapters/query/**/*.${sourceExtensions}`,
],
rules: {
"no-restricted-imports": restrictedImports([
"**/adapters/http/**",
"**/adapters/storage/**",
"**/adapters/auth/**",
"**/bootstrap/**",
"**/application/ports/out/**",
]),
"no-restricted-imports": restrictedImports(
[
"**/adapters/http/**",
"**/adapters/storage/**",
"**/adapters/auth/**",
"**/bootstrap/**",
"**/application/ports/out/**",
],
"the TanStack Query binding may import @tanstack only; reach adapters through application ports (presentation-does-not-know-adapters).",
),
},
},
{
files: [`src/presentation/templates/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports([
"**/application/**",
"**/adapters/**",
"**/bootstrap/**",
"@tanstack/**",
]),
"no-restricted-imports": restrictedImports(
[
"**/application/**",
"**/adapters/**",
"**/bootstrap/**",
"@tanstack/**",
],
"page templates own layout only (page-templates-own-layout-only). Take data and actions as props from the page.",
),
},
},
{
@@ -861,7 +884,7 @@ export default [
{
files: [`src/adapters/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports(layerPatterns.adapters),
"no-restricted-imports": restrictedImports(layerPatterns.adapters, layerMessages.adapters),
"no-restricted-properties": restrictedBrowserDataProperties,
"no-restricted-globals": [
"error",
@@ -902,7 +925,7 @@ export default [
{
files: [`src/features/*/domain/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports(layerPatterns.domain),
"no-restricted-imports": restrictedImports(layerPatterns.domain, layerMessages.domain),
"no-restricted-properties": restrictedBrowserDataProperties,
"no-restricted-globals": [
"error",
@@ -927,7 +950,7 @@ export default [
{
files: [`src/features/*/application/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports(layerPatterns.application),
"no-restricted-imports": restrictedImports(layerPatterns.application, layerMessages.application),
"no-restricted-properties": restrictedBrowserDataProperties,
"no-restricted-globals": [
"error",
@@ -952,15 +975,18 @@ export default [
{
files: [`src/features/*/presentation/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports([
"**/features/*/adapters/**",
"**/adapters/http/**",
"**/adapters/storage/**",
"**/adapters/auth/**",
"**/bootstrap/**",
"**/application/ports/out/**",
"@tanstack/**",
]),
"no-restricted-imports": restrictedImports(
[
"**/features/*/adapters/**",
"**/adapters/http/**",
"**/adapters/storage/**",
"**/adapters/auth/**",
"**/bootstrap/**",
"**/application/ports/out/**",
"@tanstack/**",
],
"feature presentation calls its application API (feature-presentation-does-not-know-outbound-adapters). Bootstrap wires the adapters.",
),
"no-restricted-properties": restrictedBrowserDataProperties,
"no-restricted-globals": [
"error",
@@ -982,11 +1008,14 @@ export default [
{
files: [`src/features/*/adapters/**/*.${sourceExtensions}`],
rules: {
"no-restricted-imports": restrictedImports([
"**/presentation/**",
"**/bootstrap/**",
"@tanstack/**",
]),
"no-restricted-imports": restrictedImports(
[
"**/presentation/**",
"**/bootstrap/**",
"@tanstack/**",
],
"a feature adapter implements the feature's ports and never imports UI or bootstrap (feature-adapters-do-not-know-presentation).",
),
"no-restricted-properties": restrictedBrowserDataProperties,
"no-restricted-globals": [
"error",
@@ -1031,14 +1060,17 @@ export default [
`tests/fixtures/architecture/forbidden/**/*.${sourceExtensions}`,
],
rules: {
"no-restricted-imports": restrictedImports([
"**/adapters/**",
"**/application/ports/out/**",
"@tanstack/**",
"react",
"react-dom",
"**/application/**",
]),
"no-restricted-imports": restrictedImports(
[
"**/adapters/**",
"**/application/ports/out/**",
"@tanstack/**",
"react",
"react-dom",
"**/application/**",
],
"forbidden architecture fixture: this import must be rejected.",
),
"no-restricted-globals": [
"error",
"fetch",
@@ -1073,4 +1105,50 @@ export default [
],
},
},
{
// 13-06. Vite inlines every loaded VITE_* value into the bundle wherever
// code references the whole `import.meta.env` object, including values no
// code reads. Keyed reads are replaced one by one.
files: [`src/**/*.${sourceExtensions}`],
plugins: {
"build-env": {
rules: {
"no-whole-import-meta-env": {
meta: {
type: "problem",
schema: [],
messages: {
whole:
"Read build variables by key (import.meta.env.VITE_NAME). Referencing import.meta or import.meta.env as a whole bundles every VITE_* value (13-06).",
},
},
create(context: any) {
const isMember = (node: any) =>
node?.type === "MemberExpression" ||
node?.type === "OptionalMemberExpression";
return {
MetaProperty(node: any) {
if (node.meta?.name !== "import") return;
const member = node.parent;
if (!isMember(member) || member.object !== node || member.computed) {
context.report({ node, messageId: "whole" });
return;
}
if (member.property?.name !== "env") return;
const read = member.parent;
if (isMember(read) && read.object === member && !read.computed) {
return;
}
context.report({ node: member, messageId: "whole" });
},
};
},
},
},
},
},
rules: {
"build-env/no-whole-import-meta-env": "error",
},
},
];
+12 -1
View File
@@ -12,7 +12,18 @@
<link rel="icon" type="image/svg+xml" href="%BASE_URL%favicon.svg" />
</head>
<body>
<div id="root"></div>
<div id="root">
<!-- Q-6.9-8. Static boot shell: visible while config, manifest and
contract checks run; the first React render replaces it. -->
<div
class="state-surface state-surface--loading"
role="status"
aria-busy="true"
data-boot-shell=""
>
불러오는 중
</div>
</div>
<script type="module" src="/src/bootstrap/main.tsx"></script>
</body>
</html>
+79 -60
View File
@@ -9,27 +9,27 @@
"pnpm": ">=11.0.0 <12.0.0"
},
"scripts": {
"dev": "vite",
"build": "node scripts/build-frontend.ts",
"dev": "node scripts/generate-product-feature-index.ts && vite",
"build": "node scripts/generate-product-feature-index.ts && node scripts/build-frontend.ts",
"build:profile": "node scripts/generate-runtime-config.ts",
"build:release-candidate": "corepack pnpm build && corepack pnpm generate:supply-chain && corepack pnpm scan:security && corepack pnpm verify:release && node scripts/verify-supply-chain-artifacts.ts && node scripts/create-release-candidate.ts",
"build:release-candidate": "node scripts/generate-product-feature-index.ts && corepack pnpm build && corepack pnpm generate:supply-chain && corepack pnpm scan:security && corepack pnpm verify:release && node scripts/verify-supply-chain-artifacts.ts && node scripts/create-release-candidate.ts",
"preview": "node dist/server.mjs",
"verify:tech-log-source-parity": "node tests/support/browser/verify-tech-log-source-parity.ts",
"lint": "eslint src scripts tests recipes .storybook vite.config.ts vitest.config.ts playwright*.config.ts --max-warnings=0",
"check:architecture": "node scripts/check-architecture.ts && node scripts/check-tech-log-route-literals.ts",
"check:design-system": "node scripts/check-design-system.ts",
"check:design-system:fixture": "node scripts/check-design-system.ts --fixture",
"check:i18n": "node scripts/check-i18n.ts",
"check:i18n:fixture": "node scripts/check-i18n.ts --fixture",
"check:architecture": "node scripts/generate-product-feature-index.ts && node scripts/check-architecture.ts && node scripts/check-tech-log-route-literals.ts",
"check:design-system": "node scripts/generate-product-feature-index.ts && node scripts/check-design-system.ts",
"check:design-system:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-design-system.ts --fixture",
"check:i18n": "node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts",
"check:i18n:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts --fixture",
"check:adapter-inventory": "node scripts/check-adapter-inventory.ts",
"check:remediation-ledger": "node scripts/check-remediation-ledger.ts",
"check:release-admission": "node scripts/check-release-admission.ts",
"check:diagnostics": "node scripts/check-diagnostics.ts",
"check:diagnostics:fixture": "node scripts/check-diagnostics.ts --fixture",
"check:release-admission": "node scripts/generate-product-feature-index.ts && node scripts/check-release-admission.ts",
"check:diagnostics": "node scripts/generate-product-feature-index.ts && node scripts/check-diagnostics.ts",
"check:diagnostics:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-diagnostics.ts --fixture",
"check:types": "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",
"check:types:app": "tsc --project tsconfig.app.json",
"check:types:node": "tsc --project tsconfig.node.json",
"check:types:test": "tsc --project tsconfig.test.json",
"check:types:app": "node scripts/generate-product-feature-index.ts && tsc --project tsconfig.app.json",
"check:types:node": "node scripts/generate-product-feature-index.ts && tsc --project tsconfig.node.json",
"check:types:test": "node scripts/generate-product-feature-index.ts && tsc --project tsconfig.test.json",
"check:types:recipes": "node scripts/check-optional-recipe-types.ts",
"check:types:fixture": "tsc -p tests/fixtures/typecheck/tsconfig.port-call.json",
"check:types:fixture:ts-port": "tsc -p tests/fixtures/typecheck/tsconfig.port-implementation.json",
@@ -40,11 +40,11 @@
"check:types:fixture:failure-kind": "tsc -p tests/fixtures/typecheck/tsconfig.failure-kind.json",
"check:types:fixture:reference-operation": "tsc -p tests/fixtures/typecheck/tsconfig.reference-operation.json",
"check:types:fixture:async-overlay": "tsc -p tests/fixtures/typecheck/tsconfig.async-overlay.json",
"check:types:fixture:route-runtime": "tsc -p tests/fixtures/typecheck/tsconfig.route-runtime.json",
"check:types:fixture:page-action": "tsc -p tests/fixtures/typecheck/tsconfig.page-action.json",
"check:types:fixture:icon-button": "tsc -p tests/fixtures/typecheck/tsconfig.icon-button.json",
"check:types:fixture:i18n-key": "tsc -p tests/fixtures/typecheck/tsconfig.message-key.json",
"check:types:fixture:i18n-params": "tsc -p tests/fixtures/typecheck/tsconfig.message-params.json",
"check:types:fixture:route-runtime": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.route-runtime.json",
"check:types:fixture:page-action": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.page-action.json",
"check:types:fixture:icon-button": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.icon-button.json",
"check:types:fixture:i18n-key": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.message-key.json",
"check:types:fixture:i18n-params": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.message-params.json",
"check:types:fixture:diagnostics": "tsc -p tests/fixtures/typecheck/tsconfig.diagnostics-port.json",
"check:types:fixture:image-resolve-signal": "tsc -p tests/fixtures/typecheck/tsconfig.image-cdn-resolve-signal.json",
"test:runtime-schema": "node scripts/run-vitest.ts run tests/runtime-schema --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/runtime-schema.xml --passWithNoTests",
@@ -60,8 +60,8 @@
"test:e2e:dev": "playwright test --config playwright.dev.config.ts",
"test:browser-capabilities": "playwright test --config playwright.capabilities.config.ts",
"verify:browser-capability-evidence": "node scripts/verify-browser-capability-evidence.ts",
"storybook": "storybook dev -p 6006",
"build:storybook": "storybook build -o artifacts/storybook/static",
"storybook": "node scripts/generate-product-feature-index.ts && storybook dev -p 6006",
"build:storybook": "node scripts/generate-product-feature-index.ts && storybook build -o artifacts/storybook/static",
"test:storybook": "playwright test --config playwright.storybook.config.ts",
"test:visual": "playwright test --config playwright.visual.config.ts",
"test:visual:update": "playwright test --config playwright.visual.config.ts --update-snapshots",
@@ -71,66 +71,67 @@
"check:http-scenario-evidence:fixture": "node scripts/check-test-evidence.ts --scenario-only --source-root tests/fixtures/test-evidence/scenarios/source --policy tests/fixtures/test-evidence/scenarios/policy.json --catalog tests/fixtures/test-evidence/scenarios/catalog.json --receipt tests/fixtures/test-evidence/scenarios/receipt.json --artifact artifacts/quality/http-scenario-evidence-fixture.json",
"check:test-evidence:source": "node scripts/check-test-evidence.ts --source-only --artifact artifacts/quality/test-evidence-source.json",
"check:test-evidence:fixture": "node scripts/check-test-evidence.ts --source-root tests/fixtures/test-evidence/forbidden --artifact artifacts/quality/test-evidence-fixture.json",
"test:a11y": "playwright test --grep @a11y && node scripts/write-a11y-report.ts",
"review:a11y-manual": "node scripts/verify-a11y-manual.ts",
"test:sample-removal": "node scripts/test-sample-removal.ts",
"test:a11y": "node scripts/generate-product-feature-index.ts && playwright test --grep @a11y && node scripts/write-a11y-report.ts",
"review:a11y-manual": "node scripts/generate-product-feature-index.ts && node scripts/verify-a11y-manual.ts",
"test:sample-removal": "node scripts/generate-product-feature-index.ts && node scripts/test-sample-removal.ts",
"test:optional-recipe-removal": "node scripts/test-optional-recipe-removal.ts",
"test:browser-file-storage-removal": "node scripts/test-browser-file-storage-runtime-removal.ts",
"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",
"test:tech-log": "node scripts/run-vitest.ts run tests/features/tech-log --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/tech-log.xml",
"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 tests/features/tech-log --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 tests/platform tests/architecture tests/release tests/scripts tests/scale/browser-soak.contract.test.ts --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 check:tech-log-contract && corepack pnpm test:tech-log && 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 check:tech-log-contract && corepack pnpm test:tech-log && 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",
"check:artifact-schemas": "node scripts/generate-artifact-schemas.ts --check",
"generate:tech-log-contract": "node scripts/generate-tech-log-contract.ts",
"generate:artifact-schemas": "node scripts/generate-product-feature-index.ts && node scripts/generate-artifact-schemas.ts",
"check:artifact-schemas": "node scripts/generate-product-feature-index.ts && node scripts/generate-artifact-schemas.ts --check",
"generate:tech-log-contract": "node scripts/generate-product-feature-index.ts && node scripts/generate-tech-log-contract.ts",
"capture:screens": "node scripts/capture-screens.ts",
"measure:screens": "node scripts/capture-public-screens.ts",
"check:tech-log-contract": "node scripts/generate-tech-log-contract.ts --check",
"generate:dev-release-manifest": "node scripts/check-dev-release-manifest.ts --write",
"check:dev-release-manifest": "node scripts/check-dev-release-manifest.ts",
"generate:supply-chain": "node scripts/generate-supply-chain.ts",
"verify:local-evidence": "node scripts/verify-release-candidate.ts && node scripts/verify-release.ts && node scripts/verify-supply-chain-artifacts.ts && node scripts/verify-archived-local-evidence.ts && node scripts/verify-release-candidate.ts",
"verify:promotion": "node scripts/verify-exact-promotion-bundle.ts",
"check:tech-log-contract": "node scripts/generate-product-feature-index.ts && node scripts/generate-tech-log-contract.ts --check",
"generate:dev-release-manifest": "node scripts/generate-product-feature-index.ts && node scripts/check-dev-release-manifest.ts --write",
"check:dev-release-manifest": "node scripts/generate-product-feature-index.ts && node scripts/check-dev-release-manifest.ts",
"generate:supply-chain": "node scripts/generate-product-feature-index.ts && node scripts/generate-supply-chain.ts",
"verify:local-evidence": "node scripts/generate-product-feature-index.ts && node scripts/verify-release-candidate.ts && node scripts/verify-release.ts && node scripts/verify-supply-chain-artifacts.ts && node scripts/verify-archived-local-evidence.ts && node scripts/verify-release-candidate.ts",
"verify:promotion": "node scripts/generate-product-feature-index.ts && node scripts/verify-exact-promotion-bundle.ts",
"update:dependency-baseline": "node scripts/update-dependency-baseline.ts",
"check:supply-chain:fixtures": "node scripts/check-supply-chain-fixtures.ts",
"check:supply-chain:provider-fixtures": "node scripts/check-supply-chain-provider-fixtures.ts",
"verify:reproducible-build": "node scripts/verify-reproducible-build.ts",
"check:supply-chain:fixtures": "node scripts/generate-product-feature-index.ts && node scripts/check-supply-chain-fixtures.ts",
"check:supply-chain:provider-fixtures": "node scripts/generate-product-feature-index.ts && node scripts/check-supply-chain-provider-fixtures.ts",
"verify:reproducible-build": "node scripts/generate-product-feature-index.ts && node scripts/verify-reproducible-build.ts",
"scan:security": "node scripts/security-scan.ts",
"scan:security:fixture": "node scripts/security-scan.ts --policy tests/fixtures/security/secret-detection/forbidden-policy.json --artifact artifacts/security/scan-fixture.sarif",
"check:security:fixtures": "node scripts/check-security-fixtures.ts",
"check:browser-security": "node scripts/check-browser-security.ts",
"check:browser-file-storage-boundaries": "node scripts/check-browser-file-storage-boundaries.ts",
"check:realtime-boundaries": "node scripts/check-realtime-boundaries.ts",
"check:realtime-boundaries": "node scripts/generate-product-feature-index.ts && node scripts/check-realtime-boundaries.ts",
"check:realtime-boundaries:fixture": "node scripts/check-realtime-boundary-fixtures.ts",
"check:optional-recipes": "node scripts/check-optional-recipes.ts --require-dist",
"check:optional-recipes:source": "node scripts/check-optional-recipes.ts",
"check:optional-recipe-fixtures": "node scripts/check-optional-recipe-fixtures.ts",
"check:registries": "node scripts/check-registries.ts",
"check:registries:structure": "node scripts/check-registries.ts --no-baseline",
"check:registries:compatibility-fixtures": "node scripts/check-registry-compatibility-fixtures.ts",
"check:registries:baseline-fixture": "node scripts/check-registries.ts --approval tests/fixtures/registry/compatibility/tampered-approval.json --artifact artifacts/quality/registry-baseline-fixture.json",
"check:registries:fixture": "node scripts/check-registries.ts --governance tests/fixtures/registry/forbidden/governance.json --artifact artifacts/quality/registry-fixture.json",
"check:routes:fixture": "node scripts/check-registries.ts --governance tests/fixtures/registry/routes/governance.json --artifact artifacts/quality/route-registry-fixture.json",
"verify:compatibility": "node scripts/check-compatibility.ts",
"verify:release": "node scripts/verify-release.ts",
"verify:hosting-headers": "node scripts/verify-hosting-headers.ts",
"check:bundle": "node scripts/generate-supply-chain.ts && node scripts/check-bundle.ts",
"test:performance": "node scripts/test-performance.ts",
"collect:web-vitals-evidence": "node scripts/collect-web-vitals-evidence.ts",
"drill:runbook": "node scripts/drill-runbook.ts",
"check:optional-recipes": "node scripts/generate-product-feature-index.ts && node scripts/check-optional-recipes.ts --require-dist",
"check:optional-recipes:source": "node scripts/generate-product-feature-index.ts && node scripts/check-optional-recipes.ts",
"check:optional-recipe-fixtures": "node scripts/generate-product-feature-index.ts && node scripts/check-optional-recipe-fixtures.ts",
"check:registries": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts",
"update:registry-baseline": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts --no-baseline --artifact artifacts/quality/registry-current-snapshot.json && node scripts/update-registry-baseline.ts",
"check:registries:compatibility-fixtures": "node scripts/generate-product-feature-index.ts && node scripts/check-registry-compatibility-fixtures.ts",
"check:registries:baseline-fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts --approval tests/fixtures/registry/compatibility/tampered-approval.json --artifact artifacts/quality/registry-baseline-fixture.json",
"check:registries:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts --governance tests/fixtures/registry/forbidden/governance.json --artifact artifacts/quality/registry-fixture.json",
"check:routes:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts --governance tests/fixtures/registry/routes/governance.json --artifact artifacts/quality/route-registry-fixture.json",
"verify:compatibility": "node scripts/generate-product-feature-index.ts && node scripts/check-compatibility.ts",
"verify:release": "node scripts/generate-product-feature-index.ts && node scripts/verify-release.ts",
"verify:hosting-headers": "node scripts/generate-product-feature-index.ts && node scripts/verify-hosting-headers.ts",
"check:bundle": "node scripts/generate-product-feature-index.ts && node scripts/generate-supply-chain.ts && node scripts/check-bundle.ts",
"test:performance": "node scripts/generate-product-feature-index.ts && node scripts/test-performance.ts",
"collect:web-vitals-evidence": "node scripts/generate-product-feature-index.ts && node scripts/collect-web-vitals-evidence.ts",
"drill:runbook": "node scripts/generate-product-feature-index.ts && node scripts/drill-runbook.ts",
"drill:runbooks": "corepack pnpm drill:runbook -- FE-RB-001 && corepack pnpm drill:runbook -- FE-RB-002 && corepack pnpm drill:runbook -- FE-RB-003 && corepack pnpm drill:runbook -- FE-RB-004 && corepack pnpm drill:runbook -- FE-RB-005",
"ci:gate": "node scripts/run-ci-gate.ts",
"ci:gate": "node scripts/generate-product-feature-index.ts && node scripts/run-ci-gate.ts",
"generate:ci-workflow": "node scripts/generate-ci-workflow.ts",
"check:ci-workflow": "node scripts/generate-ci-workflow.ts --check",
"check:ci": "corepack pnpm check:artifact-schemas && node scripts/check-ci-contract.ts && corepack pnpm check:ci-workflow",
"verify:documentation": "node scripts/verify-documentation-readiness.ts",
"build:app-only": "vite build && node scripts/generate-build-manifest.ts",
"generate:contract-set": "node scripts/generate-contract-set.ts",
"update:ci-contract-baseline": "node scripts/update-ci-contract-baseline.ts",
"verify:documentation": "node scripts/generate-product-feature-index.ts && node scripts/verify-documentation-readiness.ts",
"build:app-only": "node scripts/generate-product-feature-index.ts && vite build && node scripts/generate-build-manifest.ts",
"generate:contract-set": "node scripts/generate-product-feature-index.ts && node scripts/generate-contract-set.ts",
"check:types:web-worker": "tsc --project tsconfig.web-worker.json",
"check:types:service-worker": "tsc --project tsconfig.service-worker.json",
"check:types:fixture:http-operation-input": "tsc -p tests/fixtures/typecheck/tsconfig.http-operation-input.json",
@@ -139,7 +140,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": {
"@fontsource/ibm-plex-mono": "5.3.0",
+1
View File
@@ -2,6 +2,7 @@ import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
testDir: "./tests/e2e",
forbidOnly: true,
outputDir: "./artifacts/tests/e2e/results",
reporter: [
["list"],
+1
View File
@@ -2,6 +2,7 @@ import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
testDir: "./tests/storybook",
forbidOnly: true,
outputDir: "./artifacts/tests/storybook/results",
reporter: [
["list"],
+1
View File
@@ -2,6 +2,7 @@ import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
testDir: "./tests/visual",
forbidOnly: true,
snapshotDir: "./tests/visual/__snapshots__",
outputDir: "./artifacts/tests/visual/results",
reporter: [
+10
View File
@@ -1,6 +1,16 @@
# 13-09. pnpm 11 ignores these keys in .npmrc (`pnpm config list` did not show
# them), so an unsupported Node version installed and new dependencies were
# saved with a ^ range. pnpm 11 reads its settings from this file.
engineStrict: true
saveExact: true
allowBuilds:
esbuild: true
msw: true
# 12-07. These exact pins were added on 2026-07-25 (946cf40, f3e105f) while
# they were younger than pnpm's minimum release age. An exclusion covers that
# exact version only, so a later version is checked again. Owner:
# frontend-platform. Revisit: remove an entry when its version is bumped or is
# older than the configured minimum release age.
minimumReleaseAgeExclude:
- '@playwright/test@1.62.0'
- playwright-core@1.62.0
+3 -3
View File
@@ -15,7 +15,7 @@
"SERVICE_WORKER": "DEFAULT",
"OFFLINE_COMMANDS": "DEFAULT"
},
"FEATURE_OVERRIDES": {
"reference-feature": "DEFAULT"
}
"TECH_LOG_STUDIO_SOURCE": "MOCK",
"TECH_LOG_PUBLIC_SOURCE": "MOCK",
"FEATURE_OVERRIDES": {}
}
@@ -0,0 +1,137 @@
import {
createIndexedDbRuntime,
type IndexedDbRuntimeDependencies,
} from "../../src/adapters/storage/indexeddb/index.ts";
import type { IndexedDbDatasetScope } from "../../src/application/ports/browser-file-storage/index.ts";
import {
createIndexedDbRepositoryProvider,
type IndexedDbRepositoryProvider,
} from "../../src/features/feature-adapter-contribution.ts";
import type {} from "../../src/features/local-draft-feature/adapters/create-local-draft-feature-input.ts";
import type { LocalDraft } from "../../src/features/local-draft-feature/domain/local-draft.ts";
type LocalDraftRuntimeDependencies = IndexedDbRuntimeDependencies<
LocalDraft,
LocalDraft,
never
>;
type LocalDraftRuntime = ReturnType<
typeof createIndexedDbRuntime<LocalDraft, LocalDraft, never>
>;
/**
* 09-05. How a host builds the `indexedDb` feature capability, shown for the
* local-draft sample. IndexedDB is an opt-in reference runtime
* (`offline-indexeddb` in config/recipes/frontend-capability-recipes.json,
* `productionComposition: false`), so `src/bootstrap/runtime-adapters.ts` does
* not build it. A product that installs a feature with `needs: ["indexedDb"]`
* copies this into its composition, replaces the codec, migrations and storage
* policy with its own decisions, and adds `indexedDb` to the feature
* capabilities there; until it does, that object fails the app typecheck and
* `composeFeatureAdapterInputs` names the missing capability.
*
* The scope tokens come from the product's storage registry and the lifecycle
* authority from its composition root; neither is invented here.
*/
export function createLocalDraftIndexedDbCapability(
options: Readonly<{
// The sample keeps drafts across sign-out, so its dataset is origin-shared.
scope: IndexedDbDatasetScope & Readonly<{ accountScope: "ORIGIN_SHARED" }>;
authorizeLifecycle: LocalDraftRuntimeDependencies["authorizeLifecycle"];
/** Defaults to the browser's `indexedDB`; tests pass an in-memory one. */
factory?: IDBFactory;
}>,
): Readonly<{
indexedDb: IndexedDbRepositoryProvider;
/** Opens (and migrates) the database; repository calls fail until it has. */
open(signal?: AbortSignal): ReturnType<LocalDraftRuntime["open"]>;
close(): void;
}> {
const runtime = createIndexedDbRuntime<LocalDraft, LocalDraft, never>({
...(options.factory === undefined ? {} : { factory: options.factory }),
scope: options.scope,
storagePolicy: Object.freeze({
owner: "local-draft-feature",
namespace: "local-draft",
classification: "INTERNAL",
authority: "LOCAL_FIRST",
accountScope: "ORIGIN_SHARED",
retention: Object.freeze({ kind: "EXPLICIT_DELETE" }),
softBudgetBytes: 1_000_000,
hardBudgetBytes: 2_000_000,
evictionPriority: "USER_AUTHORED",
logoutAction: "KEEP_ORIGIN_SHARED",
accountDeletionAction: "KEEP_ORIGIN_SHARED",
pressureAction: "RETAIN",
unavailableFallback: "READ_ONLY",
}),
schemaVersion: 1,
recordStore: "records",
governanceStore: "governance",
retentionStore: "retention",
retentionEligibilityIndex: "by-eligibility",
lifecycleMetadataStores: [],
idempotencyStore: "receipts",
idempotencyExpiryIndex: "by-expiry",
receiptRetentionMs: 60_000,
maxIdempotencyReceipts: 100,
migrations: [
{
id: "local-draft-schema-v1",
fromVersion: 0,
toVersion: 1,
operations: [
{ kind: "CREATE_STORE", name: "governance", keyPath: "bindingKey" },
{
kind: "CREATE_STORE",
name: "retention",
keyPath: "recordKey",
indexes: [{ name: "by-eligibility", keyPath: "eligibleAtEpochMs" }],
},
{ kind: "CREATE_STORE", name: "records", keyPath: "key" },
{
kind: "CREATE_STORE",
name: "receipts",
keyPath: "idempotencyKey",
indexes: [{ name: "by-expiry", keyPath: "expiresAtEpochMs" }],
},
],
},
],
codec: {
currentVersion: 1,
encode: (value) => ({ ok: true, value }),
measureStoredBytes: (value) =>
new TextEncoder().encode(JSON.stringify(value)).byteLength,
decode: (version, value) => {
if (version !== 1 || value === null || typeof value !== "object") {
return { ok: false };
}
const candidate = value as Partial<LocalDraft>;
return typeof candidate.draftId === "string" &&
typeof candidate.title === "string" &&
typeof candidate.body === "string"
? { ok: true, value: candidate as LocalDraft }
: { ok: false };
},
fingerprint: async (value) => {
const bytes = new TextEncoder().encode(
JSON.stringify([value.draftId, value.title, value.body]),
);
const digest = await crypto.subtle.digest("SHA-256", bytes);
return Array.from(new Uint8Array(digest), (byte) =>
byte.toString(16).padStart(2, "0"),
).join("");
},
},
queryPolicy: { plan: () => ({ limit: 1 }) },
authorizeLifecycle: options.authorizeLifecycle,
});
return Object.freeze({
indexedDb: createIndexedDbRepositoryProvider(
Object.freeze({ "local-draft": runtime }),
),
open: (signal?: AbortSignal) => runtime.open(signal),
close: () => runtime.close(),
});
}
+24 -6
View File
@@ -1,8 +1,11 @@
import { spawnSync } from "node:child_process";
import { rm } from "node:fs/promises";
import { rm, writeFile } from "node:fs/promises";
import process from "node:process";
import { SERVICE_WORKER_SCRIPT_PATH } from "../src/contracts/service-worker.ts";
import { INSTALLED_RUNTIME_CAPABILITIES } from "../src/features/installed-runtime-capabilities.ts";
import { makeDistFilesPublic } from "./lib/dist-permissions.ts";
import { SELF_UNREGISTERING_SERVICE_WORKER } from "./lib/self-unregistering-service-worker.ts";
/**
* §17.2.2. Deterministic two-pass build.
@@ -16,17 +19,23 @@ import { INSTALLED_RUNTIME_CAPABILITIES } from "../src/features/installed-runtim
* 4. materialize dist/config.json from the declared APP_PROFILE
* 5. scan app dist and generate the static asset source
* 6. ACTIVE only: Vite Service Worker build (emptyOutDir = false)
* REMOVE_REGISTRATION only: write the self-unregistering worker (06-03)
* 7. generate the self-contained TechLog production serving boundary
* 8. generate Release Manifest V2 and the build manifest
* 9. make every dist file readable by other users (13-02)
*
* Steps 5 and 6 are skipped for `REMOVE_REGISTRATION`, `PURGE_OWNED_RESOURCES`
* and `null`: those modes never run an active worker build.
* `REMOVE_REGISTRATION` still ships a `service-worker.js` so the browser's
* update check can replace a worker that stops the page from booting (D-5).
*
* Step 4 has to follow the Vite build and precede the asset scan. Vite copies
* `public/` verbatim, so without it every build — including a production one —
* ships the local runtime document; and the Service Worker hashes the emitted
* `config.json`, so the profile must be in place before that inventory is
* taken.
* Step 4 has to follow the Vite build. Vite copies `public/` verbatim, so
* without it every build — including a production one — ships the local
* runtime document. The Service Worker asset scan excludes `config.json`
* (`scripts/generate-service-worker-assets.ts`), so the order against step 5
* is not what keeps the profile out of the worker cache (13-15). Step 6 reads
* the release manifest URL from the `dist/config.json` step 4 wrote, and fails
* if its `APP_ENV` is not `APP_PROFILE` (06-10).
*/
const selection = INSTALLED_RUNTIME_CAPABILITIES.serviceWorker;
@@ -61,6 +70,12 @@ if (buildsActiveWorker) {
run("node", ["scripts/generate-service-worker-assets.ts", "dist"]);
// 6. service worker build
run("npx", ["vite", "build", "--config", "vite.service-worker.config.ts"]);
} else if (selection?.mode === "REMOVE_REGISTRATION") {
// 6. self-unregistering worker in place of the active one
await writeFile(
`dist/${SERVICE_WORKER_SCRIPT_PATH}`,
SELF_UNREGISTERING_SERVICE_WORKER,
);
} else {
process.stdout.write(
`service worker mode ${selection?.mode ?? "null"}: skipping worker build\n`,
@@ -72,3 +87,6 @@ run("node", ["scripts/generate-tech-log-serving-artifact.ts"]);
// 8. release + build manifest
run("node", ["scripts/generate-build-manifest.ts"]);
// 9. publishable permissions: the validated writer creates 0600 files
await makeDistFilesPublic("dist");
+12 -1
View File
@@ -201,7 +201,18 @@ async function main(): Promise<void> {
// 23 → 22: `storage/indexeddb/indexeddb-maintenance.ts`가 같은 이유로 지웠다.
// 22 → 21: `storage/indexeddb/indexeddb-runtime.ts`가 같은 이유로 지웠다.
// 이것으로 IndexedDB 어댑터 4벌이 모두 커널을 쓴다.
const HAND_ROLLED_ABORT_CEILING = 21;
// 21 → 19: `browser-files/download-delivery-adapter.ts`와
// `browser-files/browser-file-vault.ts`가 커널 race로 옮겨갔다(Q-6.2-7).
// 19 → 18: `browser-file-storage/storage-manager-adapter.ts`의 inspection
// 대기가 커널 race로 옮겨갔다(Q-B).
// 17 → 16: `browser-transfer/image-cdn/image-cdn-runtime.ts`의 검증 deadline과
// probe 대기가 커널 operation으로 옮겨갔다(R3-2).
// 16 → 15: `browser-files/browser-file-picker.ts`의 native input 대기와
// system picker 대기가 커널 operation으로 옮겨갔다(R3-2).
// 15 → 13: `storage/opfs/opfs-worker-client.ts`가 커널 abort primitive를 쓰고,
// `storage/indexeddb/indexeddb-governance.ts`의 binding 검증이 커널
// 트랜잭션으로 옮겨갔다(05-07, 05-12).
const HAND_ROLLED_ABORT_CEILING = 13;
const handRolledScan = spawnSync(
"git",
["grep", "-l", 'addEventListener("abort"', "--", "src/adapters"],
+143
View File
@@ -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>): string[] {
return [...new Set(values)].sort();
}
export async function inspectAppBuildInput(
root: string,
options: Readonly<{
source?: TopologyDeclarationSource;
bundleInventory?: string | null;
}> = {},
): Promise<AppBuildInputReport> {
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 ?? "<missing>"} 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<void> {
// 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();
}
+163 -59
View File
@@ -6,11 +6,13 @@ import { fileURLToPath, pathToFileURL } from "node:url";
import { createRequire } from "node:module";
import { architectureDependencyReportArtifactSchema } from "./contracts/release-artifacts.ts";
import { formatArchitectureViolation } from "./lib/architecture-violation-message.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
type PathRule = Readonly<{ path?: string; pathNot?: string }>;
type ArchitectureRule = Readonly<{
name: string;
comment?: string;
severity?: string;
from?: PathRule;
to?: PathRule & Readonly<{ circular?: boolean }>;
@@ -53,7 +55,6 @@ type GraphFixtureResult = Readonly<{
failures: string[];
}>;
type DependencyResolution = Readonly<{ path?: string; reason: string }>;
type DependencyCruiserReport = Record<string, unknown>;
type TypeScriptOnlyPolicy = Readonly<{
checkedRoots: readonly string[];
exceptionsAllowed: false;
@@ -111,27 +112,15 @@ function runPnpm(arguments_: string[]) {
});
}
// Keep dependency-cruiser's report and checks. The second graph is authoritative
// for TypeScript 7 coverage because dependency-cruiser 18 cannot parse TS 7 yet.
const dependencyCruiser = runPnpm([
"exec",
"depcruise",
"src",
"--config",
".dependency-cruiser.json",
"--output-type",
"json",
]);
// 12-05 (D-11): this graph is the only architecture checker. dependency-cruiser
// 18 cannot parse TypeScript 7, so it cruised zero modules and still passed.
// .dependency-cruiser.json keeps its name and is read here as the rule file.
const sourceGraph = await analyzeSourceGraph(sourceRoot, "src");
const typeScriptOnlyPolicy = await inspectTypeScriptOnlyPolicy();
const graphFixtureResult = await runGraphFixtureChecks();
const dependencyReport = parseDependencyCruiserReport(dependencyCruiser.stdout);
const graphErrors = blockingViolations(sourceGraph);
const dependencyCruiserReportValid = !(
"dependencyCruiserOutput" in dependencyReport
);
dependencyReport.staticImportGraph = {
const staticImportGraph = {
analyzer: "babel-parser-node-resolver",
modules: sourceGraph.modules,
dependencies: sourceGraph.dependencies,
@@ -162,25 +151,11 @@ dependencyReport.staticImportGraph = {
await writeValidatedJsonArtifact({
path: qualityArtifact,
schema: architectureDependencyReportArtifactSchema,
value: dependencyReport,
value: { staticImportGraph },
});
let architectureFailed = false;
if (!dependencyCruiserReportValid) {
architectureFailed = true;
process.stderr.write("dependency-cruiser returned an invalid JSON report\n");
}
if (dependencyCruiser.status !== 0) {
architectureFailed = true;
process.stderr.write(
(dependencyCruiser.error?.message ?? dependencyCruiser.stderr) ||
dependencyCruiser.stdout ||
"dependency-cruiser failed\n",
);
}
for (const failure of sourceGraph.parseFailures) {
architectureFailed = true;
process.stderr.write(
@@ -197,11 +172,16 @@ for (const dependency of sourceGraph.unresolved) {
for (const violation of graphErrors) {
architectureFailed = true;
const cycle = violation.cycle
? ` (cycle group: ${violation.cycle.join(", ")})`
: "";
process.stderr.write(
`Architecture violation [${violation.rule}]: ${violation.source} -> ${violation.target}${cycle}\n`,
formatArchitectureViolation(
violation,
violation.cycle
? []
: sourceGraph.dependencies
.filter(({ source, target }) => source === violation.source && target === violation.target)
.map(({ specifier }) => specifier),
architectureRules.find(({ name }) => name === violation.rule)?.comment,
),
);
}
@@ -443,7 +423,7 @@ async function importSpecifiers(sourceFile: string): Promise<string[]> {
visitSyntaxNode(syntaxTree, specifiers, nonLiteralModuleLoads);
if (nonLiteralModuleLoads.size > 0) {
throw new Error(
`module loading must use string literals: ${[...nonLiteralModuleLoads].join(", ")}`,
`module loading must name one module with a string literal: ${[...nonLiteralModuleLoads].join(", ")}`,
);
}
for (const comment of syntaxTree.comments ?? []) {
@@ -503,6 +483,17 @@ function visitSyntaxNode(
if (!addStringLiteral(arguments_[0], specifiers)) {
nonLiteralModuleLoads.add("require()");
}
} else if (
nodeType === "CallExpression" &&
syntaxNodeType(node.callee) === "MemberExpression" &&
syntaxNodeType(syntaxNodeProperty(node.callee, "object")) === "MetaProperty" &&
/^glob(?:Eager)?$/u.test(
String(syntaxNodeProperty(syntaxNodeProperty(node.callee, "property"), "name")),
)
) {
// 12-06: a glob pulls in every matching module without naming one, so no
// edge rule can see it. Refuse it like a non-literal import().
nonLiteralModuleLoads.add("import.meta.glob()");
} else if (nodeType === "TSExternalModuleReference") {
addStringLiteral(node.expression, specifiers);
} else if (nodeType === "TSImportType") {
@@ -824,14 +815,23 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
"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,
importBoundaryGraph,
] = 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"),
analyzeSourceGraph(resolve(fixtureRoot, "import-boundaries"), "src"),
]);
const allowedFiles = new Set(await listFiles(allowedRoot));
const allowedSourceFile = resolve(
allowedRoot,
@@ -851,6 +851,100 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
),
);
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: "feature root re-export of a concrete adapter is rejected",
passed: blockingViolations(crossBoundaryGraph).some(
({ rule, source, target }) =>
rule === "feature-and-app-roots-do-not-reach-adapters" &&
source === "src/features/alpha/telemetry.ts" &&
target === "src/adapters/telemetry/index.ts",
),
},
{
name: "context re-export of a concrete adapter is rejected",
passed: blockingViolations(crossBoundaryGraph).some(
({ rule, source, target }) =>
rule === "feature-and-app-roots-do-not-reach-adapters" &&
source === "src/contexts/customer/telemetry.ts" &&
target === "src/adapters/telemetry/index.ts",
),
},
{
name: "presentation import of a context is rejected",
passed: blockingViolations(crossBoundaryGraph).some(
({ rule, source, target }) =>
rule === "presentation-does-not-import-apps-or-contexts" &&
source === "src/presentation/read-context.ts" &&
target === "src/contexts/customer/telemetry.ts",
),
},
// 12-08 / 12-10: these import rules used to be regular expressions in
// check-design-system.ts and realtime-boundaries.ts beside the graph.
{
name: "design-system deep import is rejected",
passed: blockingViolations(importBoundaryGraph).some(
({ rule, source }) =>
rule === "design-system-is-reached-through-its-index" &&
source === "src/presentation/pages/deep-import.ts",
),
},
{
name: "design-system index and named facades are accepted",
passed: !blockingViolations(importBoundaryGraph).some(({ source }) =>
["src/presentation/pages/public-import.ts", "src/presentation/components/ui/button.ts"].includes(source),
),
},
{
name: "direct icon vendor import is rejected",
passed: blockingViolations(importBoundaryGraph).some(
({ rule, source, target }) =>
rule === "icon-vendor-is-facade-only" &&
source === "src/presentation/pages/direct-icon.ts" &&
target === "lucide-react",
),
},
// F-7 (13-08): zod must be configured jitless before any schema is built.
{
name: "direct zod import outside src/contracts/zod.ts is rejected",
passed: blockingViolations(importBoundaryGraph).some(
({ rule, source, target }) =>
rule === "zod-is-reached-through-contracts-zod" &&
source === "src/presentation/pages/direct-zod.ts" &&
target === "zod",
),
},
{
name: "zod through src/contracts/zod.ts is accepted",
passed: !blockingViolations(importBoundaryGraph).some(({ source }) =>
["src/contracts/zod.ts", "src/presentation/pages/wrapped-zod.ts"].includes(source),
),
},
{
name: "unselected realtime runtime composition is rejected",
passed: blockingViolations(importBoundaryGraph).some(
({ rule, source }) =>
rule === "unselected-realtime-runtime-is-not-composed" &&
source === "src/bootstrap/compose-realtime.ts",
),
},
{
name: "deep adapter import from outside the group is rejected",
passed: blockingViolations(barrelGraph).some(
@@ -860,6 +954,21 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
target === "src/adapters/http/client.ts",
),
},
{
name: "second-level index import from outside the group is rejected",
passed: blockingViolations(barrelGraph).some(
({ rule, source, target }) =>
rule === "adapter-groups-are-reached-through-their-barrel" &&
source === "src/bootstrap/compose-sub-barrel.ts" &&
target === "src/adapters/http/internals/index.ts",
),
},
{
name: "storage runtime sub-barrel import is accepted",
passed: !blockingViolations(barrelGraph).some(
({ source }) => source === "src/bootstrap/compose-storage-sub-barrel.ts",
),
},
{
name: "barrel import from outside the group is accepted",
passed: !blockingViolations(barrelGraph).some(
@@ -929,6 +1038,14 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
reason.includes("import()"),
),
},
{
name: "import.meta.glob module loads are rejected",
passed: unresolvedGraph.parseFailures.some(
({ source, reason }) =>
source === "src/application/glob-value.ts" &&
reason.includes("import.meta.glob"),
),
},
{
name: "non-literal CommonJS imports are rejected",
passed: unresolvedGraph.parseFailures.some(
@@ -1074,6 +1191,7 @@ function parseArchitectureConfig(value: unknown): ArchitectureConfig {
function isArchitectureRule(value: unknown): value is ArchitectureRule {
if (!isRecord(value) || typeof value.name !== "string") return false;
if (value.comment !== undefined && typeof value.comment !== "string") return false;
if (value.severity !== undefined && typeof value.severity !== "string") {
return false;
}
@@ -1099,17 +1217,3 @@ function isPathRule(value: unknown, allowCircular: boolean): value is PathRule {
function isRecord(value: unknown): value is Record<string, unknown> {
return Boolean(value && typeof value === "object" && !Array.isArray(value));
}
function parseDependencyCruiserReport(
output: string,
): DependencyCruiserReport {
try {
const report: unknown = JSON.parse(output);
if (!report || typeof report !== "object" || Array.isArray(report)) {
throw new Error("dependency-cruiser report must be a JSON object");
}
return report as DependencyCruiserReport;
} catch {
return { summary: { errors: 1 }, dependencyCruiserOutput: output };
}
}
+1 -1
View File
@@ -1,6 +1,6 @@
import { readFile } from "node:fs/promises";
import { evaluateBundleBudget } from "../src/application/policies/performance-budgets.ts";
import { evaluateBundleBudget } from "./lib/performance-budgets.ts";
import {
bundleOutputInventoryArtifactSchema,
bundlePerformanceArtifactSchema,
+61 -11
View File
@@ -1,16 +1,22 @@
import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
import { readFile } from "node:fs/promises";
import {
evaluatePromotionReadiness,
PROMOTION_FORMULA,
type GateResult,
} from "../src/application/policies/promotion-readiness.ts";
} from "./lib/promotion-readiness.ts";
import {
CANONICAL_GATE_IDS,
loadCiGateContract,
indexCiGateContract,
} from "./contracts/ci-gates.ts";
import { generateCiWorkflow, renderCiWorkflow } from "./generate-ci-workflow.ts";
import {
generateCiWorkflow,
renderCiWorkflow,
workflowGateExecutionFailures,
} from "./generate-ci-workflow.ts";
import {
ciContractReportSchema,
} from "./lib/ci-contract-report.ts";
@@ -18,12 +24,21 @@ import {
validateInstallScriptPolicy,
validatePackageScriptGraph,
} from "./lib/package-script-graph.ts";
import {
gatedTestPaths,
listTestFiles,
parseUngatedTestExclusions,
ungatedTestFailures,
UNGATED_TESTS_PATH,
} from "./lib/ungated-tests.ts";
import {
parseUngatedScriptExclusions,
ungatedScriptFailures,
UNGATED_SCRIPTS_PATH,
} from "./lib/ungated-scripts.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
const removalFixtureMode = process.argv.includes("--reduced-removal-fixture");
const contract = await loadCiGateContract(process.cwd(), {
mode: removalFixtureMode ? "removal-fixture" : "canonical",
});
const contract = await loadCiGateContract(process.cwd());
const index = indexCiGateContract(contract);
const [packageDocument, nodeVersion] = await Promise.all([
readFile("package.json", "utf8").then((value) => JSON.parse(value) as { scripts?: Record<string, string> }),
@@ -63,6 +78,43 @@ failures.push(
),
);
// 12-04: every test file runs in a gate, or config/ci/ungated-tests.json says why not.
try {
failures.push(
...ungatedTestFailures({
testFiles: await listTestFiles(process.cwd()),
gatedPaths: gatedTestPaths(
packageScripts,
contract.commands.map(({ script }) => script),
(file) => readFileSync(file, "utf8"),
),
exclusions: parseUngatedTestExclusions(
JSON.parse(await readFile(UNGATED_TESTS_PATH, "utf8")),
),
}),
);
} catch (error) {
failures.push(`ungated test check could not run: ${error instanceof Error ? error.message : String(error)}`);
}
// 12-04: every verification package script is reached by a gate, or
// config/ci/ungated-scripts.json says why not.
try {
const entryScripts = contract.commands.map(({ script }) => script);
failures.push(
...ungatedScriptFailures({
scripts: packageScripts,
entryScripts,
gatedTestPaths: gatedTestPaths(packageScripts, entryScripts, (file) => readFileSync(file, "utf8")),
exclusions: parseUngatedScriptExclusions(
JSON.parse(await readFile(UNGATED_SCRIPTS_PATH, "utf8")),
),
}),
);
} catch (error) {
failures.push(`ungated script check could not run: ${error instanceof Error ? error.message : String(error)}`);
}
const immutable = index.gates.get("FE-GATE-015");
const immutableCommands = immutable?.commandIds.map((id) => index.commands.get(id)?.script);
if (JSON.stringify(immutableCommands) !== JSON.stringify(["build:release-candidate", "verify:local-evidence"])) {
@@ -76,10 +128,7 @@ if (!architecture?.evidenceArtifactIds.some((id) => index.artifacts.get(id)?.pat
failures.push("FE-GATE-010 must publish the typed CI contract report");
}
const expectedGateIds = Array.from(
{ length: 27 },
(_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`,
);
const expectedGateIds = CANONICAL_GATE_IDS;
const passingResults: Record<string, GateResult> = Object.fromEntries(
expectedGateIds.map((gateId) => [gateId, "PASS"]),
);
@@ -116,6 +165,7 @@ try {
} catch (error) {
failures.push(`generated workflow is unreadable: ${error instanceof Error ? error.message : String(error)}`);
}
failures.push(...workflowGateExecutionFailures(contract, checkedWorkflowBytes.toString("utf8")));
const report = ciContractReportSchema.parse({
schemaVersion: 2,
nodeVersion,
@@ -139,4 +189,4 @@ if (failures.length > 0) {
process.stderr.write(`CI contract failed:\n${failures.join("\n")}\n`);
process.exit(1);
}
process.stdout.write("CI contract: 27 gates, strict v2 graph and generated workflow model PASS\n");
process.stdout.write(`CI contract: ${CANONICAL_GATE_IDS.length} gates, strict v2 graph and generated workflow model PASS\n`);
+55 -26
View File
@@ -1,53 +1,72 @@
import { mkdir, readFile } from "node:fs/promises";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { classifyObjectSchemaChange } from "../src/contracts/compatibility.ts";
import { z } from "zod";
import {
classifyObjectSchemaChange,
type ObjectSchemaShape,
type SchemaChangeClassification,
} from "../src/contracts/compatibility.ts";
import { runtimeConfigV2ArtifactSchema } from "../src/contracts/release-artifacts.ts";
import { compatibilityFixturesArtifactSchema } from "./contracts/release-artifacts.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
type CompatibilitySchema = Readonly<{
required?: readonly string[];
properties?: Readonly<Record<string, unknown>>;
}>;
type CompatibilityFixture = Readonly<{
before: CompatibilitySchema;
after: CompatibilitySchema;
}>;
// FE-GATE-014 (07-02, 13-10). The committed baseline stands in for the schema
// the previous release's reader accepts; the current schema is exactly what
// the build writes to dist/runtime-config.schema.json.
const BASELINE_PATH = "config/compatibility/runtime-config.schema.baseline.json";
type CompatibilityFixtures = Readonly<{
families: Readonly<
Record<string, Readonly<Record<"additive" | "breaking", CompatibilityFixture>>>
>;
cases: readonly Readonly<{
id: string;
expected: SchemaChangeClassification;
before: ObjectSchemaShape;
after: ObjectSchemaShape;
}>[];
}>;
const current = z.toJSONSchema(runtimeConfigV2ArtifactSchema);
if (process.argv.includes("--update-baseline")) {
await writeFile(BASELINE_PATH, `${JSON.stringify(current, null, 2)}\n`);
process.stdout.write(`Updated ${BASELINE_PATH}\n`);
process.exit(0);
}
const fixtures = JSON.parse(
await readFile("config/compatibility/fixtures.json", "utf8"),
) as CompatibilityFixtures;
const results = [];
const results = fixtures.cases.map(({ id, expected, before, after }) => {
const actual = classifyObjectSchemaChange(before, after);
return { id, expected, actual, passed: actual === expected };
});
for (const [family, cases] of Object.entries(fixtures.families)) {
for (const expected of ["additive", "breaking"] as const) {
const fixture = cases[expected];
const actual = classifyObjectSchemaChange(fixture.before, fixture.after);
results.push({ family, expected, actual, passed: actual === expected });
}
}
const baselineClassification = classifyObjectSchemaChange(
JSON.parse(await readFile(BASELINE_PATH, "utf8")) as ObjectSchemaShape,
current as ObjectSchemaShape,
);
const baseline = {
path: BASELINE_PATH,
classification: baselineClassification,
passed: baselineClassification !== "breaking",
};
await mkdir("artifacts/release", { recursive: true });
await writeValidatedJsonArtifact({
path: "artifacts/release/compatibility.json",
schema: compatibilityFixturesArtifactSchema,
value: {
schemaVersion: 1,
schemaVersion: 2,
generatedAt: new Date().toISOString(),
rules: [
"additive changes preserve required fields",
"breaking changes require version bump and migration, discard, fallback, or rollback",
"a change is additive only when it adds a property under a reader that tolerates unknown keys",
"type, enum, nullable, required-set and unmodelled changes are breaking (fail-closed)",
"adding a field at a strict (REJECT_UNKNOWN) boundary is breaking: deploy the reader first",
"config and API major versions must match",
"incompatible persisted cache is discarded by default",
"rollback uses a coherent compatibility tuple",
],
results,
baseline,
},
});
@@ -55,4 +74,14 @@ if (results.some((result) => !result.passed)) {
process.stderr.write("Compatibility fixture classification failed.\n");
process.exit(1);
}
process.stdout.write("Compatibility fixtures: PASS\n");
if (!baseline.passed) {
process.stderr.write(
`Runtime config schema change is breaking for readers of ${BASELINE_PATH}.\n` +
"Follow docs/contracts/compatibility.md (deploy readers first), then run\n" +
"`corepack pnpm verify:compatibility --update-baseline` and commit the baseline.\n",
);
process.exit(1);
}
process.stdout.write(
`Compatibility fixtures: PASS; runtime config schema vs baseline: ${baseline.classification}\n`,
);
+11 -13
View File
@@ -29,8 +29,14 @@ for (const [layer, file, tokens] of tokenLayers) {
}
}
// theme.css only imports the files under styles/theme/, so check them all.
const styleFiles = (
await readdir("src/presentation/styles", { recursive: true })
)
.filter((file) => file.endsWith(".css"))
.map((file) => path.join("src/presentation/styles", file));
const cssSources = await Promise.all(
[...Object.values(tokenFiles), "src/presentation/styles/theme.css"].map(
[...Object.values(tokenFiles), ...styleFiles].map(
async (file) => ({ file, source: await readFile(file, "utf8") }),
),
);
@@ -97,22 +103,14 @@ const sources = fixtureMode
: await listSourceFiles("src");
for (const file of sources) {
const source = await readFile(file, "utf8");
const vendorFacade =
file === "src/presentation/design-system/icons/vendors/lucide.tsx";
if (!vendorFacade && /from\s+["']lucide-react["']/.test(source)) {
failures.push(`direct icon vendor import in ${file}`);
}
// Icon vendor and design-system deep imports are graph rules in
// .dependency-cruiser.json (check:architecture), which also sees relative,
// dynamic and type imports (12-08, 12-10).
if (
/from\s+["'](?:react-aria-components|@radix-ui\/[^"']+)["']/.test(source)
) {
failures.push(`direct headless vendor import in ${file}`);
}
if (
!file.includes("src/presentation/design-system/") &&
/presentation\/design-system\/(?!index(?:\.tsx?)?["'])/.test(source)
) {
failures.push(`design-system deep import in ${file}`);
}
if (
!rawPaletteSourceFiles.has(file) &&
containsRawPaletteValue(source)
@@ -151,5 +149,5 @@ if (failures.length > 0) {
process.exit(1);
}
process.stdout.write(
`Design system contract: ${report.checkedTokenCount} tokens and vendor boundaries PASS\n`,
`Design system contract: ${report.checkedTokenCount} tokens and headless vendor boundary PASS\n`,
);
+25 -3
View File
@@ -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[] = [];
@@ -26,6 +33,7 @@ const telemetryProducerFiles: Readonly<Record<string, string>> = {
"api.request.failed": "src/adapters/http/client.ts",
"ui.render.failed": "src/application/create-application.ts",
"release.mismatch.detected": "src/application/create-application.ts",
"service-worker.start.failed": "src/bootstrap/optional-runtime-host.ts",
"telemetry.delivery.dropped":
"src/adapters/telemetry/best-effort-telemetry.ts",
};
@@ -40,7 +48,21 @@ const diagnosticProducerFiles: Readonly<Record<string, string>> = {
"ui.render.failed": "src/application/create-application.ts",
"release.mismatch.detected": "src/application/create-application.ts",
"telemetry.delivery.dropped": "src/bootstrap/runtime-adapters.ts",
};
"feature.override.unknown": "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)) {
+53 -10
View File
@@ -53,26 +53,57 @@ if (!fixtureMode) {
}
}
// 08-04. Screen code under these directories must take its words from the
// catalog. `src/presentation/examples` is the component gallery and stays out
// of scope on purpose. Fixture mode runs the same discovery on a fixture tree.
const sourceRoot = fixtureMode ? "tests/fixtures/i18n/forbidden" : ".";
const commonDirectories = [
"src/presentation/boundaries",
"src/presentation/components",
"src/presentation/design-system",
"src/presentation/forms",
"src/presentation/layouts",
"src/presentation/pages",
"src/presentation/routes",
"src/presentation/templates",
];
const commonSources = fixtureMode
? await listSourceFiles("tests/fixtures/i18n/forbidden")
: (
await Promise.all(commonDirectories.map((directory) => listSourceFiles(directory)))
).flat();
async function featurePresentationDirectories(root: string): Promise<string[]> {
const features = path.join(root, "src/features");
const entries = await readdir(features, { withFileTypes: true }).catch(
() => [],
);
return entries
.filter((entry) => entry.isDirectory())
.map((entry) => path.join("src/features", entry.name, "presentation"));
}
async function existingSourceFiles(directory: string): Promise<string[]> {
return listSourceFiles(directory).catch((error: NodeJS.ErrnoException) => {
if (error.code === "ENOENT") return [];
throw error;
});
}
// Template sync (af3d8e6). TechLog's presentation is held to its own
// behavioral-literal policy (scripts/lib/tech-log-i18n-policy.ts), which reads
// string literals and JSX text rather than whole files, so the whole-file
// Korean rule above applies to every other feature and not to it.
const techLogPresentation = path.join("src/features", "tech-log", "presentation");
const sourceDirectories = [
...commonDirectories,
...(await featurePresentationDirectories(sourceRoot)).filter(
(directory) => directory !== techLogPresentation,
),
].map((directory) => path.join(sourceRoot, directory));
const sources = (
await Promise.all(sourceDirectories.map(existingSourceFiles))
).flat();
const techLogSources = fixtureMode
? []
: await listSourceFiles("src/features/tech-log/presentation");
const sources = [...commonSources, ...techLogSources];
: await existingSourceFiles(techLogPresentation);
for (const file of commonSources) {
for (const file of sources) {
const source = await readFile(file, "utf8");
if (koreanLiteral.test(source)) {
failures.push(`hardcoded common user-facing locale literal in ${file}`);
@@ -85,7 +116,6 @@ for (const file of commonSources) {
}
}
for (const file of techLogSources) {
const source = await readFile(file, "utf8");
for (const violation of findTechLogBehavioralLiteralViolations(source)) {
@@ -106,7 +136,7 @@ const report = i18nReportArtifactSchema.parse({
mode: fixtureMode ? "negative-fixture" : "source",
localeCount: Object.keys(MESSAGE_CATALOGS).length + 1,
messageKeyCount: Object.keys(KO_MESSAGES).length,
checkedFiles: sources.length,
checkedFiles: sources.length + techLogSources.length,
failures,
passed: failures.length === 0,
});
@@ -119,6 +149,19 @@ await writeValidatedJsonArtifact({
value: report,
});
// Every fixture file must be rejected on its own; one rejected file must not
// hide a directory the discovery above stopped reaching.
const fixtureFiles = fixtureMode ? await listSourceFiles(sourceRoot) : [];
const unrejectedFixtures = fixtureFiles.filter(
(file) => !failures.some((failure) => failure.endsWith(file)),
);
if (fixtureMode && (fixtureFiles.length === 0 || unrejectedFixtures.length > 0)) {
process.stderr.write(
`I18n fixture was not rejected:\n${unrejectedFixtures.join("\n") || "(no fixture files found)"}\n`,
);
process.exit(2);
}
if (failures.length > 0) {
process.stderr.write(`I18n contract failed:\n${failures.join("\n")}\n`);
process.exit(1);
@@ -13,7 +13,6 @@ const forbiddenOutput = `${forbidden.stdout}${forbidden.stderr}`;
const expectedRules = [
"NATIVE_REALTIME_API_OUTSIDE_ADAPTER",
"PRESENTATION_INTERVAL_OWNER",
"UNSELECTED_REALTIME_RUNTIME_COMPOSED",
] as const;
if (
+26 -1
View File
@@ -330,6 +330,27 @@ function projectSnapshotRows(
});
}
/**
* 09-07. `src/features/*\/adapters` names that directory in every feature, so
* adding a feature does not mean adding it to this governance file.
*/
async function expandDirectoryPattern(pattern: string): Promise<string[]> {
const star = pattern.split("/").indexOf("*");
if (star === -1) return [pattern];
const segments = pattern.split("/");
const parent = segments.slice(0, star).join("/");
const rest = segments.slice(star + 1).join("/");
const entries = await readdir(parent, { withFileTypes: true }).catch(() => []);
const expanded = await Promise.all(
entries
.filter((entry) => entry.isDirectory())
.map((entry) =>
expandDirectoryPattern(path.join(parent, entry.name, rest)),
),
);
return expanded.flat();
}
async function filesBelow(directory: string): Promise<string[]> {
try {
const entries = await readdir(directory, { withFileTypes: true });
@@ -548,7 +569,11 @@ for (const specification of governance.registries) {
if (specification.consumerIdentityField) {
const consumerFiles = (
await Promise.all(
(specification.consumerDirectories ?? []).map(filesBelow),
(await Promise.all(
(specification.consumerDirectories ?? []).map(expandDirectoryPattern),
))
.flat()
.map(filesBelow),
)
).flat();
const sourcePath = sourcesByRegistry.get(specification.registryId);
+26
View File
@@ -7,7 +7,9 @@ import {
isDeploymentTarget,
type AdmissionInput,
} from "../src/contracts/deployment-admission.ts";
import { unknownProductFeatureOverrides } from "../src/contracts/product-features.ts";
import { parseRuntimeConfigArtifact } from "../src/contracts/release-artifacts.ts";
import { COMPILED_PRODUCT_FEATURE_IDS } from "../src/features/installed-product-manifest.ts";
/**
* §6.4 / FE-GATE-027. Refuses to admit an artifact to an environment it was not
@@ -40,6 +42,17 @@ async function main(): Promise<void> {
process.exitCode = 1;
return;
}
// 13-01: the build profile and the admission target are separate repository
// variables; a profile left on staging must not ship to production.
const profile = process.env["APP_PROFILE"];
if (profile !== undefined && profile !== declared) {
process.stderr.write(
`release admission refused: the artifact was built with APP_PROFILE=${profile} ` +
`but RELEASE_TARGET=${declared}. Set both to the same environment.\n`,
);
process.exitCode = 1;
return;
}
let document: unknown;
try {
@@ -68,6 +81,18 @@ async function main(): Promise<void> {
}
const violations = findAdmissionViolations(declared, config);
// 09-09. Inert by design (a shared document may name another build's
// features), so this warns instead of refusing.
const warnings = unknownProductFeatureOverrides(
COMPILED_PRODUCT_FEATURE_IDS,
"FEATURE_OVERRIDES" in config ? config.FEATURE_OVERRIDES : undefined,
).map((featureId) => ({
field: `FEATURE_OVERRIDES.${featureId}`,
reason: `names no feature this build declares (${COMPILED_PRODUCT_FEATURE_IDS.join(", ") || "none"}); the override does nothing`,
}));
for (const warning of warnings) {
process.stderr.write(`release admission warning: ${warning.field} ${warning.reason}\n`);
}
await mkdir("artifacts/release", { recursive: true });
await writeFile(
RECORD_PATH,
@@ -82,6 +107,7 @@ async function main(): Promise<void> {
releaseId: config.RELEASE_ID ?? null,
status: violations.length === 0 ? "ADMITTED" : "REFUSED",
violations,
warnings,
},
null,
2,
+1 -1
View File
@@ -1,4 +1,4 @@
import { access, readFile } from "node:fs/promises";
import { readFile } from "node:fs/promises";
/**
* GOV-03. Joins the machine-readable remediation dispositions against the prose
+185
View File
@@ -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: <reason>`.
*/
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<string, unknown>;
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<readonly FanoutViolation[]> {
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<string[]> {
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<Readonly<{ files: number; violations: readonly FanoutViolation[] }>> {
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<void> {
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();
}
@@ -41,7 +41,10 @@ import {
releaseCandidateManifestSchema,
} from "./lib/release-candidate.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
import { linkFixtureNodeModules } from "./lib/fixture-node-modules.ts";
import {
FIXTURE_PNPM_ENVIRONMENT,
linkFixtureNodeModules,
} from "./lib/fixture-node-modules.ts";
const repositoryRoot = process.cwd();
const fixtureRoot = await mkdtemp(path.join(tmpdir(), "provider-exact-five-fixture-"));
@@ -74,6 +77,7 @@ try {
maxBuffer: 32 * 1024 * 1024,
env: {
...process.env,
...FIXTURE_PNPM_ENVIRONMENT,
CI: "true",
VITE_BUILD_ID: "provider-exact-five-fixture",
VITE_COMMIT_SHA: revision,
@@ -249,6 +253,31 @@ try {
},
nowEpochMs: () => now,
} as const;
// 13-04: the same bundle three hours later. Current freshness refuses the
// expired provider evidence; archived freshness accepts it at the recorded
// promotion time, and still refuses a tampered archive.
const threeHoursLater = now + 3 * 60 * 60 * 1_000;
const archivedAfterWindow = await captureRejection(async () => {
await verifyExactPromotionBundle(exactFiles, {
...bundleTrust,
nowEpochMs: () => threeHoursLater,
freshness: "archived",
});
});
const currentAfterWindow = await captureRejection(async () => {
await verifyExactPromotionBundle(exactFiles, {
...bundleTrust,
nowEpochMs: () => threeHoursLater,
});
});
const tamperedArchive = Buffer.from(exactFiles["release-candidate.tar.gz"]);
tamperedArchive[tamperedArchive.length - 1] ^= 0xff;
const archivedTampered = await captureRejection(async () => {
await verifyExactPromotionBundle(
{ ...exactFiles, "release-candidate.tar.gz": tamperedArchive },
{ ...bundleTrust, nowEpochMs: () => threeHoursLater, freshness: "archived" },
);
});
const absentFiles = { ...exactFiles } as Partial<typeof exactFiles>;
delete absentFiles["provider-verification.json"];
const absent = await captureRejection(async () => {
@@ -282,7 +311,8 @@ try {
await captureCiCandidateArchive({ archivePath, expectedSha256: "0".repeat(64) });
});
const passed =
validImmutable && absent.rejected && invalidTar.rejected && wrongDigest.rejected;
validImmutable && absent.rejected && invalidTar.rejected && wrongDigest.rejected &&
!archivedAfterWindow.rejected && currentAfterWindow.rejected && archivedTampered.rejected;
await cleanupFinalizedPromotion({
runnerTempRoot,
stagingRoot: finalized.stagingRoot,
@@ -314,12 +344,24 @@ try {
status: invalidTar.rejected ? "FAIL_UNVERIFIED" : "PASS",
failures: [invalidTar.failure],
},
archivedAfterWindow: {
status: archivedAfterWindow.rejected ? "FAIL_UNVERIFIED" : "PASS",
failures: archivedAfterWindow.rejected ? [archivedAfterWindow.failure] : [],
},
currentAfterWindow: {
status: currentAfterWindow.rejected ? "FAIL_UNVERIFIED" : "PASS",
failures: [currentAfterWindow.failure],
},
archivedTampered: {
status: archivedTampered.rejected ? "FAIL_UNVERIFIED" : "PASS",
failures: [archivedTampered.failure],
},
},
externalTreeCanary: {
status: validImmutable ? "PASS" : "FAIL_UNVERIFIED",
failures: validImmutable ? [] : ["external tree canary influenced captured archive"],
},
passingFixtureCount: validImmutable ? 1 : 0,
passingFixtureCount: (validImmutable ? 1 : 0) + (archivedAfterWindow.rejected ? 0 : 1),
status: passed ? "PASS" : "FAIL",
},
});
+24 -3
View File
@@ -281,17 +281,27 @@ if (!scenarioOnly) {
const sourceFiles = (await filesBelow(sourceRoot)).filter(
(file) => fixtureMode || !file.split(path.sep).includes("fixtures"),
);
const today = new Date().toISOString().slice(0, 10);
for (const file of sourceFiles) {
if (!/\.(?:ts|tsx|fixture|txt)$/.test(file)) continue;
const source = await readFile(file, "utf8");
facts.scannedFiles += 1;
if (/\b(?:test|it|describe)(?:\.describe)?\.only\s*\(/.test(source)) {
failures.push(`${file}: focused test (.only) runs alone and hides the rest of the suite`);
}
const skipPattern = /\b(?:test|it|describe)(?:\.describe)?\.(?:skip|fixme)\s*\(/g;
if (skipPattern.test(source)) {
const quarantine =
/quarantine\(owner=[^)]+,\s*defect=[^)]+,\s*expires=\d{4}-\d{2}-\d{2}\)/;
if (!quarantine.test(source)) {
const quarantines = [
...source.matchAll(
/quarantine\(owner=[^)]+,\s*defect=[^)]+,\s*expires=(\d{4}-\d{2}-\d{2})\)/g,
),
];
if (quarantines.length === 0) {
failures.push(`${file}: skip/fixme lacks owned expiring quarantine`);
}
for (const [, expires = ""] of quarantines) {
if (expires < today) failures.push(`${file}: quarantine expired on ${expires}`);
}
}
const wholeUiMask =
/\bmask\s*:\s*\[[\s\S]{0,240}(?:locator|getByRole)\s*\(\s*["'](?:html|body|main|application|document)["']/i;
@@ -370,6 +380,17 @@ if (!fixtureMode && !scenarioOnly) {
failures.push(`playwright.config.ts missing release evidence token ${token}`);
}
}
// playwright.dev.config.ts spreads playwright.config.ts.
for (const config of [
"playwright.config.ts",
"playwright.visual.config.ts",
"playwright.storybook.config.ts",
"playwright.capabilities.config.ts",
]) {
if (!(await readFile(config, "utf8")).includes("forbidOnly: true")) {
failures.push(`${config}: missing forbidOnly: true, so a committed test.only passes the gate`);
}
}
const e2eFiles = (await filesBelow("tests/e2e")).filter((file) =>
/\.spec\.ts$/.test(file),
+1 -1
View File
@@ -3,7 +3,7 @@ import { mkdir, readFile } from "node:fs/promises";
import {
evaluateFieldBudget,
percentile75,
} from "../src/application/policies/performance-budgets.ts";
} from "./lib/performance-budgets.ts";
import { fieldWebVitalsArtifactSchema } from "./contracts/release-artifacts.ts";
import { validateFieldEvidenceInput } from "./lib/field-vitals-evidence.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
+148 -160
View File
@@ -4,8 +4,8 @@ import path from "node:path";
import { z } from "zod";
import { PROMOTION_FORMULA } from "../../src/application/policies/promotion-readiness.ts";
import { MANUAL_A11Y_ROUTE_IDS } from "../lib/manual-a11y-evidence.ts";
import { PROMOTION_FORMULA } from "../lib/promotion-readiness.ts";
import {
RELEASE_CANDIDATE_EVIDENCE_PATHS,
RELEASE_CANDIDATE_MANIFEST_PATH,
@@ -439,56 +439,42 @@ export type CiGateContractIndex = Readonly<{
jobs: ReadonlyMap<string, CiWorkflowJob>;
retentionClasses: ReadonlyMap<string, CiGateContract["retention"]["classes"][number]>;
}>;
export type LoadCiGateContractOptions = Readonly<{
mode?: "canonical" | "removal-fixture";
}>;
const CANONICAL_GATE_SHAPE_SHA256 =
// 환경 구성(SETUP) 문서 종류: FE-GATE-009 가 TECH_LOG_SETUP 수동 접근성 증거를 얻어 다시
// 계산했다. 같은 방법이다 — 이전 상수 e4e61b06… 을 이전 gates.json 에서 먼저 재현해
// 계산이 맞는지 확인한 뒤 새 파일을 해싱했다.
// 개념(CONCEPT) 문서 종류: FE-GATE-009 가 TECH_LOG_CONCEPT 수동 접근성 증거를 얻어 다시 계산했다.
// 같은 방법으로 — 옛 gates.json 에서 이전 상수 fb138e7c… 를 먼저 재현해 계산이 맞는지
// 확인한 뒤 새 파일을 해싱했다.
// Template merge. Both sides carried a digest of their own gate set; neither
// describes the merged one. Recomputed from the merged config/ci/gates.json.
// Task 11: recomputed again after FE-GATE-009 gained the
// TECH_LOG_STUDIO_ASSETS manual accessibility evidence artifact.
// Final fix wave item 1: recomputed again after FE-GATE-010 gained
// `check-tech-log-contract`. Recomputed with `canonicalGateShapeSha256`
// below, verified by first reproducing the previous constant from the
// previous `config/ci/gates.json` before hashing the new one.
// Alignment follow-up item 2: recomputed again after FE-GATE-007 gained
// `test-tech-log` and its junit evidence, by the same method — the previous
// constant f3cc9075… was reproduced from the previous gates.json first, so
// the transcription that produced this value is known to be the real one.
// Dev release manifest drift fix, item 2: recomputed again after FE-GATE-010
// gained `check-dev-release-manifest`. Same method — 98d19911… was first
// reproduced from the previous gates.json before this value was hashed.
// Taxonomy route: recomputed again after FE-GATE-009 gained the
// TECH_LOG_STUDIO_TAXONOMY manual accessibility evidence artifact. The gate
// lists one evidence artifact per installed route and refuses a set that does
// not match the route scope exactly, so adding a route necessarily moves this
// digest — that is the point of pinning it.
// Release authoring: recomputed again after FE-GATE-009 gained the
// TECH_LOG_STUDIO_RELEASES evidence artifact, by the same method — 8c73d447…
// was first reproduced from the previous gates.json, so the computation that
// produced this value is known to be the one the constant was pinned under.
// 프로젝트 편집 화면: FE-GATE-009 가 TECH_LOG_STUDIO_PROJECT_EDIT 증거 아티팩트를
// 얻어 다시 계산했다. 같은 방법이다 — 187dbd96… 을 이전 gates.json 에서 먼저 재현해,
// 이 값을 만든 계산이 상수가 고정될 때 쓰인 그 계산임을 확인했다.
// 릴리즈 편집 화면: 같은 방법으로 다시 계산했다. f9e7e521… 을 이전 gates.json 에서 먼저
// 재현했다.
// 주제 화면 셋(`/topics`, `/topics/:slug/:variant`, `/studio/topics/:id`): FE-GATE-009 가 각
// 라우트의 수동 접근성 증거를 얻어 다시 계산했다. 같은 방법이다 — 87a22f68… 을 이전
// gates.json 에서 먼저 재현해 계산이 맞는지 확인한 뒤 새 파일을 해싱했다.
// Template sync (ebea300). Both sides again carried a digest of their own
// gate set — 8a1a5479… here, 43dc4ed1… upstream — and neither describes the
// merged config/ci/gates.json. Recomputed from the merged file by the same
// method: 8a1a5479… was first reproduced from the pre-merge gates.json, so
// the computation that produced this value is the one the constant is
// pinned under.
"629e5898f6a38d5056fc6a4bee834c47f363669ce9925a2c0dabeddd64d11879";
/**
* D-14. FE-GATE-016 (rollback-drill) ran the same FE-RB-005 drill as
* FE-GATE-025 and counted it twice toward production readiness. Its id stays
* retired so no later gate reuses it with a different meaning.
*/
export const RETIRED_GATE_IDS: readonly string[] = Object.freeze(["FE-GATE-016"]);
export const CANONICAL_GATE_IDS: readonly string[] = Object.freeze(
Array.from({ length: 28 }, (_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`)
.filter((gateId) => !RETIRED_GATE_IDS.includes(gateId)),
);
/**
* D-13. The contract's size and gate shape are a reviewed baseline, not code
* constants: a project that removes a sample or adds a gate records the new
* shape with `update:ci-contract-baseline` (owner and reason required) and the
* diff of this file is what review sees.
*/
export const CI_CONTRACT_BASELINE_PATH = "config/ci/contract-baseline.json";
const ciContractBaselineSchema = z
.object({
schemaVersion: z.literal(1),
owner: nonEmpty,
reason: nonEmpty,
gates: z.number().int().nonnegative(),
commands: z.number().int().nonnegative(),
commandReferences: z.number().int().nonnegative(),
artifacts: z.number().int().nonnegative(),
stages: z.number().int().nonnegative(),
gateShapeSha256: z.string().regex(/^[0-9a-f]{64}$/u),
})
.strict();
export type CiContractBaseline = z.infer<typeof ciContractBaselineSchema>;
function canonicalGateShapeSha256(gates: CiGateContract["gates"]): string {
const normalized = gates.map(
@@ -513,57 +499,52 @@ function canonicalGateShapeSha256(gates: CiGateContract["gates"]): string {
return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
}
function canonicalAuthorityBaselineFailures(contract: CiGateContract): string[] {
const failures: string[] = [];
const commandReferenceCount = contract.gates.reduce(
(total, gate) => total + gate.commandIds.length,
0,
export function measureCiContractBaseline(
contract: CiGateContract,
): Omit<CiContractBaseline, "schemaVersion" | "owner" | "reason"> {
return {
gates: contract.gates.length,
commands: contract.commands.length,
commandReferences: contract.gates.reduce(
(total, gate) => total + gate.commandIds.length,
0,
),
artifacts: contract.artifacts.length,
stages: contract.stages.length,
gateShapeSha256: canonicalGateShapeSha256(contract.gates),
};
}
async function assertCiContractBaseline(
root: string,
contract: CiGateContract,
): Promise<void> {
const parsed = ciContractBaselineSchema.safeParse(
JSON.parse(await readFile(path.join(root, CI_CONTRACT_BASELINE_PATH), "utf8")),
);
if (contract.gates.length !== 27) {
failures.push(`gate authority baseline must contain exactly 27 gates; received ${contract.gates.length}`);
}
// Final fix wave, item 1: FE-GATE-010 gained `check-tech-log-contract`, the
// drift gate that pins the vendored canonical Studio contract to its digest.
// Until it was referenced by a gate it ran only when typed by hand.
// Alignment follow-up, item 2: FE-GATE-007 gained `test-tech-log`. The suite
// already ran inside `test:coverage`'s combined vitest invocation, so a
// TechLog failure was reported as a coverage-gate failure with no junit of
// its own to name it.
// Dev release manifest drift fix, item 2: FE-GATE-010 gained
// `check-dev-release-manifest`. No gate read `public/*.json` at all, so a
// fixture that did not declare the compiled contract set broke `pnpm dev`
// outright while every static gate stayed green.
// Template sync (ebea300). The template's own baseline was 91/103; this
// product's was 85/97. Recomputed from the merged config/ci/gates.json.
if (contract.commands.length !== 94 || commandReferenceCount !== 106) {
failures.push(
`command authority baseline must contain exactly 94 definitions and 106 references; received ${contract.commands.length} definitions and ${commandReferenceCount} references`,
if (!parsed.success) {
throw new TypeError(
`${CI_CONTRACT_BASELINE_PATH} invalid:\n${parsed.error.issues
.map((issue) => `${issue.path.join(".") || "root"}: ${issue.message}`)
.join("\n")}`,
);
}
// Template merge. 126 product artifacts plus the two the template added.
// Task 11 added one more: the TECH_LOG_STUDIO_ASSETS manual a11y evidence file.
// Alignment follow-up, item 2 added the TechLog junit report.
// The taxonomy route added its own manual a11y evidence file — every installed
// route carries one, and the gate checks that the two sets match exactly.
// The project edit route did the same: it is what finally lets a project carry
// a purpose, a current objective, and a next step, so the public screens that
// read those fields stop rendering blanks.
// The release edit route followed: the editor used to open below the release
// list, so editing meant scrolling past every release to reach it.
// 개념(CONCEPT) 문서 종류가 `/concepts/:slug` 를 더했다 — 설치된 라우트마다 수동 접근성 증거를
// 하나씩 갖는 규칙이 그대로 적용된다.
// 주제(Topic) 화면 셋이 뒤를 이었다: 목록 `/topics`, 축 상세 `/topics/:slug/:variant`,
// 그리고 Studio 의 주제 편집 `/studio/topics/:id`.
// 환경 구성(SETUP) 문서 종류가 `/setups/:slug` 를 더했다 — 설치된 라우트마다 수동 접근성
// 증거를 하나씩 갖는 규칙이 그대로 적용된다.
// Template sync (ebea300). The template's own baseline was 109 artifacts;
// this product's was 139. Recomputed from the merged config/ci/gates.json.
if (contract.artifacts.length !== 141) {
failures.push(`artifact authority baseline must contain exactly 141 artifacts; received ${contract.artifacts.length}`);
}
if (contract.stages.length !== 5) {
failures.push(`stage authority baseline must contain exactly 5 stages; received ${contract.stages.length}`);
const baseline = parsed.data;
const drift = Object.entries(measureCiContractBaseline(contract))
.filter(([key, value]) => baseline[key as keyof CiContractBaseline] !== value)
.map(([key, value]) =>
`${key}: baseline ${String(baseline[key as keyof CiContractBaseline])}, contract ${String(value)}`
);
if (drift.length > 0) {
throw new TypeError(
`CI gate contract does not match ${CI_CONTRACT_BASELINE_PATH}:\n${drift.join("\n")}\n` +
"If the change is intended, review it and run " +
"CI_CONTRACT_BASELINE_OWNER=<team> CI_CONTRACT_BASELINE_REASON=<why> corepack pnpm update:ci-contract-baseline",
);
}
}
function retentionRegistryFailures(contract: CiGateContract): string[] {
const expectedRetentionClasses = [
{ id: "merge-cycle", policy: "at least through pull-request readiness decision" },
{ id: "release-coherence", policy: "at least until the next release is promoted" },
@@ -571,16 +552,12 @@ function canonicalAuthorityBaselineFailures(contract: CiGateContract): string[]
{ id: "field", policy: "through the 28-day window and aggregation" },
{ id: "documentation", policy: "through documentation readiness review" },
];
if (JSON.stringify(contract.retention.classes) !== JSON.stringify(expectedRetentionClasses)) {
failures.push("retention registry must contain exactly the five canonical retention classes");
}
return failures;
return JSON.stringify(contract.retention.classes) === JSON.stringify(expectedRetentionClasses)
? []
: ["retention registry must contain exactly the five canonical retention classes"];
}
export function parseCiGateContract(
value: unknown,
options: LoadCiGateContractOptions = {},
): CiGateContract {
export function parseCiGateContract(value: unknown): CiGateContract {
const result = ciGateContractSchema.safeParse(value);
if (!result.success) {
const diagnostic = result.error.issues
@@ -588,49 +565,21 @@ export function parseCiGateContract(
.join("\n");
throw new TypeError(`CI gate contract invalid:\n${diagnostic}`);
}
if ((options.mode ?? defaultCiContractMode()) === "canonical") {
const failures = canonicalAuthorityBaselineFailures(result.data);
if (failures.length > 0) {
throw new TypeError(`CI gate contract invalid:\n${failures.map((failure) => `root: ${failure}`).join("\n")}`);
}
const failures = retentionRegistryFailures(result.data);
if (failures.length > 0) {
throw new TypeError(`CI gate contract invalid:\n${failures.map((failure) => `root: ${failure}`).join("\n")}`);
}
return result.data;
}
/**
* A removal fixture runs the whole suite against a deliberately *reduced* CI
* contract: the removed capability's gates, commands and artifacts are pruned.
* Loading that contract in canonical mode re-imposes the full exact-count
* authority on it, so the fixture failed on the very reduction it exists to
* prove. `runRemovalFixturePnpm` marks those runs, and this is where the mark
* is honoured.
*/
export function defaultCiContractMode(): "canonical" | "removal-fixture" {
return process.env.CI_CONTRACT_MODE === "removal-fixture"
? "removal-fixture"
: "canonical";
}
export function isReducedCiContractRun(): boolean {
return defaultCiContractMode() === "removal-fixture";
}
export async function loadCiGateContract(
root = process.cwd(),
options: LoadCiGateContractOptions = {},
): Promise<CiGateContract> {
const mode = options.mode ?? defaultCiContractMode();
const [rawContract, rawPackage] = await Promise.all([
readFile(path.join(root, "config/ci/gates.json"), "utf8"),
readFile(path.join(root, "package.json"), "utf8"),
]);
const contract = parseCiGateContract(JSON.parse(rawContract), { mode });
if (
mode === "canonical" &&
canonicalGateShapeSha256(contract.gates) !== CANONICAL_GATE_SHAPE_SHA256
) {
throw new TypeError("CI gate contract canonical gate semantic shape drift");
}
const contract = parseCiGateContract(JSON.parse(rawContract));
const packageDocument = z
.object({ scripts: z.record(z.string(), z.string()).default({}) })
.passthrough()
@@ -642,17 +591,17 @@ export async function loadCiGateContract(
if (missing.length > 0) {
throw new TypeError(`CI gate contract missing package scripts: ${missing.join(", ")}`);
}
const expectedCheckCi = mode === "canonical"
? "corepack pnpm check:artifact-schemas && node scripts/check-ci-contract.ts && corepack pnpm check:ci-workflow"
: "corepack pnpm check:artifact-schemas && node scripts/check-ci-contract.ts --reduced-removal-fixture && corepack pnpm check:ci-workflow";
const expectedCheckCi =
"corepack pnpm check:artifact-schemas && node scripts/check-ci-contract.ts && corepack pnpm check:ci-workflow";
if (packageDocument.scripts["check:ci"] !== expectedCheckCi) {
throw new TypeError("check:ci must use the exact canonical non-recursive orchestration");
}
const canonicalCheckCiDependencies = {
"check:artifact-schemas": "node scripts/generate-artifact-schemas.ts --check",
"check:ci-workflow": mode === "canonical"
? "node scripts/generate-ci-workflow.ts --check"
: "node scripts/generate-ci-workflow.ts --check --reduced-removal-fixture",
// R-0. The schema generator imports src, which loads the gitignored
// product index, so the index is rendered first.
"check:artifact-schemas":
"node scripts/generate-product-feature-index.ts && node scripts/generate-artifact-schemas.ts --check",
"check:ci-workflow": "node scripts/generate-ci-workflow.ts --check",
} as const;
for (const [script, expected] of Object.entries(canonicalCheckCiDependencies)) {
if (packageDocument.scripts[script] !== expected) {
@@ -682,6 +631,7 @@ export async function loadCiGateContract(
`CI package script install policy invalid:\n${installPolicyFailures.join("\n")}`,
);
}
await assertCiContractBaseline(root, contract);
return contract;
}
@@ -819,15 +769,17 @@ function validateContractSemantics(
}
}
// Template sync (af3d8e6). The signed manual review moved from FE-GATE-009
// to release gate FE-GATE-028 upstream (08-06); the one-artifact-per-route
// rule this product pins moved with it.
const accessibilityGate = contract.gates.find(
({ id: gateId }) => gateId === "FE-GATE-009",
({ id: gateId }) => gateId === "FE-GATE-028",
);
const manualAccessibilityArtifacts = MANUAL_A11Y_ROUTE_IDS.map((routeId) => ({
id: `artifact-artifacts-tests-a11y-manual-${routeId.replaceAll("_", "-")}-md`,
path: `artifacts/tests/a11y-manual/${routeId}.md`,
}));
const expectedAccessibilityEvidenceArtifactIds = [
"artifact-artifacts-tests-a11y-json",
...manualAccessibilityArtifacts.map(({ id: artifactId }) => artifactId),
"artifact-artifacts-tests-a11y-manual-report-json",
];
@@ -837,7 +789,7 @@ function validateContractSemantics(
JSON.stringify(expectedAccessibilityEvidenceArtifactIds)
) {
issue(
"FE-GATE-009 manual accessibility evidence must exactly match the installed route scope",
"FE-GATE-028 manual accessibility evidence must exactly match the installed route scope",
);
}
for (const expected of manualAccessibilityArtifacts) {
@@ -851,7 +803,7 @@ function validateContractSemantics(
artifact.production !== "source-controlled"
) {
issue(
`FE-GATE-009 manual accessibility artifact registration is invalid: ${expected.id}`,
`FE-GATE-028 manual accessibility artifact registration is invalid: ${expected.id}`,
);
}
}
@@ -891,12 +843,9 @@ function validateContractSemantics(
issue(`stage dependency cycle: ${cycle.join(" -> ")}`);
}
const expectedGateIds = Array.from(
{ length: 27 },
(_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`,
);
const expectedGateIds = CANONICAL_GATE_IDS;
if (JSON.stringify(contract.gates.map(({ id }) => id)) !== JSON.stringify(expectedGateIds)) {
issue("gate registry must contain FE-GATE-001..027 in canonical order");
issue(`gate registry must contain FE-GATE-001..028 without retired ${RETIRED_GATE_IDS.join(", ")} in canonical order`);
}
const expectedStages: ReadonlyArray<readonly [string, string, readonly string[], readonly string[]]> = [
["merge", "MERGE_READY", [], PROMOTION_FORMULA.MERGE_READY],
@@ -966,12 +915,12 @@ function validateContractSemantics(
}
const expectedJobOwnership: Readonly<Record<string, readonly string[]>> = {
merge_gate: ["FE-GATE-001", "FE-GATE-002", "FE-GATE-003", "FE-GATE-004", "FE-GATE-005", "FE-GATE-006", "FE-GATE-007", "FE-GATE-008", "FE-GATE-009", "FE-GATE-010", "FE-GATE-011", "FE-GATE-013", "FE-GATE-020"],
release_gate: ["FE-GATE-012", "FE-GATE-014", "FE-GATE-019", "FE-GATE-026"],
release_gate: ["FE-GATE-012", "FE-GATE-014", "FE-GATE-026", "FE-GATE-028"],
immutable_build: ["FE-GATE-015", "FE-GATE-027"],
vulnerability_provider: [],
provenance_provider: [],
promotion: [],
production_gate: ["FE-GATE-016", "FE-GATE-021", "FE-GATE-022", "FE-GATE-023", "FE-GATE-024", "FE-GATE-025"],
production_gate: ["FE-GATE-019", "FE-GATE-021", "FE-GATE-022", "FE-GATE-023", "FE-GATE-024", "FE-GATE-025"],
field_gate: ["FE-GATE-018"],
documentation_gate: ["FE-GATE-017"],
};
@@ -991,7 +940,7 @@ function validateContractSemantics(
vulnerability_provider: ["provider", ["immutable_build"], "always"],
provenance_provider: ["provider", ["immutable_build"], "always"],
promotion: ["promotion", ["immutable_build", "vulnerability_provider", "provenance_provider"], "needs-success"],
production_gate: ["gate-matrix", ["promotion"], "production"],
production_gate: ["gate-matrix", ["immutable_build", "promotion"], "production"],
field_gate: ["gate-single", ["production_gate"], "field"],
documentation_gate: ["gate-single", [], "documentation"],
};
@@ -1008,7 +957,7 @@ function validateContractSemantics(
vulnerability_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"],
provenance_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"],
promotion: ["checkout", "setup-node", "frozen-install", "download", "download", "download", "verify-promotion", "upload", "cleanup-promotion"],
production_gate: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
production_gate: ["checkout", "setup-node", "frozen-install", "download", "extract", "run-gate", "upload"],
field_gate: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
documentation_gate: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"],
};
@@ -1020,7 +969,7 @@ function validateContractSemantics(
}
const expectedEnvironmentBindings: Readonly<Record<string, readonly Readonly<{ name: string; value: string }> []>> = {
merge_gate: [],
release_gate: [{ name: "HOSTING_BASE_URL", value: "${{ vars.HOSTING_BASE_URL }}" }],
release_gate: [],
immutable_build: [
// FE-GATE-027 admits the built artifact to a named environment, so both
// the profile it was built from and the destination it is claimed for are
@@ -1066,7 +1015,14 @@ function validateContractSemantics(
{ name: "VULNERABILITY_INVOCATION_NONCE", value: "${{ needs.vulnerability_provider.outputs.invocation_nonce }}" },
{ name: "PROVENANCE_INVOCATION_NONCE", value: "${{ needs.provenance_provider.outputs.invocation_nonce }}" },
],
production_gate: [],
// 13-05: FE-GATE-019 probes the promoted release after the provider has
// deployed it, so the live base URL belongs to the production stage.
// 13-03: the drills extract the promoted archive and check it against the
// digest immutable_build recorded.
production_gate: [
{ name: "HOSTING_BASE_URL", value: "${{ vars.HOSTING_BASE_URL }}" },
{ name: "CANDIDATE_ARCHIVE_SHA256", value: "${{ needs.immutable_build.outputs.archive_sha256 }}" },
],
field_gate: [
{ name: "FIELD_WEB_VITALS_INPUT", value: "${{ vars.FIELD_WEB_VITALS_INPUT }}" },
{ name: "MIN_ELIGIBLE_SAMPLES", value: "${{ vars.MIN_ELIGIBLE_SAMPLES }}" },
@@ -1261,6 +1217,38 @@ function validateCanonicalStepFields(
) {
issue("promotion download fields and finalizer/cleanup step identities must remain linked");
}
// 13-03: the production stage drills the promoted archive it downloads. It
// used to rebuild from source, so the drilled bytes were not the release.
const production = contract.jobs.find(({ id }) => id === "production_gate");
const promotedDownload = production?.steps.find(
(step) => step.kind === "download" && step.transferId === "promoted-release",
);
const promotedExtract = production?.steps.find(({ kind }) => kind === "extract");
if (
!production ||
promotedDownload?.kind !== "download" ||
promotedExtract?.kind !== "extract" ||
promotedExtract.archivePath !== `${promotedDownload.path}/release-candidate.tar.gz`
) {
issue("production_gate must download the promoted release and extract its release-candidate.tar.gz");
} else {
for (const gateId of production.gateIds) {
const commands = (contract.gates.find(({ id }) => id === gateId)?.commandIds ?? [])
.map((commandId) => contract.commands.find(({ id }) => id === commandId));
if (!commands.some((command) => command?.script === "drill:runbook")) continue;
if (commands.some((command) => command?.script !== "drill:runbook")) {
issue(`production drill gate must drill the promoted archive only, without rebuilding: ${gateId}`);
}
for (const command of commands) {
const args = command?.args ?? [];
const releaseRoot = args.indexOf("--release-root");
if (releaseRoot < 0 || args[releaseRoot + 1] !== promotedExtract.targetRoot) {
issue(`production drill must pass --release-root ${promotedExtract.targetRoot} (the promoted archive): ${command?.id ?? gateId}`);
}
}
}
}
}
function validateJobStepKinds(
@@ -1268,7 +1256,7 @@ function validateJobStepKinds(
issue: (message: string, path?: PropertyKey[]) => void,
): void {
const allowed: Readonly<Record<z.infer<typeof jobSchema>["kind"], ReadonlySet<string>>> = {
"gate-matrix": new Set(["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"]),
"gate-matrix": new Set(["checkout", "setup-node", "frozen-install", "browser-install", "download", "extract", "run-gate", "upload"]),
"gate-single": new Set(["checkout", "setup-node", "frozen-install", "run-gate", "upload"]),
immutable: new Set(["checkout", "setup-node", "frozen-install", "run-gate", "archive-candidate", "upload"]),
provider: new Set(["checkout", "setup-node", "frozen-install", "download", "extract", "run-provider", "validate-provider-evidence", "upload"]),

Some files were not shown because too many files have changed in this diff Show More