import { DelegatingMutationGovernanceSink, DelegatingMutationPolicyApprovalProvider, DelegatingMutationPolicyRegistry, MISSING_MUTATION_POLICY, MISSING_MUTATION_POLICY_APPROVAL, MutationDecision, MutationGovernanceWarning, MutationPlan, MutationPolicy, MutationPolicyError, MutationPolicyIdentity, MutationIntent, UserContext, } from '../src'; import { AbstractSQLTeaQLClient, SqlSession, TeaQLSqlDriver, } from '../src/sql/core'; const schemas = { Order: { table: 'order_data', columns: { id: { columnName: 'id', logicalType: 'integer' as const, decode: 'string' as const }, version: { columnName: 'version', logicalType: 'integer' as const, decode: 'number' as const }, name: { columnName: 'name', logicalType: 'text' as const, decode: 'string' as const }, } }, OrderLine: { table: 'order_line_data', columns: { id: { columnName: 'id', logicalType: 'integer' as const, decode: 'string' as const }, version: { columnName: 'version', logicalType: 'integer' as const, decode: 'number' as const }, name: { columnName: 'name', logicalType: 'text' as const, decode: 'string' as const }, } }, }; class RecordingDriver implements TeaQLSqlDriver, SqlSession { readonly databaseKind = 'sqlite' as const; providerMutations = 0; persistedMutations = 0; transactions = 0; commits = 0; rollbacks = 0; private next = 0; private pendingMutations = 0; async query(sql: string): Promise { if (/^\s*(?:INSERT|UPDATE|DELETE)/i.test(sql)) { this.providerMutations++; this.pendingMutations++; } if (/^\s*SELECT/i.test(sql)) { return { rows: [{ id: String(this.next), version: 1, name: 'persisted' }], rowCount: 1 }; } return { rows: [], rowCount: 1 }; } async *stream(): AsyncIterable {} identifier(value: string): string { return `"${value}"`; } placeholder(): string { return '?'; } encode(value: any): any { return value; } contains(): string { return ''; } aggregateFunction(name: string): string { return name; } async ensureSchema(): Promise {} async transaction(work: (session: SqlSession) => Promise): Promise { this.transactions++; this.pendingMutations = 0; try { const result = await work(this); this.persistedMutations += this.pendingMutations; this.pendingMutations = 0; this.commits++; return result; } catch (error) { this.pendingMutations = 0; this.rollbacks++; throw error; } } async nextId(): Promise { this.next++; return String(this.next); } async ensureIdFloor(): Promise {} async close(): Promise {} } class Client extends AbstractSQLTeaQLClient { constructor(driver: RecordingDriver) { super(driver, schemas); } } class TestPolicy implements MutationPolicy { constructor( readonly identity: MutationPolicyIdentity, private readonly reviewer: (plan: MutationPlan) => MutationDecision, ) {} review(_context: unknown, plan: MutationPlan): MutationDecision { return this.reviewer(plan); } } const identity = Object.freeze({ policyId: 'orders', version: '1', fingerprint: 'sha256:orders-v1', }); function approvedContext(policy: MutationPolicy): UserContext { return new UserContext() .withMutationPolicyRegistry(new DelegatingMutationPolicyRegistry(() => policy)) .withMutationPolicyApprovalProvider(new DelegatingMutationPolicyApprovalProvider( requested => ({ policy: requested, approvedBy: 'security-owner', approvedAt: new Date() }), )); } test('whole graph is reviewed immutably and its governance reaches every audit event', async () => { const observed: Record = {}; const policy = new TestPolicy(identity, plan => { observed.operationCount = plan.operations.length; observed.firstName = plan.operations[0].changedValues.name; observed.frozen = Object.isFrozen(plan) && Object.isFrozen(plan.operations) && Object.isFrozen(plan.operations[0].changedValues); return { verdict: 'allow' }; }); const context = approvedContext(policy); const driver = new RecordingDriver(); const client = new Client(driver).setUserContext(context); const order = { entity: 'Order', action: 'Create', payload: { name: 'DRAFT' }, comment: 'submit order' }; const line = { entity: 'OrderLine', action: 'Create', payload: { name: 'LINE-1' }, comment: 'submit line' }; await client.executeGraphSave(new MutationIntent('submit order'), async graph => { client.preflightMutation(graph.request(order)); client.preflightMutation(graph.request(line)); order.payload.name = 'CHANGED-AFTER-PREFLIGHT'; await client.executeMutation(graph.request({ ...order, payload: { name: 'DRAFT' } })); await client.executeMutation(graph.request(line)); }); expect(observed).toEqual({ operationCount: 2, firstName: 'DRAFT', frozen: true }); expect(driver.providerMutations).toBe(2); expect(driver.persistedMutations).toBe(2); expect(driver.commits).toBe(1); expect(client.auditTrace).toHaveLength(2); expect(client.auditTrace.map(event => (event.mutationGovernance as any).approvalStatus)).toEqual(['approved', 'approved']); expect((client.auditTrace[0].mutationGovernance as any).executionId) .toBe((client.auditTrace[1].mutationGovernance as any).executionId); }); test('customer denial happens before SQL and incomplete reviewed graphs roll back', async () => { const deniedDriver = new RecordingDriver(); const denied = new Client(deniedDriver).setUserContext(approvedContext( new TestPolicy(identity, () => ({ verdict: 'deny', code: 'ORDER_DENIED', message: 'orders are disabled', })), )); await expect(denied.executeGraphSave(new MutationIntent('deny'), async graph => { const mutation = { entity: 'Order', action: 'Create', payload: { name: 'D' }, comment: 'deny' }; denied.preflightMutation(graph.request(mutation)); await denied.executeMutation(graph.request(mutation)); })).rejects.toThrow(/ORDER_DENIED/); expect(deniedDriver.providerMutations).toBe(0); expect(deniedDriver.persistedMutations).toBe(0); expect(deniedDriver.rollbacks).toBe(1); const incompleteDriver = new RecordingDriver(); const incomplete = new Client(incompleteDriver).setUserContext(approvedContext( new TestPolicy(identity, () => ({ verdict: 'allow' })), )); const first = { entity: 'Order', action: 'Create', payload: { name: 'A' }, comment: 'first' }; const second = { entity: 'OrderLine', action: 'Create', payload: { name: 'B' }, comment: 'second' }; await expect(incomplete.executeGraphSave(new MutationIntent('incomplete graph'), async graph => { incomplete.preflightMutation(graph.request(first)); incomplete.preflightMutation(graph.request(second)); await incomplete.executeMutation(graph.request(first)); })).rejects.toThrow(/were not executed/); expect(incompleteDriver.providerMutations).toBe(1); expect(incompleteDriver.persistedMutations).toBe(0); expect(incompleteDriver.commits).toBe(0); expect(incompleteDriver.rollbacks).toBe(1); }); test('missing policy and approval warnings are stable, deduplicated, and fail open', () => { const warnings: MutationGovernanceWarning[] = []; const context = new UserContext().withMutationGovernanceSink( new DelegatingMutationGovernanceSink((_context, warning) => { warnings.push(warning); if (warnings.length === 1) throw new Error('warning sink unavailable'); }), ); const plan: MutationPlan = { executionId: 'warning-1', requestKey: 'Order.saveGraph', rootEntityType: 'Order', auditReason: 'verify missing-policy warnings', operations: [{ kind: 'update', entity: 'Order', entityId: '1', originalVersion: 1, changedValues: { name: 'updated' } }], }; const generated = context.reviewMutationPlan(plan); context.reviewMutationPlan({ ...plan, executionId: 'warning-2' }); expect(generated.warningCodes).toEqual([MISSING_MUTATION_POLICY]); expect(warnings.map(warning => warning.firstOccurrence)).toEqual([true, false]); const customerWarnings: MutationGovernanceWarning[] = []; const customer = new UserContext() .withMutationPolicyRegistry(new DelegatingMutationPolicyRegistry(() => new TestPolicy(identity, () => ({ verdict: 'allow' })))) .withMutationGovernanceSink(new DelegatingMutationGovernanceSink( (_context, warning) => customerWarnings.push(warning), )); const unapproved = customer.reviewMutationPlan(plan); expect(unapproved.warningCodes).toEqual([MISSING_MUTATION_POLICY_APPROVAL]); expect(unapproved.approvalStatus).toBe('missing'); customer.withMutationPolicyApprovalProvider(new DelegatingMutationPolicyApprovalProvider( () => ({ policy: { ...identity, fingerprint: 'sha256:different' }, approvedBy: 'security-owner', approvedAt: new Date(), }), )); expect(customer.reviewMutationPlan({ ...plan, executionId: 'mismatch' }).approvalStatus) .toBe('missing'); }); test('warning sink failure does not change generated-default persistence', async () => { const driver = new RecordingDriver(); const context = new UserContext().withMutationGovernanceSink( new DelegatingMutationGovernanceSink(() => { throw new Error('sink unavailable'); }), ); const client = new Client(driver).setUserContext(context); await expect(client.executeMutation({ entity: 'Order', action: 'Create', payload: { name: 'allowed' }, comment: 'default', })).resolves.toBeDefined(); expect(driver.persistedMutations).toBe(1); expect((client.auditTrace[0].mutationGovernance as any).warningCodes) .toEqual([MISSING_MUTATION_POLICY]); }); test('customer policy requires complete generated preflight for graph saves', async () => { const driver = new RecordingDriver(); const client = new Client(driver).setUserContext(approvedContext( new TestPolicy(identity, () => ({ verdict: 'allow' })), )); await expect(client.executeGraphSave(new MutationIntent('unplanned'), graph => client.executeMutation(graph.request({ entity: 'Order', action: 'Create', payload: { name: 'unplanned' }, comment: 'unplanned', })))).rejects.toThrow(MutationPolicyError); expect(driver.providerMutations).toBe(0); }); test('cyclic policy values fail explicitly instead of overflowing the stack', () => { const payload: Record = { name: 'cycle' }; payload.self = payload; const context = new UserContext(); expect(() => context.reviewMutationPlan({ executionId: 'cyclic-plan', requestKey: 'Order.saveGraph', rootEntityType: 'Order', auditReason: 'reject cyclic policy values', operations: [{ kind: 'update', entity: 'Order', entityId: '1', originalVersion: 1, changedValues: payload }], })).toThrow(/must not contain cycles/); }); test('failed graph lifecycle initialization releases the save queue', async () => { const context = new UserContext(); const driver = new RecordingDriver(); const client = new Client(driver).setUserContext(context); context.beginMutationPolicyGraph(); await expect(client.executeGraphSave(new MutationIntent('lifecycle'), async () => undefined)) .rejects.toThrow(/already active/); context.endMutationPolicyGraph(); await expect(client.executeGraphSave(new MutationIntent('lifecycle'), async () => undefined)).resolves.toBeUndefined(); expect(driver.transactions).toBe(1); expect(driver.commits).toBe(1); }); test('stable ledger identity tolerates parent ids assigned during graph execution', async () => { const driver = new RecordingDriver(); const client = new Client(driver).setUserContext(approvedContext( new TestPolicy(identity, plan => { expect(plan.operations[1].changedValues.name).toBeUndefined(); return { verdict: 'allow' }; }), )); const parent = { entity: 'Order', action: 'Create', payload: { name: 'parent' }, comment: 'create graph', ledgerKey: { entity: 'Order', id: -1 } }; const childBefore = { entity: 'OrderLine', action: 'Create', payload: { name: { id: undefined, label: 'parent' } }, comment: 'create graph', ledgerKey: { entity: 'OrderLine', id: -2 } }; const childAfter = { ...childBefore, payload: { name: { id: '1', label: 'parent' } } }; await client.executeGraphSave(new MutationIntent('create graph'), async graph => { client.preflightMutation(graph.request(parent)); client.preflightMutation(graph.request(childBefore)); await client.executeMutation(graph.request(parent)); await client.executeMutation(graph.request(childAfter)); }); expect(driver.persistedMutations).toBe(2); expect(driver.commits).toBe(1); });