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>
350 lines
11 KiB
TypeScript
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],
|
|
}),
|
|
),
|
|
);
|
|
}
|