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)
158 lines
7.6 KiB
Markdown
158 lines
7.6 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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 credentials
|
|
- `external`: delegates to `globalThis.__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 `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
|
|
|
|
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.
|
|
|
|
### 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.
|