Files
clean-architecture-frontend…/src/contracts/runtime-capabilities.ts
T
DongHyeonkaandClaude Opus 5.5 abaaa9c773 fix(contracts): return read-only indexes and frozen row snapshots (Q-6.7-7)
indexInvalidationRegistry and indexInvalidationTopicVersions froze only
the wrapper object, so `.clear()` on the returned Map emptied a
validated fan-out. validateWebWorkerContributions,
validateOfflineCommandContribution and validateRealtimeContributions
froze only the outer array and returned the caller's rows, so a later
write could raise a deadline, request byte bound or polling interval
that had already been checked.

read-only-registry.ts gains createReadOnlyMap (same private-store
facade, typed ReadonlyMap so the public index types do not change;
forEach now also passes the map argument). The three contribution
validators snapshot every row (exact keys, arrays by index) with
exact-snapshot.ts, validate the snapshot and return it frozen.

Behavior: contribution rows with extra keys, accessors or non-plain
prototypes are now rejected (template registries are empty today).

Verified: new tests/unit/contract-index-immutability.test.ts (5 cases,
all RED before); gates green except the known removal-fixture test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:45:37 +09:00

350 lines
11 KiB
TypeScript

import type { InstalledOfflineCommandContribution } from "./offline-command.ts";
import type { InstalledServiceWorkerSelection } from "./service-worker.ts";
import type { InstalledWebWorkerContribution } from "./web-worker.ts";
import {
exactOwnDataSnapshot,
ownDataValue,
snapshotExactArray,
} from "./exact-snapshot.ts";
/**
* §3.4–§3.6. Optional runtime capability selection and hosting.
*
* Source contribution decides what is installed. Runtime Config may only carry
* `DEFAULT | DISABLED`, so a configuration document can never switch on a
* capability whose source is absent.
*/
export type RuntimeCapabilityOverride = "DEFAULT" | "DISABLED";
export type RuntimeStopReason =
| "APPLICATION_SHUTDOWN"
| "SCOPE_FENCED"
| "FEATURE_DISABLED"
| "HIDDEN_POLICY"
| "INCIDENT_CONTAINMENT";
export interface RuntimeLifecycle {
start(): void | Promise<void>;
stop(reason: RuntimeStopReason): void | Promise<void>;
dispose(): void | Promise<void>;
}
/** §20.2. `FAILED -> STARTING` is never automatic. */
export type RuntimeLifecycleState =
| "NEW"
| "STARTING"
| "RUNNING"
| "STOPPING"
| "STOPPED"
| "FAILED"
| "DISPOSING"
| "DISPOSED";
/** §22.12. Health is per capability; there is no global `healthy` boolean. */
export type RuntimeHealth =
| "AVAILABLE"
| "DEGRADED"
| "UNAVAILABLE"
| "INCOMPATIBLE"
| "DISABLED";
// §13.2. Realtime product contribution.
export type RealtimeEffectKind =
| "INVALIDATE_TOPICS"
| "APPLY_AUTHORITATIVE_DELTA"
| "EPHEMERAL_NOTIFICATION";
export interface InstalledRealtimeEventEffect {
readonly eventType: string;
readonly mapperId: string;
readonly effect: RealtimeEffectKind;
readonly invalidationTopics: readonly string[];
}
export type InstalledRealtimeTransport =
| Readonly<{ kind: "SSE"; endpointId: string }>
| Readonly<{ kind: "WEBSOCKET"; endpointId: string }>
| Readonly<{ kind: "POLLING"; operationId: string; intervalMs: number }>;
export interface InstalledRealtimeContribution {
readonly contributionId: string;
readonly featureId: string;
readonly contractSourcePackageId: string;
readonly streamId: string;
readonly recoveryMode: "CURSOR" | "SNAPSHOT_ONLY" | "SESSION_REBUILD";
readonly eventEffects: readonly InstalledRealtimeEventEffect[];
readonly transport: InstalledRealtimeTransport;
}
export const REALTIME_CONTRIBUTION_BOUNDS = Object.freeze({
contributions: 64,
streams: 128,
eventTypes: 512,
effectsPerEvent: 8,
invalidationTopicsPerEvent: 32,
minimumPollingIntervalMs: 5_000,
maximumPollingIntervalMs: 300_000,
});
export interface InstalledRuntimeCapabilities {
readonly realtime: readonly InstalledRealtimeContribution[];
readonly webWorkers: readonly InstalledWebWorkerContribution[];
readonly serviceWorker: InstalledServiceWorkerSelection | null;
readonly offlineCommands: InstalledOfflineCommandContribution | null;
}
export type CapabilityOverrideMap = Readonly<{
REALTIME: RuntimeCapabilityOverride;
WEB_WORKER: RuntimeCapabilityOverride;
SERVICE_WORKER: RuntimeCapabilityOverride;
OFFLINE_COMMANDS: RuntimeCapabilityOverride;
}>;
/**
* The effective selection after applying runtime overrides. `serviceWorkerMode`
* keeps the §3.6 persistent-registration exception explicit: a statically
* `ACTIVE` worker that runtime config disables still performs exactly one
* owned-registration lookup and at most one unregister, and deletes no cache.
*/
export type ResolvedRuntimeCapabilities = Readonly<{
realtime: readonly InstalledRealtimeContribution[];
webWorkers: readonly InstalledWebWorkerContribution[];
serviceWorker: InstalledServiceWorkerSelection | null;
serviceWorkerDisabledCleanup: boolean;
offlineCommands: InstalledOfflineCommandContribution | null;
}>;
export function resolveRuntimeCapabilities(
installed: InstalledRuntimeCapabilities,
overrides: CapabilityOverrideMap,
): ResolvedRuntimeCapabilities {
const realtimeDisabled = overrides.REALTIME === "DISABLED";
const workersDisabled = overrides.WEB_WORKER === "DISABLED";
const serviceWorkerDisabled = overrides.SERVICE_WORKER === "DISABLED";
const offlineDisabled = overrides.OFFLINE_COMMANDS === "DISABLED";
return Object.freeze({
realtime: realtimeDisabled ? Object.freeze([]) : installed.realtime,
webWorkers: workersDisabled ? Object.freeze([]) : installed.webWorkers,
serviceWorker: serviceWorkerDisabled ? null : installed.serviceWorker,
serviceWorkerDisabledCleanup:
serviceWorkerDisabled && installed.serviceWorker?.mode === "ACTIVE",
offlineCommands: offlineDisabled ? null : installed.offlineCommands,
});
}
const REALTIME_CONTRIBUTION_KEYS = Object.freeze([
"contributionId",
"featureId",
"contractSourcePackageId",
"streamId",
"recoveryMode",
"eventEffects",
"transport",
] as const);
const EVENT_EFFECT_KEYS = Object.freeze([
"eventType",
"mapperId",
"effect",
"invalidationTopics",
] as const);
const ENDPOINT_TRANSPORT_KEYS = Object.freeze(["kind", "endpointId"] as const);
const POLLING_TRANSPORT_KEYS = Object.freeze([
"kind",
"operationId",
"intervalMs",
] as const);
function invalidRealtime(detail: string): never {
throw new TypeError(`Realtime contribution is not exact: ${detail}`);
}
function snapshotTransport(source: unknown): InstalledRealtimeTransport {
const polling = ownDataValue(source, "kind") === "POLLING";
const keys = polling ? POLLING_TRANSPORT_KEYS : ENDPOINT_TRANSPORT_KEYS;
const transport = exactOwnDataSnapshot<Record<string, unknown>>(
source,
keys,
keys,
invalidRealtime,
) as InstalledRealtimeTransport;
// The key set was chosen by one read; the snapshot must agree with it.
if ((transport.kind === "POLLING") !== polling) invalidRealtime("transport");
return transport;
}
function snapshotEventEffect(source: unknown): InstalledRealtimeEventEffect {
const effect = exactOwnDataSnapshot<InstalledRealtimeEventEffect>(
source,
EVENT_EFFECT_KEYS,
EVENT_EFFECT_KEYS,
invalidRealtime,
);
const topics =
snapshotExactArray(effect.invalidationTopics) ??
invalidRealtime("invalidationTopics");
return Object.freeze({
...effect,
invalidationTopics: topics as readonly string[],
});
}
/**
* Q-6.7-7. Validates and returns owned frozen snapshots, so a later write to
* the caller's row cannot change a polling interval or topic list that was
* already checked.
*/
export function validateRealtimeContributions(
source: readonly InstalledRealtimeContribution[],
): readonly InstalledRealtimeContribution[] {
const bounds = REALTIME_CONTRIBUTION_BOUNDS;
const rows = snapshotExactArray(source) ?? invalidRealtime("array required");
if (rows.length > bounds.contributions) {
throw new TypeError("Realtime contributions exceed their bound.");
}
const contributionIds = new Set<string>();
const streamIds = new Set<string>();
let eventTypeCount = 0;
const installed: InstalledRealtimeContribution[] = [];
for (const row of rows) {
const outer = exactOwnDataSnapshot<InstalledRealtimeContribution>(
row,
REALTIME_CONTRIBUTION_KEYS,
REALTIME_CONTRIBUTION_KEYS,
invalidRealtime,
);
const effectRows =
snapshotExactArray(outer.eventEffects) ??
invalidRealtime("eventEffects");
const contribution: InstalledRealtimeContribution = Object.freeze({
...outer,
eventEffects: Object.freeze(effectRows.map(snapshotEventEffect)),
transport: snapshotTransport(outer.transport),
});
if (
!contribution.contributionId ||
contributionIds.has(contribution.contributionId)
) {
throw new TypeError("Duplicate realtime contribution identity.");
}
contributionIds.add(contribution.contributionId);
streamIds.add(contribution.streamId);
if (streamIds.size > bounds.streams) {
throw new TypeError("Realtime streams exceed their bound.");
}
const transport = contribution.transport;
if (transport.kind === "POLLING") {
if (
!Number.isSafeInteger(transport.intervalMs) ||
transport.intervalMs < bounds.minimumPollingIntervalMs ||
transport.intervalMs > bounds.maximumPollingIntervalMs
) {
throw new TypeError(
`Realtime polling interval is out of range: ${contribution.contributionId}`,
);
}
}
const seenEvents = new Map<string, number>();
for (const effect of contribution.eventEffects) {
eventTypeCount += 1;
if (eventTypeCount > bounds.eventTypes) {
throw new TypeError("Realtime event types exceed their bound.");
}
const count = (seenEvents.get(effect.eventType) ?? 0) + 1;
if (count > bounds.effectsPerEvent) {
throw new TypeError(
`Realtime effects per event exceeded: ${effect.eventType}`,
);
}
seenEvents.set(effect.eventType, count);
if (
effect.invalidationTopics.length > bounds.invalidationTopicsPerEvent
) {
throw new TypeError(
`Realtime invalidation topics exceeded: ${effect.eventType}`,
);
}
if (
effect.effect === "INVALIDATE_TOPICS" &&
effect.invalidationTopics.length === 0
) {
throw new TypeError(
`INVALIDATE_TOPICS effect declares no topic: ${effect.eventType}`,
);
}
}
installed.push(contribution);
}
return Object.freeze(installed);
}
export type RuntimeCapabilityId =
| "REALTIME"
| "WEB_WORKER"
| "SERVICE_WORKER"
| "OFFLINE_COMMANDS";
/**
* §3.5. A bounded, serialisable view of one capability. `selected` is the
* static SSOT count and `active` is what survived the runtime override, so the
* difference between the two is exactly the operator's effect. An override can
* only subtract, which is why a never-selected capability stays at zero.
*/
export type RuntimeCapabilityStatus = Readonly<{
capabilityId: RuntimeCapabilityId;
selected: number;
active: number;
override: RuntimeCapabilityOverride;
}>;
export type RuntimeCapabilitySnapshot = readonly RuntimeCapabilityStatus[];
const CAPABILITY_ORDER = Object.freeze([
"REALTIME",
"WEB_WORKER",
"SERVICE_WORKER",
"OFFLINE_COMMANDS",
] as const);
export function describeRuntimeCapabilities(
installed: InstalledRuntimeCapabilities,
overrides: CapabilityOverrideMap,
): RuntimeCapabilitySnapshot {
const resolved = resolveRuntimeCapabilities(installed, overrides);
const counts: Readonly<
Record<RuntimeCapabilityId, Readonly<{ selected: number; active: number }>>
> = Object.freeze({
REALTIME: Object.freeze({
selected: installed.realtime.length,
active: resolved.realtime.length,
}),
WEB_WORKER: Object.freeze({
selected: installed.webWorkers.length,
active: resolved.webWorkers.length,
}),
SERVICE_WORKER: Object.freeze({
selected: installed.serviceWorker === null ? 0 : 1,
active: resolved.serviceWorker === null ? 0 : 1,
}),
OFFLINE_COMMANDS: Object.freeze({
selected: installed.offlineCommands === null ? 0 : 1,
active: resolved.offlineCommands === null ? 0 : 1,
}),
});
return Object.freeze(
CAPABILITY_ORDER.map((capabilityId) =>
Object.freeze({
capabilityId,
selected: counts[capabilityId].selected,
active: counts[capabilityId].active,
override: overrides[capabilityId],
}),
),
);
}