governance-sdk 0.5.0

package/dist/eval-trace.d.ts

@@ -0,0 +1,30 @@
+/**
+ * governance-sdk — In-Memory Trace Collector
+ *
+ * Captures agent operation traces for eval scoring.
+ * Default implementation stores traces in memory with configurable limits.
+ * Commercial deployments replace this with a persistent backend.
+ *
+ * @example
+ * ```ts
+ * import { createTraceCollector } from 'governance-sdk/eval-trace';
+ *
+ * const traces = createTraceCollector({ maxTraces: 200 });
+ * const ctx = traces.startTrace('luna', 'What deals closed this week?');
+ * const spanId = ctx.addSpan({
+ *   operation: 'tool_call', toolName: 'honeycomb_search',
+ *   input: { query: 'deals closed this week' },
+ *   output: { results: [...] }, latencyMs: 142, success: true,
+ * });
+ * const trace = ctx.end('3 deals closed this week totaling $45k');
+ * ```
+ */
+import type { TraceCollector } from "./eval-types.js";
+export interface TraceCollectorConfig {
+    /** Maximum traces to keep in memory (default: 100). Oldest evicted first. */
+    maxTraces?: number;
+    /** Maximum age in ms for pending (in-flight) traces before cleanup (default: 300000 / 5 min) */
+    pendingTimeoutMs?: number;
+}
+export declare function createTraceCollector(config?: TraceCollectorConfig): TraceCollector;
+//# sourceMappingURL=eval-trace.d.ts.map

package/dist/eval-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval-trace.d.ts","sourceRoot":"","sources":["../src/eval-trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAGV,cAAc,EAEf,MAAM,iBAAiB,CAAC;AAIzB,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gGAAgG;IAChG,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAID,wBAAgB,oBAAoB,CAAC,MAAM,GAAE,oBAAyB,GAAG,cAAc,CAkHtF"}

package/dist/eval-trace.js

