Files
tech-log-frontend/docs/operations/template-sync-2026-09-21.md
T
DongHyeonkaandClaude Opus 5 afde2b1da1 chore: sync the frontend template from 5434760 to ebea300
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>
2026-09-21 16:31:05 +09:00

17 KiB
Raw Blame History

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.