@plumbus/core 0.1.0

package/dist/execution/capability-registry.js

@@ -0,0 +1,49 @@
+/**
+ * Registry that holds all discovered/registered capabilities,
+ * indexed by name for lookup during execution and route generation.
+ */
+export class CapabilityRegistry {
+    capabilities = new Map();
+    /**
+     * Register a capability contract. Throws on duplicate names.
+     */
+    register(capability) {
+        if (this.capabilities.has(capability.name)) {
+            throw new Error(`Capability "${capability.name}" is already registered`);
+        }
+        this.capabilities.set(capability.name, capability);
+    }
+    /**
+     * Register multiple capabilities at once.
+     */
+    registerAll(capabilities) {
+        for (const cap of capabilities) {
+            this.register(cap);
+        }
+    }
+    /**
+     * Get a capability by name.
+     */
+    get(name) {
+        return this.capabilities.get(name);
+    }
+    /**
+     * Return all registered capabilities.
+     */
+    getAll() {
+        return Array.from(this.capabilities.values());
+    }
+    /**
+     * Return all capabilities for a specific domain.
+     */
+    getByDomain(domain) {
+        return this.getAll().filter((c) => c.domain === domain);
+    }
+    /**
+     * Check if a capability is registered.
+     */
+    has(name) {
+        return this.capabilities.has(name);
+    }
+}
+//# sourceMappingURL=capability-registry.js.map

package/dist/execution/capability-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-registry.js","sourceRoot":"","sources":["../../src/execution/capability-registry.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IACrB,YAAY,GAAG,IAAI,GAAG,EAA8B,CAAC;IAE7D;;OAEG;IACH,QAAQ,CAAC,UAA8B;QACrC,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CAAC,eAAe,UAAU,CAAC,IAAI,yBAAyB,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACrD,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,YAAkC;QAC5C,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAC/B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,MAAM;QACJ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC;IAChD,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,MAAc;QACxB,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;IAC1D,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;CACF"}

package/dist/execution/context-factory.d.ts

@@ -0,0 +1,20 @@
+import type { AuditService } from '../types/audit.js';
+import type { AIService, ConfigService, DataService, EventService, ExecutionContext, FlowService, LoggerService, TimeService } from '../types/context.js';
+import type { AuthContext } from '../types/security.js';
+export interface ContextDependencies {
+    auth: AuthContext;
+    data: DataService;
+    events?: EventService;
+    flows?: FlowService;
+    ai?: AIService;
+    audit?: AuditService;
+    logger?: LoggerService;
+    time?: TimeService;
+    config?: ConfigService;
+}
+/**
+ * Build an ExecutionContext from the provided dependencies.
+ * Missing optional services are replaced with safe defaults/stubs.
+ */
+export declare function createExecutionContext(deps: ContextDependencies): ExecutionContext;
+//# sourceMappingURL=context-factory.d.ts.map

package/dist/execution/context-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-factory.d.ts","sourceRoot":"","sources":["../../src/execution/context-factory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EACV,SAAS,EACT,aAAa,EACb,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,aAAa,EAEb,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAsFD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,GAAG,gBAAgB,CAclF"}

package/dist/execution/context-factory.js

@@ -0,0 +1,98 @@
+import { createErrorService } from '../errors/index.js';
+const noopAudit = {
+    async record() { },
+};
+const noopEvents = {
+    async emit() { },
+};
+const noopFlows = {
+    async start() {
+        return { id: '', flowName: '', status: 'not_started' };
+    },
+    async resume() { },
+    async cancel() { },
+    async status() {
+        return { id: '', flowName: '', status: 'unknown' };
+    },
+};
+const noopAI = {
+    async generate() {
+        throw new Error('AI service not configured');
+    },
+    async extract() {
+        throw new Error('AI service not configured');
+    },
+    async classify() {
+        throw new Error('AI service not configured');
+    },
+    async retrieve() {
+        throw new Error('AI service not configured');
+    },
+};
+const consoleLogger = {
+    debug(message, metadata) {
+        console.debug(message, metadata ?? '');
+    },
+    info(message, metadata) {
+        console.info(message, metadata ?? '');
+    },
+    warn(message, metadata) {
+        console.warn(message, metadata ?? '');
+    },
+    error(message, metadata) {
+        console.error(message, metadata ?? '');
+    },
+};
+const realTime = {
+    now() {
+        return new Date();
+    },
+};
+function createSecurityService(auth) {
+    return {
+        hasRole(role) {
+            return auth.roles.includes(role);
+        },
+        hasScope(scope) {
+            return auth.scopes.includes(scope);
+        },
+        hasAllRoles(roles) {
+            return roles.every((r) => auth.roles.includes(r));
+        },
+        hasAllScopes(scopes) {
+            return scopes.every((s) => auth.scopes.includes(s));
+        },
+        requireRole(role) {
+            if (!auth.roles.includes(role)) {
+                throw Object.assign(new Error(`Forbidden: requires role "${role}"`), { code: 'forbidden' });
+            }
+        },
+        requireScope(scope) {
+            if (!auth.scopes.includes(scope)) {
+                throw Object.assign(new Error(`Forbidden: requires scope "${scope}"`), {
+                    code: 'forbidden',
+                });
+            }
+        },
+    };
+}
+/**
+ * Build an ExecutionContext from the provided dependencies.
+ * Missing optional services are replaced with safe defaults/stubs.
+ */
+export function createExecutionContext(deps) {
+    return {
+        auth: deps.auth,
+        data: deps.data,
+        events: deps.events ?? noopEvents,
+        flows: deps.flows ?? noopFlows,
+        ai: deps.ai ?? noopAI,
+        audit: deps.audit ?? noopAudit,
+        errors: createErrorService(),
+        logger: deps.logger ?? consoleLogger,
+        time: deps.time ?? realTime,
+        config: deps.config ?? {},
+        security: createSecurityService(deps.auth),
+    };
+}
+//# sourceMappingURL=context-factory.js.map

