@agilno-tech/rivet 0.1.0-alpha.0

package/src/runtime/portable-dependencies.js

@@ -0,0 +1,94 @@
+import {createHash,randomUUID} from 'node:crypto';
+import {lstat,mkdir,writeFile} from 'node:fs/promises';
+import {dirname,join} from 'node:path';
+import {inspectDependencyDirectory as ownedDirectory,readDependencyFile as regularFile} from './dependency-directory.js';
+import {compileProjectDependencies} from '../config/commands.js';
+import {assertGitClient} from '../git/client.js';
+import {createApprovalReceipt,createApprovalRegistry} from '../policy/approvals.js';
+import {createAuthorityEnvelope} from '../policy/authority.js';
+import {runCommand,verifyCommandExecutable} from '../policy/commands.js';
+import {WorktreeBootstrapError,verifyBootstrapCheckout} from './worktree-bootstrap.js';
+
+const DIRECTORY='.rivet-deps';
+const MARKER='.rivet-owner.json';
+const hash=bytes=>createHash('sha256').update(bytes).digest('hex');
+const fail=(reason='unsafe-checkout')=>{throw new WorktreeBootstrapError(reason);};
+function cancelled(signal){signal?.throwIfAborted();}
+
+async function inputsFor(value,gitClient,config) {
+ let total=0;const files=[];
+ for(const path of config.inputs) {
+  // Every ancestor is a real directory; a tracked symlink never becomes an input.
+  let cursor=value.worktreePath;
+  for(const part of path.split('/').slice(0,-1)) {cursor=join(cursor,part);const entry=await lstat(cursor);if(!entry.isDirectory()||entry.isSymbolicLink())fail();}
+  const bytes=await regularFile(join(value.worktreePath,path),8*1024*1024);
+  total+=bytes.length;if(total>16*1024*1024)fail();
+  const tracked=await gitClient.inspectTrackedFile(value.worktreePath,value.expectedCommit,path);
+  const blob=createHash(tracked.blob.length===40?'sha1':'sha256').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+  if(blob!==tracked.blob)fail();
+  files.push(Object.freeze({path,sha256:hash(bytes)}));
+ }
+ return Object.freeze(files);
+}
+export async function inspectPortableDependencies(value,options) {
+ try {
+  assertGitClient(options.gitClient);
+  const dependencies=compileProjectDependencies({schemaVersion:3,dependencies:value.dependencies});
+  if(!dependencies)fail('invalid-input');
+  cancelled(options.signal);
+  await verifyBootstrapCheckout(value,options.gitClient);
+  const ownership=await ownedDirectory(value.worktreePath);
+  const inputs=await inputsFor(value,options.gitClient,dependencies);
+  return Object.freeze({kind:'portable',projectRoot:value.projectRoot,worktreePath:value.worktreePath,expectedCommit:value.expectedCommit,expectedBranch:value.expectedBranch,inputs,steps:dependencies.steps,provides:dependencies.provides,ownership});
+ }catch(error){if(error instanceof WorktreeBootstrapError)throw error;cancelled(options.signal);fail();}
+}
+function samePlan(a,b){return JSON.stringify(a)===JSON.stringify(b);}
+async function directoryIdentity(path) {const stat=await lstat(path,{bigint:true});return `${stat.dev}:${stat.ino}`;}
+async function ensureOwned(root,prior,signal) {
+ if(prior)return prior;
+ const path=join(root,DIRECTORY);
+ // mkdir without recursive is the ownership claim; never adopt an existing entry.
+ cancelled(signal);
+ await mkdir(path,{mode:0o700});
+ cancelled(signal);
+ await writeFile(join(path,'.gitignore'),'*\n',{flag:'wx',mode:0o600});
+ cancelled(signal);
+ await writeFile(join(path,MARKER),JSON.stringify({kind:'rivet-dependencies',version:1,root,rootIdentity:await directoryIdentity(root),directoryIdentity:await directoryIdentity(path),token:randomUUID()}),{flag:'wx',mode:0o600});
+ return ownedDirectory(root);
+}
+export async function bootstrapPortableDependencies(value,options) {
+ const plan=await inspectPortableDependencies(value,options);
+ if(typeof options.confirm!=='function'||typeof options.resolveCommandExecutable!=='function')fail('invalid-input');
+ cancelled(options.signal);
+ if(await options.confirm(plan)!==true)return Object.freeze({status:'declined'});
+ cancelled(options.signal);
+ if(!samePlan(plan,await inspectPortableDependencies(value,options)))fail();
+ cancelled(options.signal);
+ let ownership;
+ try {ownership=await ensureOwned(plan.worktreePath,plan.ownership,options.signal);}catch{fail();}
+ async function revalidate() {
+  cancelled(options.signal);
+  const current=await inspectPortableDependencies(value,options);
+  if(!samePlan({...plan,ownership},current))fail('checkout-changed');
+ }
+ const results=[];
+ for(const step of plan.steps) {
+  await revalidate();
+  const executable=await options.resolveCommandExecutable(step.argv[0],{execution:'argv',worktree:plan.worktreePath,cwd:step.cwd});
+  await verifyCommandExecutable(executable,{execution:'argv'});
+  await revalidate();
+  const nowMs=Date.now(),commandId=step.id;
+  const registry=createApprovalRegistry({approvers:[{id:'human-owner',principal:'human'}]});
+  const approval=createApprovalReceipt({id:`approval-${randomUUID()}`,approverId:'human-owner',approverPrincipal:'human',subjectId:'rivet-bootstrap',action:'dependency.install',resource:`command:${commandId}:${plan.worktreePath}`,policyId:'dependency.install',decision:'approved',expiresAt:new Date(nowMs+60000).toISOString(),singleUse:true});
+  const result=await runCommand({worktree:plan.worktreePath,authority:createAuthorityEnvelope({actorId:'rivet-bootstrap',principal:'agent',actions:['dependency.install'],ownedPaths:[],providers:[],commands:[commandId]}),commands:{[commandId]:{execution:'argv',executable,args:step.argv.slice(1),action:'dependency.install',elevated:true,approvalPolicyId:'dependency.install',approverId:'human-owner'}},environment:{PATH:[dirname(executable),dirname(process.execPath),'/usr/bin','/bin'].join(':')},timeoutMs:10*60000,maxOutputBytes:16384,maxStreamOutputBytes:16384},{actorId:'rivet-bootstrap',commandId,cwd:step.cwd,approval,approvalRegistry:registry,nowMs},{signal:options.signal});
+  results.push(result);
+  await revalidate();
+  if(result.status!=='success')return Object.freeze({status:'failed',result,results:Object.freeze(results)});
+ }
+ for(const name of plan.provides) {
+  const executable=await options.resolveCommandExecutable(name,{execution:'argv',worktree:plan.worktreePath,cwd:'.'});
+  await verifyCommandExecutable(executable,{execution:'argv'});
+ }
+ await revalidate();
+ return Object.freeze({status:'ready',results:Object.freeze(results)});
+}