@@ -0,0 +1,129 @@
+/**
+ * governance-sdk — In-Memory Trace Collector
+ *
+ * Captures agent operation traces for eval scoring.
+ * Default implementation stores traces in memory with configurable limits.
+ * Commercial deployments replace this with a persistent backend.
+ *
+ * @example
+ * ```ts
+ * import { createTraceCollector } from 'governance-sdk/eval-trace';
+ *
+ * const traces = createTraceCollector({ maxTraces: 200 });
+ * const ctx = traces.startTrace('luna', 'What deals closed this week?');
+ * const spanId = ctx.addSpan({
+ *   operation: 'tool_call', toolName: 'honeycomb_search',
+ *   input: { query: 'deals closed this week' },
+ *   output: { results: [...] }, latencyMs: 142, success: true,
+ * });
+ * const trace = ctx.end('3 deals closed this week totaling $45k');
+ * ```
+ */
+// ─── Implementation ────────────────────────────────────────────
+export function createTraceCollector(config = {}) {
+    const maxTraces = config.maxTraces ?? 100;
+    const pendingTimeoutMs = config.pendingTimeoutMs ?? 300_000; // 5 minutes
+    /** All completed traces, keyed by agentId → traces[] */
+    const store = new Map();
+    /** In-flight traces, keyed by traceId */
+    const pending = new Map();
+    function generateId() {
+        const bytes = new Uint8Array(16);
+        if (typeof globalThis.crypto !== "undefined" && globalThis.crypto.getRandomValues) {
+            globalThis.crypto.getRandomValues(bytes);
+        }
+        else {
+            for (let i = 0; i < 16; i++)
+                bytes[i] = Math.floor(Math.random() * 256);
+        }
+        return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+    }
+    function evict(agentId) {
+        const traces = store.get(agentId);
+        if (!traces)
+            return;
+        while (traces.length > maxTraces) {
+            traces.shift(); // remove oldest
+        }
+    }
+    /** Evict pending traces that have been in-flight longer than pendingTimeoutMs */
+    function evictStalePending() {
+        const now = Date.now();
+        for (const [traceId, entry] of pending) {
+            if (now - entry.createdAt > pendingTimeoutMs) {
+                pending.delete(traceId);
+            }
+        }
+    }
+    return {
+        startTrace(agentId, input, metadata) {
+            evictStalePending();
+            const traceId = generateId();
+            const trace = {
+                traceId,
+                agentId,
+                spans: [],
+                startedAt: new Date().toISOString(),
+                input,
+                metadata,
+            };
+            pending.set(traceId, { trace, agentId, createdAt: Date.now() });
+            let ended = false;
+            return {
+                traceId,
+                addSpan(spanData) {
+                    if (ended)
+                        return ""; // silently ignore spans after end
+                    const entry = pending.get(traceId);
+                    if (!entry)
+                        return "";
+                    const spanId = generateId().slice(0, 16);
+                    const span = {
+                        ...spanData,
+                        spanId,
+                        timestamp: new Date().toISOString(),
+                    };
+                    entry.trace.spans.push(span);
+                    return spanId;
+                },
+                end(output) {
+                    if (ended)
+                        return trace; // idempotent — return cached trace
+                    ended = true;
+                    const entry = pending.get(traceId);
+                    if (!entry)
+                        return trace;
+                    entry.trace.completedAt = new Date().toISOString();
+                    if (output !== undefined)
+                        entry.trace.output = output;
+                    // Move from pending to store
+                    pending.delete(traceId);
+                    if (!store.has(entry.agentId))
+                        store.set(entry.agentId, []);
+                    store.get(entry.agentId).push(entry.trace);
+                    evict(entry.agentId);
+                    return entry.trace;
+                },
+            };
+        },
+        getTraces(agentId) {
+            return store.get(agentId) ?? [];
+        },
+        getRecentTraces(agentId, since) {
+            const traces = store.get(agentId) ?? [];
+            const sinceMs = new Date(since).getTime();
+            return traces.filter((t) => new Date(t.startedAt).getTime() >= sinceMs);
+        },
+        traceCount() {
+            let total = 0;
+            for (const traces of store.values())
+                total += traces.length;
+            return total;
+        },
+        clear() {
+            store.clear();
+            pending.clear();
+        },
+    };
+}
+//# sourceMappingURL=eval-trace.js.map

package/dist/eval-trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval-trace.js","sourceRoot":"","sources":["../src/eval-trace.ts"],"names":[],"mappings":"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"}