package/dist/execution/context-factory.js.map

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

package/dist/execution/index.d.ts

@@ -0,0 +1,8 @@
+export { createExecutionContext } from './context-factory.js';
+export type { ContextDependencies } from './context-factory.js';
+export { executeCapability } from './capability-executor.js';
+export type { CapabilityResult, ExecutionFailure, ExecutionResult, } from './capability-executor.js';
+export { evaluateAccess } from './authorization.js';
+export type { AuthorizationResult } from './authorization.js';
+export { CapabilityRegistry } from './capability-registry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/execution/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/execution/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/execution/index.js

@@ -0,0 +1,10 @@
+// ── Execution Module ──
+// Capability execution pipeline: context factory, authorization (deny-by-default),
+// capability executor (validate → authorize → execute → audit), and capability registry.
+//
+// Key exports: executeCapability, createExecutionContext, evaluateAccess, CapabilityRegistry
+export { createExecutionContext } from './context-factory.js';
+export { executeCapability } from './capability-executor.js';
+export { evaluateAccess } from './authorization.js';
+export { CapabilityRegistry } from './capability-registry.js';
+//# sourceMappingURL=index.js.map

package/dist/execution/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/execution/index.ts"],"names":[],"mappings":"AAAA,yBAAyB;AACzB,mFAAmF;AACnF,yFAAyF;AACzF,EAAE;AACF,6FAA6F;AAE7F,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAG9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAO7D,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/explanation/__tests__/tracker.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tracker.test.d.ts.map

package/dist/explanation/__tests__/tracker.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.test.d.ts","sourceRoot":"","sources":["../../../src/explanation/__tests__/tracker.test.ts"],"names":[],"mappings":""}

package/dist/explanation/__tests__/tracker.test.js

