@agilno-tech/rivet 0.1.0-alpha.0

package/src/graph/fixtures.js

@@ -0,0 +1,116 @@
+import { graphFailure, sanitizeGraphOperation } from './validate.js';
+
+const budget = (timeMinutes, tokenLimit, costUsd, taskLimit) => ({ timeMinutes, tokenLimit, costUsd, taskLimit });
+
+function node({
+  id, parentId, objective, role, ownerId, dependencies, authorityScopes,
+  nodeBudget, completionProfile, requiredEvidenceTypes, evidenceRefs, status, approvalGate,
+}) {
+  return {
+    id,
+    ...(parentId ? { parentId } : {}),
+    objective,
+    owner: { role, id: ownerId },
+    dependencies,
+    authorityScopes,
+    budget: nodeBudget,
+    completionProfile,
+    requiredEvidenceTypes,
+    evidenceRefs,
+    status,
+    ...(approvalGate ? { approvalGate } : {}),
+  };
+}
+
+function commonNodes(goalPrefix = '') {
+  return [
+    node({
+      id: 'boss-plan', objective: `${goalPrefix}Own the approved delivery goal`, role: 'boss', ownerId: 'portfolio-boss',
+      dependencies: [], authorityScopes: ['plan', 'implement', 'delegate', 'verify'],
+      nodeBudget: budget(480, 500000, 100, 100), completionProfile: 'delivery',
+      requiredEvidenceTypes: ['commit', 'test', 'review', 'human-approval'],
+      evidenceRefs: ['boss-commit', 'boss-test', 'boss-review', 'boss-approval'], status: 'completed',
+    }),
+    node({
+      id: 'manager-plan', parentId: 'boss-plan', objective: `${goalPrefix}Coordinate implementation`, role: 'manager', ownerId: 'engineering-manager',
+      dependencies: ['boss-plan'], authorityScopes: ['implement', 'delegate', 'verify'],
+      nodeBudget: budget(240, 250000, 50, 40), completionProfile: 'engineering',
+      requiredEvidenceTypes: ['commit', 'test'], evidenceRefs: ['manager-commit', 'manager-test'], status: 'completed',
+    }),
+  ];
+}
+
+function parallelFanIn() {
+  const nodes = commonNodes();
+  nodes.push(
+    node({
+      id: 'api-contract', parentId: 'manager-plan', objective: 'Define the completed API contract', role: 'worker', ownerId: 'api-contract-worker',
+      dependencies: ['manager-plan'], authorityScopes: ['implement', 'verify'], nodeBudget: budget(60, 30000, 6, 5),
+      completionProfile: 'engineering', requiredEvidenceTypes: ['commit', 'test'], evidenceRefs: ['contract-commit', 'contract-test'], status: 'completed',
+    }),
+    node({
+      id: 'design', parentId: 'manager-plan', objective: 'Implement approved component states', role: 'worker', ownerId: 'design-worker',
+      dependencies: ['manager-plan'], authorityScopes: ['implement', 'verify'], nodeBudget: budget(90, 50000, 10, 8),
+      completionProfile: 'engineering', requiredEvidenceTypes: ['commit', 'test'], evidenceRefs: ['design-commit', 'design-test'], status: 'ready',
+    }),
+    node({
+      id: 'api', parentId: 'manager-plan', objective: 'Implement the agenda API', role: 'worker', ownerId: 'api-worker',
+      dependencies: ['api-contract'], authorityScopes: ['implement', 'verify'], nodeBudget: budget(120, 60000, 12, 10),
+      completionProfile: 'engineering', requiredEvidenceTypes: ['commit', 'test'], evidenceRefs: ['api-commit', 'api-test'], status: 'ready',
+    }),
+    node({
+      id: 'integration', parentId: 'manager-plan', objective: 'Integrate UI and API journeys', role: 'worker', ownerId: 'integration-worker',
+      dependencies: ['design', 'api'], authorityScopes: ['implement', 'verify'], nodeBudget: budget(120, 70000, 14, 12),
+      completionProfile: 'engineering', requiredEvidenceTypes: ['commit', 'test', 'journey'],
+      evidenceRefs: ['integration-commit', 'integration-test', 'integration-journey'], status: 'ready',
+    }),
+    node({
+      id: 'human-final', parentId: 'boss-plan', objective: 'Approve final delivery', role: 'boss', ownerId: 'portfolio-boss',
+      dependencies: ['integration'], authorityScopes: ['verify'], nodeBudget: budget(30, 1000, 1, 1), completionProfile: 'delivery',
+      requiredEvidenceTypes: ['commit', 'test', 'review', 'human-approval'],
+      evidenceRefs: ['final-commit', 'final-test', 'final-review', 'final-approval'], status: 'ready', approvalGate: 'final-delivery',
+    }),
+  );
+  return { schemaVersion: 1, id: 'parallel-fan-in', goal: 'Deliver a dependency-aware conference demo', providerRefs: ['git-ci-main'], maxDelegationDepth: 3, status: 'approved', nodes };
+}
+
+function corrective() {
+  const nodes = commonNodes();
+  nodes[0].objective = 'Own the corrective delivery goal';
+  nodes[1].objective = 'Coordinate the corrective task';
+  nodes[0].budget = budget(240, 200000, 40, 40);
+  nodes[1].budget = budget(180, 150000, 30, 30);
+  nodes.push(
+    node({
+      id: 'fix-journey', parentId: 'manager-plan', objective: 'Correct the journey regression', role: 'worker', ownerId: 'quality-worker',
+      dependencies: ['manager-plan'], authorityScopes: ['implement', 'verify'], nodeBudget: budget(90, 50000, 10, 8),
+      completionProfile: 'engineering', requiredEvidenceTypes: ['commit', 'test', 'journey'],
+      evidenceRefs: ['fix-commit', 'fix-test', 'fix-journey-result'], status: 'corrective',
+    }),
+    node({
+      id: 'human-final', parentId: 'boss-plan', objective: 'Approve corrected delivery', role: 'boss', ownerId: 'portfolio-boss',
+      dependencies: ['fix-journey'], authorityScopes: ['verify'], nodeBudget: budget(30, 1000, 1, 1), completionProfile: 'delivery',
+      requiredEvidenceTypes: ['commit', 'test', 'review', 'human-approval'],
+      evidenceRefs: ['final-commit', 'final-test', 'final-review', 'final-approval'], status: 'ready', approvalGate: 'final-delivery',
+    }),
+  );
+  return { schemaVersion: 1, id: 'corrective-loop', goal: 'Correct a failed journey before delivery', providerRefs: ['git-ci-main'], maxDelegationDepth: 2, status: 'running', nodes };
+}
+
+const BUILDERS = Object.freeze({
+  'parallel-fan-in': parallelFanIn,
+  corrective,
+});
+
+function graphFixtureUnsafe(name) {
+  const builder = BUILDERS[name];
+  if (!builder) graphFailure('unknown-graph-fixture');
+  return structuredClone(builder());
+}
+
+export function graphFixture(name) {
+  return sanitizeGraphOperation(
+    () => graphFixtureUnsafe(name),
+    'invalid-graph-fixture',
+  );
+}