package/src/runtime/recovery.js

@@ -0,0 +1,190 @@
+import { evaluateAuthority } from '../policy/authority.js';
+import { claimApproval } from '../policy/approvals.js';
+import { EVIDENCE_TYPES } from '../config/defaults.js';
+import { validatedGraphSnapshot } from '../graph/validate.js';
+import { RuntimeError, appendRuntimeEvent, remainingRuntimeNodeBudget, runtimeTransaction, transitionRuntimeState } from './orchestrator.js';
+import { heartbeatStatus } from './heartbeat.js';
+import { retryDecision, retryPolicySchedule } from './retry.js';
+
+function fail(reason) { throw new RuntimeError(reason); }
+function version(value) { if (!Number.isSafeInteger(value) || value < 0 || value >= Number.MAX_SAFE_INTEGER) fail('invalid-runtime-input'); return value; }
+function safeId(value) { return typeof value === 'string' && /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(value) && value.length <= 64; }
+
+function capture(input, allowed, required = allowed) {
+  try {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) fail('invalid-runtime-input');
+    const keys = Reflect.ownKeys(input);
+    if (keys.some(key => typeof key !== 'string' || !allowed.includes(key))) fail('invalid-runtime-input');
+    const result = {};
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(input, key);
+      if (!descriptor?.enumerable) fail('invalid-runtime-input');
+      result[key] = input[key];
+    }
+    if (required.some(key => !Object.hasOwn(result, key))) fail('invalid-runtime-input');
+    return result;
+  } catch (error) { if (error instanceof RuntimeError) throw error; fail('invalid-runtime-input'); }
+}
+function now(value) { const result = value ?? 0; if (!Number.isSafeInteger(result) || result < 0) fail('invalid-runtime-input'); return result; }
+function reason(value) { if (typeof value !== 'string' || value.length < 1 || value.length > 1000 || /[\u0000\r\n]/.test(value)) fail('invalid-runtime-input'); return value; }
+function structuralNode(state, nodeId, authority, action) {
+  if (!safeId(nodeId)) fail('invalid-runtime-input');
+  const node = state.graph.nodes.find(item => item.id === nodeId); const parent = state.graph.nodes.find(item => item.id === node?.parentId);
+  if (!node || !parent || authority?.actorId !== parent.owner.id) fail('approval-required');
+  const decision = evaluateAuthority(authority, { actorId: authority.actorId, action, resource: node.id });
+  if (decision.decision !== 'allow') fail('approval-required');
+  return node;
+}
+function retryBound(state, node) {
+  const attempts = state.attempts[node.id] ?? 1; const maximum = Math.min((state.limits?.retries ?? 2) + 1, 10);
+  if (attempts >= maximum || (state.usage?.retries ?? 0) >= (state.limits?.retries ?? 2)) fail('invalid-runtime-input');
+  state.attempts[node.id] = attempts + 1; state.usage ??= { tokens: 0, costUsd: '0', retries: 0, timeMinutes: 0, taskLimit: 0 }; state.usage.retries += 1;
+}
+function reopenGraph(state, nowMs, actorId) {
+  if (!['blocked', 'failed'].includes(state.terminal)) return;
+  if (['blocked', 'failed'].includes(state.graph.status)) transitionRuntimeState(state, state.graph, 'corrective', nowMs, { role: 'manager', id: actorId });
+  if (state.graph.status === 'corrective') transitionRuntimeState(state, state.graph, 'running', nowMs, { role: 'manager', id: actorId });
+  state.terminal = null;
+}
+
+export async function retryNode(instance, input, runtimeOptions = null) {
+  const value = capture(input, ['expectedVersion', 'nodeId', 'authority', 'reason', 'nowMs'], ['expectedVersion', 'nodeId', 'authority', 'reason']);
+  const retryReason = reason(value.reason); const nowMs = now(value.nowMs);
+  return runtimeTransaction(instance, value.expectedVersion, state => {
+    const node = structuralNode(state, value.nodeId, value.authority, 'orchestration.retry');
+    if (!['blocked', 'failed', 'corrective'].includes(node.status)) fail('invalid-runtime-input');
+    let delayMs = 0;
+    if (runtimeOptions?.retryPolicy) {
+      const decision = retryDecision(runtimeOptions.retryPolicy, { attempt: state.attempts[node.id] ?? 1, classification: 'provider-transient' });
+      if (!decision.retry || (state.usage?.retries ?? 0) >= (state.limits?.retries ?? 0)) fail('invalid-runtime-input');
+      state.attempts[node.id] = decision.nextAttempt; state.usage.retries += 1; delayMs = decision.delayMs;
+    } else retryBound(state, node);
+    delete state.heartbeats[node.id]; delete state.lastHeartbeatAt[node.id];
+    if (['failed', 'blocked'].includes(node.status)) transitionRuntimeState(state, node, 'corrective', nowMs, node.owner);
+    if (delayMs === 0) transitionRuntimeState(state, node, 'ready', nowMs, node.owner);
+    else { state.retryAtMs ??= {}; state.retryAtMs[node.id] = nowMs + delayMs; }
+    appendRuntimeEvent(state, nowMs, { actor: { role: 'manager', id: value.authority.actorId }, event: { type: 'retry', nodeId: node.id, retryReason } });
+    reopenGraph(state, nowMs, value.authority.actorId);
+    return state;
+  }, runtimeOptions?.retryPolicy ? retryPolicySchedule(runtimeOptions.retryPolicy) : null);
+}
+
+export async function cancelNode(instance, input) {
+  const value = capture(input, ['expectedVersion', 'nodeId', 'authority', 'nowMs'], ['expectedVersion', 'nodeId', 'authority']); const nowMs = now(value.nowMs);
+  return runtimeTransaction(instance, value.expectedVersion, state => {
+    const node = structuralNode(state, value.nodeId, value.authority, 'orchestration.cancel');
+    if (node.status === 'cancelled') return null;
+    if (['completed', 'archived'].includes(node.status)) fail('invalid-runtime-input');
+    const cancelled = new Set([node.id]);
+    for (let changed = true; changed;) {
+      changed = false;
+      for (const candidate of state.graph.nodes) if (!cancelled.has(candidate.id) && candidate.dependencies.some(id => cancelled.has(id))) { cancelled.add(candidate.id); changed = true; }
+    }
+    for (const candidate of state.graph.nodes) if (cancelled.has(candidate.id) && !['completed', 'archived', 'cancelled'].includes(candidate.status)) {
+      transitionRuntimeState(state, candidate, 'cancelled', nowMs, candidate.owner);
+      const intent = state.launchIntents[candidate.id];
+      if (intent && ['committed', 'prepared', 'started'].includes(intent.status)) { delete intent.preparationClaim; intent.status = 'complete'; }
+      if (intent) delete intent.retryAtMs;
+      if (state.retryAtMs) delete state.retryAtMs[candidate.id];
+    }
+    if (state.graph.status !== 'cancelled') transitionRuntimeState(state, state.graph, 'cancelled', nowMs, node.owner);
+    state.terminal = 'cancelled'; return state;
+  });
+}
+
+export async function cancelGoal(instance, input) {
+  const value = capture(input, ['expectedVersion', 'authority', 'nowMs'], ['expectedVersion', 'authority']); const nowMs = now(value.nowMs);
+  return runtimeTransaction(instance, value.expectedVersion, state => {
+    const decision = evaluateAuthority(value.authority, { actorId: value.authority?.actorId, action: 'orchestration.cancel', resource: instance.id });
+    if (value.authority?.principal !== 'human' || decision.decision !== 'allow') fail('approval-required');
+    if (state.terminal === 'cancelled') return null;
+    if (state.terminal === 'completed') fail('invalid-runtime-input');
+    for (const node of state.graph.nodes) if (!['completed', 'cancelled', 'archived'].includes(node.status)) {
+      transitionRuntimeState(state, node, 'cancelled', nowMs, { role: 'human', id: value.authority.actorId });
+      const intent = state.launchIntents[node.id];
+      if (intent && ['committed', 'prepared', 'started'].includes(intent.status)) { delete intent.preparationClaim; intent.status = 'complete'; }
+      if (intent) delete intent.retryAtMs;
+      if (state.retryAtMs) delete state.retryAtMs[node.id];
+    }
+    if (state.graph.status !== 'cancelled') transitionRuntimeState(state, state.graph, 'cancelled', nowMs, { role: 'human', id: value.authority.actorId });
+    state.terminal = 'cancelled'; return state;
+  });
+}
+
+export async function createCorrectiveNode(instance, input) {
+  const captured = capture(input, ['expectedVersion', 'sourceNodeId', 'nodeId', 'ownerId', 'authority', 'reason', 'evidenceRefs', 'evidenceTypes', 'nowMs'], ['expectedVersion', 'sourceNodeId', 'nodeId', 'ownerId', 'authority', 'reason', 'evidenceRefs']);
+  const evidenceRefs = Array.isArray(captured.evidenceRefs) ? [...captured.evidenceRefs] : captured.evidenceRefs; const retryReason = reason(captured.reason); const nowMs = now(captured.nowMs);
+  if (![captured.sourceNodeId, captured.nodeId, captured.ownerId].every(safeId) || !Array.isArray(evidenceRefs) || evidenceRefs.length < 1 || evidenceRefs.length > 8 || evidenceRefs.some(item => !safeId(item)) || new Set(evidenceRefs).size !== evidenceRefs.length) fail('invalid-runtime-input');
+  return runtimeTransaction(instance, captured.expectedVersion, state => {
+    if (state.graph.nodes.some(node => node.id === captured.nodeId) || state.graph.nodes.length >= 1000) fail('invalid-runtime-input');
+    const source = structuralNode(state, captured.sourceNodeId, captured.authority, 'orchestration.correct');
+    if (!['failed', 'blocked', 'corrective'].includes(source.status)) fail('invalid-runtime-input');
+    retryBound(state, source);
+    const evidenceTypes = captured.evidenceTypes === undefined ? [...source.requiredEvidenceTypes] : Array.isArray(captured.evidenceTypes) ? [...captured.evidenceTypes] : captured.evidenceTypes;
+    if (!Array.isArray(evidenceTypes) || evidenceTypes.length !== evidenceRefs.length || evidenceTypes.length > 8
+      || evidenceTypes.some(item => !EVIDENCE_TYPES.includes(item)) || new Set(evidenceTypes).size !== evidenceTypes.length) fail('invalid-runtime-input');
+    evidenceTypes.sort(); evidenceRefs.sort();
+    const inheritedEvidenceTypes = [...source.requiredEvidenceTypes].sort();
+    if (evidenceTypes.length !== inheritedEvidenceTypes.length
+      || evidenceTypes.some((item, index) => item !== inheritedEvidenceTypes[index])) fail('invalid-runtime-input');
+    const remaining = remainingRuntimeNodeBudget(state, source);
+    if (remaining.timeMinutes < 1 || remaining.tokenLimit < 1 || remaining.taskLimit < 1) fail('invalid-runtime-input');
+    const correctiveCost = Number(remaining.costUsd);
+    if (!Number.isFinite(correctiveCost) || correctiveCost <= 0) fail('invalid-runtime-input');
+    const corrective = { id: captured.nodeId, parentId: source.parentId, objective: `Correct ${source.id}: ${retryReason}`.slice(0, 2000), owner: { role: 'worker', id: captured.ownerId }, dependencies: [...source.dependencies], authorityScopes: [...source.authorityScopes], budget: { ...remaining, costUsd: correctiveCost }, completionProfile: source.completionProfile, requiredEvidenceTypes: evidenceTypes, evidenceRefs: [...evidenceRefs], status: 'corrective' };
+    if (source.status === 'blocked') transitionRuntimeState(state, source, 'failed', nowMs, source.owner);
+    if (state.graph.nodes.find(node => node.id === source.id).status === 'corrective') transitionRuntimeState(state, source, 'failed', nowMs, source.owner);
+    transitionRuntimeState(state, source, 'archived', nowMs, source.owner);
+    const nodes = state.graph.nodes.map(node => ({ ...node, dependencies: node.dependencies.map(id => id === source.id ? corrective.id : id) }));
+    state.graph = validatedGraphSnapshot({ ...state.graph, nodes: [...nodes, corrective] });
+    appendRuntimeEvent(state, nowMs, { actor: { role: 'manager', id: captured.authority.actorId }, event: { type: 'retry', nodeId: source.id, retryReason: `corrective:${retryReason}` } });
+    reopenGraph(state, nowMs, captured.authority.actorId);
+    return state;
+  });
+}
+
+export async function recoverStalledNode(instance, input) {
+  const value = capture(input, ['expectedVersion', 'nodeId', 'authority', 'nowMs', 'reason']); const nowMs = now(value.nowMs); const retryReason = reason(value.reason);
+  return runtimeTransaction(instance, value.expectedVersion, state => {
+    const node = structuralNode(state, value.nodeId, value.authority, 'orchestration.recover');
+    const intent = state.launchIntents[node.id]; const heartbeat = state.heartbeats[node.id];
+    if (!['reserved', 'running'].includes(node.status) || !intent || !['committed', 'prepared', 'started'].includes(intent.status) || !heartbeat) fail('invalid-runtime-input');
+    const liveness = heartbeatStatus(heartbeat, { nowMs, expected: { instanceId: instance.id, nodeId: node.id, actorId: node.owner.id, leaseId: intent.reservationId } });
+    if (liveness.status !== 'stalled') fail('invalid-runtime-input');
+    retryBound(state, node);
+    if (node.status === 'running') {
+      transitionRuntimeState(state, node, 'corrective', nowMs, node.owner);
+      transitionRuntimeState(state, node, 'ready', nowMs, node.owner);
+    } else transitionRuntimeState(state, node, 'ready', nowMs, node.owner);
+    delete state.heartbeats[node.id]; delete state.lastHeartbeatAt[node.id];
+    delete intent.preparationClaim; intent.status = 'recovered'; appendRuntimeEvent(state, nowMs, { actor: { role: 'manager', id: value.authority.actorId }, event: { type: 'retry', nodeId: node.id, retryReason } }); return state;
+  });
+}
+
+export async function recoverRuntimeLock(target, input) {
+  const value = capture(input, ['expectedVersion', 'nowMs', 'authority', 'approval', 'approvalRegistry', 'expectedApproverId']);
+  if (!target || !safeId(target.id) || typeof target.version !== 'function' || typeof target.inspectLock !== 'function' || typeof target.recoverLock !== 'function') fail('invalid-runtime-input');
+  const expectedVersion = version(value.expectedVersion); const nowMs = now(value.nowMs);
+  if (await target.version() !== expectedVersion) fail('version-conflict');
+  const lock = capture(await target.inspectLock(), ['ownerId', 'acquiredAtMs', 'expiresAtMs', 'ownerAlive']);
+  if (!safeId(lock.ownerId) || !Number.isSafeInteger(lock.acquiredAtMs) || !Number.isSafeInteger(lock.expiresAtMs) || lock.acquiredAtMs < 0 || lock.expiresAtMs <= lock.acquiredAtMs || nowMs < lock.expiresAtMs || lock.ownerAlive !== false) fail('invalid-runtime-input');
+  const decision = evaluateAuthority(value.authority, { actorId: value.authority?.actorId, action: 'orchestration.recover', resource: target.id });
+  if (decision.decision !== 'allow') fail('approval-required');
+  const claim = claimApproval(value.approval, { subjectId: value.authority.actorId, action: 'orchestration.recover', resource: target.id, policyId: 'runtime.stale-lock-recovery' }, { registry: value.approvalRegistry, expectedApproverId: value.expectedApproverId, requireHumanApprover: true, requireSingleUse: true, nowMs });
+  if (!claim.valid) fail('approval-required');
+  try {
+    if (!claim.finalize()) fail('approval-required');
+    await target.recoverLock(Object.freeze({ expectedVersion, expectedOwnerId: lock.ownerId, expectedExpiresAtMs: lock.expiresAtMs, nowMs, requireOwnerDead: true }));
+    if (!claim.publish()) fail('approval-required');
+    return Object.freeze({ recovered: true, expectedVersion });
+  } catch (error) {
+    try {
+      const observedLock = capture(await target.inspectLock(), ['ownerId', 'acquiredAtMs', 'expiresAtMs', 'ownerAlive']);
+      const unchanged = observedLock.ownerId === lock.ownerId && observedLock.acquiredAtMs === lock.acquiredAtMs
+        && observedLock.expiresAtMs === lock.expiresAtMs && observedLock.ownerAlive === lock.ownerAlive;
+      if (unchanged) { if (!claim.rollback()) claim.release(); }
+      else claim.publish();
+    } catch { /* Ambiguous recovery remains finalized and unusable. */ }
+    throw error;
+  }
+}

