@govplane/runtime-sdk 0.2.4 → 0.5.0

package/docs/usage/DecisionTrace.md

@@ -0,0 +1,289 @@
+---
+description: >-
+  Capture structured, zero-PII decision traces for observability, debugging,
+  and audit — with configurable levels, sampling, and async sinks.
+---
+
+# Decision Tracing
+
+## Overview
+
+The SDK can optionally record a `DecisionTrace` for each evaluation. Traces contain:
+
+- The evaluated `target`
+- A rule-level breakdown of what matched, what was discarded, and why
+- The winning rule and effect
+- A summary of all considered effects
+
+**Traces never contain context values or user data.** Only structural metadata (rule IDs, policy keys, effect types, discard reasons) is included.
+
+---
+
+## `evaluateWithTrace()`
+
+```typescript
+const result = client.evaluateWithTrace(
+  { target, context },
+  { level: "full", force: true }   // trace options, optional
+);
+
+if (result.trace) {
+  console.log(result.trace.winner);
+  console.log(result.trace.summary);
+}
+```
+
+The `trace` field is only present when the level, sampling, and budget allow it. When it is absent the `result` object is identical to `evaluate()`.
+
+---
+
+## Trace levels
+
+| Level | Behaviour |
+|---|---|
+| `"off"` | No trace is computed or attached. Equivalent to `evaluate()`. |
+| `"errors"` | Trace is attached only when the decision is `deny` or `kill_switch`. Compact format (no rule list). |
+| `"sampled"` | Trace is attached probabilistically based on `sampling` rate and budget. Compact format. |
+| `"full"` | Trace is always attempted (budget permitting). Full format includes the complete per-rule list. |
+
+---
+
+## Trace formats
+
+### Compact (`DecisionTraceCompact`)
+
+Contains the summary and winner but no per-rule list. Used by `"errors"` and `"sampled"` levels.
+
+```typescript
+type DecisionTraceCompact = {
+  traceId:     string;
+  sampled:     "forced" | "random";
+  evaluatedAt: string;                 // ISO timestamp
+  target:      Target;
+  summary: {
+    policiesSeen: number;
+    rulesSeen:    number;
+    matched:      number;
+    considered: {
+      kill_switch: number;
+      deny:        number;
+      throttle:    number;
+      allow:       number;
+      custom:      number;
+    };
+  };
+  winner?: {
+    policyKey:  string;
+    ruleId:     string;
+    effectType: string;
+    priority:   number;
+  };
+};
+```
+
+### Full (`DecisionTraceFull`)
+
+`DecisionTraceCompact` extended with a per-rule breakdown.
+
+```typescript
+type DecisionTraceFull = DecisionTraceCompact & {
+  rules: Array<{
+    policyKey:       string;
+    ruleId:          string;
+    priority:        number;
+    effectType?:     string;
+    matched:         boolean;
+    discardedReason?: "disabled" | "target_mismatch" | "when_false" | "invalid_effect";
+  }>;
+};
+```
+
+---
+
+## Configuring trace defaults
+
+Set default trace behaviour via `trace.defaults` in `RuntimeClientConfig`:
+
+```typescript
+const client = new RuntimeClient({
+  baseUrl:    "https://runtime.govplane.io",
+  runtimeKey: "rk_live_••••••••",
+  trace: {
+    defaults: {
+      level:    "sampled",
+      sampling: 0.05,         // 5% of evaluations
+      budget: {
+        maxTraces:  60,        // max traces per window
+        windowMs:   60_000,    // 1-minute window
+      },
+    },
+  },
+});
+```
+
+### Per-call override
+
+```typescript
+// Override for a single call — useful in test or debug contexts
+const result = client.evaluateWithTrace(
+  { target, context },
+  { level: "full", force: true }   // force=true bypasses sampling and budget
+);
+```
+
+---
+
+## Trace sinks
+
+Traces can be pushed to a synchronous or async sink automatically after each evaluation.
+
+### Sync sink (`onDecisionTrace`)
+
+Called immediately after each traced evaluation. Keep it fast; errors are caught and forwarded to `onTraceError`.
+
+```typescript
+const client = new RuntimeClient({
+  ...
+  trace: {
+    defaults: { level: "sampled", sampling: 0.1 },
+    onDecisionTrace: (evt) => {
+      logger.info("decision_trace", {
+        traceId:  evt.traceId,
+        decision: evt.decision,
+        winner:   evt.winner?.ruleId,
+      });
+    },
+  },
+});
+```
+
+### Async sink (`onDecisionTraceAsync`)
+
+Buffered via an internal queue. Evaluations are never blocked waiting for the sink. Queue is drained asynchronously via `queueMicrotask`.
+
+```typescript
+const client = new RuntimeClient({
+  ...
+  trace: {
+    defaults: { level: "full" },
+    onDecisionTraceAsync: async (evt) => {
+      await analyticsClient.ingest("govplane.trace", evt);
+    },
+    queueMax:   1000,        // default 1000
+    dropPolicy: "drop_new",  // "drop_new" | "drop_old" — default "drop_new"
+    onTraceError: (err) => logger.error("trace sink error", err),
+  },
+});
+```
+
+#### Flushing the queue
+
+```typescript
+// On graceful shutdown, drain the queue before exiting
+await client.flushTraces();
+```
+
+---
+
+## `StructuredTraceEvent`
+
+The object delivered to both sync and async sinks:
+
+```typescript
+type StructuredTraceEvent = {
+  v:        1;
+  ts:       string;                            // ISO evaluation timestamp
+  traceId:  string;                            // UUID v4
+  sampled:  "forced" | "random" | "errors";
+  level:    "off" | "errors" | "sampled" | "full";
+  target:   Target;
+  decision: "allow" | "deny" | "throttle" | "kill_switch" | "custom";
+  reason:   "rule" | "default";
+  winner?: {
+    policyKey:  string;
+    ruleId:     string;
+    effectType: string;
+    priority:   number;
+  };
+  summary: { ... };    // same as DecisionTraceCompact.summary
+  rules?:  Array<...>; // only present when level === "full"
+};
+```
+
+---
+
+## `formatTrace()` utility
+
+Pretty-print a trace to a single line (or multi-line) string for log output:
+
+```typescript
+import { formatTrace } from "@govplane/runtime-sdk";
+
+const result = client.evaluateWithTrace({ target, context }, { level: "full", force: true });
+
+if (result.trace) {
+  // Single-line (default)
+  console.log(formatTrace(result.trace));
+  // [govplane] traceId=... sampled=random policies=2 rules=5 matched=1 | winner → ...
+
+  // Multi-line with discarded rules
+  console.log(formatTrace(result.trace, { multiline: true, includeDiscarded: true }));
+}
+```
+
+---
+
+## Budget
+
+The trace budget prevents trace volume from growing unbounded in high-traffic environments. Traces that exceed the budget are silently skipped (the evaluation result is still returned normally).
+
+```typescript
+budget: {
+  maxTraces: 60,      // max N traces per window
+  windowMs:  60_000,  // sliding window size in ms
+}
+```
+
+Use `force: true` to bypass the budget for specific calls (e.g. debugging a production issue):
+
+```typescript
+client.evaluateWithTrace({ target, context }, { force: true });
+```
+
+---
+
+## Integration examples
+
+### Ship to Datadog
+
+```typescript
+onDecisionTraceAsync: async (evt) => {
+  await fetch("https://http-intake.logs.datadoghq.com/api/v2/logs", {
+    method:  "POST",
+    headers: { "DD-API-KEY": process.env.DD_API_KEY!, "Content-Type": "application/json" },
+    body: JSON.stringify({
+      ddsource: "govplane",
+      ddtags:   `env:${process.env.NODE_ENV},service:${evt.target.service}`,
+      message:  JSON.stringify(evt),
+    }),
+  });
+},
+```
+
+### Write to stdout as NDJSON
+
+```typescript
+onDecisionTrace: (evt) => {
+  process.stdout.write(JSON.stringify(evt) + "\n");
+},
+```
+
+---
+
+{% content-ref url="BundleLifecycle.md" %}
+[Bundle Lifecycle](BundleLifecycle.md)
+{% endcontent-ref %}
+
+{% content-ref url="../reference/Configuration.md" %}
+[Configuration Reference](../reference/Configuration.md)
+{% endcontent-ref %}