package/src/graph/reducer.js

@@ -0,0 +1,124 @@
+import { validateEvent } from '../config/validate.js';
+import { graphFailure, sanitizeGraphOperation, validatedGraphSnapshot } from './validate.js';
+
+const EVENT_KEYS = new Set([
+  'schemaVersion', 'eventId', 'graphId', 'nodeId', 'sequence', 'timestamp', 'actor', 'type',
+  'priorState', 'newState', 'retryReason', 'authorityDelta', 'budgetDelta', 'evidenceRefs',
+  'instanceId', 'leaseId', 'heartbeatSequence', 'heartbeatIntervalMs', 'approvalReceiptId',
+]);
+const ACTOR_KEYS = new Set(['role', 'id']);
+const AUTHORITY_DELTA_KEYS = new Set(['added', 'removed']);
+const BUDGET_DELTA_KEYS = new Set(['timeMinutes', 'tokenLimit', 'costUsd', 'taskLimit']);
+
+const TRANSITIONS = Object.freeze({
+  proposed: new Set(['approved', 'blocked', 'cancelled']),
+  approved: new Set(['ready', 'blocked', 'cancelled']),
+  ready: new Set(['reserved', 'blocked', 'cancelled']),
+  reserved: new Set(['ready', 'running', 'blocked', 'cancelled']),
+  running: new Set(['verifying', 'corrective', 'blocked', 'failed', 'cancelled']),
+  verifying: new Set(['completed', 'corrective', 'blocked', 'failed', 'cancelled']),
+  corrective: new Set(['ready', 'reserved', 'running', 'verifying', 'blocked', 'failed', 'cancelled']),
+  blocked: new Set(['ready', 'corrective', 'failed', 'cancelled']),
+  failed: new Set(['corrective', 'archived']),
+  completed: new Set(['archived']),
+  archived: new Set(),
+  cancelled: new Set(['archived']),
+});
+
+function transitionAllowedUnsafe(priorState, newState) {
+  return TRANSITIONS[priorState]?.has(newState) ?? false;
+}
+
+export function transitionAllowed(priorState, newState) {
+  return sanitizeGraphOperation(
+    () => transitionAllowedUnsafe(priorState, newState),
+    'invalid-transition-arguments',
+  );
+}
+
+function checkedEvent(event) {
+  validateEvent(event);
+}
+
+function capturedObject(value, allowedKeys) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) graphFailure('invalid-event');
+  const keys = Object.keys(value);
+  if (keys.length > allowedKeys.size || keys.some(key => !allowedKeys.has(key))) graphFailure('invalid-event');
+  const captured = {};
+  for (const key of keys) captured[key] = value[key];
+  return captured;
+}
+
+function capturedArray(value, maximum) {
+  if (!Array.isArray(value)) graphFailure('invalid-event');
+  const length = value.length;
+  if (!Number.isSafeInteger(length) || length > maximum) graphFailure('invalid-event');
+  const captured = [];
+  for (let index = 0; index < length; index += 1) captured.push(value[index]);
+  return captured;
+}
+
+function capturedEvent(event) {
+  const captured = capturedObject(event, EVENT_KEYS);
+  if ('actor' in captured) captured.actor = capturedObject(captured.actor, ACTOR_KEYS);
+  if ('authorityDelta' in captured) {
+    captured.authorityDelta = capturedObject(captured.authorityDelta, AUTHORITY_DELTA_KEYS);
+    if ('added' in captured.authorityDelta) captured.authorityDelta.added = capturedArray(captured.authorityDelta.added, 32);
+    if ('removed' in captured.authorityDelta) captured.authorityDelta.removed = capturedArray(captured.authorityDelta.removed, 32);
+  }
+  if ('budgetDelta' in captured) captured.budgetDelta = capturedObject(captured.budgetDelta, BUDGET_DELTA_KEYS);
+  if ('evidenceRefs' in captured) captured.evidenceRefs = capturedArray(captured.evidenceRefs, 64);
+  return captured;
+}
+
+function targetFor(graph, event) {
+  if (!event.nodeId) return graph;
+  const node = graph.nodes.find(candidate => candidate.id === event.nodeId);
+  if (!node) graphFailure('unknown-node');
+  return node;
+}
+
+function appendEvidence(target, evidenceRefs) {
+  if (!Array.isArray(target.evidenceRefs)) graphFailure('graph-evidence-target');
+  const known = new Set(target.evidenceRefs);
+  if (evidenceRefs.some(reference => known.has(reference))) graphFailure('duplicate-evidence');
+  target.evidenceRefs.push(...evidenceRefs);
+}
+
+function exactReferences(left, right) {
+  if (left.length !== right.length) return false;
+  const actual = [...left].sort(); const expected = [...right].sort();
+  return actual.every((value, index) => value === expected[index]);
+}
+
+function reduceGraphUnsafe(graph, event) {
+  const stableGraph = validatedGraphSnapshot(graph);
+  const stableEvent = capturedEvent(event);
+  checkedEvent(stableEvent);
+  if (stableEvent.graphId !== stableGraph.id) graphFailure('graph-event-mismatch');
+
+  const next = stableGraph;
+  const target = targetFor(next, stableEvent);
+  if (stableEvent.type === 'state-transition') {
+    if (target.status !== stableEvent.priorState) graphFailure('stale-transition');
+    if (!transitionAllowedUnsafe(stableEvent.priorState, stableEvent.newState)) graphFailure('invalid-transition');
+    target.status = stableEvent.newState;
+  } else if (stableEvent.type === 'cancelled') {
+    if (!transitionAllowedUnsafe(target.status, 'cancelled')) graphFailure('invalid-transition');
+    target.status = 'cancelled';
+  } else if (stableEvent.type === 'evidence-recorded') {
+    appendEvidence(target, stableEvent.evidenceRefs);
+  } else if (stableEvent.type === 'approval-recorded' && stableEvent.nodeId) {
+    if (target.owner.role !== 'boss' || !target.approvalGate
+      || !exactReferences(stableEvent.evidenceRefs, target.evidenceRefs)) graphFailure('invalid-approval-fact');
+  }
+
+  return validatedGraphSnapshot(next);
+}
+
+export function reduceGraph(graph, event) {
+  return sanitizeGraphOperation(
+    () => reduceGraphUnsafe(graph, event),
+    'invalid-event',
+  );
+}

