@supernovae-st/nika 0.120.2 → 0.120.3

package/dist/index.js

@@ -203,29 +203,41 @@ function captureEngine(bin, args, options) {
       shell: false,
       stdio: ["ignore", "pipe", "pipe"]
     });
-    let stdout = "";
-    let stderr = "";
+    const stdout = [];
+    const stderr = [];
+    const bytes = { stdout: 0, stderr: 0 };
     let overflow = false;
     let spawnError;
+    let closed = false;
+    let killTimer;
+    const stop = () => {
+      child.kill("SIGTERM");
+      if (options.killGraceMs === void 0) return;
+      killTimer ??= setTimeout(() => {
+        if (!closed) child.kill("SIGKILL");
+      }, options.killGraceMs);
+      killTimer.unref();
+    };
     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) {
+      bytes[stream] += chunk.byteLength;
+      if (bytes[stream] > options.bufferBytes) {
         overflow = true;
-        child.kill("SIGTERM");
+        stop();
+        return;
       }
+      (stream === "stdout" ? stdout : stderr).push(chunk);
     };
-    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");
+    const abort = () => stop();
     options.signal?.addEventListener("abort", abort, { once: true });
     child.once("error", (cause) => {
       spawnError = cause;
     });
-    child.once("close", (code) => {
+    child.once("close", (code, exitSignal) => {
+      closed = true;
+      if (killTimer) clearTimeout(killTimer);
       options.signal?.removeEventListener("abort", abort);
       if (options.signal?.aborted) {
         reject(new NikaTransportError(options.transport, `${options.label} aborted by caller`));
@@ -241,7 +253,19 @@ function captureEngine(bin, args, options) {
           `${options.label} exceeded ${options.bufferBytes} bytes`
         ));
       } else {
-        resolve({ exitCode: code ?? 3, stdout, stderr });
+        let decoded;
+        try {
+          decoded = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Buffer.concat(stdout, bytes.stdout));
+        } catch {
+          reject(new NikaProtocolError(options.transport, `${options.label} stdout was not valid UTF-8`));
+          return;
+        }
+        resolve({
+          exitCode: code ?? 3,
+          stdout: decoded,
+          stderr: Buffer.concat(stderr, bytes.stderr).toString("utf8"),
+          exitSignal
+        });
       }
     });
   });