package/docs/usage/Effects.md

@@ -0,0 +1,213 @@
+---
+description: >-
+  The five effect types the engine can return, their bundle shapes, and how to
+  handle them in application code.
+---
+
+# Effect Types
+
+The Govplane policy engine recognises five effect types. They are applied in this fixed precedence order:
+
+```
+kill_switch  >  deny  >  throttle  >  allow  >  custom  >  deny-by-default
+```
+
+---
+
+## `allow`
+
+Grants access. The request proceeds normally.
+
+**Bundle rule shape:**
+
+```json
+{
+  "id": "r_allow_viewers",
+  "status": "active",
+  "priority": 10,
+  "target": { "service": "api", "resource": "reports", "action": "read" },
+  "effect": { "type": "allow" }
+}
+```
+
+**Decision shape:**
+
+```typescript
+{ decision: "allow", reason: "rule", policyKey: "reports-policy", ruleId: "r_allow_viewers" }
+```
+
+---
+
+## `deny`
+
+Blocks access.
+
+**Bundle rule shape:**
+
+```json
+{
+  "id": "r_deny_guests",
+  "status": "active",
+  "priority": 5,
+  "target": { "service": "api", "resource": "admin", "action": "write" },
+  "effect": { "type": "deny" }
+}
+```
+
+**Decision shape:**
+
+```typescript
+{ decision: "deny", reason: "rule", policyKey: "admin-policy", ruleId: "r_deny_guests" }
+```
+
+**Deny-by-default:** If no rule matches and no policy default applies, the SDK returns `{ decision: "deny", reason: "default" }` automatically. There is no `policyKey` or `ruleId` in this case.
+
+---
+
+## `throttle`
+
+Rate-limits the request. Your application is responsible for enforcing the limit; the SDK only signals the intent.
+
+**Bundle rule shape:**
+
+```json
+{
+  "id": "r_throttle_free",
+  "status": "active",
+  "priority": 20,
+  "target": { "service": "api", "resource": "export", "action": "create" },
+  "effect": {
+    "type": "throttle",
+    "throttle": {
+      "limit": 10,
+      "windowSeconds": 3600,
+      "key": "tenant"
+    }
+  }
+}
+```
+
+**Decision shape:**
+
+```typescript
+{
+  decision: "throttle",
+  reason: "rule",
+  policyKey: "export-policy",
+  ruleId: "r_throttle_free",
+  throttle: { limit: 10, windowSeconds: 3600, key: "tenant" }
+}
+```
+
+| `throttle` field | Description |
+|---|---|
+| `limit` | Maximum number of requests allowed per window. |
+| `windowSeconds` | Duration of the sliding window in seconds. |
+| `key` | The entity to key the counter on (`"tenant"`, `"user"`, `"ip"`, etc.). Your app must read this and apply the counter accordingly. |
+
+{% hint style="info" %}
+The SDK does not maintain counters. It signals the throttle intent and parameters. Your infrastructure (middleware, Redis, etc.) is responsible for tracking and enforcing the rate limit.
+{% endhint %}
+
+**Handling a throttle:**
+
+```typescript
+if (result.decision === "throttle") {
+  const allowed = await rateLimiter.check(
+    result.throttle.key === "tenant" ? ctx.tenantId : ctx.userId,
+    result.throttle.limit,
+    result.throttle.windowSeconds,
+  );
+  if (!allowed) {
+    return reply.status(429)
+      .header("Retry-After", String(result.throttle.windowSeconds))
+      .send({ error: "Too Many Requests" });
+  }
+  // within limit — proceed
+}
+```
+
+**Strictest-wins rule:** When multiple `throttle` rules match, the engine selects the one with the lowest request-per-second rate (i.e. the most restrictive limit), not the one with the highest priority.
+
+---
+
+## `kill_switch`
+
+Immediately blocks all traffic to a service. Designed for incidents and emergency shutdowns.
+
+**Bundle rule shape:**
+
+```json
+{
+  "id": "r_kill_payments",
+  "status": "active",
+  "priority": 1,
+  "target": { "service": "payments", "resource": "*", "action": "*" },
+  "effect": {
+    "type": "kill_switch",
+    "killSwitch": {
+      "service": "payments",
+      "reason": "Database degradation detected — incident INC-4421"
+    }
+  }
+}
+```
+
+**Decision shape:**
+
+```typescript
+{
+  decision: "kill_switch",
+  reason: "rule",
+  policyKey: "payments-circuit-breaker",
+  ruleId: "r_kill_payments",
+  killSwitch: { service: "payments", reason: "Database degradation detected — incident INC-4421" }
+}
+```
+
+**Handling a kill switch:**
+
+```typescript
+if (result.decision === "kill_switch") {
+  logger.error("kill_switch active", { service: result.killSwitch.service });
+  return reply.status(503).send({
+    error: "Service Unavailable",
+    reason: result.killSwitch.reason,
+  });
+}
+```
+
+{% hint style="danger" %}
+`kill_switch` has the highest precedence. It overrides any `allow`, `deny`, `throttle`, or `custom` decision from any other rule in any policy.
+{% endhint %}
+
+---
+
+## `custom`
+
+Returns an arbitrary string value — including a JSON-encoded object — defined in the bundle. Useful for feature flags, A/B variants, contextual metadata, or any structured response that does not fit the other effect types.
+
+See [Custom Effects](CustomEffect.md) for the full reference.
+
+**Decision shape (summary):**
+
+```typescript
+{
+  decision: "custom",
+  reason: "rule",
+  policyKey: "feature-flags",
+  ruleId: "r_flags_pro",
+  value: "{\"newCheckout\": true, \"aiSearch\": false}",
+  parsedValue: { newCheckout: true, aiSearch: false }  // present when parseCustomEffect is enabled
+}
+```
+
+---
+
+{% content-ref url="CustomEffect.md" %}
+[Custom Effects](CustomEffect.md)
+{% endcontent-ref %}
+
+{% content-ref url="PolicyDefaults.md" %}
+[Policy Defaults](PolicyDefaults.md)
+{% endcontent-ref %}