package/src/runtime/retry.js

@@ -0,0 +1,54 @@
+const ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const policies = new WeakSet();
+export const MAX_RETRY_DELAY_MS = 3_600_000;
+
+export class RetryPolicyError extends Error {
+  constructor(reason = 'invalid-retry-policy') {
+    super('Runtime retry policy is invalid.');
+    this.name = 'RetryPolicyError';
+    this.code = 'ERR_RUNTIME_RETRY_POLICY';
+    this.safeMessage = this.message;
+    this.details = Object.freeze({ reason });
+  }
+}
+
+function fail(reason) { throw new RetryPolicyError(reason); }
+
+export function createRetryPolicy(input) {
+  try {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) fail('invalid-retry-policy');
+    const keys = Reflect.ownKeys(input);
+    if (keys.some(key => typeof key !== 'string' || !['maxAttempts', 'delaysMs', 'retryable'].includes(key))) fail('invalid-retry-policy');
+    const maxAttempts = input.maxAttempts;
+    const delays = input.delaysMs;
+    const retryable = input.retryable;
+    if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 16
+      || !Array.isArray(delays) || delays.length !== Math.max(0, maxAttempts - 1) || delays.length > 15
+      || delays.some(value => !Number.isSafeInteger(value) || value < 0 || value > MAX_RETRY_DELAY_MS)
+      || !Array.isArray(retryable) || retryable.length > 32
+      || retryable.some(value => typeof value !== 'string' || value.length > 64 || !ID.test(value))
+      || new Set(retryable).size !== retryable.length) fail('invalid-retry-policy');
+    const policy = Object.freeze({ maxAttempts, delaysMs: Object.freeze([...delays]), retryable: Object.freeze([...retryable].sort()) });
+    policies.add(policy);
+    return policy;
+  } catch (error) { if (error instanceof RetryPolicyError) throw error; fail('invalid-retry-policy'); }
+}
+
+export function retryDecision(policy, input) {
+  try {
+    if (!policies.has(policy) || !input || typeof input !== 'object' || Array.isArray(input)) fail('invalid-retry-decision');
+    const keys = Reflect.ownKeys(input);
+    if (keys.some(key => typeof key !== 'string' || !['attempt', 'classification'].includes(key))) fail('invalid-retry-decision');
+    const attempt = input.attempt;
+    const classification = input.classification;
+    if (!Number.isSafeInteger(attempt) || attempt < 1 || attempt > 16 || typeof classification !== 'string' || !ID.test(classification)) fail('invalid-retry-decision');
+    if (!policy.retryable.includes(classification)) return Object.freeze({ retry: false, reason: 'not-retryable' });
+    if (attempt >= policy.maxAttempts) return Object.freeze({ retry: false, reason: 'attempts-exhausted' });
+    return Object.freeze({ retry: true, nextAttempt: attempt + 1, delayMs: policy.delaysMs[attempt - 1] });
+  } catch (error) { if (error instanceof RetryPolicyError) throw error; fail('invalid-retry-decision'); }
+}
+
+export function retryPolicySchedule(policy) {
+  if (!policies.has(policy)) fail('invalid-retry-policy');
+  return policy.delaysMs;
+}

