rainskills 0.1.41 → 0.1.43

package/bin/delivery-probe.js

@@ -0,0 +1,306 @@
+"use strict";
+
+const dns = require("node:dns").promises;
+const http = require("node:http");
+const https = require("node:https");
+const net = require("node:net");
+
+const MAX_REDIRECTS = 3;
+const CONNECT_TIMEOUT_MS = 5_000;
+const TOTAL_TIMEOUT_MS = 15_000;
+const MAX_BODY_BYTES = 256 * 1024;
+const MAX_URL_LENGTH = 4_096;
+const POLICY_VERSION = "rainskills.delivery-probe-policy.v1";
+
+function isPublicIpv4(address) {
+  const parts = address.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+    return false;
+  }
+  const [a, b] = parts;
+  if (a === 0 || a === 10 || a === 127 || a >= 224) return false;
+  if (a === 100 && b >= 64 && b <= 127) return false;
+  if (a === 169 && b === 254) return false;
+  if (a === 172 && b >= 16 && b <= 31) return false;
+  if (a === 192 && (b === 0 || b === 168)) return false;
+  if (a === 192 && b === 0 && parts[2] === 2) return false;
+  if (a === 198 && (b === 18 || b === 19 || b === 51)) return false;
+  if (a === 203 && b === 0 && parts[2] === 113) return false;
+  return true;
+}
+
+function ipv6Parts(address) {
+  let normalized = address.toLowerCase().split("%", 1)[0];
+  const dotted = normalized.match(/(\d+\.\d+\.\d+\.\d+)$/);
+  if (dotted) {
+    if (!net.isIPv4(dotted[1])) return null;
+    const octets = dotted[1].split(".").map(Number);
+    normalized = `${normalized.slice(0, -dotted[1].length)}${((octets[0] << 8) | octets[1]).toString(16)}:${((octets[2] << 8) | octets[3]).toString(16)}`;
+  }
+  const halves = normalized.split("::");
+  if (halves.length > 2) return null;
+  const left = halves[0] ? halves[0].split(":") : [];
+  const right = halves.length === 2 && halves[1] ? halves[1].split(":") : [];
+  const missing = 8 - left.length - right.length;
+  if ((halves.length === 1 && missing !== 0) || missing < 0) return null;
+  const tokens = [...left, ...Array(missing).fill("0"), ...right];
+  if (tokens.length !== 8 || tokens.some((token) => !/^[0-9a-f]{1,4}$/.test(token))) return null;
+  return tokens.map((token) => Number.parseInt(token, 16));
+}
+
+function embeddedIpv4(parts, offset) {
+  return [
+    parts[offset] >> 8,
+    parts[offset] & 0xff,
+    parts[offset + 1] >> 8,
+    parts[offset + 1] & 0xff,
+  ].join(".");
+}
+
+function isPublicIpv6(address) {
+  const parts = ipv6Parts(address);
+  if (!parts) return false;
+  if (parts.every((part) => part === 0)) return false;
+  if (parts.slice(0, 7).every((part) => part === 0) && parts[7] === 1) return false;
+  if ((parts[0] & 0xfe00) === 0xfc00) return false;
+  if ((parts[0] & 0xffc0) === 0xfe80) return false;
+  if ((parts[0] & 0xff00) === 0xff00) return false;
+  if (parts[0] === 0x0100 && parts.slice(1, 4).every((part) => part === 0)) return false;
+  if (parts[0] === 0x2001 && parts[1] === 0x0000) return false;
+  if (parts[0] === 0x2001 && (parts[1] & 0xfff0) === 0x0010) return false;
+  if (parts[0] === 0x2001 && (parts[1] & 0xfff0) === 0x0020) return false;
+  if (parts[0] === 0x2001 && parts[1] === 0x0002) return false;
+  if (parts[0] === 0x2001 && parts[1] === 0x0db8) return false;
+  if ((parts[0] & 0xfff0) === 0x3ff0) return false;
+  if (parts.slice(0, 5).every((part) => part === 0) && parts[5] === 0xffff) {
+    return isPublicIpv4(embeddedIpv4(parts, 6));
+  }
+  if (parts.slice(0, 6).every((part) => part === 0)) {
+    return isPublicIpv4(embeddedIpv4(parts, 6));
+  }
+  if (parts[0] === 0x0064 && parts[1] === 0xff9b && parts.slice(2, 6).every((part) => part === 0)) {
+    return isPublicIpv4(embeddedIpv4(parts, 6));
+  }
+  if (parts[0] === 0x2002) return isPublicIpv4(embeddedIpv4(parts, 1));
+  return true;
+}
+
+function isPublicAddress(address) {
+  const family = net.isIP(address);
+  if (family === 4) return isPublicIpv4(address);
+  if (family === 6) return isPublicIpv6(address);
+  return false;
+}
+
+function normalizedHostname(url) {
+  return url.hostname.replace(/^\[|\]$/g, "");
+}
+
+async function defaultResolveHost(hostname) {
+  const records = await dns.lookup(hostname, { all: true, verbatim: true });
+  return records.map((record) => record.address);
+}
+
+function defaultRequestUrl(url, {
+  method,
+  address,
+  headers,
+  connectTimeoutMs = CONNECT_TIMEOUT_MS,
+  totalTimeoutMs = TOTAL_TIMEOUT_MS,
+  maxBodyBytes = MAX_BODY_BYTES,
+}) {
+  const client = url.protocol === "https:" ? https : http;
+  return new Promise((resolve) => {
+    let settled = false;
+    let connectTimer;
+    let totalTimer;
+    const finish = (result, request) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(connectTimer);
+      clearTimeout(totalTimer);
+      if (request && !request.destroyed) request.destroy();
+      resolve(result);
+    };
+    const request = client.request(url, {
+      method,
+      headers,
+      redirect: "manual",
+      lookup: (_hostname, options, callback) => {
+        const family = net.isIP(address);
+        if (options && options.all) {
+          callback(null, [{ address, family }]);
+          return;
+        }
+        callback(null, address, family);
+      },
+    }, (response) => {
+      const statusCode = response.statusCode || 0;
+      const location = response.headers.location;
+      const contentType = String(response.headers["content-type"] || "");
+      const contentLength = Number(response.headers["content-length"] || 0);
+      if (Number.isFinite(contentLength) && contentLength > maxBodyBytes) {
+        response.resume();
+        finish({ error: "body_too_large" }, request);
+        return;
+      }
+      if (method === "HEAD" || (statusCode >= 300 && statusCode < 400)) {
+        response.resume();
+        finish({ statusCode, location, contentType, bodyBytes: 0 }, request);
+        return;
+      }
+      let bodyBytes = 0;
+      response.on("data", (chunk) => {
+        bodyBytes += chunk.length;
+        if (bodyBytes > maxBodyBytes) finish({ error: "body_too_large" }, request);
+      });
+      response.on("end", () => finish({ statusCode, location, contentType, bodyBytes }, request));
+      response.on("error", () => finish({ error: "response_error" }, request));
+    });
+    request.on("socket", (socket) => {
+      if (!socket.connecting) return;
+      connectTimer = setTimeout(() => finish({ error: "timeout" }, request), connectTimeoutMs);
+      socket.once(url.protocol === "https:" ? "secureConnect" : "connect", () => clearTimeout(connectTimer));
+    });
+    request.on("error", (error) => finish({ error: error.code === "ETIMEDOUT" ? "timeout" : "request_error" }, request));
+    totalTimer = setTimeout(() => finish({ error: "timeout" }, request), totalTimeoutMs);
+    request.end();
+  });
+}
+
+function parseTarget(value) {
+  if (typeof value !== "string" || !value || value.length > MAX_URL_LENGTH) return null;
+  let url;
+  try {
+    url = new URL(value);
+  } catch (_error) {
+    return null;
+  }
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) return null;
+  return url;
+}
+
+function createDeliveryProbe({
+  resolveHost = defaultResolveHost,
+  requestUrl = defaultRequestUrl,
+} = {}) {
+  return async function probe(input) {
+    const allowedInputKeys = new Set(["policy_version", "url", "method"]);
+    const validShape = input && typeof input === "object" && !Array.isArray(input)
+      && Object.keys(input).every((key) => allowedInputKeys.has(key));
+    const method = input?.method;
+    let current = parseTarget(input?.url);
+    const candidateUrl = current ? current.href : String(input?.url || "");
+    if (!validShape || !current || !["HEAD", "GET"].includes(method) || input?.policy_version !== POLICY_VERSION) {
+      return { policy_version: POLICY_VERSION, status: "rejected", reason: "unsafe_url_or_method", candidate_url: candidateUrl };
+    }
+    const redirects = [];
+    let prefetchedResolution = null;
+
+    const resolveSafeAddresses = async (url) => {
+      const hostname = normalizedHostname(url);
+      try {
+        const addresses = net.isIP(hostname) ? [hostname] : await resolveHost(hostname);
+        if (!Array.isArray(addresses) || !addresses.length || addresses.some((address) => !isPublicAddress(address))) {
+          return { error: "non_public_address" };
+        }
+        return { addresses };
+      } catch (_error) {
+        return { error: "dns_error" };
+      }
+    };
+
+    for (let redirectCount = 0; redirectCount <= MAX_REDIRECTS; redirectCount += 1) {
+      const resolved = prefetchedResolution || await resolveSafeAddresses(current);
+      prefetchedResolution = null;
+      if (resolved.error) {
+        return {
+          policy_version: POLICY_VERSION,
+          status: resolved.error === "dns_error" ? "failed" : "rejected",
+          reason: resolved.error,
+          candidate_url: candidateUrl,
+        };
+      }
+
+      const headers = Object.freeze({ Accept: "*/*", "User-Agent": "rainskills-delivery-probe/1" });
+      const response = await requestUrl(current, {
+        method,
+        address: resolved.addresses[0],
+        headers,
+        connectTimeoutMs: CONNECT_TIMEOUT_MS,
+        totalTimeoutMs: TOTAL_TIMEOUT_MS,
+        maxBodyBytes: MAX_BODY_BYTES,
+      });
+      if (response?.error) {
+        return { policy_version: POLICY_VERSION, status: "failed", reason: response.error, candidate_url: candidateUrl };
+      }
+
+      const statusCode = Number(response?.statusCode || 0);
+      if (statusCode >= 300 && statusCode < 400) {
+        if (!response.location) {
+          return { policy_version: POLICY_VERSION, status: "failed", reason: "redirect_without_location", candidate_url: candidateUrl };
+        }
+        if (redirectCount === MAX_REDIRECTS) {
+          return { policy_version: POLICY_VERSION, status: "failed", reason: "too_many_redirects", candidate_url: candidateUrl };
+        }
+        let next;
+        try {
+          next = parseTarget(new URL(response.location, current).href);
+        } catch (_error) {
+          next = null;
+        }
+        if (!next) return { policy_version: POLICY_VERSION, status: "rejected", reason: "unsafe_redirect", candidate_url: candidateUrl };
+        const nextResolved = await resolveSafeAddresses(next);
+        if (nextResolved.error) {
+          return { policy_version: POLICY_VERSION, status: "rejected", reason: "unsafe_redirect", candidate_url: candidateUrl };
+        }
+        if (current.protocol === "https:" && next.protocol !== "https:") {
+          return { policy_version: POLICY_VERSION, status: "rejected", reason: "redirect_downgrade", candidate_url: candidateUrl };
+        }
+        const sameEndpoint = next.host === current.host && next.protocol === current.protocol;
+        const httpUpgrade = current.protocol === "http:"
+          && next.protocol === "https:"
+          && normalizedHostname(next) === normalizedHostname(current)
+          && (current.port || "80") === "80"
+          && (next.port || "443") === "443";
+        if (!sameEndpoint && !httpUpgrade) {
+          return {
+            policy_version: POLICY_VERSION,
+            status: "manual_validation_required",
+            reason: "cross_host_redirect",
+            candidate_url: candidateUrl,
+            redirect_target: next.href,
+          };
+        }
+        redirects.push(next.href);
+        current = next;
+        prefetchedResolution = nextResolved;
+        continue;
+      }
+
+      return {
+        policy_version: POLICY_VERSION,
+        status: statusCode >= 200 && statusCode < 400 ? "verified" : "failed",
+        reason: statusCode >= 200 && statusCode < 400 ? null : "http_status",
+        candidate_url: candidateUrl,
+        final_url: current.href,
+        status_code: statusCode,
+        content_type: String(response.contentType || ""),
+        body_bytes: Number(response.bodyBytes || 0),
+        redirects,
+      };
+    }
+    return { policy_version: POLICY_VERSION, status: "failed", reason: "too_many_redirects", candidate_url: candidateUrl };
+  };
+}
+
+module.exports = {
+  CONNECT_TIMEOUT_MS,
+  MAX_BODY_BYTES,
+  MAX_REDIRECTS,
+  TOTAL_TIMEOUT_MS,
+  POLICY_VERSION,
+  createDeliveryProbe,
+  defaultRequestUrl,
+  isPublicAddress,
+};