@@ -473,9 +497,9 @@ function incompatible(transport, message) {
 
 // src/lib/binary/verify.ts
 var IDENTITY_BUFFER_BYTES = 16 * 1024;
-async function verifyNikaEngine(engine) {
+async function verifyNikaEngine(engine, options = {}) {
   const expectedVersion = engine.packageRoot ? await verifyManagedPayload(engine) : void 0;
-  const identity = await probeIdentity(engine.bin);
+  const identity = await probeIdentity(engine.bin, options);
   if (expectedVersion !== void 0 && identity.engineVersion !== expectedVersion) {
     throw incompatible2(
       `Packaged engine version ${identity.engineVersion} does not match payload version ${expectedVersion}`
@@ -514,13 +538,15 @@ async function verifyManagedPayload(engine) {
   }
   return manifest.version;
 }
-async function probeIdentity(bin) {
+async function probeIdentity(bin, options) {
   const notAnEngine = `is ${bin} a nika engine? (run "${bin} --sdk-identity" by hand)`;
   const captured = await captureEngine(bin, ["--sdk-identity"], {
+    ...options,
     bufferBytes: IDENTITY_BUFFER_BYTES,
     transport: "native-process",
     label: "Engine identity probe"
   }).catch((cause) => {
+    if (options.signal?.aborted) throw cause;
     throw incompatible2(
       `Engine identity probe of ${bin} failed`,
       cause
@@ -600,25 +626,26 @@ 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) {
+function encodeLiteralInputs(inputs, label = "run({ inputs })") {
   if (containerKind(inputs) !== "object") {
+    const subject = label === "run({ inputs })" ? "inputs must be a plain object mapping declared workflow input names" : "answers must be a plain object mapping stable question keys";
     throw new NikaConfigurationError(
-      `run({ inputs }): inputs must be a plain object mapping declared workflow input names to strict JSON values; received ${describe(inputs)}`
+      `${label}: ${subject} 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();
+    if (bytes > LITERAL_INPUTS_MAX_BYTES) throw tooLarge(label);
     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 path4 = stack.map((frame) => frame.segment).join("") + segment;
+    const shown = path4.length > PATH_LIMIT ? `${path4.slice(0, PATH_LIMIT / 2)}\u2026${path4.slice(-PATH_LIMIT / 2)}` : path4;
+    return new NikaConfigurationError(`${label}: ${shown} ${problem}; ${STRICT_JSON}`);
   };
   const enter = (value, segment, kind) => {
     open.add(value);
@@ -671,7 +698,7 @@ function encodeLiteralInputs(inputs) {
     const value = member.value;
     switch (typeof value) {
       case "string":
-        if (value.length > LITERAL_INPUTS_MAX_BYTES) throw tooLarge();
+        if (value.length > LITERAL_INPUTS_MAX_BYTES) throw tooLarge(label);
         if (LONE_SURROGATE.test(value)) {
           throw refuse(segment, "contains a lone surrogate, which is not valid Unicode");
         }
@@ -703,7 +730,17 @@ function encodeLiteralInputs(inputs) {
   }
   return { json: parts.join(""), bytes };
 }
-function tooLarge() {
+function tooLarge(label) {
+  if (label === "compile({ change })") {
+    return new NikaConfigurationError(
+      `compile({ change }): the serialized literal exceeds ${LITERAL_INPUTS_MAX_BYTES} bytes (1 MiB)`
+    );
+  }
+  if (label === "compile({ answers })") {
+    return new NikaConfigurationError(
+      `compile({ answers }): the serialized answers exceed ${LITERAL_INPUTS_MAX_BYTES} bytes (1 MiB); answers ride argv, one KEY=JSON element each, never a wire`
+    );
+  }
   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`
   );
@@ -760,6 +797,364 @@ function refusedObject(value) {
   return typeof name === "string" && IDENTIFIER.test(name) && name.length <= 64 ? `is a ${name} instance, not a plain object or array` : custom;
 }
 
+// src/lib/compile.ts
+import { mkdtemp, rm, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import path3 from "path";
+import { types as utilTypes } from "util";
+import { addAbortListener } from "events";
+var COMPILE_CAPABILITY = "compile";
+var COMPILE_WIRE_VERSION = 1;
+var COMPILE_RESPONSE_MAX_BYTES = 8 * 1024 * 1024;
+var COMPILE_KILL_GRACE_MS = 2e3;
+var STATUSES = ["ready", "incomplete", "refused"];
+var signalAborted = Object.getOwnPropertyDescriptor(AbortSignal.prototype, "aborted").get;
+var removeSignalListener = EventTarget.prototype.removeEventListener;
+var signalInterface = /* @__PURE__ */ new Set([
+  "aborted",
+  "reason",
+  "throwIfAborted",
+  "addEventListener",
+  "removeEventListener",
+  "dispatchEvent"
+]);
+function normalizeCompileRequest(input) {
+  if (typeof input === "string") {
+    if (input.length === 0) {
+      throw new NikaConfigurationError("compile: an intent string must not be empty");
+    }
+    return { intent: input };
+  }
+  const record2 = dataRecord(input, "request");
+  for (const key of Reflect.ownKeys(record2)) {
+    if (key !== "intent" && key !== "workflow" && key !== "change" && key !== "answers") {
+      throw new NikaConfigurationError(
+        `compile: unknown request field ${String(key)}; the request is refused rather than silently reinterpreted`
+      );
+    }
+  }
+  const answers = record2.answers;
+  if (answers !== void 0) encodeLiteralInputs(answers, "compile({ answers })");
+  const intent = record2.intent;
+  const workflow = record2.workflow;
+  const change = record2.change;
+  if (intent !== void 0) {
+    if (workflow !== void 0 || change !== void 0) {
+      throw new NikaConfigurationError(
+        "compile: intent (create) never mixes with workflow/change (edit) in one request"
+      );
+    }
+    if (typeof intent !== "string" || intent.length === 0) {
+      throw new NikaConfigurationError("compile: intent must be a non-empty string");
+    }
+    return answers === void 0 ? { intent } : { intent, answers };
+  }
+  if (workflow === void 0 && change === void 0) {
+    throw new NikaConfigurationError(
+      "compile: the request carries neither intent nor workflow/change; nothing would compile"
+    );
+  }
+  if (typeof workflow !== "string" || workflow.length === 0) {
+    throw new NikaConfigurationError(
+      "compile: an edit needs the accepted workflow source as a non-empty string"
+    );
+  }
+  const normalizedChange = normalizeChange(change);
+  return answers === void 0 ? { workflow, change: normalizedChange } : { workflow, change: normalizedChange, answers };
+}
+function dataRecord(value, label) {
+  if (value === null || typeof value !== "object" || utilTypes.isProxy(value) || Array.isArray(value) || Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new NikaConfigurationError(`compile: ${label} must be ${label === "request" ? "an intent string or " : ""}a plain object with own data fields`);
+  }
+  const result = /* @__PURE__ */ Object.create(null);
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  for (const key of Reflect.ownKeys(descriptors)) {
+    const descriptor = descriptors[key];
+    if (typeof key !== "string" || !("value" in descriptor) || !descriptor.enumerable) {
+      throw new NikaConfigurationError(`compile: ${label} must contain only enumerable string data fields`);
+    }
+    result[key] = descriptor.value;
+  }
+  return result;
+}
+function normalizeChange(change) {
+  if (typeof change === "string" && change.length > 0) return change;
+  if (change === void 0 || change === "") {
+    throw new NikaConfigurationError("compile: an edit needs a non-empty change request");
+  }
+  const encoded = encodeLiteralInputs({ change }, "compile({ change })");
+  const object = machineObject(JSON.parse(encoded.json).change);
+  const constant = machineObject(object?.set_constant);
+  if (!object || Object.keys(object).length !== 1 || !constant || Object.keys(constant).length !== 2 || !("value" in constant) || typeof constant.name !== "string" || !/^[A-Za-z0-9_]+$/.test(constant.name)) {
+    throw new NikaConfigurationError(
+      "compile: an edit needs a non-empty change string or set_constant with a bare name and JSON value"
+    );
+  }
+  return object;
+}
+function normalizeCompileOptions(options) {
+  const record2 = dataRecord(options, "options");
+  for (const key of Reflect.ownKeys(record2)) {
+    if (key !== "signal" && key !== "timeoutMs") {
+      throw new NikaConfigurationError(`compile: unknown option ${String(key)}`);
+    }
+  }
+  const timeoutMs = record2.timeoutMs;
+  if (timeoutMs !== void 0 && (typeof timeoutMs !== "number" || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647)) {
+    throw new NikaConfigurationError(
+      "compile: timeoutMs must be a positive safe integer between 1 and 2147483647 milliseconds"
+    );
+  }
+  const signal = record2.signal;
+  if (signal !== void 0) {
+    const invalidSignal = () => new NikaConfigurationError("compile: signal must be an AbortSignal");
+    if (signal === null || typeof signal !== "object" || utilTypes.isProxy(signal) || Object.getPrototypeOf(signal) !== AbortSignal.prototype) throw invalidSignal();
+    const descriptors = Object.getOwnPropertyDescriptors(signal);
+    for (const key of Reflect.ownKeys(descriptors)) {
+      if (typeof key === "string" && signalInterface.has(key) || !("value" in descriptors[key])) throw invalidSignal();
+    }
+    try {
+      signalAborted.call(signal);
+    } catch {
+      throw invalidSignal();
+    }
+  }
+  return record2;
+}
+function compileSignal(options) {
+  const caller = options.signal;
+  let bridge;
+  let abort;
+  if (caller !== void 0) {
+    bridge = new AbortController();
+    const controller = bridge;
+    abort = () => controller.abort();
+    if (signalAborted.call(caller)) abort();
+    else addAbortListener(caller, abort);
+  }
+  let timeout;
+  if (options.timeoutMs !== void 0) timeout = AbortSignal.timeout(options.timeoutMs);
+  const signals = [bridge?.signal, timeout].filter((s) => s !== void 0);
+  return {
+    signal: signals.length === 0 ? void 0 : AbortSignal.any(signals),
+    timedOut: () => timeout?.aborted === true,
+    // Use the intrinsic even if the caller shadows removeEventListener after
+    // starting Compile. Do not retain a listener on a long-lived caller signal.
+    dispose: () => {
+      if (caller && abort) removeSignalListener.call(caller, "abort", abort);
+    }
+  };
+}
+async function compileArgv(request) {
+  const args = ["compile", "--json"];
+  for (const answer of compileAnswers(request.answers)) {
+    args.push(`--answer=${answer}`);
+  }
+  if (request.intent !== void 0) {
+    refuseNul(request.intent);
+    args.push("--", request.intent);
+    return { args };
+  }
+  const change = typeof request.change === "string" ? request.change : `Set const.${request.change.set_constant.name} to ${literalJson(request.change.set_constant.value)}`;
+  refuseNul(change);
+  const scratchDir = await mkdtemp(path3.join(tmpdir(), "nika-sdk-compile-"));
+  const base = path3.join(scratchDir, "base.nika");
+  try {
+    await writeFile(base, request.workflow, { encoding: "utf8", mode: 384 });
+  } catch (cause) {
+    await rm(scratchDir, { recursive: true, force: true });
+    throw new NikaTransportError("native-process", "compile could not write its temporary base source", {
+      cause: cause instanceof Error ? cause : void 0
+    });
+  }
+  args.push("--base", base, `--change=${change}`);
+  return { args, scratchDir };
+}
+async function removeCompileScratch(invocation) {
+  if (invocation.scratchDir !== void 0) {
+    await rm(invocation.scratchDir, { recursive: true, force: true });
+  }
+}
+function compileAnswers(answers) {
+  if (answers === void 0) return [];
+  encodeLiteralInputs(answers, "compile({ answers })");
+  return Reflect.ownKeys(answers).map((key) => {
+    const name = String(key);
+    if (name.length === 0 || name.includes("=") || name.includes("\0")) {
+      throw new NikaConfigurationError(
+        "compile({ answers }): a question key must be non-empty and cannot carry '='; the engine splits KEY=JSON on its first equals sign"
+      );
+    }
+    return `${name}=${literalJson(answers[name])}`;
+  });
+}
+function literalJson(value) {
+  return encodeLiteralInputs({ value }, "compile({ change })").json.slice('{"value":'.length, -1);
+}
+function refuseNul(value) {
+  if (value.includes("\0")) throw new NikaConfigurationError("compile: text cannot contain a NUL byte");
+}
+function compileBody(request) {
+  compileAnswers(request.answers);
+  const answers = request.answers === void 0 ? "" : `,"answers":${encodeLiteralInputs(request.answers, "compile({ answers })").json}`;
+  if (request.intent !== void 0) {
+    refuseNul(request.intent);
+    return `{"compile_version":1,"mode":"create","intent":${JSON.stringify(request.intent)}${answers}}`;
+  }
+  if (typeof request.change === "string") refuseNul(request.change);
+  const change = typeof request.change === "string" ? `{"text":${JSON.stringify(request.change)}}` : `{"set_constant":{"name":${JSON.stringify(request.change.set_constant.name)},"value":${literalJson(request.change.set_constant.value)}}}`;
+  return `{"compile_version":1,"mode":"edit","source":${JSON.stringify(request.workflow)},"change":${change}${answers}}`;
+}
+function compileOutcomeFrom(captured, transport, engine) {
+  const protocol = (message) => new NikaProtocolError(transport, `${message} (compile child at ${engine})`);
+  if (captured.exitSignal !== null) {
+    throw new NikaTransportError(
+      transport,
+      `compile child at ${engine} was ended externally by ${captured.exitSignal}`
+    );
+  }
+  const payload = machineObject(tryParseJson(captured.stdout));
+  if (!payload) {
+    const detail = excerpt(captured.stderr) || excerpt(captured.stdout);
+    throw protocol(
+      `the compile wire object is absent or malformed (exit ${captured.exitCode})` + (detail ? `: ${detail}` : "")
+    );
+  }
+  validateCompileVersion(payload.compile_version, transport, engine, protocol);
+  const hasError = "error" in payload;
+  const hasStatus = "status" in payload;
+  if (hasError && hasStatus) {
+    throw protocol("the payload carries both an outcome and an error");
+  }
+  if (hasError) {
+    const error = machineObject(payload.error);
+    if (!error || typeof error.code !== "string" || typeof error.message !== "string") {
+      throw protocol("the error payload lacks its code/message strings");
+    }
+    if (captured.exitCode !== 2 && captured.exitCode !== 3) {
+      throw protocol(
+        `an engine-stamped error arrived with exit ${captured.exitCode}, not 2 or 3`
+      );
+    }
+    throw new NikaOperationError("compile", transport, error.code, error.message, {
+      status: captured.exitCode,
+      machineCode: error.code
+    });
+  }
+  const status = payload.status;
+  if (typeof status !== "string" || !STATUSES.includes(status)) {
+    throw protocol(`unknown compile status ${JSON.stringify(status ?? null)}`);
+  }
+  if (status === "ready" ? captured.exitCode !== 0 : captured.exitCode !== 2) {
+    throw protocol(
+      `status ${JSON.stringify(status)} contradicts exit ${captured.exitCode}`
+    );
+  }
+  writtenFrom(payload.written, protocol);
+  return compilePayloadFrom(payload, transport, engine);
+}
+function compilePayloadFrom(payload, transport, engine) {
+  const protocol = (message) => new NikaProtocolError(transport, `compile at ${engine}: ${message}`);
+  validateCompileVersion(payload.compile_version, transport, engine, protocol);
+  if ("error" in payload) throw protocol("the payload carries an error instead of an outcome");
+  if (transport === "http" && "written" in payload) throw protocol("HTTP outcome claims a written destination");
+  const status = payload.status;
+  if (typeof status !== "string" || !STATUSES.includes(status)) {
+    throw protocol("unknown compile status");
+  }
+  const candidate = payload.candidate;
+  if (candidate !== null && typeof candidate !== "string") {
+    throw protocol("candidate is neither source text nor null");
+  }
+  if (status === "ready" && candidate === null) {
+    throw protocol("a ready outcome carries no candidate");
+  }
+  const outcome = {
+    compile_version: COMPILE_WIRE_VERSION,
+    status,
+    ready: status === "ready",
+    candidate,
+    questions: questionsFrom(payload.questions, protocol),
+    diagnostics: diagnosticsFrom(payload.diagnostics, protocol),
+    requested_boundary: nullableObject(payload.requested_boundary, "requested_boundary", protocol),
+    check_preview: previewFrom(payload.check_preview, protocol),
+    provenance: provenanceFrom(payload.provenance, protocol)
+  };
+  return outcome;
+}
+function validateCompileVersion(version, transport, engine, protocol) {
+  if (typeof version !== "number" || !Number.isSafeInteger(version) || version < 1) {
+    throw protocol("compile_version must be a positive safe integer");
+  }
+  if (version !== COMPILE_WIRE_VERSION) {
+    throw new NikaCompatibilityError(
+      COMPILE_CAPABILITY,
+      transport,
+      `Engine at ${engine} speaks compile wire ${version}; expected ${COMPILE_WIRE_VERSION}`
+    );
+  }
+}
+function tryParseJson(text) {
+  const trimmed = text.trim();
+  if (!trimmed) return void 0;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return void 0;
+  }
+}
+function excerpt(text) {
+  const flat = text.trim().replace(/\s+/g, " ");
+  return flat.length <= 240 ? flat : `${flat.slice(0, 240)}\u2026`;
+}
+function nullableObject(value, field, protocol) {
+  if (value === null) return null;
+  const object = machineObject(value);
+  if (!object) throw protocol(`${field} is neither an object nor null`);
+  return object;
+}
+function questionsFrom(value, protocol) {
+  if (!Array.isArray(value)) throw protocol("questions is not an array");
+  return value.map((entry) => {
+    const question = machineObject(entry);
+    if (!question || typeof question.key !== "string" || typeof question.label !== "string" || question.type !== "text" && question.type !== "literal" || typeof question.why !== "string" || typeof question.mandatory !== "boolean") {
+      throw protocol("a question lacks its key/label/type/why/mandatory shape");
+    }
+    return question;
+  });
+}
+function diagnosticsFrom(value, protocol) {
+  if (!Array.isArray(value)) throw protocol("diagnostics is not an array");
+  return value.map((entry) => {
+    const diagnostic = machineObject(entry);
+    if (!diagnostic || typeof diagnostic.kind !== "string" || !["applied", "missed", "unknown", "requiresHuman", "refused"].includes(diagnostic.kind) || typeof diagnostic.target !== "string" || typeof diagnostic.message !== "string") {
+      throw protocol("a diagnostic lacks its kind/target/message shape");
+    }
+    return diagnostic;
+  });
+}
+function previewFrom(value, protocol) {
+  if (value === null) return null;
+  const preview = machineObject(value);
+  if (!preview || preview.scope !== "sourceOnly" || !machineObject(preview.report)) {
+    throw protocol("check_preview lacks its scope/report shape");
+  }
+  return { ...preview, scope: preview.scope, report: preview.report };
+}
+function provenanceFrom(value, protocol) {
+  const provenance = machineObject(value);
+  if (!provenance || typeof provenance.compiler_version !== "string" || typeof provenance.spec_pin !== "string" || provenance.skeleton !== null && typeof provenance.skeleton !== "string" || provenance.cognition !== "deterministicOnly") {
+    throw protocol("provenance lacks its compiler_version/spec_pin/skeleton/cognition shape");
+  }
+  return provenance;
+}
+function writtenFrom(value, protocol) {
+  if (value !== null) {
+    throw protocol("the outcome claims a written destination the SDK never asked for");
+  }
+  return null;
+}
+
 // src/lib/sse/parser.ts
 var SseParseError = class extends Error {
   constructor(message, options) {
@@ -921,8 +1316,8 @@ async function* decodeSse(stream, limits, signal) {
 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(/[\\/]/);
+function workflowBasename(path4) {
+  const parts = path4.split(/[\\/]/);
   return parts[parts.length - 1] ?? "";
 }
 function hasControlChar(value) {
@@ -934,14 +1329,14 @@ function hasControlChar(value) {
   }
   return false;
 }
-function isLegacyWorkflowPath(path3) {
-  if (typeof path3 !== "string" || path3.length === 0) {
+function isLegacyWorkflowPath(path4) {
+  if (typeof path4 !== "string" || path4.length === 0) {
     return false;
   }
-  if (path3.endsWith("/") || path3.endsWith("\\")) {
+  if (path4.endsWith("/") || path4.endsWith("\\")) {
     return false;
   }
-  const base = workflowBasename(path3);
+  const base = workflowBasename(path4);
   return LEGACY_WORKFLOW_SUFFIXES.some((suffix) => base.endsWith(suffix));
 }
 function isCanonicalWorkflowFilename(basename) {
@@ -962,17 +1357,17 @@ function isCanonicalWorkflowFilename(basename) {
   }
   return basename.length > WORKFLOW_SUFFIX.length;
 }
-function isCanonicalWorkflowPath(path3) {
-  if (typeof path3 !== "string" || path3.length === 0) {
+function isCanonicalWorkflowPath(path4) {
+  if (typeof path4 !== "string" || path4.length === 0) {
     return false;
   }
-  if (hasControlChar(path3)) {
+  if (hasControlChar(path4)) {
     return false;
   }
-  if (path3.endsWith("/") || path3.endsWith("\\")) {
+  if (path4.endsWith("/") || path4.endsWith("\\")) {
     return false;
   }
-  return isCanonicalWorkflowFilename(workflowBasename(path3));
+  return isCanonicalWorkflowFilename(workflowBasename(path4));
 }
 function containedRelativeShape(value) {
   if (value.includes("\\") || value.startsWith("/")) {
@@ -1063,6 +1458,69 @@ var HttpTransport = class {
     }
     return captured.report;
   }
+  /**
+   * Stateless authoring through the authenticated Serve compile door.
+   * A remote connection never falls back to a local compile — the candidate
+   * must come from the server the caller connected to, or not exist.
+   */
+  async compile(request, options) {
+    const body = compileBody(request);
+    const timeoutMs = options.timeoutMs ?? this.options.requestTimeout;
+    const composed = compileSignal({ ...options, timeoutMs });
+    const signal = composed.signal;
+    try {
+      if (signal.aborted) throw new NikaTransportError(this.kind, "compile aborted");
+      const identity = this.remoteIdentity ?? await this.probeServerIdentity(signal);
+      if (!identity.supportedCapabilities.includes(COMPILE_CAPABILITY)) {
+        throw this.gap(
+          COMPILE_CAPABILITY,
+          "The connected engine does not advertise compile; the SDK never compiles locally as a substitute"
+        );
+      }
+      const path4 = "/v1/compile";
+      const response = await this.fetchResponse(path4, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body,
+        signal
+      }, false, true, false);
+      if (response.headers.get("Content-Type")?.split(";", 1)[0]?.trim().toLowerCase() !== "application/json") {
+        await discardResponse(response);
+        throw new NikaProtocolError(this.kind, "HTTP compile returned an invalid content-type");
+      }
+      const object = await this.readObservationObject(
+        response,
+        path4,
+        signal,
+        Math.min(this.options.machineBufferBytes, COMPILE_RESPONSE_MAX_BYTES),
+        false
+      );
+      if (signal.aborted) throw new NikaTransportError(this.kind, "compile aborted");
+      if (response.status !== 200) {
+        const error = machineObject(object.error);
+        if (response.ok || !error || typeof error.code !== "string" || !/^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(error.code) || error.code.includes(this.options.token) || typeof error.message !== "string" || Object.keys(object).some((key) => key !== "error")) {
+          throw new NikaProtocolError(this.kind, "HTTP compile returned a malformed refusal or non-contract status");
+        }
+        throw this.refused(path4, {
+          operation: "compile",
+          status: response.status,
+          refusal: { code: error.code, message: this.redact(error.message) }
+        });
+      }
+      return compilePayloadFrom(object, this.kind, this.options.url);
+    } catch (cause) {
+      if (signal.aborted) {
+        throw new NikaTransportError(
+          this.kind,
+          composed.timedOut() ? `compile timed out after ${timeoutMs} ms` : "compile aborted by caller",
+          { cause: cause instanceof Error ? cause : void 0 }
+        );
+      }
+      throw cause;
+    } finally {
+      composed.dispose();
+    }
+  }
   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) {
@@ -1182,14 +1640,14 @@ var HttpTransport = class {
   async schedule(workflow, options) {
     refuseLegacyContainedName(workflow);
     await this.ensureScheduleCapability();
-    const path3 = `/v1/schedules/${encodeURIComponent(options.id)}`;
+    const path4 = `/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, {
+    const object = await this.operationJson("schedule", path4, {
       method: "PUT",
       headers,
       body: JSON.stringify(scheduleBody(workflow, options))
@@ -1201,8 +1659,8 @@ var HttpTransport = class {
   }
   async scheduleStatus(id) {
     await this.ensureScheduleCapability();
-    const path3 = `/v1/schedules/${encodeURIComponent(id)}`;
-    const object = await this.operationJson("scheduleStatus", path3, {
+    const path4 = `/v1/schedules/${encodeURIComponent(id)}`;
+    const object = await this.operationJson("scheduleStatus", path4, {
       method: "GET",
       headers: { Accept: "application/json" }
     });
@@ -1535,16 +1993,16 @@ var HttpTransport = class {
     }
     return event;
   }
-  async inspectDurableJob(path3, expectedId, signal) {
+  async inspectDurableJob(path4, expectedId, signal) {
     let response;
     try {
-      response = await this.observationRequest(path3, { headers: { Accept: "application/json" }, signal });
+      response = await this.observationRequest(path4, { 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`);
+      throw new NikaTransportError(this.kind, `HTTP 404 for ${path4}; job was durably absent`);
     }
     if (isRetryableStatus(response.status)) {
       const retryAfterMilliseconds = retryAfter(response.headers.get("Retry-After"));
@@ -1554,9 +2012,9 @@ var HttpTransport = class {
         ...retryAfterMilliseconds !== void 0 ? { retryAfterMilliseconds } : {}
       };
     }
-    this.assertObservationResponse(response, path3, "application/json");
+    this.assertObservationResponse(response, path4, "application/json");
     try {
-      const object = await this.readObservationObject(response, path3);
+      const object = await this.readObservationObject(response, path4);
       return durableJob(object, expectedId, this.kind);
     } catch (cause) {
       if (cause instanceof NikaTransportError && !(cause instanceof NikaProtocolError)) {
@@ -1565,31 +2023,31 @@ var HttpTransport = class {
       throw cause;
     }
   }
-  assertObservationResponse(response, path3, contentType) {
+  assertObservationResponse(response, path4, contentType) {
     if (response.status === 204) {
       void discardResponse(response);
-      throw new NikaProtocolError(this.kind, `HTTP 204 permanently stopped observation for ${path3}`);
+      throw new NikaProtocolError(this.kind, `HTTP 204 permanently stopped observation for ${path4}`);
     }
     if (response.status === 401 || response.status === 403) {
       void discardResponse(response);
-      throw new NikaTransportError(this.kind, `HTTP ${response.status} authorization failure for ${path3}`);
+      throw new NikaTransportError(this.kind, `HTTP ${response.status} authorization failure for ${path4}`);
     }
     if (response.status !== 200) {
       void discardResponse(response);
-      throw new NikaTransportError(this.kind, `HTTP ${response.status} permanently failed ${path3}`);
+      throw new NikaTransportError(this.kind, `HTTP ${response.status} permanently failed ${path4}`);
     }
     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`
+        `HTTP ${path4} returned an invalid content-type`
       );
     }
   }
-  async readObservationObject(response, path3, signal) {
+  async readObservationObject(response, path4, signal, maxBytes = this.options.machineBufferBytes, useRequestTimeout = true) {
     if (!response.body) {
-      throw new NikaProtocolError(this.kind, `HTTP ${path3} omitted its JSON body`);
+      throw new NikaProtocolError(this.kind, `HTTP ${path4} omitted its JSON body`);
     }
     const reader = response.body.getReader();
     const chunks = [];
@@ -1599,38 +2057,38 @@ var HttpTransport = class {
       rejectBoundary = reject;
     });
     const abort = () => {
-      rejectBoundary(new NikaTransportError(this.kind, `HTTP ${path3} response body was aborted`));
+      rejectBoundary(new NikaTransportError(this.kind, `HTTP ${path4} response body was aborted`));
       void reader.cancel().catch(() => {
       });
     };
     signal?.addEventListener("abort", abort, { once: true });
-    const timer = setTimeout(() => {
+    const timer = useRequestTimeout ? setTimeout(() => {
       rejectBoundary(new NikaTransportError(
         this.kind,
         `HTTP response body timed out after ${this.options.requestTimeout}ms`
       ));
       void reader.cancel().catch(() => {
       });
-    }, this.options.requestTimeout);
+    }, this.options.requestTimeout) : void 0;
     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) {
+        if (bytes > maxBytes) {
           throw new NikaProtocolError(
             this.kind,
-            `HTTP ${path3} JSON exceeded ${this.options.machineBufferBytes} bytes`
+            `HTTP ${path4} JSON exceeded ${maxBytes} bytes`
           );
         }
         chunks.push(value2);
       }
     } catch (cause) {
       if (cause instanceof NikaProtocolError) throw cause;
-      throw new NikaTransportError(this.kind, `HTTP ${path3} response body reset`);
+      throw new NikaTransportError(this.kind, `HTTP ${path4} response body reset`);
     } finally {
-      clearTimeout(timer);
+      if (timer) clearTimeout(timer);
       signal?.removeEventListener("abort", abort);
       await reader.cancel().catch(() => {
       });
@@ -1646,7 +2104,7 @@ var HttpTransport = class {
     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`, {
+      throw new NikaProtocolError(this.kind, `HTTP ${path4} JSON was not valid UTF-8`, {
         cause: cause instanceof Error ? cause : void 0
       });
     }
@@ -1654,15 +2112,15 @@ var HttpTransport = class {
     try {
       value = JSON.parse(text);
     } catch (cause) {
-      throw new NikaProtocolError(this.kind, `HTTP ${path3} did not return valid JSON`, {
+      throw new NikaProtocolError(this.kind, `HTTP ${path4} 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`);
+    if (!object) throw new NikaProtocolError(this.kind, `HTTP ${path4} did not return an object`);
     return object;
   }
-  async observationRequest(path3, init, withTimeout = true) {
+  async observationRequest(path4, 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;
@@ -1671,7 +2129,7 @@ var HttpTransport = class {
     const headers = new Headers(init.headers);
     headers.set("Authorization", `Bearer ${this.options.token}`);
     try {
-      return await this.options.fetch(`${this.options.url}${path3}`, {
+      return await this.options.fetch(`${this.options.url}${path4}`, {
         ...init,
         headers,
         signal: controller?.signal ?? callerSignal
@@ -1730,8 +2188,18 @@ var HttpTransport = class {
     this.serverIdentity ??= this.probeServerIdentity();
     return this.serverIdentity;
   }
-  async probeServerIdentity() {
-    const health = await this.json("/health", { method: "GET" }, false);
+  async probeServerIdentity(signal) {
+    const outcome = await this.jsonOutcome(
+      "/health",
+      { method: "GET", signal },
+      false,
+      [200],
+      void 0,
+      false,
+      signal === void 0
+    );
+    if ("refusal" in outcome) throw this.refused("/health", outcome);
+    const health = outcome.object;
     if (health.status !== "ok" || health.service !== "nika-serve") {
       throw new NikaCompatibilityError(
         "engineIdentity",
@@ -1869,9 +2337,9 @@ var HttpTransport = class {
     delete report.execution_snapshot;
     return report;
   }
-  async json(path3, init, authenticated = true, acceptedStatuses = [200], operation) {
+  async json(path4, init, authenticated = true, acceptedStatuses = [200], operation) {
     const { object } = await this.jsonWithStatus(
-      path3,
+      path4,
       init,
       authenticated,
       acceptedStatuses,
@@ -1884,48 +2352,54 @@ var HttpTransport = class {
    * 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);
+  async jsonWithStatus(path4, init, authenticated, acceptedStatuses, operation) {
+    const outcome = await this.jsonOutcome(path4, init, authenticated, acceptedStatuses, operation);
+    if ("refusal" in outcome) throw this.refused(path4, outcome);
     return outcome;
   }
-  async jsonOutcome(path3, init, authenticated, acceptedStatuses, operation, strictRefusal = false) {
-    const response = await this.fetchResponse(path3, init, true, authenticated, false);
+  async jsonOutcome(path4, init, authenticated, acceptedStatuses, operation, strictRefusal = false, useRequestTimeout = true) {
+    const response = await this.fetchResponse(path4, init, useRequestTimeout, 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}`
+          `HTTP ${path4} returned non-contract status ${response.status}`
         );
       }
-      const refusal = operation === void 0 ? void 0 : await this.readRefusal(response, path3, strictRefusal);
+      const refusal = operation === void 0 ? void 0 : await this.readRefusal(response, path4, 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]`
+        `HTTP ${response.status} for ${path4}: [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`);
+      throw new NikaProtocolError(this.kind, `HTTP ${path4} returned an invalid content-type`);
     }
     return {
-      object: await this.readObservationObject(response, path3, init.signal ?? void 0),
+      object: await this.readObservationObject(
+        response,
+        path4,
+        init.signal ?? void 0,
+        this.options.machineBufferBytes,
+        useRequestTimeout
+      ),
       status: response.status
     };
   }
-  refused(path3, outcome) {
+  refused(path4, outcome) {
     const { code, message } = outcome.refusal;
     return new NikaOperationError(
       outcome.operation,
       this.kind,
       code,
-      `HTTP ${outcome.status} for ${path3}: ${code}` + (message ? ` (${message})` : ""),
+      `HTTP ${outcome.status} for ${path4}: ${code}` + (message ? ` (${message})` : ""),
       { status: outcome.status, machineCode: code }
     );
   }
@@ -1935,7 +2409,7 @@ var HttpTransport = class {
    * 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) {
+  async readRefusal(response, path4, strict = false) {
     const contentType = response.headers.get("Content-Type")?.split(";", 1)[0]?.trim().toLowerCase();
     if (contentType !== "application/json") {
       await discardResponse(response);
@@ -1943,7 +2417,7 @@ var HttpTransport = class {
     }
     let object;
     try {
-      object = await this.readObservationObject(response, path3);
+      object = await this.readObservationObject(response, path4);
     } catch {
       return void 0;
     }
@@ -1961,14 +2435,14 @@ var HttpTransport = class {
     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);
+  async operationJson(operation, path4, init) {
+    const response = await this.fetchResponse(path4, 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`);
+      throw new NikaProtocolError(this.kind, `HTTP ${path4} returned an invalid content-type`);
     }
-    const object = await this.readObservationObject(response, path3);
+    const object = await this.readObservationObject(response, path4);
     if (!response.ok) throw this.operationFailure(operation, response.status, object);
     return object;
   }
@@ -2013,16 +2487,17 @@ var HttpTransport = class {
       { status, machineCode: machine.code }
     );
   }
-  async fetchResponse(path3, init, withTimeout, authenticated = true, requireOk = true) {
+  async fetchResponse(path4, 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 });
+    if (callerSignal?.aborted) abort();
     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}`, {
+      const response = await this.options.fetch(`${this.options.url}${path4}`, {
         ...init,
         headers,
         signal: controller?.signal ?? callerSignal
@@ -2031,7 +2506,7 @@ var HttpTransport = class {
         await discardResponse(response);
         throw new NikaTransportError(
           this.kind,
-          `HTTP ${response.status} for ${path3}: [REDACTED]`
+          `HTTP ${response.status} for ${path4}: [REDACTED]`
         );
       }
       return response;
@@ -2477,15 +2952,65 @@ var NativeProcessTransport = class {
     const captured = await this.capture(args, options.signal);
     const report = reportObject(captured.stdout) ?? reportObject(stripEnginePrefix(captured.stderr));
     if (!report) {
-      const excerpt = diagnosticExcerpt(captured.stderr);
+      const excerpt2 = diagnosticExcerpt(captured.stderr);
       throw new NikaCompatibilityError(
         "check",
         this.kind,
-        `This engine did not emit the required JSON check report (exit ${captured.exitCode})` + (excerpt ? `: ${excerpt}` : "")
+        `This engine did not emit the required JSON check report (exit ${captured.exitCode})` + (excerpt2 ? `: ${excerpt2}` : "")
       );
     }
     return { ...report, exitCode: captured.exitCode };
   }
+  /**
+   * Authoring, not execution (issue #128): one bounded `nika compile --json`
+   * invocation, projected verbatim. The engine must advertise the compile
+   * capability — an engine from before the door is refused here, before any
+   * spawn, and there is never a TypeScript fallback. No destination is passed:
+   * the candidate stays source in memory, nothing is written, and no Run
+   * exists; `signal`/`timeoutMs` only stop this one child.
+   */
+  async compile(request, options) {
+    const composed = compileSignal(options);
+    let invocation;
+    try {
+      if (composed.signal?.aborted) {
+        throw new NikaTransportError(this.kind, "compile aborted");
+      }
+      invocation = await compileArgv(request);
+      const identity = composed.signal ? await verifyNikaEngine(this.options.engine, {
+        signal: composed.signal,
+        killGraceMs: COMPILE_KILL_GRACE_MS
+      }) : await this.ensureReady();
+      if (!identity.supportedCapabilities.includes(COMPILE_CAPABILITY)) {
+        throw new NikaCompatibilityError(
+          COMPILE_CAPABILITY,
+          this.kind,
+          `Engine ${identity.engineVersion} at ${this.options.engine.bin} does not advertise ${COMPILE_CAPABILITY} (advertised: ${identity.supportedCapabilities.join(", ") || "nothing"}); compile needs an engine that speaks the \`compile_version: 1\` wire (engine nika#1663). The SDK never compiles in TypeScript and never falls back to another channel`
+        );
+      }
+      const captured = await captureEngine(this.options.engine.bin, invocation.args, {
+        cwd: this.options.cwd,
+        signal: composed.signal,
+        bufferBytes: COMPILE_RESPONSE_MAX_BYTES,
+        transport: this.kind,
+        label: "compile",
+        killGraceMs: COMPILE_KILL_GRACE_MS
+      });
+      return compileOutcomeFrom(captured, this.kind, this.options.engine.bin);
+    } catch (cause) {
+      if (composed.signal?.aborted && cause instanceof NikaTransportError) {
+        throw new NikaTransportError(
+          this.kind,
+          composed.timedOut() ? `compile timed out after ${options.timeoutMs} ms` : "compile aborted by caller",
+          { cause }
+        );
+      }
+      throw cause;
+    } finally {
+      composed.dispose();
+      if (invocation) await removeCompileScratch(invocation);
+    }
+  }
   async startRun(workflow, options) {
     const inputs = literalInputs(options);
     const identity = await this.ensureReady();
@@ -2926,8 +3451,8 @@ function quotedProtocolError(cause, text, kind) {
   );
 }
 function quoted(verdict, text) {
-  const excerpt = diagnosticExcerpt(text);
-  return excerpt ? `${verdict}: ${excerpt}` : verdict;
+  const excerpt2 = diagnosticExcerpt(text);
+  return excerpt2 ? `${verdict}: ${excerpt2}` : verdict;
 }
 function runFlags(options, literal) {
   const flags = [];
@@ -3322,6 +3847,26 @@ var Nika = class {
   check(workflow, options = {}) {
     return this.transport.check(workflowName(workflow), options);
   }
+  /**
+   * Authoring (issue #128): describe work — or name an accepted workflow plus
+   * a change — and get the engine's checked candidate back, without running
+   * anything. `compile()` never means `run()`: the outcome is data (candidate
+   * source, questions, diagnostics, requested boundary, source-only Check
+   * preview, provenance), `incomplete`/`refused` resolve instead of throwing,
+   * and no workflow effect, approval or Proof exists.
+   *
+   * The candidate is ordinary `.nika` SOURCE. `run()` consumes a path,
+   * so the caller materializes the candidate and `run(path)` re-admits it —
+   * the compile preview is a review, never admission. Over `{ url }` this calls
+   * the authenticated Serve compile door, gated by its advertised capability;
+   * the SDK never compiles locally as a fallback.
+   */
+  async compile(request, options = {}) {
+    return this.transport.compile(
+      normalizeCompileRequest(request),
+      normalizeCompileOptions(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: