Files
rea/src/domain/replayMachineRuntime.ts
T
morlutoandGitHub b8a9da0c0f refactor(mcp): make analysis states unrepresentable (#468)
* refactor(config): parse capability settings into exact states

* refactor(runtime): encode replay and process outcomes exactly

* refactor: make analysis states unrepresentable

* refactor(mcp): register canonical schemas with SDK

* fix: preserve capability and catalog invariants

* fix(build): remove stale compiled modules

* fix(replay): update real verifier policy dependency

* fix(package): verify the complete MCP catalog

* fix(test): supply complete replay reload policy

* refactor(contracts): centralize output schema lookup

* refactor(mcp): delegate protocol boundaries to SDK

* fix(browser): approve real source capture

* fix(mcp): preserve catalog guidance
2026-08-10 02:28:11 +08:00

439 lines
13 KiB
TypeScript

import canonicalize from "canonicalize";
import { z } from "zod";
import type { ReplayMachine } from "./replayMachine.js";
type ReplayTransition = ReplayMachine["transitions"][number];
type ReplayValueSource = ReplayTransition["captures"][number]["value"];
interface TransitionRecordOptions {
readonly sequence: number;
readonly atMs: number;
readonly stateBefore: string;
readonly transition: ReplayTransition;
readonly captures: readonly {
readonly variable: string;
readonly sensitive: boolean;
}[];
}
/** One bounded inbound protocol event offered to a replay machine. */
const replayEventHeadersSchema = z
.record(
z
.string()
.min(1)
.max(256)
.regex(/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u),
z
.string()
.max(8_192)
.regex(/^[\t\x20-\x7e\x80-\xff]*$/u),
)
.superRefine((headers, context) => {
const normalized = Object.keys(headers).map((name) => name.toLowerCase());
if (new Set(normalized).size !== normalized.length)
context.addIssue({
code: "custom",
message: "replay event headers must be unique ignoring case",
input: headers,
});
});
const replayEventFields = {
at_ms: z.number().int().safe().nonnegative(),
path: z.string().startsWith("/").max(8_192),
headers: replayEventHeadersSchema,
body: z.string().max(1_000_000),
};
export const replayMachineEventSchema = z.discriminatedUnion("protocol", [
z.strictObject({
protocol: z.literal("http"),
connection: z.literal("not_applicable"),
method: z
.string()
.min(1)
.max(16)
.transform((method) => method.toUpperCase()),
...replayEventFields,
}),
z.strictObject({
protocol: z.literal("websocket_connect"),
connection: z.enum(["initial", "reconnect"]),
method: z.null(),
...replayEventFields,
}),
z.strictObject({
protocol: z.literal("websocket_message"),
connection: z.enum(["initial", "reconnect"]),
method: z.null(),
...replayEventFields,
}),
]);
/** One bounded inbound protocol event offered to a replay machine. */
export interface ReplayMachineEvent {
readonly protocol: "http" | "websocket_connect" | "websocket_message";
readonly connection: "not_applicable" | "initial" | "reconnect";
readonly at_ms: number;
readonly recorded_at_ms?: number;
readonly method: string | null;
readonly path: string;
readonly headers: Readonly<Record<string, string>>;
readonly body: string;
}
/** Runtime counters committed only for events admitted by all machine limits. */
export interface ReplayMachineUsage {
readonly events: number;
readonly transitions: number;
readonly connections: number;
readonly messages: number;
readonly bytes: number;
readonly last_at_ms: number;
}
/** Persistable transition journal entry containing aliases, never secrets. */
export interface ReplayTransitionRecord {
readonly sequence: number;
readonly at_ms: number;
readonly transition_id: string;
readonly state_before: string;
readonly state_after: string;
readonly sensitive_aliases: readonly string[];
}
/** Result of dispatching one event through a replay machine. */
export type ReplayMachineDecision =
| {
readonly outcome: "matched";
readonly actions: ReplayTransition["actions"];
readonly transition: ReplayTransitionRecord;
}
| {
readonly outcome:
| "unmatched"
| "invalid_state"
| "guard_failed"
| "transition_exhausted"
| "invalid_capture"
| "unexpected_reconnect"
| "limit_exhausted";
readonly actions: readonly [];
readonly transition: null;
};
const parseJson = (value: string): unknown => {
try {
const parsed: unknown = JSON.parse(value);
return parsed;
} catch {
return undefined;
}
};
const atPath = (
value: unknown,
path: readonly (string | number)[],
): unknown => {
let current = value;
for (const segment of path) {
if (typeof segment === "number") {
if (!Array.isArray(current)) return undefined;
current = current[segment];
continue;
}
if (
typeof current !== "object" ||
current === null ||
!Object.hasOwn(current, segment)
)
return undefined;
const next: unknown = Reflect.get(current, segment);
current = next;
}
return current;
};
const actionJsonBody = (transition: ReplayTransition): string | undefined => {
for (const action of transition.actions)
if (action.type === "http_response") return action.body;
else if (action.type === "websocket_send") return action.data;
return undefined;
};
const readValue = (
source: ReplayValueSource,
event: ReplayMachineEvent,
transition: ReplayTransition,
): unknown => {
switch (source.source) {
case "request_header":
return event.headers[source.name.toLowerCase()];
case "request_json":
return atPath(parseJson(event.body), source.path);
case "websocket_json":
return atPath(parseJson(event.body), source.path);
case "action_json": {
const body = actionJsonBody(transition);
return body === undefined
? undefined
: atPath(parseJson(body), source.path);
}
}
};
const triggerMatches = (
transition: ReplayTransition,
event: ReplayMachineEvent,
): boolean => {
const trigger = transition.trigger;
if (trigger.protocol !== event.protocol || trigger.path !== event.path)
return false;
if (
"headers" in trigger &&
Object.entries(trigger.headers).some(
([name, value]) => event.headers[name.toLowerCase()] !== value,
)
)
return false;
if (trigger.protocol === "http")
return (
trigger.method === event.method &&
(trigger.body === null || trigger.body === event.body)
);
if (trigger.protocol === "websocket_message")
return trigger.body === null || trigger.body === event.body;
return true;
};
const isJsonCompatible = (value: unknown): boolean => {
if (value === null || typeof value === "string" || typeof value === "boolean")
return true;
if (typeof value === "number") return Number.isFinite(value);
if (Array.isArray(value)) return value.every(isJsonCompatible);
if (typeof value !== "object") return false;
return Object.values(value).every(isJsonCompatible);
};
const replayValuesEqual = (left: unknown, right: unknown): boolean =>
isJsonCompatible(left) &&
isJsonCompatible(right) &&
(Object.is(left, right) || canonicalize(left) === canonicalize(right));
const createTransitionRecord = ({
sequence,
atMs,
stateBefore,
transition,
captures,
}: TransitionRecordOptions): ReplayTransitionRecord => ({
sequence,
at_ms: atMs,
transition_id: transition.id,
state_before: stateBefore,
state_after: transition.to,
sensitive_aliases: captures
.filter(({ sensitive }) => sensitive)
.map(({ variable }) => variable)
.sort(),
});
/** Stateful evaluator for one validated replay-machine instance. */
export class ReplayMachineRuntime {
readonly #variables = new Map<string, unknown>();
readonly #sensitiveValues = new Map<string, Set<string>>();
readonly #uses = new Map<string, number>();
readonly #stateVisits = new Map<string, number>();
readonly #timeline: ReplayTransitionRecord[] = [];
#state: string;
#connections = 0;
#messages = 0;
#bytes = 0;
#lastAtMs = 0;
#events = 0;
constructor(readonly machine: ReplayMachine) {
this.#state = machine.initial_state;
this.#stateVisits.set(machine.initial_state, 1);
}
/** Current machine state after all accepted transitions. */
get state(): string {
return this.#state;
}
/** Ordered, secret-free transition records. */
get timeline(): readonly ReplayTransitionRecord[] {
return this.#timeline;
}
/** Current committed use of the machine's declared limits. */
get usage(): ReplayMachineUsage {
return {
events: this.#events,
transitions: this.#timeline.length,
connections: this.#connections,
messages: this.#messages,
bytes: this.#bytes,
last_at_ms: this.#lastAtMs,
};
}
/** Replace captured secret values with stable aliases before persistence. */
redact(value: string): string {
let redacted = value;
const secrets = [...this.#sensitiveValues]
.flatMap(([variable, values]) =>
[...values].map((secret) => ({ variable, secret })),
)
.sort(
(left, right) =>
right.secret.length - left.secret.length ||
left.variable.localeCompare(right.variable),
);
for (const { variable, secret } of secrets)
redacted = redacted.replaceAll(secret, `<secret:${variable}>`);
return redacted;
}
/** Replace a field containing captured secrets with one stable alias only. */
redactField(value: string): string {
const alias = [...this.#sensitiveValues]
.filter(([, values]) =>
[...values].some((secret) => value.includes(secret)),
)
.map(([variable]) => variable)
.sort()[0];
return alias === undefined ? value : `<secret:${alias}>`;
}
/** Evaluate and, when admitted, commit one protocol event. */
dispatch(event: ReplayMachineEvent): ReplayMachineDecision {
const normalizedEvent = {
...event,
headers: Object.fromEntries(
Object.entries(event.headers).map(([name, value]) => [
name.toLowerCase(),
value,
]),
),
};
if (!this.#admitEvent(normalizedEvent))
return this.#refusal("limit_exhausted");
const matching = this.machine.transitions
.map((transition, declarationOrder) => ({
transition,
declarationOrder,
}))
.filter(({ transition }) => triggerMatches(transition, normalizedEvent));
const eligible = matching
.filter(({ transition }) => transition.from === this.#state)
.sort(
(left, right) =>
left.transition.priority - right.transition.priority ||
left.declarationOrder - right.declarationOrder,
);
if (eligible.length === 0)
return this.#refusal(
matching.length === 0
? "unmatched"
: normalizedEvent.protocol === "websocket_connect" &&
normalizedEvent.connection === "reconnect"
? "unexpected_reconnect"
: "invalid_state",
);
const guarded = eligible.filter(({ transition }) =>
transition.guards.every(
(guard) =>
this.#variables.has(guard.variable) &&
replayValuesEqual(
this.#variables.get(guard.variable),
readValue(guard.value, normalizedEvent, transition),
),
),
);
if (guarded.length === 0) return this.#refusal("guard_failed");
if (this.#timeline.length >= this.machine.max_transitions)
return this.#refusal("transition_exhausted");
const usable = guarded.find(
({ transition }) =>
(this.#uses.get(transition.id) ?? 0) < transition.max_uses,
);
if (usable === undefined) return this.#refusal("transition_exhausted");
const transition = usable.transition;
const used = this.#uses.get(transition.id) ?? 0;
const nextState = this.machine.states.find(
({ name }) => name === transition.to,
);
const nextVisits = (this.#stateVisits.get(transition.to) ?? 0) + 1;
if (nextState === undefined || nextVisits > nextState.max_visits)
return this.#refusal("limit_exhausted");
const captures = transition.captures.map((capture) => ({
...capture,
captured: readValue(capture.value, normalizedEvent, transition),
}));
if (
captures.some(
({ captured, sensitive }) =>
!isJsonCompatible(captured) ||
(sensitive && typeof captured !== "string"),
)
)
return this.#refusal("invalid_capture");
for (const capture of captures) {
this.#variables.set(capture.variable, capture.captured);
if (capture.sensitive && typeof capture.captured === "string") {
const values = this.#sensitiveValues.get(capture.variable) ?? new Set();
if (capture.captured.length > 0) values.add(capture.captured);
this.#sensitiveValues.set(capture.variable, values);
}
}
const record = createTransitionRecord({
sequence: this.#timeline.length,
atMs: normalizedEvent.recorded_at_ms ?? normalizedEvent.at_ms,
stateBefore: this.#state,
transition,
captures,
});
this.#uses.set(transition.id, used + 1);
this.#stateVisits.set(transition.to, nextVisits);
this.#state = transition.to;
this.#timeline.push(record);
return {
outcome: "matched",
actions: transition.actions,
transition: record,
};
}
#admitEvent(event: ReplayMachineEvent): boolean {
const connections =
this.#connections + (event.protocol === "websocket_connect" ? 1 : 0);
const messages =
this.#messages + (event.protocol === "websocket_message" ? 1 : 0);
const bytes = this.#bytes + Buffer.byteLength(event.body);
if (
!Number.isSafeInteger(event.at_ms) ||
event.at_ms < this.#lastAtMs ||
event.at_ms > this.machine.limits.duration_ms ||
connections > this.machine.limits.connections ||
messages > this.machine.limits.messages ||
bytes > this.machine.limits.bytes
)
return false;
this.#connections = connections;
this.#messages = messages;
this.#bytes = bytes;
this.#lastAtMs = event.at_ms;
this.#events += 1;
return true;
}
#refusal(
outcome: Exclude<ReplayMachineDecision["outcome"], "matched">,
): ReplayMachineDecision {
return { outcome, actions: [], transition: null };
}
}