@@ -0,0 +1,169 @@
+import { describe, expect, it } from 'vitest';
+import { createExplanationTracker } from '../tracker.js';
+describe('ExplanationTracker', () => {
+    describe('recordAuthorization', () => {
+        it('records allow decisions', () => {
+            const tracker = createExplanationTracker();
+            const record = tracker.recordAuthorization({
+                capability: 'getUser',
+                actor: 'user-1',
+                tenantId: 't-1',
+                decision: 'allow',
+                matchedRoles: ['admin'],
+                matchedScopes: ['read:users'],
+            });
+            expect(record.id).toBeDefined();
+            expect(record.type).toBe('authorization');
+            expect(record.component).toBe('capability:getUser');
+            expect(record.decision).toBe('allow');
+            expect(record.reasoning).toContain('admin');
+        });
+        it('records deny decisions with reason', () => {
+            const tracker = createExplanationTracker();
+            const record = tracker.recordAuthorization({
+                capability: 'deleteUser',
+                actor: 'user-2',
+                decision: 'deny',
+                deniedReason: 'insufficient roles',
+            });
+            expect(record.decision).toBe('deny');
+            expect(record.reasoning).toContain('insufficient roles');
+        });
+    });
+    describe('recordFlowBranch', () => {
+        it('records branch decisions', () => {
+            const tracker = createExplanationTracker();
+            const record = tracker.recordFlowBranch({
+                flowName: 'refund-approval',
+                executionId: 'exec-1',
+                stepName: 'check-amount',
+                condition: 'amount > 1000',
+                evaluatedTo: true,
+                branchTaken: 'manual-review',
+                stateSnapshot: { amount: 1500 },
+            });
+            expect(record.type).toBe('flow-branch');
+            expect(record.component).toBe('flow:refund-approval');
+            expect(record.decision).toBe('branch:manual-review');
+            expect(record.reasoning).toContain('amount > 1000');
+            expect(record.reasoning).toContain('true');
+        });
+    });
+    describe('recordAIInvocation', () => {
+        it('records AI invocations', () => {
+            const tracker = createExplanationTracker();
+            const record = tracker.recordAIInvocation({
+                promptName: 'classify-ticket',
+                operation: 'classify',
+                model: 'gpt-4',
+                retrievalSources: [{ source: 'doc1.md', score: 0.95 }],
+                validationResult: { passed: true, attempts: 1 },
+                tokenUsage: { input: 500, output: 50 },
+            });
+            expect(record.type).toBe('ai-invocation');
+            expect(record.component).toBe('prompt:classify-ticket');
+            expect(record.reasoning).toContain('gpt-4');
+            expect(record.reasoning).toContain('1 retrieval sources');
+            expect(record.outcome).toBe('validated');
+        });
+        it('records unvalidated AI invocations', () => {
+            const tracker = createExplanationTracker();
+            const record = tracker.recordAIInvocation({
+                operation: 'generate',
+                validationResult: { passed: false, attempts: 3 },
+            });
+            expect(record.component).toBe('ai:generate');
+            expect(record.outcome).toBe('unvalidated');
+        });
+    });
+    describe('recordGovernance', () => {
+        it('records active governance signals', () => {
+            const tracker = createExplanationTracker();
+            const record = tracker.recordGovernance({
+                rule: 'privacy.sensitive-field-unencrypted',
+                severity: 'high',
+                affectedComponent: 'entity:User.ssn',
+                overridden: false,
+            });
+            expect(record.type).toBe('governance');
+            expect(record.outcome).toBe('active');
+            expect(record.reasoning).toContain('high');
+        });
+        it('records overridden governance signals', () => {
+            const tracker = createExplanationTracker();
+            const record = tracker.recordGovernance({
+                rule: 'security.no-tenant-isolation',
+                severity: 'info',
+                affectedComponent: 'entity:Config',
+                overridden: true,
+                overrideJustification: 'Global config entity — not tenant-specific',
+            });
+            expect(record.outcome).toBe('overridden');
+            expect(record.reasoning).toContain('Global config entity');
+        });
+    });
+    describe('querying', () => {
+        it('returns all records', () => {
+            const tracker = createExplanationTracker();
+            tracker.recordAuthorization({ capability: 'a', actor: 'u1', decision: 'allow' });
+            tracker.recordFlowBranch({
+                flowName: 'f',
+                executionId: 'e',
+                stepName: 's',
+                condition: 'x',
+                evaluatedTo: true,
+                branchTaken: 'y',
+            });
+            expect(tracker.getRecords()).toHaveLength(2);
+        });
+        it('filters by type', () => {
+            const tracker = createExplanationTracker();
+            tracker.recordAuthorization({ capability: 'a', actor: 'u1', decision: 'allow' });
+            tracker.recordFlowBranch({
+                flowName: 'f',
+                executionId: 'e',
+                stepName: 's',
+                condition: 'x',
+                evaluatedTo: true,
+                branchTaken: 'y',
+            });
+            expect(tracker.getByType('authorization')).toHaveLength(1);
+            expect(tracker.getByType('flow-branch')).toHaveLength(1);
+        });
+        it('filters by component', () => {
+            const tracker = createExplanationTracker();
+            tracker.recordAuthorization({ capability: 'getUser', actor: 'u1', decision: 'allow' });
+            tracker.recordAuthorization({ capability: 'deleteUser', actor: 'u1', decision: 'deny' });
+            expect(tracker.getByComponent('capability:getUser')).toHaveLength(1);
+        });
+        it('filters by time range', () => {
+            const tracker = createExplanationTracker();
+            tracker.recordAuthorization({ capability: 'a', actor: 'u1', decision: 'allow' });
+            const future = new Date(Date.now() + 86_400_000);
+            expect(tracker.getRecords({ since: future })).toHaveLength(0);
+        });
+        it('filters by actor when configured', () => {
+            const tracker = createExplanationTracker({ actor: 'test-user' });
+            tracker.recordAuthorization({ capability: 'a', actor: 'u1', decision: 'allow' });
+            expect(tracker.getRecords({ actor: 'test-user' })).toHaveLength(1);
+            expect(tracker.getRecords({ actor: 'other' })).toHaveLength(0);
+        });
+    });
+    describe('audit integration', () => {
+        it('records to audit service when configured', async () => {
+            const auditLog = [];
+            const tracker = createExplanationTracker({
+                audit: {
+                    record: async (eventType, metadata) => {
+                        auditLog.push({ eventType, metadata });
+                    },
+                },
+            });
+            tracker.recordAuthorization({ capability: 'test', actor: 'u1', decision: 'allow' });
+            // Audit is called synchronously (fire-and-forget)
+            expect(auditLog).toHaveLength(1);
+            expect(auditLog[0]?.eventType).toBe('explanation.authorization');
+        });
+    });
+});
+//# sourceMappingURL=tracker.test.js.map