package/bin/handoff-context.js

@@ -0,0 +1,151 @@
+"use strict";
+
+const { createHash } = require("node:crypto");
+
+const SCHEMA = "rainskills.handoff-context.v1";
+const PROFILE = new Set(["cli", "embedded"]);
+const SOURCE_KIND = new Set(["source", "image", "package", "template", null]);
+const RUNTIME_STATE = new Set([
+  "topology_missing", "topology_building", "runtime_unhealthy", "runtime_healthy",
+  "capacity_blocked", "code_or_build_handoff_needed",
+]);
+const NEXT_PHASE = new Set(["init", "bootstrap", "troubleshoot", "verify", "stop"]);
+const CONTEXT_KEYS = Object.freeze([
+  "schema", "producer", "profile", "observed_at", "enterprise_id", "team_id",
+  "team_name", "region_name", "app_id", "app_name", "runtime_fingerprint",
+  "identity_fingerprint", "snapshot_revision", "source_kind", "runtime_state",
+  "next_phase", "invalidation_reason",
+]);
+const CREATE_KEYS = new Set([
+  "producer", "profile", "observed_at", "enterprise_id", "team_id", "team_name",
+  "region_name", "app_id", "app_name", "endpoint", "runtime_revision",
+  "snapshot_revision", "source_kind", "runtime_state", "next_phase", "invalidation_reason",
+]);
+const SENSITIVE_KEY = /(?:jwt|token|password|secret|credential|confirmation|raw.?log|tool.?output)/i;
+const SHA256 = /^[a-f0-9]{64}$/;
+const SKILL_ID = /^rainbond-[a-z0-9-]+$/;
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+  }
+  return value;
+}
+
+function fingerprint(value) {
+  return createHash("sha256").update(JSON.stringify(canonical(value))).digest("hex");
+}
+
+function assertString(value, label, nullable = false) {
+  if (nullable && value === null) return;
+  if (typeof value !== "string" || value.length === 0) throw new Error(`${label} must be a non-empty string`);
+}
+
+function runtimeIdentity(value) {
+  return {
+    profile: value.profile,
+    endpoint: value.endpoint,
+    runtime_revision: value.runtime_revision,
+  };
+}
+
+function workspaceIdentity(value) {
+  return {
+    enterprise_id: value.enterprise_id,
+    team_id: value.team_id,
+    region_name: value.region_name,
+    app_id: value.app_id,
+  };
+}
+
+function validateCreationInput(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("handoff input must be an object");
+  for (const key of Object.keys(value)) {
+    if (SENSITIVE_KEY.test(key)) throw new Error("sensitive handoff fields are forbidden");
+    if (!CREATE_KEYS.has(key)) throw new Error(`unknown handoff field: ${key}`);
+  }
+  if (!SKILL_ID.test(value.producer || "")) throw new Error("producer is invalid");
+  if (!PROFILE.has(value.profile)) throw new Error("profile is invalid");
+  if (!Number.isFinite(Date.parse(value.observed_at))) throw new Error("observed_at is invalid");
+  for (const key of ["enterprise_id", "team_id", "team_name", "region_name", "endpoint", "runtime_revision"]) assertString(value[key], key);
+  if (!(value.app_id === null || (Number.isInteger(value.app_id) && value.app_id > 0))) throw new Error("app_id is invalid");
+  assertString(value.app_name, "app_name", true);
+  assertString(value.snapshot_revision, "snapshot_revision", true);
+  if (!SOURCE_KIND.has(value.source_kind)) throw new Error("source_kind is invalid");
+  if (!RUNTIME_STATE.has(value.runtime_state)) throw new Error("runtime_state is invalid");
+  if (!NEXT_PHASE.has(value.next_phase)) throw new Error("next_phase is invalid");
+  assertString(value.invalidation_reason, "invalidation_reason", true);
+}
+
+function validateContextShape(context) {
+  if (!context || typeof context !== "object" || Array.isArray(context)) throw new Error("context must be an object");
+  const keys = Object.keys(context).sort();
+  if (JSON.stringify(keys) !== JSON.stringify([...CONTEXT_KEYS].sort())) throw new Error("context fields are invalid");
+  if (context.schema !== SCHEMA || !SKILL_ID.test(context.producer || "") || !PROFILE.has(context.profile)) throw new Error("context identity is invalid");
+  if (!Number.isFinite(Date.parse(context.observed_at))) throw new Error("context observed_at is invalid");
+  for (const key of ["enterprise_id", "team_id", "team_name", "region_name"]) assertString(context[key], key);
+  if (!(context.app_id === null || (Number.isInteger(context.app_id) && context.app_id > 0))) throw new Error("context app_id is invalid");
+  assertString(context.app_name, "app_name", true);
+  if (!SHA256.test(context.runtime_fingerprint) || !SHA256.test(context.identity_fingerprint)) throw new Error("context fingerprint is invalid");
+  assertString(context.snapshot_revision, "snapshot_revision", true);
+  if (!SOURCE_KIND.has(context.source_kind) || !RUNTIME_STATE.has(context.runtime_state) || !NEXT_PHASE.has(context.next_phase)) throw new Error("context state is invalid");
+  assertString(context.invalidation_reason, "invalidation_reason", true);
+}
+
+function createHandoffContext(value) {
+  validateCreationInput(value);
+  return {
+    schema: SCHEMA,
+    producer: value.producer,
+    profile: value.profile,
+    observed_at: new Date(value.observed_at).toISOString(),
+    enterprise_id: value.enterprise_id,
+    team_id: value.team_id,
+    team_name: value.team_name,
+    region_name: value.region_name,
+    app_id: value.app_id,
+    app_name: value.app_name,
+    runtime_fingerprint: fingerprint(runtimeIdentity(value)),
+    identity_fingerprint: fingerprint(workspaceIdentity(value)),
+    snapshot_revision: value.snapshot_revision,
+    source_kind: value.source_kind,
+    runtime_state: value.runtime_state,
+    next_phase: value.next_phase,
+    invalidation_reason: value.invalidation_reason,
+  };
+}
+
+function validateHandoffContext(context, { current, signal = null, now = Date.now(), maxAgeMs = 30_000 } = {}) {
+  try {
+    validateContextShape(context);
+    validateCreationInput({
+      producer: context.producer,
+      observed_at: context.observed_at,
+      team_name: context.team_name,
+      app_name: context.app_name,
+      snapshot_revision: context.snapshot_revision,
+      source_kind: context.source_kind,
+      runtime_state: context.runtime_state,
+      next_phase: context.next_phase,
+      invalidation_reason: context.invalidation_reason,
+      ...current,
+    });
+  } catch (_error) {
+    return { valid: false, reason: "invalid-context" };
+  }
+  const signalReasons = new Set(["runtime-reconnect", "unauthorized-401", "forbidden-403", "not-found", "revision-conflict"]);
+  if (signal && signalReasons.has(signal)) return { valid: false, reason: signal };
+  if (fingerprint(runtimeIdentity(current)) !== context.runtime_fingerprint) return { valid: false, reason: "runtime-identity-changed" };
+  if (fingerprint(workspaceIdentity(current)) !== context.identity_fingerprint) return { valid: false, reason: "workspace-identity-changed" };
+  if (current.source_kind !== context.source_kind) return { valid: false, reason: "source-strategy-changed" };
+  if (current.snapshot_revision !== context.snapshot_revision) return { valid: false, reason: "snapshot-revision-changed" };
+  if (now - Date.parse(context.observed_at) > maxAgeMs) return { valid: false, reason: "mutable-state-stale" };
+  if (context.invalidation_reason) return { valid: false, reason: context.invalidation_reason };
+  return { valid: true, reason: null };
+}
+
+module.exports = {
+  createHandoffContext,
+  validateHandoffContext,
+};

