@ravefox/space 0.2.1 → 0.3.0

package/node_modules/@commonlyai/seats/src/record/format.js

@@ -1,737 +0,0 @@
-/**
- * The run record, format v1: one canonical JSON object per line, each line
- * hash-chained to the one before it. docs/record-v1.md is the specification;
- * this file is its reference writer and verifier, and nothing here imports
- * the store, so another tool can vendor it alone.
- */
-import { createHash } from 'node:crypto';
-import { isIP } from 'node:net';
-import { FAILURE_KINDS } from '../failures.js';
-import { SWITCH_REASONS, entryLabel, parseEntry } from '../harness-plan.js';
-
-export const RECORD_VERSION = 1;
-export const RECORD_SCHEMA = 'seats.record';
-
-export const ACTOR_TYPES = Object.freeze(['agent', 'human', 'policy', 'system']);
-// Who decides an approval today is the owner of the credential it would use;
-// `decision-owner` is reserved for a separately assigned decider.
-export const DECIDED_BY_ROLES = Object.freeze(['credential-owner', 'decision-owner', 'agent-owner', 'pod-member', 'policy']);
-// A parked tool call is decided by an owner or by policy, never by a pod member
-// who owns neither the credential nor the asking agent (ADR-033 D5).
-export const PARKED_CALL_ROLES = Object.freeze(DECIDED_BY_ROLES.filter((role) => role !== 'pod-member'));
-export const TOOL_SURFACES = Object.freeze(['connector', 'commonly', 'native']);
-export const GRANT_ENDS_ON = Object.freeze(['task.done', 'expiresAt']);
-export const REVOKE_REASONS = Object.freeze(['task.done', 'expired', 'cascade', 'manual']);
-export const WRITE_MODES = Object.freeze(['read', 'write', 'write-with-confirm']);
-export const GRANT_TARGET_KINDS = Object.freeze(['pod', 'seat']);
-export const OUTCOMES = Object.freeze(['ok', 'failed', 'stuck', 'cancelled']);
-export const RESULT_STATUSES = Object.freeze(['done', 'partial', 'blocked', 'failed']);
-// Whose request an agent acts on: 'requester' sent the message that started
-// the run, 'assigner' assigned its task. Absent when no human asked.
-export const ON_BEHALF_ROLES = Object.freeze(['requester', 'assigner']);
-// Why the egress proxy refused a request. The first two can leave host and port null.
-export const EGRESS_DENIED_REASONS = Object.freeze([
-  'bad_request', 'not_connect', 'ip_literal', 'not_allowed', 'unresolved', 'private_address', 'unreachable',
-]);
-const EGRESS_TARGETLESS = new Set(['bad_request', 'not_connect']);
-export const SANDBOXES = Object.freeze(['seatbelt', 'bwrap', 'none']);
-export const SESSION_METHODS = Object.freeze(['new', 'resume', 'load']);
-export const RETRY_STATES = Object.freeze(['scheduled', 'started']);
-/**
- * agent.retry.errorType. The provider error types opencode 2.1.4 reports on a
- * retry, read from its error formatter, plus `other` for any type outside
- * them. A closed set, so no agent text can ride in this field.
- */
-export const RETRY_ERROR_TYPES = Object.freeze([
-  'provider.auth',
-  'provider.content-filter',
-  'provider.free-limit',
-  'provider.internal',
-  'provider.invalid-output',
-  'provider.invalid-request',
-  'provider.no-route',
-  'provider.quota',
-  'provider.rate-limit',
-  'provider.timeout',
-  'provider.transport',
-  'provider.unknown',
-  'provider.unsupported-operation',
-  'other',
-]);
-// Why a requested session was not reopened: the two forms an ACP adapter
-// writes. The code is the JSON-RPC error's, an integer by JSON-RPC 2.0.
-const SESSION_FALLBACK = /^(?:agent supports neither session\/resume nor session\/load|session\/(?:resume|load) answered error -?\d{1,16})$/;
-export const REDACTED = '[redacted]';
-
-/** The actors a writer records for its own bookkeeping, and for the board. */
-export const SYSTEM_ACTOR = Object.freeze({ type: 'system', id: 'seats' });
-export const BOARD_ACTOR = Object.freeze({ type: 'system', id: 'board' });
-
-/**
- * Every v1 kind. `actor` is who a writer records when the emitter names
- * nobody: 'run' (the run's own actor), 'system', or derived from the data
- * ('issuer', 'decider'). `trace` is the EVENT_TYPES name, when it differs.
- */
-export const KINDS = Object.freeze({
-  'task.claimed': Object.freeze({ group: 'claim', actor: 'run' }),
-  'task.released': Object.freeze({ group: 'claim', actor: 'run' }),
-  'task.done': Object.freeze({ group: 'claim', actor: 'board' }),
-  'grant.issued': Object.freeze({ group: 'grant', actor: 'issuer' }),
-  'grant.revoked': Object.freeze({ group: 'grant', actor: 'system' }),
-  'permission.requested': Object.freeze({ group: 'approval', actor: 'run' }),
-  'permission.decided': Object.freeze({ group: 'approval', actor: 'decider' }),
-  'decision.ruled': Object.freeze({ group: 'approval', actor: 'decider' }),
-  'attempt.started': Object.freeze({ group: 'attempt', actor: 'run', trace: 'run.started' }),
-  'session.opened': Object.freeze({ group: 'attempt', actor: 'system' }),
-  'attempt.settled': Object.freeze({ group: 'attempt', actor: 'system' }),
-  'run.settled': Object.freeze({ group: 'attempt', actor: 'system' }),
-  // The attempt that follows runs on another harness entry than the seat was on.
-  'harness.switched': Object.freeze({ group: 'attempt', actor: 'system' }),
-  'tool.call': Object.freeze({ group: 'tool', actor: 'run' }),
-  'tool.update': Object.freeze({ group: 'tool', actor: 'run' }),
-  'credential.granted': Object.freeze({ group: 'credential', actor: 'system' }),
-  'credential.denied': Object.freeze({ group: 'credential', actor: 'system' }),
-  'result.reported': Object.freeze({ group: 'result', actor: 'run' }),
-  'turn.prompt_sent': Object.freeze({ group: 'activity', actor: 'system' }),
-  'agent.message_chunk': Object.freeze({ group: 'activity', actor: 'run' }),
-  'agent.thought_chunk': Object.freeze({ group: 'activity', actor: 'run' }),
-  'agent.retry': Object.freeze({ group: 'activity', actor: 'run' }),
-  plan: Object.freeze({ group: 'activity', actor: 'run' }),
-  usage: Object.freeze({ group: 'activity', actor: 'run' }),
-  'liveness.stalled': Object.freeze({ group: 'activity', actor: 'system' }),
-  'liveness.recovery': Object.freeze({ group: 'activity', actor: 'system' }),
-  'process.exited': Object.freeze({ group: 'activity', actor: 'system' }),
-  // The run's confinement, recorded once per spawn, beside its egress.
-  'sandbox.applied': Object.freeze({ group: 'sandbox', actor: 'system' }),
-  'egress.allowed': Object.freeze({ group: 'egress', actor: 'system' }),
-  'egress.denied': Object.freeze({ group: 'egress', actor: 'system' }),
-});
-
-const TRACE_TO_KIND = new Map(Object.entries(KINDS).filter(([, spec]) => spec.trace).map(([kind, spec]) => [spec.trace, kind]));
-
-/** Record kind for an EVENT_TYPES name or a kind; null when it is neither. */
-export const kindOfType = (type) => TRACE_TO_KIND.get(type) || (Object.hasOwn(KINDS, type) ? type : null);
-/** The EVENT_TYPES name readRun reports for a kind (unknown kinds pass through). */
-export const traceTypeOf = (kind) => KINDS[kind]?.trace || kind;
-
-const fail = (message) => { throw new Error(`record: ${message}`); };
-const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
-const isText = (value) => typeof value === 'string' && value.length > 0;
-const ENV_NAME = /^[A-Z_][A-Z0-9_]*$/;
-const RUN_ID = /^[A-Za-z0-9_-]{6,64}$/;
-// A user id is an opaque token from the instance: no spaces, so a display
-// name can't pass for one. Display names go in actor.name.
-const USER_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
-export const isUserId = (value) => typeof value === 'string' && USER_ID.test(value);
-const TOOL_NAME = /^[^\s*?]{1,256}$/;
-const RFC3339_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/;
-const KIND_SHAPE = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*$/;
-const isTimestamp = (value) => typeof value === 'string' && RFC3339_UTC.test(value) && !Number.isNaN(Date.parse(value));
-// Section 8: 128 random bits make a line's hash a commitment nobody can guess at.
-const SALT = /^[0-9a-f]{32}$/;
-const isSalt = (value) => typeof value === 'string' && SALT.test(value);
-const LINE_HASH = /^[0-9a-f]{64}$/;
-// Section 9: an id held beside the line. It is a valid id token, so every
-// writer check and every older reader takes it as an opaque id.
-const COMMITMENT = /^c1:[0-9a-f]{64}$/;
-export const isCommitment = (value) => typeof value === 'string' && COMMITMENT.test(value);
-const isOpenings = (value) => isPlainObject(value) && Object.entries(value).every(([token, opening]) => isCommitment(token)
-  && isPlainObject(opening) && isText(opening.id) && isSalt(opening.salt) && Object.keys(opening).length === 2);
-// Every string on a line, at any depth: where a commitment can sit.
-const idTokens = (value, found = new Set()) => {
-  if (typeof value === 'string') found.add(value);
-  else if (Array.isArray(value)) value.forEach((item) => idTokens(item, found));
-  else if (isPlainObject(value)) Object.values(value).forEach((item) => idTokens(item, found));
-  return found;
-};
-const isRedaction = (value) => isPlainObject(value) && Array.isArray(value.fields) && value.fields.every(isText)
-  && (value.hash === null || (typeof value.hash === 'string' && LINE_HASH.test(value.hash)));
-
-/**
- * RFC 8785 (JCS) serialization. For the JSON values a record holds, JCS is
- * JSON.stringify with object keys sorted by UTF-16 code units, which is what
- * Array.prototype.sort does by default.
- *
- * `strict` also refuses a lone surrogate in any string or key, as RFC 8785
- * requires. Lines are not strict: agent text from a stream cut mid-pair must
- * still record, and JSON.stringify writes the lone half as a \u escape.
- */
-const canonicalString = (text, strict) => {
-  if (strict && !text.isWellFormed()) fail('strings must be well-formed UTF-16 (no lone surrogates)');
-  return JSON.stringify(text);
-};
-const canonical = (value, strict = false) => {
-  if (value !== null && typeof value === 'object' && typeof value.toJSON === 'function') return canonical(value.toJSON(), strict);
-  if (value === null) return 'null';
-  switch (typeof value) {
-    case 'string': return canonicalString(value, strict);
-    case 'boolean': return value ? 'true' : 'false';
-    case 'number':
-      if (!Number.isFinite(value)) fail('numbers must be finite');
-      return JSON.stringify(value);
-    case 'object':
-      if (Array.isArray(value)) return `[${value.map((item) => (item === undefined ? 'null' : canonical(item, strict))).join(',')}]`;
-      return `{${Object.keys(value).filter((key) => value[key] !== undefined).sort()
-        .map((key) => `${canonicalString(key, strict)}:${canonical(value[key], strict)}`).join(',')}}`;
-    default: return fail(`cannot serialize a ${typeof value}`);
-  }
-};
-
-/** The canonical line for an entry, without its trailing newline. */
-export const canonicalLine = (entry) => {
-  if (!isPlainObject(entry)) fail('an entry is a JSON object');
-  return canonical(entry);
-};
-
-/** Lowercase hex SHA-256 over a line's UTF-8 bytes: what the next `prev` holds. */
-export const hashLine = (line) => createHash('sha256').update(String(line), 'utf8').digest('hex');
-
-/**
- * A tool call's arguments as a digest, never the values: `sha256:` + the
- * lowercase hex SHA-256 of the arguments' RFC 8785 form. The same arguments
- * give the same digest wherever they are seen, so a reader can match a
- * tool.call to the permission entries that approved it. Returns undefined
- * when there are no arguments, or they are not JSON (a function, NaN, a
- * string or key holding a lone surrogate): a writer then omits argsDigest.
- */
-const ARGS_DIGEST = /^sha256:[0-9a-f]{64}$/;
-export const argsDigestOf = (args) => {
-  if (args === undefined) return undefined;
-  try { return `sha256:${hashLine(canonical(args, true))}`; } catch { return undefined; }
-};
-export const isArgsDigest = (value) => typeof value === 'string' && ARGS_DIGEST.test(value);
-
-/**
- * What a line holds in place of an id it may later have to forget: nobody can
- * test a guess at the id without the salt, which is kept beside the record.
- */
-export const commitId = (id, salt) => {
-  if (!isSalt(salt)) fail('salt must be 32 lowercase hex characters');
-  return `c1:${hashLine(`seats.record/commitment/v1\n${salt}\n${id}`)}`;
-};
-
-/** null when the actor is well formed, else the reason. */
-const actorProblem = (actor) => {
-  if (actor === null) return null;
-  if (!isPlainObject(actor)) return 'actor must be an object or null';
-  if (!ACTOR_TYPES.includes(actor.type)) return `actor.type must be one of ${ACTOR_TYPES.join(', ')}`;
-  if (!isUserId(actor.id)) return 'actor.id must be an id token (a user id for agent and human actors), never a display name';
-  if (actor.owner !== undefined && (actor.type !== 'agent' || !isUserId(actor.owner))) return 'actor.owner is a user id, on agent actors only';
-  if (actor.name !== undefined && !isText(actor.name)) return 'actor.name must be a non-empty string';
-  if (actor.onBehalfOf !== undefined) {
-    const behalf = actor.onBehalfOf;
-    if (actor.type !== 'agent') return 'actor.onBehalfOf is on agent actors only';
-    if (!isPlainObject(behalf)) return 'actor.onBehalfOf must be {id, role}';
-    const extra = Object.keys(behalf).find((key) => key !== 'id' && key !== 'role');
-    if (extra !== undefined) return `unknown field actor.onBehalfOf.${extra}`;
-    if (!isUserId(behalf.id)) return 'actor.onBehalfOf.id must be an id token (a user id), never a display name';
-    if (!ON_BEHALF_ROLES.includes(behalf.role)) return `actor.onBehalfOf.role must be one of ${ON_BEHALF_ROLES.join(', ')}`;
-  }
-  return null;
-};
-
-export const validateActor = (actor) => {
-  const problem = actorProblem(actor);
-  if (problem) fail(problem);
-  if (actor === null) return null;
-  return Object.freeze({
-    type: actor.type,
-    id: actor.id,
-    ...(actor.owner ? { owner: actor.owner } : {}),
-    ...(actor.onBehalfOf ? { onBehalfOf: Object.freeze({ id: actor.onBehalfOf.id, role: actor.onBehalfOf.role }) } : {}),
-    ...(actor.name ? { name: actor.name } : {}),
-  });
-};
-
-const refuseUnknownKeys = (value, allowed, where) => {
-  for (const key of Object.keys(value)) if (!allowed.includes(key)) fail(`unknown field ${where}${key}`);
-};
-const envNames = (names, where) => {
-  if (!Array.isArray(names) || !names.every((name) => typeof name === 'string' && ENV_NAME.test(name))) {
-    fail(`${where} must be credential NAMES ([A-Z_][A-Z0-9_]*), never values`);
-  }
-  return [...names];
-};
-const optionalText = (value, where) => {
-  if (value !== undefined && value !== null && !isText(value)) fail(`${where} must be a non-empty string`);
-};
-const userIdOrPolicy = (value, where) => {
-  if (value !== undefined && value !== null && value !== 'policy' && !isUserId(value)) fail(`${where} must be a user id or "policy"`);
-};
-// Only the digest form: raw arguments would carry values.
-const optionalArgsDigest = (data, kind) => {
-  if (data.argsDigest !== undefined && !isArgsDigest(data.argsDigest)) fail(`${kind}.argsDigest must be sha256:<64 hex>, a digest of the arguments, never the arguments`);
-};
-// A host as the egress proxy traces it: a lowercase DNS name, an IP literal
-// (IPv6 without brackets), or [redacted] when it held a run credential.
-const DNS_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
-const isEgressHost = (host) => typeof host === 'string' && (host === REDACTED || isIP(host) !== 0
-  || (host.length <= 253 && host.split('.').every((label) => DNS_LABEL.test(label))));
-const isPort = (port) => Number.isInteger(port) && port >= 1 && port <= 65535;
-const checkEgressTarget = (data, kind, { nullable }) => {
-  if (data.host === null && data.port === null && nullable) return;
-  if (data.host === null || data.port === null) {
-    fail(nullable ? `${kind}: host and port are null together, or both set` : `${kind} needs a host and a port`);
-  }
-  if (!isEgressHost(data.host)) fail(`${kind}.host must be a lowercase DNS name, an IP literal or "${REDACTED}"`);
-  if (!isPort(data.port)) fail(`${kind}.port must be an integer from 1 to 65535`);
-};
-
-const checkRole = (role, where, roles = DECIDED_BY_ROLES) => {
-  if (!roles.includes(role)) fail(`${where} must be one of ${roles.join(', ')}`);
-};
-
-/** A grant's scope, in the shape of a room grant: exact tool names and a connection id. */
-const checkScope = (scope) => {
-  if (!isPlainObject(scope)) fail('grant.issued needs a scope');
-  refuseUnknownKeys(scope, ['connectionId', 'tools', 'writeMode', 'budget', 'audience'], 'grant.issued.scope.');
-  optionalText(scope.connectionId, 'grant.issued.scope.connectionId');
-  const tools = scope.tools ?? [];
-  if (!Array.isArray(tools) || !tools.every((name) => typeof name === 'string' && TOOL_NAME.test(name))) {
-    fail('grant.issued.scope.tools must be exact tool names (no spaces, no * or ?), not patterns');
-  }
-  if (scope.writeMode !== undefined && !WRITE_MODES.includes(scope.writeMode)) fail(`grant.issued.scope.writeMode must be one of ${WRITE_MODES.join(', ')}`);
-  let budget;
-  if (scope.budget !== undefined) {
-    if (!isPlainObject(scope.budget)) fail('grant.issued.scope.budget must be an object');
-    refuseUnknownKeys(scope.budget, ['calls', 'windowMs'], 'grant.issued.scope.budget.');
-    if (scope.budget.calls !== undefined && !(Number.isInteger(scope.budget.calls) && scope.budget.calls >= 0)) fail('grant.issued.scope.budget.calls must be an integer >= 0');
-    if (scope.budget.windowMs !== undefined && !(Number.isInteger(scope.budget.windowMs) && scope.budget.windowMs >= 1)) fail('grant.issued.scope.budget.windowMs must be an integer >= 1');
-    budget = { ...scope.budget };
-  }
-  const audience = scope.audience ?? [];
-  if (!Array.isArray(audience) || !audience.every(isUserId)) fail('grant.issued.scope.audience must be user ids');
-  return {
-    ...(scope.connectionId ? { connectionId: scope.connectionId } : {}),
-    tools: [...tools],
-    ...(scope.writeMode ? { writeMode: scope.writeMode } : {}),
-    ...(budget ? { budget } : {}),
-    audience: [...audience],
-  };
-};
-
-// Per-kind checks, applied by every writer. They are strictest where a value
-// could ride in: a grant's scope, target and binding refuse fields they don't define.
-const CHECKS = {
-  'grant.issued': (data, envelope) => {
-    refuseUnknownKeys(data, ['grantId', 'parentGrantId', 'scope', 'target', 'issuedBy', 'expiresAt', 'binding'], 'grant.issued.');
-    if (!isText(data.grantId)) fail('grant.issued needs a grantId');
-    optionalText(data.parentGrantId, 'grant.issued.parentGrantId');
-    const scope = checkScope(data.scope);
-    let target;
-    if (data.target !== undefined) {
-      if (!isPlainObject(data.target)) fail('grant.issued.target must be an object');
-      refuseUnknownKeys(data.target, ['kind', 'id'], 'grant.issued.target.');
-      if (!GRANT_TARGET_KINDS.includes(data.target.kind) || !isText(data.target.id)) fail('grant.issued.target is {kind: pod|seat, id}');
-      target = { kind: data.target.kind, id: data.target.id };
-    }
-    userIdOrPolicy(data.issuedBy, 'grant.issued.issuedBy');
-    if (data.expiresAt !== undefined && !isTimestamp(data.expiresAt)) fail('grant.issued.expiresAt must be an RFC 3339 UTC timestamp');
-    let binding;
-    if (data.binding !== undefined) {
-      if (!isPlainObject(data.binding)) fail('grant.issued.binding must be an object');
-      refuseUnknownKeys(data.binding, ['taskId', 'podId', 'endsOn'], 'grant.issued.binding.');
-      if (!isText(data.binding.taskId) || !isText(data.binding.podId)) fail('grant.issued.binding needs taskId and podId: task ids repeat across pods');
-      if (data.binding.taskId !== envelope.taskId || data.binding.podId !== envelope.podId) fail('grant.issued.binding must name the run\'s own taskId and podId');
-      if (!GRANT_ENDS_ON.includes(data.binding.endsOn)) fail(`grant.issued.binding.endsOn must be one of ${GRANT_ENDS_ON.join(', ')}`);
-      if (data.binding.endsOn === 'expiresAt' && data.expiresAt === undefined) fail('a grant that ends on expiresAt needs an expiresAt');
-      binding = { taskId: data.binding.taskId, podId: data.binding.podId, endsOn: data.binding.endsOn };
-    }
-    return {
-      ...data,
-      ...(data.parentGrantId === undefined ? {} : { parentGrantId: data.parentGrantId }),
-      scope,
-      ...(target ? { target } : {}),
-      ...(binding ? { binding } : {}),
-    };
-  },
-  'grant.revoked': (data) => {
-    if (!Array.isArray(data.grantIds) || data.grantIds.length === 0 || !data.grantIds.every(isText)) fail('grant.revoked needs grantIds: a non-empty array');
-    if (new Set(data.grantIds).size !== data.grantIds.length) fail('grant.revoked.grantIds repeats an id');
-    if (!REVOKE_REASONS.includes(data.reason)) fail(`grant.revoked.reason must be one of ${REVOKE_REASONS.join(', ')}`);
-    return { ...data, grantIds: [...data.grantIds] };
-  },
-  'task.done': (data, envelope) => {
-    if (!envelope.taskId) fail('task.done needs a run with a taskId');
-    userIdOrPolicy(data.doneBy, 'task.done.doneBy');
-    return data;
-  },
-  'permission.requested': (data) => {
-    if (!isText(data.question)) fail('permission.requested needs a question: the human-readable ask');
-    if (!isPlainObject(data.askedOf)) fail('permission.requested needs askedOf: {id, role}');
-    refuseUnknownKeys(data.askedOf, ['id', 'role'], 'permission.requested.askedOf.');
-    if (!isUserId(data.askedOf.id)) fail('permission.requested.askedOf.id must be an id token, never a display name');
-    checkRole(data.askedOf.role, 'permission.requested.askedOf.role', PARKED_CALL_ROLES);
-    optionalText(data.grantId, 'permission.requested.grantId');
-    optionalText(data.decisionCardId, 'permission.requested.decisionCardId');
-    optionalArgsDigest(data, 'permission.requested');
-    return { ...data, askedOf: { id: data.askedOf.id, role: data.askedOf.role } };
-  },
-  'decision.ruled': (data) => {
-    if (!isText(data.decisionCardId)) fail('decision.ruled needs a decisionCardId');
-    const { value } = data;
-    if (!(typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value)))) {
-      fail('decision.ruled.value must be a string, number or boolean');
-    }
-    if (data.decidedBy !== 'policy' && !isUserId(data.decidedBy)) fail('decision.ruled.decidedBy must be a user id or "policy"');
-    checkRole(data.decidedByRole, 'decision.ruled.decidedByRole');
-    return data;
-  },
-  'permission.decided': (data) => {
-    optionalArgsDigest(data, 'permission.decided');
-    // A rule-decided call never had a person in the loop; a writer says so
-    // rather than leave a reader to infer it from rule.list.
-    // A decision always names who made it: no writer may record one nobody
-    // can be held to.
-    const out = { ...data };
-    if (!('decidedBy' in out) && !('decidedByRole' in out) && out.rule && out.rule.list !== 'ask') {
-      out.decidedBy = 'policy';
-      out.decidedByRole = 'policy';
-    }
-    if (out.decidedBy === undefined || out.decidedBy === null) fail('permission.decided.decidedBy is required: a user id, or "policy"');
-    userIdOrPolicy(out.decidedBy, 'permission.decided.decidedBy');
-    checkRole(out.decidedByRole, 'permission.decided.decidedByRole', PARKED_CALL_ROLES);
-    if ((out.decidedBy === 'policy') !== (out.decidedByRole === 'policy')) {
-      fail('permission.decided.decidedBy is "policy" exactly when decidedByRole is "policy"');
-    }
-    optionalText(out.decisionCardId, 'permission.decided.decisionCardId');
-    return out;
-  },
-  'tool.call': (data) => {
-    if (data.surface !== undefined && !TOOL_SURFACES.includes(data.surface)) fail(`tool.call.surface must be one of ${TOOL_SURFACES.join(', ')}`);
-    optionalArgsDigest(data, 'tool.call');
-    return data;
-  },
-  'credential.granted': (data) => {
-    const names = envNames(data.names ?? [], 'credential.granted.names');
-    if (data.injected === undefined) return { ...data, names };
-    const injected = envNames(data.injected, 'credential.granted.injected');
-    if (!injected.every((name) => names.includes(name))) fail('credential.granted.injected must be a subset of names');
-    return { ...data, names, injected };
-  },
-  'credential.denied': (data) => {
-    envNames([data.name], 'credential.denied.name');
-    return data;
-  },
-  'attempt.settled': (data) => {
-    if (!Number.isInteger(data.attempt) || data.attempt < 1) fail('attempt.settled.attempt must be a positive integer');
-    if (!OUTCOMES.includes(data.outcome)) fail(`attempt.settled.outcome must be one of ${OUTCOMES.join(', ')}`);
-    if (data.failure !== undefined && data.failure !== null) {
-      const { kind } = data.failure;
-      if (kind !== null && kind !== undefined && !FAILURE_KINDS[kind]) fail(`attempt.settled.failure.kind ${kind} is not a FAILURE_KINDS key`);
-    }
-    return data;
-  },
-  'session.opened': (data) => {
-    refuseUnknownKeys(data, ['method', 'sessionId', 'requestedSessionId', 'fallback'], 'session.opened.');
-    if (!SESSION_METHODS.includes(data.method)) fail(`session.opened.method must be one of ${SESSION_METHODS.join(', ')}`);
-    if (!isText(data.sessionId)) fail('session.opened needs a sessionId');
-    if ((data.requestedSessionId === undefined) !== (data.fallback === undefined)) {
-      fail('session.opened.requestedSessionId and fallback come together: a session was asked for and not reopened');
-    }
-    if (data.requestedSessionId !== undefined) {
-      if (data.method !== 'new') fail('session.opened.requestedSessionId is set only when method is new');
-      if (!isText(data.requestedSessionId)) fail('session.opened.requestedSessionId must be a non-empty string');
-      if (typeof data.fallback !== 'string' || !SESSION_FALLBACK.test(data.fallback)) {
-        fail('session.opened.fallback must be "agent supports neither session/resume nor session/load" or "session/<resume|load> answered error <code>"');
-      }
-    }
-    return data;
-  },
-  'harness.switched': (data) => {
-    refuseUnknownKeys(data, ['from', 'to', 'reason'], 'harness.switched.');
-    for (const key of ['from', 'to']) {
-      let entry = null;
-      try { entry = typeof data[key] === 'string' ? parseEntry(data[key]) : null; } catch { entry = null; }
-      // The canonical label only, so one entry is always written one way.
-      if (!entry || entryLabel(entry) !== data[key]) fail(`harness.switched.${key} must be an entry label harness/model[@effort]`);
-    }
-    if (data.from === data.to) fail('harness.switched.from and to must differ');
-    if (!SWITCH_REASONS.includes(data.reason)) fail(`harness.switched.reason must be one of ${SWITCH_REASONS.join(', ')}`);
-    return data;
-  },
-  'agent.retry': (data) => {
-    refuseUnknownKeys(data, ['state', 'attempt', 'nextRetryAt', 'status', 'errorType'], 'agent.retry.');
-    if (!RETRY_STATES.includes(data.state)) fail(`agent.retry.state must be one of ${RETRY_STATES.join(', ')}`);
-    // Every other field is absent when unknown, never null.
-    if ('attempt' in data && !(Number.isInteger(data.attempt) && data.attempt >= 1)) fail('agent.retry.attempt must be an integer >= 1, or absent');
-    if ('nextRetryAt' in data && !isTimestamp(data.nextRetryAt)) fail('agent.retry.nextRetryAt must be an RFC 3339 UTC timestamp, or absent');
-    if ('status' in data && !(Number.isInteger(data.status) && data.status >= 100 && data.status <= 599)) fail('agent.retry.status must be an integer HTTP status (100-599), or absent');
-    if ('errorType' in data && !RETRY_ERROR_TYPES.includes(data.errorType)) fail(`agent.retry.errorType must be one of ${RETRY_ERROR_TYPES.join(', ')}, or absent`);
-    return data;
-  },
-  usage: (data) => {
-    for (const key of ['contextTokens', 'contextSize']) {
-      const value = data[key];
-      if (value !== undefined && value !== null && !(Number.isInteger(value) && value >= 0)) fail(`usage.${key} must be an integer >= 0, or null when unknown`);
-    }
-    return data;
-  },
-  'sandbox.applied': (data) => {
-    refuseUnknownKeys(data, ['sandbox', 'reason'], 'sandbox.applied.');
-    if (!SANDBOXES.includes(data.sandbox)) fail(`sandbox.applied.sandbox must be one of ${SANDBOXES.join(', ')}`);
-    if (data.reason !== undefined) {
-      if (data.sandbox !== 'none') fail('sandbox.applied.reason is set only when sandbox is none');
-      if (!isText(data.reason)) fail('sandbox.applied.reason must be a non-empty string');
-    }
-    return data;
-  },
-  'egress.allowed': (data) => {
-    refuseUnknownKeys(data, ['host', 'port'], 'egress.allowed.');
-    checkEgressTarget(data, 'egress.allowed', { nullable: false });
-    return data;
-  },
-  'egress.denied': (data) => {
-    refuseUnknownKeys(data, ['host', 'port', 'reason'], 'egress.denied.');
-    if (!EGRESS_DENIED_REASONS.includes(data.reason)) fail(`egress.denied.reason must be one of ${EGRESS_DENIED_REASONS.join(', ')}`);
-    checkEgressTarget(data, 'egress.denied', { nullable: EGRESS_TARGETLESS.has(data.reason) });
-    return data;
-  },
-  'result.reported': (data) => {
-    if (!RESULT_STATUSES.includes(data.status)) fail(`result.reported.status must be one of ${RESULT_STATUSES.join(', ')}`);
-    if (data.refs !== undefined && !(Array.isArray(data.refs) && data.refs.every((ref) => isPlainObject(ref) && isText(ref.type) && isText(ref.id)))) {
-      fail('result.reported.refs must be [{type, id}]');
-    }
-    return data;
-  },
-};
-
-/**
- * Validate one kind's data and return the copy a writer records. `envelope`
- * is {taskId, podId}, for checks that tie data to the run it sits in.
- */
-export const normalizeData = (kind, data = {}, envelope = {}) => {
-  if (!isPlainObject(data)) fail(`${kind} data must be an object`);
-  const check = CHECKS[kind];
-  return check ? check({ ...data }, envelope) : { ...data };
-};
-
-/** A grant's rules acting on their own: named by the grant when its id is a token. */
-export const policyActorId = (grantId) => (isText(grantId) && isUserId(`grant:${grantId}`) ? `grant:${grantId}` : 'policy');
-const policyActor = (grantId) => ({ type: 'policy', id: policyActorId(grantId) });
-
-/** The actor a writer records when the emitter names none. */
-export const defaultActor = (kind, data = {}, runActor = null) => {
-  switch (KINDS[kind]?.actor) {
-    case 'run': return runActor;
-    case 'system': return SYSTEM_ACTOR;
-    case 'board': return BOARD_ACTOR;
-    case 'issuer':
-      if (data.issuedBy === 'policy') return policyActor(data.grantId);
-      return isUserId(data.issuedBy) ? { type: 'human', id: data.issuedBy } : null;
-    case 'decider':
-      if (data.decidedByRole === 'policy' || data.decidedBy === 'policy') return policyActor(data.grantId);
-      return isUserId(data.decidedBy) ? { type: 'human', id: data.decidedBy } : null;
-    default: return null;
-  }
-};
-
-const parseLine = (line) => {
-  let entry;
-  try { entry = JSON.parse(line); } catch { return fail('the previous line is not JSON'); }
-  if (!isPlainObject(entry) || !Number.isInteger(entry.seq)) fail('the previous line is not a record entry');
-  return entry;
-};
-
-/**
- * appendEntry(prevLine, fields, { runActor }?) → the next line, canonical,
- * without its newline.
- *
- * fields: { runId, taskId?, podId?, ts, kind, actor?, data, seq?, salt? }. seq
- * and prev come from prevLine (null for the first line); a given seq must agree.
- * An absent actor takes the kind's default; null records "unknown".
- */
-export const appendEntry = (prevLine, fields = {}, { runActor = null } = {}) => {
-  let seq = 1;
-  let prev = null;
-  if (prevLine !== null && prevLine !== undefined) {
-    const before = parseLine(prevLine);
-    seq = before.seq + 1;
-    prev = hashLine(prevLine);
-    if (before.runId !== fields.runId) fail('one record holds one run');
-    if (before.taskId !== fields.taskId || before.podId !== fields.podId) fail('taskId and podId are fixed for the whole run');
-    if (before.kind === 'run.settled') fail('nothing is written after run.settled');
-  }
-  if (fields.seq !== undefined && fields.seq !== seq) fail(`seq ${fields.seq} does not follow ${seq - 1}`);
-  if (!RUN_ID.test(String(fields.runId))) fail('runId must be 6-64 characters of [A-Za-z0-9_-]');
-  optionalText(fields.taskId, 'taskId');
-  optionalText(fields.podId, 'podId');
-  if (fields.salt !== undefined && !isSalt(fields.salt)) fail('salt must be 32 lowercase hex characters');
-  if (fields.taskId && !fields.podId) fail('a taskId needs a podId: task ids repeat across pods');
-  const ts = fields.ts instanceof Date ? fields.ts.toISOString() : fields.ts;
-  if (!isTimestamp(ts)) fail('ts must be an RFC 3339 UTC timestamp');
-  if (!Object.hasOwn(KINDS, fields.kind)) fail(`unknown record kind: ${fields.kind}`);
-  const data = normalizeData(fields.kind, fields.data ?? {}, { taskId: fields.taskId, podId: fields.podId });
-  const actor = validateActor(fields.actor === undefined ? defaultActor(fields.kind, data, runActor) : fields.actor);
-  return canonicalLine({
-    v: RECORD_VERSION,
-    schema: RECORD_SCHEMA,
-    runId: fields.runId,
-    ...(fields.taskId ? { taskId: fields.taskId } : {}),
-    ...(fields.podId ? { podId: fields.podId } : {}),
-    ...(fields.salt ? { salt: fields.salt } : {}),
-    seq,
-    ts,
-    kind: fields.kind,
-    actor,
-    data,
-    prev,
-  });
-};
-
-/** Split a record file's text into lines; a last line with no newline is torn. */
-export const splitRecord = (text) => {
-  if (!text) return { lines: [], torn: null };
-  const parts = String(text).split('\n');
-  const tail = parts.pop();
-  return { lines: parts, torn: tail === '' ? null : tail };
-};
-
-const envelopeProblem = (entry) => {
-  if (!Number.isInteger(entry.v) || entry.v < 1) return 'v';
-  if (entry.schema !== RECORD_SCHEMA) return 'schema';
-  if (!RUN_ID.test(String(entry.runId))) return 'runId';
-  if (entry.taskId !== undefined && !isText(entry.taskId)) return 'taskId';
-  if (entry.podId !== undefined && !isText(entry.podId)) return 'podId';
-  if (entry.taskId !== undefined && entry.podId === undefined) return 'podId';
-  if (!Number.isInteger(entry.seq) || entry.seq < 1) return 'seq';
-  if (!isTimestamp(entry.ts)) return 'ts';
-  if (typeof entry.kind !== 'string' || !KIND_SHAPE.test(entry.kind)) return 'kind';
-  if (actorProblem(entry.actor)) return 'actor';
-  if (!isPlainObject(entry.data)) return 'data';
-  if (entry.prev !== null && !(typeof entry.prev === 'string' && LINE_HASH.test(entry.prev))) return 'prev';
-  if (entry.salt !== undefined && !isSalt(entry.salt)) return 'salt';
-  if (entry.redaction !== undefined && !isRedaction(entry.redaction)) return 'redaction';
-  if (entry.openings !== undefined && !isOpenings(entry.openings)) return 'openings';
-  return null;
-};
-
-/**
- * verifyRecord(text | lines) → { ok, errors: [{seq, reason, detail?}], entries, head, settled }
- *
- * Text is a whole file, so a torn final line (no newline) can be seen; an
- * array is taken as complete lines. Each problem is reported at the seq of
- * the line where it was observed:
- *   torn           the last line was cut short by a crash mid-write
- *   unparseable    not JSON
- *   bad_envelope   an envelope field is missing or malformed (detail names it)
- *   unsupported_version  v is newer than this reader
- *   not_canonical  the bytes are not the canonical form of what they parse to
- *   seq_mismatch   seq is not the previous seq + 1 (a deleted or moved line)
- *   prev_mismatch  prev is not the hash of the line before it: that line, or
- *                  this one's prev, was changed, removed or moved
- *   run_mismatch   runId, taskId or podId differs from the first line
- *   after_settled  a line follows run.settled
- *   bad_opening    an opening does not match its commitment
- *   stray_opening  an opening's commitment is not on the line
- * The chain re-syncs after each problem, so one edit is reported once.
- *
- * A redacted view (spec section 8) passes this check by what it can show. A
- * line with a `redaction` marker is not the stored line: its marker names the
- * stored line's hash, which the next line is checked against, or null when
- * that hash is withheld and the next line links to nothing. Only a view adds
- * `partial: true`, `redacted` (the seqs whose content the chain doesn't cover)
- * and `unlinked` (the subset with no hash to link through); `ok` then says no
- * tampering was found in what could be checked, not that every line was.
- *
- * A line with `openings` (section 9) is checked as the stored line it was
- * built from: the map comes off, and the bytes left are what `prev` covers. A
- * commitment nobody opened is not a problem. A deleted id looks exactly so.
- */
-export const verifyRecord = (input) => {
-  const { lines, torn } = Array.isArray(input) ? { lines: input.map(String), torn: null } : splitRecord(input);
-  const errors = [];
-  const report = (seq, reason, detail) => errors.push(detail ? { seq, reason, detail } : { seq, reason });
-  let expected = 1;
-  let prevHash = null;
-  let first = null;
-  let settled = false;
-  const redacted = [];
-  const unlinked = [];
-  for (const line of lines) {
-    let entry;
-    try { entry = JSON.parse(line); } catch { entry = undefined; }
-    if (!isPlainObject(entry)) {
-      report(expected, 'unparseable');
-      prevHash = hashLine(line);
-      expected += 1;
-      continue;
-    }
-    const seq = Number.isInteger(entry.seq) ? entry.seq : expected;
-    if (Number.isInteger(entry.v) && entry.v > RECORD_VERSION) report(seq, 'unsupported_version', `v${entry.v}`);
-    const problem = envelopeProblem(entry);
-    if (problem) report(seq, 'bad_envelope', problem);
-    let canonicalForm = null;
-    try { canonicalForm = canonicalLine(entry); } catch { /* reported below */ }
-    if (canonicalForm !== line) report(seq, 'not_canonical');
-    if (seq !== expected) report(seq, 'seq_mismatch', `expected ${expected}`);
-    if (entry.prev !== prevHash) report(seq, 'prev_mismatch');
-    if (first === null) first = entry;
-    else if (entry.runId !== first.runId || entry.taskId !== first.taskId || entry.podId !== first.podId) report(seq, 'run_mismatch');
-    if (settled) report(seq, 'after_settled');
-    if (entry.kind === 'run.settled') settled = true;
-    const { openings, ...stored } = entry;
-    if (isOpenings(openings)) {
-      const onLine = idTokens(stored);
-      for (const [token, { id, salt }] of Object.entries(openings)) {
-        if (commitId(id, salt) !== token) report(seq, 'bad_opening');
-        if (!onLine.has(token)) report(seq, 'stray_opening');
-      }
-    }
-    const marker = isRedaction(entry.redaction) ? entry.redaction : null;
-    if (marker) {
-      redacted.push(seq);
-      if (marker.hash === null) unlinked.push(seq);
-    }
-    if (marker) prevHash = marker.hash;
-    else if (openings === undefined) prevHash = hashLine(line);
-    else {
-      // What can't be serialized was reported as not_canonical above.
-      try { prevHash = hashLine(canonicalLine(stored)); } catch { prevHash = hashLine(line); }
-    }
-    expected = seq + 1;
-  }
-  if (torn !== null) report(expected, 'torn');
-  return {
-    ok: errors.length === 0,
-    errors,
-    entries: lines.length,
-    head: prevHash,
-    settled,
-    ...(redacted.length > 0 ? { partial: true, redacted, unlinked } : {}),
-  };
-};
-
-/** An entry with each opened commitment replaced by its id, and no `openings`. */
-const openEntry = ({ openings, ...entry }) => {
-  if (!isOpenings(openings)) return entry;
-  const open = (value) => {
-    if (typeof value === 'string') return Object.hasOwn(openings, value) ? openings[value].id : value;
-    if (Array.isArray(value)) return value.map(open);
-    return isPlainObject(value) ? Object.fromEntries(Object.entries(value).map(([key, item]) => [key, open(item)])) : value;
-  };
-  return open(entry);
-};
-
-/**
- * Parse a record's text into entries, skipping a torn tail and unparseable
- * lines. Opened ids read in place; a commitment nobody opened stays as it is.
- */
-export const readRecord = (text) => splitRecord(text).lines.flatMap((line) => {
-  try {
-    const entry = JSON.parse(line);
-    return isPlainObject(entry) ? [openEntry(entry)] : [];
-  } catch { return []; }
-});
-
-/**
- * Which surface a tool name belongs to, for an adapter that knows the real
- * tool name (an MCP server/tool pair, say). Never apply it to a title: a
- * title is the agent's own text and can claim any prefix.
- */
-export const toolSurfaceOf = (toolName) => {
-  const name = String(toolName || '');
-  if (/^(?:mcp__commonly__|commonly_)/.test(name)) return 'commonly';
-  if (/^mcp__[^_]/.test(name)) return 'connector';
-  return 'native';
-};