package/src/graph/scheduler.js

@@ -0,0 +1,252 @@
+import { graphFailure, sanitizeGraphOperation, validatedGraphSnapshot } from './validate.js';
+
+const CANDIDATE_STATES = new Set(['ready', 'corrective']);
+const ACTIVE_STATES = new Set(['reserved', 'running', 'verifying']);
+const BUDGET_KEYS = ['timeMinutes', 'tokenLimit', 'costUsd', 'taskLimit'];
+const OPTION_KEYS = new Set([
+  'maxActiveNodes',
+  'maxDelegationDepth',
+  'priorities',
+  'capacityByOwner',
+  'childCapacityByParent',
+  'budget',
+]);
+
+function codePointCompare(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function nonNegativeSafeInteger(value, reason) {
+  if (!Number.isSafeInteger(value) || value < 0) graphFailure(reason);
+  return value;
+}
+
+function decimalFromNumber(value) {
+  const match = /^(\d+)(?:\.(\d+))?(?:e([+-]?\d+))?$/i.exec(String(value));
+  if (!match) graphFailure('invalid-budget');
+  const fraction = match[2] ?? '';
+  const exponent = Number(match[3] ?? 0);
+  let coefficient = BigInt(`${match[1]}${fraction}`);
+  let scale = fraction.length - exponent;
+  if (scale < 0) {
+    coefficient *= 10n ** BigInt(-scale);
+    scale = 0;
+  }
+  while (scale > 0 && coefficient % 10n === 0n) {
+    coefficient /= 10n;
+    scale -= 1;
+  }
+  return { coefficient, scale };
+}
+
+function decimalCoefficientAt(value, scale) {
+  return value.coefficient * (10n ** BigInt(scale - value.scale));
+}
+
+function compareDecimals(left, right) {
+  const scale = Math.max(left.scale, right.scale);
+  const leftCoefficient = decimalCoefficientAt(left, scale);
+  const rightCoefficient = decimalCoefficientAt(right, scale);
+  return leftCoefficient < rightCoefficient ? -1 : leftCoefficient > rightCoefficient ? 1 : 0;
+}
+
+function subtractDecimals(left, right) {
+  const scale = Math.max(left.scale, right.scale);
+  let coefficient = decimalCoefficientAt(left, scale) - decimalCoefficientAt(right, scale);
+  if (coefficient < 0n) graphFailure('budget-underflow');
+  let normalizedScale = scale;
+  while (normalizedScale > 0 && coefficient % 10n === 0n) {
+    coefficient /= 10n;
+    normalizedScale -= 1;
+  }
+  return { coefficient, scale: normalizedScale };
+}
+
+function capturedObject(value, allowedKeys, reason) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) graphFailure(reason);
+  const keys = Object.keys(value);
+  if (keys.some(key => !allowedKeys.has(key))) graphFailure(reason);
+  const captured = {};
+  for (const key of keys) captured[key] = value[key];
+  return captured;
+}
+
+function validateOptions(rawOptions, graph) {
+  const options = capturedObject(rawOptions, OPTION_KEYS, 'invalid-scheduler-options');
+  if (!options || typeof options !== 'object' || Array.isArray(options)) graphFailure('invalid-scheduler-options');
+  const maxActiveNodes = options.maxActiveNodes === undefined
+    ? graph.nodes.length
+    : nonNegativeSafeInteger(options.maxActiveNodes, 'invalid-active-capacity');
+  const maxDelegationDepth = options.maxDelegationDepth === undefined
+    ? graph.maxDelegationDepth
+    : nonNegativeSafeInteger(options.maxDelegationDepth, 'invalid-delegation-depth');
+
+  const nodeIds = new Set(graph.nodes.map(node => node.id));
+  const ownerIds = new Set(graph.nodes.map(node => node.owner.id));
+  const parentIds = new Set(graph.nodes.flatMap(node => (node.parentId ? [node.parentId] : [])));
+  const normalizedMaps = {};
+  for (const [name, values, allowedKeys] of [
+    ['priorities', options.priorities ?? {}, nodeIds],
+    ['capacity', options.capacityByOwner ?? {}, ownerIds],
+    ['child-capacity', options.childCapacityByParent ?? {}, parentIds],
+  ]) {
+    const captured = capturedObject(values, allowedKeys, `unknown-${name}-key`);
+    for (const [id, value] of Object.entries(captured)) {
+      nonNegativeSafeInteger(value, `invalid-${name}`);
+    }
+    normalizedMaps[name] = captured;
+  }
+
+  let budget;
+  if (options.budget !== undefined) {
+    const capturedBudget = capturedObject(options.budget, new Set(BUDGET_KEYS), 'invalid-budget');
+    if (Object.keys(capturedBudget).length !== BUDGET_KEYS.length) graphFailure('invalid-budget');
+    budget = {};
+    for (const key of BUDGET_KEYS) {
+      const value = capturedBudget[key];
+      if (key === 'costUsd') {
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) graphFailure('invalid-budget');
+        budget[key] = decimalFromNumber(value);
+      } else {
+        nonNegativeSafeInteger(value, 'invalid-budget');
+        budget[key] = value;
+      }
+    }
+  }
+
+  return {
+    maxActiveNodes,
+    maxDelegationDepth,
+    priorities: normalizedMaps.priorities,
+    capacityByOwner: normalizedMaps.capacity,
+    childCapacityByParent: normalizedMaps['child-capacity'],
+    budget,
+  };
+}
+
+function dependencyDepths(graph) {
+  const nodes = new Map(graph.nodes.map(node => [node.id, node]));
+  const depths = new Map(graph.nodes.map(node => [node.id, 0]));
+  const remaining = new Map(graph.nodes.map(node => [node.id, node.dependencies.length]));
+  const dependents = new Map(graph.nodes.map(node => [node.id, []]));
+  for (const node of graph.nodes) {
+    for (const dependency of node.dependencies) dependents.get(dependency).push(node.id);
+  }
+  const queue = graph.nodes.filter(node => node.dependencies.length === 0).map(node => node.id).sort(codePointCompare);
+  for (let index = 0; index < queue.length; index += 1) {
+    const id = queue[index];
+    for (const dependentId of dependents.get(id).sort(codePointCompare)) {
+      depths.set(dependentId, Math.max(depths.get(dependentId), depths.get(id) + 1));
+      const next = remaining.get(dependentId) - 1;
+      remaining.set(dependentId, next);
+      if (next === 0) queue.push(dependentId);
+    }
+  }
+  if ([...remaining.values()].some(value => value !== 0)) graphFailure('dependency-cycle');
+  return depths;
+}
+
+function delegationDepth(node, nodes) {
+  let depth = 0;
+  let current = node;
+  while (current.parentId) {
+    depth += 1;
+    current = nodes.get(current.parentId);
+  }
+  return depth;
+}
+
+function dependenciesComplete(node, nodes) {
+  return node.dependencies.every(id => nodes.get(id).status === 'completed');
+}
+
+function candidates(graph, options) {
+  const nodes = new Map(graph.nodes.map(node => [node.id, node]));
+  const depths = dependencyDepths(graph);
+  return graph.nodes
+    .filter(node => (
+      CANDIDATE_STATES.has(node.status)
+      && dependenciesComplete(node, nodes)
+      && delegationDepth(node, nodes) <= options.maxDelegationDepth
+    ))
+    .sort((left, right) => (
+      ((options.priorities[left.id] ?? 0) < (options.priorities[right.id] ?? 0) ? 1
+        : (options.priorities[left.id] ?? 0) > (options.priorities[right.id] ?? 0) ? -1 : 0)
+      || depths.get(left.id) - depths.get(right.id)
+      || codePointCompare(left.id, right.id)
+    ));
+}
+
+function budgetFits(node, remaining) {
+  return !remaining || BUDGET_KEYS.every(key => (
+    key === 'costUsd'
+      ? compareDecimals(decimalFromNumber(node.budget[key]), remaining[key]) <= 0
+      : node.budget[key] <= remaining[key]
+  ));
+}
+
+function consumeBudget(node, remaining) {
+  if (!remaining) return;
+  for (const key of BUDGET_KEYS) {
+    remaining[key] = key === 'costUsd'
+      ? subtractDecimals(remaining[key], decimalFromNumber(node.budget[key]))
+      : remaining[key] - node.budget[key];
+  }
+}
+
+function scheduleReadyNodesUnsafe(graph, rawOptions) {
+  const stableGraph = validatedGraphSnapshot(graph);
+  return scheduleValidatedGraph(stableGraph, rawOptions);
+}
+
+function scheduleValidatedGraph(graph, rawOptions) {
+  const options = validateOptions(rawOptions, graph);
+  const active = graph.nodes.filter(node => ACTIVE_STATES.has(node.status));
+  let slots = Math.max(0, options.maxActiveNodes - active.length);
+  const ownerCounts = new Map();
+  const childCounts = new Map();
+  for (const node of active) {
+    ownerCounts.set(node.owner.id, (ownerCounts.get(node.owner.id) ?? 0) + 1);
+    if (node.parentId) childCounts.set(node.parentId, (childCounts.get(node.parentId) ?? 0) + 1);
+  }
+  const remaining = options.budget ? { ...options.budget } : undefined;
+  const selected = [];
+  for (const node of candidates(graph, options)) {
+    if (slots === 0) break;
+    const ownerCapacity = options.capacityByOwner[node.owner.id] ?? graph.nodes.length;
+    const childCapacity = node.parentId
+      ? options.childCapacityByParent[node.parentId] ?? graph.nodes.length
+      : graph.nodes.length;
+    if ((ownerCounts.get(node.owner.id) ?? 0) >= ownerCapacity) continue;
+    if (node.parentId && (childCounts.get(node.parentId) ?? 0) >= childCapacity) continue;
+    if (!budgetFits(node, remaining)) continue;
+    selected.push(node.id);
+    slots -= 1;
+    ownerCounts.set(node.owner.id, (ownerCounts.get(node.owner.id) ?? 0) + 1);
+    if (node.parentId) childCounts.set(node.parentId, (childCounts.get(node.parentId) ?? 0) + 1);
+    consumeBudget(node, remaining);
+  }
+  return selected;
+}
+
+export function scheduleReadyNodes(graph, rawOptions = {}) {
+  return sanitizeGraphOperation(
+    () => scheduleReadyNodesUnsafe(graph, rawOptions),
+    'invalid-scheduler-options',
+  );
+}
+
+export function readyNodeIds(graph, options = {}) {
+  return sanitizeGraphOperation(
+    () => scheduleReadyNodesUnsafe(graph, options),
+    'invalid-scheduler-options',
+  );
+}
+
+export function canStart(graph, nodeId, options = {}) {
+  return sanitizeGraphOperation(() => {
+    const stableGraph = validatedGraphSnapshot(graph);
+    if (!stableGraph.nodes.some(node => node.id === nodeId)) graphFailure('unknown-node');
+    return scheduleValidatedGraph(stableGraph, options).includes(nodeId);
+  }, 'invalid-scheduler-options');
+}