package/dist/eval-types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * governance-sdk — Eval Type System
+ *
+ * Zero-dependency type definitions for the governance eval loop.
+ * Traces capture what agents do. Metrics measure quality.
+ * Results feed back into the governance score.
+ *
+ * @example
+ * ```ts
+ * import type { EvalTrace, EvalResult, TraceCollector } from 'governance-sdk/eval-types';
+ * ```
+ */
+/** The type of operation captured in a span. */
+export type SpanOperation = "llm_call" | "tool_call" | "retrieval" | "generation" | "embedding" | "guard" | "custom";
+/** A single operation within a trace. */
+export interface EvalSpan {
+    spanId: string;
+    parentSpanId?: string;
+    operation: SpanOperation;
+    /** What went in (prompt, tool args, query, etc.) */
+    input: unknown;
+    /** What came out (completion, tool result, documents, etc.) */
+    output: unknown;
+    /** Model used (if LLM call) */
+    model?: string;
+    /** Wall-clock duration */
+    latencyMs: number;
+    /** Token usage (if LLM call) */
+    tokenUsage?: {
+        input: number;
+        output: number;
+    };
+    /** Tool name (if tool call) */
+    toolName?: string;
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Error message (if failed) */
+    error?: string;
+    /** Arbitrary metadata */
+    metadata?: Record<string, unknown>;
+    timestamp: string;
+}
+/** A complete trace of an agent's work unit (one request/task). */
+export interface EvalTrace {
+    traceId: string;
+    agentId: string;
+    agentName?: string;
+    spans: EvalSpan[];
+    startedAt: string;
+    completedAt?: string;
+    /** The user/system input that triggered this trace */
+    input?: string;
+    /** The agent's final output */
+    output?: string;
+    /** Arbitrary context (task description, session ID, etc.) */
+    metadata?: Record<string, unknown>;
+}
+/** Standard governance eval metric names. */
+export type GovernanceMetricName = "tool_correctness" | "output_faithfulness" | "task_completion" | "safety_compliance" | "instruction_following" | "red_team_resistance";
+/** A single eval metric score. */
+export interface EvalMetric {
+    /** Metric name — use GovernanceMetricName for standard metrics */
+    name: string;
+    /** Score between 0 (worst) and 1 (best) */
+    score: number;
+    /** LLM-as-judge reasoning (why this score?) */
+    reasoning?: string;
+    /** Additional metric-specific data */
+    metadata?: Record<string, unknown>;
+}
+/** The result of evaluating one trace. */
+export interface EvalResult {
+    traceId: string;
+    agentId: string;
+    metrics: EvalMetric[];
+    evaluatedAt: string;
+}
+/** Handle returned when starting a trace — used to add spans and finish. */
+export interface TraceContext {
+    traceId: string;
+    /** Add a span to this trace. */
+    addSpan(span: Omit<EvalSpan, "spanId" | "timestamp">): string;
+    /** Mark the trace complete. Returns the full trace. */
+    end(output?: string): EvalTrace;
+}
+/** Collects traces from agent operations. */
+export interface TraceCollector {
+    /** Start a new trace for an agent action. */
+    startTrace(agentId: string, input?: string, metadata?: Record<string, unknown>): TraceContext;
+    /** Retrieve completed traces for an agent. */
+    getTraces(agentId: string): EvalTrace[];
+    /** Retrieve traces completed since a given time. */
+    getRecentTraces(agentId: string, since: string): EvalTrace[];
+    /** Total trace count (all agents). */
+    traceCount(): number;
+    /** Clear all stored traces. */
+    clear(): void;
+}
+/** Function that evaluates a trace and produces metrics. */
+export type EvalMetricFn = (trace: EvalTrace) => Promise<EvalMetric[]>;
+/** Configuration for an eval runner. */
+export interface EvalRunnerConfig {
+    /** Metrics to evaluate (functions that score traces) */
+    metrics: EvalMetricFn[];
+    /** Sample rate: evaluate 1 in N traces (default: 1 = all) */
+    sampleRate?: number;
+}
+//# sourceMappingURL=eval-types.d.ts.map

package/dist/eval-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval-types.d.ts","sourceRoot":"","sources":["../src/eval-types.ts"],"names":[],"mappings":"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"}

package/dist/eval-types.js

@@ -0,0 +1,14 @@
+/**
+ * governance-sdk — Eval Type System
+ *
+ * Zero-dependency type definitions for the governance eval loop.
+ * Traces capture what agents do. Metrics measure quality.
+ * Results feed back into the governance score.
+ *
+ * @example
+ * ```ts
+ * import type { EvalTrace, EvalResult, TraceCollector } from 'governance-sdk/eval-types';
+ * ```
+ */
+export {};
+//# sourceMappingURL=eval-types.js.map

