Files
tech-log-frontend/docs/architecture/contract-ownership.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

111 lines
4.2 KiB
Markdown

# Contract ownership
`src/contracts` is not a default destination for every shared-looking type.
A contract belongs there only when the change authority is genuinely shared
across layers, capabilities, build tooling, or runtime composition.
## Decision rule
For every proposed contract, ask:
1. Which requirement can cause this type or policy to change?
2. Is there one clear capability or feature owner?
3. Does another runtime/tooling boundary consume the same semantic contract?
4. Is the contract a wire/artifact authority shared by browser runtime and
build/release tooling?
The placement rule is:
- one feature owner -> keep it under that feature,
- one reusable capability owner -> keep it under that adapter/capability and
export it through the capability public entry point,
- multiple independent capability/layer owners -> `src/contracts`,
- browser/build/release wire or artifact authority -> `src/contracts` even
when the browser source graph alone looks small.
Consumer count alone is not sufficient. Scripts, generated artifacts and
release gates are semantic consumers too.
## Audit result
The September 2026 architecture review triggered an import-graph audit of all
39 contract files.
### Capability-owned contract moved
`cursor-pagination.ts` had one production owner:
`src/adapters/query-cache/cursor-pagination-runtime.ts`.
It moved to:
`src/adapters/query-cache/cursor-pagination-contract.ts`
and is exported through:
`src/adapters/query-cache/index.ts`
Tests use that public capability entry point. Pagination vocabulary no longer
occupies the global contract bucket merely because it is reusable inside one
adapter.
### Contracts intentionally kept global
The following examples have multiple semantic owners and remain global:
- `errors.ts` — application, presentation and several adapters,
- `result.ts` — common success/failure carrier below application,
- `boundary-mapper.ts` — HTTP, browser RPC, realtime and feature registries,
- `mutation-intent.ts` — application, presentation, HTTP, platform and
bootstrap,
- `exact-snapshot.ts` — HTTP, query-cache and browser-transfer,
- `rest-profiles.ts` — auth, HTTP, bootstrap and feature contract validation,
- `query-invalidation.ts` / `query-keys.ts` — query-cache, presentation,
bootstrap and features,
- `cache-invalidation.ts` — cross-context wire protocol plus query
invalidation policy,
- `storage-keys.ts` — browser storage and cross-context invalidation,
- `telemetry.ts` / `diagnostics.ts` — runtime adapters, application and
bootstrap.
Some contracts appear to have few browser-source consumers but are still shared
authorities:
- `env.ts` is consumed by bootstrap, runtime-schema/security tests and
registry governance,
- `deployment-admission.ts` is shared by runtime-config generation and release
admission,
- `release-tokens.ts` is shared by runtime coherence tooling and tests,
- `service-worker-static-manifest.ts` is a runtime-neutral canonical format
shared by build generation, validation and service-worker evidence.
Moving those based only on `src/**` import counts would split one semantic
authority across processes.
## Feature contracts
Feature-specific contracts stay inside the vertical slice:
`features/<feature>/contracts`
The reference feature owns routes, schemas, mapper definitions, message
catalogs and contribution identities. Central installed files aggregate those
contributions; they do not own their semantics.
The message catalog is a deliberate special case: the compiled catalog remains
total even when a feature is build-time disabled so the typed message lookup
does not become partial. The central message file therefore aggregates compiled
message keys rather than treating runtime installation as message ownership.
## Review rule for future additions
A new file under `src/contracts` should be rejected during review when all of
the following are true:
- one feature or one capability is the only semantic owner,
- no build/release/runtime wire authority needs the same definition,
- moving the definition to that owner does not create an inward dependency
violation.
Do not move a contract merely to reduce the number 39. The goal is explicit
ownership, not a smaller directory.