package/src/graph/validate.js

@@ -0,0 +1,106 @@
+import { validateGoalGraph } from '../config/validate.js';
+
+const GRAPH_KEYS = new Set(['schemaVersion', 'id', 'goal', 'providerRefs', 'maxDelegationDepth', 'status', 'nodes']);
+const NODE_KEYS = new Set([
+  'id', 'parentId', 'objective', 'owner', 'dependencies', 'authorityScopes', 'budget',
+  'completionProfile', 'requiredEvidenceTypes', 'evidenceRefs', 'status', 'approvalGate',
+]);
+const OWNER_KEYS = new Set(['role', 'id']);
+const BUDGET_KEYS = new Set(['timeMinutes', 'tokenLimit', 'costUsd', 'taskLimit']);
+
+export class GraphValidationError extends Error {
+  constructor(reason = 'invalid-graph') {
+    super('Goal graph operation is invalid.');
+    this.name = 'GraphValidationError';
+    this.code = 'ERR_INVALID_GOAL_GRAPH';
+    this.safeMessage = this.message;
+    this.details = Object.freeze({ reason });
+    Object.freeze(this);
+  }
+}
+
+export function graphFailure(reason) {
+  throw new GraphValidationError(reason);
+}
+
+export function sanitizeGraphOperation(operation, reason) {
+  try {
+    return operation();
+  } catch {
+    throw new GraphValidationError(reason);
+  }
+}
+
+function capturedObject(value, allowedKeys) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) graphFailure('invalid-graph');
+  const keys = Object.keys(value);
+  if (keys.length > allowedKeys.size || keys.some(key => !allowedKeys.has(key))) graphFailure('invalid-graph');
+  const captured = {};
+  for (const key of keys) captured[key] = value[key];
+  return captured;
+}
+
+function capturedArray(value, maximum, transform = item => item) {
+  if (!Array.isArray(value)) graphFailure('invalid-graph');
+  const length = value.length;
+  if (!Number.isSafeInteger(length) || length > maximum) graphFailure('invalid-graph');
+  const captured = [];
+  for (let index = 0; index < length; index += 1) captured.push(transform(value[index], index));
+  return captured;
+}
+
+function capturedOwner(value) {
+  return capturedObject(value, OWNER_KEYS);
+}
+
+function capturedBudget(value) {
+  return capturedObject(value, BUDGET_KEYS);
+}
+
+function capturedNode(value) {
+  const node = capturedObject(value, NODE_KEYS);
+  if ('owner' in node) node.owner = capturedOwner(node.owner);
+  if ('dependencies' in node) node.dependencies = capturedArray(node.dependencies, 100);
+  if ('authorityScopes' in node) node.authorityScopes = capturedArray(node.authorityScopes, 32);
+  if ('budget' in node) node.budget = capturedBudget(node.budget);
+  if ('requiredEvidenceTypes' in node) node.requiredEvidenceTypes = capturedArray(node.requiredEvidenceTypes, 8);
+  if ('evidenceRefs' in node) node.evidenceRefs = capturedArray(node.evidenceRefs, 64);
+  return node;
+}
+
+function capturedGraph(graph) {
+  const captured = capturedObject(graph, GRAPH_KEYS);
+  if ('providerRefs' in captured) captured.providerRefs = capturedArray(captured.providerRefs, 64);
+  if ('nodes' in captured) captured.nodes = capturedArray(captured.nodes, 1000, capturedNode);
+  return captured;
+}
+
+function validatedGraphSnapshotUnsafe(graph, config) {
+  const snapshot = capturedGraph(graph);
+  validateGoalGraph(snapshot, config);
+
+  const rolesByOwner = new Map();
+  for (const node of snapshot.nodes) {
+    const priorRole = rolesByOwner.get(node.owner.id);
+    if (priorRole && priorRole !== node.owner.role) graphFailure('owner-role-conflict');
+    rolesByOwner.set(node.owner.id, node.owner.role);
+  }
+  return snapshot;
+}
+
+export function validatedGraphSnapshot(graph, config) {
+  return sanitizeGraphOperation(
+    () => validatedGraphSnapshotUnsafe(graph, config),
+    'invalid-graph',
+  );
+}
+
+export function validateExecutionGraph(graph, config) {
+  return sanitizeGraphOperation(
+    () => {
+      validatedGraphSnapshotUnsafe(graph, config);
+      return true;
+    },
+    'invalid-graph',
+  );
+}