package/src/runtime/supervisor.js

@@ -0,0 +1,166 @@
+const TERMINAL = new Set(['complete', 'completed', 'blocked', 'cancelled', 'budget-exhausted', 'failed']);
+const ABORTED_GETTER = Object.getOwnPropertyDescriptor(AbortSignal.prototype, 'aborted')?.get;
+const ADD_ABORT_LISTENER = AbortSignal.prototype.addEventListener;
+const REMOVE_ABORT_LISTENER = AbortSignal.prototype.removeEventListener;
+
+export class SupervisorError extends Error {
+  constructor(reason = 'invalid-watch') {
+    super('Orchestration watch request is invalid.');
+    this.name = 'SupervisorError'; this.code = 'ERR_RUNTIME_SUPERVISOR'; this.safeMessage = this.message;
+    this.details = Object.freeze({ reason });
+  }
+}
+
+function fail(reason) { throw new SupervisorError(reason); }
+
+function readClock(now, prior) {
+  let value;
+  try { value = now(); } catch { fail('clock-failed'); }
+  if (Number.isSafeInteger(value) && Number.isSafeInteger(prior) && value < prior) fail('clock-regressed');
+  return value;
+}
+
+function captureSignal(value) {
+  if (value === undefined) return Object.freeze({ signal: undefined, release() {} });
+  try {
+    if (!(value instanceof AbortSignal) || typeof ABORTED_GETTER !== 'function') fail('invalid-watch');
+    const controller = new AbortController(); const relayAbort = () => controller.abort();
+    const aborted = ABORTED_GETTER.call(value);
+    if (typeof aborted !== 'boolean') fail('invalid-watch');
+    let listening = false;
+    if (aborted) controller.abort();
+    else {
+      ADD_ABORT_LISTENER.call(value, 'abort', relayAbort, { once: true }); listening = true;
+      if (ABORTED_GETTER.call(value)) relayAbort();
+    }
+    return Object.freeze({
+      signal: controller.signal,
+      release() {
+        if (!listening) return;
+        listening = false;
+        try { REMOVE_ABORT_LISTENER.call(value, 'abort', relayAbort); } catch {}
+      },
+    });
+  } catch { fail('invalid-watch'); }
+}
+
+function captureTickResult(value) {
+  let terminal; let version;
+  try {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) fail('tick-output');
+    terminal = value.terminal; version = value.version;
+  } catch { fail('tick-output'); }
+  if (TERMINAL.has(terminal)) return Object.freeze({ terminal, version });
+  if (terminal !== null || !Number.isSafeInteger(version) || version < 0) fail('tick-output');
+  return Object.freeze({ terminal, version });
+}
+
+async function boundedWait(wait, intervalMs, signal) {
+  const controller = new AbortController(); const timeoutToken = Object.freeze(Object.create(null)); const abortToken = Object.freeze(Object.create(null));
+  let timer; let resolveAbort; let externallyAborted = false; let timedOut = false;
+  const relayAbort = () => { externallyAborted = true; resolveAbort?.(abortToken); controller.abort(); };
+  signal?.addEventListener('abort', relayAbort, { once: true });
+  try {
+    const operation = Promise.resolve().then(() => wait(intervalMs, controller.signal))
+      .then(() => Object.freeze({ ok: true }), () => Object.freeze({ ok: false }));
+    const timeout = new Promise(resolve => { timer = setTimeout(() => { timedOut = true; resolve(timeoutToken); controller.abort(); }, intervalMs); });
+    const aborted = new Promise(resolve => { resolveAbort = resolve; if (signal?.aborted) relayAbort(); });
+    const result = await Promise.race([operation, timeout, aborted]);
+    if (result === abortToken || externallyAborted) return 'aborted';
+    if (result === timeoutToken || timedOut) return 'timeout';
+    if (result !== timeoutToken && result.ok !== true) fail('wait-failed');
+    return 'settled';
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    signal?.removeEventListener('abort', relayAbort);
+  }
+}
+
+async function boundedTick(runtime, tick, instance, expectedVersion, timeoutMs, signal) {
+  const controller = new AbortController();
+  const timeoutToken = Object.freeze({ status: 'timeout' });
+  const abortToken = Object.freeze({ status: 'aborted' });
+  const lateToken = Object.freeze({ status: 'late' });
+  let expired = false; let timer; let resolveAbort; let timeoutRemaining = timeoutMs;
+  const relayAbort = () => { controller.abort(); resolveAbort?.(abortToken); };
+  signal?.addEventListener('abort', relayAbort, { once: true });
+  try {
+    const operation = Promise.resolve()
+      .then(() => tick.call(runtime, instance, { expectedVersion, signal: controller.signal }))
+      .then(
+        value => expired ? lateToken : Object.freeze({ status: 'settled', ok: true, value }),
+        () => expired ? lateToken : Object.freeze({ status: 'settled', ok: false }),
+      );
+    const timeout = new Promise(resolve => {
+      const schedule = () => {
+        const delay = Math.min(timeoutRemaining, 2_147_483_647);
+        timer = setTimeout(() => {
+          timeoutRemaining -= delay;
+          if (timeoutRemaining > 0) schedule();
+          else { expired = true; controller.abort(); resolve(timeoutToken); }
+        }, delay);
+      };
+      schedule();
+    });
+    const aborted = new Promise(resolve => { resolveAbort = resolve; if (signal?.aborted) relayAbort(); });
+    const result = await Promise.race([operation, timeout, aborted]);
+    if (result === timeoutToken || result === abortToken) { expired = true; return result; }
+    if (result.ok !== true) fail('tick-failed');
+    return result;
+  } finally {
+    expired = true;
+    if (timer !== undefined) clearTimeout(timer);
+    signal?.removeEventListener('abort', relayAbort);
+  }
+}
+
+export async function watchOrchestration(runtime, instance, input) {
+    let tick; let expectedVersion; let intervalMs; let maxTicks; let deadlineMs; let now; let wait; let signal;
+    try {
+      if (!runtime || !instance || !input || typeof input !== 'object' || Array.isArray(input)) fail('invalid-watch');
+      const prototype = Object.getPrototypeOf(input);
+      if (prototype !== Object.prototype && prototype !== null) fail('invalid-watch');
+      const allowed = new Set(['expectedVersion', 'intervalMs', 'maxTicks', 'deadlineMs', 'now', 'wait', 'signal']);
+      const required = ['expectedVersion', 'intervalMs', 'maxTicks', 'deadlineMs', 'now', 'wait'];
+      const keys = Reflect.ownKeys(input);
+      if (keys.length > allowed.size || keys.some(key => typeof key !== 'string' || !allowed.has(key))
+        || required.some(key => !keys.includes(key))) fail('invalid-watch');
+      for (const key of keys) if (!Object.getOwnPropertyDescriptor(input, key)?.enumerable) fail('invalid-watch');
+      tick = runtime.tick;
+      if (typeof tick !== 'function') fail('invalid-watch');
+      expectedVersion = input.expectedVersion;
+      intervalMs = input.intervalMs;
+      maxTicks = input.maxTicks;
+      deadlineMs = input.deadlineMs;
+      now = input.now;
+      wait = input.wait;
+      signal = input.signal;
+    } catch { fail('invalid-watch'); }
+    if (!Number.isSafeInteger(expectedVersion) || expectedVersion < 0 || !Number.isSafeInteger(intervalMs) || intervalMs < 1 || intervalMs > 60_000
+      || !Number.isSafeInteger(maxTicks) || maxTicks < 1 || maxTicks > 10_000 || !Number.isSafeInteger(deadlineMs) || deadlineMs < 0
+      || typeof now !== 'function' || typeof wait !== 'function') fail('invalid-watch');
+    const signalBoundary = captureSignal(signal); signal = signalBoundary.signal;
+    try {
+    let version = expectedVersion; let lastClock;
+    for (let ticks = 1; ticks <= maxTicks; ticks += 1) {
+      if (signal?.aborted) return Object.freeze({ terminal: 'cancelled', ticks: ticks - 1 });
+      const current = readClock(now, lastClock); lastClock = current;
+      if (!Number.isSafeInteger(current) || current < 0 || current > deadlineMs) return Object.freeze({ terminal: 'deadline', ticks: ticks - 1 });
+      const remainingForTick = deadlineMs - current;
+      if (remainingForTick <= 0) return Object.freeze({ terminal: 'deadline', ticks: ticks - 1 });
+      const tickOutcome = await boundedTick(runtime, tick, instance, version, remainingForTick, signal);
+      if (tickOutcome.status === 'timeout') return Object.freeze({ terminal: 'deadline', ticks });
+      if (tickOutcome.status === 'aborted') return Object.freeze({ terminal: 'cancelled', ticks });
+      const result = captureTickResult(tickOutcome.value);
+      if (TERMINAL.has(result.terminal)) return Object.freeze({ terminal: result.terminal, ticks });
+      version = result.version;
+      if (ticks === maxTicks) return Object.freeze({ terminal: 'max-ticks', ticks });
+      const afterTick = readClock(now, lastClock); lastClock = afterTick;
+      const remaining = deadlineMs - afterTick;
+      if (!Number.isSafeInteger(remaining) || remaining <= 0) return Object.freeze({ terminal: 'deadline', ticks });
+      const waitOutcome = await boundedWait(wait, Math.min(intervalMs, remaining), signal);
+      if (waitOutcome === 'aborted') return Object.freeze({ terminal: 'cancelled', ticks });
+    }
+    fail('invalid-watch');
+    } finally { signalBoundary.release(); }
+}