@supernovae-st/nika 0.118.7 → 0.120.2

package/dist/index.cjs

@@ -43,6 +43,7 @@ __export(index_exports, {
   NikaTransportError: () => NikaTransportError,
   isNikaRunSealedEvent: () => isNikaRunSealedEvent,
   isNikaRunSettledEvent: () => isNikaRunSettledEvent,
+  isNikaRunSucceeded: () => isNikaRunSucceeded,
   isNikaTerminalEvent: () => isNikaTerminalEvent
 });
 module.exports = __toCommonJS(index_exports);
@@ -121,12 +122,19 @@ var NikaOperationError = class extends NikaError {
 };
 var NikaEventBufferOverflowError = class extends NikaError {
   runId;
+  /** The bound that was exceeded: the view's `bufferSize`. */
   limit;
-  constructor(runId, limit) {
-    super(`Event subscriber for run ${runId} exceeded its ${limit}-event buffer`);
+  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 {
@@ -136,9 +144,6 @@ var NikaRunOwnershipError = class extends NikaError {
   }
 };
 
-// src/lib/http-transport.ts
-var import_node_crypto2 = require("crypto");
-
 // src/lib/binary/error.ts
 var NikaEngineUnavailable = class extends NikaError {
   code = "NIKA_ENGINE_UNAVAILABLE";
@@ -628,6 +633,184 @@ function incompatible2(message, cause) {
   );
 }
 
+// src/lib/literal-inputs.ts
+var import_node_util = require("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" || import_node_util.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 || import_node_util.types.isProxy(prototype)) return false;
+  const constructor = ownValue(prototype, "constructor");
+  if (typeof constructor !== "function" || import_node_util.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 (import_node_util.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 (import_node_util.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 || import_node_util.types.isProxy(prototype)) return custom;
+  const constructor = ownValue(prototype, "constructor");
+  if (typeof constructor !== "function" || import_node_util.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) {
@@ -785,6 +968,100 @@ async function* decodeSse(stream, limits, signal) {
   }
 }
 
+// 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",
@@ -801,6 +1078,7 @@ 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;
@@ -817,6 +1095,7 @@ var HttpTransport = class {
         "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;
@@ -836,19 +1115,35 @@ var HttpTransport = class {
     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"
+        "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"
       );
     }
-    const idempotencyKey = options.idempotencyKey ?? (0, import_node_crypto2.randomUUID)();
     if (Buffer.byteLength(idempotencyKey) < 1 || Buffer.byteLength(idempotencyKey) > 255) {
       throw new NikaTransportError(this.kind, "Idempotency-Key must be 1-255 bytes");
     }
-    if (isContainedWorkflowName(workflow)) {
+    if (byName) {
       await this.ensureServerIdentity();
-      const job2 = await this.admitJob(JSON.stringify({ workflow }), idempotencyKey);
+      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);
@@ -924,6 +1219,7 @@ var HttpTransport = class {
     return Object.freeze([...object.workflows]);
   }
   async workflow(name) {
+    refuseLegacyContainedName(name);
     await this.ensureServerIdentity();
     const object = await this.json(`/v1/workflows/${workflowPath(name)}`, {
       method: "GET",
@@ -935,6 +1231,7 @@ var HttpTransport = class {
     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" });
@@ -1026,6 +1323,7 @@ var HttpTransport = class {
       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,
@@ -1035,7 +1333,8 @@ var HttpTransport = class {
         ...outputs ? { outputs } : {},
         ...receipt ? { receipt } : {},
         ...error ? { error } : {},
-        ...settlement ? { settlement } : {}
+        ...settlement ? { settlement } : {},
+        ...evidence ? { evidence } : {}
       });
     };
     if (attachedState && isObservationEnded(attachedState)) settle(attachedState);
@@ -1234,13 +1533,15 @@ var HttpTransport = class {
     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"
+      "settlement",
+      "evidence"
     ]);
     if (Object.keys(event).some((key) => !allowed.has(key))) {
       throw new NikaProtocolError(this.kind, "SSE data contained fields outside the public projection");
@@ -1262,6 +1563,10 @@ var HttpTransport = class {
         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");
     }
@@ -1511,6 +1816,21 @@ var HttpTransport = class {
       );
     }
   }
+  /**
+   * 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(
@@ -1784,6 +2104,11 @@ var HttpTransport = class {
     }
   }
 };
+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 === "..")) {
@@ -1791,15 +2116,6 @@ function workflowPath(name) {
   }
   return segments.map(encodeURIComponent).join("/");
 }
-function isContainedWorkflowName(value) {
-  if (typeof value !== "string" || !value.endsWith(".nika.yaml")) return false;
-  try {
-    workflowPath(value);
-    return true;
-  } catch {
-    return false;
-  }
-}
 function scheduleBody(workflow, options) {
   return {
     workflow,
@@ -1906,7 +2222,8 @@ function durableJob(value, expectedId, transport) {
     "outputs",
     "receipt",
     "error",
-    "settlement"
+    "settlement",
+    "evidence"
   ]);
   if (Object.keys(value).some((key) => !allowed.has(key))) {
     throw new NikaProtocolError(transport, "Durable job response contained unknown fields");
@@ -1930,6 +2247,7 @@ function durableJob(value, expectedId, transport) {
   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");
   }
@@ -1953,9 +2271,24 @@ function durableJob(value, expectedId, transport) {
     ...outputs ? { outputs } : {},
     ...receipt ? { receipt: Object.freeze(receipt) } : {},
     ...error ? { error } : {},
-    ...settlement ? { settlement } : {}
+    ...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",
@@ -2083,7 +2416,104 @@ function isCanonicalTimestamp(value) {
 
 // src/lib/native-process-transport.ts
 var import_node_child_process2 = require("child_process");
-var import_node_crypto3 = require("crypto");
+var import_node_crypto2 = require("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;
@@ -2108,7 +2538,8 @@ var NativeProcessTransport = class {
     return { ...report, exitCode: captured.exitCode };
   }
   async startRun(workflow, options) {
-    await this.ensureReady();
+    const inputs = literalInputs(options);
+    const identity = await this.ensureReady();
     if (options.idempotencyKey !== void 0) {
       throw new NikaCompatibilityError(
         "idempotencyKey",
@@ -2116,13 +2547,26 @@ var NativeProcessTransport = class {
         "idempotencyKey is an HTTP admission option"
       );
     }
-    const args = ["run", workflow, "--json", ...runFlags(options)];
-    const child = (0, import_node_child_process2.spawn)(this.options.engine.bin, args, {
-      cwd: this.options.cwd,
-      stdio: ["ignore", "pipe", "pipe"],
-      shell: false
-    });
-    return this.processRun((0, import_node_crypto3.randomUUID)(), child);
+    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 ? (0, import_node_child_process2.spawn)(this.options.engine.bin, args, { ...spawnOptions, stdio: ["pipe", "pipe", "pipe"] }) : (0, import_node_child_process2.spawn)(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((0, import_node_crypto2.randomUUID)(), engine, first);
   }
   async attachRun(_id, _options) {
     throw new NikaCompatibilityError(
@@ -2205,19 +2649,8 @@ RECEIPT MISMATCH: ${mismatch}
 `)
     };
   }
-  processRun(id, child) {
+  nativeProcess(child) {
     let settled = false;
-    let lastEvent;
-    let receipt;
-    let outputs;
-    let machineError;
-    let settlement;
-    let streamError;
-    let refusal;
-    let resolveDrained;
-    const drained = new Promise((resolve) => {
-      resolveDrained = resolve;
-    });
     let stderr = "";
     child.stderr.setEncoding("utf8");
     child.stderr.on("data", (chunk) => {
@@ -2225,94 +2658,154 @@ RECEIPT MISMATCH: ${mismatch}
     });
     const closed = new Promise((resolve, reject) => {
       child.once("error", (cause) => {
-        streamError = new NikaTransportError(
+        reject(new NikaTransportError(
           this.kind,
           `Cannot spawn ${this.options.engine.bin}: ${cause.message}`,
           { cause }
-        );
-        reject(streamError);
+        ));
       });
       child.once("close", (code, signal) => {
         settled = true;
-        if (code === null && signal && !streamError) resolve(130);
-        else resolve(code ?? 3);
+        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 machineBufferBytes = this.options.machineBufferBytes;
-    const lineEvent = (line) => {
-      const refused = engineRefusal(line);
-      if (refused) {
-        refusal ??= refused;
-        return void 0;
+    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);
       }
-      return machineLine(line, 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* () {
-        let buffer = "";
-        child.stdout.setEncoding("utf8");
         try {
-          for await (const chunk of child.stdout) {
-            buffer += String(chunk);
-            let newline;
-            while ((newline = buffer.indexOf("\n")) >= 0) {
-              const line = buffer.slice(0, newline).trim();
-              buffer = buffer.slice(newline + 1);
-              if (!line) continue;
-              const event = lineEvent(line);
-              if (!event) continue;
-              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;
-              yield event;
-            }
-            if (Buffer.byteLength(buffer) > machineBufferBytes) {
-              throw new NikaProtocolError(
-                kind,
-                `Native machine line exceeded ${machineBufferBytes} bytes`
-              );
-            }
-          }
-          const tail = buffer.trim();
-          if (tail) {
-            const event = lineEvent(tail);
-            if (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;
-              yield event;
-            }
+          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 (!settled) child.kill("SIGTERM");
+          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;
-      if (refusal) {
-        throw new NikaOperationError(
-          "run",
-          this.kind,
-          refusal.code,
-          refusal.line,
-          { status: exitCode }
-        );
-      }
       const status = eventStatus(lastEvent) ?? statusForExit(exitCode, lastEvent?.kind);
+      const stderr = engine.diagnostics();
       return {
         id,
         status,
@@ -2336,12 +2829,12 @@ RECEIPT MISMATCH: ${mismatch}
         throw new NikaCompatibilityError(
           "runStatus",
           this.kind,
-          "A direct native process has no independent durable status authority; await run.done"
+          "A direct native process has no independent durable status authority; await run.result()"
         );
       },
       cancel: () => {
         cancelPromise ??= Promise.resolve(
-          settled ? {
+          engine.settled() ? {
             runId: id,
             accepted: false,
             status: "already_settled",
@@ -2355,11 +2848,7 @@ RECEIPT MISMATCH: ${mismatch}
         );
         return cancelPromise;
       },
-      cleanup: async () => {
-        if (!settled) child.kill("SIGTERM");
-        await closed.catch(() => {
-        });
-      }
+      cleanup: () => engine.stop()
     };
   }
   capture(args, signal) {
@@ -2403,14 +2892,56 @@ RECEIPT MISMATCH: ${mismatch}
       });
     });
   }
+  /** The verified engine's identity is kept: its capabilities gate what a run may ask. */
   ensureReady() {
-    this.ready ??= verifyNikaEngine(this.options.engine).then(() => void 0);
+    this.ready ??= verifyNikaEngine(this.options.engine);
     return this.ready;
   }
 };
-var ENGINE_PREFIX = /^nika:\s*/;
-var REFUSAL_CODE = /^(NIKA-[A-Z0-9-]+)\b/;
+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;
@@ -2423,32 +2954,35 @@ function reportObject(text) {
   return machineObject(value);
 }
 function stripEnginePrefix(text) {
-  return text.trim().replace(ENGINE_PREFIX, "");
+  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 engineRefusal(line) {
-  const code = REFUSAL_CODE.exec(line)?.[1];
-  return code ? { code, line } : void 0;
-}
 function machineLine(line, kind) {
   try {
     return parseMachineObject(line, kind);
   } catch (cause) {
-    const verdict = cause instanceof Error ? cause.message : "Engine machine output was unreadable";
-    const excerpt = diagnosticExcerpt(line);
-    throw new NikaProtocolError(
-      kind,
-      excerpt ? `${verdict}: ${excerpt}` : verdict,
-      { cause: cause instanceof Error ? cause : void 0 }
-    );
+    throw quotedProtocolError(cause, line, kind);
   }
 }
-function runFlags(options) {
+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)}`);
   }
@@ -2493,18 +3027,87 @@ function receiptMismatch(receipt, manifest) {
   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) {
+  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, done: this.done });
+    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();
   }
@@ -2516,7 +3119,30 @@ var RunSession = class {
   rejectDone;
   terminal = false;
   cancelPromise;
-  historyOverflowed = false;
+  /** 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) {
@@ -2524,8 +3150,11 @@ var RunSession = class {
         `events bufferSize must be an integer from 1 to ${this.eventBufferSize}`
       );
     }
-    if (this.historyOverflowed || this.history.length > requested) {
-      throw new NikaEventBufferOverflowError(this.source.id, requested);
+    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,
@@ -2573,11 +3202,9 @@ var RunSession = class {
   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();
-          this.historyOverflowed = true;
-        }
+        if (this.history.length > this.eventBufferSize) this.history.shift();
         for (const subscriber of [...this.subscribers]) subscriber.push(event);
       }
       this.resolveDone(await this.source.done);
@@ -2669,6 +3296,11 @@ var EventSubscription = class {
   }
 };
 
+// src/results.ts
+function isNikaRunSucceeded(result) {
+  return result.status === "succeeded";
+}
+
 // src/events.ts
 var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
   "succeeded",
@@ -2687,7 +3319,7 @@ function isNikaRunSealedEvent(event) {
 }
 
 // src/index.ts
-var DEFAULT_EVENT_BUFFER_SIZE = 256;
+var DEFAULT_EVENT_BUFFER_SIZE = 4096;
 var DEFAULT_MACHINE_BUFFER_BYTES = 64 * 1024;
 var DEFAULT_REQUEST_TIMEOUT = 3e4;
 var Nika = class {
@@ -2742,25 +3374,30 @@ var Nika = class {
     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);
-    const session = new RunSession(source, this.eventBufferSize);
-    this.sessions.set(session.run, session);
-    return session.run;
+    return this.own(source);
   }
-  /** Reattach this client process to an already-admitted durable HTTP job. */
+  /**
+   * 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 });
-    const session = new RunSession(source, this.eventBufferSize);
-    this.sessions.set(session.run, session);
-    return session.run;
+    return this.own(source);
   }
   /** List contained workflow names from a resident HTTP authority. */
   listWorkflows() {
@@ -2770,13 +3407,34 @@ var Nika = class {
   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. */
+  /**
+   * 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();
   }
@@ -2793,6 +3451,12 @@ var Nika = class {
     }
     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();
@@ -2885,5 +3549,6 @@ function jobId(value) {
   NikaTransportError,
   isNikaRunSealedEvent,
   isNikaRunSettledEvent,
+  isNikaRunSucceeded,
   isNikaTerminalEvent
 });