@warmhub/sdk-ts 0.44.1 → 0.46.0

package/dist/{chunk-KFNNTFDG.js → chunk-RX3ZL6P5.js}

@@ -51,6 +51,115 @@ function splitLocalPath(name) {
   return { shapePrefix: name.slice(0, idx), bareName: name.slice(idx + 1) };
 }
 
+// ../rules/src/component-cli-signing.ts
+var CLI_INSTALL_REPO_HEADER = "X-WarmHub-Install-Repo";
+var CLI_SIGNATURE_HEADER = "X-WarmHub-Signature";
+var CLI_TIMESTAMP_HEADER = "X-WarmHub-Timestamp";
+var RFC3986_UNRESERVED = /^[A-Za-z0-9\-._~]$/;
+function pctEncode(value) {
+  let out = "";
+  const bytes = new TextEncoder().encode(value);
+  for (const byte of bytes) {
+    const ch = String.fromCharCode(byte);
+    if (RFC3986_UNRESERVED.test(ch)) {
+      out += ch;
+    } else {
+      out += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+    }
+  }
+  return out;
+}
+function serializeQueryValue(value) {
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return JSON.stringify(value);
+  return value;
+}
+function cliMethodHasBody(method) {
+  return method === "POST" || method === "PUT" || method === "PATCH";
+}
+function canonicalCliQueryString(args) {
+  const entries = [];
+  for (const [k, v] of Object.entries(args)) {
+    if (v === void 0 || v === null) continue;
+    entries.push([k, serializeQueryValue(v)]);
+  }
+  entries.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  return entries.map(([k, v]) => `${pctEncode(k)}=${pctEncode(v)}`).join("&");
+}
+function bytesToHex(bytes) {
+  let out = "";
+  for (const byte of bytes) {
+    out += byte.toString(16).padStart(2, "0");
+  }
+  return out;
+}
+async function sha256Hex(text) {
+  const buf = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(text)
+  );
+  return bytesToHex(new Uint8Array(buf));
+}
+var EMPTY_BODY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+function buildCliSigningInput(input) {
+  return [
+    input.method,
+    input.path,
+    input.canonicalQuery,
+    input.installRepo,
+    input.bodyHash,
+    String(input.timestamp)
+  ].join("\n");
+}
+async function hmacSha256Hex(secret, message) {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(message)
+  );
+  return bytesToHex(new Uint8Array(signature));
+}
+var SIGNATURE_RE = /^sha256=([0-9a-f]{64})$/;
+var DEFAULT_TOLERANCE_SEC = 300;
+async function verifyCliRequest(input) {
+  const match = SIGNATURE_RE.exec(input.signature);
+  if (!match) return { ok: false, reason: "invalid-format" };
+  const providedHex = match[1];
+  const tolerance = input.toleranceSec ?? DEFAULT_TOLERANCE_SEC;
+  const skew = Math.abs(input.nowUnixSeconds - input.timestamp);
+  if (skew > tolerance) return { ok: false, reason: "expired" };
+  const bodyHash = input.body.length === 0 ? EMPTY_BODY_SHA256 : await sha256Hex(input.body);
+  const canonical = buildCliSigningInput({
+    method: input.method,
+    path: input.path,
+    canonicalQuery: canonicalCliQueryString(input.query),
+    installRepo: input.installRepo,
+    bodyHash,
+    timestamp: input.timestamp
+  });
+  const expectedHex = await hmacSha256Hex(input.secret, canonical);
+  if (!constantTimeEqualHex(providedHex, expectedHex)) {
+    return { ok: false, reason: "invalid-signature" };
+  }
+  return { ok: true };
+}
+function constantTimeEqualHex(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
 // ../rules/src/repo-auth-scopes.ts
 var REPO_AUTH_SCOPES = [
   "repo:read",
@@ -1442,6 +1551,23 @@ function inferKind(name, operation) {
 // src/stream-submit.ts
 var DEFAULT_STREAM_CHUNK_SIZE = DEFAULT_STREAM_APPEND_CHUNK_SIZE;
 var MAX_STREAM_APPEND_OPERATION_COUNT2 = MAX_STREAM_APPEND_OPERATION_COUNT;
+function streamAppendResultStatus(result) {
+  if (result.status === "failed") {
+    return "error";
+  }
+  return result.status === "noop" || result.operation === "noop" ? "noop" : "applied";
+}
+function countStreamAppendResultStatuses(results) {
+  const statusCounts = {
+    applied: 0,
+    noop: 0,
+    error: 0
+  };
+  for (const result of results) {
+    statusCounts[streamAppendResultStatus(result)]++;
+  }
+  return statusCounts;
+}
 var DEFAULT_RETRY_POLICY = {
   maxAttempts: 3,
   baseDelayMs: 250,
@@ -1509,12 +1635,41 @@ var PartialStreamSubmissionError = class extends Error {
     this.completedOperations = input.completedOperations;
   }
 };
+var AllStreamOperationsFailedError = class extends Error {
+  code = "STREAM_ALL_OPERATIONS_FAILED";
+  result;
+  operations;
+  statusCounts;
+  cause;
+  constructor(result) {
+    const primaryFailure = result.operations.find(
+      (operation) => operation.error !== void 0
+    )?.error;
+    super(
+      primaryFailure ? `All ${result.operationCount} stream operations failed: ${primaryFailure.message}` : `All ${result.operationCount} stream operations failed.`
+    );
+    this.name = "WarmHubError";
+    this.cause = primaryFailure;
+    this.result = result;
+    this.operations = result.operations;
+    this.statusCounts = result.statusCounts ?? {
+      applied: 0,
+      noop: 0,
+      error: result.operationCount
+    };
+  }
+};
 async function submitOperationsViaStream(client, args) {
   if (args.operations.length === 0) {
     throw new StreamValidationError(
       "At least one operation is required for stream submission."
     );
   }
+  if ((args.allocatedTokens?.length ?? 0) > 0 && args.streamId === void 0) {
+    throw new StreamValidationError(
+      "Manual stream resume with allocatedTokens requires the original streamId."
+    );
+  }
   const operations = args.operations.map((operation, index) => {
     let streamOperation;
     try {
@@ -1535,8 +1690,13 @@ async function submitOperationsViaStream(client, args) {
   const isManualResume = args.streamId !== void 0 || (args.allocatedTokens?.length ?? 0) > 0;
   const policy = isManualResume ? false : resolveRetryPolicy(args.retry);
   let allocatedTokens = args.allocatedTokens ?? [];
+  let createdByEmail;
   const chunkResults = [];
-  for (const chunk of chunkOperations(operations, chunkSize)) {
+  let sawAmbiguousAttempt = false;
+  for (const { operations: chunk, start: chunkStart } of chunkOperations(
+    operations,
+    chunkSize
+  )) {
     let attempt = 1;
     let priorAttemptAmbiguous = false;
     const chunkIsAtomic = chunk.length === 1;
@@ -1550,10 +1710,16 @@ async function submitOperationsViaStream(client, args) {
           streamId,
           componentId: args.componentId,
           committer: args.committer,
+          message: args.message,
           operations: chunk
         });
         allocatedTokens = appendResult.allocatedTokens;
-        chunkResults.push(...appendResult.results);
+        if (appendResult.createdByEmail !== void 0) {
+          createdByEmail = appendResult.createdByEmail;
+        }
+        chunkResults.push(
+          ...offsetChunkResultIndexes(appendResult.results, chunkStart)
+        );
         break;
       } catch (cause) {
         if (chunkResults.length === 0 && !priorAttemptAmbiguous && isDefiniteClientError(cause)) {
@@ -1563,18 +1729,23 @@ async function submitOperationsViaStream(client, args) {
           await sleep(computeBackoffDelayMs(attempt, policy));
           attempt += 1;
           priorAttemptAmbiguous = true;
+          sawAmbiguousAttempt = true;
           streamId = createStreamId();
           allocatedTokens = [];
           continue;
         }
-        const completedOperations = toSubmittedStreamResult(
-          {
-            operationCount: chunkResults.length
-          },
-          args.committer,
-          args.message,
-          chunkResults
-        ).operations;
+        const completedOperations = completedOperationsFrom(
+          toSubmittedStreamResult(
+            {
+              operationCount: chunkResults.length
+            },
+            args.committer,
+            createdByEmail,
+            args.message,
+            chunkResults,
+            operations
+          )
+        );
         throw new PartialStreamSubmissionError({
           cause,
           completedOperations
@@ -1582,20 +1753,54 @@ async function submitOperationsViaStream(client, args) {
       }
     }
   }
-  return toSubmittedStreamResult(
+  const result = toSubmittedStreamResult(
     {
       operationCount: chunkResults.length
     },
     args.committer,
+    createdByEmail,
     args.message,
-    chunkResults
+    chunkResults,
+    operations
   );
+  if (isAllSubmittedOperationsFailed(result, operations.length)) {
+    const failure = new AllStreamOperationsFailedError(result);
+    if (sawAmbiguousAttempt) {
+      throw new PartialStreamSubmissionError({
+        cause: failure,
+        completedOperations: completedOperationsFrom(result)
+      });
+    }
+    throw failure;
+  }
+  return result;
+}
+function isAllSubmittedOperationsFailed(result, submittedOperationCount) {
+  if (submittedOperationCount <= 0) {
+    return false;
+  }
+  const inputRowsFailed = /* @__PURE__ */ new Map();
+  for (const operation of result.operations) {
+    if (operation.opIndex === void 0 || operation.opIndex < 0 || operation.opIndex >= submittedOperationCount) {
+      continue;
+    }
+    inputRowsFailed.set(
+      operation.opIndex,
+      (inputRowsFailed.get(operation.opIndex) ?? true) && operation.status === "error"
+    );
+  }
+  return inputRowsFailed.size === submittedOperationCount && [...inputRowsFailed.values()].every(Boolean);
+}
+function completedOperationsFrom(result) {
+  return result.operations.filter((operation) => operation.status !== "error");
 }
 var DEFINITE_CLIENT_REJECT_CODES = /* @__PURE__ */ new Set([
   "UNAUTHENTICATED",
   "FORBIDDEN",
   "VALIDATION_ERROR",
   "SHAPE_MISMATCH",
+  "RESERVED_NAME",
+  "ILLEGAL_OP_SEQUENCE",
   "NOT_FOUND",
   "KIND_MISMATCH",
   "CONFLICT",
@@ -1625,13 +1830,18 @@ function isDefiniteClientError(cause) {
 }
 function isTransientStreamFailure(cause) {
   if (isDefiniteClientError(cause)) return false;
+  if (isFetchNetworkTypeError(cause)) return true;
   if (cause instanceof TypeError) return false;
   if (cause instanceof SyntaxError) return false;
   const inner = cause?.cause;
+  if (isFetchNetworkTypeError(inner)) return true;
   if (inner instanceof TypeError) return false;
   if (inner instanceof SyntaxError) return false;
   return true;
 }
+function isFetchNetworkTypeError(cause) {
+  return cause instanceof TypeError && /fetch/i.test(cause.message);
+}
 function computeBackoffDelayMs(attempt, policy) {
   const exponential = policy.baseDelayMs * 2 ** Math.max(0, attempt - 1);
   const jitter = Math.random() * policy.baseDelayMs;
@@ -1644,12 +1854,22 @@ var TOKEN_REF_REGEX = /[$#]\d+/;
 function stringHasTokenRef(value) {
   return typeof value === "string" && TOKEN_REF_REGEX.test(value);
 }
-function membersHaveTokenRef(members) {
-  if (!Array.isArray(members)) return false;
-  return members.some(stringHasTokenRef);
+function structuralValueHasTokenRef(value, seen = /* @__PURE__ */ new WeakSet()) {
+  if (stringHasTokenRef(value)) return true;
+  if (value !== null && typeof value === "object") {
+    if (seen.has(value)) return false;
+    seen.add(value);
+    if (Array.isArray(value)) {
+      return value.some((entry) => structuralValueHasTokenRef(entry, seen));
+    }
+    return Object.values(value).some(
+      (entry) => structuralValueHasTokenRef(entry, seen)
+    );
+  }
+  return false;
 }
 function opUsesTokens(op) {
-  return stringHasTokenRef(op.name) || stringHasTokenRef(op.wref) || stringHasTokenRef(op.about) || stringHasTokenRef(op.aboutWref) || membersHaveTokenRef(op.members);
+  return stringHasTokenRef(op.name) || stringHasTokenRef(op.wref) || structuralValueHasTokenRef(op.about) || stringHasTokenRef(op.aboutWref) || structuralValueHasTokenRef(op.members) || structuralValueHasTokenRef(op.data);
 }
 function createStreamId() {
   return globalThis.crypto?.randomUUID?.() ?? `stream-${Date.now()}-${Math.random()}`;
@@ -1667,27 +1887,213 @@ function normalizeChunkSize(chunkSize) {
 function chunkOperations(operations, chunkSize) {
   const chunks = [];
   for (let start = 0; start < operations.length; start += chunkSize) {
-    chunks.push(operations.slice(start, start + chunkSize));
+    chunks.push({
+      operations: operations.slice(start, start + chunkSize),
+      start
+    });
   }
   return chunks;
 }
-function toSubmittedStreamResult(writeResult, committer, message, results) {
+function offsetChunkResultIndexes(results, chunkStart) {
+  return results.map((result, index) => ({
+    ...result,
+    opIndex: chunkStart + (result.opIndex ?? index)
+  }));
+}
+function toSubmittedStreamResult(writeResult, committer, createdByEmail, message, results, operations) {
+  const statusCounts = countStreamAppendResultStatuses(results);
+  const partial = statusCounts.error > 0;
   return {
     committer,
+    ...createdByEmail !== void 0 ? { createdByEmail } : {},
     message,
     operationCount: writeResult.operationCount,
+    ...partial ? { partial, statusCounts } : {},
     operations: results.map((result) => ({
+      ...result.opIndex !== void 0 ? { opIndex: result.opIndex } : {},
       name: result.name ?? "",
       operation: result.operation === "revise" || result.operation === "retract" || result.operation === "noop" ? result.operation : "add",
       dataHash: result.dataHash ?? "",
       version: result.version ?? 0,
-      status: result.status,
+      status: streamAppendResultStatus(result),
       error: result.error,
+      ...result.status === "failed" && result.opIndex !== void 0 && operations[result.opIndex]?.name !== void 0 ? { submittedName: operations[result.opIndex]?.name } : {},
+      ...result.resolvedName !== void 0 ? { resolvedName: result.resolvedName } : {},
+      ...result.retryable !== void 0 ? { retryable: result.retryable } : {},
       ...result.warnings ? { warnings: result.warnings } : {}
     }))
   };
 }
 
+// src/component-cli.ts
+var SUPPORTED_METHODS = /* @__PURE__ */ new Set([
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE"
+]);
+var CliCallVerificationError = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "CliCallVerificationError";
+    this.reason = reason;
+  }
+};
+async function verifyCliCall(request, secrets, opts) {
+  const method = request.method.toUpperCase();
+  if (!SUPPORTED_METHODS.has(method)) {
+    throw new CliCallVerificationError(
+      "unsupported-method",
+      `Unsupported HTTP method "${request.method}" \u2014 component CLI dispatch only emits GET, POST, PUT, or PATCH`
+    );
+  }
+  const cliMethod = method;
+  const installRepo = request.headers.get(CLI_INSTALL_REPO_HEADER);
+  if (!installRepo) {
+    throw new CliCallVerificationError(
+      "missing-install-repo",
+      `Missing ${CLI_INSTALL_REPO_HEADER} header`
+    );
+  }
+  const hasSigning = isNonEmpty(secrets.CLI_SIGNING_SECRET);
+  const hasBearer = isNonEmpty(secrets.CLI_BEARER_TOKEN);
+  const hasApiKey = isNonEmpty(secrets.CLI_API_KEY);
+  const hasBasic = isNonEmpty(secrets.CLI_BASIC_USERNAME) && isNonEmpty(secrets.CLI_BASIC_PASSWORD);
+  if (!hasSigning && !hasBearer && !hasApiKey && !hasBasic) {
+    throw new CliCallVerificationError(
+      "no-scheme-configured",
+      "no-scheme-configured: need at least one of CLI_SIGNING_SECRET, CLI_BEARER_TOKEN, CLI_API_KEY, or CLI_BASIC_USERNAME + CLI_BASIC_PASSWORD"
+    );
+  }
+  const url = new URL(request.url);
+  const path = url.pathname;
+  let query;
+  let body;
+  let args;
+  if (!cliMethodHasBody(cliMethod)) {
+    query = Object.fromEntries(url.searchParams.entries());
+    body = "";
+    args = { ...query };
+  } else {
+    query = {};
+    body = await request.text();
+    let parsed;
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      throw new CliCallVerificationError(
+        "invalid-body",
+        "POST body is not valid JSON"
+      );
+    }
+    if (!isArgsRecord(parsed)) {
+      throw new CliCallVerificationError(
+        "invalid-body",
+        "POST body must be a JSON object of primitive args (string / number / boolean)"
+      );
+    }
+    args = parsed;
+  }
+  if (hasSigning) {
+    const signature = request.headers.get(CLI_SIGNATURE_HEADER);
+    if (!signature) {
+      throw new CliCallVerificationError(
+        "missing-signature",
+        `Missing ${CLI_SIGNATURE_HEADER} header`
+      );
+    }
+    const timestampHeader = request.headers.get(CLI_TIMESTAMP_HEADER);
+    if (!timestampHeader) {
+      throw new CliCallVerificationError(
+        "missing-timestamp",
+        `Missing ${CLI_TIMESTAMP_HEADER} header`
+      );
+    }
+    const timestamp = Number(timestampHeader);
+    if (!Number.isFinite(timestamp) || !Number.isInteger(timestamp)) {
+      throw new CliCallVerificationError(
+        "invalid-timestamp",
+        `${CLI_TIMESTAMP_HEADER} must be an integer unix seconds value; got "${timestampHeader}"`
+      );
+    }
+    const verification = await verifyCliRequest({
+      secret: secrets.CLI_SIGNING_SECRET,
+      method: cliMethod,
+      path,
+      query,
+      installRepo,
+      body,
+      signature,
+      timestamp,
+      nowUnixSeconds: opts?.nowUnixSeconds ?? Math.floor(Date.now() / 1e3),
+      toleranceSec: opts?.toleranceSec
+    });
+    if (!verification.ok) {
+      throw new CliCallVerificationError(
+        verification.reason,
+        `HMAC verification failed: ${verification.reason}`
+      );
+    }
+  }
+  if (hasBearer) {
+    const expected = `Bearer ${secrets.CLI_BEARER_TOKEN}`;
+    const provided = request.headers.get("authorization") ?? "";
+    if (!constantTimeEqual(provided, expected)) {
+      throw new CliCallVerificationError(
+        "invalid-bearer",
+        "invalid-bearer: bearer token mismatch"
+      );
+    }
+  }
+  if (hasApiKey) {
+    const headerName = isNonEmpty(secrets.CLI_API_KEY_HEADER) ? secrets.CLI_API_KEY_HEADER : "X-API-Key";
+    const provided = request.headers.get(headerName) ?? "";
+    if (!constantTimeEqual(provided, secrets.CLI_API_KEY)) {
+      throw new CliCallVerificationError(
+        "invalid-api-key",
+        `invalid-api-key: mismatch on header "${headerName}"`
+      );
+    }
+  }
+  if (hasBasic) {
+    const expected = `Basic ${btoa(`${secrets.CLI_BASIC_USERNAME}:${secrets.CLI_BASIC_PASSWORD}`)}`;
+    const provided = request.headers.get("authorization") ?? "";
+    if (!constantTimeEqual(provided, expected)) {
+      throw new CliCallVerificationError(
+        "invalid-basic",
+        "invalid-basic: basic auth mismatch"
+      );
+    }
+  }
+  return { method: cliMethod, installRepo, args };
+}
+function isNonEmpty(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function isArgsRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  for (const v of Object.values(value)) {
+    if (v === void 0) continue;
+    if (typeof v === "string") continue;
+    if (typeof v === "number") continue;
+    if (typeof v === "boolean") continue;
+    return false;
+  }
+  return true;
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
 // src/operation-builder.ts
 var OperationBuilder = class {
   ops = [];
@@ -1952,7 +2358,7 @@ var OperationBuilder = class {
   /**
    * Validate, submit, and seal the builder.
    *
-   * A successful call submits operations through the same stream path as `client.commit.apply` and makes the builder single-use. Validation failures throw before any server request is made. Ambiguous multi-chunk failures surface as `PartialStreamSubmissionError`.
+   * A successful call submits operations through the same stream path as `client.commit.apply` and makes the builder single-use. Validation failures throw before any server request is made. Ambiguous multi-chunk failures surface as `PartialStreamSubmissionError`; deterministic all-failed batches surface as `AllStreamOperationsFailedError` with per-op failure data.
    *
    * @param params.client WarmHub client or compatible stream client used for submission.
    * @param params.message Optional commit message.
@@ -2183,7 +2589,7 @@ function preflightCheckRevise(kind, name, data) {
 function normalizeWref(wref) {
   return wref.replace(/@(?:v\d+|HEAD|ALL)$/i, "");
 }
-var SDK_VERSION = "0.44.1" ;
+var SDK_VERSION = "0.46.0" ;
 var DEFAULT_API_URL = "https://api.warmhub.ai";
 var UNBATCHED_TRPC_PATHS = /* @__PURE__ */ new Set([
   "repo.shapeInstanceCounts",
@@ -2307,13 +2713,22 @@ var WarmHubError = class extends Error {
    * responses and other backend signals that carry a Retry-After header.
    */
   retryAfter;
-  constructor(code, message, status, hint, retryAfter) {
+  /**
+   * Backend domain code from the response body. Set iff the backend wire
+   * carried a structured `error.code` string. Use this when the question is
+   * "did the backend specifically say this?". For best-effort labelling that
+   * also covers SDK-local transport codes (`NETWORK`, `CANCELLED`, the
+   * generic `BACKEND` fallback), branch on {@link code} or {@link kind}.
+   */
+  backendCode;
+  constructor(code, message, status, hint, retryAfter, backendCode) {
     super(message);
     this.name = "WarmHubError";
     this.code = code;
     this.status = status;
     this.hint = hint;
     this.retryAfter = retryAfter;
+    this.backendCode = backendCode;
   }
   get kind() {
     return this.code;
@@ -2334,13 +2749,15 @@ function toWarmHubError(error) {
       return error.cause;
     }
     const data = error.data;
+    const wireCode = data?.warmhub?.code;
     const message = data?.warmhub?.message ?? sanitizeErrorMessage(error.message);
     return new WarmHubError(
-      data?.warmhub?.code ?? "BACKEND",
+      wireCode ?? "BACKEND",
       message,
       data?.warmhub?.status,
       data?.warmhub?.hint,
-      data?.warmhub?.retryAfter
+      data?.warmhub?.retryAfter,
+      wireCode
     );
   }
   if (error instanceof Error) {
@@ -2351,7 +2768,8 @@ function toWarmHubError(error) {
         sanitizeErrorMessage(error.message),
         typeof warmhubLike.status === "number" ? warmhubLike.status : void 0,
         typeof warmhubLike.hint === "string" ? warmhubLike.hint : void 0,
-        typeof warmhubLike.retryAfter === "number" ? warmhubLike.retryAfter : void 0
+        typeof warmhubLike.retryAfter === "number" ? warmhubLike.retryAfter : void 0,
+        typeof warmhubLike.backendCode === "string" ? warmhubLike.backendCode : void 0
       );
     }
     if (error.name === "AbortError") {
@@ -2393,6 +2811,57 @@ function isConnectionError(error) {
 function connectionErrorMessage(url) {
   return `Unable to connect to ${url}. Is the computer able to access the url?`;
 }
+function parseSemver(value) {
+  const match = value.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/);
+  if (!match) return void 0;
+  let prerelease = [];
+  if (match[4]) {
+    prerelease = match[4].split(".");
+    for (const id of prerelease) {
+      if (id.length === 0) return void 0;
+      if (/^\d+$/.test(id) && id.length > 1 && id.startsWith("0")) {
+        return void 0;
+      }
+    }
+  }
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease
+  };
+}
+function comparePrereleaseIdentifiers(a, b) {
+  const aNum = /^\d+$/.test(a);
+  const bNum = /^\d+$/.test(b);
+  if (aNum && bNum) return Number(a) - Number(b);
+  if (aNum && !bNum) return -1;
+  if (!aNum && bNum) return 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function comparePrerelease(a, b) {
+  if (a.length === 0 && b.length > 0) return 1;
+  if (a.length > 0 && b.length === 0) return -1;
+  const max = Math.max(a.length, b.length);
+  for (let i = 0; i < max; i += 1) {
+    const aPart = a[i];
+    const bPart = b[i];
+    if (aPart === void 0) return -1;
+    if (bPart === void 0) return 1;
+    const cmp = comparePrereleaseIdentifiers(aPart, bPart);
+    if (cmp !== 0) return cmp;
+  }
+  return 0;
+}
+function sdkVersionIsBelowMinimum(version, minimum) {
+  const v = parseSemver(version);
+  const m = parseSemver(minimum);
+  if (!v || !m) return false;
+  if (v.major !== m.major) return v.major < m.major;
+  if (v.minor !== m.minor) return v.minor < m.minor;
+  if (v.patch !== m.patch) return v.patch < m.patch;
+  return comparePrerelease(v.prerelease, m.prerelease) < 0;
+}
 var WarmHubClient = class _WarmHubClient {
   /**
    * The resolved API base URL the client issues requests against. Defaults to
@@ -2403,6 +2872,11 @@ var WarmHubClient = class _WarmHubClient {
   accessToken;
   functionLogMode;
   getToken;
+  // Cached promise for diagnostics.assertCompatible(). Stored at instance
+  // level so a successful check is reused across calls, and a failed check
+  // is also cached so a too-old SDK keeps reporting the same actionable
+  // error rather than re-hitting the network. Cleared on construction.
+  compatibilityCheck;
   /**
    * Authentication helpers for browser sign-in flows, session checks, and token diagnostics.
    */
@@ -2521,6 +2995,41 @@ var WarmHubClient = class _WarmHubClient {
       } catch (error) {
         throw toWarmHubError(error);
       }
+    },
+    /**
+     * Verify the installed SDK is at or above the backend's advertised
+     * minimum supported version, throwing a `WarmHubError` with a clear
+     * "upgrade to >=X" message when it is not.
+     *
+     * Call this once at startup (e.g. immediately after constructing the
+     * client) to fail fast on SDK version skew, rather than discovering a
+     * removed route deep in the commit pipeline as an opaque error.
+     * The result is cached on the client instance — repeated calls reuse
+     * the first network round-trip and re-throw the same error if too old.
+     *
+     * @see https://github.com/warmhub/warmhub-app/issues/3081
+     */
+    assertCompatible: () => {
+      if (this.compatibilityCheck) return this.compatibilityCheck;
+      const promise = (async () => {
+        const capabilities = await this.diagnostics.capabilities();
+        if (sdkVersionIsBelowMinimum(SDK_VERSION, capabilities.minSupportedSdk)) {
+          throw new WarmHubError(
+            "VALIDATION_ERROR",
+            `@warmhub/sdk-ts ${SDK_VERSION} is older than the backend's minimum supported SDK (${capabilities.minSupportedSdk}). Upgrade to >=${capabilities.minSupportedSdk}.`,
+            400,
+            `Run: npm install @warmhub/sdk-ts@latest (or your package manager's equivalent).`
+          );
+        }
+      })();
+      this.compatibilityCheck = promise;
+      void promise.catch((error) => {
+        if (isWarmHubError(error) && error.code === "VALIDATION_ERROR") return;
+        if (this.compatibilityCheck === promise) {
+          this.compatibilityCheck = void 0;
+        }
+      });
+      return promise;
     }
   };
   /**
@@ -2710,7 +3219,7 @@ var WarmHubClient = class _WarmHubClient {
   /**
    * High-level write surface for submitting WarmHub operations through the commit pipeline.
    *
-   * @see https://docs.warmhub.ai/sdk/commit-vs-builder/
+   * @see https://docs.warmhub.ai/sdk/write-methods/
    */
   commit = {
     /**
@@ -2718,7 +3227,7 @@ var WarmHubClient = class _WarmHubClient {
      *
      * This is the primary write path for SDK callers. It streams operations to the backend, preserves server-side per-operation results, supports chunking for large submissions, and can attribute writes to a committer wref or installed component.
      *
-     * Simple first-chunk transport failures are retried by default. Multi-chunk ambiguous failures are surfaced as `PartialStreamSubmissionError` so callers can inspect repository state before deciding whether to resume or retry. See [Transient Retry](/sdk/transient-retry/) for the full retry and partial-submission rules.
+     * Simple first-chunk transport failures are retried by default. Ambiguous failures surface as `PartialStreamSubmissionError`, including the case where an ambiguous attempt is followed by an all-failed retry; inspect `error.cause` for the underlying `AllStreamOperationsFailedError` or backend error. Deterministic all-failed submissions without prior ambiguity throw `AllStreamOperationsFailedError` directly so callers can inspect per-operation failure rows. Validation, auth, conflict, rate-limit, and other definite backend failures surface as `WarmHubError`. See [Transient Retry](/sdk/transient-retry/) for the full retry and partial-submission rules.
      *
      * Writing to an archived organization or repository fails with an `ARCHIVED` error before any operations are applied.
      *
@@ -2748,7 +3257,7 @@ var WarmHubClient = class _WarmHubClient {
           operations
         });
       } catch (error) {
-        if (error instanceof PartialStreamSubmissionError) {
+        if (error instanceof PartialStreamSubmissionError || error instanceof AllStreamOperationsFailedError) {
           throw error;
         }
         throw toWarmHubError(error);
@@ -3019,7 +3528,7 @@ var WarmHubClient = class _WarmHubClient {
      *
      * The returned `total` is the sum of active shapes, things, and assertions. Use this when billing, quota checks, health reports, or per-shape breakdowns need single-repo stats.
      *
-     * The per-shape breakdown counts active things by shape; assertions are not included in that map.
+     * The per-shape breakdown counts active things and assertions by shape.
      */
     getStats: async (orgName, repoName) => {
       try {
@@ -4718,6 +5227,7 @@ var WarmHubClient = class _WarmHubClient {
     if (!response.ok) {
       let message = `Request failed with status ${response.status}`;
       let code = httpStatusToWarmHubCode(response.status);
+      let backendCode;
       let hint;
       let retryAfter;
       try {
@@ -4727,6 +5237,7 @@ var WarmHubClient = class _WarmHubClient {
         }
         if (typeof body.error?.code === "string") {
           code = body.error.code;
+          backendCode = body.error.code;
         }
         if (typeof body.error?.hint === "string") {
           hint = body.error.hint;
@@ -4736,7 +5247,14 @@ var WarmHubClient = class _WarmHubClient {
         }
       } catch {
       }
-      throw new WarmHubError(code, message, response.status, hint, retryAfter);
+      throw new WarmHubError(
+        code,
+        message,
+        response.status,
+        hint,
+        retryAfter,
+        backendCode
+      );
     }
     return response;
   }
@@ -4850,6 +5368,6 @@ function isAbortError(error) {
   return error instanceof Error && error.name === "AbortError";
 }
 
-export { CONTENT_FIELD_LIMIT_ERROR, DEFAULT_API_URL, DEFAULT_STREAM_CHUNK_SIZE, MAX_CONTENT_FIELD_BYTES, MAX_STREAM_APPEND_OPERATION_COUNT2 as MAX_STREAM_APPEND_OPERATION_COUNT, OperationBuilder, PartialStreamSubmissionError, SDK_VERSION, WarmHubClient, WarmHubError, connectionErrorMessage, contentFieldLimitError, isConnectionError, isRetryable, isWarmHubError, normalizeWref, resolveFunctionLogMode, sanitizeErrorMessage, submitOperationsViaStream, toWarmHubError, validateAgainstShape };
-//# sourceMappingURL=chunk-KFNNTFDG.js.map
-//# sourceMappingURL=chunk-KFNNTFDG.js.map
+export { AllStreamOperationsFailedError, CLI_INSTALL_REPO_HEADER, CLI_SIGNATURE_HEADER, CLI_TIMESTAMP_HEADER, CONTENT_FIELD_LIMIT_ERROR, CliCallVerificationError, DEFAULT_API_URL, DEFAULT_STREAM_CHUNK_SIZE, MAX_CONTENT_FIELD_BYTES, MAX_STREAM_APPEND_OPERATION_COUNT2 as MAX_STREAM_APPEND_OPERATION_COUNT, OperationBuilder, PartialStreamSubmissionError, SDK_VERSION, WarmHubClient, WarmHubError, connectionErrorMessage, contentFieldLimitError, countStreamAppendResultStatuses, isConnectionError, isRetryable, isWarmHubError, normalizeWref, resolveFunctionLogMode, sanitizeErrorMessage, sdkVersionIsBelowMinimum, streamAppendResultStatus, submitOperationsViaStream, toWarmHubError, validateAgainstShape, verifyCliCall };
+//# sourceMappingURL=chunk-RX3ZL6P5.js.map
+//# sourceMappingURL=chunk-RX3ZL6P5.js.map