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 at8210d48. 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 at8210d48first 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)
7.6 KiB
Starter experience contract
The repository provides a runnable, domain-neutral application rather than only infrastructure contracts. The starter experience is intentionally replaceable at the page level while the shell, providers, boundaries, primitives, and state surfaces remain reusable.
Runtime composition
validated config + coherent release manifest
-> concrete adapters
-> QueryClientProvider
-> ApplicationProvider
-> RouterProvider
-> ThemeProvider
-> SessionProvider
-> AppShell
-> lazy route boundary
Boot stops before product mount when configuration or release coherence fails. Each lazy page renders inside Suspense and a telemetry-aware route boundary. Route changes move focus to the new page heading; the skip link and landmarks remain stable in the shell.
Registered routes
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
authorization.
Authentication seam
The session port exposes state subscription, sign-in start, sign-out, credential attachment, recovery, and unauthenticated notification. Credentials remain opaque to the application and presentation layers.
demo: local/development-only state transition with no credentialsexternal: delegates toglobalThis.__CA_FRONTEND_AUTH_OWNER__- missing/invalid external owner: fails closed as
integration-failed
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
subclaim, Supabasesession.user.id, or Firebaseuser.uid nullwhen 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
New platform work should follow routing, page templates, and reusable patterns and the TypeScript, state, and data-flow target rather than adding another independent route or data-loading convention.
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 nofeature-module.tsand noNOT_INSTALLEDmarker file (src/features/local-draft-feature/NOT_INSTALLEDis 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_FEATURESnames a feature the app does not declare. The variable narrows the installed set here, before anything is compiled.
Adding a feature
- Create
src/features/<feature>/feature-module.ts. BuildFEATURE_MODULEwithdefineFeatureModule(src/features/feature-module.ts): the feature's contract (routes, route runtime contracts, API operations, invalidation, schemas, runtime schemas, mappers), its adapter contributions (defineFeatureAdapterContribution, withneedsnaming the platform capabilities it receives), its runtime descriptor (route codecs), its message catalogs and its contract contributions.src/features/reference-feature/feature-module.tsis the complete example. - Create
src/features/<feature>/context-routes.tsexportingFEATURE_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). - Name the owning context in
FEATURE_CONTEXT_ID. Use an existing context or addsrc/contexts/<context>/context-module.tsowned by the app. - If the feature has application input, augment
ApplicationFeatureInputsfrom the feature (src/features/local-draft-feature/application/local-draft-api.ts). - Run
corepack pnpm check:architecture,corepack pnpm check:types,corepack pnpm check:registriesand the tests.tests/unit/two-feature-install-typecheck.test.tskeeps the installed catalogs compiling with more than one feature. - 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.