nexus-agents 4.26.9 → 4.28.0

package/dist/{consensus-vote-ZCZJS543.js → consensus-vote-YYHQHD7V.js}

@@ -11,12 +11,12 @@ import {
   resetCorrelationTracker,
   runConsensusForGoal,
   unwrapVoteOrThrow
-} from "./chunk-O7LX6CCH.js";
+} from "./chunk-6OAWETHW.js";
 import "./chunk-NAL4EHFM.js";
 import "./chunk-OQB3XC5O.js";
-import "./chunk-YOGYNVAN.js";
-import "./chunk-ARR4ZJVE.js";
-import "./chunk-MJQVSJZB.js";
+import "./chunk-7V5V6H5C.js";
+import "./chunk-D2E5PC2V.js";
+import "./chunk-RV57MIQU.js";
 import "./chunk-N3SKF4YT.js";
 import "./chunk-PU2NTY6U.js";
 import "./chunk-6T3EPABN.js";
@@ -50,4 +50,4 @@ export {
   runConsensusForGoal,
   unwrapVoteOrThrow
 };
-//# sourceMappingURL=consensus-vote-ZCZJS543.js.map
+//# sourceMappingURL=consensus-vote-YYHQHD7V.js.map

package/dist/{improvement-review-GG7IIXBS.js → improvement-review-C74SDVTQ.js}

@@ -11,10 +11,10 @@ import {
   loadSelfEvalSignals,
   registerImprovementReviewTool,
   runImprovementReview
-} from "./chunk-DHYDTSS3.js";
-import "./chunk-YOGYNVAN.js";
-import "./chunk-ARR4ZJVE.js";
-import "./chunk-MJQVSJZB.js";
+} from "./chunk-Q4T3UWOC.js";
+import "./chunk-7V5V6H5C.js";
+import "./chunk-D2E5PC2V.js";
+import "./chunk-RV57MIQU.js";
 import "./chunk-6Q4XUAE5.js";
 import "./chunk-GBHJ37V3.js";
 import "./chunk-OGHEKPLD.js";
@@ -33,4 +33,4 @@ export {
   registerImprovementReviewTool,
   runImprovementReview
 };
-//# sourceMappingURL=improvement-review-GG7IIXBS.js.map
+//# sourceMappingURL=improvement-review-C74SDVTQ.js.map

package/dist/index.d.ts

