chore: sync the frontend template from ebea300 to af3d8e6

Carries 359 template commits, tag v0.2.0 plus one documentation commit: the
generator-built feature index with its app, bounded-context and feature
declarations, the src/platform kernel and scale tooling, the 2026-09-24 src
review fixes, and the 2026-09-25 maturity review round with its CHANGELOG
[보안]/[계약] rows. 691 of the 824 template paths are applied, 85 of them
merged with product changes; 127 are not carried.

Product identity is unchanged: name, version 0.1.0, routes, design and the
TechLog domain.

Three decisions worth naming. TechLog stays composed directly, as the last
two syncs recorded; its directory carries a NOT_INSTALLED marker that says so,
and every installed-* composer takes the template's projection with TechLog
added on top. The reference sample is no longer installed: the template now
installs a feature only through feature-module.ts and context-routes.ts,
which load the screens this product deleted, so its three operations, six
schemas and one topic leave the registries, recorded as registry change
evidence. And AppRouter mounts the platform and TechLog routes only; the
template's bounded-context route gateway waits for a generator-installed
feature.

Required fixes: readSubject on the BFF session owner (without it every HTTP
Studio session would close as integration-failed), zod through the facade in
nine TechLog files, noUnusedLocals, and public/config.json written out to
match the local profile. Derived baselines were recomputed after reproducing
both sides' values: CI contract 101 commands / 106 references / 141
artifacts, gate shape c9adcf85; registry approval 2dc6c3a3; the runtime
config schema baseline equals the schema at 8210d48.

Verified here: types, lint, architecture, adapter inventory, CI contract,
i18n, design system, diagnostics, browser security, dev release manifest,
TechLog contract and build pass; 220 component, 155 integration, 15
contract, 418 TechLog, 43 reference-feature, 18 recipe and 46
release-coherence tests pass, and 2381 of 2383 unit tests. Reproduced at
8210d48 first and unchanged: check:registries (byte-identical),
test:runtime-schema, verify:documentation. Brought by the template and
escalated rather than suppressed: check:request-fanout on TechLog's cursor
pagination, check:remediation-ledger (fails upstream too), the shared-chunk
hash test, and the registry-dependent sample removal and second-feature
tests. Playwright suites were not run.

Full record, the five open questions and the follow-ups in
docs/operations/template-sync-2026-09-29.md.

(cherry picked from commit b2170cf265dea45dc9cc05d3c61e627e97f31cdb)
This commit is contained in:
DongHyeonka
2026-11-12 08:28:54 +09:00
parent 585c62431a
commit c80320dfc7
738 changed files with 55027 additions and 13567 deletions
@@ -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.