chore(review): 1103 계약·레지스트리 조치 브랜치를 합친다

Refs: docs/reviews/2026-11-03-maturity-review/README.md 07-01~07-04 13-04 14-06
This commit is contained in:
DongHyeonka
2026-11-04 21:28:13 +09:00
24 changed files with 1060 additions and 42 deletions
+87
View File
@@ -1,16 +1,40 @@
import type {
CommandEffectDescriptor,
CommandRecoveryDescriptor,
HttpMethod,
InstalledContractContribution,
InstalledHttpContract,
ResponseEnvelope,
RetrySemantics,
RuntimeValidator,
} from "./external-contract-runtime.ts";
import type { TrafficBudget } from "../platform/traffic/traffic-budget.ts";
/**
* 1103/07-01. The data of a command effect descriptor. Its classifiers are
* behaviour and stay out of the row; what the row keeps is whether the
* descriptor answers 401, 403 and 429 itself, and the problem codes it names
* as refused before any write when it names them.
*/
export type ApiCommandEffectRow = Readonly<{
classifiesStatus: boolean;
refusedBeforeWrite?: readonly string[];
}>;
/** A validator slot whose validation is skipped (`unvalidatedPayload`). */
export type ApiUnvalidatedSlot = "input" | "output" | "problem";
/**
* 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.
*
* 1103/07-01. The row carries every wire-facing value of the descriptor:
* what is sent and accepted, the bounds, and the retry and command data. The
* governance grades a change (`config/contracts/registry-governance.json`).
* Only functions stay out (`projectRequest`, the validators' parsing, the
* command effect classifiers), with the policy and diagnostics names.
*/
export type ApiOperationRow = Readonly<{
operationId: string;
@@ -25,6 +49,17 @@ export type ApiOperationRow = Readonly<{
requestSchema: string;
responseSchema: string;
problemSchema: string;
acceptedStatuses: readonly number[];
emptyBodyStatuses: readonly number[];
/** Validator slots that skip validation by name; `[]` when all validate. */
unvalidated: readonly ApiUnvalidatedSlot[];
requestByteLimit: number;
responseByteLimit: number;
totalDeadlineMs: number;
retryBudget: 0 | 1 | 2;
traffic: TrafficBudget | null;
commandEffect: ApiCommandEffectRow | null;
commandRecovery: CommandRecoveryDescriptor | null;
}>;
/**
@@ -50,8 +85,60 @@ export function projectApiOperationRows(
requestSchema: contract.inputValidator.schemaId,
responseSchema: contract.outputValidator.schemaId,
problemSchema: contract.problemValidator.schemaId,
acceptedStatuses: Object.freeze([...contract.acceptedStatuses]),
emptyBodyStatuses: Object.freeze([...contract.emptyBodyStatuses]),
unvalidated: unvalidatedSlots({
input: contract.inputValidator,
output: contract.outputValidator,
problem: contract.problemValidator,
}),
requestByteLimit: frontend.requestByteLimit,
responseByteLimit: frontend.responseByteLimit,
totalDeadlineMs: frontend.totalDeadlineMs,
retryBudget: frontend.retryBudget,
traffic:
frontend.traffic === undefined
? null
: Object.freeze({
maxPhysicalRequests: frontend.traffic.maxPhysicalRequests,
maxRetries: frontend.traffic.maxRetries,
maxConcurrentRequests: frontend.traffic.maxConcurrentRequests,
maxQueuedRequests: frontend.traffic.maxQueuedRequests,
}),
commandEffect: commandEffectRow(contract.commandEffect),
commandRecovery:
contract.commandRecovery === null
? null
: Object.freeze({ ...contract.commandRecovery }),
});
}
}
return Object.freeze(rows);
}
/** The same marker rule as `listUnvalidatedPayloads`: any marker counts. */
function unvalidatedSlots(
validators: Readonly<Record<ApiUnvalidatedSlot, RuntimeValidator<unknown>>>,
): readonly ApiUnvalidatedSlot[] {
return Object.freeze(
(Object.keys(validators) as ApiUnvalidatedSlot[]).filter(
(slot) => validators[slot].validation !== undefined,
),
);
}
function commandEffectRow(
effect: CommandEffectDescriptor<unknown> | null,
): ApiCommandEffectRow | null {
if (effect === null) return null;
// Read structurally: a descriptor that does not name refused codes has no
// such list, and the row then has no such field.
const refused: unknown = (effect as Readonly<{ refusedBeforeWrite?: unknown }>)
.refusedBeforeWrite;
return Object.freeze({
classifiesStatus: typeof effect.classifyStatus === "function",
...(Array.isArray(refused)
? { refusedBeforeWrite: Object.freeze(refused.map(String)) }
: {}),
});
}
+16 -5
View File
@@ -41,6 +41,12 @@ export type EnvironmentDefinition = Readonly<{
defaultValue: unknown;
}>;
/**
* FE-REG-ENV. A runtime row states its key as `runtimeConfigV2ArtifactSchema`
* (`release-artifacts.ts`) reads it: `required` when config.json must carry
* the key, and `defaultValue` the value the schema gives an absent key, or
* `null` when it gives none (1103/13-04, tests/unit/env-registry-coverage).
*/
export const ENV_REGISTRY = Object.freeze(withProductRows({
// F-6. Required: a staging or production build fails without it
// (scripts/generate-runtime-config.ts). Local and development builds fall
@@ -53,20 +59,25 @@ export const ENV_REGISTRY = Object.freeze(withProductRows({
API_BASE_URL: runtime("public-sensitive", true, null),
REQUEST_TIMEOUT_MS: runtime("public", false, 10_000),
MAX_RETRY_ATTEMPTS: runtime("public", false, 2),
TELEMETRY_ENABLED: runtime("public", true, false),
TELEMETRY_ENABLED: runtime("public", true, null),
TELEMETRY_ENDPOINT: runtime("public-sensitive", false, null),
AUTH_MODE: runtime("public", true, "external"),
AUTH_MODE: runtime("public", true, null),
CONFIG_SCHEMA_VERSION: runtime("public", true, null),
RELEASE_MANIFEST_URL: runtime("public", true, "/release-manifest.json"),
RELEASE_MANIFEST_URL: runtime("public", false, "/release-manifest.json"),
// F-6. The release identity the build writes into config.json. It must match
// the deployed HTML and release manifest, or boot stops with
// CONFIG_BUILD_MISMATCH (scripts/check-release-admission.ts).
RELEASE_ID: runtime("public-metadata", false, null),
BUILD_ID: runtime("public-metadata", false, null),
// §3.5: overrides may only disable an installed capability, never enable one.
CAPABILITY_OVERRIDES: runtime("public", false, null),
CAPABILITY_OVERRIDES: runtime("public", false, Object.freeze({
REALTIME: "DEFAULT",
WEB_WORKER: "DEFAULT",
SERVICE_WORKER: "DEFAULT",
OFFLINE_COMMANDS: "DEFAULT",
})),
// §3.5: likewise for features — subtractive, keyed by installed feature id.
FEATURE_OVERRIDES: runtime("public", false, null),
FEATURE_OVERRIDES: runtime("public", false, Object.freeze({})),
// §3.5: build-time narrowing of the product manifest, applied by
// scripts/generate-product-feature-index.ts (09-02). A feature left out here
// is not imported by any registry and never reaches the bundle.
+17
View File
@@ -118,10 +118,27 @@ export type FailureEffectCertainty =
| "APPLIED_CONFIRMED"
| "MAYBE_APPLIED";
/**
* 1101/07-05. The failure that crosses an application input boundary: a
* gateway result, a query or mutation error. Its `kind` is the closed set
* above. `AppError` (`src/platform/errors/app-error.ts`) is the other
* vocabulary: an open `owner.reason` kind a feature uses inside its own
* domain, mapped from an `AppFailure` where the feature needs it. Neither
* changes how a request is retried; the HTTP executor follows the
* operation's `retrySemantics` and `retryBudget`.
*/
export type AppFailure = Readonly<{
kind: FailureKind;
code: string;
httpStatus?: number;
/**
* Whether sending the same operation again is safe as far as this failure
* tells: the registry default, forced `false` once a write may have
* applied. Nothing in src reads it today. What the screen offers is
* `action`: `"retry"` shows a retry button even when this is `false`
* (`CONFLICT`, `QUERY_CACHE_FAILURE`): the user, not the runtime, sends
* again.
*/
retryable: boolean;
operationId: string;
attemptCount: number;
@@ -127,6 +127,15 @@ export function mappingViolation(code: string): MappingResult<never> {
});
}
/**
* 1101/07-07. How the package says a write whose result is unknown can be
* settled: resend with the same idempotency key, or read the operation back
* through `inspectOperationId`. Composition requires one on a KEYED command,
* and FE-REG-API records it. The HTTP executor does not read it: a write
* that ends `MAYBE_APPLIED` comes back to the feature, and the feature's
* gateway decides whether to resend or inspect (closed-deep-design.md
* §4.4 under docs/architecture).
*/
export type CommandRecoveryDescriptor = Readonly<{
mode: "IDEMPOTENCY_REPLAY" | "INSPECT_OPERATION";
operationIdentityField: string;
@@ -510,6 +519,17 @@ function assertHttpContract(
if (contract.requestBody !== "NONE") {
fail(`${label}: read operations carry no request body`);
}
// 1103/07-01 (c). The executor runs a read as a read whatever it is
// declared; KEYED or NEVER here only looks like a decision the executor
// never makes. A realtime snapshot binding reads the same pair.
if (
contract.retrySemantics !== "SAFE" &&
contract.retrySemantics !== "IDEMPOTENT"
) {
fail(
`${label}: ${contract.method} is a read; its retrySemantics is SAFE or IDEMPOTENT, not ${contract.retrySemantics}`,
);
}
} else {
if (!contract.commandEffect) {
fail(`${label}: command operations require a command effect descriptor`);