@@ -21293,7 +21293,38 @@ interface DryRunResult {
  * Dependencies required by the run_workflow tool.
  */
 interface RunWorkflowDeps extends BaseMcpToolDeps {
+    /**
+     * Engine used to ENUMERATE and load templates — `listTemplates`,
+     * `getTemplateByName`, `loadTemplate`. Never used to execute.
+     *
+     * Listing needs no model adapter, so this engine is constructible on a fresh
+     * install with no credentials. That is the capability split #5116 turns on:
+     * enumerating workflows and running them have different prerequisites.
+     */
     workflowEngine: IWorkflowEngine;
+    /**
+     * Resolves the engine that actually EXECUTES, at call time (#5116).
+     *
+     * A THUNK rather than a value because constructing an executing engine throws
+     * `WorkflowExecutionUnavailableError` under the #507 fail-safe when nothing
+     * can execute for real — doing that eagerly at tool registration killed the
+     * whole server, all 47 tools, over one unconfigured adapter.
+     *
+     * OPTIONAL rather than required, by unanimous panel decision. It was briefly
+     * required, which is how all eight internal call sites were enumerated by the
+     * compiler — that value is already banked. Keeping it required would make
+     * this a breaking change to a publicly exported type (`exports/mcp.ts`) and
+     * gate a p1 correctness fix behind a major version.
+     *
+     * Defaulting to `workflowEngine` is semantically correct for an external
+     * caller, not merely compile-compatible: their single engine genuinely serves
+     * both listing and execution, so the fallback preserves exactly what they had.
+     * The residual hazard — a future INTERNAL call site omitting this and
+     * executing against a listing engine — is covered two ways: a test asserting
+     * the production registration supplies it, and the listing engine failing
+     * closed rather than returning a fabricated success.
+     */
+    resolveExecutionEngine?: (() => IWorkflowEngine) | undefined;
     /** MCP notifier for client-visible logging (Issue #974) */
     notifier?: IMcpNotifier | undefined;
 }
@@ -30690,6 +30721,21 @@ interface ClawGuardViolationEvent extends AuditEventBase {
     readonly mode: string;
     /** Request ID of the offending tool call, for correlation. */
     readonly requestId: string;
+    /**
+     * Which rule produced the verdict (#5106) — `unbypassable:tool`,
+     * `unbypassable:path`, `allowedTools`, `allowedTools:confirm_risky`.
+     *
+     * A first-class field rather than prose inside `warning`, because `warning`
+     * is truncated at 500 chars and a long attacker-selectable `path` argument
+     * pushes the rule off the end. A chain reader must be able to tell an
+     * unbypassable denylist hit from an allowlist miss without parsing a string
+     * that may have been cut mid-word.
+     *
+     * Absent for verdicts that carry no rule (an audit-mode allowlist
+     * observation), which is why it is optional rather than defaulted — there is
+     * no rule to name, and inventing one would misreport.
+     */
+    readonly matchedRule?: string;
 }
 /** Graph execution lifecycle event (Issue #839). */
 interface GraphExecutionAuditEvent extends AuditEventBase {

package/dist/index.js

@@ -553,7 +553,7 @@ import {
   withLogging,
   withRetry,
   withRetryWrapper
-} from "./chunk-VYZWF4DB.js";
+} from "./chunk-EGO754SU.js";
 import {
   FALLBACK_SCANNER_DATA,
   buildPlanFromAnalysis,
@@ -574,7 +574,7 @@ import {
   connectTransport,
   createServer,
   startStdioServer
-} from "./chunk-MQTXQPFN.js";
+} from "./chunk-VEFRTBUE.js";
 import {
   OPENAI_MODELS,
   OPENAI_MODEL_ALIASES,
@@ -632,7 +632,7 @@ import {
   generateProposalId,
   parseAgentPairKey,
   registerConsensusVoteTool
-} from "./chunk-O7LX6CCH.js";
+} from "./chunk-6OAWETHW.js";
 import "./chunk-NAL4EHFM.js";
 import {
   allOf
@@ -660,7 +660,7 @@ import {
   requiresHumanApproval,
   validateAgentAction,
   validateCorroboration
-} from "./chunk-FQQOROWP.js";
+} from "./chunk-LLJ65HUO.js";
 import {
   GitHubProvider,
   ScmError
@@ -683,7 +683,7 @@ import {
 import {
   ImprovementReviewInputSchema,
   registerImprovementReviewTool
-} from "./chunk-DHYDTSS3.js";
+} from "./chunk-Q4T3UWOC.js";
 import {
   AgentPerformanceSchema,
   ConsensusAlgorithmSchema,
@@ -719,10 +719,10 @@ import {
   toolSuccess,
   toolSuccessStructured,
   validateToolInput
-} from "./chunk-YOGYNVAN.js";
+} from "./chunk-7V5V6H5C.js";
 import {
   VERSION
-} from "./chunk-ARR4ZJVE.js";
+} from "./chunk-D2E5PC2V.js";
 import {
   AuditTrail,
   MAX_STRIPPED_ELEMENTS_PER_EVENT,
@@ -734,7 +734,7 @@ import {
   emitReputationEvent,
   emitSanitizationEvent,
   emitTrustEvent
-} from "./chunk-MJQVSJZB.js";
+} from "./chunk-RV57MIQU.js";
 import {
   UnifiedAdapterRegistry,
   createUnifiedRegistry,
@@ -4729,7 +4729,7 @@ function buildVotingInput(plan, config) {
 }
 async function executeSingleVote(plan, config, log) {
   try {
-    const { executeVoting } = await import("./consensus-vote-ZCZJS543.js");
+    const { executeVoting } = await import("./consensus-vote-YYHQHD7V.js");
     const input = buildVotingInput(plan, config);
     const result = await executeVoting(input, log);
     return parseVotingResult(result);

package/dist/{issue-triage-N4ZYYJYR.js → issue-triage-BOGQS5GP.js}

@@ -1,10 +1,10 @@
 import {
   IssueTriage,
   createIssueTriage
-} from "./chunk-FQQOROWP.js";
+} from "./chunk-LLJ65HUO.js";
 import "./chunk-PSZVTY77.js";
 import "./chunk-UBWHBW7S.js";
-import "./chunk-MJQVSJZB.js";
+import "./chunk-RV57MIQU.js";
 import "./chunk-V353Q4L7.js";
 import "./chunk-6Q4XUAE5.js";
 import "./chunk-GBHJ37V3.js";
@@ -14,4 +14,4 @@ export {
   IssueTriage,
   createIssueTriage
 };
-//# sourceMappingURL=issue-triage-N4ZYYJYR.js.map
+//# sourceMappingURL=issue-triage-BOGQS5GP.js.map

package/dist/{setup-data-dir-CF5HCZ3V.js → setup-data-dir-YSN7UU3M.js}

@@ -2,11 +2,11 @@ import {
   NEXUS_DATA_DIR,
   describeDataDirFix,
   initDataDirectories
-} from "./chunk-MQTXQPFN.js";
+} from "./chunk-VEFRTBUE.js";
 import "./chunk-VCM2NHH7.js";
 import "./chunk-NAL4EHFM.js";
 import "./chunk-OQB3XC5O.js";
-import "./chunk-ARR4ZJVE.js";
+import "./chunk-D2E5PC2V.js";
 import "./chunk-6T3EPABN.js";
 import "./chunk-IED5SFCF.js";
 import "./chunk-QUVWKVKU.js";
@@ -26,4 +26,4 @@ export {
   describeDataDirFix,
   initDataDirectories
 };
-//# sourceMappingURL=setup-data-dir-CF5HCZ3V.js.map
+//# sourceMappingURL=setup-data-dir-YSN7UU3M.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexus-agents",
-  "version": "4.26.9",
+  "version": "4.28.0",
   "description": "Governance substrate for AI coding agents — adversarial PR review, drift-detected rules, tamper-evident audit, and closed-loop outcome routing for Claude, Codex, Gemini, and OpenCode",
   "mcpName": "io.github.nexus-substrate/nexus-agents",
   "license": "MIT",

package/dist/chunk-ARR4ZJVE.js

@@ -1,7 +0,0 @@
-// src/version.ts
-var VERSION = true ? "4.26.9" : "dev";
-
-export {
-  VERSION
-};
-//# sourceMappingURL=chunk-ARR4ZJVE.js.map

package/dist/chunk-MJQVSJZB.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/security/audit-trail.ts"],"sourcesContent":["/**\n * nexus-agents/security - Audit Trail\n *\n * Machine-readable JSON audit events for security pipeline decisions.\n * Every trust classification, policy gate decision, corroboration check,\n * and reputation assessment is recorded as a structured event.\n *\n * Satisfies CLAUDE.md requirement: \"Every action on untrusted input must\n * log: trust tier, sources cited, policy gate decision, stripped content.\"\n *\n * @module security/audit-trail\n * (Source: Issue #832 — Security audit trail)\n */\n\nimport { getTimeProvider } from '../core/index.js';\nimport type { TrustTier } from './trust-types.js';\nimport type { AgentActionType } from './action-schema.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/** Maximum stored events before oldest are evicted. */\nconst MAX_EVENTS = 10_000;\n\n/**\n * Discriminated union of audit event types.\n * Each event captures a single security pipeline decision.\n */\nexport type AuditEvent =\n  | TrustClassificationEvent\n  | PolicyGateEvent\n  | CorroborationEvent\n  | ReputationEvent\n  | SanitizationEvent\n  | GraphExecutionAuditEvent\n  | ClawGuardViolationEvent;\n\n/** Base fields shared by all audit events. */\ninterface AuditEventBase {\n  readonly id: string;\n  readonly timestamp: string;\n  readonly component: string;\n}\n\n/** Trust classification decision. */\nexport interface TrustClassificationEvent extends AuditEventBase {\n  readonly type: 'trust_classification';\n  readonly username: string;\n  readonly assignedTier: TrustTier;\n  readonly userRole: string;\n  readonly isAllowlisted: boolean;\n  readonly wasDowngraded: boolean;\n  readonly reason: string;\n}\n\n/** Policy gate evaluation result. */\nexport interface PolicyGateEvent extends AuditEventBase {\n  readonly type: 'policy_gate';\n  /**\n   * The agent action evaluated, for the security policy-gate path\n   * (security/policy-gate.ts). Optional because the PIPELINE policy path\n   * (pipeline/policy-evaluator.ts → #3710) records stage-boundary policy\n   * decisions that have no `AgentAction` — they carry {@link stageType} +\n   * {@link mode} + {@link ruleIds} instead. Security emitters always set it.\n   */\n  readonly actionType?: AgentActionType;\n  readonly allowed: boolean;\n  readonly requiresApproval: boolean;\n  readonly inputTrustTier: TrustTier;\n  readonly violationRules: readonly string[];\n  /**\n   * Pipeline-policy fields (#3710). Carried for the dev-pipeline\n   * consensus→execute seam so the DURABLE record can distinguish soak (`warn`)\n   * from enforce (`block`) and which rules/stage fired — without these the\n   * persisted event is useless to the tune/readiness loop. Absent for the\n   * security policy-gate path.\n   */\n  /** Enforcement mode the decision was made under: `warn` (soak) or `block` (enforce). */\n  readonly mode?: 'off' | 'warn' | 'block';\n  /** IDs of the policy rules that fired (mirrors `violationRules` for the pipeline path). */\n  readonly ruleIds?: readonly string[];\n  /** Type of the stage the gate guarded (e.g. `execute`). */\n  readonly stageType?: string;\n  /**\n   * #3727: discriminates a per-EVALUATION SUMMARY record (`'summary'` — emitted\n   * once per pipeline policy evaluation INCLUDING clean ones, the DENOMINATOR for\n   * the would-block rate) from a per-VIOLATION record (`'violation'` — the\n   * existing #3710 per-violation records). Absent for the security policy-gate\n   * path. Denominator = count(recordKind==='summary'); numerator = summaries with\n   * `violationCount > 0`. Scope the #3710 count-parity assertion to `'violation'`.\n   */\n  readonly recordKind?: 'summary' | 'violation';\n  /** #3727: number of violations in THIS evaluation (set on the summary record). */\n  readonly violationCount?: number;\n}\n\n/** Corroboration validation result. */\nexport interface CorroborationEvent extends AuditEventBase {\n  readonly type: 'corroboration';\n  readonly actionType: AgentActionType;\n  readonly satisfied: boolean;\n  readonly sourceCount: number;\n  readonly missingRequirements: readonly string[];\n}\n\n/** Reputation assessment result. */\nexport interface ReputationEvent extends AuditEventBase {\n  readonly type: 'reputation';\n  readonly username: string;\n  readonly reputationScore: number;\n  readonly isSuspicious: boolean;\n  readonly effectiveTier: TrustTier;\n  readonly signalCount: number;\n}\n\n/** Summary of a single element stripped during sanitization. */\nexport interface StrippedElementSummary {\n  /** Truncated tag text (≤30 chars + '...' from the sanitizer). */\n  readonly tag: string;\n  /** Reason the element was removed (e.g. 'Trail of Bits injection vector'). */\n  readonly reason: string;\n}\n\n/** Max stripped-element details retained per sanitization event. */\nexport const MAX_STRIPPED_ELEMENTS_PER_EVENT = 20;\n\n/** Input sanitization result. */\nexport interface SanitizationEvent extends AuditEventBase {\n  readonly type: 'sanitization';\n  readonly source: string;\n  readonly wasModified: boolean;\n  readonly strippedCount: number;\n  readonly injectionFlagCount: number;\n  /**\n   * Per-element tag/reason details, truncated to at most\n   * MAX_STRIPPED_ELEMENTS_PER_EVENT entries. Required by CLAUDE.md's\n   * Untrusted Input Policy: \"Log stripped elements for audit trail.\"\n   */\n  readonly strippedElements: readonly StrippedElementSummary[];\n}\n\n/**\n * ClawGuard AUDIT-mode violation (#4097). Records a tool call that VIOLATED the\n * derived access policy but was ALLOWED to proceed because the policy is in\n * `audit` mode (log-and-allow). Persisting these is what lets the audit→enforce\n * graduation loop size the real violation rate from durable telemetry rather\n * than ephemeral logs.\n */\nexport interface ClawGuardViolationEvent extends AuditEventBase {\n  readonly type: 'clawguard_violation';\n  /** The tool whose call violated the policy. */\n  readonly toolName: string;\n  /** Human-readable warning from the access decision (may be truncated). */\n  readonly warning: string;\n  /** Source of the derived policy (`llm` / `fallback-keyword` / `bypass`). */\n  readonly policySource: string;\n  /** Policy mode under which the violation was allowed (e.g. `audit`). */\n  readonly mode: string;\n  /** Request ID of the offending tool call, for correlation. */\n  readonly requestId: string;\n}\n\n/** Graph execution lifecycle event (Issue #839). */\nexport interface GraphExecutionAuditEvent extends AuditEventBase {\n  readonly type: 'graph_execution';\n  readonly graphEvent: string;\n  readonly nodeId?: string;\n  readonly stepNumber: number;\n  readonly detail: string;\n}\n\n/**\n * Query filter for retrieving audit events.\n *\n * The post-mortem dimensions (#3197) — `actionType`, `actor`, `violationRule`\n * — NARROW to events that actually carry the field (events lacking it are\n * excluded), unlike `trustTier`'s legacy keep-non-applicable behavior. Only\n * dimensions backed by a real event field are offered: `resource` and\n * `policyName` from the original ask were dropped because no AuditEvent\n * records them (a filter with no backing field would be dead config); the\n * policy-rule intent is served by `violationRule` (PolicyGateEvent's\n * `violationRules`).\n */\nexport interface AuditQuery {\n  readonly type?: AuditEvent['type'];\n  readonly since?: string;\n  readonly until?: string;\n  readonly trustTier?: TrustTier;\n  /** Match PolicyGate/Corroboration events by their `actionType`. */\n  readonly actionType?: AgentActionType;\n  /** Match Trust/Reputation events by `username` (the acting/assessed user). */\n  readonly actor?: string;\n  /** Match PolicyGate events whose `violationRules` include this rule name. */\n  readonly violationRule?: string;\n  readonly limit?: number;\n}\n\n// ============================================================================\n// AuditTrail\n// ============================================================================\n\n/**\n * Append-only audit trail for security pipeline decisions.\n * Events are bounded by MAX_EVENTS to prevent unbounded growth.\n */\n/**\n * Optional durable sink: receives every fully-formed event appended to the\n * trail, so security decisions can be mirrored to a persistent, hash-chained\n * store (see security/audit-bridge.ts). Default-off — when absent, the trail\n * behaves exactly as before (#3291).\n */\nexport type DurableAuditSink = (event: AuditEvent) => void;\n\nexport class AuditTrail {\n  private events: AuditEvent[] = [];\n  private nextId = 1;\n\n  constructor(private readonly durableSink?: DurableAuditSink) {}\n\n  /** Appends an event to the trail. Returns the assigned event ID. */\n  append(event: Omit<AuditEvent, 'id' | 'timestamp'>): string {\n    const id = `audit-${String(this.nextId++)}`;\n    const fullEvent = {\n      ...event,\n      id,\n      timestamp: getTimeProvider().nowIso(),\n    } as AuditEvent;\n\n    this.events.push(fullEvent);\n    this.enforceLimit();\n\n    // Mirror to the durable store when wired (#3291). Best-effort: a sink\n    // failure must never break the in-memory security pipeline.\n    if (this.durableSink !== undefined) {\n      try {\n        this.durableSink(fullEvent);\n      } catch {\n        // Sink implementations already swallow+log; this is belt-and-suspenders.\n      }\n    }\n\n    return id;\n  }\n\n  /** Queries events matching the given filter. */\n  query(filter: AuditQuery = {}): readonly AuditEvent[] {\n    let results = this.events as readonly AuditEvent[];\n\n    if (filter.type !== undefined) {\n      results = results.filter((e) => e.type === filter.type);\n    }\n\n    if (filter.since !== undefined) {\n      results = filterSince(results, filter.since);\n    }\n\n    if (filter.until !== undefined) {\n      results = filterUntil(results, filter.until);\n    }\n\n    if (filter.trustTier !== undefined) {\n      results = filterByTrustTier(results, filter.trustTier);\n    }\n\n    if (filter.actionType !== undefined) {\n      results = filterByActionType(results, filter.actionType);\n    }\n\n    if (filter.actor !== undefined) {\n      results = filterByActor(results, filter.actor);\n    }\n\n    if (filter.violationRule !== undefined) {\n      results = filterByViolationRule(results, filter.violationRule);\n    }\n\n    const limit = filter.limit ?? results.length;\n    return results.slice(-limit);\n  }\n\n  /** Returns the total number of events. */\n  get size(): number {\n    return this.events.length;\n  }\n\n  /** Clears all events. */\n  clear(): void {\n    this.events = [];\n  }\n\n  /** Enforces MAX_EVENTS bound. */\n  private enforceLimit(): void {\n    if (this.events.length > MAX_EVENTS) {\n      this.events = this.events.slice(-MAX_EVENTS);\n    }\n  }\n}\n\n// ============================================================================\n// Filter Helpers\n// ============================================================================\n\nfunction filterSince(events: readonly AuditEvent[], since: string): readonly AuditEvent[] {\n  const sinceTime = new Date(since).getTime();\n  return events.filter((e) => new Date(e.timestamp).getTime() >= sinceTime);\n}\n\nfunction filterUntil(events: readonly AuditEvent[], until: string): readonly AuditEvent[] {\n  const untilTime = new Date(until).getTime();\n  return events.filter((e) => new Date(e.timestamp).getTime() <= untilTime);\n}\n\nfunction filterByTrustTier(events: readonly AuditEvent[], tier: TrustTier): readonly AuditEvent[] {\n  return events.filter((e) => {\n    if (e.type === 'trust_classification') return e.assignedTier === tier;\n    if (e.type === 'policy_gate') return e.inputTrustTier === tier;\n    if (e.type === 'reputation') return e.effectiveTier === tier;\n    return true;\n  });\n}\n\n/**\n * Narrow to events carrying the given `actionType` (#3197). Only PolicyGate and\n * Corroboration events have one; all others are excluded.\n */\nfunction filterByActionType(\n  events: readonly AuditEvent[],\n  actionType: AgentActionType\n): readonly AuditEvent[] {\n  return events.filter(\n    (e) => (e.type === 'policy_gate' || e.type === 'corroboration') && e.actionType === actionType\n  );\n}\n\n/**\n * Narrow to events for the given actor (#3197), matched on `username`. Only\n * Trust-classification and Reputation events carry a username; others are\n * excluded so an actor filter never returns unrelated rows.\n */\nfunction filterByActor(events: readonly AuditEvent[], actor: string): readonly AuditEvent[] {\n  return events.filter(\n    (e) => (e.type === 'trust_classification' || e.type === 'reputation') && e.username === actor\n  );\n}\n\n/**\n * Narrow to PolicyGate events whose `violationRules` include the given rule\n * name (#3197) — the security post-mortem \"who tripped rule X\" query.\n */\nfunction filterByViolationRule(events: readonly AuditEvent[], rule: string): readonly AuditEvent[] {\n  return events.filter((e) => e.type === 'policy_gate' && e.violationRules.includes(rule));\n}\n\n// ============================================================================\n// Convenience Emitters\n// ============================================================================\n\n/**\n * Records a trust classification decision.\n */\nexport function emitTrustEvent(\n  trail: AuditTrail,\n  data: Omit<TrustClassificationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'trust_classification',\n    component: 'trust-classifier',\n    ...data,\n  });\n}\n\n/**\n * Records a policy gate evaluation.\n */\nexport function emitPolicyEvent(\n  trail: AuditTrail,\n  data: Omit<PolicyGateEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'policy_gate',\n    component: 'policy-gate',\n    ...data,\n  });\n}\n\n/**\n * Records a PIPELINE-policy gate decision (#3710) — the dev-pipeline\n * consensus→execute seam. Distinct from {@link emitPolicyEvent} (the security\n * policy-gate path with an `AgentAction`): this carries `mode`/`ruleIds`/\n * `stageType` so the durable record distinguishes soak(warn) from enforce(block)\n * and is usable by the tune/readiness loop. ONE append per call.\n */\nexport function emitPipelinePolicyEvent(\n  trail: AuditTrail,\n  data: Omit<PolicyGateEvent, 'id' | 'timestamp' | 'type' | 'component' | 'actionType'>\n): string {\n  return trail.append({\n    type: 'policy_gate',\n    component: 'pipeline-policy-evaluator',\n    ...data,\n  });\n}\n\n/** The pipeline-policy would-block rate over a window (#3727). */\nexport interface PolicyWouldBlockRate {\n  /** Total pipeline-policy evaluations (the denominator — summary records). */\n  readonly evaluations: number;\n  /** Evaluations that had ≥1 violation (what enforce mode WOULD block). */\n  readonly wouldBlock: number;\n  /** `wouldBlock / evaluations`; 0 when there are no evaluations. */\n  readonly rate: number;\n}\n\n/**\n * Compute the pipeline-policy would-block RATE from durable audit events (#3727)\n * — the read-side of the per-evaluation summary records, and the signal the\n * #3769-enforce soak-readiness gate needs. Denominator = per-evaluation SUMMARY\n * records (`recordKind === 'summary'`); numerator = summaries with\n * `violationCount > 0` (the would-block fraction, independent of warn/block mode).\n * Per-violation records (`recordKind === 'violation'`) are intentionally NOT\n * counted — counting them would double-count and break the denominator.\n */\nexport function computePolicyWouldBlockRate(events: readonly AuditEvent[]): PolicyWouldBlockRate {\n  let evaluations = 0;\n  let wouldBlock = 0;\n  for (const e of events) {\n    if (e.type !== 'policy_gate' || e.recordKind !== 'summary') continue;\n    evaluations += 1;\n    if ((e.violationCount ?? 0) > 0) wouldBlock += 1;\n  }\n  return { evaluations, wouldBlock, rate: evaluations > 0 ? wouldBlock / evaluations : 0 };\n}\n\n/**\n * Records a corroboration validation.\n */\nexport function emitCorroborationEvent(\n  trail: AuditTrail,\n  data: Omit<CorroborationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'corroboration',\n    component: 'corroboration-validator',\n    ...data,\n  });\n}\n\n/**\n * Records a reputation assessment.\n */\nexport function emitReputationEvent(\n  trail: AuditTrail,\n  data: Omit<ReputationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'reputation',\n    component: 'reputation-model',\n    ...data,\n  });\n}\n\n/**\n * Records an input sanitization result.\n */\nexport function emitSanitizationEvent(\n  trail: AuditTrail,\n  data: Omit<SanitizationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'sanitization',\n    component: 'input-sanitizer',\n    ...data,\n  });\n}\n\n/**\n * Records a graph execution lifecycle event.\n */\nexport function emitGraphExecutionEvent(\n  trail: AuditTrail,\n  data: Omit<GraphExecutionAuditEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'graph_execution',\n    component: 'graph-executor',\n    ...data,\n  });\n}\n\n/**\n * Records a ClawGuard AUDIT-mode violation (#4097) — a policy-violating tool\n * call that was log-and-allowed because the policy is in `audit` mode. ONE\n * append per call; mirrors to the durable sink when the trail is wired.\n */\nexport function emitClawGuardViolation(\n  trail: AuditTrail,\n  data: Omit<ClawGuardViolationEvent, 'id' | 'timestamp' | 'type' | 'component'>\n): string {\n  return trail.append({\n    type: 'clawguard_violation',\n    component: 'clawguard-audit',\n    ...data,\n  });\n}\n\n/**\n * Creates an onEvent callback that bridges graph events to the audit trail.\n * Pass the returned function as `onEvent` in GraphExecuteOptions.\n *\n * @example\n * const trail = createAuditTrail();\n * await executeGraph(graph, inputs, { onEvent: createGraphAuditBridge(trail) });\n */\nexport function createGraphAuditBridge(\n  trail: AuditTrail\n): (event: { readonly type: string; readonly [key: string]: unknown }) => void {\n  return (event) => {\n    const nodeId = typeof event['nodeId'] === 'string' ? event['nodeId'] : undefined;\n    const stepNumber = typeof event['stepNumber'] === 'number' ? event['stepNumber'] : 0;\n    emitGraphExecutionEvent(trail, {\n      graphEvent: event.type,\n      ...(nodeId !== undefined ? { nodeId } : {}),\n      stepNumber,\n      detail: formatGraphEventDetail(event),\n    });\n  };\n}\n\n/** Formats a brief detail string from a graph event. */\nfunction formatGraphEventDetail(event: {\n  readonly type: string;\n  readonly [key: string]: unknown;\n}): string {\n  switch (event.type) {\n    case 'node_started':\n      return `Node ${String(event['nodeId'])} starting`;\n    case 'node_completed':\n      return `Node ${String(event['nodeId'])} completed in ${String(event['durationMs'])}ms`;\n    case 'node_error':\n      return `Node ${String(event['nodeId'])} failed: ${String(event['error'])}`;\n    case 'state_updated':\n      return `State updated: ${String(event['updatedKeys'])}`;\n    case 'step_completed':\n      return `Step ${String(event['stepNumber'])}: ${String(event['nodesExecuted'])} nodes`;\n    case 'execution_complete':\n      return `Complete: ${String(event['totalSteps'])} steps, ${String(event['durationMs'])}ms`;\n    default:\n      return event.type;\n  }\n}\n\n/**\n * Creates a new AuditTrail instance. Pass a {@link DurableAuditSink} (e.g. from\n * `createDurableAuditSink(auditLogger)`) to mirror appended security decisions\n * to a durable, hash-chained store (#3291). Default: in-memory only.\n */\nexport function createAuditTrail(durableSink?: DurableAuditSink): AuditTrail {\n  return new AuditTrail(durableSink);\n}\n"],"mappings":"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","names":[]}