@tangle-network/agent-runtime 6.0.8 → 7.0.0

package/dist/settle-record-U7fkQEZa.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"settle-record-U7fkQEZa.js","names":[],"sources":["../src/durable/settle-record.ts"],"sourcesContent":["import { readFile } from 'node:fs/promises'\nimport { resolve } from 'node:path'\nimport { canonicalCandidateDigest, canonicalCandidateJson } from '@tangle-network/agent-interface'\nimport {\n  publishExclusiveDurableFile,\n  writeAtomicDurableFile,\n} from '../runtime/supervise/durable-file'\nimport type { RootStreamReceipt, SupervisedResult } from '../runtime/supervise/types'\nimport { isNoEntError } from './jsonl-file'\n\n/** Terminal evidence has one result per segment. Reopen archives that result byte for byte;\n * a failed attempt may resume because failure.json records only the latest throw.\n * Serialization, exclusive publication and validation stay with the record operations below.\n */\n\n/** The settle record: the returned `SupervisedResult` as canonical JSON, written once. */\nexport const SETTLE_RECORD_FILE = 'result.json'\n/** The failure record: the most recent throw, replaced by a later throw. */\nexport const FAILURE_RECORD_FILE = 'failure.json'\n\n/** What `failure.json` records about the most recent throw. */\nexport interface DurableFailureRecord {\n  readonly runId: string\n  readonly pursuitId: string\n  /** ISO instant the throw was recorded. */\n  readonly at: string\n  readonly error: { readonly name: string; readonly message: string }\n  /** The root's retained provider stream at the time of the throw, when the directory holds one:\n   *  a root that died mid-turn keeps what it had streamed, and this names it. */\n  readonly rootStream?: RootStreamReceipt\n}\n\n/** The directory already holds a settle record, so the run it records must not be re-entered. */\nexport class SettledRunDirectoryError extends Error {\n  readonly path: string\n  /** The root of the recorded run, which is its `runId`. */\n  readonly recordedRunId: string\n\n  constructor(path: string, recordedRunId: string, requestedRunId: string) {\n    super(\n      recordedRunId === requestedRunId\n        ? `supervisePursuit: ${path} records that run '${recordedRunId}' already settled; a settled run is not re-entered unless the call passes reopen: { operator, reason, operationId }`\n        : `supervisePursuit: ${path} records that run '${recordedRunId}' already settled in this directory; a directory holds one settle record, so run '${requestedRunId}' needs its own runDir`,\n    )\n    this.name = 'SettledRunDirectoryError'\n    this.path = path\n    this.recordedRunId = recordedRunId\n  }\n}\n\n/** A result member whose JSON form would misstate it. */\nclass UnrecordableSettleValueError extends TypeError {\n  readonly path: string\n\n  constructor(path: string, kind: string) {\n    super(\n      `supervisePursuit: result${path} is a ${kind}, which JSON cannot record faithfully; a settle record holds plain data only`,\n    )\n    this.name = 'UnrecordableSettleValueError'\n    this.path = path\n  }\n}\n\nconst PLAIN_PROTOTYPES = new Set<unknown>([Object.prototype, Array.prototype, null])\n\n/**\n * The JSON value of a result, or a throw naming the first member JSON would misstate. An\n * `undefined` member and a function are dropped, exactly as any JSON consumer drops them; a Map,\n * a Set, a Date, a typed array, or a class instance would be rewritten to `{}` or a string and\n * so is refused.\n */\nfunction jsonValue(result: unknown): unknown {\n  const seen: unknown[] = []\n  const visit = (value: unknown, path: string): void => {\n    if (value === null || typeof value !== 'object') return\n    if (value instanceof Map) throw new UnrecordableSettleValueError(path, 'Map')\n    if (value instanceof Set) throw new UnrecordableSettleValueError(path, 'Set')\n    if (value instanceof Date) throw new UnrecordableSettleValueError(path, 'Date')\n    if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {\n      throw new UnrecordableSettleValueError(path, 'binary buffer')\n    }\n    if (!PLAIN_PROTOTYPES.has(Object.getPrototypeOf(value))) {\n      throw new UnrecordableSettleValueError(path, 'class instance')\n    }\n    if (seen.includes(value)) throw new UnrecordableSettleValueError(path, 'cycle')\n    seen.push(value)\n    if (Array.isArray(value)) {\n      for (const [index, item] of value.entries()) visit(item, `${path}[${index}]`)\n    } else {\n      for (const [key, item] of Object.entries(value)) visit(item, `${path}.${key}`)\n    }\n    seen.pop()\n  }\n  visit(result, '')\n  return JSON.parse(JSON.stringify(result))\n}\n\n/**\n * The exact bytes `result.json` holds for a result: its JSON value serialized as RFC 8785\n * canonical JSON. Throws `UnrecordableSettleValueError` before any byte is written when the\n * result carries a value JSON would misstate.\n */\nexport function settleRecordJson(result: unknown): string {\n  return canonicalCandidateJson(jsonValue(result))\n}\n\n/** The digest the settle record's bytes hash to: the candidate digest of the result's JSON value. */\nexport function settleRecordDigest(result: unknown): string {\n  return canonicalCandidateDigest(jsonValue(result))\n}\n\n/** Publish `result.json` in the run directory once. Throws when a record is already there. */\nexport async function writeSettleRecord(runDir: string, result: unknown): Promise<string> {\n  const path = resolve(runDir, SETTLE_RECORD_FILE)\n  if (!publishExclusiveDurableFile(path, settleRecordJson(result))) {\n    throw new Error(`supervisePursuit: ${path} already exists; a settle record is written once`)\n  }\n  return path\n}\n\n/** Replace `failure.json` in the run directory with the most recent throw. */\nexport async function writeFailureRecord(\n  runDir: string,\n  record: DurableFailureRecord,\n): Promise<string> {\n  const path = resolve(runDir, FAILURE_RECORD_FILE)\n  writeAtomicDurableFile(path, `${JSON.stringify(record, null, 2)}\\n`)\n  return path\n}\n\n/**\n * Read the settle record a run directory holds, or `undefined` when it holds none. A file that\n * is present but is not a settle record is corruption and fails loud.\n */\nexport async function readSettleRecord(\n  runDir: string,\n): Promise<SupervisedResult<unknown> | undefined> {\n  return readTerminalFile(runDir, SETTLE_RECORD_FILE, parseSettleRecord)\n}\n\nasync function readTerminalFile<T>(\n  runDir: string,\n  file: string,\n  parse: (text: string, path: string) => T,\n): Promise<T | undefined> {\n  const path = resolve(runDir, file)\n  try {\n    return parse(await readFile(path, 'utf8'), path)\n  } catch (error) {\n    if (isNoEntError(error)) return undefined\n    throw error\n  }\n}\n\nfunction parseTerminalJson(text: string, path: string): unknown {\n  try {\n    return JSON.parse(text)\n  } catch (cause) {\n    throw new Error(`supervisePursuit: ${path} is not valid JSON`, { cause })\n  }\n}\n\n/** Parse settle-record bytes already read, so a caller hashes and parses the same bytes. */\nexport function parseSettleRecord(text: string, path: string): SupervisedResult<unknown> {\n  const parsed = parseTerminalJson(text, path)\n  const record = parsed as { kind?: unknown; tree?: { root?: unknown } }\n  if (\n    typeof record !== 'object' ||\n    record === null ||\n    typeof record.kind !== 'string' ||\n    typeof record.tree !== 'object' ||\n    record.tree === null ||\n    typeof record.tree.root !== 'string'\n  ) {\n    throw new Error(`supervisePursuit: ${path} is not a settle record (no kind or tree.root)`)\n  }\n  return parsed as SupervisedResult<unknown>\n}\n\n/** Read the most recent failure record, or `undefined` when the directory holds none. */\nexport async function readFailureRecord(runDir: string): Promise<DurableFailureRecord | undefined> {\n  return readTerminalFile(runDir, FAILURE_RECORD_FILE, (text, path) => {\n    const parsed = parseTerminalJson(text, path)\n    const record = parsed as Partial<DurableFailureRecord>\n    if (\n      typeof record !== 'object' ||\n      record === null ||\n      typeof record.runId !== 'string' ||\n      typeof record.pursuitId !== 'string' ||\n      typeof record.at !== 'string' ||\n      typeof record.error?.name !== 'string' ||\n      typeof record.error.message !== 'string' ||\n      (record.rootStream !== undefined &&\n        (typeof record.rootStream.ref !== 'string' || typeof record.rootStream.events !== 'number'))\n    ) {\n      throw new Error(`supervisePursuit: ${path} is not a failure record`)\n    }\n    return parsed as DurableFailureRecord\n  })\n}\n"],"mappings":"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"}