@ikon85/agent-workflow-kit 0.44.2 → 0.45.0

package/src/lib/dispatchJournal.mjs

@@ -0,0 +1,300 @@
+/**
+ * The dispatch journal — the durable, owner-only record of what a dispatch was
+ * about to do and what became of it.
+ *
+ * A receipt proves what ran; the journal is what makes a *crash* provable. The
+ * `prepared` entry is written before the spawn and its terminal entry after, so
+ * a process that dies in between leaves an entry that is neither dispatched nor
+ * blocked. That entry is indeterminate: the agent may or may not have been
+ * started, and nothing on disk can tell the difference.
+ *
+ * How an indeterminate entry resolves is a property of the surface, not a
+ * preference:
+ *
+ * - **Claude** has a caller-assignable spawn id (`claude --session-id <uuid>`),
+ *   assigned before the spawn and refused loudly on reuse. A retry against that
+ *   id therefore cannot start a second agent. The id is scoped per
+ *   `(cwd, session-id)` — the same uuid re-run from another working directory
+ *   was accepted — so the journal keys on the pair and a recovery is valid only
+ *   from the directory that prepared it.
+ * - **Codex** exposes no caller-assignable thread id at all (`resume` only
+ *   targets an already-recorded session), so an indeterminate Codex entry keeps
+ *   blocking pending reconciliation.
+ *
+ * The file is `0600`, append-only under an exclusive lock, and carries a closed,
+ * redacted field set: no task text, no prompt, no adapter diagnostic. A line
+ * truncated by a crash is quarantined rather than fatal — the readable entries
+ * survive, the damage is counted, and an execution whose state cannot be proven
+ * clear blocks until a prune reconciles it.
+ */
+import { appendFile, chmod, mkdir, readFile, rmdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+import { writeAtomic } from './atomicWrite.mjs';
+
+export const DISPATCH_JOURNAL_VERSION = 1;
+/** User-local dispatch evidence: owner-only, like every other routing document. */
+export const DISPATCH_JOURNAL_MODE = 0o600;
+export const DEFAULT_JOURNAL_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+
+export const JOURNAL_PHASES = Object.freeze([
+  'prepared', 'dispatched', 'handed-off', 'blocked',
+]);
+export const TERMINAL_JOURNAL_PHASES = Object.freeze(['dispatched', 'handed-off', 'blocked']);
+export const DISPATCH_RECOVERY_STATES = Object.freeze([
+  'clear', 'settled', 'retry-idempotent', 'blocked-pending-reconciliation',
+]);
+/** The surfaces that can pre-assign a spawn id, and so may retry a crash. */
+export const IDEMPOTENT_DISPATCH_SURFACES = Object.freeze(['claude']);
+
+const ENTRY_FIELDS = [
+  'schemaVersion', 'phase', 'executionId', 'surfaceId', 'transportId', 'cwd',
+  'idempotencyKey', 'taskId', 'reason', 'authorizationId', 'recordedAt',
+];
+const RECEIPT_PHASE = Object.freeze({
+  'routed-dispatch': 'dispatched',
+  'inherited-dispatch': 'dispatched',
+  handoff: 'handed-off',
+  blocked: 'blocked',
+});
+
+const MAX_FIELD_LENGTH = 512;
+const CONTROL_CHARACTERS = /[\u0000-\u001F\u007F]/;
+const LOCK_TIMEOUT_MS = 2000;
+const LOCK_POLL_MS = 10;
+
+const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+
+/** Every recorded value is short, printable and free of consumer task data. */
+function redacted(value, field, optional = false) {
+  if (value == null && optional) return null;
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`dispatch journal entry ${field} must be a non-empty string`);
+  }
+  if (value.length > MAX_FIELD_LENGTH) {
+    throw new TypeError(`dispatch journal entry ${field} exceeds the redacted length limit`);
+  }
+  if (CONTROL_CHARACTERS.test(value)) {
+    throw new TypeError(`dispatch journal entry ${field} must carry no control characters`);
+  }
+  return value;
+}
+
+function assertPhaseFields(entry) {
+  if (!JOURNAL_PHASES.includes(entry.phase)) {
+    throw new TypeError(
+      `dispatch journal entry phase must be one of: ${JOURNAL_PHASES.join(', ')}`,
+    );
+  }
+  if (entry.taskId != null && entry.phase !== 'dispatched') {
+    throw new TypeError('dispatch journal entry taskId is recorded on a dispatched entry only');
+  }
+  if (entry.reason != null && !TERMINAL_JOURNAL_PHASES.includes(entry.phase)) {
+    throw new TypeError('dispatch journal entry reason is recorded on a terminal entry only');
+  }
+}
+
+export function validateDispatchJournalEntry(entry) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw new TypeError('dispatch journal entry must be an object');
+  }
+  for (const key of Object.keys(entry)) {
+    if (!ENTRY_FIELDS.includes(key)) {
+      throw new TypeError(`dispatch journal entry must carry no consumer task data: ${key}`);
+    }
+  }
+  if (entry.schemaVersion != null && entry.schemaVersion !== DISPATCH_JOURNAL_VERSION) {
+    throw new TypeError(`dispatch journal entry schemaVersion must be ${DISPATCH_JOURNAL_VERSION}`);
+  }
+  assertPhaseFields(entry);
+  const recordedAt = redacted(entry.recordedAt, 'recordedAt');
+  if (!Number.isFinite(Date.parse(recordedAt))) {
+    throw new TypeError('dispatch journal entry recordedAt must be an ISO timestamp');
+  }
+  return Object.freeze({
+    schemaVersion: DISPATCH_JOURNAL_VERSION,
+    phase: entry.phase,
+    executionId: redacted(entry.executionId, 'executionId'),
+    surfaceId: redacted(entry.surfaceId, 'surfaceId'),
+    transportId: redacted(entry.transportId, 'transportId', true),
+    cwd: redacted(entry.cwd, 'cwd'),
+    idempotencyKey: redacted(entry.idempotencyKey, 'idempotencyKey', true),
+    taskId: redacted(entry.taskId, 'taskId', true),
+    reason: redacted(entry.reason, 'reason', true),
+    authorizationId: redacted(entry.authorizationId, 'authorizationId', true),
+    recordedAt,
+  });
+}
+
+/**
+ * The pre-assigned spawn id a retry may reuse, or `null` when the surface has
+ * none. The key is the `(cwd, session-id)` pair because that is the scope the
+ * host actually enforces.
+ */
+export function dispatchIdempotencyKey({ surfaceId, cwd, sessionId = null } = {}) {
+  redacted(cwd, 'cwd');
+  if (!IDEMPOTENT_DISPATCH_SURFACES.includes(surfaceId) || sessionId == null) return null;
+  return `${surfaceId}:${cwd}::${redacted(sessionId, 'idempotencyKey')}`;
+}
+
+async function withJournalLock(file, lockTimeoutMs, run) {
+  const lock = `${file}.lock`;
+  const deadline = Date.now() + lockTimeoutMs;
+  for (;;) {
+    try {
+      await mkdir(lock, { recursive: false });
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      if (Date.now() >= deadline) throw new Error(`dispatch journal is locked: ${lock}`);
+      await sleep(LOCK_POLL_MS);
+    }
+  }
+  try {
+    return await run();
+  } finally {
+    await rmdir(lock).catch(() => {});
+  }
+}
+
+/** Append one entry. The lock serializes writers; `0600` is enforced every time. */
+export async function appendDispatchJournalEntry(file, entry, options = {}) {
+  const validated = validateDispatchJournalEntry(entry);
+  const { lockTimeoutMs = LOCK_TIMEOUT_MS } = options;
+  await mkdir(dirname(file), { recursive: true });
+  return withJournalLock(file, lockTimeoutMs, async () => {
+    await appendFile(file, `${JSON.stringify(validated)}\n`, {
+      encoding: 'utf8', mode: DISPATCH_JOURNAL_MODE,
+    });
+    await chmod(file, DISPATCH_JOURNAL_MODE);
+    return validated;
+  });
+}
+
+/**
+ * Read the journal. A line a crash truncated is counted as damage — by position
+ * and size, never by content — and every readable entry survives it.
+ */
+export async function readDispatchJournal(file) {
+  let raw;
+  try {
+    raw = await readFile(file, 'utf8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return Object.freeze({ entries: Object.freeze([]), damaged: Object.freeze([]) });
+  }
+  const entries = [];
+  const damaged = [];
+  raw.split('\n').forEach((line, index) => {
+    if (line.trim() === '') return;
+    try {
+      entries.push(validateDispatchJournalEntry(JSON.parse(line)));
+    } catch {
+      damaged.push(Object.freeze({ line: index + 1, bytes: line.length }));
+    }
+  });
+  return Object.freeze({ entries: Object.freeze(entries), damaged: Object.freeze(damaged) });
+}
+
+function outcome(state, reason, entry) {
+  if (!DISPATCH_RECOVERY_STATES.includes(state)) {
+    throw new TypeError(`unknown dispatch recovery state: ${state}`);
+  }
+  return Object.freeze({ state, reason, entry });
+}
+
+/** What an indeterminate `prepared` entry permits, decided by surface. */
+function indeterminate(entry, surfaceId, idempotencyKey) {
+  if (!IDEMPOTENT_DISPATCH_SURFACES.includes(surfaceId)) {
+    return outcome(
+      'blocked-pending-reconciliation', `no-idempotency-key-on-surface:${surfaceId}`, entry,
+    );
+  }
+  if (idempotencyKey == null || entry.idempotencyKey == null) {
+    return outcome('blocked-pending-reconciliation', 'no-idempotency-key-recorded', entry);
+  }
+  if (entry.idempotencyKey !== idempotencyKey) {
+    return outcome('blocked-pending-reconciliation', 'idempotency-key-scope-mismatch', entry);
+  }
+  return outcome('retry-idempotent', 'idempotency-key-reserved', entry);
+}
+
+/**
+ * Decide what one execution may still do. A settled execution never dispatches
+ * again, an indeterminate one retries only against a pre-assigned key, and
+ * unidentifiable damage cannot prove anything clear.
+ */
+export function planDispatchRecovery({
+  entries = [], damaged = [], executionId, surfaceId, idempotencyKey = null,
+} = {}) {
+  redacted(executionId, 'executionId');
+  redacted(surfaceId, 'surfaceId');
+  const mine = entries.filter((entry) => entry.executionId === executionId);
+  const last = mine[mine.length - 1] ?? null;
+  if (last && TERMINAL_JOURNAL_PHASES.includes(last.phase)) {
+    return outcome('settled', `already-recorded:${last.phase}`, last);
+  }
+  if (last) return indeterminate(last, surfaceId, idempotencyKey);
+  if (damaged.length > 0) {
+    return outcome('blocked-pending-reconciliation', 'journal-damaged', null);
+  }
+  return outcome('clear', 'no-indeterminate-entry', null);
+}
+
+function indeterminateExecutions(entries) {
+  const last = new Map();
+  for (const entry of entries) last.set(entry.executionId, entry);
+  return new Set([...last.values()]
+    .filter((entry) => entry.phase === 'prepared')
+    .map((entry) => entry.executionId));
+}
+
+/**
+ * Retention: aged terminal entries are dropped, an indeterminate execution is
+ * kept at any age (dropping it would silently unblock a crash), and damage is
+ * only discarded when the caller explicitly reconciles it.
+ */
+export async function pruneDispatchJournal(file, options = {}) {
+  const {
+    retainMs = DEFAULT_JOURNAL_RETENTION_MS, now = Date.now(),
+    dropDamaged = false, lockTimeoutMs = LOCK_TIMEOUT_MS,
+  } = options;
+  return withJournalLock(file, lockTimeoutMs, async () => {
+    const { entries, damaged } = await readDispatchJournal(file);
+    if (damaged.length > 0 && !dropDamaged) {
+      throw new Error('dispatch journal has damaged entries: reconcile with dropDamaged');
+    }
+    const pending = indeterminateExecutions(entries);
+    const kept = entries.filter((entry) => pending.has(entry.executionId)
+      || Date.parse(entry.recordedAt) > now - retainMs);
+    await writeAtomic(
+      file,
+      kept.map((entry) => `${JSON.stringify(entry)}\n`).join(''),
+      DISPATCH_JOURNAL_MODE,
+    );
+    return Object.freeze({
+      kept: kept.length,
+      dropped: entries.length - kept.length,
+      damagedDropped: damaged.length,
+    });
+  });
+}
+
+/** The terminal entry one receipt of any kind leaves behind. */
+export function journalEntryForReceipt(receipt, context = {}) {
+  const phase = RECEIPT_PHASE[receipt?.kind];
+  if (!phase) throw new TypeError(`unknown dispatch receipt kind: ${receipt?.kind}`);
+  const route = receipt.appliedRoute ?? receipt.requestedRoute ?? null;
+  return validateDispatchJournalEntry({
+    phase,
+    executionId: receipt.executionId,
+    surfaceId: context.surfaceId ?? route?.surfaceId ?? null,
+    transportId: context.transportId ?? route?.transportId ?? null,
+    cwd: context.cwd,
+    idempotencyKey: context.idempotencyKey ?? null,
+    taskId: phase === 'dispatched' ? context.taskId ?? null : null,
+    reason: phase === 'dispatched' ? null : receipt.reason,
+    authorizationId: receipt.authorizationId ?? null,
+    recordedAt: receipt.dispatchedAt,
+  });
+}

package/src/lib/dispatchPlan.mjs

@@ -0,0 +1,286 @@
+/**
+ * The Dispatch plan and the authorization record that binds it.
+ *
+ * A delegating workflow presents one table before its first dispatch: each unit
+ * of work with its Routing intent, the chosen route, and the reason that route
+ * won. It runs the two stages in order — intent resolution first (an explicit
+ * intent, otherwise the provider-neutral workflow classifier), then route
+ * selection against decisive evidence, otherwise the Standard route for the
+ * resolved workload class. A route is never an intent source, so nothing that
+ * comes out of stage two ever flows back into stage one.
+ *
+ * The plan is canonicalized and hashed over every unit, intent, route, reason
+ * and the policy, catalog and Access-graph revisions, and that hash is bound to
+ * an authorization record naming id, scope, mode, timestamp and actor. Every
+ * dispatch references the record and every receipt carries its id, so a wave is
+ * authorized once and that authorization cannot silently cover something else:
+ * a mismatch blocks pending a newly attributed authorization. Only a recorded
+ * mode that explicitly permits bounded dynamic re-resolution continues, and only
+ * within the axes it names — a bound may accept a *different route for the same
+ * work*, never different work and never a changed authorization basis, which is
+ * why `units`, `intent`, `intentSource` and `policy` can never be bounded.
+ */
+import { createHash } from 'node:crypto';
+
+import { resolveRoute } from './routingResolver.mjs';
+import { resolveRoutingIntent } from './routingIntentClassifier.mjs';
+
+export const DISPATCH_PLAN_VERSION = 1;
+
+export const PLAN_AUTHORIZATION_MODES = Object.freeze(['fixed', 'bounded-re-resolution']);
+
+/** What a bounded mode may cover: a re-chosen route and the facts that moved it. */
+export const BOUNDED_RE_RESOLUTION_AXES = Object.freeze([
+  'route', 'reason', 'origin', 'state', 'catalog', 'accessGraph',
+]);
+
+export const PLAN_AUTHORIZATION_MISMATCH = 'dispatch plan authorization does not cover this dispatch';
+export const PLAN_UNIT_UNAUTHORIZED = 'dispatch plan authorization names no such unit';
+export const PLAN_ROUTE_DRIFT = 'dispatch route differs from the authorized dispatch plan';
+
+const UNIT_FIELDS = ['unitId', 'intent', 'signals', 'approval'];
+const UNIT_AXES = ['intentSource', 'intent', 'origin', 'state', 'route', 'reason'];
+const REVISION_AXES = ['catalog', 'accessGraph', 'policy'];
+const ROUTE_FIELDS = ['providerId', 'modelId', 'effort', 'surfaceId', 'transportId'];
+const RECORD_FIELDS = ['id', 'scope', 'mode', 'timestamp', 'actor', 'bounds'];
+
+function object(value, field) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${field} must be an object`);
+  }
+  return value;
+}
+
+function string(value, field) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+function closedFields(value, allowed, message) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) throw new TypeError(`${message}: ${key}`);
+  }
+  return value;
+}
+
+/** The dispatchable identity of the selected candidate, or none if it has no path. */
+function plannedRoute(selected) {
+  if (!selected || typeof selected.modelId !== 'string' || typeof selected.surfaceId !== 'string') {
+    return null;
+  }
+  return Object.freeze(Object.fromEntries(
+    ROUTE_FIELDS.map((field) => [field, selected[field] ?? null]),
+  ));
+}
+
+function plannedUnit(input, resolverInput) {
+  closedFields(object(input, 'dispatch plan unit'), UNIT_FIELDS, 'unknown dispatch plan unit field');
+  const resolved = resolveRoutingIntent({
+    explicit: input.intent ?? null, signals: input.signals ?? null,
+  });
+  const decision = resolveRoute({
+    ...resolverInput,
+    intent: resolved.intent,
+    ...(input.approval == null ? {} : { approval: input.approval }),
+  });
+  return {
+    revisions: decision.revisions,
+    unit: Object.freeze({
+      unitId: string(input.unitId, 'dispatch plan unitId'),
+      intentSource: resolved.source,
+      intent: resolved.intent,
+      origin: decision.origin,
+      state: decision.state,
+      route: plannedRoute(decision.selected),
+      reason: decision.selected?.reason ?? decision.reason,
+    }),
+  };
+}
+
+/** One plan decides under one set of revisions; a plan that cannot name them is not bindable. */
+function planRevisions(entries) {
+  const [first, ...rest] = entries.map(({ revisions }) => revisions);
+  for (const field of REVISION_AXES) {
+    if (typeof first[field] !== 'string') {
+      throw new TypeError(`dispatch plan requires a ${field} revision`);
+    }
+    if (rest.some((revisions) => revisions[field] !== first[field])) {
+      throw new TypeError(`dispatch plan units disagree on the ${field} revision`);
+    }
+  }
+  return Object.freeze(Object.fromEntries(REVISION_AXES.map((field) => [field, first[field]])));
+}
+
+export function buildDispatchPlan(input) {
+  object(input, 'dispatch plan input');
+  if (!Array.isArray(input.units) || input.units.length === 0) {
+    throw new TypeError('dispatch plan needs at least one unit');
+  }
+  const entries = input.units.map((unit) => plannedUnit(unit, input.resolverInput));
+  const units = sortedUnits(entries.map(({ unit }) => unit));
+  units.forEach((unit, index) => {
+    if (index > 0 && units[index - 1].unitId === unit.unitId) {
+      throw new TypeError(`duplicate dispatch plan unit: ${unit.unitId}`);
+    }
+  });
+  const document = {
+    schemaVersion: DISPATCH_PLAN_VERSION,
+    units: Object.freeze(units),
+    revisions: planRevisions(entries),
+  };
+  return Object.freeze({ ...document, planHash: dispatchPlanHash(document) });
+}
+
+const sortedUnits = (units) =>
+  [...units].sort((left, right) => left.unitId.localeCompare(right.unitId));
+
+/** Key order, unit order and absent values never change what a plan is. */
+function canonicalValue(value) {
+  if (Array.isArray(value)) return value.map(canonicalValue);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort()
+      .map((key) => [key, canonicalValue(value[key])]));
+  }
+  return value === undefined ? null : value;
+}
+
+export function canonicalizeDispatchPlan(plan) {
+  object(plan, 'dispatch plan');
+  if (!Array.isArray(plan.units)) throw new TypeError('dispatch plan units must be an array');
+  return JSON.stringify(canonicalValue({
+    schemaVersion: plan.schemaVersion,
+    units: sortedUnits(plan.units),
+    revisions: plan.revisions,
+  }));
+}
+
+export function dispatchPlanHash(plan) {
+  return `sha256-${createHash('sha256').update(canonicalizeDispatchPlan(plan)).digest('hex')}`;
+}
+
+function validateBounds(input, mode) {
+  if (mode === 'fixed') {
+    if (input != null) throw new TypeError('a fixed plan authorization records no bounds');
+    return null;
+  }
+  if (input == null || !Array.isArray(object(input, 'plan authorization bounds').axes)
+      || input.axes.length === 0) {
+    throw new TypeError('bounded re-resolution must name the axes it covers');
+  }
+  closedFields(input, ['axes'], 'unknown plan authorization bounds field');
+  for (const axis of input.axes) {
+    if (!BOUNDED_RE_RESOLUTION_AXES.includes(axis)) {
+      throw new TypeError(`bounded re-resolution cannot cover: ${axis}`);
+    }
+  }
+  return Object.freeze({ axes: Object.freeze([...new Set(input.axes)].sort()) });
+}
+
+export function authorizeDispatchPlan(plan, input) {
+  const planHash = dispatchPlanHash(plan);
+  closedFields(object(input, 'plan authorization'), RECORD_FIELDS, 'unknown plan authorization field');
+  if (!PLAN_AUTHORIZATION_MODES.includes(input.mode)) {
+    throw new TypeError(
+      `plan authorization mode must be one of: ${PLAN_AUTHORIZATION_MODES.join(', ')}`,
+    );
+  }
+  string(input.timestamp, 'plan authorization timestamp');
+  if (!Number.isFinite(Date.parse(input.timestamp))) {
+    throw new TypeError('plan authorization timestamp must be an ISO timestamp');
+  }
+  return Object.freeze({
+    schemaVersion: DISPATCH_PLAN_VERSION,
+    id: string(input.id, 'plan authorization id'),
+    scope: string(input.scope, 'plan authorization scope'),
+    mode: input.mode,
+    timestamp: input.timestamp,
+    actor: string(input.actor, 'plan authorization actor'),
+    bounds: validateBounds(input.bounds ?? null, input.mode),
+    planHash,
+    // The bound contents, so a mismatch can name what actually moved.
+    plan: Object.freeze({
+      schemaVersion: plan.schemaVersion,
+      units: Object.freeze(sortedUnits(plan.units)),
+      revisions: plan.revisions,
+    }),
+  });
+}
+
+const sameValue = (left, right) =>
+  JSON.stringify(canonicalValue(left)) === JSON.stringify(canonicalValue(right));
+
+/** Which axes moved between the authorized plan and the one about to run. */
+function planDrift(authorized, current) {
+  const axes = new Set();
+  for (const field of REVISION_AXES) {
+    if (authorized.revisions?.[field] !== current.revisions?.[field]) axes.add(field);
+  }
+  const currentUnits = new Map(current.units.map((unit) => [unit.unitId, unit]));
+  const authorizedIds = authorized.units.map((unit) => unit.unitId);
+  if (authorizedIds.length !== currentUnits.size
+      || authorizedIds.some((unitId) => !currentUnits.has(unitId))) {
+    axes.add('units');
+  }
+  for (const unit of authorized.units) {
+    const other = currentUnits.get(unit.unitId);
+    if (!other) continue;
+    for (const axis of UNIT_AXES) {
+      if (!sameValue(unit[axis], other[axis])) axes.add(axis);
+    }
+  }
+  return Object.freeze([...axes].sort());
+}
+
+const blockedCheck = (mode, drift, outside) => Object.freeze({
+  state: 'blocked', mode, drift, outside, reason: PLAN_AUTHORIZATION_MISMATCH,
+});
+
+export function checkPlanAuthorization(input) {
+  object(input, 'plan authorization check');
+  const authorization = object(input.authorization, 'plan authorization');
+  const plan = object(input.plan, 'dispatch plan');
+  // A record whose bound contents no longer hash to the id it carries proves
+  // nothing about the plan the user saw, so it authorizes nothing.
+  if (dispatchPlanHash(authorization.plan) !== authorization.planHash) {
+    return blockedCheck(authorization.mode, Object.freeze(['authorization']), Object.freeze(['authorization']));
+  }
+  const drift = dispatchPlanHash(plan) === authorization.planHash
+    ? Object.freeze([])
+    : planDrift(authorization.plan, plan);
+  if (drift.length === 0) {
+    return Object.freeze({
+      state: 'authorized', mode: authorization.mode, drift, outside: drift, reason: null,
+    });
+  }
+  const allowed = authorization.bounds?.axes ?? [];
+  const outside = Object.freeze(drift.filter((axis) => !allowed.includes(axis)));
+  if (authorization.mode === 'bounded-re-resolution' && outside.length === 0) {
+    return Object.freeze({
+      state: 'authorized', mode: authorization.mode, drift, outside, reason: null,
+    });
+  }
+  return blockedCheck(authorization.mode, drift, outside);
+}
+
+/**
+ * The dispatch-time gate: the authorization must still cover the plan, the plan
+ * must carry the unit, and the route about to run must be the one the unit was
+ * authorized for. The returned id is what the Dispatch receipt carries, blocked
+ * or not, so a refusal stays attributable to the authorization it was checked
+ * against.
+ */
+export function authorizeDispatchUnit(input) {
+  object(input, 'dispatch authorization input');
+  const authorizationId = input.authorization?.id ?? null;
+  const blocked = (reason) => Object.freeze({ authorizationId, reason });
+  const check = checkPlanAuthorization(input);
+  if (check.state !== 'authorized') return blocked(check.reason);
+  const unit = input.plan.units.find((entry) => entry.unitId === input.unitId);
+  if (!unit) return blocked(PLAN_UNIT_UNAUTHORIZED);
+  if (input.route != null && !sameValue(unit.route, plannedRoute(input.route))) {
+    return blocked(PLAN_ROUTE_DRIFT);
+  }
+  return blocked(null);
+}