Files
clean-architecture-frontend…/docs/architecture/capability-consumer-experience.md
T
DongHyeonka e3c8db48ae chore(features): 참조 기능과 예제 화면을 지우고 레지스트리를 다시 승인한다
소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.4절)으로
템플릿 샘플을 지운다. 샘플이 맡던 시험 대상은 앞 커밋들이 옮겼다.

참조 기능과 예제 화면, 두 context, 그 시험, e2e 3개, 수동 접근성 기록
7개, 런타임 프로필 키, test:reference-feature(명령, 산출물, 게이트
참조), 커버리지 정책 행을 지웠다. removable-template-features 목록은
비우고 장치는 남겼다: test:sample-removal은 인자가 없으면 목록을
하나씩 지우고, 비면 SKIP을 출력하고 보고서에 건너뛴 사례를 남긴다.
기능 스위치 시험과 홈 시작 링크 스위치 시험은 시험 전용 fixture 기능으로
옮겼다. browser soak은 생성 기능을 넣은 빌드에서 돈다. 문서의 샘플
경로를 고쳤다. 날짜가 붙은 설계·리뷰 기록의 본문은 그대로 두었다.
레지스트리 기준선(update:registry-baseline, OWNER DongHyeonka), CI 계약
기준선과 workflow, 초기 JS 기록(194,354B, 17파일, 첫 기능 6,327B, 기능
539B, context 4B)을 다시 받았다.

위험: 레지스트리 행 삭제는 breaking이다. 샘플을 고쳐 쓰는 다운스트림은
수정/삭제 충돌을 만난다. 성능 lab의 기능 라우트 측정은 템플릿에
공개 기능 라우트가 없어 measured:false다. TEMPLATE_FIXTURE 출처는
플랫폼 코드에 남았다.

검증(desktop): check:types, lint, check:architecture, check:registries,
check:ci, verify:documentation, test:unit, test:component,
test:contract, test:integration, test:recipes, test:coverage(Risk
coverage PASS 378/378, 문턱 68개), test:e2e 183, test:a11y, test:visual,
test:storybook, test:browser-capabilities, test:feature-scaffold PASS(76
checks), test:sample-removal SKIP, build, check:bundle.
2026-11-08 14:07:58 +09:00

158 lines
6.3 KiB
Markdown