package/docs/usage/Evaluate.md

@@ -0,0 +1,164 @@
+---
+description: >-
+  The two evaluation methods, their inputs and outputs, and how to handle every
+  decision type.
+---
+
+# Evaluating Decisions
+
+## `evaluate()`
+
+The primary API. Synchronous, in-process, sub-millisecond.
+
+```typescript
+const result = client.evaluate({
+  target: {
+    service:  "api",       // logical service name
+    resource: "invoices",  // resource identifier
+    action:   "create",    // action being performed
+  },
+  context: {
+    role:            "billing_admin",
+    plan:            "enterprise",
+    isAuthenticated: true,
+  },
+});
+```
+
+### Return value — `Decision`
+
+`evaluate()` always returns a `Decision` object. The `decision` discriminant tells you which effect was applied.
+
+```typescript
+type Decision =
+  | { decision: "allow";       reason: "default" | "rule"; policyKey?: string; ruleId?: string }
+  | { decision: "deny";        reason: "default" | "rule"; policyKey?: string; ruleId?: string }
+  | { decision: "kill_switch"; reason: "default" | "rule"; policyKey?: string; ruleId?: string;
+      killSwitch: { service: string; reason?: string } }
+  | { decision: "throttle";    reason: "default" | "rule"; policyKey?: string; ruleId?: string;
+      throttle: { limit: number; windowSeconds: number; key: string } }
+  | { decision: "custom";      reason: "default" | "rule"; policyKey?: string; ruleId?: string;
+      value: string; parsedValue?: unknown };
+```
+
+| Field | Description |
+|---|---|
+| `decision` | The effect that was applied. |
+| `reason` | `"rule"` when a matching rule produced the effect; `"default"` when a policy default or the SDK's global deny-by-default fired. |
+| `policyKey` | The policy that produced the decision (absent on global deny-by-default). |
+| `ruleId` | The specific rule that matched (absent when `reason` is `"default"`). |
+
+### Handling every decision type
+
+```typescript
+const result = client.evaluate({ target, context });
+
+if (result.decision === "allow") {
+  return next(); // proceed
+}
+
+if (result.decision === "deny") {
+  return reply.status(403).send({ error: "Forbidden", policy: result.policyKey });
+}
+
+if (result.decision === "throttle") {
+  return reply.status(429)
+    .header("Retry-After", String(result.throttle.windowSeconds))
+    .send({ error: "Too Many Requests", limit: result.throttle.limit });
+}
+
+if (result.decision === "kill_switch") {
+  return reply.status(503).send({
+    error: "Service Unavailable",
+    reason: result.killSwitch.reason,
+  });
+}
+
+if (result.decision === "custom") {
+  // raw string value always available
+  const payload = result.parsedValue ?? JSON.parse(result.value);
+  return reply.send(payload);
+}
+```
+
+---
+
+## `evaluateWithTrace()`
+
+Same as `evaluate()` but can attach a `DecisionTrace` to the returned object for observability. The trace level and sampling rate are controlled by your configuration.
+
+```typescript
+const result = client.evaluateWithTrace(
+  { target, context },
+  { level: "full", force: true }   // per-call override (optional)
+);
+
+if (result.trace) {
+  logger.info(result.trace);
+}
+```
+
+The trace is only present when the configured `level`, `sampling`, and `budget` allow it. See [Decision Tracing](DecisionTrace.md) for the full reference.
+
+---
+
+## Target matching
+
+A rule matches a call when all three fields in `target` are identical (exact string match, case-sensitive).
+
+```typescript
+// This call matches only rules whose target is exactly:
+// service="payments", resource="checkout", action="create"
+client.evaluate({
+  target: { service: "payments", resource: "checkout", action: "create" },
+  context: { ... },
+});
+```
+
+{% hint style="warning" %}
+There are no wildcards in target matching. Each service/resource/action combination is an exact literal string. Design your target namespace accordingly.
+{% endhint %}
+
+---
+
+## Decision precedence
+
+When multiple rules across multiple policies match the same target, the SDK applies a fixed precedence order:
+
+```
+kill_switch  >  deny  >  throttle  >  allow  >  custom  >  deny-by-default
+```
+
+Within the same effect type, the rule with the **highest `priority`** value wins. Ties are broken lexicographically by `policyKey`, then `ruleId`.
+
+Policy-level defaults are treated as synthetic rules with `priority = -1`, so any explicit rule always wins over a policy default.
+
+---
+
+## Using `createPolicyEngine` directly
+
+If you manage the bundle yourself (e.g. read from a file, injected via config) you can bypass `RuntimeClient` and use the engine standalone:
+
+```typescript
+import { createPolicyEngine } from "@govplane/runtime-sdk";
+import { readFileSync } from "node:fs";
+
+const bundle = JSON.parse(readFileSync("bundle.json", "utf8"));
+
+const engine = createPolicyEngine({
+  getBundle: () => bundle,
+  parseCustomEffect: true,
+});
+
+const result = engine.evaluate({ target, context });
+```
+
+---
+
+{% content-ref url="Effects.md" %}
+[Effect Types](Effects.md)
+{% endcontent-ref %}
+
+{% content-ref url="DecisionTrace.md" %}
+[Decision Tracing](DecisionTrace.md)
+{% endcontent-ref %}