@gitgov/core 1.0.0

package/dist/src/event_bus/types.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Event Bus types for GitGovernance event-driven architecture
+ */
+/**
+ * Event metadata for ordering and debugging
+ */
+export type EventMetadata = {
+    /** Unique event identifier */
+    eventId: string;
+    /** Event creation timestamp */
+    timestamp: number;
+    /** Event processing timestamp (set by handlers) */
+    processedAt?: number;
+    /** Source adapter that emitted the event */
+    sourceAdapter: string;
+    /** Sequence number for ordering (optional) */
+    sequenceNumber?: number;
+};
+/**
+ * Base event structure
+ */
+export type BaseEvent = {
+    /** Event type identifier */
+    type: string;
+    /** Event timestamp */
+    timestamp: number;
+    /** Event payload */
+    payload: unknown;
+    /** Source that emitted the event */
+    source: string;
+    /** Event metadata for ordering and debugging */
+    metadata?: EventMetadata;
+};
+/**
+ * Task-related events
+ * Uses Utility Types derived automatically from official TaskRecord
+ */
+import type { TaskRecord } from '../types/generated/task_record';
+export type TaskCreatedEvent = BaseEvent & {
+    type: 'task.created';
+    payload: {
+        taskId: string;
+        triggeredBy: string;
+    };
+};
+export type TaskStatusChangedEvent = BaseEvent & {
+    type: 'task.status.changed';
+    payload: {
+        taskId: string;
+        oldStatus: TaskRecord['status'];
+        newStatus: TaskRecord['status'];
+        triggeredBy: string;
+        reason?: string;
+    };
+};
+/**
+ * Cycle-related events
+ * Uses Utility Types derived automatically from official CycleRecord
+ */
+import type { CycleRecord } from '../types/generated/cycle_record';
+export type CycleCreatedEvent = BaseEvent & {
+    type: 'cycle.created';
+    payload: {
+        cycleId: string;
+        triggeredBy: string;
+    };
+};
+export type CycleStatusChangedEvent = BaseEvent & {
+    type: 'cycle.status.changed';
+    payload: {
+        cycleId: string;
+        oldStatus: CycleRecord['status'];
+        newStatus: CycleRecord['status'];
+        triggeredBy: string;
+    };
+};
+/**
+ * Execution-related events
+ * Uses Utility Types derived automatically from official ExecutionRecord
+ */
+import type { ExecutionRecord } from '../types/generated/execution_record';
+export type ExecutionCreatedEvent = BaseEvent & {
+    type: 'execution.created';
+    payload: Pick<ExecutionRecord, 'taskId' | 'type' | 'title'> & {
+        executionId: string;
+        triggeredBy: string;
+        isFirstExecution: boolean;
+    };
+};
+/**
+ * Feedback-related events
+ * Uses Utility Types derived automatically from official FeedbackRecord
+ */
+import type { FeedbackRecord } from '../types/generated/feedback_record';
+export type FeedbackCreatedEvent = BaseEvent & {
+    type: 'feedback.created';
+    payload: Pick<FeedbackRecord, 'entityType' | 'entityId' | 'type' | 'status' | 'content' | 'assignee'> & {
+        feedbackId: string;
+        triggeredBy: string;
+    };
+};
+export type FeedbackStatusChangedEvent = BaseEvent & {
+    type: 'feedback.status.changed';
+    payload: Pick<FeedbackRecord, 'assignee'> & {
+        feedbackId: string;
+        oldStatus: FeedbackRecord['status'];
+        newStatus: FeedbackRecord['status'];
+        triggeredBy: string;
+    };
+};
+/**
+ * Changelog-related events
+ * Uses Utility Types derived automatically from official ChangelogRecord
+ */
+import type { ChangelogRecord } from '../types/generated/changelog_record';
+export type ChangelogCreatedEvent = BaseEvent & {
+    type: 'changelog.created';
+    payload: Pick<ChangelogRecord, 'entityType' | 'entityId' | 'changeType' | 'riskLevel' | 'title' | 'trigger'> & {
+        changelogId: string;
+        triggeredBy: string;
+    };
+};
+/**
+ * Identity-related events
+ * Uses Utility Types derived automatically from official ActorRecord and AgentRecord
+ */
+import type { ActorRecord } from '../types/generated/actor_record';
+import type { AgentRecord } from '../types/generated/agent_record';
+export type ActorCreatedEvent = BaseEvent & {
+    type: 'identity.actor.created';
+    payload: Pick<ActorRecord, 'type' | 'publicKey' | 'roles'> & {
+        actorId: string;
+        isBootstrap: boolean;
+    };
+};
+export type ActorRevokedEvent = BaseEvent & {
+    type: 'identity.actor.revoked';
+    payload: Pick<ActorRecord, 'supersededBy'> & {
+        actorId: string;
+        revokedBy: string;
+        revocationReason: 'compromised' | 'rotation' | 'manual';
+    };
+};
+export type AgentRegisteredEvent = BaseEvent & {
+    type: 'identity.agent.registered';
+    payload: Pick<AgentRecord, 'guild' | 'engine'> & {
+        agentId: string;
+        correspondingActorId: string;
+    };
+};
+/**
+ * System events
+ */
+export type SystemDailyTickEvent = BaseEvent & {
+    type: 'system.daily_tick';
+    payload: {
+        date: string;
+    };
+};
+/**
+ * Union type of all possible events
+ */
+export type GitGovEvent = TaskCreatedEvent | TaskStatusChangedEvent | CycleCreatedEvent | CycleStatusChangedEvent | ExecutionCreatedEvent | FeedbackCreatedEvent | FeedbackStatusChangedEvent | ChangelogCreatedEvent | ActorCreatedEvent | ActorRevokedEvent | AgentRegisteredEvent | SystemDailyTickEvent;
+/**
+ * Event handler function type
+ */
+export type EventHandler<T extends BaseEvent = BaseEvent> = (event: T) => void | Promise<void>;
+/**
+ * Event subscription
+ */
+export type EventSubscription = {
+    /** Unique subscription ID */
+    id: string;
+    /** Event type being subscribed to */
+    eventType: string;
+    /** Handler function */
+    handler: EventHandler;
+    /** Subscription metadata */
+    metadata?: {
+        subscriberName?: string;
+        createdAt: number;
+    };
+};
+/**
+ * Activity Event for IndexerAdapter activity tracking
+ */
+export type ActivityEvent = {
+    timestamp: number;
+    type: "task_created" | "cycle_created" | "feedback_created" | "changelog_created" | "execution_created" | "actor_created" | "agent_registered";
+    entityId: string;
+    entityTitle: string;
+    actorId?: string;
+    metadata?: {
+        priority?: string;
+        status?: string;
+        type?: string;
+        assignee?: string;
+        resolution?: string;
+        executionType?: string;
+        taskId?: string;
+    };
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/event_bus/types.d.ts.map

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

package/dist/src/event_bus/types.js

@@ -0,0 +1,5 @@
+/**
+ * Event Bus types for GitGovernance event-driven architecture
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/event_bus/types.js.map

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

package/dist/src/factories/actor_factory.d.ts

@@ -0,0 +1,6 @@
+import type { ActorRecord } from "../types";
+/**
+ * Creates a new, fully-formed ActorRecord with validation.
+ */
+export declare function createActorRecord(payload: Partial<ActorRecord>): Promise<ActorRecord>;
+//# sourceMappingURL=actor_factory.d.ts.map

package/dist/src/factories/actor_factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor_factory.d.ts","sourceRoot":"","sources":["../../../src/factories/actor_factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAK5C;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,GAC5B,OAAO,CAAC,WAAW,CAAC,CAmBtB"}

package/dist/src/factories/actor_factory.js

@@ -0,0 +1,25 @@
+import { validateActorRecordDetailed } from "../validation/actor_validator";
+import { generateActorId } from "../utils/id_generator";
+import { DetailedValidationError } from "../validation/common";
+/**
+ * Creates a new, fully-formed ActorRecord with validation.
+ */
+export async function createActorRecord(payload) {
+    // Build actor with defaults for optional fields
+    const actor = {
+        id: payload.id || generateActorId(payload.type || 'human', payload.displayName || ''),
+        type: payload.type || 'human',
+        displayName: payload.displayName || '',
+        publicKey: payload.publicKey || '',
+        roles: payload.roles || ['author'],
+        status: payload.status || 'active',
+        ...payload,
+    };
+    // Use validator to check complete schema with detailed errors
+    const validation = validateActorRecordDetailed(actor);
+    if (!validation.isValid) {
+        throw new DetailedValidationError('ActorRecord', validation.errors);
+    }
+    return actor;
+}
+//# sourceMappingURL=actor_factory.js.map

package/dist/src/factories/actor_factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor_factory.js","sourceRoot":"","sources":["../../../src/factories/actor_factory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE/D;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAA6B;IAE7B,gDAAgD;IAChD,MAAM,KAAK,GAAgB;QACzB,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,eAAe,CAAC,OAAO,CAAC,IAAI,IAAI,OAAO,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC;QACrF,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,OAAgB;QACtC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE;QACtC,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,EAAE;QAClC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC,QAAQ,CAA0B;QAC3D,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,QAAQ;QAClC,GAAG,OAAO;KACI,CAAC;IAEjB,8DAA8D;IAC9D,MAAM,UAAU,GAAG,2BAA2B,CAAC,KAAK,CAAC,CAAC;IACtD,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,uBAAuB,CAAC,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACtE,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/src/factories/actor_factory.test.d.ts

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

package/dist/src/factories/actor_factory.test.d.ts.map

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

package/dist/src/factories/actor_factory.test.js

@@ -0,0 +1,169 @@
+import { createActorRecord } from './actor_factory';
+import { DetailedValidationError } from '../validation/common';
+// Mock the validator to control test outcomes
+jest.mock('../validation/actor_validator', () => ({
+    validateActorRecordDetailed: jest.fn(() => ({ isValid: true, errors: [] })),
+}));
+describe('createActorRecord', () => {
+    beforeEach(() => {
+        // Reset mock to default success state before each test
+        const { validateActorRecordDetailed } = require('../validation/actor_validator');
+        validateActorRecordDetailed.mockReturnValue({ isValid: true, errors: [] });
+    });
+    it('[EARS-2 & EARS-3] should create a valid actor record with defaults and a generated ID', async () => {
+        const payload = {
+            type: 'human',
+            displayName: 'Test User',
+            publicKey: 'some-key',
+            roles: ['author'],
+        };
+        const actor = await createActorRecord(payload);
+        expect(actor.id).toContain('human:test-user'); // ID is generated
+        expect(actor.status).toBe('active');
+        expect(actor.type).toBe('human');
+        expect(actor.displayName).toBe('Test User');
+    });
+    it('[EARS-1] should throw DetailedValidationError for missing/invalid fields', async () => {
+        const { validateActorRecordDetailed } = require('../validation/actor_validator');
+        validateActorRecordDetailed.mockReturnValue({
+            isValid: false,
+            errors: [
+                { field: 'type', message: 'must be one of: human, agent', value: 'human' },
+                { field: 'displayName', message: 'must be a non-empty string', value: '' }
+            ]
+        });
+        const payload = {
+            displayName: 'Test User',
+            publicKey: 'some-key',
+        };
+        await expect(createActorRecord(payload)).rejects.toThrow(DetailedValidationError);
+    });
+    it('[EARS-4] should use a provided ID instead of generating one', async () => {
+        const payload = {
+            id: 'human:custom-id',
+            type: 'human',
+            displayName: 'Test User',
+            publicKey: 'some-key',
+            roles: ['author'],
+        };
+        const actor = await createActorRecord(payload);
+        expect(actor.id).toBe('human:custom-id');
+    });
+    it('[EARS-5] should throw DetailedValidationError if the created record fails validation', async () => {
+        // Override the mock for this specific test
+        const { validateActorRecordDetailed } = require('../validation/actor_validator');
+        validateActorRecordDetailed.mockReturnValue({
+            isValid: false,
+            errors: [
+                { field: 'publicKey', message: 'invalid key format', value: 'some-key' }
+            ]
+        });
+        const payload = {
+            type: 'human',
+            displayName: 'Test User',
+            publicKey: 'some-key',
+            roles: ['author'],
+        };
+        await expect(createActorRecord(payload)).rejects.toThrow(DetailedValidationError);
+        // Restore the mock
+        validateActorRecordDetailed.mockReturnValue({ isValid: true, errors: [] });
+    });
+    it('[EARS-6] should set default values for optional fields', async () => {
+        const payload = {
+            type: 'human',
+            displayName: 'Minimal User',
+        };
+        const actor = await createActorRecord(payload);
+        expect(actor.status).toBe('active'); // Default status
+        expect(actor.roles).toEqual(['author']); // Default roles
+        expect(actor.publicKey).toBe(''); // Default empty string
+    });
+    it('[EARS-7] should preserve provided optional fields', async () => {
+        const payload = {
+            type: 'agent',
+            displayName: 'Complex Agent',
+            publicKey: 'custom-public-key',
+            roles: ['author', 'reviewer', 'approver'],
+            status: 'revoked'
+        };
+        const actor = await createActorRecord(payload);
+        expect(actor.status).toBe('revoked'); // Custom status preserved
+        expect(actor.roles).toEqual(['author', 'reviewer', 'approver']);
+        expect(actor.publicKey).toBe('custom-public-key');
+    });
+    it('[EARS-8] should generate ID from type and displayName when not provided', async () => {
+        const payload = {
+            type: 'human',
+            displayName: 'Test User for ID Generation',
+            publicKey: 'some-key',
+            roles: ['author'],
+        };
+        const actor = await createActorRecord(payload);
+        expect(actor.id).toBe('human:test-user-for-id-generation');
+        expect(actor.type).toBe('human');
+        expect(actor.displayName).toBe('Test User for ID Generation');
+    });
+    describe('ActorRecord Specific Factory Operations (EARS 9-11)', () => {
+        it('[EARS-9] should apply appropriate defaults for human type', async () => {
+            const payload = {
+                type: 'human',
+                displayName: 'Human User',
+                publicKey: 'test-key',
+                roles: ['developer']
+            };
+            const actor = await createActorRecord(payload);
+            expect(actor.type).toBe('human');
+            expect(actor.status).toBe('active'); // Default for humans
+        });
+        it('[EARS-10] should apply appropriate defaults for agent type', async () => {
+            const payload = {
+                type: 'agent',
+                displayName: 'AI Agent',
+                publicKey: 'agent-key',
+                roles: ['assistant']
+            };
+            const actor = await createActorRecord(payload);
+            expect(actor.type).toBe('agent');
+            expect(actor.status).toBe('active'); // Default for agents
+        });
+        it('[EARS-11] should throw DetailedValidationError when roles is missing', async () => {
+            const { validateActorRecordDetailed } = require('../validation/actor_validator');
+            validateActorRecordDetailed.mockReturnValue({
+                isValid: false,
+                errors: [
+                    { field: 'roles', message: 'must have at least 1 items', value: [] }
+                ]
+            });
+            const payload = {
+                type: 'human',
+                displayName: 'User Without Roles',
+                publicKey: 'test-key'
+                // roles missing - should trigger validation error
+            };
+            await expect(createActorRecord(payload)).rejects.toThrow(DetailedValidationError);
+            // Restore mock
+            validateActorRecordDetailed.mockReturnValue({ isValid: true, errors: [] });
+        });
+        it('[EARS-11] should throw DetailedValidationError when roles is empty array', async () => {
+            const { validateActorRecordDetailed } = require('../validation/actor_validator');
+            validateActorRecordDetailed.mockReturnValue({
+                isValid: false,
+                errors: [
+                    { field: 'roles', message: 'must have at least 1 items', value: [] }
+                ]
+            });
+            // Create payload with empty roles array - using object literal to bypass TypeScript checking
+            const invalidRoles = [];
+            const payload = {
+                type: 'human',
+                displayName: 'User With Empty Roles',
+                publicKey: 'test-key',
+                roles: invalidRoles // Type assertion to match expected type
+            };
+            await expect(createActorRecord(payload)).rejects.toThrow(DetailedValidationError);
+            // Restore mock
+            validateActorRecordDetailed.mockReturnValue({ isValid: true, errors: [] });
+        });
+    });
+});
+//# sourceMappingURL=actor_factory.test.js.map

package/dist/src/factories/actor_factory.test.js.map

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

package/dist/src/factories/agent_factory.d.ts

@@ -0,0 +1,6 @@
+import type { AgentRecord } from "../types";
+/**
+ * Creates a new, fully-formed AgentRecord with validation.
+ */
+export declare function createAgentRecord(payload: Partial<AgentRecord>): Promise<AgentRecord>;
+//# sourceMappingURL=agent_factory.d.ts.map

package/dist/src/factories/agent_factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent_factory.d.ts","sourceRoot":"","sources":["../../../src/factories/agent_factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAI5C;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,GAC5B,OAAO,CAAC,WAAW,CAAC,CAoBtB"}

package/dist/src/factories/agent_factory.js

@@ -0,0 +1,25 @@
+import { validateAgentRecordDetailed } from "../validation/agent_validator";
+import { DetailedValidationError } from "../validation/common";
+/**
+ * Creates a new, fully-formed AgentRecord with validation.
+ */
+export async function createAgentRecord(payload) {
+    // Build agent with defaults for optional fields
+    const agent = {
+        id: payload.id || '',
+        guild: payload.guild || 'design',
+        engine: payload.engine || { type: 'local' },
+        status: payload.status || 'active',
+        triggers: payload.triggers || [],
+        knowledge_dependencies: payload.knowledge_dependencies || [],
+        prompt_engine_requirements: payload.prompt_engine_requirements || {},
+        ...payload,
+    };
+    // Use validator to check complete schema with detailed errors
+    const validation = validateAgentRecordDetailed(agent);
+    if (!validation.isValid) {
+        throw new DetailedValidationError('AgentRecord', validation.errors);
+    }
+    return agent;
+}
+//# sourceMappingURL=agent_factory.js.map

package/dist/src/factories/agent_factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent_factory.js","sourceRoot":"","sources":["../../../src/factories/agent_factory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAC5E,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE/D;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAA6B;IAE7B,gDAAgD;IAChD,MAAM,KAAK,GAAgB;QACzB,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE;QACpB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,QAAiB;QACzC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE,IAAI,EAAE,OAAgB,EAAE;QACpD,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,QAAQ;QAClC,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE;QAChC,sBAAsB,EAAE,OAAO,CAAC,sBAAsB,IAAI,EAAE;QAC5D,0BAA0B,EAAE,OAAO,CAAC,0BAA0B,IAAI,EAAE;QACpE,GAAG,OAAO;KACI,CAAC;IAEjB,8DAA8D;IAC9D,MAAM,UAAU,GAAG,2BAA2B,CAAC,KAAK,CAAC,CAAC;IACtD,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,uBAAuB,CAAC,aAAa,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACtE,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/src/factories/agent_factory.test.d.ts

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

package/dist/src/factories/agent_factory.test.d.ts.map

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