@govplane/runtime-sdk 0.2.4

package/dist/index.cjs

@@ -0,0 +1,1080 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_CONTEXT_POLICY: () => DEFAULT_CONTEXT_POLICY,
+  GovplaneError: () => GovplaneError,
+  HttpError: () => HttpError,
+  RuntimeClient: () => RuntimeClient,
+  createPolicyEngine: () => createPolicyEngine,
+  formatTrace: () => formatTrace,
+  validateContext: () => validateContext
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client/RuntimeClient.ts
+var import_undici = require("undici");
+
+// src/engine/context.ts
+var DEFAULT_CONTEXT_POLICY = {
+  allowedKeys: [
+    "ctx.plan",
+    "ctx.country",
+    "ctx.requestTier",
+    "ctx.feature",
+    "ctx.amount",
+    "ctx.isAuthenticated",
+    "ctx.role"
+  ],
+  maxStringLen: 64,
+  maxArrayLen: 10,
+  blockLikelyPiiKeys: true
+};
+var PII_KEY_PATTERNS = [
+  /email/i,
+  /phone/i,
+  /mobile/i,
+  /name/i,
+  /firstname/i,
+  /lastname/i,
+  /address/i,
+  /street/i,
+  /postcode|postal/i,
+  /city/i,
+  /ip/i,
+  /ssn/i,
+  /dni|nie/i,
+  /passport/i
+];
+var DEFAULT_POLICY = {
+  maxStringLen: 80,
+  maxArrayLen: 25,
+  blockLikelyPiiKeys: true
+};
+function validateContext(ctx, policy) {
+  const allowed = new Set(policy.allowedKeys);
+  const maxStringLen = policy.maxStringLen ?? DEFAULT_POLICY.maxStringLen;
+  const maxArrayLen = policy.maxArrayLen ?? DEFAULT_POLICY.maxArrayLen;
+  const blockLikelyPiiKeys = policy.blockLikelyPiiKeys ?? DEFAULT_POLICY.blockLikelyPiiKeys;
+  for (const [k, v] of Object.entries(ctx)) {
+    const path = `ctx.${k}`;
+    if (!allowed.has(path)) {
+      throw new Error(`Context key not allowed: ${path}`);
+    }
+    if (blockLikelyPiiKeys) {
+      for (const re of PII_KEY_PATTERNS) {
+        if (re.test(k)) {
+          throw new Error(`Context key looks like PII and is blocked: ${path}`);
+        }
+      }
+    }
+    if (v === null || v === void 0) continue;
+    const t = typeof v;
+    if (t === "boolean" || t === "number") continue;
+    if (t === "string") {
+      if (v.length > maxStringLen) throw new Error(`Context value too long: ${path}`);
+      continue;
+    }
+    if (Array.isArray(v)) {
+      if (v.length > maxArrayLen) throw new Error(`Context array too long: ${path}`);
+      for (const it of v) {
+        if (typeof it !== "string") throw new Error(`Invalid array value type: ${path}`);
+        if (it.length > maxStringLen) throw new Error(`Invalid array value length: ${path}`);
+      }
+      continue;
+    }
+    throw new Error(`Invalid context type for ${path}`);
+  }
+}
+
+// src/engine/when.ts
+function getPath(obj, path) {
+  const parts = path.split(".");
+  let cur = obj;
+  for (const p of parts) {
+    if (!cur || typeof cur !== "object") return void 0;
+    cur = cur[p];
+  }
+  return cur;
+}
+function evalWhen(node, ctx) {
+  switch (node.op) {
+    case "and":
+      return node.args.every((n) => evalWhen(n, ctx));
+    case "or":
+      return node.args.some((n) => evalWhen(n, ctx));
+    case "not":
+      return !evalWhen(node.arg, ctx);
+    case "exists":
+      return getPath({ ctx }, node.path) !== void 0;
+    case "in": {
+      const v = getPath({ ctx }, node.path);
+      return node.values.some((x) => x === v);
+    }
+    case "eq":
+      return getPath({ ctx }, node.path) === node.value;
+    case "ne":
+      return getPath({ ctx }, node.path) !== node.value;
+    case "gt":
+      return Number(getPath({ ctx }, node.path)) > Number(node.value);
+    case "gte":
+      return Number(getPath({ ctx }, node.path)) >= Number(node.value);
+    case "lt":
+      return Number(getPath({ ctx }, node.path)) < Number(node.value);
+    case "lte":
+      return Number(getPath({ ctx }, node.path)) <= Number(node.value);
+    default:
+      return false;
+  }
+}
+
+// src/engine/traceDispatcher.ts
+var TraceDispatcher = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  q = [];
+  draining = false;
+  flushWaiters = [];
+  enqueue(evt) {
+    if (this.q.length >= this.opts.max) {
+      if (this.opts.dropPolicy === "drop_old") {
+        this.q.shift();
+      } else {
+        return;
+      }
+    }
+    this.q.push(evt);
+    this.kick();
+  }
+  async flush() {
+    if (!this.draining && this.q.length === 0) return;
+    return new Promise((resolve) => {
+      this.flushWaiters.push(resolve);
+      this.kick();
+    });
+  }
+  kick() {
+    if (this.draining) return;
+    if (this.q.length === 0) {
+      this.resolveFlushWaitersIfIdle();
+      return;
+    }
+    this.draining = true;
+    queueMicrotask(() => void this.drain());
+  }
+  resolveFlushWaitersIfIdle() {
+    if (this.draining) return;
+    if (this.q.length !== 0) return;
+    const waiters = this.flushWaiters;
+    this.flushWaiters = [];
+    for (const w of waiters) w();
+  }
+  async drain() {
+    try {
+      while (this.q.length) {
+        const evt = this.q.shift();
+        try {
+          await this.opts.sinkAsync(evt);
+        } catch (err) {
+          if (this.opts.onError) this.opts.onError(err);
+        }
+      }
+    } finally {
+      this.draining = false;
+      this.resolveFlushWaitersIfIdle();
+      if (this.q.length) this.kick();
+    }
+  }
+};
+
+// src/engine/toStructuredTrace.ts
+function toStructuredTraceEvent(input) {
+  const { decision, trace, level } = input;
+  const evt = {
+    v: 1,
+    ts: trace.evaluatedAt,
+    traceId: trace.traceId,
+    sampled: trace.sampled,
+    level,
+    target: trace.target,
+    decision: decision.decision,
+    reason: decision.reason,
+    winner: trace.winner,
+    summary: trace.summary
+  };
+  if (level === "full" && "rules" in trace) {
+    evt.rules = trace.rules.map((r) => ({
+      policyKey: r.policyKey,
+      ruleId: r.ruleId,
+      priority: r.priority,
+      effectType: r.effectType,
+      matched: r.matched,
+      discardedReason: r.discardedReason
+    }));
+  }
+  return evt;
+}
+
+// src/engine/emitTrace.ts
+function emitTraceIfAny(input) {
+  const { trace, decision, level } = input;
+  if (!trace) return;
+  let evt;
+  try {
+    evt = toStructuredTraceEvent({ level, decision, trace });
+  } catch (err) {
+    input.onSinkError?.(err);
+    return;
+  }
+  if (input.sink) {
+    try {
+      input.sink(evt);
+    } catch (err) {
+      input.onSinkError?.(err);
+    }
+  }
+  if (input.dispatcher) {
+    input.dispatcher.enqueue(evt);
+  }
+}
+
+// src/engine/createPolicyEngine.ts
+function clamp01(n) {
+  if (!Number.isFinite(n)) return 0;
+  if (n < 0) return 0;
+  if (n > 1) return 1;
+  return n;
+}
+function safeEffectType(effect) {
+  const t = effect?.type;
+  return typeof t === "string" ? t : void 0;
+}
+function makeTraceId() {
+  const g = globalThis;
+  const cryptoAny = g.crypto;
+  if (cryptoAny?.randomUUID) {
+    return cryptoAny.randomUUID();
+  }
+  try {
+    const nodeCrypto = require("crypto");
+    if (nodeCrypto?.randomUUID) return nodeCrypto.randomUUID();
+    const b = nodeCrypto.randomBytes?.(16);
+    if (!b || b.length < 16) {
+      throw new Error("Failed to generate random bytes for UUID");
+    }
+    if (b) {
+      b[6] = b[6] & 15 | 64;
+      b[8] = b[8] & 63 | 128;
+    }
+    const hex = b.toString("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+  } catch {
+    return `gp_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
+  }
+}
+function targetMatch(a, b) {
+  return a.service === b.service && a.resource === b.resource && a.action === b.action;
+}
+function byRuleOrder(a, b) {
+  const pr = (Number(b.priority) || 0) - (Number(a.priority) || 0);
+  if (pr !== 0) return pr;
+  const pk = String(a.policyKey).localeCompare(String(b.policyKey));
+  if (pk !== 0) return pk;
+  return String(a.ruleId).localeCompare(String(b.ruleId));
+}
+function throttleStrictness(th) {
+  const limit = Number(th?.limit);
+  const windowSeconds = Number(th?.windowSeconds);
+  const rate = windowSeconds > 0 ? limit / windowSeconds : Number.POSITIVE_INFINITY;
+  return { rate, limit, windowSeconds };
+}
+function makeTraceBudget(maxTraces, windowMs) {
+  let windowStart = Date.now();
+  let used = 0;
+  return {
+    allow() {
+      const now = Date.now();
+      if (now - windowStart >= windowMs) {
+        windowStart = now;
+        used = 0;
+      }
+      if (used >= maxTraces) return false;
+      used += 1;
+      return true;
+    }
+  };
+}
+function createPolicyEngine(opts) {
+  const budget = makeTraceBudget(
+    Number.isFinite(opts.traceDefaults?.budget?.maxTraces) ? opts.traceDefaults.budget.maxTraces : 60,
+    Number.isFinite(opts.traceDefaults?.budget?.windowMs) ? opts.traceDefaults.budget.windowMs : 6e4
+  );
+  const dispatcher = opts.traceSinkAsync ? new TraceDispatcher({
+    sinkAsync: opts.traceSinkAsync,
+    max: Number.isFinite(opts.traceQueueMax) ? opts.traceQueueMax : 1e3,
+    dropPolicy: opts.traceQueueDropPolicy ?? "drop_new",
+    onError: opts.onTraceSinkError
+  }) : void 0;
+  function coreEvaluate(input, wantTrace) {
+    const bundle = opts.getBundle();
+    const ctx = input.context ?? {};
+    if (opts.validateContext !== false) {
+      validateContext(ctx, opts.contextPolicy ?? DEFAULT_CONTEXT_POLICY);
+    }
+    const traceBase = wantTrace ? {
+      traceId: makeTraceId(),
+      sampled: "random",
+      // overwritten if forced
+      evaluatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      target: input.target,
+      summary: {
+        policiesSeen: 0,
+        rulesSeen: 0,
+        matched: 0,
+        considered: { kill_switch: 0, deny: 0, throttle: 0, allow: 0 }
+      },
+      rules: []
+    } : null;
+    if (!bundle || bundle.schemaVersion !== 1) {
+      const decision2 = { decision: "deny", reason: "default" };
+      if (!wantTrace) return decision2;
+      return {
+        ...decision2,
+        trace: {
+          ...traceBase,
+          winner: void 0
+        }
+      };
+    }
+    const kills = [];
+    const denies = [];
+    const throttles = [];
+    const allows = [];
+    const policies = bundle.policies ?? [];
+    if (wantTrace) traceBase.summary.policiesSeen = policies.length;
+    for (const p of policies) {
+      const policyKey = String(p.policyKey ?? "");
+      const rules = p.rules ?? [];
+      for (const r of rules) {
+        if (wantTrace) traceBase.summary.rulesSeen += 1;
+        const ruleId = String(r?.id ?? "");
+        const priority = Number(r?.priority ?? 0);
+        const effectType = safeEffectType(r?.effect);
+        if (r?.status !== "active") {
+          if (wantTrace) {
+            traceBase.rules.push({
+              policyKey,
+              ruleId,
+              priority,
+              effectType,
+              matched: false,
+              discardedReason: "disabled"
+            });
+          }
+          continue;
+        }
+        if (!r?.target || !targetMatch(r.target, input.target)) {
+          if (wantTrace) {
+            traceBase.rules.push({
+              policyKey,
+              ruleId,
+              priority,
+              effectType,
+              matched: false,
+              discardedReason: "target_mismatch"
+            });
+          }
+          continue;
+        }
+        if (r.when && !evalWhen(r.when, ctx)) {
+          if (wantTrace) {
+            traceBase.rules.push({
+              policyKey,
+              ruleId,
+              priority,
+              effectType,
+              matched: false,
+              discardedReason: "when_false"
+            });
+          }
+          continue;
+        }
+        if (!effectType) {
+          if (wantTrace) {
+            traceBase.rules.push({
+              policyKey,
+              ruleId,
+              priority,
+              effectType: void 0,
+              matched: false,
+              discardedReason: "invalid_effect"
+            });
+          }
+          continue;
+        }
+        if (wantTrace) {
+          traceBase.summary.matched += 1;
+          traceBase.rules.push({
+            policyKey,
+            ruleId,
+            priority,
+            effectType,
+            matched: true
+          });
+        }
+        const m = { policyKey, ruleId, priority, effect: r.effect };
+        if (effectType === "kill_switch") {
+          kills.push(m);
+          if (wantTrace) traceBase.summary.considered.kill_switch += 1;
+        } else if (effectType === "deny") {
+          denies.push(m);
+          if (wantTrace) traceBase.summary.considered.deny += 1;
+        } else if (effectType === "throttle") {
+          throttles.push(m);
+          if (wantTrace) traceBase.summary.considered.throttle += 1;
+        } else if (effectType === "allow") {
+          allows.push(m);
+          if (wantTrace) traceBase.summary.considered.allow += 1;
+        }
+      }
+    }
+    if (kills.length) {
+      const w = kills.sort(byRuleOrder)[0];
+      const decision2 = {
+        decision: "kill_switch",
+        reason: "rule",
+        policyKey: w.policyKey,
+        ruleId: w.ruleId,
+        killSwitch: w.effect.killSwitch
+      };
+      if (!wantTrace) return decision2;
+      return {
+        ...decision2,
+        trace: {
+          ...traceBase,
+          winner: { policyKey: w.policyKey, ruleId: w.ruleId, effectType: "kill_switch", priority: w.priority }
+        }
+      };
+    }
+    if (denies.length) {
+      const w = denies.sort(byRuleOrder)[0];
+      const decision2 = {
+        decision: "deny",
+        reason: "rule",
+        policyKey: w.policyKey,
+        ruleId: w.ruleId
+      };
+      if (!wantTrace) return decision2;
+      return {
+        ...decision2,
+        trace: {
+          ...traceBase,
+          winner: { policyKey: w.policyKey, ruleId: w.ruleId, effectType: "deny", priority: w.priority }
+        }
+      };
+    }
+    if (throttles.length) {
+      const w = throttles.sort((a, b) => {
+        const A = throttleStrictness(a.effect.throttle);
+        const B = throttleStrictness(b.effect.throttle);
+        if (A.rate !== B.rate) return A.rate - B.rate;
+        if (A.limit !== B.limit) return A.limit - B.limit;
+        if (A.windowSeconds !== B.windowSeconds) return A.windowSeconds - B.windowSeconds;
+        return byRuleOrder(a, b);
+      })[0];
+      const decision2 = {
+        decision: "throttle",
+        reason: "rule",
+        policyKey: w.policyKey,
+        ruleId: w.ruleId,
+        throttle: w.effect.throttle
+      };
+      if (!wantTrace) return decision2;
+      return {
+        ...decision2,
+        trace: {
+          ...traceBase,
+          winner: { policyKey: w.policyKey, ruleId: w.ruleId, effectType: "throttle", priority: w.priority }
+        }
+      };
+    }
+    if (allows.length) {
+      const w = allows.sort(byRuleOrder)[0];
+      const decision2 = {
+        decision: "allow",
+        reason: "rule",
+        policyKey: w.policyKey,
+        ruleId: w.ruleId
+      };
+      if (!wantTrace) return decision2;
+      return {
+        ...decision2,
+        trace: {
+          ...traceBase,
+          winner: { policyKey: w.policyKey, ruleId: w.ruleId, effectType: "allow", priority: w.priority }
+        }
+      };
+    }
+    const decision = { decision: "deny", reason: "default" };
+    if (!wantTrace) return decision;
+    return {
+      ...decision,
+      trace: {
+        ...traceBase,
+        winner: void 0
+      }
+    };
+  }
+  return {
+    evaluate(input) {
+      return coreEvaluate(input, false);
+    },
+    evaluateWithTrace(input, options) {
+      const merged = {
+        ...opts.traceDefaults ?? {},
+        ...options ?? {}
+      };
+      const level = merged.level ?? "sampled";
+      const sampling = clamp01(merged.sampling ?? 0.01);
+      const force = merged.force === true;
+      const isOff = level === "off";
+      const isErrorLevel = level === "errors";
+      const isFull = level === "full";
+      const isSampled = level === "sampled";
+      if (isOff) {
+        return coreEvaluate(input, false);
+      }
+      const baseDecision = coreEvaluate(input, false);
+      if (isErrorLevel) {
+        const isErrDecision = baseDecision.decision === "deny" || baseDecision.decision === "kill_switch";
+        if (!isErrDecision && !force) {
+          return baseDecision;
+        }
+        if (!force) {
+          const ok = budget.allow();
+          if (!ok) return baseDecision;
+        }
+        const out = coreEvaluate(input, true);
+        if (out?.trace) out.trace.sampled = force ? "forced" : "errors";
+        const { rules: _rules, ...compact } = out.trace ?? {};
+        const finalOut = { ...out, trace: compact };
+        emitTraceIfAny({ level: "errors", decision: out, trace: out.trace, sink: opts.traceSink, dispatcher, onSinkError: opts.onTraceSinkError });
+        return finalOut;
+      }
+      if (isFull) {
+        if (!force) {
+          const ok = budget.allow();
+          if (!ok) return baseDecision;
+        }
+        const out = coreEvaluate(input, true);
+        if (out?.trace) out.trace.sampled = force ? "forced" : "random";
+        emitTraceIfAny({ level: "full", decision: out, trace: out.trace, sink: opts.traceSink, dispatcher, onSinkError: opts.onTraceSinkError });
+        return out;
+      }
+      if (isSampled) {
+        const include = force ? true : Math.random() < sampling;
+        if (!include) return baseDecision;
+        if (!force) {
+          const ok = budget.allow();
+          if (!ok) return baseDecision;
+        }
+        const out = coreEvaluate(input, true);
+        if (out?.trace) out.trace.sampled = force ? "forced" : "random";
+        const { rules: _rules, ...compact } = out.trace ?? {};
+        const finalOut = { ...out, trace: compact };
+        emitTraceIfAny({ level: "sampled", decision: out, trace: out.trace, sink: opts.traceSink, dispatcher, onSinkError: opts.onTraceSinkError });
+        return finalOut;
+      }
+      return baseDecision;
+    },
+    flushTraces: async () => {
+      if (!dispatcher) return;
+      await dispatcher.flush();
+    }
+  };
+}
+
+// src/client/RuntimeClient.ts
+var import_node_fs = require("fs");
+var RuntimeClient = class {
+  cfg;
+  cache = {};
+  timer = null;
+  isRunning = false;
+  hasValidBundle = false;
+  inFlightRefresh = null;
+  burstUntil = 0;
+  // health / degraded state
+  consecutiveFailures = 0;
+  lastError = null;
+  nextRetryAtMs = null;
+  updateListeners = [];
+  statusListeners = [];
+  // Policy engine
+  engine;
+  // Incident controls
+  incidentPollTimer = null;
+  incidentFileLastMtimeMs = null;
+  installedSignalHandler = false;
+  sigHandler;
+  constructor(config) {
+    this.cfg = {
+      ...config,
+      pollMs: config.pollMs ?? 5e3,
+      burstPollMs: config.burstPollMs ?? 500,
+      burstDurationMs: config.burstDurationMs ?? 3e4,
+      timeoutMs: config.timeoutMs ?? 5e3,
+      backoffBaseMs: config.backoffBaseMs ?? 500,
+      backoffMaxMs: config.backoffMaxMs ?? 3e4,
+      backoffJitter: config.backoffJitter ?? 0.2,
+      degradeAfterFailures: config.degradeAfterFailures ?? 3,
+      incidentEnvFlag: config.incidentEnvFlag ?? "GP_RUNTIME_INCIDENT",
+      incidentFilePollMs: config.incidentFilePollMs ?? 1e3,
+      incidentSignal: config.incidentSignal ?? "SIGUSR1"
+    };
+    this.engine = createPolicyEngine({
+      getBundle: () => this.cache.bundle,
+      validateContext: config.engine?.validateContext !== false,
+      contextPolicy: config.engine?.contextPolicy,
+      traceDefaults: config.trace?.defaults,
+      traceSink: config.trace?.onDecisionTrace,
+      traceSinkAsync: config.trace?.onDecisionTraceAsync,
+      traceQueueMax: config.trace?.queueMax,
+      traceQueueDropPolicy: config.trace?.dropPolicy,
+      onTraceSinkError: config.trace?.onTraceError
+    });
+  }
+  /** Subscribe to bundle updates (only when changed). */
+  onUpdate(fn) {
+    const wrapped = (res) => {
+      if (res.changed) fn(res);
+    };
+    this.updateListeners.push(wrapped);
+    return () => {
+      this.updateListeners = this.updateListeners.filter((x) => x !== wrapped);
+    };
+  }
+  /** Subscribe to status changes (ok/degraded). */
+  onStatus(fn) {
+    this.statusListeners.push(fn);
+    fn(this.getStatus());
+    return () => {
+      this.statusListeners = this.statusListeners.filter((x) => x !== fn);
+    };
+  }
+  /** Evaluate a decision using the cached bundle (deny-by-default if bundle missing/invalid). */
+  evaluate(input) {
+    return this.engine.evaluate(input);
+  }
+  /** Evaluate and (optionally) attach trace based on trace defaults/overrides. */
+  evaluateWithTrace(input, options) {
+    return this.engine.evaluateWithTrace(input, options);
+  }
+  /** Flush async trace queue (only does something if traceSinkAsync is configured). */
+  flushTraces() {
+    return this.engine.flushTraces();
+  }
+  getCached() {
+    return { ...this.cache };
+  }
+  getStatus() {
+    const b = this.cache.bundle;
+    const valid = !!(b && typeof b === "object" && b.schemaVersion === 1 && Array.isArray(b.policies));
+    if (!this.hasValidBundle && !valid) return { state: "warming_up" };
+    if (this.consecutiveFailures >= this.cfg.degradeAfterFailures) {
+      return {
+        state: "degraded",
+        consecutiveFailures: this.consecutiveFailures,
+        lastError: this.lastError ?? { message: "unknown", at: (/* @__PURE__ */ new Date()).toISOString() },
+        nextRetryAt: this.nextRetryAtMs ? new Date(this.nextRetryAtMs).toISOString() : void 0
+      };
+    }
+    return { state: "ok" };
+  }
+  start() {
+    if (this.isRunning) return;
+    this.isRunning = true;
+    this.applyIncidentFromEnv();
+    this.startIncidentFilePoller();
+    this.installIncidentSignal();
+    this.scheduleNext(0);
+  }
+  async warmStart(opts) {
+    this.applyIncidentFromEnv();
+    this.startIncidentFilePoller();
+    this.installIncidentSignal();
+    const timeoutMs = opts?.timeoutMs ?? 1e4;
+    const until = Date.now() + timeoutMs;
+    if (opts?.burst) {
+      await this.refreshNow({ burst: true }).catch(() => void 0);
+    } else {
+      await this.refreshNow().catch(() => void 0);
+    }
+    while (Date.now() < until) {
+      const b = this.cache.bundle;
+      const valid = !!(b && typeof b === "object" && b.schemaVersion === 1 && Array.isArray(b.policies));
+      if (valid) {
+        this.hasValidBundle = true;
+        return;
+      }
+      await new Promise((r) => setTimeout(r, 100));
+    }
+    throw new Error("warmStart timeout: no valid runtime bundle received");
+  }
+  stop() {
+    this.isRunning = false;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    if (this.incidentPollTimer) clearInterval(this.incidentPollTimer);
+    this.incidentPollTimer = null;
+    this.uninstallIncidentSignal();
+  }
+  async refreshNow(opts) {
+    if (opts?.burst) {
+      this.burstUntil = Date.now() + this.cfg.burstDurationMs;
+      if (this.isRunning) this.scheduleNext(0);
+    }
+    return this.refresh();
+  }
+  emitStatusIfNeeded(prev) {
+    const next = this.getStatus();
+    const key = (s) => {
+      if (s.state === "warming_up") return "warming_up";
+      if (s.state === "ok") return "ok";
+      return `degraded:${s.consecutiveFailures}:${s.lastError.message}`;
+    };
+    if (key(prev) !== key(next)) {
+      for (const l of this.statusListeners) l(next);
+    }
+  }
+  async refresh() {
+    if (this.inFlightRefresh) return this.inFlightRefresh;
+    const prevStatus = this.getStatus();
+    this.inFlightRefresh = (async () => {
+      try {
+        const head = await this.headBundle();
+        if (!head) {
+          this.markSuccess();
+          this.emitStatusIfNeeded(prevStatus);
+          return { changed: false, meta: this.cache.meta };
+        }
+        const prevEtag = this.cache.meta?.etag;
+        if (prevEtag && head.etag === prevEtag) {
+          this.cache.meta = head;
+          this.markSuccess();
+          this.emitStatusIfNeeded(prevStatus);
+          return { changed: false, meta: head };
+        }
+        const got = await this.getBundle();
+        this.markSuccess();
+        this.emitStatusIfNeeded(prevStatus);
+        return got.changed ? got : { changed: false, meta: got.meta };
+      } catch (err) {
+        this.markFailure(err);
+        this.emitStatusIfNeeded(prevStatus);
+        throw err;
+      } finally {
+        this.inFlightRefresh = null;
+      }
+    })();
+    return this.inFlightRefresh;
+  }
+  scheduleNext(delayMs) {
+    if (!this.isRunning) return;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(async () => {
+      const prevStatus = this.getStatus();
+      try {
+        this.applyIncidentFromEnv();
+        if (this.nextRetryAtMs && Date.now() < this.nextRetryAtMs) {
+          this.scheduleNext(Math.max(0, this.nextRetryAtMs - Date.now()));
+          return;
+        }
+        const res = await this.refresh();
+        if (res.changed) {
+          for (const l of this.updateListeners) l(res);
+        }
+      } catch {
+      } finally {
+        this.emitStatusIfNeeded(prevStatus);
+        const next = this.nextRetryAtMs && Date.now() < this.nextRetryAtMs ? Math.max(0, this.nextRetryAtMs - Date.now()) : this.effectivePollMs();
+        this.scheduleNext(next);
+      }
+    }, delayMs);
+  }
+  effectivePollMs() {
+    const now = Date.now();
+    if (now < this.burstUntil) return this.cfg.burstPollMs;
+    return this.cfg.pollMs;
+  }
+  markSuccess() {
+    this.consecutiveFailures = 0;
+    this.lastError = null;
+    this.nextRetryAtMs = null;
+  }
+  markFailure(err) {
+    this.consecutiveFailures += 1;
+    this.lastError = { message: String(err?.message ?? err ?? "unknown"), at: (/* @__PURE__ */ new Date()).toISOString() };
+    const delay = this.computeBackoffDelayMs(this.consecutiveFailures);
+    this.nextRetryAtMs = Date.now() + delay;
+  }
+  computeBackoffDelayMs(failures) {
+    const base = this.cfg.backoffBaseMs;
+    const max = this.cfg.backoffMaxMs;
+    const exp = base * Math.pow(2, Math.max(0, failures - 1));
+    const capped = Math.min(max, exp);
+    const jitter = Math.max(0, Math.min(1, this.cfg.backoffJitter));
+    const delta = capped * jitter;
+    const min = Math.max(0, capped - delta);
+    const maxJ = capped + delta;
+    const r = Math.random();
+    return Math.floor(min + r * (maxJ - min));
+  }
+  bundleUrl() {
+    const u = new URL(this.cfg.baseUrl);
+    u.pathname = "/v1/runtime/bundle";
+    u.searchParams.set("projectId", this.cfg.projectId);
+    u.searchParams.set("env", this.cfg.env);
+    return u.toString();
+  }
+  commonHeaders(extra) {
+    return {
+      Authorization: `Bearer ${this.cfg.runtimeKey}`,
+      "User-Agent": this.cfg.userAgent ?? "govplane-runtime-sdk/0.x",
+      ...extra
+    };
+  }
+  async headBundle() {
+    const url = this.bundleUrl();
+    const { statusCode, headers, body } = await (0, import_undici.request)(url, {
+      method: "HEAD",
+      headers: this.commonHeaders(),
+      bodyTimeout: this.cfg.timeoutMs,
+      headersTimeout: this.cfg.timeoutMs
+    });
+    await body.text().catch(() => void 0);
+    if (statusCode === 401 || statusCode === 403) throw new Error(`Unauthorized (${statusCode})`);
+    if (statusCode >= 500) throw new Error(`Runtime server error (${statusCode})`);
+    if (statusCode !== 200 && statusCode !== 304) return this.cache.meta;
+    const etag = headers["etag"] ?? "";
+    if (!etag) return this.cache.meta;
+    const bundleVersionRaw = headers["x-gp-bundle-version"];
+    const updatedAt = headers["x-gp-updated-at"];
+    return {
+      etag,
+      bundleVersion: bundleVersionRaw ? Number(bundleVersionRaw) : void 0,
+      updatedAt
+    };
+  }
+  async getBundle() {
+    const url = this.bundleUrl();
+    const ifNoneMatch = this.cache.meta?.etag;
+    const { statusCode, headers, body } = await (0, import_undici.request)(url, {
+      method: "GET",
+      headers: this.commonHeaders(ifNoneMatch ? { "If-None-Match": ifNoneMatch } : void 0),
+      bodyTimeout: this.cfg.timeoutMs,
+      headersTimeout: this.cfg.timeoutMs
+    });
+    const txt = await body.text();
+    if (statusCode === 304) {
+      const etag2 = headers["etag"] ?? ifNoneMatch ?? "";
+      const bundleVersionRaw2 = headers["x-gp-bundle-version"];
+      const updatedAt2 = headers["x-gp-updated-at"];
+      const meta2 = etag2 ? { etag: etag2, bundleVersion: bundleVersionRaw2 ? Number(bundleVersionRaw2) : void 0, updatedAt: updatedAt2 } : this.cache.meta;
+      if (meta2) this.cache.meta = meta2;
+      return { changed: false, meta: meta2 };
+    }
+    if (statusCode === 401 || statusCode === 403) throw new Error(`Unauthorized (${statusCode})`);
+    if (statusCode >= 400) throw new Error(`Runtime HTTP error (${statusCode}): ${txt.slice(0, 200)}`);
+    const etag = headers["etag"] ?? "";
+    const bundleVersionRaw = headers["x-gp-bundle-version"];
+    const updatedAt = headers["x-gp-updated-at"];
+    const meta = {
+      etag: etag || (ifNoneMatch ?? ""),
+      bundleVersion: bundleVersionRaw ? Number(bundleVersionRaw) : void 0,
+      updatedAt
+    };
+    const parsed = JSON.parse(txt);
+    const normalized = parsed?.schemaVersion === 1 ? parsed : parsed?.data?.schemaVersion === 1 ? parsed.data : parsed?.data?.body?.schemaVersion === 1 ? parsed.data.body : parsed?.body?.schemaVersion === 1 ? parsed.body : parsed;
+    this.cache = { meta, bundle: normalized };
+    const nb = normalized;
+    if (nb && typeof nb === "object" && nb.schemaVersion === 1 && Array.isArray(nb.policies)) {
+      this.hasValidBundle = true;
+    }
+    return { changed: true, meta, bundle: normalized };
+  }
+  // Incident controls
+  enableBurst(input) {
+    const now = Date.now();
+    const until = now + Math.max(0, input.durationMs);
+    if (until > this.burstUntil) this.burstUntil = until;
+    if (Number.isFinite(input.pollMs) && input.pollMs > 0) {
+      this.cfg.burstPollMs = input.pollMs;
+    }
+    console.log(`[govplane][incident] burst enabled until ${new Date(this.burstUntil).toISOString()} (pollMs=${this.cfg.burstPollMs})`);
+  }
+  disableBurst() {
+    this.burstUntil = 0;
+    console.log(`[govplane][incident] burst disabled`);
+  }
+  applyIncidentFromEnv() {
+    const flag = this.cfg.incidentEnvFlag;
+    if (!flag) return;
+    const v = String(process.env[flag] ?? "").trim().toLowerCase();
+    const on = v === "1" || v === "true" || v === "yes" || v === "on";
+    if (on) {
+      this.enableBurst({ durationMs: this.cfg.burstDurationMs, pollMs: this.cfg.burstPollMs });
+    }
+  }
+  startIncidentFilePoller() {
+    const filePath = this.cfg.incidentFilePath;
+    if (!filePath) return;
+    if (this.incidentPollTimer) clearInterval(this.incidentPollTimer);
+    this.incidentPollTimer = setInterval(() => {
+      void this.checkIncidentFileOnce(filePath).catch(() => void 0);
+    }, this.cfg.incidentFilePollMs);
+    void this.checkIncidentFileOnce(filePath).catch(() => void 0);
+  }
+  async checkIncidentFileOnce(filePath) {
+    let mtimeMs;
+    try {
+      const st = await import_node_fs.promises.stat(filePath);
+      mtimeMs = st.mtimeMs;
+    } catch {
+      return;
+    }
+    if (this.incidentFileLastMtimeMs !== null && mtimeMs === this.incidentFileLastMtimeMs) return;
+    this.incidentFileLastMtimeMs = mtimeMs;
+    let txt;
+    try {
+      txt = await import_node_fs.promises.readFile(filePath, "utf8");
+    } catch {
+      return;
+    }
+    let payload;
+    try {
+      payload = JSON.parse(txt);
+    } catch {
+      return;
+    }
+    if (!payload || typeof payload !== "object") return;
+    if (payload.burst === true) {
+      this.enableBurst({
+        durationMs: payload.burstDurationMs ?? this.cfg.burstDurationMs,
+        pollMs: payload.burstPollMs ?? this.cfg.burstPollMs
+      });
+      if (this.isRunning) this.scheduleNext(0);
+    } else if (payload.burst === false) {
+      this.disableBurst();
+    }
+    if (payload.refreshNow === true) {
+      void this.refreshNow({ burst: payload.burst === true }).catch(() => void 0);
+    }
+  }
+  installIncidentSignal() {
+    if (this.installedSignalHandler) return;
+    if (this.cfg.incidentSignal === false) return;
+    const sig = this.cfg.incidentSignal;
+    if (!sig) return;
+    try {
+      this.sigHandler = () => {
+        this.enableBurst({ durationMs: this.cfg.burstDurationMs, pollMs: this.cfg.burstPollMs });
+        if (this.isRunning) this.scheduleNext(0);
+        void this.refreshNow({ burst: true }).catch(() => void 0);
+      };
+      process.on(sig, this.sigHandler);
+      this.installedSignalHandler = true;
+    } catch {
+    }
+  }
+  uninstallIncidentSignal() {
+    if (!this.installedSignalHandler) return;
+    if (this.cfg.incidentSignal === false) return;
+    const sig = this.cfg.incidentSignal;
+    if (!sig) return;
+    try {
+      if (this.sigHandler) process.off(sig, this.sigHandler);
+    } catch {
+    } finally {
+      this.installedSignalHandler = false;
+      this.sigHandler = void 0;
+    }
+  }
+};
+
+// src/errors/Errors.ts
+var GovplaneError = class extends Error {
+  constructor(message, code = "GP_ERROR", details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "GovplaneError";
+  }
+};
+var HttpError = class extends GovplaneError {
+  constructor(message, status, headers, details) {
+    super(message, "HTTP_ERROR", details);
+    this.status = status;
+    this.headers = headers;
+    this.name = "HttpError";
+  }
+};
+
+// src/engine/formatTrace.ts
+function formatTrace(trace, opts = {}) {
+  const lines = [];
+  const hdr = `[govplane] traceId=${trace.traceId} sampled=${trace.sampled} policies=${trace.summary.policiesSeen} rules=${trace.summary.rulesSeen} matched=${trace.summary.matched}`;
+  lines.push(hdr);
+  if (trace.winner) {
+    lines.push(
+      `winner \u2192 policy=${trace.winner.policyKey} rule=${trace.winner.ruleId} effect=${trace.winner.effectType} priority=${trace.winner.priority}`
+    );
+  } else {
+    lines.push(`winner \u2192 none (default decision)`);
+  }
+  if ("rules" in trace && opts.includeDiscarded) {
+    const discarded = trace.rules.filter((r) => !r.matched);
+    if (discarded.length) {
+      lines.push(`discarded rules:`);
+      for (const r of discarded) {
+        lines.push(
+          `- policy=${r.policyKey} rule=${r.ruleId} effect=${r.effectType ?? "?"} reason=${r.discardedReason}`
+        );
+      }
+    }
+  }
+  if (opts.multiline) {
+    return lines.join("\n");
+  }
+  return lines.join(" | ");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_CONTEXT_POLICY,
+  GovplaneError,
+  HttpError,
+  RuntimeClient,
+  createPolicyEngine,
+  formatTrace,
+  validateContext
+});
+//# sourceMappingURL=index.cjs.map