@piagent/platform 1.2.16 → 1.3.0-ie.8

package/packages/piagent-core/runtime/trajectory/trajectory-state.ts

@@ -0,0 +1,161 @@
+import crypto from "node:crypto";
+
+import type {
+  TerminalTaskOutcomeRef,
+  TrajectoryCause,
+  TrajectoryPhase,
+  TrajectoryRecommendationRef,
+  TrajectorySourceHook,
+  TrajectoryState,
+  TrajectoryTransitionEvent
+} from "./trajectory-types.ts";
+import {
+  TRAJECTORY_POLICY_VERSION,
+  TRAJECTORY_SCHEMA_VERSION,
+  trajectoryEventId,
+  validateTrajectoryState,
+  validateTrajectoryTransition
+} from "./trajectory-types.ts";
+
+export type CreateTrajectoryInput = {
+  taskId: string;
+  taskRunId: string;
+  sessionId: string;
+  changeMode: TrajectoryState["changeMode"];
+  riskLane: TrajectoryState["riskLane"];
+  recommendationRef?: TrajectoryRecommendationRef | null;
+  createdAt?: string;
+};
+
+export type CreateTransitionInput = {
+  to: TrajectoryPhase;
+  cause: TrajectoryCause;
+  sourceHook: TrajectorySourceHook;
+  taskDigest?: string | null;
+  treeDigest?: string | null;
+  skippedPhases?: TrajectoryPhase[];
+  skipReason?: string | null;
+  observedAt?: string;
+  terminalTaskOutcomeRef?: TerminalTaskOutcomeRef | null;
+};
+
+const PHASE_CAUSES: Partial<Record<TrajectoryPhase, Set<TrajectoryCause>>> = {
+  scout: new Set(["context-observed"]),
+  plan: new Set(["plan-observed"]),
+  execute: new Set(["execution-authorized", "mutation-observed"]),
+  verify: new Set(["verification-started", "verification-passed"]),
+  repair: new Set(["verification-failed", "recovery-requested"]),
+  review: new Set(["review-observed", "verification-passed"]),
+  handoff: new Set(["handoff-observed"]),
+  terminal: new Set(["task-terminal"])
+};
+
+export function trajectoryPath(changeMode: TrajectoryState["changeMode"], riskLane: TrajectoryState["riskLane"]): TrajectoryPhase[] {
+  if (changeMode === "read-only") return ["intake", "scout", "review", "handoff", "terminal"];
+  if (riskLane === "tiny") return ["intake", "execute", "verify", "handoff", "terminal"];
+  if (riskLane === "high-risk") return ["intake", "scout", "plan", "execute", "verify", "review", "handoff", "terminal"];
+  return ["intake", "plan", "execute", "verify", "review", "handoff", "terminal"];
+}
+
+export function createTrajectoryState(input: CreateTrajectoryInput): TrajectoryState {
+  const createdAt = input.createdAt ?? new Date().toISOString();
+  return validateTrajectoryState({
+    schemaVersion: TRAJECTORY_SCHEMA_VERSION,
+    policyVersion: TRAJECTORY_POLICY_VERSION,
+    taskId: input.taskId,
+    taskRunId: input.taskRunId,
+    sessionHash: crypto.createHash("sha256").update(String(input.sessionId || "unknown-session")).digest("hex"),
+    changeMode: input.changeMode,
+    riskLane: input.riskLane,
+    currentPhase: "intake",
+    recommendationRef: input.recommendationRef ?? null,
+    sequence: 0,
+    appliedEventIds: [],
+    lastTransition: null,
+    createdAt,
+    updatedAt: createdAt,
+    terminalTaskOutcomeRef: null
+  });
+}
+
+export function createTrajectoryTransition(stateInput: TrajectoryState, input: CreateTransitionInput): TrajectoryTransitionEvent {
+  const state = validateTrajectoryState(stateInput);
+  const material = {
+    schemaVersion: TRAJECTORY_SCHEMA_VERSION,
+    policyVersion: TRAJECTORY_POLICY_VERSION,
+    taskId: state.taskId,
+    taskRunId: state.taskRunId,
+    sessionHash: state.sessionHash,
+    sequence: state.sequence + 1,
+    from: state.currentPhase,
+    to: input.to,
+    cause: input.cause,
+    sourceHook: input.sourceHook,
+    taskDigest: input.taskDigest ?? null,
+    treeDigest: input.treeDigest ?? null,
+    skippedPhases: [...(input.skippedPhases ?? [])],
+    skipReason: input.skipReason ?? null,
+    terminalTaskOutcomeRef: input.terminalTaskOutcomeRef ?? null
+  };
+  return validateTrajectoryTransition({
+    ...material,
+    eventId: trajectoryEventId(material),
+    observedAt: input.observedAt ?? new Date().toISOString()
+  });
+}
+
+function samePhases(left: TrajectoryPhase[], right: TrajectoryPhase[]): boolean {
+  return left.length === right.length && left.every((phase, index) => phase === right[index]);
+}
+
+function policyError(state: TrajectoryState, event: TrajectoryTransitionEvent): string | undefined {
+  const path = trajectoryPath(state.changeMode, state.riskLane);
+  const fromIndex = path.indexOf(event.from);
+  const toIndex = path.indexOf(event.to);
+  const repairEdge = (["execute", "verify", "review"].includes(event.from) && event.to === "repair")
+    || (event.from === "repair" && event.to === "verify");
+  if (repairEdge) {
+    if (event.skippedPhases.length > 0) return "repair transitions cannot skip phases";
+    return undefined;
+  }
+  if (fromIndex < 0 || toIndex < 0 || toIndex <= fromIndex) return "transition is outside the configured trajectory path";
+  const skipped = path.slice(fromIndex + 1, toIndex);
+  if (!samePhases(skipped, event.skippedPhases)) return "skipped phases do not match the configured trajectory path";
+  if (skipped.length > 0) {
+    const failureHandoff = event.to === "handoff" && event.cause === "handoff-observed" && ["execute", "verify", "repair"].includes(event.from);
+    const terminal = event.to === "terminal" && event.cause === "task-terminal";
+    const executableWorkPlan = event.to === "execute" && event.cause === "execution-authorized";
+    if (event.cause !== "explicit-skip" && !executableWorkPlan && !failureHandoff && !terminal) return "non-adjacent transition requires explicit skip evidence";
+    if (state.changeMode === "source-change" && skipped.includes("verify") && !failureHandoff && !terminal) return "source verification cannot be skipped";
+    if (state.riskLane === "high-risk" && skipped.includes("plan") && !terminal) return "high-risk planning cannot be skipped";
+    if ((state.changeMode === "read-only" || state.riskLane === "high-risk") && skipped.includes("review") && !terminal) return "required review cannot be skipped";
+  }
+  const causes = PHASE_CAUSES[event.to];
+  if (event.cause !== "explicit-skip" && causes && !causes.has(event.cause)) return `cause ${event.cause} cannot enter ${event.to}`;
+  return undefined;
+}
+
+export function reduceTrajectory(stateInput: TrajectoryState, eventInput: TrajectoryTransitionEvent): TrajectoryState {
+  const state = validateTrajectoryState(structuredClone(stateInput));
+  const event = validateTrajectoryTransition(structuredClone(eventInput));
+  if (state.appliedEventIds.includes(event.eventId)) return state;
+  if (state.currentPhase === "terminal") throw new Error("terminal Task Contract reference prevents trajectory mutation");
+  if (event.taskId !== state.taskId || event.taskRunId !== state.taskRunId || event.sessionHash !== state.sessionHash) throw new Error("trajectory transition identity mismatch");
+  if (event.sequence !== state.sequence + 1 || event.from !== state.currentPhase) throw new Error("trajectory transition is out of order");
+  if (Date.parse(event.observedAt) < Date.parse(state.updatedAt)) throw new Error("trajectory transition timestamp is stale");
+  const error = policyError(state, event);
+  if (error) throw new Error(error);
+  return validateTrajectoryState({
+    ...state,
+    currentPhase: event.to,
+    sequence: event.sequence,
+    appliedEventIds: [...state.appliedEventIds, event.eventId],
+    lastTransition: event,
+    updatedAt: event.observedAt,
+    terminalTaskOutcomeRef: event.terminalTaskOutcomeRef
+  });
+}
+
+export function replayTrajectory(initial: TrajectoryState, events: readonly TrajectoryTransitionEvent[]): TrajectoryState {
+  return events.reduce((state, event) => reduceTrajectory(state, event), validateTrajectoryState(structuredClone(initial)));
+}