package/dist/eval-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval-types.js","sourceRoot":"","sources":["../src/eval-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/events.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Governance Event Emitter
+ *
+ * Subscribe to governance events in real-time — enforcement decisions,
+ * agent registrations, kill switch activations, score changes.
+ * Essential for dashboards, monitoring, and alerting.
+ *
+ * Zero-dependency implementation using native EventTarget.
+ */
+export type GovernanceEventType = "enforcement" | "registration" | "kill" | "revive" | "score_change" | "policy_added" | "policy_removed" | "audit";
+export interface GovernanceEvent {
+    type: GovernanceEventType;
+    timestamp: string;
+    agentId?: string;
+    detail: Record<string, unknown>;
+}
+export type GovernanceEventHandler = (event: GovernanceEvent) => void;
+export interface GovernanceEmitter {
+    /** Subscribe to a specific event type */
+    on: (type: GovernanceEventType, handler: GovernanceEventHandler) => void;
+    /** Subscribe to all events */
+    onAny: (handler: GovernanceEventHandler) => void;
+    /** Unsubscribe from a specific event type */
+    off: (type: GovernanceEventType, handler: GovernanceEventHandler) => void;
+    /** Unsubscribe from all events */
+    offAny: (handler: GovernanceEventHandler) => void;
+    /** Emit an event (used internally by governance hooks) */
+    emit: (event: GovernanceEvent) => void;
+    /** Get count of listeners */
+    listenerCount: (type?: GovernanceEventType) => number;
+    /** Remove all listeners */
+    removeAllListeners: () => void;
+}
+/**
+ * Create a governance event emitter.
+ *
+ * Lightweight, synchronous, zero-dependency event system.
+ * Use with governance hooks to stream events to dashboards,
+ * logging systems, or alerting pipelines.
+ *
+ * @example
+ * ```ts
+ * const emitter = createGovernanceEmitter();
+ *
+ * emitter.on('enforcement', (event) => {
+ *   if (event.detail.blocked) {
+ *     alert(`Agent ${event.agentId} blocked!`);
+ *   }
+ * });
+ *
+ * emitter.onAny((event) => {
+ *   metrics.increment(`governance.${event.type}`);
+ * });
+ * ```
+ */
+export declare function createGovernanceEmitter(): GovernanceEmitter;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,MAAM,mBAAmB,GAC3B,aAAa,GACb,cAAc,GACd,MAAM,GACN,QAAQ,GACR,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,OAAO,CAAC;AAEZ,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;AAEtE,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,EAAE,EAAE,CAAC,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,sBAAsB,KAAK,IAAI,CAAC;IACzE,8BAA8B;IAC9B,KAAK,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,IAAI,CAAC;IACjD,6CAA6C;IAC7C,GAAG,EAAE,CAAC,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,sBAAsB,KAAK,IAAI,CAAC;IAC1E,kCAAkC;IAClC,MAAM,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,IAAI,CAAC;IAClD,0DAA0D;IAC1D,IAAI,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;IACvC,6BAA6B;IAC7B,aAAa,EAAE,CAAC,IAAI,CAAC,EAAE,mBAAmB,KAAK,MAAM,CAAC;IACtD,2BAA2B;IAC3B,kBAAkB,EAAE,MAAM,IAAI,CAAC;CAChC;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,IAAI,iBAAiB,CAsD3D"}

package/dist/events.js

