@gitgov/core 2.2.0 → 2.3.0

package/dist/src/record_projection.types-B8AM7u8U.d.ts

@@ -0,0 +1,1207 @@
+import { R as RecordStore } from './record_store-BXKWqon5.js';
+
+/**
+ * This file was automatically generated from actor_record_schema.json.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source schema,
+ * and run 'pnpm compile:types' to regenerate this file.
+ */
+/**
+ * Canonical schema for actor records as defined in actor_protocol.md
+ */
+interface ActorRecord {
+    /**
+     * Unique, human-readable identifier for the actor.
+     */
+    id: string;
+    /**
+     * The type of actor.
+     */
+    type: 'human' | 'agent';
+    /**
+     * The name of the actor to be used in user interfaces.
+     */
+    displayName: string;
+    /**
+     * The Ed25519 public key (base64 encoded, 44 characters) for verifying the actor's signatures.
+     */
+    publicKey: string;
+    /**
+     * List of capacity roles defining the actor's skills and permissions. Uses hierarchical format with colons.
+     *
+     * @minItems 1
+     */
+    roles: [string, ...string[]];
+    /**
+     * Optional. The lifecycle status of the actor. Defaults to 'active' if not specified.
+     */
+    status?: 'active' | 'revoked';
+    /**
+     * Optional. The ID of the actor that replaces this one.
+     */
+    supersededBy?: string;
+    /**
+     * An optional field for additional, non-canonical metadata.
+     */
+    metadata?: {};
+}
+
+/**
+ * This file was automatically generated from agent_record_schema.json.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source schema,
+ * and run 'pnpm compile:types' to regenerate this file.
+ */
+/**
+ * Canonical schema for agent operational manifests.
+ */
+interface AgentRecord<TMetadata = object> {
+    /**
+     * Unique identifier for the agent, linking to an ActorRecord.
+     */
+    id: string;
+    status?: 'active' | 'archived';
+    /**
+     * Optional list of triggers that activate the agent.
+     * Additional fields are allowed and depend on trigger type:
+     * - webhook triggers: 'event' (event identifier), 'filter' (condition)
+     * - scheduled triggers: 'cron' (cron expression)
+     * - manual triggers: 'command' (example CLI command)
+     *
+     */
+    triggers?: {
+        /**
+         * Type of trigger that activates the agent
+         */
+        type: 'manual' | 'webhook' | 'scheduled';
+        [k: string]: unknown | undefined;
+    }[];
+    knowledge_dependencies?: string[];
+    prompt_engine_requirements?: {
+        roles?: string[];
+        skills?: string[];
+    };
+    /**
+     * Optional framework-specific or deployment-specific metadata for agent extensions.
+     * Common use cases: framework identification (langchain, google-adk), deployment info (provider, image, region),
+     * cost tracking (cost_per_invocation, currency), tool capabilities, maintainer info.
+     * This field does NOT affect agent execution - it is purely informational.
+     *
+     */
+    metadata?: TMetadata;
+    engine: {
+        type: 'local';
+        /**
+         * Runtime environment (typescript, python, etc.)
+         */
+        runtime?: string;
+        /**
+         * Path to the agent entry file
+         */
+        entrypoint?: string;
+        /**
+         * Function name to invoke
+         */
+        function?: string;
+    } | {
+        type: 'api';
+        /**
+         * HTTP endpoint for the agent
+         */
+        url: string;
+        method?: 'POST' | 'GET' | 'PUT';
+        /**
+         * Authentication configuration for API requests
+         */
+        auth?: {
+            /**
+             * Authentication type. 'actor-signature' uses the agent's ActorRecord keypair to sign requests.
+             */
+            type?: 'bearer' | 'oauth' | 'api-key' | 'actor-signature';
+            /**
+             * Reference to secret in Secret Manager (for bearer/api-key/oauth auth types)
+             */
+            secret_key?: string;
+            /**
+             * Direct token value (not recommended for production, use secret_key instead)
+             */
+            token?: string;
+            [k: string]: unknown | undefined;
+        };
+    } | {
+        type: 'mcp';
+        /**
+         * MCP server endpoint
+         */
+        url: string;
+        /**
+         * Name of the MCP tool to invoke. If not specified, defaults to agentId without 'agent:' prefix.
+         */
+        tool?: string;
+        /**
+         * Authentication configuration for MCP server
+         */
+        auth?: {
+            /**
+             * Authentication type. 'actor-signature' uses the agent's ActorRecord keypair to sign requests.
+             */
+            type?: 'bearer' | 'oauth' | 'api-key' | 'actor-signature';
+            /**
+             * Reference to secret in Secret Manager (for bearer/api-key/oauth auth types)
+             */
+            secret_key?: string;
+            /**
+             * Direct token value (not recommended for production, use secret_key instead)
+             */
+            token?: string;
+            [k: string]: unknown | undefined;
+        };
+    } | {
+        type: 'custom';
+        /**
+         * Custom protocol identifier (e.g., 'a2a', 'grpc')
+         */
+        protocol?: string;
+        /**
+         * Protocol-specific configuration
+         */
+        config?: {};
+    };
+}
+
+/**
+ * This file was automatically generated from changelog_record_schema.json.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source schema,
+ * and run 'pnpm compile:types' to regenerate this file.
+ */
+/**
+ * Canonical schema for changelog records - aggregates N tasks into 1 release note
+ */
+interface ChangelogRecord {
+    /**
+     * Unique identifier for the changelog entry
+     */
+    id: string;
+    /**
+     * Executive title of the deliverable
+     */
+    title: string;
+    /**
+     * Detailed description of the value delivered, including key decisions and impact
+     */
+    description: string;
+    /**
+     * IDs of tasks that compose this deliverable (minimum 1 required)
+     *
+     * @minItems 1
+     */
+    relatedTasks: [string, ...string[]];
+    /**
+     * Unix timestamp in seconds when the deliverable was completed
+     */
+    completedAt: number;
+    /**
+     * Optional IDs of cycles related to this deliverable
+     */
+    relatedCycles?: string[];
+    /**
+     * Optional IDs of key execution records related to this work
+     */
+    relatedExecutions?: string[];
+    /**
+     * Optional version or release identifier (e.g., 'v1.0.0', 'sprint-24')
+     */
+    version?: string;
+    /**
+     * Optional tags for categorization (e.g., 'feature:auth', 'bugfix', 'security')
+     */
+    tags?: string[];
+    /**
+     * Optional list of git commit hashes related to this deliverable
+     */
+    commits?: string[];
+    /**
+     * Optional list of main files that were created or modified
+     */
+    files?: string[];
+    /**
+     * Optional additional context, decisions, or learnings
+     */
+    notes?: string;
+}
+
+/**
+ * This file was automatically generated from cycle_record_schema.json.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source schema,
+ * and run 'pnpm compile:types' to regenerate this file.
+ */
+/**
+ * Canonical schema for cycle records - strategic grouping of work
+ */
+interface CycleRecord {
+    /**
+     * Unique identifier for the cycle (10 timestamp + 1 dash + 5 'cycle' + 1 dash + max 50 slug = 67 max)
+     */
+    id: string;
+    /**
+     * Human-readable title for the cycle (e.g., 'Sprint 24', 'Auth v2.0', 'Q4 2025')
+     */
+    title: string;
+    /**
+     * The lifecycle status of the cycle
+     */
+    status: 'planning' | 'active' | 'completed' | 'archived';
+    /**
+     * Optional array of Task IDs that belong to this cycle. Can be empty for cycles that only contain child cycles. (10 timestamp + 1 dash + 4 'task' + 1 dash + max 50 slug = 66 max)
+     */
+    taskIds?: string[];
+    /**
+     * Optional array of Cycle IDs that are children of this cycle, allowing for hierarchies (e.g., Q1 containing Sprint 1, Sprint 2, Sprint 3). (10 timestamp + 1 dash + 5 'cycle' + 1 dash + max 50 slug = 67 max)
+     */
+    childCycleIds?: string[];
+    /**
+     * Optional list of key:value tags for categorization (e.g., 'roadmap:q4', 'team:alpha', 'okr:growth').
+     */
+    tags?: string[];
+    /**
+     * Optional description of the cycle's goals, objectives, and context
+     */
+    notes?: string;
+}
+
+/**
+ * This file was automatically generated from execution_record_schema.json.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source schema,
+ * and run 'pnpm compile:types' to regenerate this file.
+ */
+/**
+ * Canonical schema for execution log records - the universal event stream
+ */
+interface ExecutionRecord<TMetadata = object> {
+    /**
+     * Unique identifier for the execution log entry (10 timestamp + 1 dash + 4 'exec' + 1 dash + max 50 slug = 66 max)
+     */
+    id: string;
+    /**
+     * ID of the parent task this execution belongs to (10 timestamp + 1 dash + 4 'task' + 1 dash + max 50 slug = 66 max)
+     */
+    taskId: string;
+    /**
+     * Semantic classification of the execution event
+     */
+    type: 'analysis' | 'progress' | 'blocker' | 'completion' | 'info' | 'correction';
+    /**
+     * Human-readable title for the execution (used to generate ID)
+     */
+    title: string;
+    /**
+     * The tangible, verifiable output or result of the execution.
+     * This is the "WHAT" - evidence of work or event summary.
+     *
+     */
+    result: string;
+    /**
+     * Optional narrative, context and decisions behind the execution.
+     * This is the "HOW" and "WHY" - the story behind the result.
+     *
+     */
+    notes?: string;
+    /**
+     * Optional list of typed references to relevant commits, files, PRs, or external documents.
+     * Should use typed prefixes for clarity and trazabilidad (see execution_protocol_appendix.md):
+     * - commit:     Git commit SHA
+     * - pr:         Pull Request number
+     * - file:       File path (relative to repo root)
+     * - url:        External URL
+     * - issue:      GitHub Issue number
+     * - task:       TaskRecord ID
+     * - exec:       ExecutionRecord ID (for corrections or dependencies)
+     * - changelog:  ChangelogRecord ID
+     *
+     */
+    references?: string[];
+    /**
+     * Optional structured data for machine consumption.
+     * Use this field for data that needs to be programmatically processed (e.g., audit findings,
+     * performance metrics, scan results). This complements result (human-readable WHAT) and
+     * notes (narrative HOW/WHY) by providing structured, queryable data.
+     * Common use cases: audit findings arrays, performance metrics, tool outputs, scan summaries.
+     *
+     */
+    metadata?: TMetadata;
+}
+
+/**
+ * This file was automatically generated from feedback_record_schema.json.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source schema,
+ * and run 'pnpm compile:types' to regenerate this file.
+ */
+/**
+ * Canonical schema for feedback records - structured conversation about work
+ */
+interface FeedbackRecord<TMetadata = object> {
+    /**
+     * Unique identifier for the feedback entry
+     */
+    id: string;
+    /**
+     * The type of entity this feedback refers to
+     */
+    entityType: 'task' | 'execution' | 'changelog' | 'feedback' | 'cycle';
+    /**
+     * The ID of the entity this feedback refers to.
+     * Must match the pattern for its entityType:
+     * - task: ^\d{10}-task-[a-z0-9-]{1,50}$
+     * - execution: ^\d{10}-exec-[a-z0-9-]{1,50}$
+     * - changelog: ^\d{10}-changelog-[a-z0-9-]{1,50}$
+     * - feedback: ^\d{10}-feedback-[a-z0-9-]{1,50}$
+     * - cycle: ^\d{10}-cycle-[a-z0-9-]{1,50}$
+     *
+     */
+    entityId: string;
+    /**
+     * The semantic intent of the feedback
+     */
+    type: 'blocking' | 'suggestion' | 'question' | 'approval' | 'clarification' | 'assignment';
+    /**
+     * The lifecycle status of the feedback.
+     * Note: FeedbackRecords are immutable. To change status, create a new feedback
+     * that references this one using entityType: "feedback" and resolvesFeedbackId.
+     *
+     */
+    status: 'open' | 'acknowledged' | 'resolved' | 'wontfix';
+    /**
+     * The content of the feedback. Reduced from 10000 to 5000 chars for practical use.
+     */
+    content: string;
+    /**
+     * Optional. The Actor ID responsible for addressing the feedback (e.g., 'human:maria', 'agent:camilo:cursor')
+     */
+    assignee?: string;
+    /**
+     * Optional. The ID of another feedback record that this one resolves or responds to
+     */
+    resolvesFeedbackId?: string;
+    /**
+     * Optional structured data for machine consumption.
+     * Use this field for domain-specific data that needs to be programmatically processed.
+     * Common use cases: waiver details (fingerprint, ruleId, file, line), approval context, assignment metadata.
+     *
+     */
+    metadata?: TMetadata;
+}
+
+/**
+ * This file was automatically generated from task_record_schema.json.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source schema,
+ * and run 'pnpm compile:types' to regenerate this file.
+ */
+/**
+ * Canonical schema for task records as defined in task_protocol.md
+ */
+interface TaskRecord {
+    /**
+     * Unique identifier for the task (10 timestamp + 1 dash + 4 'task' + 1 dash + max 50 slug = 66 max)
+     */
+    id: string;
+    /**
+     * A brief, human-readable title for the task. Used to generate the ID slug.
+     */
+    title: string;
+    /**
+     * Optional. The IDs of the strategic cycles this task belongs to. (10 timestamp + 1 dash + 5 'cycle' + 1 dash + max 50 slug = 67 max)
+     */
+    cycleIds?: string[];
+    /**
+     * Current state of the task in the institutional flow
+     */
+    status: 'draft' | 'review' | 'ready' | 'active' | 'done' | 'archived' | 'paused' | 'discarded';
+    /**
+     * Strategic or tactical priority level
+     */
+    priority: 'low' | 'medium' | 'high' | 'critical';
+    /**
+     * Functional, technical or strategic summary of the objective
+     */
+    description: string;
+    /**
+     * Optional. List of key:value tags for categorization and role suggestion (e.g., 'skill:react', 'role:agent:developer').
+     */
+    tags?: string[];
+    /**
+     * Valid links or files, when mentioned
+     */
+    references?: string[];
+    /**
+     * Additional comments, decisions made or added context
+     */
+    notes?: string;
+}
+
+/**
+ * This file was automatically generated from embedded_metadata_schema.json.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source schema,
+ * and run 'pnpm compile:types' to regenerate this file.
+ */
+/**
+ * Canonical schema for the wrapper structure of all GitGovernance records.
+ */
+type EmbeddedMetadataRecord$1 = {
+    header: {
+        /**
+         * Version of the embedded metadata format.
+         */
+        version: '1.0';
+        /**
+         * The type of the record contained in the payload.
+         */
+        type: 'actor' | 'agent' | 'task' | 'execution' | 'changelog' | 'feedback' | 'cycle' | 'custom';
+        /**
+         * Optional URL to a custom schema for the payload.
+         */
+        schemaUrl?: string;
+        /**
+         * Optional SHA-256 checksum of the custom schema.
+         */
+        schemaChecksum?: string;
+        /**
+         * SHA-256 checksum of the canonically serialized payload.
+         */
+        payloadChecksum: string;
+        /**
+         * An array of one or more signature objects.
+         *
+         * @minItems 1
+         */
+        signatures: [
+            {
+                /**
+                 * The Actor ID of the signer (must match ActorRecord.id pattern).
+                 */
+                keyId: string;
+                /**
+                 * The context role of the signature (e.g., 'author', 'reviewer', 'auditor', or 'custom:*').
+                 */
+                role: string;
+                /**
+                 * Human-readable note from the signer. Part of the signature digest.
+                 */
+                notes: string;
+                /**
+                 * The Ed25519 signature (base64 encoded, 88 chars with padding) of the signature digest.
+                 */
+                signature: string;
+                /**
+                 * Unix timestamp of the signature.
+                 */
+                timestamp: number;
+            },
+            ...{
+                /**
+                 * The Actor ID of the signer (must match ActorRecord.id pattern).
+                 */
+                keyId: string;
+                /**
+                 * The context role of the signature (e.g., 'author', 'reviewer', 'auditor', or 'custom:*').
+                 */
+                role: string;
+                /**
+                 * Human-readable note from the signer. Part of the signature digest.
+                 */
+                notes: string;
+                /**
+                 * The Ed25519 signature (base64 encoded, 88 chars with padding) of the signature digest.
+                 */
+                signature: string;
+                /**
+                 * Unix timestamp of the signature.
+                 */
+                timestamp: number;
+            }[]
+        ];
+    };
+    /**
+     * The specific record data, validated against the schema defined by header.type.
+     */
+    payload: {};
+} & {
+    [k: string]: unknown | undefined;
+};
+
+/**
+ * Extract Signature type from the auto-generated base type.
+ * This is hardcoded solution but avoids duplication and uses the generated type as source of truth.
+ */
+type Signature = EmbeddedMetadataRecord$1['header']['signatures'][0];
+/**
+ * Extract Header type from the auto-generated base type.
+ * This is the complete header structure for EmbeddedMetadata.
+ */
+type EmbeddedMetadataHeader = EmbeddedMetadataRecord$1['header'];
+/**
+ * Generic version of EmbeddedMetadataRecord that accepts any payload type T.
+ * This extends the auto-generated base type but makes the payload generic.
+ * We need to explicitly preserve the header structure due to the index signature in the base type.
+ */
+type EmbeddedMetadataRecord<T extends GitGovRecordPayload> = {
+    header: EmbeddedMetadataHeader;
+    payload: T;
+};
+
+/**
+ * A custom record type for testing purposes.
+ */
+type CustomRecord = {
+    type: 'custom';
+    data: unknown;
+};
+/**
+ * Defines the possible 'type' values for any record in the system.
+ */
+type GitGovRecordType = "actor" | "agent" | "cycle" | "task" | "execution" | "changelog" | "feedback" | "custom";
+/**
+ * The canonical payload for any GitGovernance record.
+ */
+type GitGovRecordPayload = ActorRecord | AgentRecord | CycleRecord | TaskRecord | ExecutionRecord | ChangelogRecord | FeedbackRecord | CustomRecord;
+/**
+ * The canonical type for any record in GitGovernance, wrapping a payload with metadata.
+ */
+type GitGovRecord = EmbeddedMetadataRecord<GitGovRecordPayload>;
+/**
+ * Specific GitGov record types with full metadata (header + payload).
+ * These types provide clean, type-safe access to records with their signatures and checksums.
+ *
+ * @example
+ * const taskRecord: GitGovTaskRecord = await taskStore.read(taskId);
+ * const authorId = taskRecord.header.signatures[0].keyId;
+ */
+type GitGovTaskRecord = EmbeddedMetadataRecord<TaskRecord>;
+type GitGovCycleRecord = EmbeddedMetadataRecord<CycleRecord>;
+type GitGovFeedbackRecord = EmbeddedMetadataRecord<FeedbackRecord>;
+type GitGovExecutionRecord = EmbeddedMetadataRecord<ExecutionRecord>;
+type GitGovChangelogRecord = EmbeddedMetadataRecord<ChangelogRecord>;
+type GitGovActorRecord = EmbeddedMetadataRecord<ActorRecord>;
+type GitGovAgentRecord = EmbeddedMetadataRecord<AgentRecord>;
+type ActorPayload = Partial<ActorRecord>;
+type AgentPayload = Partial<AgentRecord>;
+type CyclePayload = Partial<CycleRecord>;
+type TaskPayload = Partial<TaskRecord>;
+type ExecutionPayload = Partial<ExecutionRecord>;
+type ChangelogPayload = Partial<ChangelogRecord>;
+type FeedbackPayload = Partial<FeedbackRecord>;
+/**
+ * Base class for all GitGovernance-specific errors.
+ * Centralized here as it's used across multiple modules (schemas, validation, etc.)
+ */
+declare class GitGovError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+
+/**
+ * RecordStores - Typed container for all stores
+ *
+ * Allows injecting multiple stores to modules that need them.
+ * Keys correspond to directory names in .gitgov/
+ *
+ * All stores are OPTIONAL.
+ * Reason: LintModule.lint(stores) can receive only relevant stores.
+ * Example: To validate only tasks, pass { tasks: taskStore }.
+ * The module iterates over Object.entries(stores) and skips undefined.
+ */
+type RecordStores = {
+    actors?: RecordStore<GitGovActorRecord>;
+    agents?: RecordStore<GitGovAgentRecord>;
+    tasks?: RecordStore<GitGovTaskRecord>;
+    cycles?: RecordStore<GitGovCycleRecord>;
+    executions?: RecordStore<GitGovExecutionRecord>;
+    feedbacks?: RecordStore<GitGovFeedbackRecord>;
+    changelogs?: RecordStore<GitGovChangelogRecord>;
+};
+
+/**
+ * RecordMetrics Dependencies - Facade + Dependency Injection Pattern
+ */
+type RecordMetricsDependencies = {
+    stores: Required<Pick<RecordStores, 'tasks' | 'cycles' | 'feedbacks' | 'executions' | 'actors'>>;
+};
+type SystemStatus = {
+    tasks: {
+        total: number;
+        byStatus: Record<string, number>;
+        byPriority: Record<string, number>;
+    };
+    cycles: {
+        total: number;
+        active: number;
+        completed: number;
+    };
+    health: {
+        overallScore: number;
+        blockedTasks: number;
+        staleTasks: number;
+    };
+};
+type TaskHealthReport = {
+    taskId: string;
+    healthScore: number;
+    timeInCurrentStage: number;
+    stalenessIndex: number;
+    blockingFeedbacks: number;
+    lastActivity: number;
+    recommendations: string[];
+};
+type ProductivityMetrics = {
+    throughput: number;
+    leadTime: number;
+    cycleTime: number;
+    tasksCompleted7d: number;
+    averageCompletionTime: number;
+};
+type CollaborationMetrics = {
+    activeAgents: number;
+    totalAgents: number;
+    agentUtilization: number;
+    humanAgentRatio: number;
+    collaborationIndex: number;
+};
+/**
+ * RecordMetrics Interface - The System Analyst
+ */
+interface IRecordMetrics {
+    getSystemStatus(): Promise<SystemStatus>;
+    getTaskHealth(taskId: string): Promise<TaskHealthReport>;
+    getProductivityMetrics(): Promise<ProductivityMetrics>;
+    getCollaborationMetrics(): Promise<CollaborationMetrics>;
+    calculateTimeInCurrentStage(task: TaskRecord): number;
+    calculateStalenessIndex(tasks: TaskRecord[]): number;
+    calculateBlockingFeedbackAge(feedback: FeedbackRecord[]): number;
+    calculateHealth(tasks: TaskRecord[]): number;
+    calculateBacklogDistribution(tasks: TaskRecord[]): Record<string, number>;
+    calculateTasksCreatedToday(tasks: TaskRecord[]): number;
+    calculateThroughput(tasks: TaskRecord[]): number;
+    calculateLeadTime(tasks: TaskRecord[]): number;
+    calculateCycleTime(tasks: TaskRecord[]): number;
+    calculateActiveAgents(actors: ActorRecord[], executions: ExecutionRecord[]): number;
+}
+
+/**
+ * RecordMetrics - The System Analyst
+ *
+ * Implements Facade + Dependency Injection Pattern for testeable and configurable orchestration.
+ * Acts as Mediator between analytics system and multi-store data sources.
+ */
+declare class RecordMetrics implements IRecordMetrics {
+    private stores;
+    constructor(dependencies: RecordMetricsDependencies);
+    /**
+     * [EARS-A1] Gets aggregated system status using Tier 1 metrics.
+     */
+    getSystemStatus(): Promise<SystemStatus>;
+    /**
+     * [EARS-A2] Gets task health analysis using Tier 1 metrics.
+     */
+    getTaskHealth(taskId: string): Promise<TaskHealthReport>;
+    /**
+     * [EARS-E1] Gets productivity metrics using Tier 2 calculations.
+     */
+    getProductivityMetrics(): Promise<ProductivityMetrics>;
+    /**
+     * [EARS-E2] Gets collaboration metrics with agent activity analysis.
+     */
+    getCollaborationMetrics(): Promise<CollaborationMetrics>;
+    /**
+     * [EARS-B1] Calculates exact days since last state change.
+     */
+    calculateTimeInCurrentStage(task: TaskRecord): number;
+    /**
+     * [EARS-B2] Calculates days since last ExecutionRecord.
+     */
+    calculateStalenessIndex(tasks: TaskRecord[]): number;
+    /**
+     * [EARS-B3] Calculates days of oldest active blocking feedback.
+     */
+    calculateBlockingFeedbackAge(feedback: FeedbackRecord[]): number;
+    /**
+     * [EARS-B4] Calculates health percentage using improved protocol formula.
+     */
+    calculateHealth(tasks: TaskRecord[]): number;
+    /**
+     * [EARS-B5] Returns status distribution with percentages.
+     */
+    calculateBacklogDistribution(tasks: TaskRecord[]): Record<string, number>;
+    /**
+     * [EARS-B6] Counts tasks created in last 24 hours.
+     */
+    calculateTasksCreatedToday(tasks: TaskRecord[]): number;
+    /**
+     * [EARS-D1] Counts tasks moved to 'done' in last 7 days.
+     */
+    calculateThroughput(tasks: TaskRecord[]): number;
+    /**
+     * [EARS-D2] Calculates average done-draft time for lead time.
+     */
+    calculateLeadTime(tasks: TaskRecord[]): number;
+    /**
+     * [EARS-D3] Calculates average done-active time for cycle time.
+     */
+    calculateCycleTime(tasks: TaskRecord[]): number;
+    /**
+     * [EARS-D4] Counts unique agents with executions in 24h.
+     */
+    calculateActiveAgents(actors: ActorRecord[], executions: ExecutionRecord[]): number;
+    /**
+     * Extracts timestamp from ID (format: {timestamp}-{type}-{slug})
+     */
+    private getTimestampFromId;
+    /**
+     * Counts tasks by status
+     */
+    private countTasksByStatus;
+    /**
+     * Counts tasks by priority
+     */
+    private countTasksByPriority;
+    /**
+     * [EARS-C3] Throws NotImplementedError for Tier 3 functions.
+     */
+    calculateQuality(_tasks: TaskRecord[]): number;
+    calculateReworkRate(_tasks: TaskRecord[]): number;
+    calculateCompletionRate(_tasks: TaskRecord[]): number;
+    calculateAuditScoreDistribution(_tasks: TaskRecord[]): Record<string, number>;
+    calculateEpicPromotionRate(_tasks: TaskRecord[]): number;
+    calculateTaskRefinementRate(_tasks: TaskRecord[]): number;
+    calculatePlanningAccuracy(_tasks: TaskRecord[]): number;
+    calculateDependencyDiscoveryRate(_tasks: TaskRecord[]): number;
+    calculateCostBurnRate(): number;
+    calculateTokenConsumption(): number;
+    calculateTokenConsumptionByAgent(): Record<string, number>;
+    calculateAiAccuracyRate(): number;
+    calculateAgentExecutionTime(): number;
+}
+
+/**
+ * Event Bus types for GitGovernance event-driven architecture
+ */
+/**
+ * Event metadata for ordering and debugging
+ */
+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
+ */
+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;
+};
+
+type TaskCreatedEvent = BaseEvent & {
+    type: 'task.created';
+    payload: {
+        taskId: string;
+        triggeredBy: string;
+    };
+};
+type TaskStatusChangedEvent = BaseEvent & {
+    type: 'task.status.changed';
+    payload: {
+        taskId: string;
+        oldStatus: TaskRecord['status'];
+        newStatus: TaskRecord['status'];
+        triggeredBy: string;
+        reason?: string;
+    };
+};
+
+type CycleCreatedEvent = BaseEvent & {
+    type: 'cycle.created';
+    payload: {
+        cycleId: string;
+        triggeredBy: string;
+    };
+};
+type CycleStatusChangedEvent = BaseEvent & {
+    type: 'cycle.status.changed';
+    payload: {
+        cycleId: string;
+        oldStatus: CycleRecord['status'];
+        newStatus: CycleRecord['status'];
+        triggeredBy: string;
+    };
+};
+
+type ExecutionCreatedEvent = BaseEvent & {
+    type: 'execution.created';
+    payload: Pick<ExecutionRecord, 'taskId' | 'type' | 'title'> & {
+        executionId: string;
+        triggeredBy: string;
+        isFirstExecution: boolean;
+    };
+};
+
+type FeedbackCreatedEvent = BaseEvent & {
+    type: 'feedback.created';
+    payload: Pick<FeedbackRecord, 'entityType' | 'entityId' | 'type' | 'status' | 'content' | 'assignee' | 'resolvesFeedbackId'> & {
+        feedbackId: string;
+        triggeredBy: string;
+    };
+};
+
+type ChangelogCreatedEvent = BaseEvent & {
+    type: 'changelog.created';
+    payload: Pick<ChangelogRecord, 'relatedTasks' | 'title' | 'version'> & {
+        changelogId: string;
+    };
+};
+
+type ActorCreatedEvent = BaseEvent & {
+    type: 'identity.actor.created';
+    payload: Pick<ActorRecord, 'type' | 'publicKey' | 'roles'> & {
+        actorId: string;
+        isBootstrap: boolean;
+    };
+};
+type ActorRevokedEvent = BaseEvent & {
+    type: 'identity.actor.revoked';
+    payload: Pick<ActorRecord, 'supersededBy'> & {
+        actorId: string;
+        revokedBy: string;
+        revocationReason: 'compromised' | 'rotation' | 'manual';
+    };
+};
+type AgentRegisteredEvent = BaseEvent & {
+    type: 'identity.agent.registered';
+    payload: Pick<AgentRecord, 'engine'> & {
+        agentId: string;
+        correspondingActorId: string;
+    };
+};
+/**
+ * System events
+ */
+type SystemDailyTickEvent = BaseEvent & {
+    type: 'system.daily_tick';
+    payload: {
+        date: string;
+    };
+};
+/**
+ * Union type of all possible events
+ */
+type GitGovEvent = TaskCreatedEvent | TaskStatusChangedEvent | CycleCreatedEvent | CycleStatusChangedEvent | ExecutionCreatedEvent | FeedbackCreatedEvent | ChangelogCreatedEvent | ActorCreatedEvent | ActorRevokedEvent | AgentRegisteredEvent | SystemDailyTickEvent;
+/**
+ * Event handler function type
+ */
+type EventHandler<T extends BaseEvent = BaseEvent> = (event: T) => void | Promise<void>;
+/**
+ * Event subscription
+ */
+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 RecordProjector activity tracking
+ * Uses discriminated unions for type-safe metadata per event type
+ */
+type ActivityEvent = {
+    timestamp: number;
+    type: "task_created";
+    entityId: string;
+    entityTitle: string;
+    actorId?: string;
+    metadata?: {
+        priority?: string;
+        status?: string;
+    };
+} | {
+    timestamp: number;
+    type: "cycle_created";
+    entityId: string;
+    entityTitle: string;
+    actorId?: string;
+    metadata?: {
+        status?: string;
+    };
+} | {
+    timestamp: number;
+    type: "feedback_created";
+    entityId: string;
+    entityTitle: string;
+    actorId?: string;
+    metadata?: {
+        type?: string;
+        assignee?: string;
+        resolution?: string;
+    };
+} | {
+    timestamp: number;
+    type: "changelog_created";
+    entityId: string;
+    entityTitle: string;
+    actorId?: string;
+    metadata?: {
+        version?: string;
+    };
+} | {
+    timestamp: number;
+    type: "execution_created";
+    entityId: string;
+    entityTitle: string;
+    actorId?: string;
+    metadata?: {
+        executionType?: string;
+        taskId?: string;
+    };
+} | {
+    timestamp: number;
+    type: "actor_created";
+    entityId: string;
+    entityTitle: string;
+    actorId?: string;
+    metadata?: {
+        type?: string;
+    };
+} | {
+    timestamp: number;
+    type: "agent_registered";
+    entityId: string;
+    entityTitle: string;
+    actorId?: string;
+    metadata?: Record<string, never>;
+};
+
+/**
+ * Collection of all records with full GitGov metadata (headers + payloads).
+ * This allows access to signatures, checksums, and other metadata for enrichment.
+ *
+ * @see GitGovTaskRecord - Full record type with header.signatures for author/lastModifier extraction
+ */
+type AllRecords = {
+    tasks: GitGovTaskRecord[];
+    cycles: GitGovCycleRecord[];
+    feedback: GitGovFeedbackRecord[];
+    executions: GitGovExecutionRecord[];
+    changelogs: GitGovChangelogRecord[];
+    actors: GitGovActorRecord[];
+};
+/**
+ * System-wide derived states for dashboard analytics and filtering.
+ * Calculated by calculateDerivedStates() during index generation.
+ *
+ * @see derived_data_protocol.md for calculation algorithms
+ */
+type DerivedStates = {
+    stalledTasks: string[];
+    atRiskTasks: string[];
+    needsClarificationTasks: string[];
+    blockedByDependencyTasks: string[];
+};
+/**
+ * Optimized version of DerivedStates using Sets for O(1) lookup performance.
+ * Used internally by enrichTaskRecord() to efficiently check task membership.
+ *
+ * Conversion from DerivedStates (arrays) to DerivedStateSets (Sets) happens once
+ * in generateIndex() before processing multiple tasks, avoiding repeated O(n) lookups.
+ */
+type DerivedStateSets = {
+    stalledTasks: Set<string>;
+    atRiskTasks: Set<string>;
+    needsClarificationTasks: Set<string>;
+    blockedByDependencyTasks: Set<string>;
+};
+/**
+ * Enhanced Task Record with complete intelligence layer.
+ * Calculated by enrichTaskRecord() with relationships, metrics, and derived states.
+ *
+ * @see record_projection.md Section 3.6 - EnrichedTaskRecord Specification (EARS 25-48)
+ */
+type EnrichedTaskRecord = TaskRecord & {
+    derivedState: {
+        isStalled: boolean;
+        isAtRisk: boolean;
+        needsClarification: boolean;
+        isBlockedByDependency: boolean;
+        healthScore: number;
+        timeInCurrentStage: number;
+    };
+    relationships: {
+        author?: {
+            actorId: string;
+            timestamp: number;
+        };
+        lastModifier?: {
+            actorId: string;
+            timestamp: number;
+        };
+        assignedTo: Array<{
+            actorId: string;
+            assignedAt?: number;
+        }>;
+        dependsOn: string[];
+        blockedBy: string[];
+        cycles: Array<{
+            id: string;
+            title: string;
+        }>;
+    };
+    metrics: {
+        executionCount: number;
+        blockingFeedbackCount: number;
+        openQuestionCount: number;
+        timeToResolution?: number;
+    };
+    release: {
+        isReleased: boolean;
+        lastReleaseVersion?: string;
+    };
+    lastUpdated: number;
+    lastActivityType: 'task_modified' | 'feedback_received' | 'execution_added' | 'changelog_created' | 'task_created';
+    recentActivity?: string;
+};
+/**
+ * IndexData - Complete cached index structure.
+ * Generated by generateIndex() and consumed by CLI/Dashboard.
+ */
+type IndexData = {
+    metadata: {
+        generatedAt: string;
+        lastCommitHash: string;
+        integrityStatus: 'valid' | 'warnings' | 'errors';
+        recordCounts: Record<string, number>;
+        generationTime: number;
+    };
+    metrics: SystemStatus & ProductivityMetrics & CollaborationMetrics;
+    derivedStates: DerivedStates;
+    activityHistory: ActivityEvent[];
+    tasks: GitGovTaskRecord[];
+    enrichedTasks: EnrichedTaskRecord[];
+    cycles: GitGovCycleRecord[];
+    actors: GitGovActorRecord[];
+    feedback: GitGovFeedbackRecord[];
+};
+/**
+ * Integrity validation error types.
+ */
+type IntegrityError = {
+    type: 'schema_violation' | 'checksum_failure' | 'signature_invalid';
+    recordId: string;
+    message: string;
+};
+/**
+ * Integrity validation warning types.
+ */
+type IntegrityWarning = {
+    type: 'missing_reference' | 'deprecated_field' | 'performance_issue';
+    recordId: string;
+    message: string;
+};
+/**
+ * Result of validateIntegrity() operation.
+ */
+type IntegrityReport = {
+    status: 'valid' | 'warnings' | 'errors';
+    recordsScanned: number;
+    errorsFound: IntegrityError[];
+    warningsFound: IntegrityWarning[];
+    validationTime: number;
+    checksumFailures: number;
+    signatureFailures: number;
+};
+/**
+ * Result of generateIndex() operation.
+ */
+type IndexGenerationReport = {
+    success: boolean;
+    recordsProcessed: number;
+    metricsCalculated: number;
+    derivedStatesApplied: number;
+    generationTime: number;
+    errors: string[];
+    performance: {
+        readTime: number;
+        calculationTime: number;
+        writeTime: number;
+    };
+};
+/**
+ * Context for projection operations.
+ * Provides metadata about the projection target.
+ */
+type ProjectionContext = {
+    repoIdentifier?: string;
+    lastCommitHash?: string;
+};
+/**
+ * IRecordProjection - Driver pattern for projection output.
+ *
+ * Abstracts where IndexData is persisted. Implementations:
+ * - FsRecordProjection: writes to .gitgov/index.json (CLI)
+ * - MemoryRecordProjection: in-memory Map (tests)
+ * - PrismaRecordProjection: stores as JSON blob via Prisma-compatible client (SaaS)
+ */
+interface IRecordProjection {
+    persist(data: IndexData, context: ProjectionContext): Promise<void>;
+    read(context: ProjectionContext): Promise<IndexData | null>;
+    exists(context: ProjectionContext): Promise<boolean>;
+    clear(context: ProjectionContext): Promise<void>;
+}
+/**
+ * RecordProjector Dependencies - Facade + Dependency Injection Pattern.
+ *
+ * @see record_projection.md Section 2 - Architecture
+ */
+type RecordProjectorDependencies = {
+    recordMetrics: RecordMetrics;
+    stores: Required<Pick<RecordStores, 'tasks' | 'cycles' | 'feedbacks' | 'executions' | 'changelogs' | 'actors'>>;
+    sink?: IRecordProjection;
+};
+/**
+ * RecordProjector Interface - The Projection Engine.
+ */
+interface IRecordProjector {
+    generateIndex(): Promise<IndexGenerationReport>;
+    computeProjection(opts?: {
+        lastCommitHash?: string;
+    }): Promise<IndexData>;
+    getIndexData(): Promise<IndexData | null>;
+    validateIntegrity(): Promise<IntegrityReport>;
+    calculateDerivedStates(allRecords: AllRecords): Promise<DerivedStates>;
+    calculateActivityHistory(allRecords: AllRecords): Promise<ActivityEvent[]>;
+    calculateLastUpdated(task: GitGovTaskRecord, relatedRecords: AllRecords): Promise<{
+        lastUpdated: number;
+        lastActivityType: EnrichedTaskRecord['lastActivityType'];
+        recentActivity: string;
+    }>;
+    enrichTaskRecord(task: GitGovTaskRecord, relatedRecords: AllRecords, derivedStateSets: DerivedStateSets): Promise<EnrichedTaskRecord>;
+    isIndexUpToDate(): Promise<boolean>;
+    invalidateCache(): Promise<void>;
+}
+
+export { type FeedbackCreatedEvent as $, type ActorPayload as A, type ProductivityMetrics as B, type ChangelogPayload as C, RecordMetrics as D, type EmbeddedMetadataHeader as E, type FeedbackPayload as F, type GitGovRecord as G, type RecordMetricsDependencies as H, type IRecordProjector as I, type SystemStatus as J, type TaskHealthReport as K, type ActivityEvent as L, type ActorCreatedEvent as M, type ActorRevokedEvent as N, type AgentRegisteredEvent as O, type ProjectionContext as P, type BaseEvent as Q, type RecordStores as R, type Signature as S, type TaskPayload as T, type ChangelogCreatedEvent as U, type CycleCreatedEvent as V, type CycleStatusChangedEvent as W, type EventHandler as X, type EventMetadata as Y, type EventSubscription as Z, type ExecutionCreatedEvent as _, type IRecordProjection as a, type GitGovEvent as a0, type SystemDailyTickEvent as a1, type TaskCreatedEvent as a2, type TaskStatusChangedEvent as a3, type RecordProjectorDependencies as a4, type IndexGenerationReport as a5, type IntegrityReport as a6, type AllRecords as a7, type DerivedStates as a8, type EnrichedTaskRecord as a9, type DerivedStateSets as aa, type IntegrityError as ab, type IntegrityWarning as ac, type IndexData as b, type ActorRecord as c, type AgentPayload as d, type AgentRecord as e, type ChangelogRecord as f, type CustomRecord as g, type CyclePayload as h, type CycleRecord as i, type EmbeddedMetadataRecord as j, type ExecutionPayload as k, type ExecutionRecord as l, type FeedbackRecord as m, type GitGovActorRecord as n, type GitGovAgentRecord as o, type GitGovChangelogRecord as p, type GitGovCycleRecord as q, GitGovError as r, type GitGovExecutionRecord as s, type GitGovFeedbackRecord as t, type GitGovRecordPayload as u, type GitGovRecordType as v, type GitGovTaskRecord as w, type TaskRecord as x, type CollaborationMetrics as y, type IRecordMetrics as z };