package/packages/piagent-core/runtime/trajectory/trajectory-store.ts

@@ -0,0 +1,79 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { ensurePrivateStateDirectory, resolveLocalStatePath } from "../../extensions/local-state-path.js";
+import { appendJsonlBounded } from "../../extensions/state-retention.js";
+import { safeTaskId } from "../../extensions/task-state.js";
+import { reduceTrajectory } from "./trajectory-state.ts";
+import type { TrajectoryState, TrajectoryTransitionEvent } from "./trajectory-types.ts";
+import { validateTrajectoryState, validateTrajectoryTransition } from "./trajectory-types.ts";
+
+const MAX_EVENT_BYTES = 512 * 1024;
+
+export type TrajectoryStoreView = {
+  status: "missing" | "ok" | "corrupt";
+  state?: TrajectoryState;
+  events: TrajectoryTransitionEvent[];
+  recoveredEvents: number;
+  warnings: string[];
+  enforcementSafe: boolean;
+};
+
+export function trajectoryStatePath(cwd: string, taskRunId: string): string {
+  return path.join(cwd, ".pi", "piagent-state", "trajectory", `${safeTaskId(taskRunId)}.json`);
+}
+export function trajectoryEventsPath(cwd: string, taskRunId: string): string {
+  return path.join(cwd, ".pi", "piagent-state", "trajectory", `${safeTaskId(taskRunId)}.events.jsonl`);
+}
+
+function readText(file: string): string {
+  try { return fs.readFileSync(file, "utf8"); }
+  catch (error) { if ((error as { code?: string })?.code === "ENOENT") return ""; throw error; }
+}
+
+export function readTrajectoryStore(cwd: string, taskRunId: string): TrajectoryStoreView {
+  try {
+    const stateFile = resolveLocalStatePath(cwd, trajectoryStatePath(cwd, taskRunId), { label: "Trajectory state" });
+    const eventFile = resolveLocalStatePath(cwd, trajectoryEventsPath(cwd, taskRunId), { label: "Trajectory events" });
+    const rotated = resolveLocalStatePath(cwd, `${trajectoryEventsPath(cwd, taskRunId)}.1`, { label: "Rotated trajectory events" });
+    const stateText = readText(stateFile);
+    const eventLines = [readText(rotated), readText(eventFile)].join("").split(/\r?\n/).filter(Boolean);
+    if (!stateText && eventLines.length === 0) return { status: "missing", events: [], recoveredEvents: 0, warnings: [], enforcementSafe: true };
+    if (!stateText) return { status: "corrupt", events: [], recoveredEvents: 0, warnings: ["trajectory events exist without state"], enforcementSafe: false };
+    let state = validateTrajectoryState(JSON.parse(stateText), "persisted trajectory state");
+    const events: TrajectoryTransitionEvent[] = [];
+    for (const [index, line] of eventLines.entries()) {
+      try { events.push(validateTrajectoryTransition(JSON.parse(line), `persisted trajectory event ${index + 1}`)); }
+      catch (error) { return { status: "corrupt", events, recoveredEvents: 0, warnings: [error instanceof Error ? error.message : String(error)], enforcementSafe: false }; }
+    }
+    let recoveredEvents = 0;
+    for (const event of events) {
+      if (state.appliedEventIds.includes(event.eventId)) continue;
+      if (event.sequence <= state.sequence) return { status: "corrupt", state, events, recoveredEvents, warnings: ["trajectory journal contains an unknown out-of-order event"], enforcementSafe: false };
+      state = reduceTrajectory(state, event);
+      recoveredEvents += 1;
+    }
+    return { status: "ok", state, events, recoveredEvents, warnings: [], enforcementSafe: true };
+  } catch (error) {
+    return { status: "corrupt", events: [], recoveredEvents: 0, warnings: [error instanceof Error ? error.message : String(error)], enforcementSafe: false };
+  }
+}
+
+export function writeTrajectoryState(cwd: string, stateInput: TrajectoryState): TrajectoryState {
+  const state = validateTrajectoryState(structuredClone(stateInput));
+  const target = trajectoryStatePath(cwd, state.taskRunId);
+  const parent = ensurePrivateStateDirectory(cwd, path.dirname(target), "Trajectory state directory");
+  const safeTarget = resolveLocalStatePath(cwd, target, { label: "Trajectory state" });
+  const temporary = path.join(parent, `${path.basename(safeTarget)}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`);
+  fs.writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temporary, safeTarget);
+  try { fs.chmodSync(parent, 0o700); fs.chmodSync(safeTarget, 0o600); } catch {}
+  return state;
+}
+
+export function appendTrajectoryTransition(cwd: string, eventInput: TrajectoryTransitionEvent): TrajectoryTransitionEvent {
+  const event = validateTrajectoryTransition(structuredClone(eventInput));
+  appendJsonlBounded(trajectoryEventsPath(cwd, event.taskRunId), event, { maxBytes: MAX_EVENT_BYTES, mode: 0o600, projectRoot: cwd });
+  return event;
+}