package/bin/protected-poll.js

@@ -0,0 +1,116 @@
+"use strict";
+
+const READ_PREFIXES = [
+  "rainbond_query_", "rainbond_get_", "rainbond_list_", "rainbond_check_",
+  "rainbond_describe_", "rainbond_validate_", "rainbond_verify_", "rainbond_search_",
+];
+const DESTRUCTIVE = /(?:delete|remove|purge|destroy|update|create|set|manage|operate|restart|deploy)/i;
+const STATUS_PATH = /^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*){0,3}$/;
+
+function plain(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function readOnly(name) {
+  return typeof name === "string"
+    && READ_PREFIXES.some((prefix) => name.startsWith(prefix))
+    && !DESTRUCTIVE.test(name);
+}
+
+function stringArray(value, label) {
+  if (!Array.isArray(value) || value.length < 1 || value.some((item) => typeof item !== "string" || !item)) {
+    throw new Error(`${label} must be a non-empty string array`);
+  }
+}
+
+function validatePollInput(toolName, input) {
+  if (!readOnly(toolName)) throw new Error("poll accepts only a read-only tool");
+  if (!plain(input) || !plain(input.arguments)) throw new Error("poll input and arguments must be objects");
+  if (!STATUS_PATH.test(input.status_path || "") || input.status_path.includes("__proto__")) throw new Error("status_path is invalid");
+  stringArray(input.terminal_values, "terminal_values");
+  stringArray(input.failure_values, "failure_values");
+  if (input.retryable_values !== undefined) stringArray(input.retryable_values, "retryable_values");
+  if (!Number.isInteger(input.max_attempts) || input.max_attempts < 1 || input.max_attempts > 12) throw new Error("max_attempts must be between 1 and 12");
+  if (!Number.isInteger(input.interval_ms) || input.interval_ms < 0 || input.interval_ms > 10_000) throw new Error("interval_ms is invalid");
+  if (!Number.isInteger(input.timeout_ms) || input.timeout_ms < 1 || input.timeout_ms > 60_000) throw new Error("timeout_ms is invalid");
+  return input;
+}
+
+function valueAtPath(value, path) {
+  let current = value;
+  for (const segment of path.split(".")) {
+    if (!plain(current) || !Object.hasOwn(current, segment)) return undefined;
+    current = current[segment];
+  }
+  return current;
+}
+
+function result({ transitions, attempts, unchanged, finalState, blocker, retryable, start, end }) {
+  return {
+    schema: "rainskills.protected-poll.v1",
+    transitions,
+    final_state: finalState,
+    completed: blocker === null,
+    blocker,
+    retryable,
+    attempts,
+    unchanged_omitted: unchanged,
+    elapsed_ms: Math.max(0, end - start),
+  };
+}
+
+async function executeProtectedPoll(toolName, input, {
+  callTool,
+  sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+  now = () => Date.now(),
+  signal,
+} = {}) {
+  validatePollInput(toolName, input);
+  if (typeof callTool !== "function") throw new Error("poll callTool is required");
+  const start = now();
+  const transitions = [];
+  let previous;
+  let attempts = 0;
+  let unchanged = 0;
+  for (; attempts < input.max_attempts; attempts += 1) {
+    if (signal?.aborted) return result({ transitions, attempts, unchanged, finalState: previous ?? null, blocker: "cancelled", retryable: false, start, end: now() });
+    if (now() - start > input.timeout_ms) return result({ transitions, attempts, unchanged, finalState: previous ?? null, blocker: "timeout", retryable: true, start, end: now() });
+    let response;
+    try {
+      response = await callTool(toolName, input.arguments);
+    } catch (_error) {
+      return result({ transitions, attempts: attempts + 1, unchanged, finalState: previous ?? null, blocker: "read-failed", retryable: true, start, end: now() });
+    }
+    const state = valueAtPath(response, input.status_path);
+    if (typeof state !== "string" && typeof state !== "number" && typeof state !== "boolean") {
+      return result({ transitions, attempts: attempts + 1, unchanged, finalState: previous ?? null, blocker: "status-unavailable", retryable: false, start, end: now() });
+    }
+    const normalized = String(state);
+    if (normalized !== previous) {
+      transitions.push({ state: normalized, attempt: attempts + 1 });
+      previous = normalized;
+    } else {
+      unchanged += 1;
+    }
+    if (input.terminal_values.includes(normalized)) {
+      const failed = input.failure_values.includes(normalized);
+      return result({
+        transitions,
+        attempts: attempts + 1,
+        unchanged,
+        finalState: normalized,
+        blocker: failed ? String(response.blocker || "terminal-failure") : null,
+        retryable: failed && (input.retryable_values || []).includes(normalized),
+        start,
+        end: now(),
+      });
+    }
+    if (attempts + 1 < input.max_attempts && input.interval_ms > 0) await sleep(input.interval_ms);
+  }
+  return result({ transitions, attempts, unchanged, finalState: previous ?? null, blocker: "attempt-budget-exhausted", retryable: true, start, end: now() });
+}
+
+module.exports = {
+  executeProtectedPoll,
+  validatePollInput,
+};