package/dist/explanation/__tests__/tracker.test.js.map

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

package/dist/explanation/index.d.ts

@@ -0,0 +1,3 @@
+export { createExplanationTracker } from './tracker.js';
+export type { AIInvocationExplanation, AuthorizationExplanation, ExplanationFilter, ExplanationRecord, ExplanationTracker, ExplanationTrackerConfig, ExplanationType, FlowBranchExplanation, GovernanceExplanation, } from './tracker.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/explanation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/explanation/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EACV,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,cAAc,CAAC"}

package/dist/explanation/index.js

@@ -0,0 +1,7 @@
+// ── Explanation Module ──
+// Explainability tracking: records why the system made each decision
+// (authorization, AI invocations, flow branching, governance signals).
+//
+// Key exports: createExplanationTracker
+export { createExplanationTracker } from './tracker.js';
+//# sourceMappingURL=index.js.map

package/dist/explanation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/explanation/index.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,qEAAqE;AACrE,uEAAuE;AACvE,EAAE;AACF,wCAAwC;AAExC,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC"}

package/dist/explanation/tracker.d.ts

@@ -0,0 +1,81 @@
+import type { AuditService } from '../types/audit.js';
+export type ExplanationType = 'authorization' | 'flow-branch' | 'ai-invocation' | 'governance';
+export interface ExplanationRecord {
+    id: string;
+    timestamp: Date;
+    type: ExplanationType;
+    component: string;
+    decision: string;
+    reasoning: string;
+    inputs: Record<string, unknown>;
+    outcome: string;
+    actor?: string;
+    tenantId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AuthorizationExplanation {
+    capability: string;
+    actor: string;
+    tenantId?: string;
+    decision: 'allow' | 'deny';
+    matchedRoles?: string[];
+    matchedScopes?: string[];
+    deniedReason?: string;
+}
+export interface FlowBranchExplanation {
+    flowName: string;
+    executionId: string;
+    stepName: string;
+    condition: string;
+    evaluatedTo: boolean;
+    branchTaken: string;
+    stateSnapshot?: Record<string, unknown>;
+}
+export interface AIInvocationExplanation {
+    promptName?: string;
+    operation: string;
+    model?: string;
+    retrievalSources?: Array<{
+        source: string;
+        score: number;
+    }>;
+    validationResult?: {
+        passed: boolean;
+        attempts: number;
+    };
+    tokenUsage?: {
+        input: number;
+        output: number;
+    };
+}
+export interface GovernanceExplanation {
+    rule: string;
+    severity: string;
+    affectedComponent: string;
+    overridden: boolean;
+    overrideJustification?: string;
+}
+export interface ExplanationTracker {
+    recordAuthorization(explanation: AuthorizationExplanation): ExplanationRecord;
+    recordFlowBranch(explanation: FlowBranchExplanation): ExplanationRecord;
+    recordAIInvocation(explanation: AIInvocationExplanation): ExplanationRecord;
+    recordGovernance(explanation: GovernanceExplanation): ExplanationRecord;
+    getRecords(filter?: ExplanationFilter): ExplanationRecord[];
+    getByComponent(component: string): ExplanationRecord[];
+    getByType(type: ExplanationType): ExplanationRecord[];
+}
+export interface ExplanationFilter {
+    type?: ExplanationType;
+    component?: string;
+    actor?: string;
+    tenantId?: string;
+    since?: Date;
+    until?: Date;
+}
+export interface ExplanationTrackerConfig {
+    audit?: AuditService;
+    actor?: string;
+    tenantId?: string;
+}
+export declare function createExplanationTracker(config?: ExplanationTrackerConfig): ExplanationTracker;
+//# sourceMappingURL=tracker.d.ts.map

package/dist/explanation/tracker.d.ts.map

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

package/dist/explanation/tracker.js

@@ -0,0 +1,100 @@
+// ── Explanation System ──
+// Attach explanation metadata to: flow branching decisions, authorization decisions,
+// AI invocations, governance warnings. Store alongside audit records. Queryable.
+export function createExplanationTracker(config) {
+    const records = [];
+    function addRecord(type, component, decision, reasoning, inputs, outcome, metadata) {
+        const record = {
+            id: crypto.randomUUID(),
+            timestamp: new Date(),
+            type,
+            component,
+            decision,
+            reasoning,
+            inputs,
+            outcome,
+            actor: config?.actor,
+            tenantId: config?.tenantId,
+            metadata,
+        };
+        records.push(record);
+        if (config?.audit) {
+            config.audit.record(`explanation.${type}`, {
+                explanationId: record.id,
+                component,
+                decision,
+                outcome,
+            });
+        }
+        return record;
+    }
+    function matchesFilter(record, filter) {
+        if (filter.type && record.type !== filter.type)
+            return false;
+        if (filter.component && record.component !== filter.component)
+            return false;
+        if (filter.actor && record.actor !== filter.actor)
+            return false;
+        if (filter.tenantId && record.tenantId !== filter.tenantId)
+            return false;
+        if (filter.since && record.timestamp < filter.since)
+            return false;
+        if (filter.until && record.timestamp > filter.until)
+            return false;
+        return true;
+    }
+    return {
+        recordAuthorization(explanation) {
+            return addRecord('authorization', `capability:${explanation.capability}`, explanation.decision, explanation.decision === 'allow'
+                ? `Matched roles: [${explanation.matchedRoles?.join(', ') ?? 'none'}], scopes: [${explanation.matchedScopes?.join(', ') ?? 'none'}]`
+                : `Denied: ${explanation.deniedReason ?? 'no matching roles or scopes'}`, {
+                actor: explanation.actor,
+                tenantId: explanation.tenantId,
+                capability: explanation.capability,
+            }, explanation.decision, {
+                matchedRoles: explanation.matchedRoles,
+                matchedScopes: explanation.matchedScopes,
+            });
+        },
+        recordFlowBranch(explanation) {
+            return addRecord('flow-branch', `flow:${explanation.flowName}`, `branch:${explanation.branchTaken}`, `Condition "${explanation.condition}" evaluated to ${explanation.evaluatedTo} — took branch "${explanation.branchTaken}"`, {
+                flowName: explanation.flowName,
+                executionId: explanation.executionId,
+                stepName: explanation.stepName,
+                condition: explanation.condition,
+            }, explanation.branchTaken, { stateSnapshot: explanation.stateSnapshot });
+        },
+        recordAIInvocation(explanation) {
+            return addRecord('ai-invocation', explanation.promptName ? `prompt:${explanation.promptName}` : `ai:${explanation.operation}`, explanation.operation, `AI ${explanation.operation}${explanation.model ? ` using ${explanation.model}` : ''}${explanation.retrievalSources?.length ? ` with ${explanation.retrievalSources.length} retrieval sources` : ''}`, {
+                promptName: explanation.promptName,
+                operation: explanation.operation,
+                model: explanation.model,
+            }, explanation.validationResult?.passed ? 'validated' : 'unvalidated', {
+                retrievalSources: explanation.retrievalSources,
+                tokenUsage: explanation.tokenUsage,
+                validationResult: explanation.validationResult,
+            });
+        },
+        recordGovernance(explanation) {
+            return addRecord('governance', explanation.affectedComponent, explanation.overridden ? 'overridden' : explanation.severity, explanation.overridden
+                ? `Rule "${explanation.rule}" overridden: ${explanation.overrideJustification}`
+                : `Rule "${explanation.rule}" produced ${explanation.severity} signal`, {
+                rule: explanation.rule,
+                severity: explanation.severity,
+                affectedComponent: explanation.affectedComponent,
+            }, explanation.overridden ? 'overridden' : 'active', { overrideJustification: explanation.overrideJustification });
+        },
+        getRecords(filter) {
+            if (!filter)
+                return [...records];
+            return records.filter((r) => matchesFilter(r, filter));
+        },
+        getByComponent(component) {
+            return records.filter((r) => r.component === component);
+        },
+        getByType(type) {
+            return records.filter((r) => r.type === type);
+        },
+    };
+}
+//# sourceMappingURL=tracker.js.map

package/dist/explanation/tracker.js.map

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

package/dist/fields/__tests__/fields.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fields.test.d.ts.map

package/dist/fields/__tests__/fields.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.test.d.ts","sourceRoot":"","sources":["../../../src/fields/__tests__/fields.test.ts"],"names":[],"mappings":""}