Carries 21 template commits: the shared IndexedDB connection/transaction
kernel and the four runtimes moved onto it, the adapter barrel boundary and
the architecture rule that enforces it, the feature adapter contribution
model, `feature-http-binding`, the split of several oversized test files,
and the release identity now derived from the package name.
Product identity is unchanged. The three hard-coded `tech-log-frontend/…`
verifier ids are gone because the template derives them from the package
name and this package is `tech-log-frontend`.
Two decisions worth naming. The platform HTTP executor is the template's
verbatim — it now takes the installed contract so a feature's types flow
through the binding — and TechLog's four gateways, which address operations
by id, reach it through one adapter at the composition root instead of being
rewritten here. And the three derived CI baselines were recomputed from the
merged `config/ci/gates.json` rather than taken from either side: 94 command
definitions, 106 references, 141 artifacts, gate shape `629e5898…`. The
method was checked by first reproducing the pre-merge values from the
pre-merge file.
Verified here: types, lint, architecture, adapter inventory, CI contract,
design system, diagnostics, remediation ledger, browser security and build
all pass; 1789 unit, 152 component, 415 TechLog, 102 integration, 19
reference-feature, 17 recipe and 7 contract tests pass. Five gates stay
red and every one was reproduced at b297d65 first: `check:i18n`,
`check:registries`, `test:runtime-schema`, `verify:documentation` and
`test:sample-removal`.
Full decision record, including what was deliberately not carried and the
five open follow-ups, in `docs/operations/template-sync-2026-09-21.md`.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
316 lines
17 KiB
Markdown
316 lines
17 KiB
Markdown
# Template sync — `5434760` → `ebea300`
|
||
|
||
Record of how the frontend template's 21 pending commits were transplanted into
|
||
this product, and of every decision taken where the two trees disagreed.
|
||
|
||
## Starting state
|
||
|
||
| | |
|
||
| --- | --- |
|
||
| template pin before | `5434760` (`template.lock.json`) |
|
||
| template pin after | `ebea300` |
|
||
| template commits carried | 21 |
|
||
| template delta | 205 files, +22,729 / −9,969 |
|
||
| this product's divergence since the last sync | 618 files (`bdee07a..b297d65`) |
|
||
| files touched by both | 27 |
|
||
| applied to this product | 195 files, +21,527 / −9,980 |
|
||
|
||
Rollback ref created before touching anything:
|
||
|
||
```
|
||
backup/main-before-template-ebea300 → b297d65
|
||
```
|
||
|
||
The two histories share no commit — `git merge-base main template/main` is
|
||
empty — so this is a patch transplant, not a merge, the same way every previous
|
||
sync was. `template.lock.json` calls it `tracked-snapshot`; there is no sync
|
||
script.
|
||
|
||
### Pre-transplant baseline
|
||
|
||
Captured in a clean worktree at `b297d65` so a pre-existing failure could not be
|
||
mistaken for a transplant regression.
|
||
|
||
| Gate | Result |
|
||
| --- | --- |
|
||
| `check:types` | pass |
|
||
| `lint` | pass |
|
||
| `test:unit` | 1825 passed / 4 failed / 16 skipped |
|
||
| `test:component` | 152 passed |
|
||
| `test:tech-log` | 415 passed |
|
||
|
||
The four failures were `ci-artifact-contract` (2), `provider-guardian-transaction`
|
||
(1) and `removal-fixture` (1) — sandbox- and artifact-dependent checks that do
|
||
not run on this machine.
|
||
|
||
## What the template brought
|
||
|
||
| Group | Commits | Substance |
|
||
| --- | --- | --- |
|
||
| Frontend refactor | `ec7f20e` | Feature adapter contribution model, the `local-draft-feature` demonstration slice, a large set of typecheck fixtures, and several oversized test files split apart |
|
||
| Template refactor | `5cc4146` | `feature-http-binding`, reference feature restructured, `run-vitest.ts`, three new architecture documents |
|
||
| IndexedDB kernel | `cb62bfb` + 6 | A shared connection/transaction kernel; the OPFS journal, upload checkpoint store, maintenance and runtime moved onto it |
|
||
| Adapter barrel boundary | `b29a471` + 5 | A public `index.ts` per adapter group, enforced by the architecture gate |
|
||
| Other | `d777fb8`, `ebea300` | Abort-wiring ratchet; release identity derived from the package name |
|
||
|
||
## What was deliberately not carried
|
||
|
||
| Path | Why |
|
||
| --- | --- |
|
||
| `artifacts/tests/coverage-gateway/**` (10 files) | A coverage run the template committed by accident. Nothing outside `artifacts/` references it. |
|
||
| `docs/superpowers/specs/2026-09-20-memento-frontend-template-bootstrap-design.md` | A design for deriving a different product from the template. |
|
||
| `src/presentation/pages/home-page.tsx`, `src/presentation/examples/platform-overview-page.tsx`, `src/features/reference-feature/presentation/**` | Deleted by this product's UI migration. The template modified them; the deletions stand. |
|
||
|
||
## Conflicts and how each was decided
|
||
|
||
19 conflicts. The rule applied throughout is the one the previous sync wrote
|
||
down: **keep the template's mechanism, keep the product's content, and never
|
||
invent a third state that neither branch would accept.**
|
||
|
||
### The platform HTTP executor — `src/bootstrap/runtime-adapters.ts`
|
||
|
||
The substantive change of this sync. The template turned `contractOperations`
|
||
from a string-id executor into `InstalledHttpOperationExecutor`, which takes the
|
||
installed contract itself so a feature's Input/WireOutput/Problem types flow
|
||
through `createFeatureHttpBinding`.
|
||
|
||
TechLog's four HTTP gateways address operations by id through their own
|
||
`StudioOperationExecutor` — six call sites across
|
||
`http-studio-gateway.ts`, `http-studio-asset-gateway.ts`,
|
||
`http-management-gateway.ts` and `http-public-content-gateway.ts`. Porting them
|
||
onto the typed binding is a rewrite of TechLog's HTTP layer, and nothing about
|
||
that is decided here.
|
||
|
||
So the platform executor is the template's, verbatim, and the composition root
|
||
adapts it for TechLog: `techLogOperations` resolves the id against
|
||
`COMPOSED_CONTRACT_CONTRIBUTIONS.httpByOperationId` and delegates. The
|
||
resolution happens at the one place that already owns the registry rather than
|
||
inside the executor for every caller, and an unregistered id returns the same
|
||
`FINAL_REQUEST_INVARIANT_FAILED` violation on both paths.
|
||
|
||
The product's `let` + throwing-stub forward reference — which exists to break
|
||
the CSRF construction cycle, and which the file documents at length — moved to
|
||
`techLogOperations`, where the cycle actually is. `contractOperations` is now a
|
||
plain `const`.
|
||
|
||
The template's barrel imports were adopted; TechLog's imports were kept.
|
||
|
||
### `src/features/installed-feature-adapters.ts`
|
||
|
||
The template composes contributions through `composeFeatureAdapterInputs`,
|
||
selecting by `featureId` against the manifest. That mechanism is adopted.
|
||
|
||
TechLog is composed directly on top of it, and its input stays total, because
|
||
TechLog is this product's own domain rather than a `SelectableProductFeature` —
|
||
the same split the previous sync recorded, now expressed through the template's
|
||
mechanism instead of a hand-written ternary.
|
||
|
||
`InstalledFeatureInputs` became `Partial<ApplicationFeatureInputs>` upstream, so
|
||
the return type is that intersected with a total `Pick` of TechLog's entry.
|
||
|
||
### `src/features/installed-contract-contributions.ts`
|
||
|
||
Same shape. The manifest-governed contributions are filtered by their own
|
||
`featureId` — the template's improvement over this file naming the reference
|
||
feature — and TechLog's three contributions are appended unconditionally, where
|
||
the filter cannot drop them.
|
||
|
||
### `src/features/installed-feature-runtimes.tsx`
|
||
|
||
The template compiles the reference feature's runtime contribution here and
|
||
filters it through the manifest. This product deleted that feature's
|
||
presentation layer, so there is no contribution to compile and the import would
|
||
not resolve. Carrying an empty list plus the filter would be dead code neither
|
||
repository runs, so the previous sync's decision stands: the aggregation comes
|
||
back the day those screens do.
|
||
|
||
A second reason not to adopt it as written: the template's
|
||
`Object.assign(..., ...contributions.map(...))` widens both catalogs to `any`,
|
||
and this product's router resolves codecs and components by route id off them.
|
||
The object spread keeps them typed.
|
||
|
||
### `src/presentation/routes/app-router.tsx`, `src/presentation/layouts/app-shell.tsx`
|
||
|
||
The template split `useApplication()` into `useApplicationRuntime()`,
|
||
`useApplicationDiagnostics()` and `useApplicationRecovery()`. Adopted.
|
||
|
||
The template also added an `AppShell` import to the router; this product's
|
||
router never mounts it (the public site has its own header and the studio its
|
||
own shell), so the import was not carried — it would be dead.
|
||
|
||
### Release identity — `ebea300`
|
||
|
||
Three files hard-coded `tech-log-frontend/…` verifier ids because a previous
|
||
sync replaced the template's own hard-coded name. The template now derives them
|
||
from the package name. Taking the template's side produces the identical value
|
||
and removes the hard-coding: `scripts/generate-supply-chain.ts`,
|
||
`scripts/lib/local-release-evidence.ts`, `scripts/lib/provider-evidence.ts`.
|
||
|
||
### `package.json`
|
||
|
||
The template's mechanisms are kept — `node scripts/run-vitest.ts` in place of
|
||
bare `vitest`, the new `tests/contract` and `tests/system` suites, and the
|
||
typecheck fixtures moved onto per-fixture `tsconfig` files. This product's
|
||
entries are kept: `test:tech-log`, `check:tech-log-contract` in `test:all`, and
|
||
`tests/features/tech-log` in `test:coverage`.
|
||
|
||
### `tests/unit/security-followup.test.ts`
|
||
|
||
The template split this file into `security-followup-fixture.ts`,
|
||
`security-promotion-staging.test.ts` and `security-provider-evidence.test.ts`.
|
||
The product's only additions to it were the two hard-coded verifier ids (now
|
||
derived upstream) and `PROCESS_HEAVY_TIMEOUT_MS`, which the template's fixture
|
||
already carries. The file is byte-identical to the template's.
|
||
|
||
### `tests/component/router.test.tsx`
|
||
|
||
The template's hunk asserts `/examples/ui`, a screen this product deleted. The
|
||
product's Studio-layout assertions are kept.
|
||
|
||
### Derived baselines — recomputed, not chosen
|
||
|
||
`scripts/contracts/ci-gates.ts`, `tests/unit/ci-workflow-generation.test.ts` and
|
||
`tests/unit/task3-selective-integration.test.ts` pin counts and a digest
|
||
describing `config/ci/gates.json`. **Neither side's numbers describe the merged
|
||
file.** They were recomputed from it, and the method was checked by first
|
||
reproducing this product's pre-merge values from the pre-merge `gates.json`.
|
||
|
||
| Value | This product | The template | Merged |
|
||
| --- | --- | --- | --- |
|
||
| gates | 27 | 27 | 27 |
|
||
| command definitions | 85 | 91 | **94** |
|
||
| command references | 97 | 103 | **106** |
|
||
| commands expecting failure | 23 | 30 | **30** |
|
||
| evidence artifact references | 118 | 88 | **120** |
|
||
| artifacts | 139 | 109 | **141** |
|
||
| canonical gate shape SHA-256 | `8a1a5479…` | `43dc4ed1…` | **`629e5898f6a38d5056fc6a4bee834c47f363669ce9925a2c0dabeddd64d11879`** |
|
||
|
||
## Fixes the transplant required
|
||
|
||
### The adapter barrel boundary caught three TechLog files
|
||
|
||
`27ab17d` makes the architecture gate refuse an import that reaches past an
|
||
adapter group's barrel. Three TechLog files did:
|
||
`http-studio-gateway.ts` and `studio-error-mapping.ts` imported
|
||
`HttpExecutionOutcome` from `adapters/http/http-execution-v3.ts`, and
|
||
`studio-session-credentials.ts` imported `CredentialPatchOutcome` from
|
||
`adapters/http/http-contract-bridge.ts`. The barrel exports all three types;
|
||
the imports now go through it.
|
||
|
||
### A relative import went stale when a test moved
|
||
|
||
`tests/unit/ci-artifact-contract.test.ts` moved to
|
||
`tests/system/ci-runner/`. Its product-only import of
|
||
`scripts/lib/provider-sandbox-probe.ts` — a file the template does not have —
|
||
kept the old `../../` depth and had to become `../../../`.
|
||
|
||
### The remediation ledger pointed at files that had been split
|
||
|
||
`ec7f20e` split `presigned-transfer.test.ts`, `image-cdn-runtime.test.ts` and
|
||
`resumable-upload-runtime.test.ts`, moving the TR-02, TR-03 and TR-04 markers
|
||
into the new files, **but did not update
|
||
`docs/operations/adapter-remediation-dispositions.json`** — so
|
||
`check:remediation-ledger` is broken upstream as well. The three evidence paths
|
||
now name the files that actually carry the markers.
|
||
|
||
### `tests/features/tech-log/runtime-composition.test.ts`
|
||
|
||
Two changes. The composition call passes `http`, the platform capability the
|
||
manifest-governed contributions declare in `needs`.
|
||
|
||
And its type assertion no longer uses `keyof`. The composed map became
|
||
`Partial<ApplicationFeatureInputs>` and the template's new local-draft feature
|
||
declares a third key, so every declared feature is a key whether installed or
|
||
not. What the product needs held is the split itself, so the assertion is now
|
||
that the *required* keys are exactly `"tech-log"` and that `"reference-feature"`
|
||
is not among them.
|
||
|
||
## Gates on the transplanted tree
|
||
|
||
| Gate | Result |
|
||
| --- | --- |
|
||
| `check:types` | pass (6 projects) |
|
||
| `lint` | pass, `--max-warnings=0` |
|
||
| `check:architecture` | 490 modules, 1630 dependencies, 14 fixtures pass |
|
||
| `check:adapter-inventory` | 133 files, 9 importers of the shared abort primitive, 21/21 abort ratchet |
|
||
| `check:ci` | 27 gates, artifact schemas and generated workflow pass |
|
||
| `check:design-system` | 48 tokens |
|
||
| `check:diagnostics` | 8 diagnostics, 5 telemetry producers |
|
||
| `check:remediation-ledger` | 25 dispositions, 0 open |
|
||
| `check:browser-security` | pass |
|
||
| `build` | pass |
|
||
| `test:unit` | 1789 passed in the working checkout; 1788 passed / 1 failed in the fresh worktree, where `removal-fixture` has no evidence tree to read |
|
||
| `test:component` | 152 passed |
|
||
| `test:tech-log` | 415 passed |
|
||
| `test:contract` | 7 passed (new suite) |
|
||
| `test:integration` | 102 passed |
|
||
| `test:reference-feature` | 19 passed |
|
||
| `test:recipes` | 17 passed |
|
||
| `test:runtime-schema` | 44 passed / 1 failed |
|
||
|
||
Two of the pre-transplant failures disappeared because the template moved those
|
||
files out of `tests/unit`: `provider-guardian-transaction` now passes inside
|
||
`test:integration`, and `ci-artifact-contract` moved to `tests/system`, which
|
||
`test:all` does not run.
|
||
|
||
## Failures this sync did not cause, and did not fix
|
||
|
||
Each was reproduced at `b297d65` in a separate worktree before being classified.
|
||
|
||
| Gate | State |
|
||
| --- | --- |
|
||
| `check:i18n` | Fails at `b297d65` identically. Its rule is `/[가-힣]/` over whole files in `src/presentation/**`, so the Korean comment block in `app-shell.tsx:181` trips it. The gate matches comments, not just user-facing literals. |
|
||
| `check:registries` | Fails at `b297d65` with byte-identical output: `TechLogTopicVariantParams`, `TechLogStudioDocumentsSearch` and `TechLogStudioPublicationsSearch` are referenced by routes but absent from the schema registry, plus six breaking changes without evidence. |
|
||
| `test:runtime-schema` | Fails at `b297d65`: the vendored TechLog Studio contract is at `3.1.0` and `release-manifest.test.ts:117` still expects `3.0.0`. |
|
||
| `tests/unit/removal-fixture.test.ts` | Only fails in a fresh worktree, which has no release evidence artifacts. In the working checkout `test:unit` is 1789/1789. |
|
||
| `verify:documentation` | `FAIL_UNVERIFIED` at `b297d65` and after, in both a fresh worktree and the working checkout. `reportDigestValid` is true and both ledger results pass; the single cause is `routeScopeDocumented: false`. Ten TechLog routes — `TECH_LOG_CONCEPT`, `TECH_LOG_SETUP`, `TECH_LOG_STUDIO_ASSETS`, `TECH_LOG_STUDIO_PROJECT_EDIT`, `TECH_LOG_STUDIO_RELEASES`, `TECH_LOG_STUDIO_RELEASE_EDIT`, `TECH_LOG_STUDIO_TAXONOMY`, `TECH_LOG_STUDIO_TOPIC_EDIT`, `TECH_LOG_TOPICS`, `TECH_LOG_TOPIC_VARIANT` — shipped without being added to `README.md` or `docs/accessibility/manual-checklist.md`, and the gate requires both to name every installed route id. Adding them to the checklist means writing a manual accessibility check per route, which is product work, not a transcription. |
|
||
|
||
### `test:sample-removal` (FE-GATE-020)
|
||
|
||
Broken before this sync — at `b297d65` the fixture's `vite build` fails outright,
|
||
so the gate never reaches its checks. After the transplant the fixture builds and
|
||
reports four named failures:
|
||
|
||
| Check | Cause |
|
||
| --- | --- |
|
||
| `registry-structure` | The pre-existing registry defect above. `check:registries:structure` fails on the ordinary tree too, so this can never pass until that is fixed. |
|
||
| `typecheck` | `tests/features/tech-log/http-studio-gateway.test.ts` imports `tests/mocks/handlers/tech-log-studio.ts`, and `tests/mocks` is deleted whole as feature-owned. Pre-existing coupling in files this sync did not touch. |
|
||
| `unit-integration`, `coverage` | Downstream of that typecheck failure. |
|
||
|
||
Three of its checks were repaired along the way, because the transplant is what
|
||
made them visible:
|
||
|
||
- `common-test-evidence` — `tests/integration/http-execution-v3-observability.test.ts`
|
||
was in both `commonTestPaths` (must survive) and `featureOwnedPaths` (gets
|
||
deleted), so the check could never pass. The file names nothing of the
|
||
reference feature, so the `featureOwnedPaths` entry was stale and was removed.
|
||
- `fixture-id-residue` — `tests/features/tech-log/studio-csrf-composition.test.ts`
|
||
imports the reference feature's contract contribution on purpose: it proves a
|
||
403 on *another* feature's operation does not discard TechLog's CSRF token,
|
||
which needs a second feature to exist. With the feature gone the premise is
|
||
gone, so it is now feature-owned. The last residue was one comment in
|
||
`studio-session-credentials.ts` naming the feature by id; it now says "other
|
||
features'".
|
||
- The exclusion list still named `tests/unit/ci-artifact-contract.test.ts` at its
|
||
old path.
|
||
|
||
## Follow-ups this sync deliberately did not decide
|
||
|
||
1. **TechLog's HTTP gateways still address operations by id.** The typed
|
||
`createFeatureHttpBinding` path is what the template now expects of a feature;
|
||
TechLog reaches it through a shim at the composition root. Porting the four
|
||
gateways is its own change.
|
||
2. **The schema registry defect keeps two gates red.** `check:registries` and,
|
||
through it, `test:sample-removal` cannot pass until the three TechLog schema
|
||
ids are registered and the six breaking changes carry evidence.
|
||
3. **`tests/mocks` is feature-owned but TechLog imports it.** Either the TechLog
|
||
handlers move out of `tests/mocks`, or the directory stops being deleted
|
||
wholesale.
|
||
4. **`check:i18n` cannot distinguish a comment from a user-facing literal.**
|
||
Either the rule scans string literals and JSX text, or product comments stop
|
||
being written in Korean. Today the gate is simply red.
|
||
5. **The template's `local-draft-feature` is carried but not installed.** It is a
|
||
demonstration slice with its own IndexedDB store; nothing in this product
|
||
composes it. It declares a third `ApplicationFeatureInputs` key, which is why
|
||
the composition test's `keyof` assertion had to change.
|