# Capability consumer experience baseline
Correctness inside a reusable capability is not sufficient. The platform is
also evaluated by how much of that correctness a normal feature developer must
understand.
These measurements are baselines, not score targets. A lower line count is not
automatically better if it hides business semantics or creates a universal
repository abstraction.
## Scenario A — a REST feature
The REST consumer is the feature `corepack pnpm create:feature <id> --with-create`
writes (the template's reference sample had this role until 2026-11-07).
It covers list/detail/create behavior, mapping, typed operation inputs and
application ports.
The feature-owned boundary and application source is these four files:
- `application/<base>-feature-api.ts`
- `contracts/<base>-mapper.ts`
- `adapters/<base>-http-gateway.ts`
- `adapters/create-<base>-feature-input.ts`
This document does not keep their line counts; a hand-typed count drifted
from the code (review 14-07). Measure them in a generated feature with
`wc -l` on those four files.
The important boundary metric is not the raw total. It is what those files need
to know about the platform.
Current result:
- HTTP platform imports in the feature adapter layer: 2 files,
- canonical import path used by both:
`src/adapters/http/index.ts`,
- direct imports of `http-execution-v3.ts`, retry scheduler, response reader,
auth admission or effect-certainty internals: 0,
- feature gateway owns transport failure projection: 0,
- feature gateway chooses operation ID, route ID, exact input/value type and
mapper: yes,
- central installed files own feature-specific adapter/runtime wiring: no;
feature-owned contributions are aggregated centrally.
The reusable HTTP capability now owns execution-outcome normalization through
`createFeatureHttpBinding`. A feature may still implement a custom outbound
adapter behind its application port when the reusable contract does not match
its business requirement.
## Scenario B — IndexedDB local draft
The executable consumer probe is:
`tests/contract/consumer-experience/indexeddb-local-draft.test.ts`
It runs and reads the one Local Draft implementation, the test fixture
`tests/fixtures/indexeddb-consumer` (the template's former local-draft sample
under `src/features/`, moved there because it is no product feature). An
earlier isolated copy had drifted from it and was removed (09-12).
The consumer owns the Local Draft domain/application API and declares the slice
of the repository it calls (`LocalDraftRepository` in
`tests/fixtures/indexeddb-consumer/adapters/local-draft-indexeddb-store.ts`). The
host hands in an `IndexedDbRepositoryPort<LocalDraft, never>` through the
`indexedDb` capability; the port satisfies that slice structurally. The
cross-capability composition contract lives at:
`tests/contract/reusable-capability/feature-adapter-composition.test.ts`
That test composes one HTTP-only contribution and the IndexedDB-only Local Draft
contribution through the same generic catalog path.
The browser-level composition proof lives at:
`tests/browser-capabilities/local-draft-composition.spec.ts`
It runs against native browser IndexedDB. The test creates the platform
`createIndexedDbRuntime`, exposes that runtime through the typed
`createIndexedDbRepositoryProvider`, composes
`LOCAL_DRAFT_FEATURE_ADAPTER_CONTRIBUTION`, then executes Local Draft
save/find/remove through the feature API. The Local Draft feature still does
not import the IndexedDB runtime or native browser API.
Measured on the Local Draft consumer, then under `src/features/` (09-12):
| Metric | Result |
| --- | ---: |
| feature LOC (all `.ts` files) | 295 |
| import statements leaving the feature (`contracts/errors`, `contracts/result`, `application-api`, `feature-adapter-contribution`) | 7 |
| native IndexedDB API references | 0 |
| `src/adapters/storage/indexeddb/**` imports | 0 |
| `src/application/ports/browser-file-storage/**` imports | 0 |
The feature does not import the storage runtime or its port, so removing the
browser file/storage runtime (`test:browser-file-storage-removal`) leaves it
compiling.
The contract test rejects feature source that reaches for
`globalThis.indexedDB`, `IDBFactory`, `IDBDatabase`, `IDBTransaction`,
`IDBObjectStore`, the concrete IndexedDB adapter directory or the
browser-file-storage port.
## What this does and does not prove
The contract probe confirms that **feature business code does not need native
IndexedDB knowledge** once an `IndexedDbRepositoryPort` has been composed.
The browser-capability proof additionally confirms that the same feature
contribution works when that port is backed by the repository's real
`createIndexedDbRuntime` and native IndexedDB implementation.
It does not prove that composition of `createIndexedDbRuntime` is cheap.
That constructor still owns substantial infrastructure policy:
- dataset scope and storage policy,
- physical store governance,
- retention/idempotency stores,
- schema migrations,
- codec and query policy,
- lifecycle authority,
- durability, scheduling and observation.
That complexity belongs at the composition/platform boundary, not in the
feature. The Local Draft vertical slice is now the second concrete consumer, and
it confirms that the stable seam is the typed repository provider plus a
feature-owned repository identity. It does **not** show that dataset scope,
retention, migration, codec or lifecycle-authority configuration can be safely
collapsed into one universal `create...Repository<T>` factory.
A convenience profile should therefore be introduced only after another
IndexedDB-backed product feature repeats the same infrastructure policy, not
merely because two features consume the same repository port.
## Consumer-quality review checklist
For each new product feature, record:
- feature-owned adapter LOC,
- platform glue LOC,
- files changed,
- central catalog edits,
- direct imports from capability-internal modules,
- native browser/network API references,
- duplicated failure/retry/lifecycle policy.
A healthy feature path should look like:
1. domain type and invariant,
2. use case,
3. business port,
4. feature-owned mapper/codec and policy,
5. capability-specific binding,
6. presentation controller/page.
The feature should not need the retry scheduler, abort ownership,
effect-certainty machinery, IndexedDB transaction lifecycle, OPFS journal,
reconnect coordinator or provider process model.