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:
@@ -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
@@ -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.
|
||||
|
||||
@@ -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`);
|
||||
|
||||
Reference in New Issue
Block a user