@supernovae-st/nika 0.71.0 → 0.120.0

package/dist/index.js

@@ -0,0 +1,3502 @@
+// src/errors.ts
+var NikaError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "NikaError";
+  }
+};
+var NikaConfigurationError = class extends NikaError {
+  constructor(message) {
+    super(message);
+    this.name = "NikaConfigurationError";
+  }
+};
+var NikaTransportError = class extends NikaError {
+  transport;
+  constructor(transport, message, options) {
+    super(message, options);
+    this.name = "NikaTransportError";
+    this.transport = transport;
+  }
+};
+var NikaCompatibilityError = class extends NikaError {
+  capability;
+  transport;
+  constructor(capability, transport, message) {
+    super(message);
+    this.name = "NikaCompatibilityError";
+    this.capability = capability;
+    this.transport = transport;
+  }
+};
+var NikaProtocolError = class extends NikaTransportError {
+  constructor(transport, message, options) {
+    super(transport, message, options);
+    this.name = "NikaProtocolError";
+  }
+};
+var NikaObservationInterrupted = class extends NikaTransportError {
+  runId;
+  lastSequence;
+  attempts;
+  constructor(transport, runId, lastSequence, attempts) {
+    super(
+      transport,
+      `HTTP observation interrupted after ${attempts} retries; run ${runId} last acknowledged sequence ${lastSequence}`
+    );
+    this.name = "NikaObservationInterrupted";
+    this.runId = runId;
+    this.lastSequence = lastSequence;
+    this.attempts = attempts;
+  }
+};
+var NikaOperationError = class extends NikaError {
+  operation;
+  code;
+  transport;
+  status;
+  findings;
+  currentRevision;
+  machineCode;
+  constructor(operation, transport, code, message, details) {
+    super(message);
+    this.name = "NikaOperationError";
+    this.operation = operation;
+    this.code = code;
+    this.transport = transport;
+    this.status = details.status;
+    this.findings = details.findings;
+    this.currentRevision = details.currentRevision;
+    this.machineCode = details.machineCode;
+  }
+};
+var NikaEventBufferOverflowError = class extends NikaError {
+  runId;
+  /** The bound that was exceeded: the view's `bufferSize`. */
+  limit;
+  reason;
+  constructor(runId, limit, replay) {
+    super(replay === void 0 ? `Event subscriber for run ${runId} exceeded its ${limit}-event buffer` : `Run ${runId} had produced ${replay.observed} events when this view was opened, more than the ${limit} it can replay (${replay.retained} still retained). The run and its result are unaffected. ` + (replay.retained === replay.observed ? `Open the view with bufferSize >= ${replay.observed}` : `Set eventBufferSize >= ${replay.observed} for the next run`) + ", or observe the run live");
+    this.name = "NikaEventBufferOverflowError";
+    this.runId = runId;
+    this.limit = limit;
+    this.reason = replay === void 0 ? "live_backpressure" : "replay_truncated";
+    if (replay !== void 0) {
+      this.observed = replay.observed;
+      this.retained = replay.retained;
+    }
+  }
+};
+var NikaRunOwnershipError = class extends NikaError {
+  constructor() {
+    super("The NikaRun was not created by this Nika client");
+    this.name = "NikaRunOwnershipError";
+  }
+};
+
+// src/lib/binary/error.ts
+var NikaEngineUnavailable = class extends NikaError {
+  code = "NIKA_ENGINE_UNAVAILABLE";
+  platform;
+  arch;
+  packageName;
+  constructor(platform, arch, packageName) {
+    const target = `${platform}-${arch}`;
+    const detail = packageName ? `the optional payload ${packageName} is not installed (npm leaves it UNMET OPTIONAL when the registry has no version matching this client)` : "there is no packaged payload for this host";
+    super(
+      `Nika engine unavailable for ${target}: ${detail}. A nika found on PATH is deliberately not used. Set NIKA_BIN=/absolute/path/to/nika, pass config.bin, or install the matching payload package.`
+    );
+    this.name = "NikaEngineUnavailable";
+    this.platform = platform;
+    this.arch = arch;
+    this.packageName = packageName;
+  }
+};
+
+// src/lib/binary/packages.ts
+var NATIVE_PACKAGES = {
+  "darwin-arm64": "@supernovae-st/nika-darwin-arm64",
+  "darwin-x64": "@supernovae-st/nika-darwin-x64",
+  "linux-x64": "@supernovae-st/nika-linux-x64",
+  "linux-arm64": "@supernovae-st/nika-linux-arm64"
+};
+function packageForHost(platform, arch, glibc) {
+  if (platform === "linux" && !glibc) return void 0;
+  return NATIVE_PACKAGES[`${platform}-${arch}`];
+}
+
+// src/lib/binary/resolve.ts
+import { createRequire } from "module";
+import path from "path";
+var requireFromBundle = createRequire(
+  typeof import.meta.url === "string" ? import.meta.url : __filename
+);
+function resolveNikaEngine(configuredBin, host = {}) {
+  if (configuredBin !== void 0) {
+    return { bin: absoluteEnginePath(configuredBin, "bin") };
+  }
+  const envBin = (host.env ?? process.env).NIKA_BIN;
+  if (envBin !== void 0) {
+    return { bin: absoluteEnginePath(envBin, "NIKA_BIN") };
+  }
+  const platform = host.platform ?? process.platform;
+  const arch = host.arch ?? process.arch;
+  const packageName = packageForHost(
+    platform,
+    arch,
+    host.glibc ?? runtimeIsGlibc(platform)
+  );
+  if (!packageName) throw new NikaEngineUnavailable(platform, arch);
+  try {
+    const packageJson = (host.resolvePackageJson ?? requireFromBundle.resolve)(
+      `${packageName}/package.json`
+    );
+    const packageRoot = path.dirname(packageJson);
+    return {
+      bin: path.join(packageRoot, "bin", "nika"),
+      packageName,
+      packageRoot
+    };
+  } catch (cause) {
+    if (isMissingModule(cause)) {
+      throw new NikaEngineUnavailable(platform, arch, packageName);
+    }
+    throw cause;
+  }
+}
+function absoluteEnginePath(value, source) {
+  if (value.length === 0) {
+    throw new NikaConfigurationError(`${source} must be a non-empty string`);
+  }
+  if (!path.isAbsolute(value)) {
+    throw new NikaConfigurationError(
+      `${source} must be an absolute path to a nika engine (got "${value}"); a bare name or a relative path would be resolved through PATH or the working directory, which this client refuses`
+    );
+  }
+  return value;
+}
+function runtimeIsGlibc(platform) {
+  if (platform !== "linux") return true;
+  const report = process.report?.getReport();
+  return typeof report?.header?.glibcVersionRuntime === "string";
+}
+function isMissingModule(cause) {
+  return cause instanceof Error && "code" in cause && cause.code === "MODULE_NOT_FOUND";
+}
+
+// src/lib/binary/verify.ts
+import { createHash } from "crypto";
+import { createReadStream } from "fs";
+import { readFile, stat } from "fs/promises";
+import path2 from "path";
+
+// src/lib/engine-capture.ts
+import { spawn } from "child_process";
+function captureEngine(bin, args, options) {
+  return new Promise((resolve, reject) => {
+    if (options.signal?.aborted) {
+      reject(new NikaTransportError(options.transport, `${options.label} aborted by caller`));
+      return;
+    }
+    const child = spawn(bin, args, {
+      cwd: options.cwd,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let overflow = false;
+    let spawnError;
+    const append = (stream, chunk) => {
+      if (overflow) return;
+      if (stream === "stdout") stdout += chunk;
+      else stderr += chunk;
+      if (Buffer.byteLength(stdout) > options.bufferBytes || Buffer.byteLength(stderr) > options.bufferBytes) {
+        overflow = true;
+        child.kill("SIGTERM");
+      }
+    };
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => append("stdout", chunk));
+    child.stderr.on("data", (chunk) => append("stderr", chunk));
+    const abort = () => child.kill("SIGTERM");
+    options.signal?.addEventListener("abort", abort, { once: true });
+    child.once("error", (cause) => {
+      spawnError = cause;
+    });
+    child.once("close", (code) => {
+      options.signal?.removeEventListener("abort", abort);
+      if (options.signal?.aborted) {
+        reject(new NikaTransportError(options.transport, `${options.label} aborted by caller`));
+      } else if (spawnError) {
+        reject(new NikaTransportError(
+          options.transport,
+          `Cannot spawn ${bin} for ${options.label}: ${spawnError.message}`,
+          { cause: spawnError }
+        ));
+      } else if (overflow) {
+        reject(new NikaProtocolError(
+          options.transport,
+          `${options.label} exceeded ${options.bufferBytes} bytes`
+        ));
+      } else {
+        resolve({ exitCode: code ?? 3, stdout, stderr });
+      }
+    });
+  });
+}
+
+// src/lib/settlement.ts
+var TALLY_FIELDS = [
+  "total",
+  "ok",
+  "failed",
+  "recovered",
+  "skipped",
+  "cancelled",
+  "never_started"
+];
+function readSettlement(value, transport, expectedStatus) {
+  const fault = (detail) => {
+    throw new NikaProtocolError(transport, `Engine settlement was malformed: ${detail}`);
+  };
+  const settlement = record(value) ?? fault("not an object");
+  for (const field of ["status", "cause"]) {
+    if (settlement[field] !== void 0 && typeof settlement[field] !== "string") {
+      fault(`${field} was not a string`);
+    }
+  }
+  if (settlement.status !== void 0 && expectedStatus !== void 0 && settlement.status !== expectedStatus) {
+    fault(`status ${String(settlement.status)} contradicts the record's ${expectedStatus}`);
+  }
+  count("elapsed_ms", settlement.elapsed_ms, fault);
+  if (settlement.tasks !== void 0) {
+    const tasks = record(settlement.tasks) ?? fault("tasks was not an object");
+    for (const field of TALLY_FIELDS) count(`tasks.${field}`, tasks[field], fault);
+  }
+  if (settlement.spend !== void 0) {
+    const spend = record(settlement.spend) ?? fault("spend was not an object");
+    if (spend.qualifier !== void 0 && typeof spend.qualifier !== "string") {
+      fault("spend.qualifier was not a string");
+    }
+    if (spend.pricing_as_of !== void 0 && spend.pricing_as_of !== null && typeof spend.pricing_as_of !== "string") {
+      fault("spend.pricing_as_of was not a string");
+    }
+    count("spend.priced_calls", spend.priced_calls, fault);
+    count("spend.unpriced_calls", spend.unpriced_calls, fault);
+    if (spend.total_cost_usd !== void 0 && spend.total_cost_usd !== null) {
+      amount("spend.total_cost_usd", spend.total_cost_usd, fault);
+    }
+    if (spend.by_source !== void 0) {
+      const bySource = record(spend.by_source) ?? fault("spend.by_source was not an object");
+      for (const [source, cost] of Object.entries(bySource)) {
+        amount(`spend.by_source.${source}`, cost, fault);
+      }
+    }
+  }
+  if (settlement.error !== void 0) {
+    const error = record(settlement.error) ?? fault("error was not an object");
+    if (typeof error.code !== "string" || typeof error.message !== "string") {
+      fault("error omitted its code or message");
+    }
+    if (error.task !== void 0 && typeof error.task !== "string") {
+      fault("error.task was not a string");
+    }
+  }
+  return settlement;
+}
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function count(name, value, fault) {
+  if (value === void 0) return;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    fault(`${name} was not a non-negative integer`);
+  }
+}
+function amount(name, value, fault) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    fault(`${name} was not a non-negative number`);
+  }
+}
+
+// src/lib/machine.ts
+function machineObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function parseMachineObject(text, transport) {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (cause) {
+    throw new NikaProtocolError(transport, "Engine machine output was not valid JSON", {
+      cause: cause instanceof Error ? cause : void 0
+    });
+  }
+  const object = machineObject(value);
+  if (!object) {
+    throw new NikaProtocolError(transport, "Engine machine output was not a JSON object");
+  }
+  return object;
+}
+function eventStatus(event) {
+  if (typeof event?.status === "string") return event.status;
+  const fields = Array.isArray(event?.fields) ? event.fields : [];
+  for (const field of fields) {
+    const row = machineObject(field);
+    if (row?.key === "status" && typeof row.value === "string") return row.value;
+  }
+  return void 0;
+}
+function eventSettlement(event, transport = "http") {
+  if (!event) return void 0;
+  const record2 = event;
+  if (record2.settlement !== void 0) {
+    return readSettlement(record2.settlement, transport, eventStatus(event));
+  }
+  if (["cause", "elapsed_ms", "tasks", "spend"].every((key) => record2[key] === void 0)) return void 0;
+  const fields = ["status", "cause", "elapsed_ms", "tasks", "spend", "error"];
+  return readSettlement(Object.fromEntries(fields.filter((key) => record2[key] !== void 0).map((key) => [key, record2[key]])), transport, eventStatus(event));
+}
+function eventReceipt(event) {
+  const direct = machineObject(event?.receipt);
+  if (direct) return Object.freeze(direct);
+  const fields = Array.isArray(event?.fields) ? event.fields : [];
+  for (const field of fields) {
+    const row = machineObject(field);
+    if (row?.key === "receipt") {
+      const receipt = machineObject(row.value);
+      if (receipt) return Object.freeze(receipt);
+    }
+  }
+  return void 0;
+}
+function eventOutputs(event) {
+  const direct = machineObject(event?.outputs);
+  if (direct) return direct;
+  const fields = Array.isArray(event?.fields) ? event.fields : [];
+  for (const field of fields) {
+    const row = machineObject(field);
+    if (row?.key === "outputs") return machineObject(row.value);
+  }
+  return void 0;
+}
+function eventError(event) {
+  const settled = machineObject(machineObject(event?.settlement)?.error);
+  if (settled) return settled;
+  const direct = machineObject(event?.error);
+  if (direct) return direct;
+  if (typeof event?.code === "string" || typeof event?.message === "string") {
+    return {
+      ...typeof event.code === "string" ? { code: event.code } : {},
+      ...typeof event.message === "string" ? { message: event.message } : {}
+    };
+  }
+  return fieldsError(event);
+}
+function fieldsError(event) {
+  if (event?.kind !== "task_failed") return void 0;
+  const fields = Array.isArray(event.fields) ? event.fields : [];
+  let detail;
+  let task;
+  for (const field of fields) {
+    const row = machineObject(field);
+    if (row?.key === "detail" && typeof row.value === "string") detail = row.value;
+    if (row?.key === "task" && typeof row.value === "string") task = row.value;
+  }
+  if (detail === void 0) return void 0;
+  const match = detail.trim().match(/^(NIKA-[A-Z0-9-]+)\s*·?\s*([\s\S]*)$/);
+  const code = match?.[1];
+  const message = (match ? match[2] : detail).trim();
+  return {
+    ...code ? { code } : {},
+    ...message.length > 0 ? { message } : {},
+    ...task ? { task } : {}
+  };
+}
+function receiptTraceLocator(receipt) {
+  const value = receipt.trace_path;
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+
+// src/lib/engine-identity.ts
+var MACHINE_PROTOCOL_VERSION = 1;
+var REQUIRED_CAPABILITIES = ["check", "executionSnapshot", "eventStream"];
+var COMPATIBILITY_CLOCKS = [
+  "machineProtocolVersion",
+  "snapshotFormatVersion",
+  "checkReportVersion",
+  "eventFormatVersion"
+];
+function compatibleEngineIdentity(value, transport, peer) {
+  const identity = machineObject(value);
+  if (!identity) throw incompatible(transport, "Engine identity is not an object");
+  if (typeof identity.engineVersion !== "string" || identity.engineVersion.length === 0) {
+    throw incompatible(transport, "Engine identity is missing engineVersion");
+  }
+  for (const clock of COMPATIBILITY_CLOCKS) {
+    if (!Number.isSafeInteger(identity[clock])) {
+      throw incompatible(transport, `Engine identity is missing ${clock}`);
+    }
+  }
+  if (identity.machineProtocolVersion !== MACHINE_PROTOCOL_VERSION) {
+    throw incompatible(
+      transport,
+      `Engine machine protocol ${String(identity.machineProtocolVersion)} is incompatible with SDK protocol ${MACHINE_PROTOCOL_VERSION}`
+    );
+  }
+  if (!Array.isArray(identity.supportedCapabilities) || !identity.supportedCapabilities.every((item) => typeof item === "string")) {
+    throw incompatible(transport, "Engine identity is missing supportedCapabilities");
+  }
+  for (const capability of REQUIRED_CAPABILITIES) {
+    if (!identity.supportedCapabilities.includes(capability)) {
+      throw incompatible(transport, `Engine identity does not support ${capability}`);
+    }
+  }
+  const checked = identity;
+  if (peer) {
+    for (const clock of COMPATIBILITY_CLOCKS) {
+      if (checked[clock] !== peer[clock]) {
+        throw incompatible(
+          transport,
+          `Remote ${clock} ${checked[clock]} is incompatible with local ${clock} ${peer[clock]}`
+        );
+      }
+    }
+  }
+  return checked;
+}
+function incompatible(transport, message) {
+  return new NikaCompatibilityError("engineIdentity", transport, message);
+}
+
+// src/lib/binary/verify.ts
+var IDENTITY_BUFFER_BYTES = 16 * 1024;
+async function verifyNikaEngine(engine) {
+  const expectedVersion = engine.packageRoot ? await verifyManagedPayload(engine) : void 0;
+  const identity = await probeIdentity(engine.bin);
+  if (expectedVersion !== void 0 && identity.engineVersion !== expectedVersion) {
+    throw incompatible2(
+      `Packaged engine version ${identity.engineVersion} does not match payload version ${expectedVersion}`
+    );
+  }
+  return identity;
+}
+async function verifyManagedPayload(engine) {
+  const packageRoot = engine.packageRoot;
+  if (!packageRoot || !engine.packageName) {
+    throw incompatible2("Managed engine resolution is missing package identity");
+  }
+  const manifest = await readJson(path2.join(packageRoot, "package.json"), "payload manifest");
+  if (manifest.name !== engine.packageName || typeof manifest.version !== "string") {
+    throw incompatible2(`Invalid manifest for ${engine.packageName}`);
+  }
+  const integrity = await readJson(
+    path2.join(packageRoot, "INTEGRITY.json"),
+    "payload integrity metadata"
+  );
+  if (integrity.algorithm !== "sha256" || integrity.executable?.file !== "bin/nika" || !isSha256(integrity.executable?.sha256)) {
+    throw incompatible2(`Invalid INTEGRITY.json for ${engine.packageName}`);
+  }
+  let metadata;
+  try {
+    metadata = await stat(engine.bin);
+  } catch (cause) {
+    throw incompatible2(`Cannot read packaged engine ${engine.bin}`, cause);
+  }
+  if (!metadata.isFile()) {
+    throw incompatible2(`Packaged engine is not a file: ${engine.bin}`);
+  }
+  const actual = await sha256(engine.bin);
+  if (actual !== integrity.executable.sha256) {
+    throw incompatible2(`Packaged engine checksum mismatch for ${engine.packageName}`);
+  }
+  return manifest.version;
+}
+async function probeIdentity(bin) {
+  const notAnEngine = `is ${bin} a nika engine? (run "${bin} --sdk-identity" by hand)`;
+  const captured = await captureEngine(bin, ["--sdk-identity"], {
+    bufferBytes: IDENTITY_BUFFER_BYTES,
+    transport: "native-process",
+    label: "Engine identity probe"
+  }).catch((cause) => {
+    throw incompatible2(
+      `Engine identity probe of ${bin} failed`,
+      cause
+    );
+  });
+  if (captured.exitCode !== 0) {
+    throw incompatible2(
+      `Engine identity probe of ${bin} exited with code ${captured.exitCode}; ${notAnEngine}`
+    );
+  }
+  let value;
+  try {
+    value = JSON.parse(captured.stdout.trim());
+  } catch (cause) {
+    throw incompatible2(
+      `Engine identity probe of ${bin} did not emit one JSON object; ${notAnEngine}`,
+      cause
+    );
+  }
+  if (captured.stderr.trim()) {
+    throw incompatible2(`Engine identity probe of ${bin} wrote unexpected diagnostics`);
+  }
+  try {
+    return compatibleEngineIdentity(value, "native-process");
+  } catch (cause) {
+    if (cause instanceof NikaCompatibilityError) throw cause;
+    throw incompatible2("Engine identity probe was incompatible", cause);
+  }
+}
+async function readJson(file, label) {
+  try {
+    const parsed = JSON.parse(await readFile(file, "utf8"));
+    if (!isRecord(parsed)) throw new TypeError(`${label} is not an object`);
+    return parsed;
+  } catch (cause) {
+    throw incompatible2(`Cannot verify ${label} at ${file}`, cause);
+  }
+}
+function sha256(file) {
+  return new Promise((resolve, reject) => {
+    const hash = createHash("sha256");
+    const stream = createReadStream(file);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.once("error", reject);
+    stream.once("end", () => resolve(hash.digest("hex")));
+  });
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isSha256(value) {
+  return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+function incompatible2(message, cause) {
+  return new NikaCompatibilityError(
+    "engineIdentity",
+    "native-process",
+    cause instanceof Error ? `${message}: ${cause.message}` : message
+  );
+}
+
+// src/lib/literal-inputs.ts
+import { types } from "util";
+var LITERAL_INPUTS_MAX_BYTES = 1024 * 1024;
+function literalInputs(options) {
+  if (options.inputs === void 0) return void 0;
+  if (options.vars !== void 0) {
+    throw new NikaConfigurationError(
+      "run({ inputs, vars }): inputs and the deprecated vars alias cannot be combined; move every value into inputs"
+    );
+  }
+  return encodeLiteralInputs(options.inputs);
+}
+var STRICT_JSON = "inputs must be strict JSON (null, booleans, finite numbers, strings, plain arrays and plain objects)";
+var NATIVE_OBJECT = Function.prototype.toString.call(Object);
+var NATIVE_ARRAY = Function.prototype.toString.call(Array);
+var LONE_SURROGATE = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/;
+var IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var PATH_LIMIT = 240;
+function encodeLiteralInputs(inputs) {
+  if (containerKind(inputs) !== "object") {
+    throw new NikaConfigurationError(
+      `run({ inputs }): inputs must be a plain object mapping declared workflow input names to strict JSON values; received ${describe(inputs)}`
+    );
+  }
+  const parts = [];
+  let bytes = 0;
+  const write = (chunk) => {
+    bytes += Buffer.byteLength(chunk);
+    if (bytes > LITERAL_INPUTS_MAX_BYTES) throw tooLarge();
+    parts.push(chunk);
+  };
+  const stack = [];
+  const open = /* @__PURE__ */ new Set();
+  const refuse = (segment, problem) => {
+    const path3 = stack.map((frame) => frame.segment).join("") + segment;
+    const shown = path3.length > PATH_LIMIT ? `${path3.slice(0, PATH_LIMIT / 2)}\u2026${path3.slice(-PATH_LIMIT / 2)}` : path3;
+    return new NikaConfigurationError(`run({ inputs }): ${shown} ${problem}; ${STRICT_JSON}`);
+  };
+  const enter = (value, segment, kind) => {
+    open.add(value);
+    if (kind === "array") {
+      write("[");
+      stack.push({ value, segment, length: value.length, index: 0 });
+    } else {
+      write("{");
+      const keys = Reflect.ownKeys(value);
+      stack.push({ value, segment, keys, length: keys.length, index: 0 });
+    }
+  };
+  enter(inputs, "inputs", "object");
+  for (let frame = stack.at(-1); frame; frame = stack.at(-1)) {
+    if (frame.index === frame.length) {
+      if (!frame.keys) {
+        const named = Reflect.ownKeys(frame.value).find((key2) => !isArrayMember(key2, frame.length));
+        if (named !== void 0) {
+          stack.pop();
+          throw refuse(frame.segment + keySegment(named), typeof named === "symbol" ? "is a symbol key, which JSON cannot carry" : "is a named array property, which JSON cannot carry");
+        }
+      }
+      write(frame.keys ? "}" : "]");
+      open.delete(frame.value);
+      stack.pop();
+      continue;
+    }
+    const position = frame.index;
+    frame.index += 1;
+    if (position > 0) write(",");
+    const key = frame.keys ? frame.keys[position] : String(position);
+    const segment = frame.keys ? keySegment(key) : `[${position}]`;
+    if (typeof key === "symbol") throw refuse(segment, "is a symbol key, which JSON cannot carry");
+    const member = Object.getOwnPropertyDescriptor(frame.value, key);
+    if (!member) {
+      throw refuse(segment, frame.keys ? "is not an own data property" : "is an array hole, which JSON cannot carry");
+    }
+    if ("get" in member || "set" in member) {
+      throw refuse(segment, "is an accessor property, which JSON cannot carry");
+    }
+    if (frame.keys) {
+      if (!member.enumerable) {
+        throw refuse(segment, "is a non-enumerable property, which JSON cannot carry");
+      }
+      if (LONE_SURROGATE.test(key)) {
+        throw refuse(segment, "is a key with a lone surrogate, which is not valid Unicode");
+      }
+      write(`${JSON.stringify(key)}:`);
+    }
+    const value = member.value;
+    switch (typeof value) {
+      case "string":
+        if (value.length > LITERAL_INPUTS_MAX_BYTES) throw tooLarge();
+        if (LONE_SURROGATE.test(value)) {
+          throw refuse(segment, "contains a lone surrogate, which is not valid Unicode");
+        }
+        write(JSON.stringify(value));
+        break;
+      case "number":
+        if (!Number.isFinite(value)) {
+          throw refuse(segment, "is a non-finite number, which JSON cannot carry");
+        }
+        write(JSON.stringify(value));
+        break;
+      case "boolean":
+        write(value ? "true" : "false");
+        break;
+      case "object": {
+        if (value === null) {
+          write("null");
+          break;
+        }
+        if (open.has(value)) throw refuse(segment, "is a cycle, which JSON cannot carry");
+        const kind = containerKind(value);
+        if (!kind) throw refuse(segment, refusedObject(value));
+        enter(value, segment, kind);
+        break;
+      }
+      default:
+        throw refuse(segment, `is ${typeof value === "undefined" ? "" : "a "}${typeof value}, which JSON cannot carry`);
+    }
+  }
+  return { json: parts.join(""), bytes };
+}
+function tooLarge() {
+  return new NikaConfigurationError(
+    `run({ inputs }): the serialized inputs map exceeds ${LITERAL_INPUTS_MAX_BYTES} bytes (1 MiB), the bound both transports share with the native engine`
+  );
+}
+function containerKind(value) {
+  if (value === null || typeof value !== "object" || types.isProxy(value)) return void 0;
+  const prototype = Object.getPrototypeOf(value);
+  if (Array.isArray(value)) return isRealmPrototype(prototype, NATIVE_ARRAY) ? "array" : void 0;
+  if (prototype === null) return "object";
+  return isRealmPrototype(prototype, NATIVE_OBJECT) ? "object" : void 0;
+}
+function isRealmPrototype(prototype, source) {
+  if (prototype === null || types.isProxy(prototype)) return false;
+  const constructor = ownValue(prototype, "constructor");
+  if (typeof constructor !== "function" || types.isProxy(constructor)) return false;
+  let native;
+  try {
+    native = Function.prototype.toString.call(constructor) === source;
+  } catch {
+    return false;
+  }
+  return native && ownValue(constructor, "prototype") === prototype;
+}
+function ownValue(target, key) {
+  return Object.getOwnPropertyDescriptor(target, key)?.value;
+}
+function isArrayMember(key, length) {
+  if (typeof key === "symbol") return false;
+  if (key === "length") return true;
+  const index = Number(key);
+  return Number.isInteger(index) && index >= 0 && index < length && String(index) === key;
+}
+function keySegment(key) {
+  if (typeof key === "symbol") return `[${String(key)}]`;
+  return IDENTIFIER.test(key) ? `.${key}` : `[${JSON.stringify(key)}]`;
+}
+function describe(value) {
+  if (value === null) return "null";
+  if (typeof value === "undefined") return "undefined";
+  if (typeof value !== "object") return `a ${typeof value}`;
+  if (types.isProxy(value)) return "a Proxy";
+  if (Array.isArray(value)) return "an array";
+  return refusedObject(value).replace(/^is /, "").replace(/, not a plain object or array$/, "");
+}
+function refusedObject(value) {
+  if (types.isProxy(value)) return "is a Proxy, which cannot be read without running its traps";
+  const custom = "is an object with a custom prototype, not a plain object or array";
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype === null || types.isProxy(prototype)) return custom;
+  const constructor = ownValue(prototype, "constructor");
+  if (typeof constructor !== "function" || types.isProxy(constructor)) return custom;
+  if (ownValue(constructor, "prototype") !== prototype) return custom;
+  const name = ownValue(constructor, "name");
+  return typeof name === "string" && IDENTIFIER.test(name) && name.length <= 64 ? `is a ${name} instance, not a plain object or array` : custom;
+}
+
+// src/lib/sse/parser.ts
+var SseParseError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "SseParseError";
+  }
+};
+var SseParser = class {
+  constructor(limits) {
+    this.limits = limits;
+    for (const [name, value] of Object.entries(limits)) {
+      if (!Number.isSafeInteger(value) || value < 1) {
+        throw new RangeError(`${name} must be a positive integer`);
+      }
+    }
+  }
+  pending = new Uint8Array(0);
+  pendingBytes = 0;
+  frameBytes = 0;
+  dataLines = [];
+  id;
+  retry;
+  firstLine = true;
+  push(chunk) {
+    const frames = [];
+    let offset = 0;
+    while (offset < chunk.length) {
+      const newline = chunk.indexOf(10, offset);
+      if (newline < 0) {
+        this.append(chunk.subarray(offset));
+        break;
+      }
+      this.append(chunk.subarray(offset, newline));
+      const frame = this.processPendingLine();
+      if (frame) frames.push(frame);
+      offset = newline + 1;
+    }
+    return frames;
+  }
+  finish() {
+    if (this.pendingBytes > 0) this.processPendingLine(false);
+    if (this.dataLines.length > 0) {
+      throw new SseParseError("SSE stream ended with an incomplete data frame");
+    }
+    this.resetFrame();
+    return [];
+  }
+  append(bytes) {
+    const length = this.pendingBytes + bytes.length;
+    if (length > this.limits.maxBufferBytes) {
+      throw new SseParseError(`SSE buffer exceeded ${this.limits.maxBufferBytes} bytes`);
+    }
+    if (length > this.limits.maxLineBytes) {
+      throw new SseParseError(`SSE line exceeded ${this.limits.maxLineBytes} bytes`);
+    }
+    if (bytes.length === 0) return;
+    this.ensurePendingCapacity(length);
+    this.pending.set(bytes, this.pendingBytes);
+    this.pendingBytes = length;
+  }
+  ensurePendingCapacity(length) {
+    if (this.pending.byteLength >= length) return;
+    const ceiling = Math.min(this.limits.maxBufferBytes, this.limits.maxLineBytes);
+    const capacity = Math.min(
+      ceiling,
+      Math.max(length, Math.max(1, this.pending.byteLength) * 2)
+    );
+    const pending = new Uint8Array(capacity);
+    pending.set(this.pending.subarray(0, this.pendingBytes));
+    this.pending = pending;
+  }
+  processPendingLine(terminated = true) {
+    const rawLength = this.pendingBytes + (terminated ? 1 : 0);
+    if (this.frameBytes + rawLength > this.limits.maxFrameBytes) {
+      throw new SseParseError(`SSE frame exceeded ${this.limits.maxFrameBytes} bytes`);
+    }
+    this.frameBytes += rawLength;
+    let bytes = this.pending.subarray(0, this.pendingBytes);
+    this.pendingBytes = 0;
+    if (bytes.at(-1) === 13) bytes = bytes.subarray(0, -1);
+    let line;
+    try {
+      line = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    } catch (cause) {
+      throw new SseParseError("SSE line was not valid UTF-8", {
+        cause: cause instanceof Error ? cause : void 0
+      });
+    }
+    if (this.firstLine) {
+      this.firstLine = false;
+      if (line.startsWith("\uFEFF")) line = line.slice(1);
+    }
+    if (line.length === 0) return this.dispatch();
+    if (line.startsWith(":")) return void 0;
+    const colon = line.indexOf(":");
+    const field = colon < 0 ? line : line.slice(0, colon);
+    let value = colon < 0 ? "" : line.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    switch (field) {
+      case "data":
+        this.dataLines.push(value);
+        break;
+      case "id":
+        if (!value.includes("\0")) this.id = value;
+        break;
+      case "retry":
+        if (/^\d+$/.test(value)) {
+          const parsed = Number(value);
+          if (Number.isSafeInteger(parsed)) this.retry = parsed;
+        }
+        break;
+      default:
+        break;
+    }
+    return void 0;
+  }
+  dispatch() {
+    const data = this.dataLines.join("\n");
+    const frame = {
+      ...data.length > 0 ? { data } : {},
+      ...this.id !== void 0 ? { id: this.id } : {},
+      ...this.retry !== void 0 ? { retry: this.retry } : {}
+    };
+    this.resetFrame();
+    return Object.keys(frame).length > 0 ? frame : void 0;
+  }
+  resetFrame() {
+    this.frameBytes = 0;
+    this.dataLines = [];
+    this.id = void 0;
+    this.retry = void 0;
+  }
+};
+async function* decodeSse(stream, limits, signal) {
+  const reader = stream.getReader();
+  const parser = new SseParser(limits);
+  const abort = () => {
+    void reader.cancel().catch(() => {
+    });
+  };
+  if (signal?.aborted) abort();
+  else signal?.addEventListener("abort", abort, { once: true });
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      for (const frame of parser.push(value)) yield frame;
+    }
+    for (const frame of parser.finish()) yield frame;
+  } finally {
+    signal?.removeEventListener("abort", abort);
+    await reader.cancel().catch(() => {
+    });
+    reader.releaseLock();
+  }
+}
+
+// src/lib/workflow-name.ts
+var WORKFLOW_SUFFIX = ".nika";
+var LEGACY_WORKFLOW_SUFFIXES = [".nika.yaml", ".nika.yml"];
+var CONTAINED_CHAR = /[A-Za-z0-9/._-]/;
+function workflowBasename(path3) {
+  const parts = path3.split(/[\\/]/);
+  return parts[parts.length - 1] ?? "";
+}
+function hasControlChar(value) {
+  for (const ch of value) {
+    const c = ch.codePointAt(0) ?? 0;
+    if (c <= 31 || c === 127) {
+      return true;
+    }
+  }
+  return false;
+}
+function isLegacyWorkflowPath(path3) {
+  if (typeof path3 !== "string" || path3.length === 0) {
+    return false;
+  }
+  if (path3.endsWith("/") || path3.endsWith("\\")) {
+    return false;
+  }
+  const base = workflowBasename(path3);
+  return LEGACY_WORKFLOW_SUFFIXES.some((suffix) => base.endsWith(suffix));
+}
+function isCanonicalWorkflowFilename(basename) {
+  if (typeof basename !== "string" || basename.length === 0) {
+    return false;
+  }
+  if (hasControlChar(basename)) {
+    return false;
+  }
+  if (basename.includes("/") || basename.includes("\\")) {
+    return false;
+  }
+  if (LEGACY_WORKFLOW_SUFFIXES.some((suffix) => basename.endsWith(suffix))) {
+    return false;
+  }
+  if (!basename.endsWith(WORKFLOW_SUFFIX)) {
+    return false;
+  }
+  return basename.length > WORKFLOW_SUFFIX.length;
+}
+function isCanonicalWorkflowPath(path3) {
+  if (typeof path3 !== "string" || path3.length === 0) {
+    return false;
+  }
+  if (hasControlChar(path3)) {
+    return false;
+  }
+  if (path3.endsWith("/") || path3.endsWith("\\")) {
+    return false;
+  }
+  return isCanonicalWorkflowFilename(workflowBasename(path3));
+}
+function containedRelativeShape(value) {
+  if (value.includes("\\") || value.startsWith("/")) {
+    return false;
+  }
+  for (const ch of value) {
+    if (!CONTAINED_CHAR.test(ch)) {
+      return false;
+    }
+  }
+  const segments = value.split("/");
+  return segments.every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}
+function isContainedWorkflowName(value) {
+  return typeof value === "string" && isCanonicalWorkflowPath(value) && containedRelativeShape(value);
+}
+function isRetiredByNameAttempt(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    return false;
+  }
+  if (value.startsWith("/") || value.startsWith("./") || value.includes("\\")) {
+    return false;
+  }
+  return isLegacyWorkflowPath(value);
+}
+function renameLegacyWorkflow(name) {
+  if (name.endsWith(".nika.yaml")) {
+    return `${name.slice(0, -".nika.yaml".length)}${WORKFLOW_SUFFIX}`;
+  }
+  if (name.endsWith(".nika.yml")) {
+    return `${name.slice(0, -".nika.yml".length)}${WORKFLOW_SUFFIX}`;
+  }
+  return name;
+}
+function legacyWorkflowRenameMessage(name) {
+  return `workflow names use ${WORKFLOW_SUFFIX}; rename ${name} to ${renameLegacyWorkflow(name)}`;
+}
+
+// src/lib/http-transport.ts
+var JOB_STATUSES = /* @__PURE__ */ new Set([
+  "queued",
+  "running",
+  "interrupted",
+  "paused",
+  "succeeded",
+  "failed",
+  "cancelled"
+]);
+var MAX_OBSERVATION_RETRIES = 5;
+var POSITIVE_TRACE_VERDICTS = /* @__PURE__ */ new Set(["VERIFIED", "OK", "SEALED", "ANCHORED", "REPLAYED"]);
+var RETRY_BASE_MILLISECONDS = 100;
+var RETRY_MIN_MILLISECONDS = 25;
+var RETRY_MAX_MILLISECONDS = 5e3;
+var WORKFLOW_REFUSAL_STATUSES = /* @__PURE__ */ new Set([404, 422]);
+var JOB_INPUTS = "jobInputs";
+var HttpTransport = class {
+  constructor(options) {
+    this.options = options;
+  }
+  kind = "http";
+  serverIdentity;
+  localIdentity;
+  resolvedEngine;
+  remoteIdentity;
+  async check(workflow, options) {
+    if (options.model !== void 0 || options.nativeStrict === true) {
+      throw this.gap(
+        "checkOptions",
+        "nika serve admission has no request envelope for model or nativeStrict overrides"
+      );
+    }
+    refuseLegacyContainedName(workflow);
+    if (isContainedWorkflowName(workflow)) return this.checkByName(workflow, options.signal);
+    const captured = await this.captureSnapshot(workflow, options.signal, true);
+    if (captured.bytes === void 0) return captured.report;
+    const snapshot = captured.identity;
+    if (!snapshot) {
+      throw this.gap("executionSnapshot", "Local engine omitted execution snapshot identity");
+    }
+    const acknowledged = snapshotAck(await this.json("/v1/check", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: captured.bytes,
+      signal: options.signal
+    }, true, [200], "check"));
+    if (!acknowledged || acknowledged.snapshot_digest !== snapshot.digest || acknowledged.root !== snapshot.root || acknowledged.units !== snapshot.units) {
+      throw new NikaProtocolError(this.kind, "Check admission did not acknowledge the snapshot");
+    }
+    return captured.report;
+  }
+  async startRun(workflow, options) {
+    const inputs = literalInputs(options);
+    if (options.vars && Object.keys(options.vars).length > 0 || options.model !== void 0 || options.maxCostUsd !== void 0) {
+      throw this.gap(
+        "runOptions",
+        "nika serve admission has no request envelope for vars, model, or maxCostUsd; literal workflow values ride inputs, and vars is the native --var operator channel"
+      );
+    }
+    refuseLegacyContainedName(workflow);
+    const byName = isContainedWorkflowName(workflow);
+    if (inputs && !byName) {
+      throw this.gap(
+        "snapshotInputs",
+        "An execution snapshot freezes its inputs and takes no request overlay; run({ inputs }) over HTTP binds a workflow by its served name (listWorkflows())"
+      );
+    }
+    const idempotencyKey = options.idempotencyKey;
+    if (idempotencyKey === void 0) {
+      throw new NikaConfigurationError(
+        "HTTP run() requires a caller-owned idempotencyKey; reuse the same key and request when retrying an uncertain admission"
+      );
+    }
+    if (Buffer.byteLength(idempotencyKey) < 1 || Buffer.byteLength(idempotencyKey) > 255) {
+      throw new NikaTransportError(this.kind, "Idempotency-Key must be 1-255 bytes");
+    }
+    if (byName) {
+      await this.ensureServerIdentity();
+      if (inputs) this.requireJobInputs();
+      const body = inputs ? `{"workflow":${JSON.stringify(workflow)},"inputs":${inputs.json}}` : JSON.stringify({ workflow });
+      const job2 = await this.admitJob(body, idempotencyKey);
+      return this.httpRun(job2.id, 0, job2);
+    }
+    const captured = await this.captureSnapshot(workflow);
+    if (captured.bytes === void 0) {
+      throw this.gap("executionSnapshot", "Local workflow check was not clean; run was not admitted");
+    }
+    if (!captured.identity) {
+      throw this.gap("executionSnapshot", "Local engine omitted execution snapshot identity");
+    }
+    const job = await this.admitJob(captured.bytes, idempotencyKey);
+    return this.httpRun(job.id, 0, job, captured.identity.digest);
+  }
+  /**
+   * The by-name form of `POST /v1/check` (ADR-131): the resident captures
+   * the world of a workflow its registry lists and answers the compact
+   * acknowledgement; nothing is hashed or spawned here. A refusal that
+   * judges the workflow is a red result, as it is on the native transport:
+   * 404 (the name is not served) and 422 (the capture or admission refused
+   * it). Authorization, deadline, envelope and availability refusals still
+   * throw, because they judge the request, not the workflow.
+   */
+  async checkByName(workflow, signal) {
+    await this.ensureServerIdentity();
+    const outcome = await this.jsonOutcome("/v1/check", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ workflow }),
+      signal
+    }, true, [200], "check", true);
+    if ("refusal" in outcome) {
+      if (!WORKFLOW_REFUSAL_STATUSES.has(outcome.status)) throw this.refused("/v1/check", outcome);
+      return { clean: false, error: outcome.refusal };
+    }
+    const acknowledged = snapshotAck(outcome.object);
+    if (!acknowledged) {
+      throw new NikaProtocolError(this.kind, "Check admission did not acknowledge the workflow");
+    }
+    return { clean: true, ...acknowledged };
+  }
+  async admitJob(body, idempotencyKey) {
+    const admitted = await this.json("/v1/jobs", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Idempotency-Key": idempotencyKey
+      },
+      body
+    }, true, [200, 202], "run");
+    const id = typeof admitted.id === "string" ? admitted.id : void 0;
+    if (!id) {
+      throw new NikaProtocolError(this.kind, "Job admission response omitted its id");
+    }
+    return durableJob(admitted, id, this.kind);
+  }
+  async attachRun(id, options) {
+    await this.ensureServerIdentity();
+    const object = await this.json(`/v1/jobs/${encodeURIComponent(id)}`, {
+      method: "GET",
+      headers: { Accept: "application/json" }
+    }, true, [200], "attachRun");
+    const durable = durableJob(object, id, this.kind);
+    return this.httpRun(id, options.lastEventId ?? 0, durable);
+  }
+  async listWorkflows() {
+    await this.ensureServerIdentity();
+    const object = await this.json("/v1/workflows", {
+      method: "GET",
+      headers: { Accept: "application/json" }
+    }, true, [200], "listWorkflows");
+    if (Object.keys(object).some((key) => key !== "workflows") || !Array.isArray(object.workflows) || object.workflows.some((name) => !isContainedWorkflowName(name)) || new Set(object.workflows).size !== object.workflows.length) {
+      throw new NikaProtocolError(this.kind, "Workflow catalog response was malformed");
+    }
+    return Object.freeze([...object.workflows]);
+  }
+  async workflow(name) {
+    refuseLegacyContainedName(name);
+    await this.ensureServerIdentity();
+    const object = await this.json(`/v1/workflows/${workflowPath(name)}`, {
+      method: "GET",
+      headers: { Accept: "application/json" }
+    }, true, [200], "workflow");
+    if (Object.keys(object).some((key) => key !== "workflow") || !isContainedWorkflowName(object.workflow) || object.workflow !== name) {
+      throw new NikaProtocolError(this.kind, "Workflow metadata response was malformed");
+    }
+    return object;
+  }
+  async schedule(workflow, options) {
+    refuseLegacyContainedName(workflow);
+    await this.ensureScheduleCapability();
+    const path3 = `/v1/schedules/${encodeURIComponent(options.id)}`;
+    const headers = new Headers({ "Content-Type": "application/json" });
+    if (options.revision === void 0) {
+      headers.set("If-None-Match", "*");
+    } else {
+      headers.set("If-Match", `"${options.revision}"`);
+    }
+    const object = await this.operationJson("schedule", path3, {
+      method: "PUT",
+      headers,
+      body: JSON.stringify(scheduleBody(workflow, options))
+    });
+    if (object.applied !== true || typeof object.changed !== "boolean" || !scheduleStatusProjection(object.status)) {
+      throw new NikaProtocolError(this.kind, "Schedule apply response was not an acknowledgement");
+    }
+    return object;
+  }
+  async scheduleStatus(id) {
+    await this.ensureScheduleCapability();
+    const path3 = `/v1/schedules/${encodeURIComponent(id)}`;
+    const object = await this.operationJson("scheduleStatus", path3, {
+      method: "GET",
+      headers: { Accept: "application/json" }
+    });
+    if (!scheduleStatusProjection(object)) {
+      throw new NikaProtocolError(this.kind, "Schedule status response omitted machine fields");
+    }
+    return object;
+  }
+  async traceVerify(receipt, options) {
+    await this.ensureServerIdentity();
+    const jobId2 = receipt.job_id;
+    if (typeof jobId2 !== "string" || jobId2.length === 0) {
+      throw this.gap("traceVerify", "The engine receipt does not carry a remote job_id");
+    }
+    const object = await this.json(
+      `/v1/jobs/${encodeURIComponent(jobId2)}/trace/verify`,
+      { method: "GET", signal: options.signal },
+      true,
+      [200],
+      "traceVerify"
+    );
+    if (typeof object.verdict !== "string" || object.reason !== void 0 && typeof object.reason !== "string" || object.trace_id !== void 0 && typeof object.trace_id !== "string") {
+      throw new NikaProtocolError(this.kind, "Trace verification verdict was malformed");
+    }
+    const traceBound = typeof object.trace_id === "string" && object.trace_id === receipt.trace_id;
+    return {
+      ...object,
+      verified: POSITIVE_TRACE_VERDICTS.has(object.verdict.toUpperCase()) && traceBound
+    };
+  }
+  httpRun(id, initialSequence = 0, attachedState, expectedSnapshotDigest) {
+    const controller = new AbortController();
+    let terminalObserved = false;
+    let resolveDone;
+    let rejectDone;
+    const done = new Promise((resolve, reject) => {
+      resolveDone = resolve;
+      rejectDone = reject;
+    });
+    done.catch(() => {
+    });
+    const settle = (source) => {
+      const event = "sequence" in source ? source : void 0;
+      const durable = event ? void 0 : source;
+      const receipt = event ? eventReceipt(event) : durable?.receipt;
+      if (durable?.execution_id !== void 0 && attachedState?.execution_id !== void 0 && durable.execution_id !== attachedState.execution_id) {
+        throw new NikaProtocolError(this.kind, "Durable execution identity changed after attach");
+      }
+      if (durable?.trace_id !== void 0 && attachedState?.trace_id !== void 0 && durable.trace_id !== attachedState.trace_id) {
+        throw new NikaProtocolError(this.kind, "Durable trace identity changed after attach");
+      }
+      const knownExecutionId = attachedState?.execution_id ?? durable?.execution_id;
+      const knownTraceId = attachedState?.trace_id ?? durable?.trace_id;
+      if (receipt) {
+        assertReceiptIdentity(
+          receipt,
+          id,
+          this.kind,
+          knownExecutionId,
+          knownTraceId,
+          expectedSnapshotDigest
+        );
+      }
+      const executionId = knownExecutionId ?? (typeof receipt?.execution_id === "string" ? receipt.execution_id : void 0);
+      const traceId = knownTraceId ?? (typeof receipt?.trace_id === "string" ? receipt.trace_id : void 0);
+      terminalObserved = true;
+      const outputs = event ? eventOutputs(event) : durable?.outputs;
+      const error = event ? eventError(event) : durable?.settlement?.error ?? durable?.error;
+      const settlement = event ? eventSettlement(event, this.kind) : durable?.settlement;
+      const evidence = event ? eventEvidence(event, this.kind) : durable?.evidence;
+      resolveDone({
+        id,
+        status: source.status,
+        transport: this.kind,
+        ...executionId ? { execution_id: executionId } : {},
+        ...traceId ? { trace_id: traceId } : {},
+        ...outputs ? { outputs } : {},
+        ...receipt ? { receipt } : {},
+        ...error ? { error } : {},
+        ...settlement ? { settlement } : {},
+        ...evidence ? { evidence } : {}
+      });
+    };
+    if (attachedState && isObservationEnded(attachedState)) settle(attachedState);
+    const events = {
+      [Symbol.asyncIterator]: async function* () {
+        try {
+          for await (const event of this.observeJob(
+            id,
+            controller.signal,
+            settle,
+            initialSequence
+          )) {
+            yield event;
+          }
+        } catch (cause) {
+          const error = cause instanceof Error ? cause : new NikaTransportError(this.kind, String(cause));
+          if (terminalObserved && controller.signal.aborted) return;
+          if (!terminalObserved) rejectDone(error);
+          throw error;
+        }
+      }.bind(this)
+    };
+    return {
+      id,
+      events,
+      done,
+      status: async () => {
+        const object = await this.json(`/v1/jobs/${encodeURIComponent(id)}/status`, {
+          method: "GET",
+          headers: { Accept: "application/json" }
+        }, true, [200], "status");
+        if (typeof object.status !== "string" || !JOB_STATUSES.has(object.status)) {
+          throw new NikaProtocolError(this.kind, "Job status response was malformed");
+        }
+        return object.status;
+      },
+      cancel: async () => {
+        const { object, status } = await this.jsonWithStatus(
+          `/v1/jobs/${encodeURIComponent(id)}/cancel`,
+          { method: "POST" },
+          true,
+          [200, 202],
+          "cancel"
+        );
+        const durable = durableJob(object, id, this.kind);
+        if (status === 202) {
+          if (isExecutionTerminal(durable.status)) {
+            throw new NikaProtocolError(this.kind, "Pending cancellation returned a terminal job");
+          }
+          return {
+            runId: id,
+            accepted: true,
+            status: "cancellation_requested",
+            transport: this.kind
+          };
+        }
+        if (durable.status !== "paused" && !isExecutionTerminal(durable.status)) {
+          throw new NikaProtocolError(this.kind, "Cancellation did not return an ended observation");
+        }
+        settle(durable);
+        const accepted = durable.status === "cancelled";
+        return {
+          runId: id,
+          accepted,
+          status: accepted ? "cancelled" : "already_settled",
+          transport: this.kind
+        };
+      },
+      cleanup: async () => {
+        controller.abort();
+      }
+    };
+  }
+  async *observeJob(id, signal, settle, initialSequence = 0) {
+    const state = {
+      lastSequence: initialSequence,
+      attempt: 0,
+      terminalObserved: false
+    };
+    const jobPath = `/v1/jobs/${encodeURIComponent(id)}`;
+    const eventsPath = `/v1/jobs/${encodeURIComponent(id)}/events`;
+    const settlement = { jobPath, id, settle };
+    while (!state.terminalObserved) {
+      const headers = new Headers({ Accept: "text/event-stream" });
+      if (state.lastSequence > 0) headers.set("Last-Event-ID", String(state.lastSequence));
+      let response;
+      try {
+        response = await this.observationRequest(eventsPath, { headers, signal });
+      } catch {
+        await this.retryObservation(state, signal, {
+          retry: true
+        }, settlement);
+        continue;
+      }
+      if (response.status === 404) {
+        await discardResponse(response);
+        const durable2 = await this.inspectDurableJob(jobPath, id, signal);
+        if (isRetryObservation(durable2)) {
+          await this.retryObservation(state, signal, durable2, settlement);
+          continue;
+        }
+        if (isObservationEnded(durable2)) {
+          state.terminalObserved = true;
+          settle(durable2);
+          return;
+        }
+        await this.retryObservation(state, signal, { retry: true }, settlement);
+        continue;
+      }
+      if (isRetryableStatus(response.status)) {
+        const retryAfterMilliseconds = retryAfter(response.headers.get("Retry-After"));
+        await discardResponse(response);
+        await this.retryObservation(state, signal, {
+          retry: true,
+          ...retryAfterMilliseconds !== void 0 ? { retryAfterMilliseconds } : {}
+        }, settlement);
+        continue;
+      }
+      this.assertObservationResponse(response, eventsPath, "text/event-stream");
+      const body = response.body;
+      if (!body) {
+        throw new NikaProtocolError(this.kind, "SSE event response omitted its body");
+      }
+      try {
+        const limits = this.sseLimits();
+        for await (const frame of decodeSse(body, limits, signal)) {
+          if (frame.retry !== void 0) {
+            state.serverRetryMilliseconds = boundedDelay(frame.retry);
+          }
+          if (frame.data === void 0) continue;
+          const event = this.nikaEvent(id, frame.id, frame.data);
+          const sequence = event.sequence;
+          if (sequence === state.lastSequence) {
+            if (frame.data === state.lastData) continue;
+            throw new NikaProtocolError(
+              this.kind,
+              `SSE sequence ${sequence} replayed with different data`
+            );
+          }
+          if (sequence !== state.lastSequence + 1) {
+            const relation = sequence > state.lastSequence ? "gap" : "out-of-order replay";
+            throw new NikaProtocolError(
+              this.kind,
+              `SSE ${relation}: expected sequence ${state.lastSequence + 1}, received ${sequence}`
+            );
+          }
+          state.lastSequence = sequence;
+          state.lastData = frame.data;
+          state.attempt = 0;
+          if (isObservationEnded(event)) {
+            state.terminalObserved = true;
+            settle(event);
+          }
+          yield event;
+          if (state.terminalObserved) return;
+        }
+      } catch (cause) {
+        if (cause instanceof SseParseError) {
+          throw new NikaProtocolError(this.kind, cause.message, { cause });
+        }
+        if (cause instanceof NikaProtocolError) throw cause;
+      }
+      const durable = await this.inspectDurableJob(jobPath, id, signal);
+      if (isRetryObservation(durable)) {
+        await this.retryObservation(state, signal, durable, settlement);
+        continue;
+      }
+      if (isObservationEnded(durable)) {
+        state.terminalObserved = true;
+        settle(durable);
+        return;
+      }
+      await this.retryObservation(state, signal, { retry: true }, settlement);
+    }
+  }
+  nikaEvent(jobId2, id, data) {
+    if (!id || !/^[1-9]\d*$/.test(id)) {
+      throw new NikaProtocolError(
+        this.kind,
+        "SSE event id must be a canonical positive decimal sequence"
+      );
+    }
+    const sequence = Number(id);
+    if (!Number.isSafeInteger(sequence)) {
+      throw new NikaProtocolError(this.kind, "SSE event id exceeded the safe integer range");
+    }
+    let value;
+    try {
+      value = JSON.parse(data);
+    } catch (cause) {
+      throw new NikaProtocolError(this.kind, "SSE data was not valid JSON", {
+        cause: cause instanceof Error ? cause : void 0
+      });
+    }
+    const event = machineObject(value);
+    if (!event) throw new NikaProtocolError(this.kind, "SSE data was not an object");
+    const allowed = /* @__PURE__ */ new Set([
+      "sequence",
+      "at",
+      "kind",
+      "status",
+      "code",
+      "message",
+      "outputs",
+      "receipt",
+      "settlement",
+      "evidence"
+    ]);
+    if (Object.keys(event).some((key) => !allowed.has(key))) {
+      throw new NikaProtocolError(this.kind, "SSE data contained fields outside the public projection");
+    }
+    if (event.sequence !== sequence) {
+      throw new NikaProtocolError(
+        this.kind,
+        `SSE id ${id} did not equal JSON data.sequence`
+      );
+    }
+    if (!Object.hasOwn(event, "kind") || event.kind !== null && typeof event.kind !== "string") {
+      throw new NikaProtocolError(this.kind, "SSE data.kind was not a string or null");
+    }
+    if (!Object.hasOwn(event, "status") || event.status !== null && (typeof event.status !== "string" || !JOB_STATUSES.has(event.status))) {
+      throw new NikaProtocolError(this.kind, "SSE data.status was not a known job status or null");
+    }
+    for (const field of ["code", "message"]) {
+      if (event[field] !== void 0 && typeof event[field] !== "string") {
+        throw new NikaProtocolError(this.kind, `SSE data.${field} was not a string`);
+      }
+    }
+    if (event.at !== void 0 && (typeof event.at !== "string" || !isCanonicalTimestamp(event.at))) {
+      throw new NikaProtocolError(this.kind, "SSE data.at was not an RFC 3339 timestamp");
+    }
+    if (event.evidence !== void 0) journalEvidence(event.evidence, this.kind, "SSE data.evidence");
+    if (event.outputs !== void 0 && !machineObject(event.outputs)) {
+      throw new NikaProtocolError(this.kind, "SSE data.outputs was not an object");
+    }
+    if (event.settlement !== void 0) {
+      readSettlement(
+        event.settlement,
+        this.kind,
+        typeof event.status === "string" ? event.status : void 0
+      );
+    }
+    if (event.receipt !== void 0) {
+      const receipt = machineObject(event.receipt);
+      if (!receipt) {
+        throw new NikaProtocolError(this.kind, "SSE data.receipt was not an object");
+      }
+      assertReceiptIdentity(receipt, jobId2, this.kind);
+    }
+    return event;
+  }
+  async inspectDurableJob(path3, expectedId, signal) {
+    let response;
+    try {
+      response = await this.observationRequest(path3, { headers: { Accept: "application/json" }, signal });
+    } catch {
+      return { retry: true };
+    }
+    if (response.status === 404) {
+      await discardResponse(response);
+      throw new NikaTransportError(this.kind, `HTTP 404 for ${path3}; job was durably absent`);
+    }
+    if (isRetryableStatus(response.status)) {
+      const retryAfterMilliseconds = retryAfter(response.headers.get("Retry-After"));
+      await discardResponse(response);
+      return {
+        retry: true,
+        ...retryAfterMilliseconds !== void 0 ? { retryAfterMilliseconds } : {}
+      };
+    }
+    this.assertObservationResponse(response, path3, "application/json");
+    try {
+      const object = await this.readObservationObject(response, path3);
+      return durableJob(object, expectedId, this.kind);
+    } catch (cause) {
+      if (cause instanceof NikaTransportError && !(cause instanceof NikaProtocolError)) {
+        return { retry: true };
+      }
+      throw cause;
+    }
+  }
+  assertObservationResponse(response, path3, contentType) {
+    if (response.status === 204) {
+      void discardResponse(response);
+      throw new NikaProtocolError(this.kind, `HTTP 204 permanently stopped observation for ${path3}`);
+    }
+    if (response.status === 401 || response.status === 403) {
+      void discardResponse(response);
+      throw new NikaTransportError(this.kind, `HTTP ${response.status} authorization failure for ${path3}`);
+    }
+    if (response.status !== 200) {
+      void discardResponse(response);
+      throw new NikaTransportError(this.kind, `HTTP ${response.status} permanently failed ${path3}`);
+    }
+    const actual = response.headers.get("Content-Type")?.split(";", 1)[0]?.trim().toLowerCase();
+    if (actual !== contentType) {
+      void discardResponse(response);
+      throw new NikaProtocolError(
+        this.kind,
+        `HTTP ${path3} returned an invalid content-type`
+      );
+    }
+  }
+  async readObservationObject(response, path3, signal) {
+    if (!response.body) {
+      throw new NikaProtocolError(this.kind, `HTTP ${path3} omitted its JSON body`);
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytes = 0;
+    let rejectBoundary;
+    const boundary = new Promise((_resolve, reject) => {
+      rejectBoundary = reject;
+    });
+    const abort = () => {
+      rejectBoundary(new NikaTransportError(this.kind, `HTTP ${path3} response body was aborted`));
+      void reader.cancel().catch(() => {
+      });
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(() => {
+      rejectBoundary(new NikaTransportError(
+        this.kind,
+        `HTTP response body timed out after ${this.options.requestTimeout}ms`
+      ));
+      void reader.cancel().catch(() => {
+      });
+    }, this.options.requestTimeout);
+    try {
+      if (signal?.aborted) abort();
+      while (true) {
+        const { done, value: value2 } = await Promise.race([reader.read(), boundary]);
+        if (done) break;
+        bytes += value2.byteLength;
+        if (bytes > this.options.machineBufferBytes) {
+          throw new NikaProtocolError(
+            this.kind,
+            `HTTP ${path3} JSON exceeded ${this.options.machineBufferBytes} bytes`
+          );
+        }
+        chunks.push(value2);
+      }
+    } catch (cause) {
+      if (cause instanceof NikaProtocolError) throw cause;
+      throw new NikaTransportError(this.kind, `HTTP ${path3} response body reset`);
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      await reader.cancel().catch(() => {
+      });
+      reader.releaseLock();
+    }
+    const body = new Uint8Array(bytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+      body.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    let text;
+    try {
+      text = new TextDecoder("utf-8", { fatal: true }).decode(body);
+    } catch (cause) {
+      throw new NikaProtocolError(this.kind, `HTTP ${path3} JSON was not valid UTF-8`, {
+        cause: cause instanceof Error ? cause : void 0
+      });
+    }
+    let value;
+    try {
+      value = JSON.parse(text);
+    } catch (cause) {
+      throw new NikaProtocolError(this.kind, `HTTP ${path3} did not return valid JSON`, {
+        cause: cause instanceof Error ? cause : void 0
+      });
+    }
+    const object = machineObject(value);
+    if (!object) throw new NikaProtocolError(this.kind, `HTTP ${path3} did not return an object`);
+    return object;
+  }
+  async observationRequest(path3, init, withTimeout = true) {
+    const controller = withTimeout ? new AbortController() : void 0;
+    const timer = controller ? setTimeout(() => controller.abort(), this.options.requestTimeout) : void 0;
+    const callerSignal = init.signal;
+    const abort = () => controller?.abort(callerSignal?.reason);
+    callerSignal?.addEventListener("abort", abort, { once: true });
+    const headers = new Headers(init.headers);
+    headers.set("Authorization", `Bearer ${this.options.token}`);
+    try {
+      return await this.options.fetch(`${this.options.url}${path3}`, {
+        ...init,
+        headers,
+        signal: controller?.signal ?? callerSignal
+      });
+    } catch {
+      if (controller?.signal.aborted && !callerSignal?.aborted) {
+        throw new NikaTransportError(
+          this.kind,
+          `HTTP observation timed out after ${this.options.requestTimeout}ms`
+        );
+      }
+      throw new NikaTransportError(this.kind, "HTTP observation transport failed");
+    } finally {
+      if (timer) clearTimeout(timer);
+      callerSignal?.removeEventListener("abort", abort);
+    }
+  }
+  async retryObservation(state, signal, retry, settlement) {
+    if (state.attempt >= MAX_OBSERVATION_RETRIES) {
+      const durable = await this.inspectDurableJob(
+        settlement.jobPath,
+        settlement.id,
+        signal
+      );
+      if (!isRetryObservation(durable) && isObservationEnded(durable)) {
+        state.terminalObserved = true;
+        settlement.settle(durable);
+        return;
+      }
+      throw new NikaObservationInterrupted(
+        this.kind,
+        settlement.id,
+        state.lastSequence,
+        state.attempt
+      );
+    }
+    state.attempt += 1;
+    const exponential = Math.min(
+      RETRY_BASE_MILLISECONDS * 2 ** (state.attempt - 1),
+      RETRY_MAX_MILLISECONDS
+    );
+    const milliseconds = retry.retryAfterMilliseconds ?? state.serverRetryMilliseconds ?? exponential;
+    await (this.options.retryDelay ?? abortableDelay)(boundedDelay(milliseconds), signal);
+  }
+  sseLimits() {
+    return {
+      maxLineBytes: this.options.machineBufferBytes,
+      maxFrameBytes: this.options.machineBufferBytes,
+      maxBufferBytes: this.options.machineBufferBytes
+    };
+  }
+  gap(capability, message) {
+    return new NikaCompatibilityError(capability, this.kind, message);
+  }
+  ensureServerIdentity() {
+    this.serverIdentity ??= this.probeServerIdentity();
+    return this.serverIdentity;
+  }
+  async probeServerIdentity() {
+    const health = await this.json("/health", { method: "GET" }, false);
+    if (health.status !== "ok" || health.service !== "nika-serve") {
+      throw new NikaCompatibilityError(
+        "engineIdentity",
+        this.kind,
+        "GET /health did not identify a live nika-serve engine"
+      );
+    }
+    this.remoteIdentity = compatibleEngineIdentity(health, this.kind);
+    return this.remoteIdentity;
+  }
+  ensureLocalEngine() {
+    this.localIdentity ??= this.verifyLocalEngine();
+    return this.localIdentity;
+  }
+  localEngine() {
+    this.resolvedEngine ??= this.options.resolveEngine();
+    return this.resolvedEngine;
+  }
+  async verifyLocalEngine() {
+    const local = await verifyNikaEngine(this.localEngine());
+    const remote = await this.ensureServerIdentity();
+    compatibleEngineIdentity(remote, this.kind, local);
+    return local;
+  }
+  async ensureScheduleCapability() {
+    await this.ensureServerIdentity();
+    if (!this.remoteIdentity?.supportedCapabilities.includes("schedule")) {
+      throw this.gap(
+        "schedule",
+        "The connected nika serve process did not advertise resident schedule authority"
+      );
+    }
+  }
+  /**
+   * The resident must advertise named-input admission before a map is sent
+   * (nika#1642). A resident from before the envelope answered 202 to an extra
+   * `inputs` field and applied nothing, so an accepted POST negotiates nothing:
+   * only the capability `/health` advertised does. Called after
+   * `ensureServerIdentity()`.
+   */
+  requireJobInputs() {
+    const identity = this.remoteIdentity;
+    if (identity?.supportedCapabilities.includes(JOB_INPUTS)) return;
+    throw this.gap(
+      JOB_INPUTS,
+      `The connected nika serve ${identity?.engineVersion ?? "(unidentified)"} does not advertise ${JOB_INPUTS} (advertised: ${identity?.supportedCapabilities.join(", ") ?? "nothing"}); run({ inputs }) needs a resident that binds declared inputs by name. Nothing was posted: an older resident accepts the field and ignores its values`
+    );
+  }
+  async captureSnapshot(workflow, signal, teach = false) {
+    const identity = await this.ensureLocalEngine();
+    const captured = await captureEngine(
+      this.localEngine().bin,
+      ["check", workflow, "--json", "--sdk-snapshot"],
+      {
+        cwd: this.options.cwd,
+        signal,
+        bufferBytes: this.options.machineBufferBytes,
+        transport: this.kind,
+        label: "SDK snapshot capture"
+      }
+    );
+    let outer;
+    try {
+      outer = JSON.parse(captured.stdout.trim());
+    } catch (cause) {
+      throw new NikaCompatibilityError(
+        "executionSnapshot",
+        this.kind,
+        `Local engine did not emit the required snapshot report (exit ${captured.exitCode})`
+      );
+    }
+    const report = { ...outer, exitCode: captured.exitCode };
+    delete report.execution_snapshot;
+    if (captured.exitCode !== 0 || outer.clean !== true) {
+      report.clean = false;
+      if (teach && !Array.isArray(outer.findings)) {
+        return { report: await this.teachingReport(workflow, report, signal) };
+      }
+      return { report };
+    }
+    compatibleEngineIdentity(outer, this.kind, identity);
+    if (outer.engineVersion !== identity.engineVersion || outer.report_version !== identity.checkReportVersion) {
+      throw this.gap(
+        "executionSnapshot",
+        "Local snapshot report identity changed after the engine probe"
+      );
+    }
+    if (captured.stderr.trim()) {
+      throw this.gap("executionSnapshot", "Local snapshot capture wrote unexpected diagnostics");
+    }
+    const bytes = outer.execution_snapshot;
+    if (typeof bytes !== "string" || bytes.length === 0) {
+      throw this.gap("executionSnapshot", "Local engine omitted execution_snapshot bytes");
+    }
+    return {
+      report,
+      bytes,
+      identity: snapshotIdentity(bytes, this.kind)
+    };
+  }
+  /**
+   * A red workflow has no exportable snapshot, so the capture returns one
+   * error line and no findings. Ask the same local engine for its plain
+   * teaching report, so `findings[]` reads the same on both transports. The
+   * refused capture line is preserved as `snapshot_error` rather than
+   * overwriting whatever the engine put in `error`. No bytes leave the
+   * machine on this path: the caller still sees `clean: false`.
+   */
+  async teachingReport(workflow, refused, signal) {
+    const captured = await captureEngine(
+      this.localEngine().bin,
+      ["check", workflow, "--json"],
+      {
+        cwd: this.options.cwd,
+        signal,
+        bufferBytes: this.options.machineBufferBytes,
+        transport: this.kind,
+        label: "SDK teaching check"
+      }
+    );
+    let parsed;
+    try {
+      parsed = JSON.parse(captured.stdout.trim());
+    } catch {
+      return refused;
+    }
+    const plain = machineObject(parsed);
+    if (!plain) return refused;
+    const report = {
+      ...plain,
+      clean: false,
+      exitCode: captured.exitCode,
+      ...refused.error === void 0 ? {} : { snapshot_error: refused.error }
+    };
+    delete report.execution_snapshot;
+    return report;
+  }
+  async json(path3, init, authenticated = true, acceptedStatuses = [200], operation) {
+    const { object } = await this.jsonWithStatus(
+      path3,
+      init,
+      authenticated,
+      acceptedStatuses,
+      operation
+    );
+    return object;
+  }
+  /**
+   * The JSON object an accepted status carries, with that status, for the
+   * routes whose accepted statuses mean different things (cancel: 200 is a
+   * settled job, 202 an accepted request).
+   */
+  async jsonWithStatus(path3, init, authenticated, acceptedStatuses, operation) {
+    const outcome = await this.jsonOutcome(path3, init, authenticated, acceptedStatuses, operation);
+    if ("refusal" in outcome) throw this.refused(path3, outcome);
+    return outcome;
+  }
+  async jsonOutcome(path3, init, authenticated, acceptedStatuses, operation, strictRefusal = false) {
+    const response = await this.fetchResponse(path3, init, true, authenticated, false);
+    if (!acceptedStatuses.includes(response.status)) {
+      if (response.ok) {
+        await discardResponse(response);
+        throw new NikaProtocolError(
+          this.kind,
+          `HTTP ${path3} returned non-contract status ${response.status}`
+        );
+      }
+      const refusal = operation === void 0 ? void 0 : await this.readRefusal(response, path3, strictRefusal);
+      if (operation !== void 0 && refusal) {
+        return { operation, status: response.status, refusal };
+      }
+      await discardResponse(response);
+      throw new NikaTransportError(
+        this.kind,
+        `HTTP ${response.status} for ${path3}: [REDACTED]`
+      );
+    }
+    const contentType = response.headers.get("Content-Type")?.split(";", 1)[0]?.trim().toLowerCase();
+    if (contentType !== "application/json") {
+      await discardResponse(response);
+      throw new NikaProtocolError(this.kind, `HTTP ${path3} returned an invalid content-type`);
+    }
+    return {
+      object: await this.readObservationObject(response, path3, init.signal ?? void 0),
+      status: response.status
+    };
+  }
+  refused(path3, outcome) {
+    const { code, message } = outcome.refusal;
+    return new NikaOperationError(
+      outcome.operation,
+      this.kind,
+      code,
+      `HTTP ${outcome.status} for ${path3}: ${code}` + (message ? ` (${message})` : ""),
+      { status: outcome.status, machineCode: code }
+    );
+  }
+  /**
+   * Read a non-2xx body only when the server typed it as an engine refusal.
+   * Anything else (plain text, oversized, malformed, a code that is not a
+   * plain identifier, a code that carries the bearer token) is discarded and
+   * the caller falls back to the redacted transport error.
+   */
+  async readRefusal(response, path3, strict = false) {
+    const contentType = response.headers.get("Content-Type")?.split(";", 1)[0]?.trim().toLowerCase();
+    if (contentType !== "application/json") {
+      await discardResponse(response);
+      return void 0;
+    }
+    let object;
+    try {
+      object = await this.readObservationObject(response, path3);
+    } catch {
+      return void 0;
+    }
+    const error = machineObject(object.error);
+    if (strict && (Object.keys(object).some((key) => key !== "error") || !error || Object.keys(error).some((key) => key !== "code" && key !== "message") || typeof error.message !== "string")) return void 0;
+    const code = error?.code;
+    if (typeof code !== "string" || !/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(code) || code.includes(this.options.token)) {
+      return void 0;
+    }
+    const message = typeof error?.message === "string" && error.message.length > 0 ? this.redact(error.message) : void 0;
+    return { code, ...strict ? { message: this.redact(error?.message) } : message ? { message } : {} };
+  }
+  /** Engine messages are already path-free; a reflected bearer token never survives. */
+  redact(text) {
+    const clean = text.replace(/[\u0000-\u001f\u007f]+/g, " ").split(this.options.token).join("[REDACTED]");
+    return clean.length > 240 ? `${clean.slice(0, 240)}...` : clean;
+  }
+  async operationJson(operation, path3, init) {
+    const response = await this.fetchResponse(path3, init, true, true, false);
+    const contentType = response.headers.get("Content-Type")?.split(";", 1)[0]?.trim().toLowerCase();
+    if (contentType !== "application/json") {
+      await discardResponse(response);
+      throw new NikaProtocolError(this.kind, `HTTP ${path3} returned an invalid content-type`);
+    }
+    const object = await this.readObservationObject(response, path3);
+    if (!response.ok) throw this.operationFailure(operation, response.status, object);
+    return object;
+  }
+  operationFailure(operation, status, object) {
+    if (status === 412 && operation === "schedule") {
+      const machine2 = machineObject(object.error);
+      const currentRevision = machine2?.currentRevision;
+      return new NikaOperationError(
+        operation,
+        this.kind,
+        "schedule_conflict",
+        typeof machine2?.message === "string" ? machine2.message : "Schedule revision conflict",
+        {
+          status,
+          machineCode: typeof machine2?.code === "string" ? machine2.code : void 0,
+          ...typeof currentRevision === "string" || currentRevision === null ? { currentRevision } : {}
+        }
+      );
+    }
+    if (Array.isArray(object.findings)) {
+      const findings = operationFindings(object.findings);
+      if (!findings) {
+        throw new NikaProtocolError(this.kind, "Schedule refusal findings were malformed");
+      }
+      return new NikaOperationError(
+        operation,
+        this.kind,
+        "schedule_refused",
+        "Schedule was refused by the resident authority",
+        { status, findings }
+      );
+    }
+    const machine = machineObject(object.error);
+    if (typeof machine?.code !== "string" || typeof machine.message !== "string") {
+      throw new NikaProtocolError(this.kind, `HTTP ${pathForOperation(operation)} error was malformed`);
+    }
+    return new NikaOperationError(
+      operation,
+      this.kind,
+      machine.code,
+      machine.message,
+      { status, machineCode: machine.code }
+    );
+  }
+  async fetchResponse(path3, init, withTimeout, authenticated = true, requireOk = true) {
+    const controller = withTimeout ? new AbortController() : void 0;
+    const timer = controller ? setTimeout(() => controller.abort(), this.options.requestTimeout) : void 0;
+    const callerSignal = init.signal;
+    const abort = () => controller?.abort(callerSignal?.reason);
+    callerSignal?.addEventListener("abort", abort, { once: true });
+    const headers = new Headers(init.headers);
+    if (authenticated) headers.set("Authorization", `Bearer ${this.options.token}`);
+    try {
+      const response = await this.options.fetch(`${this.options.url}${path3}`, {
+        ...init,
+        headers,
+        signal: controller?.signal ?? callerSignal
+      });
+      if (requireOk && !response.ok) {
+        await discardResponse(response);
+        throw new NikaTransportError(
+          this.kind,
+          `HTTP ${response.status} for ${path3}: [REDACTED]`
+        );
+      }
+      return response;
+    } catch (cause) {
+      if (cause instanceof NikaTransportError) throw cause;
+      if (controller?.signal.aborted && !callerSignal?.aborted) {
+        throw new NikaTransportError(
+          this.kind,
+          `HTTP request timed out after ${this.options.requestTimeout}ms`,
+          { cause: cause instanceof Error ? cause : void 0 }
+        );
+      }
+      throw new NikaTransportError(this.kind, "HTTP transport failed", {
+        cause: cause instanceof Error ? cause : void 0
+      });
+    } finally {
+      if (timer) clearTimeout(timer);
+      callerSignal?.removeEventListener("abort", abort);
+    }
+  }
+};
+function refuseLegacyContainedName(workflow) {
+  if (isRetiredByNameAttempt(workflow)) {
+    throw new NikaConfigurationError(legacyWorkflowRenameMessage(workflow));
+  }
+}
+function workflowPath(name) {
+  const segments = name.split("/");
+  if (name.startsWith("/") || name.includes("\\") || segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+    throw new TypeError("workflow name must be a contained slash-separated path");
+  }
+  return segments.map(encodeURIComponent).join("/");
+}
+function scheduleBody(workflow, options) {
+  return {
+    workflow,
+    when: options.when,
+    maxCostUsd: options.maxCostUsd,
+    missed: options.missed,
+    ...options.maxLatenessSeconds !== void 0 ? { maxLatenessSeconds: options.maxLatenessSeconds } : {},
+    ...options.overlap !== void 0 ? { overlap: options.overlap } : {},
+    ...options.afterSkip !== void 0 ? { afterSkip: options.afterSkip } : {},
+    ...options.jitter !== void 0 ? { jitter: options.jitter } : {},
+    ...options.tolerance !== void 0 ? { tolerance: options.tolerance } : {},
+    ...options.active !== void 0 ? { active: options.active } : {},
+    ...options.pauseReason !== void 0 ? { pauseReason: options.pauseReason } : {},
+    ...options.pauseUntil !== void 0 ? { pauseUntil: options.pauseUntil } : {}
+  };
+}
+function scheduleStatusProjection(value) {
+  const status = machineObject(value);
+  const definition = machineObject(status?.definition);
+  const when = machineObject(definition?.when);
+  const due = machineObject(status?.due);
+  const finding = machineObject(status?.finding);
+  return !!status && !!definition && typeof definition.id === "string" && typeof definition.workflow === "string" && !!when && typeof when.kind === "string" && typeof definition.maxCostUsd === "number" && typeof definition.missed === "string" && (definition.maxLatenessSeconds === null || typeof definition.maxLatenessSeconds === "number") && typeof definition.overlap === "string" && typeof definition.afterSkip === "string" && (definition.jitter === null || typeof definition.jitter === "string") && (definition.tolerance === null || typeof definition.tolerance === "string") && typeof definition.active === "boolean" && (definition.pauseReason === null || typeof definition.pauseReason === "string") && (definition.pauseUntil === null || typeof definition.pauseUntil === "string") && typeof status.origin === "string" && typeof status.revision === "string" && typeof status.active === "boolean" && (status.pause === null || !!machineObject(status.pause)) && Array.isArray(status.next) && status.next.every(scheduleSlotProjection) && (status.earliestWakeHint === null || typeof status.earliestWakeHint === "string") && (status.lastDecision === null || !!machineObject(status.lastDecision)) && (typeof due?.kind === "string" && status.finding === void 0 || status.due === void 0 && scheduleFindingProjection(finding));
+}
+function scheduleSlotProjection(value) {
+  const slot = machineObject(value);
+  return typeof slot?.slotId === "string" && typeof slot.scheduledFor === "string" && (slot.requestedCivil === null || typeof slot.requestedCivil === "string") && typeof slot.shift === "string";
+}
+function scheduleFindingProjection(value) {
+  const finding = machineObject(value);
+  return typeof finding?.code === "string" && typeof finding.detail === "string";
+}
+function operationFindings(values) {
+  const findings = [];
+  for (const value of values) {
+    const finding = machineObject(value);
+    if (typeof finding?.code !== "string" || typeof finding.detail !== "string") {
+      return void 0;
+    }
+    findings.push(finding);
+  }
+  return findings;
+}
+function pathForOperation(operation) {
+  if (operation === "schedule") return "schedule apply";
+  if (operation === "scheduleStatus") return "schedule status";
+  return operation;
+}
+function isObservationEnded(source) {
+  return isExecutionTerminal(source.status) || source.status === "paused" && machineObject(source.settlement)?.status === "paused";
+}
+function isExecutionTerminal(status) {
+  return status === "succeeded" || status === "failed" || status === "interrupted" || status === "cancelled";
+}
+function isRetryableStatus(status) {
+  return status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
+}
+function retryAfter(value) {
+  if (!value) return void 0;
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) {
+    const seconds = Number(trimmed);
+    return Number.isSafeInteger(seconds) ? boundedDelay(seconds * 1e3) : void 0;
+  }
+  const date = Date.parse(trimmed);
+  if (!Number.isFinite(date)) return void 0;
+  return boundedDelay(Math.max(0, date - Date.now()));
+}
+function boundedDelay(milliseconds) {
+  return Math.max(
+    RETRY_MIN_MILLISECONDS,
+    Math.min(Math.floor(milliseconds), RETRY_MAX_MILLISECONDS)
+  );
+}
+function abortableDelay(milliseconds, signal) {
+  if (signal.aborted) return Promise.reject(signal.reason ?? new Error("Observation aborted"));
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(done, milliseconds);
+    function done() {
+      signal.removeEventListener("abort", abort);
+      resolve();
+    }
+    function abort() {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", abort);
+      reject(signal.reason ?? new Error("Observation aborted"));
+    }
+    signal.addEventListener("abort", abort, { once: true });
+  });
+}
+async function discardResponse(response) {
+  await response.body?.cancel().catch(() => {
+  });
+}
+function isRetryObservation(value) {
+  return "retry" in value;
+}
+function durableJob(value, expectedId, transport) {
+  const allowed = /* @__PURE__ */ new Set([
+    "id",
+    "status",
+    "execution_id",
+    "trace_id",
+    "outputs",
+    "receipt",
+    "error",
+    "settlement",
+    "evidence"
+  ]);
+  if (Object.keys(value).some((key) => !allowed.has(key))) {
+    throw new NikaProtocolError(transport, "Durable job response contained unknown fields");
+  }
+  if (value.id !== expectedId || typeof value.status !== "string" || !JOB_STATUSES.has(value.status)) {
+    throw new NikaProtocolError(transport, "Durable job response had an invalid id or status");
+  }
+  for (const field of ["execution_id", "trace_id"]) {
+    if (value[field] !== void 0 && typeof value[field] !== "string") {
+      throw new NikaProtocolError(transport, `Durable job response ${field} was not a string`);
+    }
+  }
+  let error;
+  if (value.error !== void 0) {
+    const object = machineObject(value.error);
+    if (!object || Object.keys(object).some((key) => key !== "code" && key !== "message") || typeof object.code !== "string" || typeof object.message !== "string") {
+      throw new NikaProtocolError(transport, "Durable job response error was malformed");
+    }
+    error = { code: object.code, message: object.message };
+  }
+  const outputs = value.outputs === void 0 ? void 0 : machineObject(value.outputs);
+  const receipt = value.receipt === void 0 ? void 0 : machineObject(value.receipt);
+  const settlement = value.settlement === void 0 ? void 0 : readSettlement(value.settlement, transport, value.status);
+  const evidence = value.evidence === void 0 ? void 0 : journalEvidence(value.evidence, transport, "Durable job response evidence");
+  if (value.outputs !== void 0 && !outputs) {
+    throw new NikaProtocolError(transport, "Durable job response outputs were malformed");
+  }
+  if (value.receipt !== void 0 && !receipt) {
+    throw new NikaProtocolError(transport, "Durable job response receipt was malformed");
+  }
+  if (receipt) {
+    assertReceiptIdentity(
+      receipt,
+      expectedId,
+      transport,
+      typeof value.execution_id === "string" ? value.execution_id : void 0,
+      typeof value.trace_id === "string" ? value.trace_id : void 0
+    );
+  }
+  return {
+    id: value.id,
+    status: value.status,
+    ...typeof value.execution_id === "string" ? { execution_id: value.execution_id } : {},
+    ...typeof value.trace_id === "string" ? { trace_id: value.trace_id } : {},
+    ...outputs ? { outputs } : {},
+    ...receipt ? { receipt: Object.freeze(receipt) } : {},
+    ...error ? { error } : {},
+    ...settlement ? { settlement } : {},
+    ...evidence ? { evidence } : {}
+  };
+}
+var JOURNAL_EVIDENCE_REASONS = /* @__PURE__ */ new Set(["write_failed", "record_refused"]);
+function journalEvidence(value, transport, where) {
+  const evidence = machineObject(value);
+  if (!evidence || Object.keys(evidence).length !== 2 || evidence.status !== "mirror_lost" || typeof evidence.reason !== "string" || !JOURNAL_EVIDENCE_REASONS.has(evidence.reason)) {
+    throw new NikaProtocolError(transport, `${where} was not the resident's journal evidence`);
+  }
+  return Object.freeze({
+    status: "mirror_lost",
+    reason: evidence.reason
+  });
+}
+function eventEvidence(event, transport) {
+  return event.evidence === void 0 ? void 0 : journalEvidence(event.evidence, transport, "SSE data.evidence");
+}
+function assertReceiptIdentity(receipt, expectedJobId, transport, expectedExecutionId, expectedTraceId, expectedSnapshotDigest) {
+  const allowed = /* @__PURE__ */ new Set([
+    "job_id",
+    "execution_id",
+    "trace_id",
+    "snapshot_digest",
+    "origin",
+    "chain_head"
+  ]);
+  if (Object.keys(receipt).some((key) => !allowed.has(key))) {
+    throw new NikaProtocolError(transport, "Receipt contained unknown fields");
+  }
+  if (receipt.job_id !== expectedJobId) {
+    throw new NikaProtocolError(transport, "Receipt job identity did not match its run");
+  }
+  if (typeof receipt.execution_id !== "string" || receipt.execution_id.length === 0) {
+    throw new NikaProtocolError(transport, "Receipt omitted its execution identity");
+  }
+  if (typeof receipt.trace_id !== "string" || receipt.trace_id.length === 0) {
+    throw new NikaProtocolError(transport, "Receipt omitted its trace identity");
+  }
+  if (typeof receipt.snapshot_digest !== "string" || !/^[0-9a-f]{64}$/.test(receipt.snapshot_digest)) {
+    throw new NikaProtocolError(transport, "Receipt omitted its canonical snapshot digest");
+  }
+  if (receipt.chain_head !== void 0 && (typeof receipt.chain_head !== "string" || receipt.chain_head.length === 0)) {
+    throw new NikaProtocolError(transport, "Receipt chain head was malformed");
+  }
+  if (receipt.origin !== void 0) validateReceiptOrigin(receipt.origin, transport);
+  if (expectedExecutionId !== void 0 && receipt.execution_id !== expectedExecutionId) {
+    throw new NikaProtocolError(transport, "Receipt execution identity did not match its job");
+  }
+  if (expectedTraceId !== void 0 && receipt.trace_id !== expectedTraceId) {
+    throw new NikaProtocolError(transport, "Receipt trace identity did not match its job");
+  }
+  if (expectedSnapshotDigest !== void 0 && receipt.snapshot_digest !== expectedSnapshotDigest) {
+    throw new NikaProtocolError(transport, "Receipt snapshot digest did not match its admission");
+  }
+}
+function snapshotAck(value) {
+  const allowed = /* @__PURE__ */ new Set(["status", "snapshot_digest", "root", "units"]);
+  if (Object.keys(value).some((key) => !allowed.has(key)) || value.status !== "accepted" || typeof value.snapshot_digest !== "string" || !/^[0-9a-f]{64}$/.test(value.snapshot_digest) || typeof value.root !== "string" || value.root.length === 0 || typeof value.units !== "number" || !Number.isSafeInteger(value.units) || value.units < 1) {
+    return void 0;
+  }
+  return {
+    status: "accepted",
+    snapshot_digest: value.snapshot_digest,
+    root: value.root,
+    units: value.units
+  };
+}
+function snapshotIdentity(bytes, transport) {
+  let value;
+  try {
+    value = JSON.parse(bytes);
+  } catch (cause) {
+    throw new NikaCompatibilityError(
+      "executionSnapshot",
+      transport,
+      "Local engine emitted malformed execution_snapshot bytes"
+    );
+  }
+  const snapshot = machineObject(value);
+  if (!snapshot || typeof snapshot.digest !== "string" || !/^[0-9a-f]{64}$/.test(snapshot.digest) || typeof snapshot.root !== "string" || snapshot.root.length === 0 || !Array.isArray(snapshot.units) || snapshot.units.length < 1) {
+    throw new NikaCompatibilityError(
+      "executionSnapshot",
+      transport,
+      "Local engine emitted an invalid execution_snapshot identity"
+    );
+  }
+  return { digest: snapshot.digest, root: snapshot.root, units: snapshot.units.length };
+}
+function validateReceiptOrigin(value, transport) {
+  const origin = machineObject(value);
+  if (!origin || typeof origin.kind !== "string") {
+    throw new NikaProtocolError(transport, "Receipt origin was malformed");
+  }
+  if (origin.kind === "manual") {
+    if (Object.keys(origin).some((key) => key !== "kind")) {
+      throw new NikaProtocolError(transport, "Manual receipt origin contained unknown fields");
+    }
+    return;
+  }
+  const required = [
+    "kind",
+    "schedule_origin",
+    "schedule_id",
+    "schedule_revision",
+    "slot_id",
+    "decision",
+    "scheduled_for",
+    "fired_at",
+    "arm_generation"
+  ];
+  if (origin.kind !== "schedule" || Object.keys(origin).some((key) => !required.includes(key)) || required.some((key) => !Object.hasOwn(origin, key)) || !["project", "api"].includes(String(origin.schedule_origin)) || !["scheduled", "catch_up"].includes(String(origin.decision)) || required.slice(2).some((key) => typeof origin[key] !== "string" || origin[key].length === 0) || Buffer.byteLength(String(origin.schedule_id)) > 255 || !/^sha256:[0-9a-f]{64}$/.test(String(origin.schedule_revision)) || !/^[0-9a-f]{64}$/.test(String(origin.slot_id)) || !/^[0-9a-f]{64}$/.test(String(origin.arm_generation)) || !isCanonicalTimestamp(String(origin.scheduled_for)) || !isCanonicalTimestamp(String(origin.fired_at))) {
+    throw new NikaProtocolError(transport, "Scheduled receipt origin was malformed");
+  }
+}
+function isCanonicalTimestamp(value) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|([+-])(\d{2}):(\d{2}))$/.exec(value);
+  if (!match) return false;
+  const [
+    ,
+    yearText,
+    monthText,
+    dayText,
+    hourText,
+    minuteText,
+    secondText,
+    offsetSign,
+    offsetHourText,
+    offsetMinuteText
+  ] = match;
+  const year = Number(yearText);
+  const month = Number(monthText);
+  const day = Number(dayText);
+  const hour = Number(hourText);
+  const minute = Number(minuteText);
+  const second = Number(secondText);
+  const offsetHour = offsetSign ? Number(offsetHourText) : 0;
+  const offsetMinute = offsetSign ? Number(offsetMinuteText) : 0;
+  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return year > 0 && month >= 1 && month <= 12 && day >= 1 && day <= days[month - 1] && hour <= 23 && minute <= 59 && second <= 59 && offsetHour <= 23 && offsetMinute <= 59 && Number.isFinite(Date.parse(value));
+}
+
+// src/lib/native-process-transport.ts
+import { spawn as spawn2 } from "child_process";
+import { randomUUID } from "crypto";
+
+// src/lib/legacy-run-refusals.ts
+var REFUSAL_EXITS = /* @__PURE__ */ new Set([2, 3]);
+var ENGINE_PREFIX = /^nika(?: [a-z-]+)?:\s*/;
+function legacyTeachingLine(line) {
+  const machineCode = leadingCode(line);
+  return machineCode ? { machineCode, message: line } : void 0;
+}
+async function legacyPrettyReport(opening, lines, limit, transport) {
+  if (!opening.startsWith("{")) return void 0;
+  let text = opening;
+  let bytes = Buffer.byteLength(opening);
+  for (; ; ) {
+    const next = await lines.next();
+    if (next.done) break;
+    text += `
+${next.value}`;
+    bytes += Buffer.byteLength(next.value) + 1;
+    if (bytes > limit) {
+      throw new NikaProtocolError(transport, `Native pre-run report exceeded ${limit} bytes`);
+    }
+  }
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return { text };
+  }
+  const frame = machineObject(value);
+  return frame ? { frame, text } : { text };
+}
+function legacyStderrRefusal(stderr, exitCode) {
+  if (!REFUSAL_EXITS.has(exitCode)) return void 0;
+  for (const raw of stderr.split("\n")) {
+    const line = raw.trim().replace(ENGINE_PREFIX, "");
+    const machineCode = leadingCode(line);
+    if (machineCode) return { machineCode, message: line };
+  }
+  return void 0;
+}
+function leadingCode(text) {
+  const code = /^NIKA-[A-Z0-9_-]+/.exec(text)?.[0].replace(/-+$/, "");
+  return code && /\d/.test(code) ? code : void 0;
+}
+
+// src/lib/run-refusal.ts
+var RUN_REFUSED = "run_refused";
+var UNEXPLAINED = "The engine refused this workflow before admission";
+function isRunEvent(frame) {
+  return typeof frame.kind === "string";
+}
+function preRunRefusal(frame, transport) {
+  if (isRunEvent(frame)) return void 0;
+  if (frame.clean === false && Array.isArray(frame.findings)) {
+    return checkRefusal(frame.findings, transport);
+  }
+  const error = machineObject(frame.error);
+  if (!error || typeof error.message !== "string" || error.message.length === 0) {
+    return void 0;
+  }
+  const machineCode = typeof error.code === "string" && error.code.length > 0 ? error.code : void 0;
+  return { ...machineCode ? { machineCode } : {}, message: error.message };
+}
+function runRefusalError(transport, refusal, exitCode) {
+  return new NikaOperationError(
+    "run",
+    transport,
+    refusal.machineCode ?? RUN_REFUSED,
+    refusal.message,
+    {
+      status: exitCode,
+      ...refusal.findings ? { findings: refusal.findings } : {},
+      ...refusal.machineCode ? { machineCode: refusal.machineCode } : {}
+    }
+  );
+}
+function checkRefusal(values, transport) {
+  const findings = [];
+  for (const value of values) {
+    const finding = machineObject(value);
+    if (!finding) {
+      throw new NikaProtocolError(transport, "Pre-run refusal findings were malformed");
+    }
+    findings.push(finding);
+  }
+  const named = findings.find((finding) => typeof finding.code === "string" && finding.code) ?? findings[0];
+  const machineCode = typeof named?.code === "string" && named.code ? named.code : void 0;
+  const said = typeof named?.message === "string" && named.message ? named.message : void 0;
+  const others = findings.length > 1 ? ` (+${findings.length - 1} more findings)` : "";
+  return {
+    ...machineCode ? { machineCode } : {},
+    message: `${[machineCode, said ?? UNEXPLAINED].filter(Boolean).join(" \xB7 ")}${others}`,
+    findings
+  };
+}
+
+// src/lib/native-process-transport.ts
+var NativeProcessTransport = class {
+  constructor(options) {
+    this.options = options;
+  }
+  kind = "native-process";
+  ready;
+  async check(workflow, options) {
+    await this.ensureReady();
+    const args = ["check", workflow, "--json"];
+    if (options.model) args.push("--model", options.model);
+    if (options.nativeStrict) args.push("--native-strict");
+    const captured = await this.capture(args, options.signal);
+    const report = reportObject(captured.stdout) ?? reportObject(stripEnginePrefix(captured.stderr));
+    if (!report) {
+      const excerpt = diagnosticExcerpt(captured.stderr);
+      throw new NikaCompatibilityError(
+        "check",
+        this.kind,
+        `This engine did not emit the required JSON check report (exit ${captured.exitCode})` + (excerpt ? `: ${excerpt}` : "")
+      );
+    }
+    return { ...report, exitCode: captured.exitCode };
+  }
+  async startRun(workflow, options) {
+    const inputs = literalInputs(options);
+    const identity = await this.ensureReady();
+    if (options.idempotencyKey !== void 0) {
+      throw new NikaCompatibilityError(
+        "idempotencyKey",
+        this.kind,
+        "idempotencyKey is an HTTP admission option"
+      );
+    }
+    if (inputs && !identity.supportedCapabilities.includes(INPUTS_LITERAL)) {
+      throw new NikaCompatibilityError(
+        INPUTS_LITERAL,
+        this.kind,
+        `Engine ${identity.engineVersion} at ${this.options.engine.bin} does not advertise ${INPUTS_LITERAL} (advertised: ${identity.supportedCapabilities.join(", ")}); run({ inputs }) needs the literal input channel \`nika run --inputs-json -\`. The SDK never falls back to --var, which reads @env: and coerces by declared type`
+      );
+    }
+    const args = ["run", workflow, "--json", ...runFlags(options, inputs !== void 0)];
+    const spawnOptions = { cwd: this.options.cwd, shell: false };
+    const child = inputs ? spawn2(this.options.engine.bin, args, { ...spawnOptions, stdio: ["pipe", "pipe", "pipe"] }) : spawn2(this.options.engine.bin, args, { ...spawnOptions, stdio: ["ignore", "pipe", "pipe"] });
+    if (inputs && child.stdin) writeLiteralInputs(child.stdin, inputs.json);
+    const engine = this.nativeProcess(child);
+    let first;
+    try {
+      first = await this.admission(engine);
+    } catch (cause) {
+      await engine.stop();
+      throw cause;
+    }
+    return this.processRun(randomUUID(), engine, first);
+  }
+  async attachRun(_id, _options) {
+    throw new NikaCompatibilityError(
+      "attachRun",
+      this.kind,
+      "Only a resident nika serve authority owns durable jobs across client processes"
+    );
+  }
+  async listWorkflows() {
+    throw new NikaCompatibilityError(
+      "workflowCatalog",
+      this.kind,
+      "The contained workflow catalog belongs to a resident nika serve authority"
+    );
+  }
+  async workflow(_name) {
+    throw new NikaCompatibilityError(
+      "workflowCatalog",
+      this.kind,
+      "The contained workflow catalog belongs to a resident nika serve authority"
+    );
+  }
+  async schedule(_workflow, _options) {
+    throw new NikaCompatibilityError(
+      "schedule",
+      this.kind,
+      "A direct native process is not a proven resident schedule authority; connect to nika serve"
+    );
+  }
+  async scheduleStatus(_id) {
+    throw new NikaCompatibilityError(
+      "schedule",
+      this.kind,
+      "A direct native process is not a proven resident schedule authority; connect to nika serve"
+    );
+  }
+  async traceVerify(receipt, options) {
+    await this.ensureReady();
+    const locator = receiptTraceLocator(receipt);
+    if (!locator) {
+      throw new NikaCompatibilityError(
+        "traceVerify",
+        this.kind,
+        "The engine receipt does not carry a native trace locator"
+      );
+    }
+    const captured = await this.capture(["trace", "verify", locator, "--plain"], options.signal);
+    if (captured.exitCode !== 0) {
+      return {
+        verified: false,
+        verdict: "invalid",
+        exitCode: captured.exitCode,
+        output: captured.stdout + captured.stderr
+      };
+    }
+    const evidence = await this.capture(
+      ["trace", "evidence", locator, "--json", "--plain"],
+      options.signal
+    );
+    let manifest;
+    try {
+      manifest = parseMachineObject(evidence.stdout.trim(), this.kind);
+    } catch (cause) {
+      throw new NikaCompatibilityError(
+        "traceVerify",
+        this.kind,
+        `This engine did not emit the required evidence manifest (exit ${evidence.exitCode})`
+      );
+    }
+    const mismatch = receiptMismatch(receipt, manifest);
+    return {
+      verified: mismatch === void 0,
+      // The same vocabulary the HTTP verdict speaks, so a caller reads one
+      // field on both transports instead of inferring it from exitCode.
+      verdict: mismatch === void 0 ? "verified" : "invalid",
+      ...mismatch === void 0 ? {} : { reason: "receipt_mismatch" },
+      exitCode: mismatch === void 0 ? 0 : 2,
+      output: captured.stdout + captured.stderr + (mismatch === void 0 ? "" : `
+RECEIPT MISMATCH: ${mismatch}
+`)
+    };
+  }
+  nativeProcess(child) {
+    let settled = false;
+    let stderr = "";
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => {
+      stderr = boundedAppend(stderr, chunk, this.options.machineBufferBytes);
+    });
+    const closed = new Promise((resolve, reject) => {
+      child.once("error", (cause) => {
+        reject(new NikaTransportError(
+          this.kind,
+          `Cannot spawn ${this.options.engine.bin}: ${cause.message}`,
+          { cause }
+        ));
+      });
+      child.once("close", (code, signal) => {
+        settled = true;
+        resolve(code === null && signal ? 130 : code ?? 3);
+      });
+    });
+    closed.catch(() => {
+    });
+    const lines = machineLines(child.stdout, this.options.machineBufferBytes, this.kind);
+    return {
+      child,
+      lines,
+      closed,
+      settled: () => settled,
+      diagnostics: () => stderr,
+      stop: async () => {
+        void lines.return(void 0).catch(() => {
+        });
+        child.stdin?.destroy();
+        if (settled) return;
+        child.kill("SIGTERM");
+        if (await endsWithin(closed, STOP_GRACE_MILLISECONDS)) return;
+        child.kill("SIGKILL");
+        await endsWithin(closed, STOP_GRACE_MILLISECONDS);
+      }
+    };
+  }
+  /**
+   * The admission law (issue #121): resolve with the run's first event, or
+   * reject before any Run exists. The first machine frame decides. A run
+   * event is the engine's own admission evidence; an object without a `kind`
+   * is its one pre-run refusal object; anything else proves neither and stays
+   * a protocol fault. The SDK reads which one the engine wrote and judges
+   * nothing itself.
+   */
+  async admission(engine) {
+    const { lines } = engine;
+    const kind = this.kind;
+    const opening = await lines.next();
+    if (opening.done) {
+      const exitCode2 = await engine.closed;
+      const taught = legacyStderrRefusal(engine.diagnostics(), exitCode2);
+      if (taught) throw runRefusalError(kind, taught, exitCode2);
+      throw new NikaProtocolError(kind, quoted(
+        `Engine exited without a machine frame (exit ${exitCode2})`,
+        engine.diagnostics()
+      ));
+    }
+    const line = opening.value;
+    let frame;
+    let unreadable;
+    try {
+      frame = parseMachineObject(line, kind);
+    } catch (cause) {
+      unreadable = cause;
+    }
+    let text = line;
+    let refusal;
+    if (frame) {
+      if (isRunEvent(frame)) return frame;
+      refusal = preRunRefusal(frame, kind);
+    } else {
+      refusal = legacyTeachingLine(line);
+      if (!refusal) {
+        const report = await legacyPrettyReport(
+          line,
+          lines,
+          this.options.machineBufferBytes,
+          kind
+        );
+        text = report?.text ?? line;
+        if (!report?.frame) throw quotedProtocolError(unreadable, text, kind);
+        refusal = preRunRefusal(report.frame, kind);
+      }
+    }
+    if (!refusal) {
+      throw new NikaProtocolError(kind, quoted(
+        "The first machine frame was neither a run event nor a pre-run refusal object",
+        text
+      ));
+    }
+    const extra = await lines.next();
+    if (!extra.done) {
+      throw new NikaProtocolError(kind, quoted(
+        "Engine wrote more machine output after its pre-run refusal",
+        extra.value
+      ));
+    }
+    const exitCode = await engine.closed;
+    if (exitCode === 0) {
+      throw new NikaProtocolError(kind, quoted(
+        "Engine wrote a pre-run refusal but exited 0",
+        refusal.message
+      ));
+    }
+    throw runRefusalError(kind, refusal, exitCode);
+  }
+  processRun(id, engine, first) {
+    const { child, lines, closed } = engine;
+    let lastEvent;
+    let receipt;
+    let outputs;
+    let machineError;
+    let settlement;
+    let streamError;
+    let resolveDrained;
+    const drained = new Promise((resolve) => {
+      resolveDrained = resolve;
+    });
+    const kind = this.kind;
+    const observe = (event) => {
+      lastEvent = event;
+      receipt = eventReceipt(event) ?? receipt;
+      outputs = eventOutputs(event) ?? outputs;
+      const currentSettlement = eventSettlement(event, kind);
+      machineError = currentSettlement ? eventError(event) : eventError(event) ?? machineError;
+      settlement = currentSettlement ?? settlement;
+      return event;
+    };
+    const events = {
+      [Symbol.asyncIterator]: async function* () {
+        try {
+          yield observe(first);
+          for (; ; ) {
+            const next = await lines.next();
+            if (next.done) break;
+            yield observe(machineLine(next.value, kind));
+          }
+        } catch (cause) {
+          streamError = cause instanceof Error ? cause : new Error(String(cause));
+          if (!engine.settled()) child.kill("SIGTERM");
+          throw streamError;
+        } finally {
+          void lines.return(void 0).catch(() => {
+          });
+          resolveDrained();
+        }
+      }
+    };
+    const done = Promise.all([closed, drained]).then(([exitCode]) => {
+      if (streamError) throw streamError;
+      const status = eventStatus(lastEvent) ?? statusForExit(exitCode, lastEvent?.kind);
+      const stderr = engine.diagnostics();
+      return {
+        id,
+        status,
+        transport: this.kind,
+        exitCode,
+        ...outputs ? { outputs } : {},
+        ...receipt ? { receipt } : {},
+        ...machineError ? { error: machineError } : {},
+        ...settlement ? { settlement } : {},
+        ...stderr ? { diagnostics: stderr } : {}
+      };
+    });
+    done.catch(() => {
+    });
+    let cancelPromise;
+    return {
+      id,
+      events,
+      done,
+      status: async () => {
+        throw new NikaCompatibilityError(
+          "runStatus",
+          this.kind,
+          "A direct native process has no independent durable status authority; await run.result()"
+        );
+      },
+      cancel: () => {
+        cancelPromise ??= Promise.resolve(
+          engine.settled() ? {
+            runId: id,
+            accepted: false,
+            status: "already_settled",
+            transport: this.kind
+          } : {
+            runId: id,
+            accepted: child.kill("SIGTERM"),
+            status: "cancellation_requested",
+            transport: this.kind
+          }
+        );
+        return cancelPromise;
+      },
+      cleanup: () => engine.stop()
+    };
+  }
+  capture(args, signal) {
+    return new Promise((resolve, reject) => {
+      if (signal?.aborted) {
+        reject(new NikaTransportError(this.kind, "Operation aborted by caller"));
+        return;
+      }
+      const child = spawn2(this.options.engine.bin, args, {
+        cwd: this.options.cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        shell: false
+      });
+      let stdout = "";
+      let stderr = "";
+      child.stdout.setEncoding("utf8");
+      child.stderr.setEncoding("utf8");
+      child.stdout.on("data", (chunk) => {
+        stdout = boundedAppend(stdout, chunk, this.options.machineBufferBytes);
+      });
+      child.stderr.on("data", (chunk) => {
+        stderr = boundedAppend(stderr, chunk, this.options.machineBufferBytes);
+      });
+      const abort = () => child.kill("SIGTERM");
+      signal?.addEventListener("abort", abort, { once: true });
+      child.once("error", (cause) => {
+        signal?.removeEventListener("abort", abort);
+        reject(new NikaTransportError(
+          this.kind,
+          `Cannot spawn ${this.options.engine.bin}: ${cause.message}`,
+          { cause }
+        ));
+      });
+      child.once("close", (code) => {
+        signal?.removeEventListener("abort", abort);
+        if (signal?.aborted) {
+          reject(new NikaTransportError(this.kind, "Operation aborted by caller"));
+          return;
+        }
+        resolve({ exitCode: code ?? 3, stdout, stderr });
+      });
+    });
+  }
+  /** The verified engine's identity is kept: its capabilities gate what a run may ask. */
+  ensureReady() {
+    this.ready ??= verifyNikaEngine(this.options.engine);
+    return this.ready;
+  }
+};
+var INPUTS_LITERAL = "inputsLiteral";
+function writeLiteralInputs(stdin, json) {
+  stdin.on("error", () => {
+  });
+  stdin.end(json);
+}
+var ENGINE_PREFIX2 = /^nika:\s*/;
+var DIAGNOSTIC_EXCERPT_LIMIT = 240;
+var STOP_GRACE_MILLISECONDS = 2e3;
+function endsWithin(settling, milliseconds) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(false), milliseconds);
+    const ended = () => {
+      clearTimeout(timer);
+      resolve(true);
+    };
+    settling.then(ended, ended);
+  });
+}
+async function* machineLines(stdout, limit, kind) {
+  const bounded = (raw) => {
+    if (Buffer.byteLength(raw) > limit) {
+      throw new NikaProtocolError(
+        kind,
+        `Native machine line exceeded ${limit} bytes; machineBufferBytes bounds one machine frame`
+      );
+    }
+    return raw.trim();
+  };
+  let buffer = "";
+  stdout.setEncoding("utf8");
+  for await (const chunk of stdout) {
+    buffer += String(chunk);
+    let newline;
+    while ((newline = buffer.indexOf("\n")) >= 0) {
+      const line = bounded(buffer.slice(0, newline));
+      buffer = buffer.slice(newline + 1);
+      if (line) yield line;
+    }
+    bounded(buffer);
+  }
+  const tail = bounded(buffer);
+  if (tail) yield tail;
+}
+function reportObject(text) {
+  const trimmed = text.trim();
+  if (!trimmed) return void 0;
+  let value;
+  try {
+    value = JSON.parse(trimmed);
+  } catch {
+    return void 0;
+  }
+  return machineObject(value);
+}
+function stripEnginePrefix(text) {
+  return text.trim().replace(ENGINE_PREFIX2, "");
+}
+function diagnosticExcerpt(text, limit = DIAGNOSTIC_EXCERPT_LIMIT) {
+  const single = stripEnginePrefix(text).replace(/\s+/g, " ").trim();
+  if (!single) return void 0;
+  return single.length > limit ? `${single.slice(0, limit)}\u2026` : single;
+}
+function machineLine(line, kind) {
+  try {
+    return parseMachineObject(line, kind);
+  } catch (cause) {
+    throw quotedProtocolError(cause, line, kind);
+  }
+}
+function quotedProtocolError(cause, text, kind) {
+  const verdict = cause instanceof Error ? cause.message : "Engine machine output was unreadable";
+  return new NikaProtocolError(
+    kind,
+    quoted(verdict, text),
+    { cause: cause instanceof Error ? cause : void 0 }
+  );
+}
+function quoted(verdict, text) {
+  const excerpt = diagnosticExcerpt(text);
+  return excerpt ? `${verdict}: ${excerpt}` : verdict;
+}
+function runFlags(options, literal) {
+  const flags = [];
+  if (literal) flags.push("--inputs-json", "-");
+  for (const [key, value] of Object.entries(options.vars ?? {})) {
+    flags.push("--var", `${key}=${String(value)}`);
+  }
+  if (options.model) flags.push("--model", options.model);
+  if (options.maxCostUsd !== void 0) flags.push("--max-cost-usd", String(options.maxCostUsd));
+  return flags;
+}
+function statusForExit(exitCode, kind) {
+  if (kind === "workflow_completed") return "succeeded";
+  if (kind === "workflow_failed") return "failed";
+  if (kind === "workflow_paused") return "paused";
+  if (kind === "workflow_cancelled") return "cancelled";
+  switch (exitCode) {
+    case 0:
+      return "succeeded";
+    case 4:
+      return "paused";
+    case 130:
+      return "interrupted";
+    default:
+      return "failed";
+  }
+}
+function boundedAppend(current, chunk, limit) {
+  const combined = current + chunk;
+  if (Buffer.byteLength(combined) <= limit) return combined;
+  return Buffer.from(combined).subarray(-limit).toString("utf8");
+}
+function receiptMismatch(receipt, manifest) {
+  const trace = machineObject(manifest.trace);
+  const seal = machineObject(manifest.seal);
+  const covers = machineObject(seal?.covers);
+  const binding = machineObject(covers?.sdk_receipt);
+  if (trace?.chain !== "intact" || seal?.present !== true || seal.verifies !== true || seal.covers_chain !== true || !binding) return "the evidence manifest has no verified signed SDK receipt binding";
+  const claims = ["receipt_format", "execution_id", "trace_id", "snapshot_digest"];
+  for (const claim of claims) {
+    if (receipt[claim] !== binding[claim]) return `${claim} is not bound to this trace`;
+  }
+  if (receipt.chain_head !== trace.head) return "chain_head is not this journal head";
+  if (receipt.chain_len !== trace.events) return "chain_len is not this journal length";
+  if (receipt.sealed !== true) return "sealed is not true for this verified seal";
+  return void 0;
+}
+
+// src/lib/run-events.ts
+var STARTED = /* @__PURE__ */ new Set(["workflow_started", "execution.started"]);
+var TASKS = /* @__PURE__ */ new Map([
+  ["task_scheduled", "task.scheduled"],
+  ["task_started", "task.started"],
+  ["task_completed", "task.completed"],
+  ["task_failed", "task.failed"]
+]);
+var SETTLEMENT = /* @__PURE__ */ new Set(["run_settled", "execution.settled"]);
+var SETTLEMENT_WORDS = /* @__PURE__ */ new Set(["succeeded", "failed", "cancelled"]);
+var SETTLED = /* @__PURE__ */ new Map([
+  ["run_settled", SETTLEMENT_WORDS],
+  ["execution.settled", SETTLEMENT_WORDS],
+  ["execution.cancelled", /* @__PURE__ */ new Set(["cancelled"])],
+  ["execution.refused", /* @__PURE__ */ new Set(["failed"])]
+]);
+var INTERRUPTED = /* @__PURE__ */ new Set([
+  "workflow_interrupted",
+  "execution.interrupted",
+  "interrupted"
+]);
+function semanticRunEvent(raw, transport) {
+  const stated = eventStatus(raw);
+  const kind = semanticKind(raw.kind, stated);
+  const named = kind !== "engine.event";
+  const status = named ? stated : void 0;
+  const task = kind.startsWith("task.") ? eventTask(raw) : void 0;
+  const failed = kind === "task.failed" || kind === "run.settled" && status === "failed";
+  const error = failed ? eventError(raw) : void 0;
+  const sequence = transport === "http" && Number.isSafeInteger(raw.sequence) ? raw.sequence : void 0;
+  return Object.freeze({
+    kind,
+    transport,
+    ...status !== void 0 ? { status } : {},
+    ...sequence !== void 0 ? { sequence } : {},
+    ...task !== void 0 ? { task } : {},
+    ...error !== void 0 ? { error } : {},
+    raw
+  });
+}
+function semanticKind(kind, status) {
+  if (typeof kind !== "string") return "engine.event";
+  if (STARTED.has(kind)) return "run.started";
+  const task = TASKS.get(kind);
+  if (task !== void 0) return task;
+  if (kind === "run_sealed") return "run.sealed";
+  if (INTERRUPTED.has(kind)) return status === "interrupted" ? "run.interrupted" : "engine.event";
+  if (status === void 0) return "engine.event";
+  if (status === "paused") return SETTLEMENT.has(kind) ? "run.waiting" : "engine.event";
+  return SETTLED.get(kind)?.has(status) === true ? "run.settled" : "engine.event";
+}
+function eventTask(raw) {
+  if (typeof raw.task === "string") return raw.task;
+  const fields = Array.isArray(raw.fields) ? raw.fields : [];
+  for (const field of fields) {
+    const row = machineObject(field);
+    if (row?.key === "task" && typeof row.value === "string") return row.value;
+  }
+  return void 0;
+}
+
+// src/lib/run-session.ts
+var RunSession = class {
+  constructor(source, eventBufferSize, transport) {
+    this.source = source;
+    this.eventBufferSize = eventBufferSize;
+    this.transport = transport;
+    this.done = new Promise((resolve, reject) => {
+      this.resolveDone = resolve;
+      this.rejectDone = reject;
+    });
+    this.done.catch(() => {
+    });
+    this.run = Object.freeze({
+      id: source.id,
+      events: (options) => this.semanticEvents(options),
+      result: () => this.done,
+      status: () => this.status(),
+      cancel: () => this.cancel(),
+      done: this.done
+    });
+    void this.observeSettlement();
+    void this.pump();
+  }
+  run;
+  history = [];
+  subscribers = /* @__PURE__ */ new Set();
+  done;
+  resolveDone;
+  rejectDone;
+  terminal = false;
+  cancelPromise;
+  /** Every frame the pump delivered; `history` holds at most the last `eventBufferSize`. */
+  observed = 0;
+  /**
+   * The lifecycle vocabulary over the same bounded view: one history, one
+   * queue, and a pure per-frame projection at the edge. No second event bus.
+   */
+  semanticEvents(options = {}) {
+    const view = this.events(options);
+    const transport = this.transport;
+    const lifecycle = {
+      [Symbol.asyncIterator]: () => lifecycle,
+      next: async () => {
+        const step = await view.next();
+        if (step.done) return { value: void 0, done: true };
+        return { value: semanticRunEvent(step.value, transport), done: false };
+      },
+      return: async () => {
+        await view.return?.();
+        return { value: void 0, done: true };
+      }
+    };
+    return lifecycle;
+  }
+  /** The protocol frames, exactly as the transport delivered them. */
+  events(options = {}) {
+    const requested = options.bufferSize ?? this.eventBufferSize;
+    if (!Number.isInteger(requested) || requested < 1 || requested > this.eventBufferSize) {
+      throw new RangeError(
+        `events bufferSize must be an integer from 1 to ${this.eventBufferSize}`
+      );
+    }
+    if (this.observed > requested) {
+      throw new NikaEventBufferOverflowError(this.source.id, requested, {
+        observed: this.observed,
+        retained: this.history.length
+      });
+    }
+    const subscription = new EventSubscription(
+      this.source.id,
+      requested,
+      this.history.slice(-requested),
+      options.signal,
+      () => this.subscribers.delete(subscription)
+    );
+    if (this.terminal || options.signal?.aborted) subscription.close();
+    else this.subscribers.add(subscription);
+    return subscription;
+  }
+  cancel() {
+    this.cancelPromise ??= this.requestCancel().catch((error) => {
+      this.cancelPromise = void 0;
+      throw error;
+    });
+    return this.cancelPromise;
+  }
+  status() {
+    return this.source.status();
+  }
+  async requestCancel() {
+    const cancellation = await this.source.cancel();
+    if (cancellation.status === "cancellation_requested") return cancellation;
+    const result = await this.source.done;
+    if (!this.terminal && this.subscribers.size === 0) {
+      this.terminal = true;
+      this.resolveDone(result);
+      for (const subscriber of [...this.subscribers]) subscriber.close();
+      this.subscribers.clear();
+      await this.source.cleanup().catch(() => {
+      });
+    }
+    return cancellation;
+  }
+  async observeSettlement() {
+    try {
+      this.resolveDone(await this.source.done);
+    } catch (cause) {
+      const error = cause instanceof Error ? cause : new Error(String(cause));
+      this.rejectDone(error);
+    }
+  }
+  async pump() {
+    try {
+      for await (const event of this.source.events) {
+        this.observed += 1;
+        this.history.push(event);
+        if (this.history.length > this.eventBufferSize) this.history.shift();
+        for (const subscriber of [...this.subscribers]) subscriber.push(event);
+      }
+      this.resolveDone(await this.source.done);
+    } catch (cause) {
+      const error = cause instanceof Error ? cause : new Error(String(cause));
+      this.rejectDone(error);
+      for (const subscriber of [...this.subscribers]) subscriber.fail(error);
+    } finally {
+      this.terminal = true;
+      for (const subscriber of [...this.subscribers]) subscriber.close();
+      this.subscribers.clear();
+      await this.source.cleanup().catch(() => {
+      });
+    }
+  }
+};
+var EventSubscription = class {
+  constructor(runId, limit, initial, signal, detach) {
+    this.runId = runId;
+    this.limit = limit;
+    this.detach = detach;
+    this.queue = [...initial];
+    this.signal = signal;
+    this.abort = () => this.close();
+    if (signal?.aborted) this.closed = true;
+    else signal?.addEventListener("abort", this.abort, { once: true });
+  }
+  queue;
+  waiter;
+  closed = false;
+  error;
+  abort;
+  signal;
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+  next() {
+    const event = this.queue.shift();
+    if (event) return Promise.resolve({ value: event, done: false });
+    if (this.error) return Promise.reject(this.error);
+    if (this.closed) return Promise.resolve({ value: void 0, done: true });
+    if (this.waiter) {
+      return Promise.reject(new Error("Concurrent next() calls are not supported"));
+    }
+    return new Promise((resolve, reject) => {
+      this.waiter = { resolve, reject };
+    });
+  }
+  return() {
+    this.close();
+    return Promise.resolve({ value: void 0, done: true });
+  }
+  push(event) {
+    if (this.closed || this.error) return;
+    if (this.waiter) {
+      const waiter = this.waiter;
+      this.waiter = void 0;
+      waiter.resolve({ value: event, done: false });
+      return;
+    }
+    if (this.queue.length >= this.limit) {
+      this.fail(new NikaEventBufferOverflowError(this.runId, this.limit));
+      return;
+    }
+    this.queue.push(event);
+  }
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.signal?.removeEventListener("abort", this.abort);
+    this.detach();
+    if (this.waiter) {
+      const waiter = this.waiter;
+      this.waiter = void 0;
+      waiter.resolve({ value: void 0, done: true });
+    }
+  }
+  fail(error) {
+    if (this.closed || this.error) return;
+    this.error = error;
+    this.queue.length = 0;
+    this.signal?.removeEventListener("abort", this.abort);
+    this.detach();
+    if (this.waiter) {
+      const waiter = this.waiter;
+      this.waiter = void 0;
+      waiter.reject(error);
+    }
+  }
+};
+
+// src/results.ts
+function isNikaRunSucceeded(result) {
+  return result.status === "succeeded";
+}
+
+// src/events.ts
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "succeeded",
+  "failed",
+  "interrupted",
+  "cancelled"
+]);
+function isNikaRunSettledEvent(event) {
+  return event.kind === "run_settled" || event.kind === "execution.settled";
+}
+function isNikaTerminalEvent(event) {
+  return typeof event.status === "string" && TERMINAL_STATUSES.has(event.status);
+}
+function isNikaRunSealedEvent(event) {
+  return event.kind === "run_sealed";
+}
+
+// src/index.ts
+var DEFAULT_EVENT_BUFFER_SIZE = 4096;
+var DEFAULT_MACHINE_BUFFER_BYTES = 64 * 1024;
+var DEFAULT_REQUEST_TIMEOUT = 3e4;
+var Nika = class {
+  transportKind;
+  transport;
+  sessions = /* @__PURE__ */ new WeakMap();
+  eventBufferSize;
+  constructor(config = {}) {
+    this.eventBufferSize = positiveInteger(
+      config.eventBufferSize ?? DEFAULT_EVENT_BUFFER_SIZE,
+      "eventBufferSize"
+    );
+    const machineBufferBytes = positiveInteger(
+      config.machineBufferBytes ?? DEFAULT_MACHINE_BUFFER_BYTES,
+      "machineBufferBytes"
+    );
+    if (config.url !== void 0) {
+      if (typeof config.token !== "string" || config.token.length === 0) {
+        throw new NikaConfigurationError("A non-empty token is required with a Nika URL");
+      }
+      const url = checkedUrl(config.url, config.allowInsecureHttp === true);
+      this.transport = new HttpTransport({
+        url,
+        token: checkedToken(config.token),
+        fetch: config.fetch ?? globalThis.fetch.bind(globalThis),
+        requestTimeout: positiveInteger(
+          config.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT,
+          "requestTimeout"
+        ),
+        machineBufferBytes,
+        // Lazy: HTTP observation needs no local engine. Resolution (and its
+        // typed NikaEngineUnavailable refusal) is deferred to caller-owned
+        // source capture in check/run.
+        resolveEngine: () => resolveNikaEngine(config.bin),
+        cwd: config.cwd
+      });
+    } else {
+      const remoteOnly = config;
+      if (remoteOnly.token !== void 0 || remoteOnly.allowInsecureHttp !== void 0 || remoteOnly.requestTimeout !== void 0 || remoteOnly.fetch !== void 0) {
+        throw new NikaConfigurationError("token, allowInsecureHttp, requestTimeout, and fetch require url");
+      }
+      const engine = resolveNikaEngine(config.bin);
+      this.transport = new NativeProcessTransport({
+        engine,
+        cwd: config.cwd,
+        machineBufferBytes
+      });
+    }
+    this.transportKind = this.transport.kind;
+  }
+  check(workflow, options = {}) {
+    return this.transport.check(workflowName(workflow), options);
+  }
+  /**
+   * Resolves with the run's handle once the engine admitted it, and rejects
+   * without one when the engine refused it. The handle owns the lifecycle:
+   * `run.events()`, `run.result()`, `run.status()`, `run.cancel()`.
+   *
+   * `Outputs` is the caller's projection of the engine-emitted outputs map;
+   * the SDK transports outputs without validating their shape.
+   */
+  async run(workflow, options = {}) {
+    const source = await this.transport.startRun(workflowName(workflow), options);
+    return this.own(source);
+  }
+  /**
+   * The one recovery door: reattach this client process to an
+   * already-admitted durable HTTP job and get a full `NikaRun` back. Pass the
+   * last `event.sequence` you fully processed as `lastEventId`. A native
+   * process is process-bound and refuses with a typed compatibility error.
+   */
+  async attachRun(id, options = {}) {
+    const lastEventId = options.lastEventId ?? 0;
+    if (!Number.isSafeInteger(lastEventId) || lastEventId < 0) {
+      throw new RangeError("lastEventId must be a non-negative safe integer");
+    }
+    const source = await this.transport.attachRun(jobId(id), { lastEventId });
+    return this.own(source);
+  }
+  /** List contained workflow names from a resident HTTP authority. */
+  listWorkflows() {
+    return this.transport.listWorkflows();
+  }
+  /** Read path-free metadata for one contained workflow. */
+  workflow(name) {
+    return this.transport.workflow(workflowName(name));
+  }
+  /**
+   * The run's events in the protocol vocabulary of its transport
+   * (`workflow_*` · `task_*` · `run_*` natively, `execution.*` over HTTP).
+   *
+   * @deprecated Use `run.events()`: one lifecycle vocabulary on both
+   * transports, with this same frame kept on `event.raw`. This wrapper is a
+   * compatibility door for one release train, counted from publication: it
+   * ships unchanged in the first published train that carries `run.events()`,
+   * and the earliest train that may remove it is the one after, as announced
+   * in that train's release notes. It accepts only a run this client created.
+   */
+  events(run, options = {}) {
+    return this.session(run).events(options);
+  }
+  /**
+   * @deprecated Use `run.cancel()`; both return the one memoized request.
+   * Kept through the same compatibility window as `events(run)`. It accepts
+   * only a run this client created.
+   */
+  cancel(run) {
+    return this.session(run).cancel();
+  }
+  /**
+   * Read the current durable status without waiting for terminal settlement.
+   *
+   * @deprecated Use `run.status()`. Kept through the same compatibility
+   * window as `events(run)`. It accepts only a run this client created.
+   */
+  status(run) {
+    return this.session(run).status();
+  }
+  schedule(workflow, options) {
+    scheduleId(options?.id);
+    return this.transport.schedule(workflowName(workflow), options);
+  }
+  scheduleStatus(id) {
+    return this.transport.scheduleStatus(scheduleId(id));
+  }
+  traceVerify(receipt, options = {}) {
+    if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
+      throw new TypeError("traceVerify() accepts an engine-issued NikaReceipt object only");
+    }
+    return this.transport.traceVerify(receipt, options);
+  }
+  /** One session per admitted run, owned by this client and by no registry. */
+  own(source) {
+    const session = new RunSession(source, this.eventBufferSize, this.transportKind);
+    this.sessions.set(session.run, session);
+    return session.run;
+  }
+  session(run) {
+    const session = this.sessions.get(run);
+    if (!session) throw new NikaRunOwnershipError();
+    return session;
+  }
+};
+function checkedUrl(value, allowInsecureHttp) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new NikaConfigurationError(`Invalid Nika URL: ${value}`);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new NikaConfigurationError("Nika URL must use https: or http:");
+  }
+  if (url.protocol === "http:") {
+    if (!allowInsecureHttp) {
+      throw new NikaConfigurationError(
+        "Plain HTTP requires allowInsecureHttp: true; prefer HTTPS for remote engines"
+      );
+    }
+    if (!isLoopbackHost(url.hostname)) {
+      throw new NikaConfigurationError(
+        `Plain HTTP is limited to loopback hosts (localhost, 127.0.0.0/8, [::1]); use HTTPS for ${url.hostname}`
+      );
+    }
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new NikaConfigurationError("Nika URL cannot contain credentials, a query, or a fragment");
+  }
+  return url.toString().replace(/\/$/, "");
+}
+var LOOPBACK_IPV4 = /^127(?:\.(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+var IPV4_MAPPED_IPV6 = /^::ffff:([0-9a-f]{1,4}):[0-9a-f]{1,4}$/;
+function isLoopbackHost(hostname) {
+  const host = hostname.toLowerCase();
+  if (host === "localhost") return true;
+  if (LOOPBACK_IPV4.test(host)) return true;
+  const literal = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+  if (literal === "::1") return true;
+  const mapped = literal.match(IPV4_MAPPED_IPV6);
+  return mapped !== null && Number.parseInt(mapped[1], 16) >>> 8 === 127;
+}
+function checkedToken(value) {
+  const bytes = Buffer.byteLength(value);
+  if (bytes < 32 || bytes > 512 || !/^[\x21-\x7e]+$/.test(value)) {
+    throw new NikaConfigurationError(
+      "Nika bearer token must be 32-512 visible ASCII bytes without whitespace"
+    );
+  }
+  return value;
+}
+function positiveInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new NikaConfigurationError(`${name} must be a positive integer`);
+  }
+  return value;
+}
+function workflowName(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError("workflow must be a non-empty string");
+  }
+  return value;
+}
+function scheduleId(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError("schedule id must be a non-empty string");
+  }
+  return value;
+}
+function jobId(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError("job id must be a non-empty string");
+  }
+  return value;
+}
+export {
+  Nika,
+  NikaCompatibilityError,
+  NikaConfigurationError,
+  NikaEngineUnavailable,
+  NikaError,
+  NikaEventBufferOverflowError,
+  NikaObservationInterrupted,
+  NikaOperationError,
+  NikaProtocolError,
+  NikaRunOwnershipError,
+  NikaTransportError,
+  isNikaRunSealedEvent,
+  isNikaRunSettledEvent,
+  isNikaRunSucceeded,
+  isNikaTerminalEvent
+};