package/packages/piagent-core/runtime/trajectory/trajectory-types.ts

@@ -0,0 +1,196 @@
+import crypto from "node:crypto";
+import { isCurrentWorkingTreeDigest } from "../../extensions/working-tree-digest.js";
+
+export const TRAJECTORY_SCHEMA_VERSION = 1 as const;
+export const TRAJECTORY_POLICY_VERSION = "trajectory-v1" as const;
+export const TRAJECTORY_PHASES = Object.freeze(["intake", "scout", "plan", "execute", "verify", "repair", "review", "handoff", "terminal"] as const);
+export const TRAJECTORY_CAUSES = Object.freeze(["task-started", "context-observed", "plan-observed", "execution-authorized", "mutation-observed", "verification-started", "verification-passed", "verification-failed", "review-observed", "handoff-observed", "task-terminal", "recovery-requested", "explicit-skip"] as const);
+export const TRAJECTORY_SOURCE_HOOKS = Object.freeze(["input", "agent-start", "tool-call", "tool-result", "completion", "session-start", "task-state", "operator"] as const);
+
+export type TrajectoryPhase = typeof TRAJECTORY_PHASES[number];
+export type TrajectoryCause = typeof TRAJECTORY_CAUSES[number];
+export type TrajectorySourceHook = typeof TRAJECTORY_SOURCE_HOOKS[number];
+export type TerminalTaskOutcomeRef = { taskRunId: string; taskUpdatedAt: string; taskDigest: string };
+export type TrajectoryRecommendationRef = {
+  solverPolicyVersion: "solver-v1";
+  featureHash: string;
+  route: "direct" | "scout-first" | "plan-first" | "review-only" | "blocked-preflight";
+  decisionDigest: string;
+};
+export type TrajectoryTransitionEvent = {
+  schemaVersion: typeof TRAJECTORY_SCHEMA_VERSION;
+  policyVersion: typeof TRAJECTORY_POLICY_VERSION;
+  eventId: string;
+  taskId: string;
+  taskRunId: string;
+  sessionHash: string;
+  sequence: number;
+  from: TrajectoryPhase;
+  to: TrajectoryPhase;
+  cause: TrajectoryCause;
+  sourceHook: TrajectorySourceHook;
+  taskDigest: string | null;
+  treeDigest: string | null;
+  skippedPhases: TrajectoryPhase[];
+  skipReason: string | null;
+  observedAt: string;
+  terminalTaskOutcomeRef: TerminalTaskOutcomeRef | null;
+};
+export type TrajectoryState = {
+  schemaVersion: typeof TRAJECTORY_SCHEMA_VERSION;
+  policyVersion: typeof TRAJECTORY_POLICY_VERSION;
+  taskId: string;
+  taskRunId: string;
+  sessionHash: string;
+  changeMode: "source-change" | "read-only";
+  riskLane: "tiny" | "normal" | "high-risk";
+  currentPhase: TrajectoryPhase;
+  recommendationRef: TrajectoryRecommendationRef | null;
+  sequence: number;
+  appliedEventIds: string[];
+  lastTransition: TrajectoryTransitionEvent | null;
+  createdAt: string;
+  updatedAt: string;
+  terminalTaskOutcomeRef: TerminalTaskOutcomeRef | null;
+};
+
+function eventIdentityMaterial(input: Omit<TrajectoryTransitionEvent, "eventId" | "observedAt">): Record<string, unknown> {
+  return {
+    schemaVersion: input.schemaVersion,
+    policyVersion: input.policyVersion,
+    taskId: input.taskId,
+    taskRunId: input.taskRunId,
+    sessionHash: input.sessionHash,
+    sequence: input.sequence,
+    from: input.from,
+    to: input.to,
+    cause: input.cause,
+    sourceHook: input.sourceHook,
+    taskDigest: input.taskDigest,
+    treeDigest: input.treeDigest,
+    skippedPhases: input.skippedPhases,
+    skipReason: input.skipReason,
+    terminalTaskOutcomeRef: input.terminalTaskOutcomeRef
+  };
+}
+
+const HASH = /^[a-f0-9]{64}$/;
+const ID = /^[a-z0-9][a-z0-9-]{0,127}$/;
+const EVENT_FIELDS = new Set(["schemaVersion", "policyVersion", "eventId", "taskId", "taskRunId", "sessionHash", "sequence", "from", "to", "cause", "sourceHook", "taskDigest", "treeDigest", "skippedPhases", "skipReason", "observedAt", "terminalTaskOutcomeRef"]);
+const STATE_FIELDS = new Set(["schemaVersion", "policyVersion", "taskId", "taskRunId", "sessionHash", "changeMode", "riskLane", "currentPhase", "recommendationRef", "sequence", "appliedEventIds", "lastTransition", "createdAt", "updatedAt", "terminalTaskOutcomeRef"]);
+const TERMINAL_REF_FIELDS = new Set(["taskRunId", "taskUpdatedAt", "taskDigest"]);
+const RECOMMENDATION_FIELDS = new Set(["solverPolicyVersion", "featureHash", "route", "decisionDigest"]);
+const ALLOWED_TRANSITIONS = new Set([
+  "intake:scout", "intake:plan", "intake:execute", "intake:review", "intake:handoff", "intake:terminal",
+  "scout:plan", "scout:review", "scout:handoff", "scout:terminal", "plan:execute", "plan:review", "plan:handoff", "plan:terminal",
+  "execute:verify", "execute:repair", "execute:handoff", "execute:terminal", "verify:repair", "verify:review", "verify:handoff", "verify:terminal",
+  "repair:verify", "repair:handoff", "repair:terminal", "review:repair", "review:handoff", "review:terminal", "handoff:terminal"
+]);
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+function exact(value: Record<string, unknown>, fields: Set<string>, label: string): string[] {
+  return [...Object.keys(value).filter((field) => !fields.has(field)).map((field) => `${label} has unknown field: ${field}`), ...[...fields].filter((field) => !(field in value)).map((field) => `${label} missing field: ${field}`)];
+}
+function timestamp(value: unknown): boolean {
+  return typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value) && Number.isFinite(Date.parse(value));
+}
+function terminalRefErrors(value: unknown, label: string): string[] {
+  if (value === null) return [];
+  const ref = record(value);
+  if (!ref) return [`${label} must be null or an object`];
+  const errors = exact(ref, TERMINAL_REF_FIELDS, label);
+  if (typeof ref.taskRunId !== "string" || !ID.test(ref.taskRunId)) errors.push(`${label}.taskRunId is invalid`);
+  if (!timestamp(ref.taskUpdatedAt)) errors.push(`${label}.taskUpdatedAt is invalid`);
+  if (typeof ref.taskDigest !== "string" || !HASH.test(ref.taskDigest)) errors.push(`${label}.taskDigest is invalid`);
+  return errors;
+}
+function recommendationErrors(value: unknown): string[] {
+  if (value === null) return [];
+  const ref = record(value);
+  if (!ref) return ["recommendationRef must be null or an object"];
+  const errors = exact(ref, RECOMMENDATION_FIELDS, "recommendationRef");
+  if (ref.solverPolicyVersion !== "solver-v1") errors.push("recommendationRef.solverPolicyVersion is invalid");
+  for (const field of ["featureHash", "decisionDigest"] as const) if (typeof ref[field] !== "string" || !HASH.test(ref[field])) errors.push(`recommendationRef.${field} is invalid`);
+  if (!["direct", "scout-first", "plan-first", "review-only", "blocked-preflight"].includes(String(ref.route))) errors.push("recommendationRef.route is invalid");
+  return errors;
+}
+
+export function trajectoryTransitionValidationErrors(input: unknown): string[] {
+  const value = record(input);
+  if (!value) return ["trajectory transition must be an object"];
+  const errors = exact(value, EVENT_FIELDS, "trajectory transition");
+  if (value.schemaVersion !== 1 || value.policyVersion !== TRAJECTORY_POLICY_VERSION) errors.push("transition schema/policy version is invalid");
+  for (const field of ["eventId", "sessionHash"] as const) if (typeof value[field] !== "string" || !HASH.test(value[field])) errors.push(`${field} is invalid`);
+  for (const field of ["taskId", "taskRunId"] as const) if (typeof value[field] !== "string" || !ID.test(value[field])) errors.push(`${field} is invalid`);
+  if (!Number.isInteger(value.sequence) || Number(value.sequence) < 1 || Number(value.sequence) > Number.MAX_SAFE_INTEGER) errors.push("sequence must be a positive integer");
+  if (!TRAJECTORY_PHASES.includes(value.from as TrajectoryPhase) || !TRAJECTORY_PHASES.includes(value.to as TrajectoryPhase) || !ALLOWED_TRANSITIONS.has(`${value.from}:${value.to}`)) errors.push("phase transition is not allowed");
+  if (!TRAJECTORY_CAUSES.includes(value.cause as TrajectoryCause)) errors.push("cause is invalid");
+  if (!TRAJECTORY_SOURCE_HOOKS.includes(value.sourceHook as TrajectorySourceHook)) errors.push("sourceHook is invalid");
+  if (value.taskDigest !== null && (typeof value.taskDigest !== "string" || !HASH.test(value.taskDigest))) errors.push("taskDigest is invalid");
+  if (value.treeDigest !== null && !isCurrentWorkingTreeDigest(value.treeDigest)) errors.push("treeDigest is invalid");
+  const skipped = Array.isArray(value.skippedPhases) ? value.skippedPhases : [];
+  if (!Array.isArray(value.skippedPhases) || skipped.length > 7 || skipped.some((phase) => !TRAJECTORY_PHASES.includes(phase as TrajectoryPhase)) || new Set(skipped).size !== skipped.length) errors.push("skippedPhases are invalid");
+  if (value.cause === "explicit-skip" && skipped.length === 0) errors.push("explicit-skip requires skippedPhases");
+  if (skipped.length > 0 && (typeof value.skipReason !== "string" || value.skipReason.length < 3 || value.skipReason.length > 240)) errors.push("skipped phases require a bounded skipReason");
+  if (skipped.length === 0 && value.skipReason !== null) errors.push("skipReason requires skippedPhases");
+  if (!timestamp(value.observedAt)) errors.push("observedAt is invalid");
+  errors.push(...terminalRefErrors(value.terminalTaskOutcomeRef, "terminalTaskOutcomeRef"));
+  if (value.to === "terminal" && value.terminalTaskOutcomeRef === null) errors.push("terminal transition requires a Task Contract outcome reference");
+  if (value.to !== "terminal" && value.terminalTaskOutcomeRef !== null) errors.push("non-terminal transition cannot carry a terminal reference");
+  const terminalRef = record(value.terminalTaskOutcomeRef);
+  if (terminalRef && terminalRef.taskRunId !== value.taskRunId) errors.push("terminal reference taskRunId must match transition identity");
+  if (errors.length === 0) {
+    const { eventId: _eventId, observedAt: _observedAt, ...material } = value;
+    if (trajectoryEventId(material as Omit<TrajectoryTransitionEvent, "eventId" | "observedAt">) !== value.eventId) errors.push("eventId does not match transition material");
+  }
+  return errors;
+}
+export function validateTrajectoryTransition(input: unknown, source = "trajectory transition"): TrajectoryTransitionEvent {
+  const errors = trajectoryTransitionValidationErrors(input);
+  if (errors.length > 0) throw new Error(`${source}: ${errors.join("; ")}`);
+  return input as TrajectoryTransitionEvent;
+}
+
+export function trajectoryStateValidationErrors(input: unknown): string[] {
+  const value = record(input);
+  if (!value) return ["trajectory state must be an object"];
+  const errors = exact(value, STATE_FIELDS, "trajectory state");
+  if (value.schemaVersion !== 1 || value.policyVersion !== TRAJECTORY_POLICY_VERSION) errors.push("state schema/policy version is invalid");
+  for (const field of ["taskId", "taskRunId"] as const) if (typeof value[field] !== "string" || !ID.test(value[field])) errors.push(`${field} is invalid`);
+  if (typeof value.sessionHash !== "string" || !HASH.test(value.sessionHash)) errors.push("sessionHash is invalid");
+  if (!["source-change", "read-only"].includes(String(value.changeMode)) || !["tiny", "normal", "high-risk"].includes(String(value.riskLane))) errors.push("changeMode/riskLane is invalid");
+  if (!TRAJECTORY_PHASES.includes(value.currentPhase as TrajectoryPhase)) errors.push("currentPhase is invalid");
+  errors.push(...recommendationErrors(value.recommendationRef));
+  if (!Number.isInteger(value.sequence) || Number(value.sequence) < 0 || Number(value.sequence) > Number.MAX_SAFE_INTEGER) errors.push("sequence must be a non-negative integer");
+  if (!Array.isArray(value.appliedEventIds) || value.appliedEventIds.length > 256 || value.appliedEventIds.some((eventId) => typeof eventId !== "string" || !HASH.test(eventId)) || new Set(value.appliedEventIds).size !== value.appliedEventIds.length) errors.push("appliedEventIds are invalid");
+  if (Array.isArray(value.appliedEventIds) && value.appliedEventIds.length !== value.sequence) errors.push("appliedEventIds length must match sequence");
+  if (!timestamp(value.createdAt) || !timestamp(value.updatedAt) || (timestamp(value.createdAt) && timestamp(value.updatedAt) && Date.parse(String(value.updatedAt)) < Date.parse(String(value.createdAt)))) errors.push("state timestamps are invalid");
+  errors.push(...terminalRefErrors(value.terminalTaskOutcomeRef, "terminalTaskOutcomeRef"));
+  if (value.currentPhase === "terminal" && value.terminalTaskOutcomeRef === null) errors.push("terminal state requires a Task Contract outcome reference");
+  if (value.currentPhase !== "terminal" && value.terminalTaskOutcomeRef !== null) errors.push("non-terminal state cannot carry a terminal reference");
+  if (value.sequence === 0 && value.lastTransition !== null) errors.push("initial state cannot have a last transition");
+  if (value.sequence !== 0 && value.lastTransition === null) errors.push("non-initial state requires a last transition");
+  if (value.lastTransition !== null) {
+    errors.push(...trajectoryTransitionValidationErrors(value.lastTransition).map((error) => `lastTransition: ${error}`));
+    const transition = record(value.lastTransition);
+    if (transition && (transition.taskId !== value.taskId || transition.taskRunId !== value.taskRunId || transition.sessionHash !== value.sessionHash)) errors.push("lastTransition identity must match state");
+    if (transition && (transition.sequence !== value.sequence || transition.to !== value.currentPhase || transition.observedAt !== value.updatedAt)) errors.push("lastTransition sequence/phase/time must match state");
+    if (transition && Array.isArray(value.appliedEventIds) && value.appliedEventIds.at(-1) !== transition.eventId) errors.push("lastTransition eventId must be the latest applied event");
+  }
+  const terminalRef = record(value.terminalTaskOutcomeRef);
+  if (terminalRef && terminalRef.taskRunId !== value.taskRunId) errors.push("terminal reference taskRunId must match state identity");
+  return errors;
+}
+export function validateTrajectoryState(input: unknown, source = "trajectory state"): TrajectoryState {
+  const errors = trajectoryStateValidationErrors(input);
+  if (errors.length > 0) throw new Error(`${source}: ${errors.join("; ")}`);
+  return input as TrajectoryState;
+}
+export function trajectoryEventId(input: Omit<TrajectoryTransitionEvent, "eventId" | "observedAt">): string {
+  return crypto.createHash("sha256").update(JSON.stringify(eventIdentityMaterial(input))).digest("hex");
+}
+export function serializeTrajectoryState(input: TrajectoryState): string {
+  return `${JSON.stringify(validateTrajectoryState(structuredClone(input)))}\n`;
+}