diff --git a/config/contracts/registry-baseline.approval.json b/config/contracts/registry-baseline.approval.json
index ea584524..7f1f1b88 100644
--- a/config/contracts/registry-baseline.approval.json
+++ b/config/contracts/registry-baseline.approval.json
@@ -1,7 +1,7 @@
{
"schemaVersion": 1,
- "snapshotDigest": "3c3702b55ad8849f399833206ea4515808eda6ab6d1fd5c49e90f8579e644170",
+ "snapshotDigest": "16f727424579279e0ef810620f672a8a9d74de6b71e3e9ce37ab07a82f645588",
"owner": "DongHyeonka",
- "reason": "2026-11-03 사용자가 결정을 위임함: 0929/07-03, 1101/16-03, 15-01 source 경로. 승인 뒤 쌓인 0925/08-13·1101/05-01(증거로 유지), VITE_BUILD_ID 기본값·service-worker.start.failed 행(증거 불필요)도 함께 흡수",
- "approvedAt": "2026-11-02T15:53:54.852Z"
+ "reason": "2026-11-03 사용자 승인('둘 다 지워'): V2 API 행 제거. FE-REG-API 행은 V3 descriptor에서 뽑은 projection(operationId·featureId·method·path·authProfileId·retrySemantics·requestBody·responseBody·responseEnvelope·request/response/problemSchema)이다. V3 descriptor가 쓰지 않는 참조 기능 NoRequest 스키마 행 제거",
+ "approvedAt": "2026-11-03T12:22:21.004Z"
}
diff --git a/config/contracts/registry-baseline.json b/config/contracts/registry-baseline.json
index 4294d79f..f01ec895 100644
--- a/config/contracts/registry-baseline.json
+++ b/config/contracts/registry-baseline.json
@@ -330,30 +330,32 @@
"rowCount": 3,
"contract": {
"requiredFields": [
+ "operationId",
+ "featureId",
"method",
"path",
- "operationId",
- "auth",
- "timeoutMs",
- "idempotency",
- "retry",
- "requestSource",
+ "authProfileId",
+ "retrySemantics",
+ "requestBody",
+ "responseBody",
+ "responseEnvelope",
"requestSchema",
"responseSchema",
- "owner"
+ "problemSchema"
],
"fieldTypes": {
+ "operationId": "string",
+ "featureId": "string",
"method": "string",
"path": "string",
- "operationId": "string",
- "auth": "string",
- "timeoutMs": "integer|null",
- "idempotency": "string",
- "retry": "string",
- "requestSource": "string",
+ "authProfileId": "string",
+ "retrySemantics": "string",
+ "requestBody": "string",
+ "responseBody": "string",
+ "responseEnvelope": "string",
"requestSchema": "string",
"responseSchema": "string",
- "owner": "string"
+ "problemSchema": "string"
},
"uniqueFields": [
"operationId"
@@ -361,28 +363,30 @@
"allowedValues": {
"method": [
"GET",
+ "HEAD",
"POST",
"PUT",
"PATCH",
"DELETE"
],
- "auth": [
- "none",
- "external-session"
+ "retrySemantics": [
+ "SAFE",
+ "IDEMPOTENT",
+ "KEYED",
+ "NEVER"
],
- "idempotency": [
- "safe",
- "keyed",
- "none"
+ "requestBody": [
+ "NONE",
+ "JSON"
],
- "retry": [
- "runtime",
- "never"
+ "responseBody": [
+ "REQUIRED_JSON",
+ "OPTIONAL_JSON",
+ "NONE"
],
- "requestSource": [
- "none",
- "search",
- "body"
+ "responseEnvelope": [
+ "NONE",
+ "ENVELOPE_V1"
]
},
"references": [
@@ -399,115 +403,60 @@
],
"keyField": "operationId",
"breakingFields": [
+ "operationId",
"method",
"path",
- "operationId",
- "auth",
- "idempotency",
- "requestSource",
+ "authProfileId",
+ "retrySemantics",
+ "requestBody",
+ "responseBody",
+ "responseEnvelope",
"requestSchema",
"responseSchema"
]
},
"rows": {
"CREATE_REFERENCE_RESOURCE": {
- "auth": "external-session",
"authProfileId": "EXTERNAL_BEARER",
- "contractVersion": 2,
- "csrfProfileId": "NO_CSRF_BEARER",
- "idempotency": "keyed",
- "idempotencyKeyPolicy": "REQUIRED",
- "mapperId": "ReferenceResourceMapper",
- "maxEncodedSearchBytes": 0,
- "maxResponseBytes": 32768,
+ "featureId": "reference-feature",
"method": "POST",
"operationId": "CREATE_REFERENCE_RESOURCE",
- "owner": "feature-frontend-reference-feature-vertical-slice",
"path": "/api/reference-resources",
- "pathParameterNames": [],
- "pathSchema": "NoRequest",
- "protocol": "REST",
- "providerId": "PRIMARY_API",
- "replayPolicy": "KEYED_COMMAND",
+ "problemSchema": "ReferenceProblem",
+ "requestBody": "JSON",
"requestSchema": "CreateReferenceResourceCommand",
- "requestSource": "body",
- "responseMediaTypes": [
- "application/json"
- ],
+ "responseBody": "REQUIRED_JSON",
+ "responseEnvelope": "NONE",
"responseSchema": "ReferenceResourcePayload",
- "retry": "runtime",
- "semantics": "COMMAND",
- "successStatuses": [
- 200,
- 201
- ],
- "timeoutMs": null
+ "retrySemantics": "KEYED"
},
"GET_REFERENCE_RESOURCE": {
- "auth": "external-session",
"authProfileId": "EXTERNAL_BEARER",
- "contractVersion": 2,
- "csrfProfileId": "NO_CSRF_BEARER",
- "idempotency": "safe",
- "idempotencyKeyPolicy": "NONE",
- "mapperId": "ReferenceResourceMapper",
- "maxEncodedSearchBytes": 0,
- "maxResponseBytes": 32768,
+ "featureId": "reference-feature",
"method": "GET",
"operationId": "GET_REFERENCE_RESOURCE",
- "owner": "feature-frontend-reference-feature-vertical-slice",
"path": "/api/reference-resources/{resourceId}",
- "pathParameterNames": [
- "resourceId"
- ],
- "pathSchema": "ReferenceResourceParams",
- "protocol": "REST",
- "providerId": "PRIMARY_API",
- "replayPolicy": "SAFE",
- "requestSchema": "NoRequest",
- "requestSource": "none",
- "responseMediaTypes": [
- "application/json"
- ],
+ "problemSchema": "ReferenceProblem",
+ "requestBody": "NONE",
+ "requestSchema": "ReferenceResourceParams",
+ "responseBody": "REQUIRED_JSON",
+ "responseEnvelope": "NONE",
"responseSchema": "ReferenceResourcePayload",
- "retry": "runtime",
- "semantics": "QUERY",
- "successStatuses": [
- 200
- ],
- "timeoutMs": null
+ "retrySemantics": "SAFE"
},
"LIST_REFERENCE_RESOURCES": {
- "auth": "external-session",
"authProfileId": "EXTERNAL_BEARER",
- "contractVersion": 2,
- "csrfProfileId": "NO_CSRF_BEARER",
- "idempotency": "safe",
- "idempotencyKeyPolicy": "NONE",
- "mapperId": "ReferenceResourceListMapper",
- "maxEncodedSearchBytes": 4096,
- "maxResponseBytes": 262144,
+ "featureId": "reference-feature",
"method": "GET",
"operationId": "LIST_REFERENCE_RESOURCES",
- "owner": "feature-frontend-reference-feature-vertical-slice",
"path": "/api/reference-resources",
- "pathParameterNames": [],
- "pathSchema": "NoRequest",
- "protocol": "REST",
- "providerId": "PRIMARY_API",
- "replayPolicy": "SAFE",
+ "problemSchema": "ReferenceProblem",
+ "requestBody": "NONE",
"requestSchema": "ReferenceResourceListQuery",
- "requestSource": "search",
- "responseMediaTypes": [
- "application/json"
- ],
+ "responseBody": "REQUIRED_JSON",
+ "responseEnvelope": "NONE",
"responseSchema": "ReferenceResourceListPayload",
- "retry": "runtime",
- "semantics": "QUERY",
- "successStatuses": [
- 200
- ],
- "timeoutMs": null
+ "retrySemantics": "SAFE"
}
}
},
@@ -515,7 +464,7 @@
"registryId": "FE-REG-SCHEMA",
"owner": "feature-frontend-contract-schema-registry",
"source": "src/features/loaded-feature-runtimes.ts",
- "rowCount": 8,
+ "rowCount": 7,
"contract": {
"requiredFields": [
"schemaId",
@@ -568,15 +517,6 @@
"runtime": "zod",
"schemaId": "none"
},
- "NoRequest": {
- "boundary": "api-request",
- "direction": "REQUEST",
- "owner": "feature-frontend-reference-feature-vertical-slice",
- "runtime": "zod",
- "schemaId": "NoRequest",
- "schemaVersion": 1,
- "unknownFieldPolicy": "REJECT_UNKNOWN"
- },
"NotFoundSplat": {
"boundary": "route-params",
"owner": "feature-frontend-routing-release-recovery-runtime",
diff --git a/config/contracts/registry-governance.json b/config/contracts/registry-governance.json
index c4a71cf5..23aa7522 100644
--- a/config/contracts/registry-governance.json
+++ b/config/contracts/registry-governance.json
@@ -138,38 +138,64 @@
"owner": "feature-frontend-api-client-response-envelope-contract",
"keyField": "operationId",
"requiredFields": [
+ "operationId",
+ "featureId",
"method",
"path",
- "operationId",
- "auth",
- "timeoutMs",
- "idempotency",
- "retry",
- "requestSource",
+ "authProfileId",
+ "retrySemantics",
+ "requestBody",
+ "responseBody",
+ "responseEnvelope",
"requestSchema",
"responseSchema",
- "owner"
+ "problemSchema"
],
"fieldTypes": {
+ "operationId": "string",
+ "featureId": "string",
"method": "string",
"path": "string",
- "operationId": "string",
- "auth": "string",
- "timeoutMs": "integer|null",
- "idempotency": "string",
- "retry": "string",
- "requestSource": "string",
+ "authProfileId": "string",
+ "retrySemantics": "string",
+ "requestBody": "string",
+ "responseBody": "string",
+ "responseEnvelope": "string",
"requestSchema": "string",
"responseSchema": "string",
- "owner": "string"
+ "problemSchema": "string"
},
- "uniqueFields": ["operationId"],
+ "uniqueFields": [
+ "operationId"
+ ],
"allowedValues": {
- "method": ["GET", "POST", "PUT", "PATCH", "DELETE"],
- "auth": ["none", "external-session"],
- "idempotency": ["safe", "keyed", "none"],
- "retry": ["runtime", "never"],
- "requestSource": ["none", "search", "body"]
+ "method": [
+ "GET",
+ "HEAD",
+ "POST",
+ "PUT",
+ "PATCH",
+ "DELETE"
+ ],
+ "retrySemantics": [
+ "SAFE",
+ "IDEMPOTENT",
+ "KEYED",
+ "NEVER"
+ ],
+ "requestBody": [
+ "NONE",
+ "JSON"
+ ],
+ "responseBody": [
+ "REQUIRED_JSON",
+ "OPTIONAL_JSON",
+ "NONE"
+ ],
+ "responseEnvelope": [
+ "NONE",
+ "ENVELOPE_V1"
+ ]
},
"references": [
{
@@ -189,12 +215,14 @@
"src/features/*/application"
],
"breakingFields": [
+ "operationId",
"method",
"path",
- "operationId",
- "auth",
- "idempotency",
- "requestSource",
+ "authProfileId",
+ "retrySemantics",
+ "requestBody",
+ "responseBody",
+ "responseEnvelope",
"requestSchema",
"responseSchema"
]
diff --git a/docs/architecture/backend-api-and-server-state-contract.md b/docs/architecture/backend-api-and-server-state-contract.md
index 772be5ca..b3ddcad8 100644
--- a/docs/architecture/backend-api-and-server-state-contract.md
+++ b/docs/architecture/backend-api-and-server-state-contract.md
@@ -546,12 +546,12 @@ query invalidate hint로만 쓸지 operation별 reducer contract가 필요하다
같은 이름의 정책이라도 전송마다 동작이 다르다. operation을 다른 전송으로 옮기면
이 표로 동작 변화를 확인한다.
-| 규칙 | V3 contract executor (기본 경로) | V2 client (기본 조합에 없음) | Browser RPC |
-|---|---|---|---|
-| KEYED 명령 자동 재시도 | 전송 전 실패만 재시도한다. 전송 뒤 실패는 재시도하지 않고 `MAYBE_APPLIED`다. 응답(5xx·429)으로는 재시도하지 않는다 (`src/adapters/http/http-retry-lifecycle.ts` `canRetryTransport`, `isRetryableSemantics`) | 네트워크·타임아웃·429·408/425/502/503/504 뒤 같은 키로 다시 보낸다. 전송 여부를 보지 않는다 (`src/adapters/http/retry-policy.ts` `shouldRetry`) | `KEYED_COMMAND`는 유효한 키가 있고 profile `retryOwner`가 `FRONTEND_ADAPTER`면 `retryableFailures`에서 같은 키로 다시 보낸다 (`src/adapters/browser-rpc/browser-rpc-runtime.ts` `shouldRetry`) |
-| 재시도 횟수 상한 | min(계약 `retryBudget`, `MAX_RETRY_ATTEMPTS`, 2) (`http-execution-v3.ts` `retryCeiling`) | `MAX_RETRY_ATTEMPTS`, 기본 2 (`client.ts` `maxRetryAttempts`) | profile `maxAttempts`(시도 횟수), 하드 상한 4 (`src/contracts/browser-rpc.ts` `BROWSER_RPC_HARD_LIMITS`) |
-| `Retry-After` | 5초를 넘으면 재시도하지 않는다. 이하면 hint에 jitter를 더해 기다린다 (`http-retry-lifecycle.ts` `retryDelayFor`) | 30초를 넘으면 재시도하지 않는다. 이하면 max(backoff, hint)만큼 기다린다 (`retry-policy.ts`) | profile `maxRetryAfterMs`로 잘라 max(backoff, hint)만큼 기다린다. 하드 상한 60초 (`browser-rpc-runtime.ts` `retryDelay`) |
-| `REQUEST_TIMEOUT_MS` | 상한이다. 계약 `totalDeadlineMs`를 줄이기만 한다 (`runtime-adapters.ts` `requestDeadlineCeilingMs`) | 기본값이다. operation `timeoutMs`가 있으면 그 값을 쓰고, 더 길 수도 있다 (`client.ts` `defaultTimeoutMs`) | 쓰지 않는다. operation `totalDeadlineMs`만 쓴다. 하드 상한 30분 |
+| 규칙 | V3 contract executor | Browser RPC |
+|---|---|---|
+| KEYED 명령 자동 재시도 | 전송 전 실패만 재시도한다. 전송 뒤 실패는 재시도하지 않고 `MAYBE_APPLIED`다. 응답(5xx·429)으로는 재시도하지 않는다 (`src/adapters/http/http-retry-lifecycle.ts` `canRetryTransport`, `isRetryableSemantics`) | `KEYED_COMMAND`는 유효한 키가 있고 profile `retryOwner`가 `FRONTEND_ADAPTER`면 `retryableFailures`에서 같은 키로 다시 보낸다 (`src/adapters/browser-rpc/browser-rpc-runtime.ts` `shouldRetry`) |
+| 재시도 횟수 상한 | min(계약 `retryBudget`, `MAX_RETRY_ATTEMPTS`, 2) (`http-execution-v3.ts` `retryCeiling`) | profile `maxAttempts`(시도 횟수), 하드 상한 4 (`src/contracts/browser-rpc.ts` `BROWSER_RPC_HARD_LIMITS`) |
+| `Retry-After` | 5초를 넘으면 재시도하지 않는다. 이하면 hint에 jitter를 더해 기다린다 (`http-retry-lifecycle.ts` `retryDelayFor`) | profile `maxRetryAfterMs`로 잘라 max(backoff, hint)만큼 기다린다. 하드 상한 60초 (`browser-rpc-runtime.ts` `retryDelay`) |
+| `REQUEST_TIMEOUT_MS` | 상한이다. 계약 `totalDeadlineMs`를 줄이기만 한다 (`runtime-adapters.ts` `requestDeadlineCeilingMs`) | 쓰지 않는다. operation `totalDeadlineMs`만 쓴다. 하드 상한 30분 |
결과 불명 뒤 사용자 재전송은 전송과 무관하게 같은 intent·같은 키를 쓴다
(`src/presentation/adapters/query/application-query.ts` `resendUnknownEffect`).
diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md
index 620edd09..054d2342 100644
--- a/docs/architecture/starter-experience.md
+++ b/docs/architecture/starter-experience.md
@@ -141,10 +141,9 @@ selected app. Every build and check script runs it first; run it yourself with
entered. Do not import it statically from anywhere: each feature would add
its whole executable code to the initial chunk again, about 3.9 KB gzip
(`tests/unit/feature-shape-growth.test.ts` bounds one feature at 1 KiB).
- An HTTP API is written twice: its API contract operation (V2) is what
- `check:registries` governs, and its contract contribution descriptor (V3)
- is what executes. `tests/unit/http-operation-v2-v3-parity.test.ts` fails
- when one exists without the other or when they disagree.
+ An HTTP API is written once, as its contract contribution descriptor: it
+ executes, and `check:registries` governs the FE-REG-API row projected from
+ it (`projectApiOperationRows` in `src/contracts/api-operations.ts`).
A product feature's contract contribution uses an `EXTERNAL_PACKAGE`
source. `TEMPLATE_FIXTURE` belongs to `reference-feature` only and never
joins the release contract set; the composer rejects it anywhere else.
diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md
index 2a6c6858..8382286d 100644
--- a/docs/manual/01-add-a-feature.md
+++ b/docs/manual/01-add-a-feature.md
@@ -158,12 +158,12 @@ corepack pnpm create:feature invoice-feature
생성된 파일:
- `contracts/-feature-contract.ts`: 선언 쪽. 라우트, 무효화, 계약 패키지 신원(`contractPackages`).
-- `contracts/-api-contract.ts`: V2 행. `check:registries`가 검사하는 선언이다.
-- `contracts/-contract-contribution.ts`: V3 descriptor. 실제로 실행되는 HTTP 계약이다.
+- `contracts/-contract-contribution.ts`: HTTP 계약(descriptor). operation을 적는 곳은 여기 하나다. 이것이 실행되고, `check:registries`의 FE-REG-API 행도 여기서 뽑는다.
+- `contracts/-schema-metadata.ts`: 스키마 메타데이터(FE-REG-SCHEMA 행). 스키마 ID마다 쓰이는 자리(`boundary`)와 소유자를 적는다.
- `contracts/-schemas.ts`: zod 스키마와 검증기.
- `contracts/-mapper.ts`: 와이어 값 → 화면 값.
-같은 API를 V2와 V3로 두 번 쓴다. V2는 레지스트리 검사용 선언이고, V3는 실행용이다.
+FE-REG-API 행은 descriptor에서 자동으로 만든다(`src/contracts/api-operations.ts`의 `projectApiOperationRows`). 같은 API를 다른 파일에 다시 적지 않는다.
① **정할 것**
@@ -172,8 +172,8 @@ corepack pnpm create:feature invoice-feature
- 재시도 의미(`retrySemantics`). [02 결정표 3절](02-decision-tables.md#3-재시도-의미)
- 쓰기의 실패 분류(`commandEffect`). [02 결정표 4절](02-decision-tables.md#4-결과-불명)
- 인증 프로필(`authProfileId`). [02 결정표 5절](02-decision-tables.md#5-인증)
- - 바이트 한도·마감: V3 `requestByteLimit`, `responseByteLimit`, `totalDeadlineMs`. V2 `maxResponseBytes`는 V3 `responseByteLimit`와 같은 값이다.
- - 스키마 ID, mapper ID, operation ID. 모두 기능 접두어를 붙인다([reference/global-ids.md](reference/global-ids.md)).
+ - 바이트 한도·마감: `requestByteLimit`, `responseByteLimit`, `totalDeadlineMs`.
+ - 스키마 ID, operation ID. 모두 기능 접두어를 붙인다([reference/global-ids.md](reference/global-ids.md)).
② **기준**
@@ -203,8 +203,8 @@ corepack pnpm create:feature invoice-feature
- 백엔드는 값이 null인 필드를 키째 뺀다. `data` 키가 없으면 `null`로 읽는다. DTO 안에서 null일 수 있는 필드는 스키마에서 `.optional()`로 받는다.
- problem 스키마(`-schemas.ts`의 `ProblemSchema`)는 Envelope의 `error` 객체다. 분기는 `code`로 한다. `message`는 버린다.
- 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`가 적용됐는지는 실행기가 백엔드 기준 표로 정한다. 목록은 [02 결정표 4절](02-decision-tables.md#4-결과-불명)이다.
-- `mapProblem`이 없거나 `undefined`를 돌려주면 V2 클라이언트와 같은 kind·code·필드 오류로 읽는다(`src/adapters/http/backend-envelope.ts`).
-- 바이트 상한(`responseByteLimit`)과 구조 예산은 Envelope 전체에 걸린다. V2 `maxResponseBytes`와 같은 값이다.
+- `mapProblem`이 없거나 `undefined`를 돌려주면 백엔드 code·필드 오류·status별 kind로 읽는다(`src/adapters/http/backend-envelope.ts`).
+- 바이트 상한(`responseByteLimit`)과 구조 예산은 Envelope 전체에 걸린다.
- MSW: `createHttpScenarioHandler`는 descriptor의 `responseEnvelope`를 보고 Envelope로 답한다(`tests/mocks/handlers/http-scenarios.ts`). 생성된 `tests/features//-http-gateway.test.ts`는 백엔드 본문을 그대로 적어 검사한다.
- `http-contract.md`는 status·`code`의 **뜻**(예: 409 `IDEMPOTENT_IN_FLIGHT`)의 정본이다. 기능 코드에서 그 code는 problem의 `code`로 읽는다.
@@ -218,69 +218,56 @@ DTO와 problem details(`type`·`title`·`status`)를 감싸지 않고 보내는
참조 기능(`src/features/reference-feature/`)이 이 모양이다. 참조 기능의 MSW 본문도 DTO와 problem details다.
-**V2 행의 입력 칸**
+**입력과 스키마 메타데이터**
-V2 행은 입력을 두 칸으로 나눠 적는다. 경로 파라미터는 `pathSchema`, 검색값·본문은 `requestSchema`다. V3는 입력 전체를 `inputValidator` 하나로 검증한다.
+`inputValidator` 하나가 operation 입력 전체를 검증한다. 입력이 요청의 어디로 가는지는 `projectRequest`가 정한다.
-정본: 칸 정의는 `src/contracts/api-operations.ts`(`RestOperationV2`, `validateRestOperation`), 스키마 칸은 `src/contracts/schema-registry.ts`(`SchemaDefinition`). 아래는 자주 바꾸고 자주 막히는 칸만 적는다.
+- 경로 파라미터: `pathValues`. 키는 `pathTemplate`의 `{이름}`과 같다.
+- 검색값: `queryEntries`. 인코딩한 쿼리는 8,192바이트까지다(`HTTP_EXECUTION_CEILINGS.encodedQueryBytes`).
+- 본문: `body`. `requestBody: "JSON"`일 때만 쓴다. 아니면 `null`이다.
-| 칸 | 뜻 | 값 고르는 법 | V3 짝 |
-|---|---|---|---|
-| `requestSource` | 입력이 요청의 어디로 가나 | `none`(입력 없음, 또는 경로 파라미터만), `search`(쿼리 문자열), `body`(JSON 본문) | `body`면 `requestBody: "JSON"`, 아니면 `"NONE"` |
-| `requestSchema` | 검색값·본문 스키마 ID | `requestSource`가 `none`이면 기능의 빈 입력 스키마(`NoRequest`) | `requestSource`가 `none`이 아니면 `inputValidator`의 스키마 ID와 같다 |
-| `pathSchema` | 경로 파라미터 스키마 ID. 비울 수 없다 | 경로 파라미터가 없으면 빈 입력 스키마 | 파라미터가 있으면 `inputValidator`의 스키마 ID와 같다 |
-| `pathParameterNames` | `path`의 `{이름}` 목록 | `path`에 적은 이름과 정확히 같게. 없으면 `[]` | `projectRequest`가 돌려주는 `pathValues`의 키 |
-| `maxEncodedSearchBytes` | 인코딩한 쿼리 문자열의 바이트 상한(0~32,768). V2 실행기만 읽는다 | 검색값이 없으면 0. 있으면 값의 최대 길이로 정한다(참조 기능 4,096) | 없음. V3는 고정 상한 8,192바이트(`HTTP_EXECUTION_CEILINGS.encodedQueryBytes`)를 쓴다 |
-| 스키마 `boundary` | 그 스키마가 쓰이는 자리 | 아래 목록 | 없음 |
+경로 파라미터와 본문을 함께 받는 operation(예: `PUT /items/{id}` + 본문)은 입력 스키마 하나에 둘을 담고 `projectRequest`가 나눈다.
+
+정본: descriptor 칸은 `src/contracts/external-contract-runtime.ts`(`InstalledHttpContract`), 스키마 메타데이터 칸은 `src/contracts/schema-registry.ts`(`SchemaDefinition`).
스키마 `boundary` 값:
-- `route-params`: 라우트 경로 파라미터(`paramsSchema`). 같은 스키마를 GET의 `pathSchema`로도 쓴다.
+- `route-params`: 라우트 경로 파라미터(`paramsSchema`). 같은 스키마를 경로 파라미터 GET의 `inputValidator`로도 쓴다.
- `route-search`: 라우트 검색값에만 쓴다.
- `route-search-api-request`: 라우트 검색값이면서 GET 쿼리다. 목록 검색이 이 경우다.
-- `api-request`: 요청 본문, 그리고 빈 입력 스키마.
+- `api-request`: 요청 입력.
- `api-response`: 응답 DTO.
-예: 공지 기능의 검색값 GET과 경로 파라미터 GET. 입력 칸만 적었다. 나머지 칸은 생성된 행과 같다.
+예: 공지 기능의 검색값 GET과 경로 파라미터 GET. 입력에 관한 칸만 적었다.
```ts
-// GET /api/notices?q=... → V3 inputValidator: NoticeListQuery, projectRequest는 queryEntries를 채운다
-NOTICE_LIST_ITEMS: defineRestOperation({
- method: "GET",
- path: "/api/notices",
- requestSource: "search",
- requestSchema: "NoticeListQuery", // boundary: "route-search-api-request"
- pathSchema: "NoticeNoRequest", // boundary: "api-request"
- pathParameterNames: [],
- maxEncodedSearchBytes: 4_096,
+// GET /api/notices?q=... inputValidator 스키마 NoticeListQuery (boundary: "route-search-api-request")
+pathTemplate: "/api/notices",
+inputValidator: zodValidator("NoticeListQuery", noticeListQuerySchema),
+projectRequest: (input) => Object.freeze({
+ pathValues: Object.freeze({}),
+ queryEntries: Object.freeze(input.q === undefined ? [] : [Object.freeze(["q", input.q] as const)]),
+ body: null,
}),
-// GET /api/notices/{noticeId} → V3 inputValidator: NoticeParams, projectRequest는 pathValues를 채운다
-NOTICE_GET_ITEM: defineRestOperation({
- method: "GET",
- path: "/api/notices/{noticeId}",
- requestSource: "none",
- requestSchema: "NoticeNoRequest",
- pathSchema: "NoticeParams", // boundary: "route-params"
- pathParameterNames: ["noticeId"],
- maxEncodedSearchBytes: 0,
+
+// GET /api/notices/{noticeId} inputValidator 스키마 NoticeParams (boundary: "route-params")
+pathTemplate: "/api/notices/{noticeId}",
+inputValidator: zodValidator("NoticeParams", noticeParamsSchema),
+projectRequest: (input) => Object.freeze({
+ pathValues: Object.freeze({ noticeId: input.noticeId }),
+ queryEntries: Object.freeze([]),
+ body: null,
}),
```
-경로 파라미터와 검색값·본문을 함께 받는 operation(예: `PUT /items/{id}` + 본문)은 아직 규칙이 없다. V2/V3 일치 테스트가 `V2 declares both a path and a request schema; decide which V3 input schema matches them`로 실패한다.
-
③ **잡는 검사 / 못 잡는 것**
-- V2와 V3가 다르면 `tests/unit/http-operation-v2-v3-parity.test.ts`(`test:unit`, FE-GATE-005)가 실패한다.
- - 비교하는 것: operation 목록, method, path, 성공 상태, 응답 한도, 인증 프로필, 재시도 의미, 쓰기 의미, 요청 본문, 스키마 ID.
- - 마감 시간은 비교하지 않는다. V2 `timeoutMs`는 `null`이다.
-- V2 입력 칸이 틀리면 모듈 로드 때 operation ID를 말하며 실패한다.
- - `pathParameterNames`가 `path`의 이름과 다름: `REST path codec does not match its template: `
- - `pathSchema`가 비었거나 `maxEncodedSearchBytes`가 범위 밖: `Invalid REST operation contract: `
- - `pathSchema`·`requestSchema`·`responseSchema`가 등록되지 않은 스키마: `Unresolved API schema binding: `
-- 인증 프로필 이름이 틀리면 operation을 적재하는 모든 게이트가 실패한다.
- - 메시지: `REST security profiles are incoherent for : unknown authProfileId .`
-- 스키마·mapper·operation ID가 겹치면 모듈 로드 때 그 ID를 말하며 실패한다.
- - 예: `Invalid or duplicate schema definition: `
+- descriptor의 입력·응답 스키마 ID가 스키마 메타데이터에 없으면 `check:registries`가 실패한다.
+ - 메시지: `FE-REG-API..requestSchema references unknown FE-REG-SCHEMA.schemaId=` (`responseSchema`도 같다)
+- 인증 프로필 이름이 틀리면 계약 조립이 거부해 operation을 적재하는 모든 게이트가 실패한다.
+ - 오류의 `reason`: `/: unknown authProfileId `
+- 스키마 ID나 operation ID가 겹치면 적재 때 그 ID를 말하며 실패한다.
+ - 예: `Invalid or duplicate schema definition: `, 계약 조립 `duplicate operation: `
- `TEMPLATE_FIXTURE` 출처를 참조 기능 밖에서 쓰면 계약 조립이 거부한다.
- 오류의 `reason`: `: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to reference-feature only; pin an EXTERNAL_PACKAGE`
- zod를 직접 import하면 `check:architecture`가 `zod-is-reached-through-contracts-zod`로 막는다.
@@ -364,7 +351,7 @@ NOTICE_GET_ITEM: defineRestOperation({
- operation ID·route ID·입력 타입을 틀리면 `check:types`가 막는다. 음성 fixture: `check:types:fixture:http-operation-id`, `check:types:fixture:http-route-id`, `check:types:fixture:http-operation-input`.
- 호스트가 주지 않는 capability를 `needs`에 적으면 조립이 실패한다.
- 메시지: `feature needs , which the host did not provide`
-- V2 operation을 선언하고 기능 `adapters/`·`application/`에서 쓰지 않으면 `check:registries`(FE-GATE-010)가 실패한다.
+- operation을 계약에 두고 기능 `adapters/`·`application/`에서 쓰지 않으면 `check:registries`(FE-GATE-010)가 실패한다.
- 메시지: `FE-REG-API. has no executable consumer for operationId=`
- **못 잡음**: `routeId`가 실제로 요청을 보내는 화면과 다른 것. 타입은 기능의 route ID인지만 본다.
- **못 잡음**: 기능 `contracts/`나 다섯 폴더 밖에 새로 만든 폴더(예: `hooks/`)를 거쳐 `src/adapters`에 닿는 import. `.dependency-cruiser.json`에 그 경로를 막는 규칙이 없다. 기능 안에는 `domain/`, `application/`, `contracts/`, `adapters/`, `presentation/` 다섯 폴더만 둔다.
diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md
index 61ceb487..352a80b4 100644
--- a/docs/manual/02-decision-tables.md
+++ b/docs/manual/02-decision-tables.md
@@ -88,8 +88,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기
|---|---|---|---|
| 서버 보장 | 멱등 키(`Idempotency-Key` 헤더)로 같은 요청의 중복 적용을 막는다 | 같은 요청을 여러 번 적용해도 결과가 같다 (키 없이) | 중복을 막지 못한다 |
| 자동 재시도 | 실제로 보내기 전까지만. 보낸 뒤 결과를 모르면 결과 불명(4절)으로 넘긴다 | 된다 | 하지 않는다 |
-| V3 | `commandRecovery: { mode: "IDEMPOTENCY_REPLAY", operationIdentityField }` 필수. 참조 기능은 `retryBudget: 0` | — | `retryBudget: 0` 필수 |
-| V2 `replayPolicy` | `KEYED_COMMAND` | `IDEMPOTENT` | `NON_REPLAYABLE` |
+| descriptor | `commandRecovery: { mode: "IDEMPOTENCY_REPLAY", operationIdentityField }` 필수. 참조 기능은 `retryBudget: 0` | — | `retryBudget: 0` 필수 |
| 뮤테이션 정책 | `requiresIdempotencyKey: true` | — | — |
- 멱등 키: 서버가 "같은 쓰기 요청"을 알아보게 하는 값이다.
@@ -99,13 +98,12 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기
**정본**: 백엔드가 멱등 키 요청에 어떻게 답하는지는 `clean-architecture-backend-template/docs/web/http-contract.md` §2(멱등성 응답)다. 여기에 표를 옮기지 않는다.
-**어디에 적나**: `contracts/-contract-contribution.ts`의 `retrySemantics`, `commandRecovery`, `frontend.retryBudget`. 같은 의미를 `contracts/-api-contract.ts`의 `replayPolicy`, `idempotency`, `idempotencyKeyPolicy`에도 적는다.
+**어디에 적나**: `contracts/-contract-contribution.ts`의 `retrySemantics`, `commandRecovery`, `frontend.retryBudget`. 다른 파일에 다시 적지 않는다.
**틀리면**
- `NEVER`에 `retryBudget`을 0보다 크게 주면 계약 조립이 `retry budget contradicts NEVER retry semantics`로 거부한다.
- `KEYED`에 `commandRecovery`가 없으면 `KEYED commands require a recovery descriptor`로 거부한다.
-- V2와 V3의 재시도 의미가 다르면 `tests/unit/http-operation-v2-v3-parity.test.ts`가 실패한다.
- 서버 보장과 다른 의미를 고른 것은 검사가 잡지 못한다.
근거: `scale-architecture.md` §13(재시도 모델).
@@ -141,7 +139,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기
- 같은 status라도 code로 나뉠 수 있다. 예: 409 중 "처리 중"은 `MAYBE_APPLIED`여야 한다. `NOT_APPLIED`로 보면 다음 저장이 새 키를 만들어 같은 작업이 두 번 적용된다.
- 401·403·429는 문제 응답 본문을 읽기 전에 status로 나뉜다. 서버가 상태를 안 바꾼다고 보장하면 `classifyStatus`로 `NOT_APPLIED`를 돌려준다. 없으면 `MAYBE_APPLIED`다.
- 문제 응답 본문이 기능의 problem 스키마를 통과하지 못하면 `classifyProblem`을 부르지 않는다. 쓰기는 `MAYBE_APPLIED`가 된다(`src/adapters/http/http-execution-v3.ts`).
-- `responseEnvelope: "ENVELOPE_V1"`인 operation은 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`의 판정을 실행기가 백엔드 기준 표로 정한다(`src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE`). 표의 근거는 [계약 문서](../architecture/backend-api-and-server-state-contract.md) 6.1절이다(백엔드 코드에서 code마다 쓰기 전·후를 읽은 결과). `classifyProblem`은 그 밖의 status만 받고, 다르게 답해도 표의 판정은 바뀌지 않는다. V2 클라이언트도 같은 표를 쓴다.
+- `responseEnvelope: "ENVELOPE_V1"`인 operation은 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`의 판정을 실행기가 백엔드 기준 표로 정한다(`src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE`). 표의 근거는 [계약 문서](../architecture/backend-api-and-server-state-contract.md) 6.1절이다(백엔드 코드에서 code마다 쓰기 전·후를 읽은 결과). `classifyProblem`은 그 밖의 status만 받고, 다르게 답해도 표의 판정은 바뀌지 않는다.
- `NOT_APPLIED`(쓰기 전 거절): 400 `VALIDATION_FAILED`(details 모양과 상관없음), 400 `IDEMPOTENCY_KEY_INVALID`, 422 `IDEMPOTENT_REQUEST_MISMATCH`
- `MAYBE_APPLIED`: 그 밖의 400·409·422. 409 `IDEMPOTENT_IN_FLIGHT`, `BAD_PARAMETER`, 도메인 code, fileserver의 422가 여기 든다. 그리고 503 `IDEMPOTENCY_UNAVAILABLE`
- 짝 백엔드가 쓰기 전에 거절하는 code를 새로 만들면 계약 문서 6.1절과 이 표를 함께 고친다. 표에 없으면 `MAYBE_APPLIED`다
@@ -161,7 +159,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기
→ 결과 불명 화면 → "같은 요청으로 다시 보내기"가 같은 키로 보낸다
```
-- V2 클라이언트(레거시)도 같다. V2와 V3 Envelope 경로가 같은 표(`src/adapters/http/backend-envelope.ts`)를 읽는다. V2는 `NOT_APPLIED`만 싣고 503은 effect 없이 돌아온다. 뮤테이션 조정자가 그것을 `MAYBE_APPLIED`로 본다(`src/presentation/adapters/query/application-query.ts`의 `mutationFailureWithEffect`).
+- 뮤테이션 조정자는 effect가 없는 실패도 `MAYBE_APPLIED`로 본다(`src/presentation/adapters/query/application-query.ts`의 `mutationFailureWithEffect`).
- 판정: 맞는다. 지금 동작은 `MAYBE_APPLIED`이고 재전송은 같은 키다. 백엔드가 요구하는 행동과 같다.
- 다른 점은 화면뿐이다. 서버는 "실행 안 함"이라고 답했지만 화면은 "결과를 모른다"로 보여 준다.
- `NOT_APPLIED`로 바꾸면 다음 저장이 새 키를 만든다. 키를 다시 쓰는 것은 결과 불명으로 남은 요청뿐이다(같은 파일). 백엔드가 말한 "같은 키"와 어긋난다.
@@ -188,16 +186,15 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기
| 언제 | 로그인 없이 부르는 API | 세션 토큰을 `authorization` 헤더로 보내는 API. 생성된 뼈대가 이것이다 | 위 둘로 안 되는 경우(쿠키 세션, 별도 토큰 등) |
| 정의 | `src/contracts/rest-profiles.ts` (템플릿 소유) | 같은 파일 | `src/contracts/product-contracts.ts`의 `PRODUCT_REST_AUTH_PROFILES` (제품 소유) |
| 자격 증명 | 없음 | 템플릿 세션 | `src/bootstrap/product-composition.ts`의 `credentialProviders` |
-| V2 `auth` | `none` | `external-session` | 프로필에 맞게 |
| 라우트 `access` | 보통 `public` | 보통 `session-required` | 프로필에 맞게 |
- `REFERENCE_EXTERNAL_BEARER`는 `EXTERNAL_BEARER`의 옛 이름이다. `@deprecated`이고 한 릴리스 뒤 지운다. 새 코드는 쓰지 않는다.
- 제품 프로필 ID는 템플릿 프로필 ID와 겹치면 안 된다.
-- CSRF 프로필은 템플릿 상수(`REST_CSRF_PROFILES`)뿐이다. 제품이 더할 자리는 없다. 쿠키 인증은 인증 프로필의 헤더 집합으로 표현한다. 예제: `tests/unit/product-composition-fixture.test.ts`.
+- 쿠키 인증과 CSRF 헤더는 인증 프로필의 헤더 집합으로 표현한다. 예제: `tests/unit/product-composition-fixture.test.ts`.
**기준**: 백엔드가 그 API에 요구하는 인증을 따른다. 새 프로필은 템플릿 파일이 아니라 제품 소유 파일 두 곳에만 더한다.
-**어디에 적나**: V3 `frontend.authProfileId`와 V2 `authProfileId`(같은 값), V2 `auth`, 라우트 `access`.
+**어디에 적나**: descriptor의 `frontend.authProfileId`, 라우트 `access`.
**틀리면**
diff --git a/docs/manual/reference/create-feature.md b/docs/manual/reference/create-feature.md
index d8e37316..5e26a4bb 100644
--- a/docs/manual/reference/create-feature.md
+++ b/docs/manual/reference/create-feature.md
@@ -43,9 +43,9 @@ corepack pnpm create:feature [--context ] [--package @scope/nam
- `context-routes.ts`: context가 적재하는 라우트
- `contracts/-feature-contract.ts`: 라우트, 무효화, 계약 패키지 신원
- `contracts/-schemas.ts`: zod 스키마와 `zodValidator` 검증기
-- `contracts/-mapper.ts`: 와이어 값 → 화면 값, 레지스트리 mapper
-- `contracts/-api-contract.ts`: V2 행
-- `contracts/-contract-contribution.ts`: V3 descriptor와 계약 기여
+- `contracts/-mapper.ts`: 와이어 값 → 화면 값
+- `contracts/-schema-metadata.ts`: 스키마 메타데이터(FE-REG-SCHEMA 행)
+- `contracts/-contract-contribution.ts`: HTTP descriptor와 계약 기여. FE-REG-API 행은 여기서 뽑는다
- `contracts/-message-catalog.ts`: ko-KR·en-US 문구
- `application/-feature-api.ts`: input, gateway port, `ApplicationFeatureInputs` 보강
- `adapters/-http-gateway.ts`: HTTP gateway
diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md
index 6cd11943..c22a5b87 100644
--- a/docs/manual/reference/errors.md
+++ b/docs/manual/reference/errors.md
@@ -71,23 +71,16 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
-| `REST security profiles are incoherent for : unknown authProfileId .` | 없는 인증 프로필 | `contracts/-api-contract.ts`의 `authProfileId`. 제품 프로필이면 `src/contracts/product-contracts.ts` |
-| `REST security profiles are incoherent for : unknown csrfProfileId .` | 없는 CSRF 프로필. 템플릿에는 `NO_CSRF_BEARER`뿐 | `contracts/-api-contract.ts`의 `csrfProfileId` |
-| `REST security profiles are incoherent for : auth "none" needs an ANONYMOUS profile, is .` | V2 `auth: "none"`인데 인증 프로필을 썼다 | V2 `auth` 또는 `authProfileId` |
-| `REST security profiles are incoherent for : auth "external-session" cannot use the ANONYMOUS profile .` | 로그인 API에 `ANONYMOUS` | V2 `auth` 또는 `authProfileId` |
+| `/: unknown authProfileId ` (계약 조립 오류의 `reason`) | 없는 인증 프로필 | `contracts/-contract-contribution.ts`의 `frontend.authProfileId`. 제품 프로필이면 `src/contracts/product-contracts.ts` |
| `Product REST auth profile reuses a template profile id.` | 제품 프로필 ID가 템플릿 것과 같다 | `src/contracts/product-contracts.ts` |
### 계약·스키마·mapper
| 메시지 | 원인 | 고칠 곳 |
|---|---|---|
-| `Invalid or duplicate schema definition: ` | 스키마 ID 중복 또는 메타 형식 | `contracts/-api-contract.ts`의 `schemas`. 접두어를 붙인다 |
-| `Invalid or duplicate runtime schema codec: ` | 런타임 codec ID 중복 | `contracts/-schemas.ts` |
-| `Invalid or duplicate boundary mapper: ` | mapper ID 중복 또는 형식 | `contracts/-mapper.ts` |
-| `Duplicate API operation: ` | V2 operation ID 중복 | `contracts/-api-contract.ts` |
-| `REST path codec does not match its template: ` | V2 `pathParameterNames`가 `path`의 `{이름}`과 다르다 | `contracts/-api-contract.ts` ([01 문서 3단계](../01-add-a-feature.md#3단계-api-계약) "V2 행의 입력 칸") |
-| `Invalid REST operation contract: ` | V2 행 형식. 예: 빈 `pathSchema`, `maxEncodedSearchBytes`가 0~32,768 밖 | 같은 곳 |
-| `Unresolved API schema binding: ` | V2 `pathSchema`·`requestSchema`·`responseSchema`가 등록되지 않은 스키마 | 같은 파일의 `schemas`, `contracts/-schemas.ts`의 codec |
+| `Invalid or duplicate schema definition: ` | 스키마 ID 중복 또는 메타 형식 | `contracts/-schema-metadata.ts`. 접두어를 붙인다 |
+| `duplicate operation: ` (계약 조립 오류의 `reason`) | operation ID 중복 | `contracts/-contract-contribution.ts`. 접두어를 붙인다 |
+| `FE-REG-API..requestSchema references unknown FE-REG-SCHEMA.schemaId=` | descriptor의 입력 스키마 ID가 스키마 메타데이터에 없다 (`responseSchema`도 같은 꼴) | `contracts/-schema-metadata.ts` |
| `Unregistered route codec: ` | URL 함수가 기능 codec을 `buildRouteUrl`에 넘기지 않았다 | `presentation/-routes.ts` |
| `contract package is declared, but no loaded contribution pins it` | 계약 `contractPackages`에 적은 패키지를 계약 기여가 쓰지 않는다 | `contracts/-contract-contribution.ts`의 `source` |
| ` contributes contract package , which no installed feature declares in contracts.contractPackages` | 계약 기여의 신원과 계약 선언의 신원이 다르다 | 둘 다 `_CONTRACT_PACKAGE` 하나를 쓰게 한다 |
@@ -149,7 +142,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
| `FE-REG-ROUTE..loadingSurface value does not match ` | 로딩 화면 이름이 케밥 표기가 아니다 | 계약 `routes.*.loadingSurface` |
| `FE-REG-ROUTE.. has unknown value ` | `access`·`errorSurface`가 정해진 값이 아니다 | 계약 `routes` |
| `FE-REG-ROUTE..paramsSchema references unknown FE-REG-SCHEMA.schemaId=` | 라우트 스키마 ID를 기능이 등록하지 않았다 (`searchSchema`도 같은 꼴) | 계약 스키마 메타 |
-| `FE-REG-API. has no executable consumer for operationId=` | V2 operation을 기능 `adapters/`·`application/`에서 쓰지 않는다 | 쓰지 않으면 V2 행을 지운다 |
+| `FE-REG-API. has no executable consumer for operationId=` | 계약의 operation을 기능 `adapters/`·`application/`에서 쓰지 않는다 | 쓰지 않으면 descriptor를 지운다 |
| `breaking change missing evidence: ` | 행을 빼거나 바꿨는데 승인이 없다 | `update:registry-baseline` 또는 `config/contracts/registry-change-evidence.json` |
| `stale breaking evidence : no breaking change in the current diff has this changeId. ...` | 지금 diff와 맞지 않는 증거 행 | 그 행을 지운다 |
| `registry baseline approval digest mismatch: approved= actual=` | 기준선 파일을 손으로 고쳤다 | `update:registry-baseline`으로 다시 찍는다 |
diff --git a/docs/manual/reference/global-ids.md b/docs/manual/reference/global-ids.md
index 0be8a5c3..cb4ca833 100644
--- a/docs/manual/reference/global-ids.md
+++ b/docs/manual/reference/global-ids.md
@@ -24,20 +24,19 @@
| `chunkId` | 계약 `routes` | `route-invoice-list` | `check:registries` (`duplicates chunkId=`) |
| `moduleId` | `routeRuntimeContracts`, 지연 페이지 표 | `invoice-list-page` | `check:registries` (FE-REG-ROUTE-RUNTIME) |
| `loadingSurface` | 계약 `routes` | `invoice-list` | 검사 없음 (형식만 본다) |
-| operation ID | V2 행, V3 descriptor, gateway | `INVOICE_LIST_ITEMS` | 모듈 로드 (`Duplicate API operation`), 계약 조립 (`duplicate operation`) |
-| API 경로 | V2 `path`, V3 `pathTemplate` | `/api/invoice-items` | 검사 없음. 백엔드 계약을 따른다 |
-| 스키마 ID | V2 스키마 메타, zod 검증기, codec | `InvoiceNoRequest`, `InvoiceItemListPayload`, `InvoiceProblem` | 모듈 로드 (`Invalid or duplicate schema definition`) |
-| mapper ID | V2 `mapperId`, 레지스트리 mapper | `InvoiceItemListMapper` | 모듈 로드 (`Invalid or duplicate boundary mapper`) |
+| operation ID | descriptor, gateway | `INVOICE_LIST_ITEMS` | 계약 조립 (`duplicate operation`) |
+| API 경로 | descriptor `pathTemplate` | `/api/invoice-items` | 검사 없음. 백엔드 계약을 따른다 |
+| 스키마 ID | 스키마 메타데이터, zod 검증기 | `InvoiceNoRequest`, `InvoiceItemListPayload`, `InvoiceProblem` | 모듈 로드 (`Invalid or duplicate schema definition`) |
| `contributionId` | 계약 기여 | `invoice-feature-http-v1` | 계약 조립 (`duplicate contributionId`) |
-| `policyId` | V3 `frontend` | `INVOICE_LIST_V1` | 검사 없음 |
-| `diagnosticsOperation` | V3 `frontend` | `invoice.list` | 검사 없음 |
+| `policyId` | descriptor `frontend` | `INVOICE_LIST_V1` | 검사 없음 |
+| `diagnosticsOperation` | descriptor `frontend` | `invoice.list` | 검사 없음 |
| 쿼리 namespace | 계약 `invalidation.namespaces`, 쿼리 바인딩 | `invoice-item` (버전 1) | 조립 (`Duplicate invalidation namespace`) |
| 무효화 topic | 계약 `invalidation.topics`, 뮤테이션 `invalidate` | `qinv.` + 무작위 26자 | 생성 명령이 설치된 topic과 비교, 조립 (`Duplicate invalidation topic`) |
| 쿼리·뮤테이션 `definitionId` | 쿼리 바인딩 | `invoice-item-list-v1` | 검사 없음 |
| 문구 키 | 기능 문구 catalog | `route.INVOICE_LIST.title`, `invoice.list.title` 등 | 생성 명령, 조립 (`Duplicate ko-KR message key`) |
| telemetry `kind` | application input | `invoice.list.failed` | 검사 없음 |
-| `owner` | V2 행, 스키마 메타, mapper | `feature-frontend-invoice-feature` | 검사 없음 |
-| 인증 프로필 ID | V2·V3 `authProfileId` | `EXTERNAL_BEARER` (템플릿 것을 씀) | 제품 프로필이 템플릿 ID를 쓰면 모듈 로드 (`reuses a template profile id`) |
+| `owner` | 스키마 메타데이터 | `feature-frontend-invoice-feature` | 검사 없음 |
+| 인증 프로필 ID | descriptor `frontend.authProfileId` | `EXTERNAL_BEARER` (템플릿 것을 씀) | 제품 프로필이 템플릿 ID를 쓰면 모듈 로드 (`reuses a template profile id`) |
| `navigationOrder` | 계약 `routes` | 설치된 최댓값 + 10 | 검사 없음. 같은 숫자가 둘이어도 통과 |
메시지 전체와 고칠 파일은 [errors.md](errors.md)에 있다.
diff --git a/docs/manual/reference/patterns.md b/docs/manual/reference/patterns.md
index 80171943..c8e49e09 100644
--- a/docs/manual/reference/patterns.md
+++ b/docs/manual/reference/patterns.md
@@ -77,12 +77,12 @@ const search = (q: string) =>
| 패턴 | 정의 | 예제 | 검사 |
|---|---|---|---|
-| V2 operation 행 | `src/contracts/api-operations.ts`의 `defineRestOperation` | 생성 뼈대 `contracts/-api-contract.ts` | `check:registries` (FE-REG-API) |
-| V3 HTTP 계약(실행) | `src/contracts/external-contract-runtime.ts` | 생성 뼈대 `contracts/-contract-contribution.ts` | 계약 조립, V2/V3 일치 테스트 |
+| HTTP 계약 | `src/contracts/external-contract-runtime.ts` | 생성 뼈대 `contracts/-contract-contribution.ts` | 계약 조립, `check:registries` (FE-REG-API 행은 `src/contracts/api-operations.ts`의 `projectApiOperationRows`가 뽑는다) |
+| 스키마 메타데이터 | `src/contracts/schema-registry.ts`의 `SchemaDefinition` | 생성 뼈대 `contracts/-schema-metadata.ts` | `check:registries` (FE-REG-SCHEMA) |
| 배포된 계약 패키지 출처 | 같은 파일의 `EXTERNAL_PACKAGE` | 생성 뼈대(자리표시자 또는 `--package` 신원). 실제 `@org-contracts/*` 패키지를 import하는 예제는 없음 | 계약 조립(신원 형식), 릴리스 승인(자리표시자) |
| 런타임 검증기 | `src/contracts/zod-validator.ts`의 `zodValidator` | 생성 뼈대 `contracts/-schemas.ts` | 스키마 ID 중복 |
| 검증 생략 | `src/contracts/unvalidated-payload.ts`의 `unvalidatedPayload` | 없음 (기능 예제) | 이유가 비면 throw, `listUnvalidatedPayloads`가 목록을 보임 |
-| DTO → 화면 값 mapper | `src/contracts/boundary-mapper.ts` | 생성 뼈대 `contracts/-mapper.ts` | mapper ID 중복 |
+| DTO → 화면 값 mapper | `src/contracts/boundary-mapper.ts`의 `BoundaryMappingResult` | 생성 뼈대 `contracts/-mapper.ts` | 타입 검사 |
| gateway port + HTTP 어댑터 | `src/adapters/http/index.ts`의 `createFeatureHttpBinding`, `defineFeatureHttpOperationForRoutes` | 생성 뼈대 `adapters/-http-gateway.ts` | 음성 타입 fixture (operation ID, route ID, 입력) |
| 문제 응답 → 업무 실패 | `mapProblem` (HTTP 바인딩) | 참조 기능 `adapters/reference-http-gateway.ts` (409, 422) | 기능 테스트 |
| 결과와 실패 | `src/contracts/result.ts`, `src/contracts/errors.ts` | 생성 뼈대 `application/-feature-api.ts` | `FailureKind` 닫힌 어휘(타입) |
diff --git a/docs/operations/api-contract-and-server-state-recovery.md b/docs/operations/api-contract-and-server-state-recovery.md
index 57bc2fc2..98c3391f 100644
--- a/docs/operations/api-contract-and-server-state-recovery.md
+++ b/docs/operations/api-contract-and-server-state-recovery.md
@@ -157,7 +157,7 @@ V3는 자격증명이 없거나(`UNAUTHENTICATED`), auth owner가 장애거나
fetch 없이 끝난다(`src/bootstrap/runtime-adapters.ts` `attachCredentials`,
`src/adapters/http/http-execution-v3.ts` credential patch 처리). 전송 0회 미인증은
diagnostics에만 남고 `api.request.failed`에는 세지 않는다(03-07). 그래도 무자격
-전송이 보이면 V3가 아닌 경로(V2 client 직접 조합, 외부 SDK)를 먼저 의심한다.
+전송이 보이면 V3가 아닌 경로(외부 SDK 직접 호출)를 먼저 의심한다.
점검:
diff --git a/scripts/create-feature.ts b/scripts/create-feature.ts
index 1be82543..b035bbf1 100644
--- a/scripts/create-feature.ts
+++ b/scripts/create-feature.ts
@@ -277,7 +277,7 @@ export function planFeature(
[`${feature}/contracts/${base}-feature-contract.ts`, renderFeatureContract(shape)],
[`${feature}/contracts/${base}-schemas.ts`, renderSchemas(shape)],
[`${feature}/contracts/${base}-mapper.ts`, renderMapper(shape)],
- [`${feature}/contracts/${base}-api-contract.ts`, renderApiContract(shape)],
+ [`${feature}/contracts/${base}-schema-metadata.ts`, renderSchemaMetadata(shape)],
[
`${feature}/contracts/${base}-contract-contribution.ts`,
renderContractContribution(shape),
@@ -369,9 +369,9 @@ function renderFeatureRuntime({ names }: Shape): string {
const { base, upper } = names;
return `import { defineFeatureRuntime } from "../feature-module.ts";
import { ${upper}_FEATURE_ADAPTER_CONTRIBUTION } from "./adapters/create-${base}-feature-input.ts";
-import { ${upper}_API_CONTRACT } from "./contracts/${base}-api-contract.ts";
import { ${upper}_CONTRACT_CONTRIBUTION } from "./contracts/${base}-contract-contribution.ts";
import { ${upper}_FEATURE_ID } from "./contracts/${base}-feature-contract.ts";
+import { ${upper}_SCHEMA_METADATA } from "./contracts/${base}-schema-metadata.ts";
/**
* The executable half. \`feature-module.ts\` imports this file dynamically, so
@@ -379,7 +379,7 @@ import { ${upper}_FEATURE_ID } from "./contracts/${base}-feature-contract.ts";
*/
export const FEATURE_RUNTIME = defineFeatureRuntime({
featureId: ${upper}_FEATURE_ID,
- apiContract: ${upper}_API_CONTRACT,
+ schemas: ${upper}_SCHEMA_METADATA,
adapters: [${upper}_FEATURE_ADAPTER_CONTRIBUTION],
contractContributions: [${upper}_CONTRACT_CONTRIBUTION],
} as const);
@@ -522,8 +522,7 @@ export const ${upper}_FEATURE_CONTRACT = Object.freeze({
function renderSchemas({ names }: Shape): string {
const { camel, pascal, upper } = names;
- return `import { runtimeSchemaCodecFromValidator } from "../../../contracts/schema-registry.ts";
-import { z } from "../../../contracts/zod.ts";
+ return `import { z } from "../../../contracts/zod.ts";
import { zodValidator } from "../../../contracts/zod-validator.ts";
/** The GET takes no input. Schema ids are global, so this one is prefixed too. */
@@ -564,28 +563,16 @@ export const ${upper}_VALIDATORS = Object.freeze({
),
${pascal}Problem: zodValidator("${pascal}Problem", ${camel}ProblemSchema),
});
-
-export const ${upper}_RUNTIME_SCHEMA_CODECS = Object.freeze({
- ${pascal}NoRequest: runtimeSchemaCodecFromValidator(${upper}_VALIDATORS.${pascal}NoRequest),
- ${pascal}ItemListPayload: runtimeSchemaCodecFromValidator(
- ${upper}_VALIDATORS.${pascal}ItemListPayload,
- ),
-});
`;
}
-function renderMapper({ names, owner }: Shape): string {
- const { base, camel, pascal, upper } = names;
+function renderMapper({ names }: Shape): string {
+ const { base, pascal } = names;
return `import {
- mappingFailure,
mappingSuccess,
type BoundaryMappingResult,
- type InstalledBoundaryMapper,
} from "../../../contracts/boundary-mapper.ts";
-import {
- ${camel}ItemListPayloadSchema,
- type ${pascal}ItemDto,
-} from "./${base}-schemas.ts";
+import type { ${pascal}ItemDto } from "./${base}-schemas.ts";
/** What the page shows. A wire field never reaches presentation by its wire name. */
export type ${pascal}ItemView = Readonly<{ itemId: string; name: string }>;
@@ -604,93 +591,37 @@ export function map${pascal}ItemList(
),
);
}
-
-/** The registry row (FE-REG-API). The registry is untyped, so it checks the shape. */
-export const ${upper}_BOUNDARY_MAPPERS = Object.freeze({
- ${pascal}ItemListMapper: Object.freeze({
- mapperId: "${pascal}ItemListMapper",
- mapperVersion: 1,
- inputSchemaId: "${pascal}ItemListPayload",
- outputContractId: "${pascal}ItemList",
- owner: "${owner}",
- maxOutputItems: 100,
- map(value: unknown) {
- const parsed = ${camel}ItemListPayloadSchema.safeParse(value);
- return parsed.success
- ? map${pascal}ItemList(parsed.data)
- : mappingFailure("MAPPING_INVARIANT_REJECTED");
- },
- }),
-} satisfies Readonly>);
`;
}
-function renderApiContract({ names, operationId, apiPath, owner }: Shape): string {
- const { base, pascal, upper } = names;
- return `import { defineRestOperation } from "../../../contracts/api-operations.ts";
-import { ${upper}_BOUNDARY_MAPPERS } from "./${base}-mapper.ts";
-import { ${upper}_RUNTIME_SCHEMA_CODECS } from "./${base}-schemas.ts";
-
-const OWNER = "${owner}";
+function renderSchemaMetadata({ names, owner }: Shape): string {
+ const { pascal, upper } = names;
+ return `const OWNER = "${owner}";
/**
- * The V2 API contract \`check:registries\` governs (FE-REG-API). The executable
- * descriptor of the same operation is in \`${base}-contract-contribution.ts\`;
- * tests/unit/http-operation-v2-v3-parity.test.ts fails when they disagree.
- * Runtime half only: \`feature-runtime.ts\` loads it.
+ * FE-REG-SCHEMA rows of the feature's schemas (\`check:registries\`). The HTTP
+ * operation is written once, in \`${names.base}-contract-contribution.ts\`;
+ * FE-REG-API rows are projected from it. Runtime half only:
+ * \`feature-runtime.ts\` loads it.
*/
-export const ${upper}_API_CONTRACT = Object.freeze({
- runtimeSchemas: ${upper}_RUNTIME_SCHEMA_CODECS,
- mappers: ${upper}_BOUNDARY_MAPPERS,
- schemas: Object.freeze({
- ${pascal}NoRequest: Object.freeze({
- schemaId: "${pascal}NoRequest",
- boundary: "api-request",
- owner: OWNER,
- runtime: "zod",
- schemaVersion: 1,
- direction: "REQUEST",
- unknownFieldPolicy: "REJECT_UNKNOWN",
- }),
- ${pascal}ItemListPayload: Object.freeze({
- schemaId: "${pascal}ItemListPayload",
- boundary: "api-response",
- owner: OWNER,
- runtime: "zod",
- schemaVersion: 1,
- direction: "RESPONSE",
- unknownFieldPolicy: "STRIP_UNKNOWN",
- }),
+export const ${upper}_SCHEMA_METADATA = Object.freeze({
+ ${pascal}NoRequest: Object.freeze({
+ schemaId: "${pascal}NoRequest",
+ boundary: "api-request",
+ owner: OWNER,
+ runtime: "zod",
+ schemaVersion: 1,
+ direction: "REQUEST",
+ unknownFieldPolicy: "REJECT_UNKNOWN",
}),
- apiOperations: Object.freeze({
- ${operationId}: defineRestOperation({
- method: "GET",
- path: "${apiPath}",
- operationId: "${operationId}",
- auth: "external-session",
- timeoutMs: null,
- idempotency: "safe",
- retry: "runtime",
- requestSource: "none",
- requestSchema: "${pascal}NoRequest",
- responseSchema: "${pascal}ItemListPayload",
- owner: OWNER,
- contractVersion: 2,
- protocol: "REST",
- semantics: "QUERY",
- replayPolicy: "SAFE",
- idempotencyKeyPolicy: "NONE",
- mapperId: "${pascal}ItemListMapper",
- successStatuses: [200],
- responseMediaTypes: ["application/json"],
- maxResponseBytes: 262_144,
- providerId: "PRIMARY_API",
- authProfileId: "EXTERNAL_BEARER",
- csrfProfileId: "NO_CSRF_BEARER",
- pathSchema: "${pascal}NoRequest",
- pathParameterNames: [],
- maxEncodedSearchBytes: 0,
- }),
+ ${pascal}ItemListPayload: Object.freeze({
+ schemaId: "${pascal}ItemListPayload",
+ boundary: "api-response",
+ owner: OWNER,
+ runtime: "zod",
+ schemaVersion: 1,
+ direction: "RESPONSE",
+ unknownFieldPolicy: "STRIP_UNKNOWN",
}),
} as const);
`;
@@ -713,7 +644,8 @@ import {
} from "./${base}-schemas.ts";
/**
- * The executable (V3) descriptor of ${operationId}. It belongs to the contract
+ * The HTTP descriptor of ${operationId}, the one place the operation is
+ * written: it executes, and FE-REG-API reads it. It belongs to the contract
* package pinned in \`${base}-feature-contract.ts\`: import \`@org-contracts/*\`
* only in this file (external-contract-package-single-import-path) and take
* the package's descriptor instead of this local one.
@@ -1038,12 +970,11 @@ export default function ${pascal}ListPage() {
}
function renderInputTest({ names, operationId }: Shape): string {
- const { base, pascal, upper } = names;
+ const { base, pascal } = names;
return `import { describe, expect, it, vi } from "vitest";
import { createFailure } from "../../../src/contracts/errors.ts";
import { create${pascal}FeatureInput } from "../../../src/features/${names.id}/application/${base}-feature-api.ts";
-import { ${upper}_BOUNDARY_MAPPERS } from "../../../src/features/${names.id}/contracts/${base}-mapper.ts";
import type { TelemetryPort } from "../../../src/platform/telemetry/telemetry-port.ts";
const ITEMS = Object.freeze([Object.freeze({ itemId: "item-1", name: "First item" })]);
@@ -1086,15 +1017,6 @@ describe("${names.id} application input", () => {
await expect(input.listItems()).resolves.toEqual({ ok: false, error: failure });
});
});
-
-describe("${names.id} registry mapper", () => {
- it("maps a list payload and rejects any other shape", () => {
- const { map } = ${upper}_BOUNDARY_MAPPERS.${pascal}ItemListMapper;
-
- expect(map([{ id: "item-1", name: "First item" }])).toEqual({ ok: true, value: ITEMS });
- expect(map({ items: [] })).toEqual({ ok: false, code: "MAPPING_INVARIANT_REJECTED" });
- });
-});
`;
}
diff --git a/scripts/scale/composition-workloads.ts b/scripts/scale/composition-workloads.ts
index adeb8646..24d44e15 100644
--- a/scripts/scale/composition-workloads.ts
+++ b/scripts/scale/composition-workloads.ts
@@ -76,7 +76,7 @@ export const COMPOSITION_WORKLOADS: readonly CompositionWorkload[] = Object.free
loadRuntime: async () =>
Object.freeze({
featureId: id,
- apiContract: Object.freeze({}),
+ schemas: Object.freeze({}),
adapters: Object.freeze([]),
contractContributions: Object.freeze([]),
}),
diff --git a/src/contracts/api-operations.ts b/src/contracts/api-operations.ts
index c333f26b..4d7b496c 100644
--- a/src/contracts/api-operations.ts
+++ b/src/contracts/api-operations.ts
@@ -1,226 +1,57 @@
-export type ApiOperation = Readonly<{
- method: string;
- path: string;
+import type {
+ HttpMethod,
+ InstalledContractContribution,
+ InstalledHttpContract,
+ ResponseEnvelope,
+ RetrySemantics,
+} from "./external-contract-runtime.ts";
+
+/**
+ * FE-REG-API. The governed row of one installed HTTP operation, projected
+ * from its V3 descriptor (`InstalledHttpContract`). A feature writes the
+ * operation once, in its contract contribution; `check:registries` compares
+ * these rows with the approved baseline.
+ */
+export type ApiOperationRow = Readonly<{
operationId: string;
- auth: "none" | "external-session";
- timeoutMs: number | null;
- idempotency: "safe" | "keyed" | "none";
- retry: "runtime" | "never";
- requestSource: "search" | "body" | "none";
+ featureId: string;
+ method: HttpMethod;
+ path: string;
+ authProfileId: string;
+ retrySemantics: RetrySemantics;
+ requestBody: InstalledHttpContract["contract"]["requestBody"];
+ responseBody: InstalledHttpContract["contract"]["responseBody"];
+ responseEnvelope: ResponseEnvelope;
requestSchema: string;
responseSchema: string;
- owner: string;
- contractVersion?: 2;
- protocol?: "REST";
- semantics?: "QUERY" | "COMMAND";
- replayPolicy?: "SAFE" | "IDEMPOTENT" | "KEYED_COMMAND" | "NON_REPLAYABLE";
- idempotencyKeyPolicy?: "NONE" | "REQUIRED";
- mapperId?: string;
- successStatuses?: readonly number[];
- responseMediaTypes?: readonly string[];
- maxResponseBytes?: number;
- providerId?: string;
- authProfileId?: string;
- csrfProfileId?: string;
- pathSchema?: string;
- pathParameterNames?: readonly string[];
- maxEncodedSearchBytes?: number;
+ problemSchema: string;
}>;
/**
- * 07-02. A V2 row is the declaration `check:registries` (FE-REG-API) governs;
- * it is not what executes. The executed copy of the same HTTP API is the V3
- * descriptor (`InstalledHttpContract`) in the feature's contract contribution.
- * A feature writes both, and `tests/unit/http-operation-v2-v3-parity.test.ts`
- * checks they name the same operations, method, path, statuses, limits, auth
- * profile, replay and write semantics, request body and schema ids. The
- * deadline is not compared: V2 `timeoutMs` is `null` while V3 always has one.
+ * Pass composed contributions (`composeContractContributions`): composition
+ * already refused duplicate operation ids and snapshotted every row.
*/
-export type RestOperationV2 = ApiOperation &
- Readonly<{
- contractVersion: 2;
- protocol: "REST";
- semantics: "QUERY" | "COMMAND";
- replayPolicy:
- | "SAFE"
- | "IDEMPOTENT"
- | "KEYED_COMMAND"
- | "NON_REPLAYABLE";
- idempotencyKeyPolicy: "NONE" | "REQUIRED";
- mapperId: string;
- successStatuses: readonly number[];
- responseMediaTypes: readonly string[];
- maxResponseBytes: number;
- providerId: string;
- authProfileId: string;
- csrfProfileId: string;
- pathSchema: string;
- pathParameterNames: readonly string[];
- maxEncodedSearchBytes: number;
- }>;
-
-const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
-const OPERATION_ID = /^[A-Z][A-Z0-9_]{2,79}$/;
-const MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/;
-
-export function defineRestOperation(
- operation: RestOperationV2,
-): RestOperationV2 {
- validateRestOperation(operation);
- return Object.freeze({
- ...operation,
- successStatuses: Object.freeze([...operation.successStatuses]),
- responseMediaTypes: Object.freeze([...operation.responseMediaTypes]),
- pathParameterNames: Object.freeze([...operation.pathParameterNames]),
- });
-}
-
-export function composeApiOperations(
- contributions: readonly Readonly>[],
-): Readonly> {
- const result: Record = Object.create(null);
+export function projectApiOperationRows(
+ contributions: readonly InstalledContractContribution[],
+): Readonly> {
+ const rows: Record = {};
for (const contribution of contributions) {
- for (const [registryId, operation] of Object.entries(contribution)) {
- if (registryId !== operation.operationId) {
- throw new TypeError("API operation registry key does not match operationId.");
- }
- if (Object.hasOwn(result, registryId)) {
- throw new TypeError(`Duplicate API operation: ${registryId}`);
- }
- if (operation.contractVersion === 2) {
- validateRestOperation(operation as RestOperationV2);
- }
- result[registryId] = operation;
+ for (const { contract, frontend } of contribution.http) {
+ rows[contract.operationId] = Object.freeze({
+ operationId: contract.operationId,
+ featureId: contribution.featureId,
+ method: contract.method,
+ path: contract.pathTemplate,
+ authProfileId: frontend.authProfileId,
+ retrySemantics: contract.retrySemantics,
+ requestBody: contract.requestBody,
+ responseBody: contract.responseBody,
+ responseEnvelope: contract.responseEnvelope ?? "NONE",
+ requestSchema: contract.inputValidator.schemaId,
+ responseSchema: contract.outputValidator.schemaId,
+ problemSchema: contract.problemValidator.schemaId,
+ });
}
}
- return Object.freeze(result);
-}
-
-export function validateApiRuntimeBindings(
- operations: Readonly>,
- schemaMetadata: Readonly>>,
- schemaCodecs: Readonly>>,
- mappers: Readonly<
- Record<
- string,
- Readonly<{ mapperId: string; inputSchemaId: string; maxOutputItems: number }>
- >
- >,
-): true {
- for (const operation of Object.values(operations)) {
- if (operation.contractVersion !== 2) continue;
- for (const schemaId of [
- operation.pathSchema,
- operation.requestSchema,
- operation.responseSchema,
- ]) {
- if (
- !schemaId ||
- schemaMetadata[schemaId]?.schemaId !== schemaId ||
- schemaCodecs[schemaId]?.schemaId !== schemaId
- ) {
- throw new TypeError(
- `Unresolved API schema binding: ${operation.operationId}`,
- );
- }
- }
- const mapper = mappers[operation.mapperId ?? ""];
- if (
- !mapper ||
- mapper.mapperId !== operation.mapperId ||
- mapper.inputSchemaId !== operation.responseSchema ||
- mapper.maxOutputItems < 1
- ) {
- throw new TypeError(
- `Unresolved API mapper binding: ${operation.operationId}`,
- );
- }
- }
- return true;
-}
-
-function validateRestOperation(operation: RestOperationV2): void {
- if (
- operation.protocol !== "REST" ||
- !OPERATION_ID.test(operation.operationId) ||
- !operation.owner ||
- !operation.mapperId ||
- !operation.providerId ||
- !operation.authProfileId ||
- !operation.csrfProfileId ||
- !operation.pathSchema ||
- !operation.path.startsWith("/") ||
- operation.path.startsWith("//") ||
- operation.path.includes("?") ||
- operation.path.includes("#") ||
- !Number.isSafeInteger(operation.maxResponseBytes) ||
- operation.maxResponseBytes < 1 ||
- operation.maxResponseBytes > MAX_RESPONSE_BYTES ||
- !Number.isSafeInteger(operation.maxEncodedSearchBytes) ||
- operation.maxEncodedSearchBytes < 0 ||
- operation.maxEncodedSearchBytes > 32_768 ||
- operation.successStatuses.length === 0 ||
- operation.successStatuses.some(
- (status) => !Number.isInteger(status) || status < 200 || status > 299,
- ) ||
- new Set(operation.successStatuses).size !== operation.successStatuses.length ||
- operation.responseMediaTypes.length === 0 ||
- operation.responseMediaTypes.some(
- (value) => !MEDIA_TYPE.test(value) || value !== value.toLowerCase(),
- )
- ) {
- throw new TypeError(`Invalid REST operation contract: ${operation.operationId}`);
- }
- const placeholders = [
- ...operation.path.matchAll(
- /:([A-Za-z][A-Za-z0-9_]*)|\{([A-Za-z][A-Za-z0-9_]*)\}/g,
- ),
- ]
- .map((match) => match[1] ?? match[2] ?? "")
- .sort();
- const codecKeys = [...operation.pathParameterNames].sort();
- if (
- new Set(codecKeys).size !== codecKeys.length ||
- placeholders.length !== codecKeys.length ||
- placeholders.some((name, index) => name !== codecKeys[index])
- ) {
- throw new TypeError(
- `REST path codec does not match its template: ${operation.operationId}`,
- );
- }
- const isQuery = operation.semantics === "QUERY";
- // R-7.4. CSRF need is decided from the method (rest-profiles), so a COMMAND
- // must use an unsafe method. Same binding as browser-rpc and the V3 runtime.
- if (
- !["QUERY", "COMMAND"].includes(operation.semantics) ||
- !["SAFE", "IDEMPOTENT", "KEYED_COMMAND", "NON_REPLAYABLE"].includes(
- operation.replayPolicy,
- ) ||
- (!isQuery && !["POST", "PUT", "PATCH", "DELETE"].includes(operation.method)) ||
- (isQuery && !["GET", "HEAD"].includes(operation.method)) ||
- (isQuery && !["SAFE", "IDEMPOTENT"].includes(operation.replayPolicy)) ||
- (operation.replayPolicy === "KEYED_COMMAND" &&
- (operation.idempotencyKeyPolicy !== "REQUIRED" ||
- operation.idempotency !== "keyed")) ||
- (operation.replayPolicy === "NON_REPLAYABLE" &&
- (operation.retry !== "never" || operation.idempotency !== "none"))
- ) {
- throw new TypeError(`Incoherent REST replay contract: ${operation.operationId}`);
- }
-}
-
-export const API_OPERATIONS: Readonly> =
- Object.freeze({});
-
-export function getApiOperation(
- operationId: string,
- operations: Readonly> = API_OPERATIONS,
-): ApiOperation {
- const selected = Object.hasOwn(operations, operationId)
- ? operations[operationId]
- : undefined;
- if (!selected) {
- throw new Error(`Unregistered API operation: ${operationId}`);
- }
- return selected;
+ return Object.freeze(rows);
}
diff --git a/src/contracts/realtime-streams.ts b/src/contracts/realtime-streams.ts
index d920640e..b99a8470 100644
--- a/src/contracts/realtime-streams.ts
+++ b/src/contracts/realtime-streams.ts
@@ -1,4 +1,4 @@
-import type { ApiOperation } from "./api-operations.ts";
+import type { ApiOperationRow } from "./api-operations.ts";
import type { InstalledBoundaryMapper } from "./boundary-mapper.ts";
import type { RuntimeSchemaCodec } from "./schema-registry.ts";
import {
@@ -105,7 +105,7 @@ export type RealtimeEventTypeRegistration = Readonly<{
export type RealtimePolicyRegistryBindings = Readonly<{
schemaCodecs: Readonly>;
mappers: Readonly>;
- apiOperations: Readonly>;
+ apiOperations: Readonly>;
endpointIds: readonly RealtimeEndpointId[];
effectProfileIds: readonly ExternalEventEffectProfileId[];
killSwitchIds: readonly KillSwitchId[];
@@ -467,11 +467,9 @@ function validSnapshotBindings(
OWNED_ID.test(input.checkpointCodecId) &&
bindings.schemaCodecs[input.checkpointCodecId]?.schemaId ===
input.checkpointCodecId &&
- operation?.contractVersion === 2 &&
- operation.protocol === "REST" &&
- operation.semantics === "QUERY" &&
- (operation.replayPolicy === "SAFE" ||
- operation.replayPolicy === "IDEMPOTENT")
+ operation?.method === "GET" &&
+ (operation.retrySemantics === "SAFE" ||
+ operation.retrySemantics === "IDEMPOTENT")
);
}
diff --git a/src/contracts/rest-profiles.ts b/src/contracts/rest-profiles.ts
index ea7e9af1..349c3957 100644
--- a/src/contracts/rest-profiles.ts
+++ b/src/contracts/rest-profiles.ts
@@ -3,19 +3,10 @@ import {
type ReadOnlyRegistry,
} from "./read-only-registry.ts";
import { snapshotExactArray, snapshotExactObject } from "./exact-snapshot.ts";
-import { isLoopbackHostname } from "./deployment-admission.ts";
import { PRODUCT_REST_AUTH_PROFILES } from "./product-contracts.ts";
export type FetchCredentialsMode = "omit" | "same-origin" | "include";
-export type RestProviderProfile = Readonly<{
- providerId: string;
- baseUrl: string;
- allowedCredentialsModes: readonly FetchCredentialsMode[];
- redirect: "error";
- referrerPolicy: "no-referrer";
-}>;
-
/**
* VD-23. The complete closed set of headers a credential owner may contribute.
* Transport-owned headers (`accept`, `content-type`, `idempotency-key`) and
@@ -57,12 +48,6 @@ export type InstalledRestAuthProfiles = ReadOnlyRegistry<
RestAuthProfile
>;
-export type RestCsrfProfile = Readonly<{
- csrfProfileId: string;
- mode: "NONE" | "HEADER";
- headerName: "x-csrf-token" | null;
-}>;
-
const EXTERNAL_BEARER = Object.freeze({
authProfileId: "EXTERNAL_BEARER",
transport: "BEARER_HEADER",
@@ -213,35 +198,7 @@ export function installRestAuthProfileRegistry(
if (installed.size === 0) {
throw new TypeError("REST auth profile registry cannot be empty.");
}
- const registry = createReadOnlyRegistry(installed);
- INSTALLED_REGISTRIES.add(registry);
- return registry;
-}
-
-/** Registries this module installed, as opposed to look-alike objects. */
-const INSTALLED_REGISTRIES = new WeakSet