@@ -0,0 +1,81 @@
+/**
+ * Governance Event Emitter
+ *
+ * Subscribe to governance events in real-time — enforcement decisions,
+ * agent registrations, kill switch activations, score changes.
+ * Essential for dashboards, monitoring, and alerting.
+ *
+ * Zero-dependency implementation using native EventTarget.
+ */
+// ─── Implementation ─────────────────────────────────────────────
+/**
+ * Create a governance event emitter.
+ *
+ * Lightweight, synchronous, zero-dependency event system.
+ * Use with governance hooks to stream events to dashboards,
+ * logging systems, or alerting pipelines.
+ *
+ * @example
+ * ```ts
+ * const emitter = createGovernanceEmitter();
+ *
+ * emitter.on('enforcement', (event) => {
+ *   if (event.detail.blocked) {
+ *     alert(`Agent ${event.agentId} blocked!`);
+ *   }
+ * });
+ *
+ * emitter.onAny((event) => {
+ *   metrics.increment(`governance.${event.type}`);
+ * });
+ * ```
+ */
+export function createGovernanceEmitter() {
+    const listeners = new Map();
+    const anyListeners = new Set();
+    function on(type, handler) {
+        const set = listeners.get(type);
+        if (set) {
+            set.add(handler);
+        }
+        else {
+            listeners.set(type, new Set([handler]));
+        }
+    }
+    function onAny(handler) {
+        anyListeners.add(handler);
+    }
+    function off(type, handler) {
+        listeners.get(type)?.delete(handler);
+    }
+    function offAny(handler) {
+        anyListeners.delete(handler);
+    }
+    function emit(event) {
+        const typeListeners = listeners.get(event.type);
+        if (typeListeners) {
+            for (const handler of typeListeners) {
+                handler(event);
+            }
+        }
+        for (const handler of anyListeners) {
+            handler(event);
+        }
+    }
+    function listenerCount(type) {
+        if (type) {
+            return (listeners.get(type)?.size ?? 0) + anyListeners.size;
+        }
+        let total = anyListeners.size;
+        for (const set of listeners.values()) {
+            total += set.size;
+        }
+        return total;
+    }
+    function removeAllListeners() {
+        listeners.clear();
+        anyListeners.clear();
+    }
+    return { on, onAny, off, offAny, emit, listenerCount, removeAllListeners };
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAwCH,mEAAmE;AAEnE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAoD,CAAC;IAC9E,MAAM,YAAY,GAAG,IAAI,GAAG,EAA0B,CAAC;IAEvD,SAAS,EAAE,CAAC,IAAyB,EAAE,OAA+B;QACpE,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,GAAG,EAAE,CAAC;YACR,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAED,SAAS,KAAK,CAAC,OAA+B;QAC5C,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IAED,SAAS,GAAG,CAAC,IAAyB,EAAE,OAA+B;QACrE,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IAED,SAAS,MAAM,CAAC,OAA+B;QAC7C,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAED,SAAS,IAAI,CAAC,KAAsB;QAClC,MAAM,aAAa,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,aAAa,EAAE,CAAC;YAClB,KAAK,MAAM,OAAO,IAAI,aAAa,EAAE,CAAC;gBACpC,OAAO,CAAC,KAAK,CAAC,CAAC;YACjB,CAAC;QACH,CAAC;QACD,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;YACnC,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAED,SAAS,aAAa,CAAC,IAA0B;QAC/C,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC;QAC9D,CAAC;QACD,IAAI,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC;QAC9B,KAAK,MAAM,GAAG,IAAI,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;YACrC,KAAK,IAAI,GAAG,CAAC,IAAI,CAAC;QACpB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,SAAS,kBAAkB;QACzB,SAAS,CAAC,KAAK,EAAE,CAAC;QAClB,YAAY,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,kBAAkB,EAAE,CAAC;AAC7E,CAAC"}

package/dist/federation-types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * governance-sdk — Multi-Agent Federation Types
+ *
+ * Types for cross-boundary governance between agents governed
+ * by different governance instances.
+ */
+import type { PolicyRule } from "./policy.js";
+/** Governance posture exchanged between federated agents */
+export interface GovernancePosture {
+    agentId: string;
+    agentName: string;
+    publicKeyHex?: string;
+    compositeScore: number;
+    level: number;
+    capabilities: string[];
+    complianceFrameworks: string[];
+    policyCount: number;
+    auditIntegrity: boolean;
+    issuedAt: string;
+    expiresAt?: string;
+    signature?: string;
+}
+/** Result of evaluating a remote agent's posture */
+export interface PostureEvaluation {
+    accepted: boolean;
+    reason: string;
+    remoteScore: number;
+    localMinimumScore: number;
+    capabilityOverlap: string[];
+}
+/** Result of negotiating shared policies between two governance instances */
+export interface PolicyNegotiationResult {
+    agreed: boolean;
+    sharedRules: PolicyRule[];
+    localOnlyRules: PolicyRule[];
+    remoteOnlyRules: PolicyRule[];
+    conflicts: string[];
+}
+/** Linked audit event connecting two governance instances */
+export interface FederatedAuditLink {
+    localEventId: string;
+    remoteEventId: string;
+    remoteAgentId: string;
+    linkType: "send" | "receive" | "delegate" | "negotiate";
+    linkedAt: string;
+}
+/** Configuration for federation */
+export interface FederationConfig {
+    /** Minimum composite score to accept a remote agent (default: 40) */
+    minimumRemoteScore?: number;
+    /** Required compliance frameworks (remote must have at least one) */
+    requiredCompliance?: string[];
+    /** Maximum negotiated rule count (default: 50) */
+    maxNegotiatedRules?: number;
+    /** Whether to require signed postures (default: false) */
+    requireSignedPosture?: boolean;
+}
+//# sourceMappingURL=federation-types.d.ts.map

package/dist/federation-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation-types.d.ts","sourceRoot":"","sources":["../src/federation-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,oDAAoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,6EAA6E;AAC7E,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,cAAc,EAAE,UAAU,EAAE,CAAC;IAC7B,eAAe,EAAE,UAAU,EAAE,CAAC;IAC9B,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,6DAA6D;AAC7D,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IACxD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,mCAAmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,kDAAkD;IAClD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC"}

package/dist/federation-types.js

@@ -0,0 +1,8 @@
+/**
+ * governance-sdk — Multi-Agent Federation Types
+ *
+ * Types for cross-boundary governance between agents governed
+ * by different governance instances.
+ */
+export {};
+//# sourceMappingURL=federation-types.js.map

package/dist/federation-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation-types.js","sourceRoot":"","sources":["../src/federation-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/federation.d.ts

@@ -0,0 +1,42 @@
+/**
+ * governance-sdk — Multi-Agent Federation Protocol
+ *
+ * Cross-boundary governance for multi-agent systems.
+ * Enables agents governed by different instances to exchange postures,
+ * negotiate shared policies, and link audit trails.
+ *
+ * @example
+ * ```ts
+ * import { createFederation } from 'governance-sdk/federation';
+ *
+ * const federation = createFederation(localGovernance, { minimumRemoteScore: 50 });
+ *
+ * // Exchange postures before inter-agent communication
+ * const localPosture = await federation.createPosture('agent-1');
+ * const evaluation = federation.evaluatePosture(remotePosture);
+ * if (!evaluation.accepted) throw new Error(evaluation.reason);
+ *
+ * // Negotiate shared policies
+ * const negotiation = federation.negotiatePolicies(remoteRules);
+ *
+ * // Link audit events across boundaries
+ * federation.linkAudit('local-event-123', 'remote-event-456', 'remote-agent-id');
+ * ```
+ */
+import type { GovernanceInstance } from "./index.js";
+import type { GovernancePosture, PostureEvaluation, PolicyNegotiationResult, FederatedAuditLink, FederationConfig } from "./federation-types.js";
+import type { PolicyRule } from "./policy.js";
+export type { GovernancePosture, PostureEvaluation, PolicyNegotiationResult, FederatedAuditLink, FederationConfig, } from "./federation-types.js";
+export declare function createFederation(governance: GovernanceInstance, config?: FederationConfig): {
+    /** Create a governance posture for a local agent to share with remote agents */
+    createPosture(agentId: string): Promise<GovernancePosture>;
+    /** Evaluate a remote agent's posture against local requirements */
+    evaluatePosture(remote: GovernancePosture): PostureEvaluation;
+    /** Negotiate shared policies between local and remote governance */
+    negotiatePolicies(remoteRules: PolicyRule[]): PolicyNegotiationResult;
+    /** Link a local audit event to a remote audit event */
+    linkAudit(localEventId: string, remoteEventId: string, remoteAgentId: string, linkType?: FederatedAuditLink["linkType"]): FederatedAuditLink;
+    /** Get all federated audit links */
+    getAuditLinks(remoteAgentId?: string): FederatedAuditLink[];
+};
+//# sourceMappingURL=federation.d.ts.map

package/dist/federation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation.d.ts","sourceRoot":"","sources":["../src/federation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAI/B,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,kBAAkB,EAAE,MAAM,GAAE,gBAAqB;IAW1F,gFAAgF;2BACnD,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAmBhE,mEAAmE;4BAC3C,iBAAiB,GAAG,iBAAiB;IAqC7D,oEAAoE;mCACrC,UAAU,EAAE,GAAG,uBAAuB;IAuCrE,uDAAuD;4BAC/B,MAAM,iBAAiB,MAAM,iBAAiB,MAAM,aAAY,kBAAkB,CAAC,UAAU,CAAC,GAAY,kBAAkB;IAYpJ,oCAAoC;kCACN,MAAM,GAAG,kBAAkB,EAAE;EAK9D"}