@gitgov/core 1.12.0 → 2.0.0

package/dist/src/agent_runner-COAjsdtr.d.ts

@@ -0,0 +1,2585 @@
+import { m as IConfigManager, C as ConfigStore, G as GitGovConfig, n as SyncConfig, o as SyncDefaults, k as AuditState, l as AuditStateUpdate, h as ISessionManager, S as SessionStore, a as GitGovSession, A as ActorState, i as SyncPreferencesUpdate, K as KeyProvider, s as FileLister, F as FsFileListerOptions, r as FileListOptions, t as FileStats, R as RecordStore, I as IGitModule } from './index-DMkBFK4C.js';
+
+/**
+ * ConfigManager - Project Configuration Manager
+ *
+ * Provides typed access to GitGovernance project configuration (config.json).
+ * Configuration is versioned in Git and shared between collaborators.
+ *
+ * Uses ConfigStore abstraction for backend-agnostic persistence.
+ *
+ * NOTE: Session state (.session.json) is handled by SessionManager, not ConfigManager.
+ *
+ * @see packages/blueprints/03_products/core/specs/modules/config_session_module.md
+ * @see packages/blueprints/03_products/protocol/10_appendices/config_file.md
+ */
+
+/**
+ * Configuration Manager Class
+ *
+ * Provides typed access to GitGovernance project configuration.
+ * Uses ConfigStore abstraction for backend-agnostic persistence.
+ *
+ * @example
+ * ```typescript
+ * // Production usage
+ * import { FsConfigStore } from '@gitgov/core/fs';
+ * const configStore = new FsConfigStore('/path/to/project');
+ * const configManager = new ConfigManager(configStore);
+ *
+ * // Test usage
+ * import { MemoryConfigStore } from '@gitgov/core/memory';
+ * const configStore = new MemoryConfigStore();
+ * configStore.setConfig({ ... });
+ * const configManager = new ConfigManager(configStore);
+ * ```
+ */
+declare class ConfigManager implements IConfigManager {
+    private readonly configStore;
+    constructor(configStore: ConfigStore);
+    /**
+     * Load GitGovernance configuration
+     */
+    loadConfig(): Promise<GitGovConfig | null>;
+    /**
+     * Get root cycle from configuration
+     */
+    getRootCycle(): Promise<string | null>;
+    /**
+     * Get project information from configuration
+     */
+    getProjectInfo(): Promise<{
+        id: string;
+        name: string;
+    } | null>;
+    /**
+     * Get sync configuration from config.json
+     * Returns sync strategy and related settings with defaults
+     */
+    getSyncConfig(): Promise<SyncConfig | null>;
+    /**
+     * Get sync defaults from config.json
+     * Returns recommended defaults for pullScheduler and fileWatcher
+     */
+    getSyncDefaults(): Promise<SyncDefaults>;
+    /**
+     * Get audit state from config.json
+     * Returns last full audit commit and timestamp for incremental mode
+     */
+    getAuditState(): Promise<AuditState>;
+    /**
+     * Update audit state in config.json after a full audit
+     * This is used to enable incremental audits
+     */
+    updateAuditState(auditState: AuditStateUpdate): Promise<void>;
+    /**
+     * Get state branch name from configuration
+     */
+    getStateBranch(): Promise<string>;
+}
+
+/**
+ * SessionManager - Local Session State Manager
+ *
+ * Provides typed access to GitGovernance session state (.session.json).
+ * Session state is ephemeral, machine-local, and NOT versioned in Git.
+ *
+ * Uses SessionStore abstraction for backend-agnostic persistence.
+ *
+ * @see packages/blueprints/03_products/protocol/10_appendices/session_state.md
+ */
+
+/**
+ * Session Manager Class
+ *
+ * Provides typed access to GitGovernance session state.
+ * Uses SessionStore abstraction for backend-agnostic persistence.
+ *
+ * @example
+ * ```typescript
+ * // Production usage
+ * import { FsSessionStore } from '@gitgov/core/fs';
+ * const sessionStore = new FsSessionStore('/path/to/project');
+ * const sessionManager = new SessionManager(sessionStore);
+ *
+ * // Test usage
+ * import { MemorySessionStore } from '@gitgov/core/memory';
+ * const sessionStore = new MemorySessionStore();
+ * sessionStore.setSession({ ... });
+ * const sessionManager = new SessionManager(sessionStore);
+ * ```
+ */
+declare class SessionManager implements ISessionManager {
+    private readonly sessionStore;
+    constructor(sessionStore: SessionStore);
+    /**
+     * Load GitGovernance session state
+     * [EARS-E1] Auto-detects actor from .key files if no session or no actorId exists
+     */
+    loadSession(): Promise<GitGovSession | null>;
+    /**
+     * [EARS-E1] Detect actor from .key files in .gitgov/actors/
+     */
+    detectActorFromKeyFiles(): Promise<string | null>;
+    /**
+     * Get actor state for a specific actor
+     */
+    getActorState(actorId: string): Promise<ActorState | null>;
+    /**
+     * Update actor state for a specific actor
+     */
+    updateActorState(actorId: string, state: Partial<ActorState>): Promise<void>;
+    /**
+     * Get cloud session token
+     */
+    getCloudSessionToken(): Promise<string | null>;
+    /**
+     * Get sync preferences from session
+     */
+    getSyncPreferences(): Promise<GitGovSession['syncPreferences'] | null>;
+    /**
+     * Update sync preferences in .session.json
+     * These are local machine preferences that override project defaults
+     */
+    updateSyncPreferences(preferences: SyncPreferencesUpdate): Promise<void>;
+    /**
+     * Get last session info (last human who interacted)
+     */
+    getLastSession(): Promise<{
+        actorId: string;
+        timestamp: string;
+    } | null>;
+}
+
+/**
+ * FsKeyProvider - Filesystem-based KeyProvider implementation
+ *
+ * Stores private keys alongside actor records in .gitgov/actors/{actorId}.key
+ * Used in development and CLI environments.
+ *
+ * @module key_provider/fs/fs_key_provider
+ */
+
+/**
+ * Options for FsKeyProvider.
+ */
+interface FsKeyProviderOptions {
+    /** Directory where key files are stored (same as actors: .gitgov/actors) */
+    actorsDir: string;
+    /** File extension for key files (default: '.key') */
+    extension?: string;
+    /** File permissions for key files (default: 0o600 - owner read/write only) */
+    fileMode?: number;
+}
+/**
+ * Filesystem-based KeyProvider implementation.
+ * Keys are stored alongside actor records with .key extension.
+ *
+ * @example
+ * ```typescript
+ * const provider = new FsKeyProvider({ actorsDir: '.gitgov/actors' });
+ * await provider.setPrivateKey('actor:human:alice', 'base64PrivateKey...');
+ * const key = await provider.getPrivateKey('actor:human:alice');
+ * ```
+ */
+declare class FsKeyProvider implements KeyProvider {
+    private readonly actorsDir;
+    private readonly extension;
+    private readonly fileMode;
+    constructor(options: FsKeyProviderOptions);
+    /**
+     * [EARS-KP01] Retrieves the private key for an actor.
+     * [EARS-FKP07] Trims whitespace from content.
+     * [EARS-FKP08] Returns null for empty key file.
+     */
+    getPrivateKey(actorId: string): Promise<string | null>;
+    /**
+     * [EARS-KP03] Stores a private key for an actor.
+     * [EARS-FKP01] Creates actorsDir if not exists.
+     * [EARS-FKP02] Writes key to {actorsDir}/{actorId}.key.
+     * [EARS-FKP03] Sets secure file permissions (0600).
+     */
+    setPrivateKey(actorId: string, privateKey: string): Promise<void>;
+    /**
+     * [EARS-FKP06] Checks if a private key exists for an actor.
+     */
+    hasPrivateKey(actorId: string): Promise<boolean>;
+    /**
+     * [EARS-KP04] Deletes the private key for an actor.
+     */
+    deletePrivateKey(actorId: string): Promise<boolean>;
+    /**
+     * [EARS-FKP04] Builds the key file path, sanitizing actorId to prevent path traversal.
+     * [EARS-FKP05] Replaces slashes with underscores.
+     */
+    private getKeyPath;
+    /**
+     * [EARS-FKP04] Sanitizes actorId to prevent directory traversal.
+     * [EARS-FKP05] Replaces path separators with underscores.
+     * [EARS-FKP09] Throws INVALID_ACTOR_ID for empty actorId.
+     */
+    private sanitizeActorId;
+    /**
+     * Sanitizes actorId for logging (removes potential secrets).
+     */
+    private sanitizeForLog;
+}
+
+/**
+ * FsFileLister - Filesystem-based FileLister implementation
+ *
+ * Uses fast-glob for pattern matching and fs/promises for file operations.
+ * Used in CLI and development environments.
+ *
+ * @module file_lister/fs/fs_file_lister
+ */
+
+/**
+ * Filesystem-based FileLister implementation.
+ * Uses fast-glob for pattern matching and fs/promises for file operations.
+ *
+ * @example
+ * ```typescript
+ * const lister = new FsFileLister({ cwd: '/path/to/project' });
+ * const files = await lister.list(['**\/*.ts'], { ignore: ['node_modules/**'] });
+ * const content = await lister.read('src/index.ts');
+ * ```
+ */
+declare class FsFileLister implements FileLister {
+    private readonly cwd;
+    constructor(options: FsFileListerOptions);
+    /**
+     * [EARS-FL01] Lists files matching glob patterns.
+     * [EARS-FFL01] Excludes files matching ignore patterns.
+     */
+    list(patterns: string[], options?: FileListOptions): Promise<string[]>;
+    /**
+     * [EARS-FL02] Checks if a file exists.
+     */
+    exists(filePath: string): Promise<boolean>;
+    /**
+     * [EARS-FL03] Reads file content as string.
+     * [EARS-FFL03] Throws FILE_NOT_FOUND for missing files.
+     */
+    read(filePath: string): Promise<string>;
+    /**
+     * [EARS-FL04] Gets file statistics.
+     * [EARS-FFL03] Throws FILE_NOT_FOUND for missing files.
+     */
+    stat(filePath: string): Promise<FileStats>;
+    /**
+     * [EARS-FFL04] Validates that the path doesn't contain traversal characters.
+     * [EARS-FFL05] Validates that the path is not absolute.
+     */
+    private validatePath;
+}
+
+/**
+ * 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$1 = {
+    actors?: RecordStore<GitGovActorRecord>;
+    agents?: RecordStore<GitGovAgentRecord>;
+    tasks?: RecordStore<GitGovTaskRecord>;
+    cycles?: RecordStore<GitGovCycleRecord>;
+    executions?: RecordStore<GitGovExecutionRecord>;
+    feedbacks?: RecordStore<GitGovFeedbackRecord>;
+    changelogs?: RecordStore<GitGovChangelogRecord>;
+};
+
+/**
+ * MetricsAdapter Dependencies - Facade + Dependency Injection Pattern
+ */
+type MetricsAdapterDependencies = {
+    stores: Required<Pick<RecordStores$1, 'tasks' | 'cycles' | 'feedbacks' | 'executions' | 'actors'>>;
+    platformApi?: IPlatformApi;
+};
+interface IPlatformApi {
+    getTokenConsumption(timeframe: string): Promise<TokenConsumption[]>;
+}
+type TokenConsumption = {
+    agentId: string;
+    tokens: number;
+    cost: number;
+    timestamp: number;
+};
+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;
+};
+/**
+ * MetricsAdapter Interface - The System Analyst
+ */
+interface IMetricsAdapter {
+    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;
+}
+
+/**
+ * MetricsAdapter - 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 MetricsAdapter implements IMetricsAdapter {
+    private stores;
+    private platformApi;
+    constructor(dependencies: MetricsAdapterDependencies);
+    /**
+     * [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;
+    /**
+     * [EARS-C4] Returns null for Premium metrics without Platform API.
+     */
+    calculateCostBurnRate(_consumption: TokenConsumption[]): number;
+    calculateTokenConsumption(_consumption: TokenConsumption[]): number;
+    calculateTokenConsumptionByAgent(_consumption: TokenConsumption[]): Record<string, number>;
+    calculateAiAccuracyRate(_tasks: TaskRecord[], _feedback: FeedbackRecord[]): number;
+    calculateAgentExecutionTime(_executions: ExecutionRecord[]): 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 IndexerAdapter 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>;
+};
+
+/**
+ * Event Stream interface - Contract for both Local and Global bus implementations
+ */
+interface IEventStream {
+    /**
+     * Publish an event to the bus
+     */
+    publish(event: BaseEvent): void;
+    /**
+     * Subscribe to events of a specific type
+     */
+    subscribe<T extends BaseEvent = BaseEvent>(eventType: string, handler: EventHandler<T>): EventSubscription;
+    /**
+     * Unsubscribe from events
+     */
+    unsubscribe(subscriptionId: string): boolean;
+    /**
+     * Get all active subscriptions
+     */
+    getSubscriptions(): EventSubscription[];
+    /**
+     * Clear all subscriptions (for testing/cleanup)
+     */
+    clearSubscriptions(): void;
+    /**
+     * Wait for all pending event handlers to complete (for testing)
+     */
+    waitForIdle(options?: {
+        timeout?: number;
+    }): Promise<void>;
+}
+/**
+ * Local EventBus implementation using Node.js EventEmitter
+ *
+ * This is the "Free Tier" implementation that operates in-memory
+ * and provides synchronous event delivery for local-first usage.
+ *
+ * Design Principles:
+ * - Decoupled Producers: Adapters emit events without knowing consumers
+ * - Pluggable Consumers: Event handlers can be added/removed dynamically
+ * - Type Safety: Full TypeScript support for all event types
+ * - Performance: In-memory delivery with minimal overhead
+ */
+declare class EventBus implements IEventStream {
+    private emitter;
+    private subscriptions;
+    private pendingHandlers;
+    constructor();
+    /**
+     * Publish an event to all subscribers
+     *
+     * @param event - The event to publish
+     */
+    publish(event: BaseEvent): void;
+    /**
+     * Subscribe to events of a specific type
+     *
+     * @param eventType - The event type to subscribe to
+     * @param handler - The handler function to call when event is received
+     * @returns EventSubscription object with subscription details
+     */
+    subscribe<T extends BaseEvent = BaseEvent>(eventType: string, handler: EventHandler<T>): EventSubscription;
+    /**
+     * Unsubscribe from events
+     *
+     * @param subscriptionId - The subscription ID to remove
+     * @returns true if subscription was found and removed, false otherwise
+     */
+    unsubscribe(subscriptionId: string): boolean;
+    /**
+     * Get all active subscriptions
+     *
+     * @returns Array of all active subscriptions
+     */
+    getSubscriptions(): EventSubscription[];
+    /**
+     * Clear all subscriptions (for testing/cleanup)
+     */
+    clearSubscriptions(): void;
+    /**
+     * Get subscription count for a specific event type
+     *
+     * @param eventType - The event type to count subscribers for
+     * @returns Number of active subscriptions for the event type
+     */
+    getSubscriptionCount(eventType: string): number;
+    /**
+     * Get all event types that have active subscriptions
+     *
+     * @returns Array of event types with active subscriptions
+     */
+    getActiveEventTypes(): string[];
+    /**
+     * Subscribe to all events (wildcard subscription)
+     * Useful for debugging, monitoring, or logging
+     *
+     * @param handler - Handler that will receive all events
+     * @returns EventSubscription object
+     */
+    subscribeToAll(handler: EventHandler<BaseEvent>): EventSubscription;
+    /**
+     * Wait for all pending event handlers to complete.
+     * This is primarily useful for testing to ensure event handlers finish before assertions.
+     *
+     * In production, events are fire-and-forget for performance.
+     * In tests, use this to synchronize and avoid race conditions.
+     *
+     * @param options - Optional configuration
+     * @param options.timeout - Maximum time to wait in ms (default: 5000)
+     * @returns Promise that resolves when all handlers complete or timeout occurs
+     *
+     * @example
+     * ```typescript
+     * await feedbackAdapter.create(...);  // publishes event
+     * await eventBus.waitForIdle();       // wait for BacklogAdapter.handleFeedbackCreated()
+     * const task = await backlogAdapter.getTask(taskId);
+     * expect(task.status).toBe('paused'); // now safe to assert
+     * ```
+     */
+    waitForIdle(options?: {
+        timeout?: number;
+    }): Promise<void>;
+}
+/**
+ * Singleton instance for application-wide event bus usage
+ */
+declare const eventBus: EventBus;
+/**
+ * Type-safe event publisher helper
+ * Ensures events conform to GitGovEvent union type
+ */
+declare function publishEvent(event: GitGovEvent): void;
+/**
+ * Type-safe event subscriber helper
+ * Provides better TypeScript inference for specific event types
+ */
+declare function subscribeToEvent<T extends GitGovEvent>(eventType: T['type'], handler: EventHandler<T>): EventSubscription;
+
+/**
+ * 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 indexer_adapter.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;
+    };
+};
+/**
+ * IndexerAdapter Dependencies - Facade + Dependency Injection Pattern.
+ *
+ * @see indexer_adapter.md Section 2 - Architecture
+ */
+type IndexerAdapterDependencies = {
+    metricsAdapter: MetricsAdapter;
+    stores: Required<Pick<RecordStores$1, 'tasks' | 'cycles' | 'feedbacks' | 'executions' | 'changelogs' | 'actors'>>;
+    cacheStore: RecordStore<IndexData>;
+};
+/**
+ * IndexerAdapter Interface - The Cache Engine.
+ */
+interface IIndexerAdapter {
+    generateIndex(): Promise<IndexGenerationReport>;
+    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>;
+}
+
+/**
+ * Public interface for pure LintModule operations (no I/O).
+ *
+ * This interface defines the core validation logic that works with
+ * GitGovRecord objects in memory, without any filesystem operations.
+ *
+ * For filesystem operations (directory scanning, file reading, backups),
+ * use IFsLintModule.
+ *
+ * @example
+ * ```typescript
+ * const lintModule: ILintModule = new LintModule({ stores });
+ *
+ * // Validate a single record (pure)
+ * const results = lintModule.lintRecord(record, { recordId, entityType });
+ *
+ * // Validate all records from stores
+ * const report = await lintModule.lint(options);
+ *
+ * // Fix a record (returns fixed record, no I/O)
+ * const fixedRecord = lintModule.fixRecord(record, results, { keyId, privateKey });
+ * ```
+ */
+interface ILintModule {
+    /**
+     * Validates a single record object (pure validation).
+     * Does NOT read files - receives pre-loaded record.
+     *
+     * @param record - The GitGovRecord object to validate
+     * @param context - Context with recordId and entityType
+     * @returns Array of lint results
+     */
+    lintRecord(record: GitGovRecord, context: LintRecordContext): LintResult[];
+    /**
+     * Validates all records from stores.
+     * Each implementation resolves its own data source.
+     *
+     * @param options - Configuration options
+     * @returns Consolidated lint report
+     */
+    lint(options?: Partial<LintOptions>): Promise<LintReport>;
+    /**
+     * Applies fixes to a record and returns the fixed version.
+     * Does NOT write to disk - returns modified object.
+     *
+     * @param record - The record to fix
+     * @param results - Lint results identifying problems
+     * @param options - Fix options including privateKey for signing
+     * @returns The fixed record
+     */
+    fixRecord(record: GitGovRecord, results: LintResult[], options: FixRecordOptions): GitGovRecord;
+}
+/**
+ * Entry for batch validation.
+ * Used by LintModule.lint() to process multiple records.
+ */
+interface RecordEntry {
+    /** The GitGovRecord object */
+    record: GitGovRecord;
+    /** Record ID */
+    id: string;
+    /** Entity type */
+    type: Exclude<GitGovRecordType, 'custom'>;
+    /** Optional file path for error reporting (FsLintModule provides this) */
+    filePath?: string;
+}
+/**
+ * Context for single record validation.
+ */
+interface LintRecordContext {
+    /** Record ID */
+    recordId: string;
+    /** Entity type */
+    entityType: Exclude<GitGovRecordType, 'custom'>;
+    /** Optional file path for error reporting */
+    filePath?: string;
+}
+/**
+ * Stores for reference lookups (pure interface).
+ * Uses generic RecordStore<T> interface, not filesystem-specific RecordStore.
+ */
+interface RecordStores {
+    actors?: RecordStore<GitGovRecord>;
+    agents?: RecordStore<GitGovRecord>;
+    tasks?: RecordStore<GitGovRecord>;
+    cycles?: RecordStore<GitGovRecord>;
+    executions?: RecordStore<GitGovRecord>;
+    feedbacks?: RecordStore<GitGovRecord>;
+    changelogs?: RecordStore<GitGovRecord>;
+}
+/**
+ * Dependencies for pure LintModule.
+ * All dependencies are optional for maximum flexibility.
+ */
+interface LintModuleDependencies {
+    /** Stores for reference lookups (OPTIONAL) */
+    stores?: RecordStores;
+    /**
+     * Indexing adapter for advanced reference resolution (OPTIONAL)
+     * If not present, reference validations will be limited.
+     */
+    indexerAdapter?: IIndexerAdapter;
+}
+/**
+ * Options for pure record fix operation.
+ * Does NOT include filesystem-specific options like createBackups.
+ */
+interface FixRecordOptions {
+    /** Types of problems to repair (default: all fixable) */
+    fixTypes?: ValidatorType[];
+    /** KeyId (actorId) for signing (default: 'system:migrator') */
+    keyId?: string;
+    /** Private key for signing (REQUIRED for signature fixes) */
+    privateKey?: string;
+}
+/**
+ * Options for pure LintModule operations.
+ * Does NOT include filesystem-specific options like path.
+ */
+interface LintOptions {
+    /**
+     * Validar referencias tipadas inteligentemente (default: false)
+     * Requiere stores presente para lookups.
+     */
+    validateReferences?: boolean;
+    /**
+     * Validar resolución de actorIds (default: false)
+     * Verifica que los actorIds existen via stores.
+     */
+    validateActors?: boolean;
+    /**
+     * Validar checksums de embedded metadata (default: true)
+     * Usa SHA256 sobre JSON canónico.
+     */
+    validateChecksums?: boolean;
+    /**
+     * Validar estructura de firmas (default: true)
+     * Verifica formato Ed25519 y campos requeridos.
+     */
+    validateSignatures?: boolean;
+    /**
+     * Validar consistencia temporal de timestamps (default: true)
+     * Valida que createdAt <= updatedAt <= completedAt.
+     */
+    validateTimestamps?: boolean;
+    /**
+     * Modo fail-fast o acumular todos los errores (default: false)
+     * Si true, detiene al primer error fatal.
+     */
+    failFast?: boolean;
+    /**
+     * Modo concurrente para batch processing (default: true)
+     * Procesa múltiples records en paralelo.
+     */
+    concurrent?: boolean;
+    /**
+     * Límite de concurrencia (default: 10)
+     * Número máximo de records procesados simultáneamente.
+     */
+    concurrencyLimit?: number;
+}
+/**
+ * Reporte consolidado de la ejecución de lint.
+ */
+interface LintReport {
+    /** Resumen cuantitativo de los resultados */
+    summary: LintSummary;
+    /** Lista detallada de cada problema encontrado */
+    results: LintResult[];
+    /** Metadata de la ejecución */
+    metadata: {
+        /** Timestamp ISO 8601 de ejecución */
+        timestamp: string;
+        /** Opciones utilizadas en esta ejecución */
+        options: LintOptions;
+        /** Versión del módulo lint */
+        version: string;
+    };
+}
+/**
+ * Resumen cuantitativo de resultados de lint.
+ */
+interface LintSummary {
+    /** Número total de archivos/records verificados */
+    filesChecked: number;
+    /** Número total de errores fatales que requieren corrección */
+    errors: number;
+    /** Número total de advertencias que sugieren mejoras */
+    warnings: number;
+    /** Número de problemas auto-reparables con fix() */
+    fixable: number;
+    /** Tiempo de ejecución en milisegundos */
+    executionTime: number;
+}
+/**
+ * Resultado individual de validación para una entidad específica.
+ */
+interface LintResult {
+    /** Nivel de severidad del problema detectado */
+    level: "error" | "warning" | "info";
+    /** Ruta relativa del archivo donde se detectó el problema */
+    filePath: string;
+    /** Tipo de validador que generó este resultado */
+    validator: ValidatorType;
+    /** Mensaje descriptivo del problema encontrado */
+    message: string;
+    /** Información de la entidad GitGovernance afectada */
+    entity: {
+        type: "actor" | "agent" | "task" | "cycle" | "execution" | "changelog" | "feedback";
+        id: string;
+    };
+    /** Indica si el error es auto-reparable con fixRecord() */
+    fixable: boolean;
+    /** Indica si el error fue reparado automáticamente (post-fix) */
+    fixed?: boolean;
+    /** Contexto adicional para debugging */
+    context?: {
+        field?: string;
+        actual?: unknown;
+        expected?: unknown;
+    };
+}
+/**
+ * Tipos de validadores disponibles en el pipeline.
+ */
+type ValidatorType = "SCHEMA_VALIDATION" | "REFERENTIAL_INTEGRITY" | "TYPED_REFERENCE" | "BIDIRECTIONAL_CONSISTENCY" | "EMBEDDED_METADATA_STRUCTURE" | "CHECKSUM_VERIFICATION" | "SIGNATURE_STRUCTURE" | "FILE_NAMING_CONVENTION" | "TEMPORAL_CONSISTENCY" | "ACTOR_RESOLUTION" | "SOFT_DELETE_DETECTION" | "SCHEMA_VERSION_MISMATCH";
+/**
+ * Contexto de ejecución para validación de un record individual.
+ */
+interface ValidationContext {
+    /** Path del archivo siendo validado */
+    filePath: string;
+    /** Configuración de validadores habilitados */
+    enabledValidators: ValidatorType[];
+    /** Caché de records ya cargados (para referencias) */
+    recordCache?: Map<string, GitGovRecord>;
+    /** Modo fail-fast habilitado */
+    failFast: boolean;
+}
+/**
+ * Reporte de operación de auto-fix.
+ */
+interface FixReport {
+    /** Resumen de reparaciones aplicadas */
+    summary: {
+        /** Número de problemas reparados exitosamente */
+        fixed: number;
+        /** Número de problemas que fallaron al reparar */
+        failed: number;
+        /** Número de backups creados */
+        backupsCreated: number;
+    };
+    /** Detalles de cada reparación */
+    fixes: FixResult[];
+}
+/**
+ * Resultado individual de reparación.
+ */
+interface FixResult {
+    /** Path del archivo reparado */
+    filePath: string;
+    /** Tipo de problema reparado */
+    validator: ValidatorType;
+    /** Descripción de la reparación aplicada */
+    action: string;
+    /** Éxito de la reparación */
+    success: boolean;
+    /** Error si falló la reparación */
+    error?: string;
+    /** Path del backup creado (si aplica) */
+    backupPath?: string;
+}
+
+/**
+ * Environment validation result.
+ * Used by filesystem implementations to check prerequisites.
+ */
+type EnvironmentValidation = {
+    /** Whether environment is valid for initialization */
+    isValid: boolean;
+    /** Whether directory contains Git repository (fs-only) */
+    isGitRepo: boolean;
+    /** Whether process has write permissions */
+    hasWritePermissions: boolean;
+    /** Whether GitGovernance is already initialized */
+    isAlreadyInitialized: boolean;
+    /** Path to .gitgov directory (if already initialized) */
+    gitgovPath?: string;
+    /** List of validation warnings */
+    warnings: string[];
+    /** Actionable suggestions for user */
+    suggestions: string[];
+    /** Whether a remote 'origin' is configured */
+    hasRemote?: boolean;
+    /** Whether the current branch has commits */
+    hasCommits?: boolean;
+    /** Name of the current branch */
+    currentBranch?: string;
+};
+
+/**
+ * Public interface for project initialization operations (pure - no I/O assumptions).
+ *
+ * This interface defines the contract for initializing GitGovernance projects
+ * across different backends (filesystem, database, API).
+ *
+ * The project context (path, tenant ID, etc.) is injected at construction time,
+ * so methods operate on the pre-configured project without needing explicit paths.
+ *
+ * Implementations:
+ * - FsProjectInitializer: Local filesystem (.gitgov/ directory)
+ * - DbProjectInitializer: Database (SaaS multi-tenant)
+ * - ApiProjectInitializer: Remote API (agents, serverless)
+ *
+ * @example
+ * ```typescript
+ * // CLI uses FsProjectInitializer with projectRoot injected
+ * const initializer: IProjectInitializer = new FsProjectInitializer('/path/to/project');
+ * await initializer.createProjectStructure();
+ *
+ * // SaaS uses DbProjectInitializer with tenant injected
+ * const initializer: IProjectInitializer = new DbProjectInitializer(pool, 'tenant-123');
+ * await initializer.createProjectStructure();
+ * ```
+ */
+interface IProjectInitializer {
+    /**
+     * Creates the project structure (directories for fs, tables for db, etc).
+     */
+    createProjectStructure(): Promise<void>;
+    /**
+     * Checks if a project is already initialized.
+     *
+     * @returns true if already initialized
+     */
+    isInitialized(): Promise<boolean>;
+    /**
+     * Writes the project configuration.
+     *
+     * @param config - GitGovConfig to persist
+     */
+    writeConfig(config: GitGovConfig): Promise<void>;
+    /**
+     * Initializes a session for the bootstrap actor.
+     *
+     * @param actorId - ID of the bootstrap actor
+     */
+    initializeSession(actorId: string): Promise<void>;
+    /**
+     * Cleans up partial setup if initialization fails.
+     */
+    rollback(): Promise<void>;
+    /**
+     * Validates environment for project initialization.
+     *
+     * @returns Validation result with warnings and suggestions
+     */
+    validateEnvironment(): Promise<EnvironmentValidation>;
+    /**
+     * Reads a file from the project context.
+     *
+     * @param filePath - Path to the file (relative or absolute depending on backend)
+     * @returns File contents as string
+     */
+    readFile(filePath: string): Promise<string>;
+    /**
+     * Copies the agent prompt to the project root for IDE access.
+     */
+    copyAgentPrompt(): Promise<void>;
+    /**
+     * Sets up version control integration (e.g., .gitignore for fs).
+     */
+    setupGitIntegration(): Promise<void>;
+    /**
+     * Gets the path/identifier for an actor record.
+     *
+     * @param actorId - Actor ID
+     * @returns Path or identifier for the actor
+     */
+    getActorPath(actorId: string): string;
+}
+
+/**
+ * IdentityAdapter Interface - The Identity Management Contract
+ *
+ * NOTE: AgentRecord operations have been moved to AgentAdapter.
+ * Use AgentAdapter for createAgentRecord, getAgentRecord, listAgentRecords.
+ */
+interface IIdentityAdapter {
+    createActor(payload: ActorPayload, signerId: string): Promise<ActorRecord>;
+    getActor(actorId: string): Promise<ActorRecord | null>;
+    listActors(): Promise<ActorRecord[]>;
+    revokeActor(actorId: string, revokedBy?: string, reason?: "compromised" | "rotation" | "manual", supersededBy?: string): Promise<ActorRecord>;
+    resolveCurrentActorId(originalActorId: string): Promise<string>;
+    getCurrentActor(): Promise<ActorRecord>;
+    getEffectiveActorForAgent(agentId: string): Promise<ActorRecord | null>;
+    signRecord<T extends GitGovRecord>(record: T, actorId: string, role: string, notes: string): Promise<T>;
+    rotateActorKey(actorId: string): Promise<{
+        oldActor: ActorRecord;
+        newActor: ActorRecord;
+    }>;
+    authenticate(sessionToken: string): Promise<void>;
+    getActorPublicKey(keyId: string): Promise<string | null>;
+}
+/**
+ * IdentityAdapter Dependencies - Facade + Dependency Injection Pattern
+ */
+interface IdentityAdapterDependencies {
+    stores: Required<Pick<RecordStores$1, 'actors'>>;
+    keyProvider: KeyProvider;
+    sessionManager: ISessionManager;
+    eventBus?: IEventStream;
+}
+
+declare class IdentityAdapter implements IIdentityAdapter {
+    private stores;
+    private keyProvider;
+    private sessionManager;
+    private eventBus;
+    constructor(dependencies: IdentityAdapterDependencies);
+    /**
+     * Get actor public key for validation - used by other adapters
+     */
+    getActorPublicKey(keyId: string): Promise<string | null>;
+    createActor(payload: ActorPayload, _signerId: string): Promise<ActorRecord>;
+    getActor(actorId: string): Promise<ActorRecord | null>;
+    listActors(): Promise<ActorRecord[]>;
+    signRecord<T extends GitGovRecord>(record: T, actorId: string, role: string, notes: string): Promise<T>;
+    /**
+     * Resolves the current active ActorRecord ID by following the succession chain.
+     * This is critical for AgentRecord operations after key rotation.
+     *
+     * @param originalActorId - The original actor ID (may be revoked)
+     * @returns Promise<string> - The current active actor ID
+     */
+    resolveCurrentActorId(originalActorId: string): Promise<string>;
+    /**
+     * Gets the current ActorRecord of the system based on active session or fallback.
+     * This is critical for CLI commands that need to know "who is the current user".
+     *
+     * @returns Promise<ActorRecord> - The current active ActorRecord
+     */
+    getCurrentActor(): Promise<ActorRecord>;
+    /**
+     * Gets the effective (current active) ActorRecord for an AgentRecord.
+     * This resolves the succession chain to get the current cryptographic identity.
+     *
+     * @param agentId - The AgentRecord ID (may reference revoked ActorRecord)
+     * @returns Promise<ActorRecord | null> - The current active ActorRecord or null
+     */
+    getEffectiveActorForAgent(agentId: string): Promise<ActorRecord | null>;
+    rotateActorKey(actorId: string): Promise<{
+        oldActor: ActorRecord;
+        newActor: ActorRecord;
+    }>;
+    revokeActor(actorId: string, revokedBy?: string, reason?: "compromised" | "rotation" | "manual", supersededBy?: string): Promise<ActorRecord>;
+    authenticate(_sessionToken: string): Promise<void>;
+}
+
+/**
+ * SyncStateModule Dependencies
+ */
+type SyncStateModuleDependencies = {
+    /** Low-level Git module (required) */
+    git: IGitModule;
+    /** Configuration manager (required) */
+    config: ConfigManager;
+    /** Identity adapter for signature verification and signing (required) */
+    identity: IIdentityAdapter;
+    /** Lint module for record validation (required) */
+    lint: ILintModule;
+    /** Indexer adapter for automatic re-indexing after pull/resolve (required) */
+    indexer: IIndexerAdapter;
+};
+/**
+ * Options for pushState operation
+ */
+type SyncStatePushOptions = {
+    /** Branch to push from (default: current branch) */
+    sourceBranch?: string;
+    /** Actor ID publishing the state (required) */
+    actorId: string;
+    /** Simulate operation without making real changes */
+    dryRun?: boolean;
+    /** Force push even if there are unsynced remote changes */
+    force?: boolean;
+};
+/**
+ * Result of pushState operation
+ */
+type SyncStatePushResult = {
+    /** Indicates if the operation was successful */
+    success: boolean;
+    /** Number of files synced */
+    filesSynced: number;
+    /** Name of the branch pushed from */
+    sourceBranch: string;
+    /** Created commit hash (null if no changes or dry-run) */
+    commitHash: string | null;
+    /** Created commit message */
+    commitMessage: string | null;
+    /** Indicates if a conflict was detected during reconciliation */
+    conflictDetected: boolean;
+    /** Conflict information if detected */
+    conflictInfo?: ConflictInfo;
+    /** Error message if operation failed */
+    error?: string;
+    /** [EARS-B16] Implicit pull results when push does reconciliation with remote */
+    implicitPull?: {
+        /** Whether changes were pulled from remote */
+        hasChanges: boolean;
+        /** Number of files updated from remote */
+        filesUpdated: number;
+        /** Whether index was regenerated */
+        reindexed: boolean;
+    };
+};
+/**
+ * Options for pullState operation
+ */
+type SyncStatePullOptions = {
+    /** Force re-indexing even if there are no new changes */
+    forceReindex?: boolean;
+    /** [EARS-C11] Force pull even if local changes would be overwritten */
+    force?: boolean;
+};
+/**
+ * Result of pullState operation
+ */
+type SyncStatePullResult = {
+    /** Indicates if the operation was successful */
+    success: boolean;
+    /** Indicates if there were new remote changes */
+    hasChanges: boolean;
+    /** Number of files updated */
+    filesUpdated: number;
+    /** Indicates if re-indexing was executed */
+    reindexed: boolean;
+    /** Indicates if a conflict was detected during pull */
+    conflictDetected: boolean;
+    /** Conflict information if detected */
+    conflictInfo?: ConflictInfo;
+    /** Error message if operation failed */
+    error?: string;
+    /** [EARS-C11] Files that were forcefully overwritten (when force: true) */
+    forcedOverwrites?: string[];
+};
+/**
+ * Options for resolveConflict operation
+ */
+type SyncStateResolveOptions = {
+    /** Justification for the conflict resolution (required) */
+    reason: string;
+    /** Actor ID resolving the conflict (required) */
+    actorId: string;
+};
+/**
+ * Result of resolveConflict operation
+ */
+type SyncStateResolveResult = {
+    /** Indicates if the operation was successful */
+    success: boolean;
+    /** Commit hash of the created rebase commit */
+    rebaseCommitHash: string;
+    /** Commit hash of the signed resolution commit */
+    resolutionCommitHash: string;
+    /** Number of conflicts resolved */
+    conflictsResolved: number;
+    /** Actor ID who resolved the conflict */
+    resolvedBy: string;
+    /** Reason for resolution */
+    reason: string;
+    /** Error message if operation failed */
+    error?: string;
+};
+/**
+ * Detailed information about a detected conflict
+ */
+type ConflictInfo = {
+    /** Type of conflict detected */
+    type: ConflictType;
+    /** Files affected by the conflict */
+    affectedFiles: string[];
+    /** Descriptive message of the conflict */
+    message: string;
+    /** Instructions to resolve the conflict */
+    resolutionSteps: string[];
+};
+/**
+ * Auxiliary type to identify the conflict type
+ *
+ * Git-Native conflict model (post-refactor):
+ * - rebase_conflict: Used for all Git-level conflicts during push/pull
+ * - local_changes_conflict: Used when pull would overwrite local changes (EARS-C10)
+ * - integrity_violation: Used when resolution commits are missing
+ */
+type ConflictType = "rebase_conflict" | "integrity_violation" | "local_changes_conflict";
+/**
+ * Information about a detected integrity violation
+ */
+type IntegrityViolation = {
+    /** Commit hash of the rebase commit without resolution */
+    rebaseCommitHash: string;
+    /** Message of the rebase commit */
+    commitMessage: string;
+    /** Timestamp of the commit */
+    timestamp: string;
+    /** Author of the commit */
+    author: string;
+};
+/**
+ * Verification scope for state audit
+ */
+type AuditScope = "current" | "state-branch" | "all";
+/**
+ * Scope for expected files verification
+ */
+type ExpectedFilesScope = "head" | "all-commits";
+/**
+ * Options for state audit
+ */
+type AuditStateOptions = {
+    /** Verification scope: which Records to verify (default: "all") */
+    scope?: AuditScope;
+    /** Verify signatures in Records (default: true) */
+    verifySignatures?: boolean;
+    /** Verify checksums of Records (default: true) */
+    verifyChecksums?: boolean;
+    /** Verify that expected files exist (default: true) */
+    verifyExpectedFiles?: boolean;
+    /** Scope for expected files verification (default: "head") */
+    expectedFilesScope?: ExpectedFilesScope;
+    /** Path of specific files to audit (default: all in .gitgov/) */
+    filePaths?: string[];
+};
+/**
+ * Conflict diff information for a file
+ */
+type ConflictFileDiff = {
+    /** Path of the conflicted file */
+    filePath: string;
+    /** Content of the local version (ours) */
+    localContent: string;
+    /** Content of the remote version (theirs) */
+    remoteContent: string;
+    /** Base content (common ancestor) */
+    baseContent: string | null;
+    /** Lines with conflict markers (if they still exist) */
+    conflictMarkers?: Array<{
+        line: number;
+        marker: string;
+    }>;
+};
+/**
+ * Structured conflict diff
+ */
+type ConflictDiff = {
+    /** Conflicted files with their diff */
+    files: ConflictFileDiff[];
+    /** Descriptive message of the conflict */
+    message: string;
+    /** Instructions to resolve */
+    resolutionSteps: string[];
+};
+/**
+ * Complete state audit report
+ *
+ * This report combines SyncStateModule-specific audits (rebase integrity, commits)
+ * with structural validation from LintModule (signatures, checksums, schemas).
+ */
+type AuditStateReport = {
+    /** Indicates if the audit passed without violations */
+    passed: boolean;
+    /** Scope used for the audit */
+    scope: AuditScope;
+    /** Total commits analyzed */
+    totalCommits: number;
+    /** Rebase commits found */
+    rebaseCommits: number;
+    /** Resolution commits found */
+    resolutionCommits: number;
+    /** Integrity violations of resolutions (SyncStateModule-specific) */
+    integrityViolations: IntegrityViolation[];
+    /** Summary message of the audit */
+    summary: string;
+    /** Complete LintModule report for structural validation (signatures, checksums, schemas, etc.) */
+    lintReport?: LintReport;
+};
+/**
+ * Information of a changed file in the delta
+ */
+type StateDeltaFile = {
+    /** File status: Added, Modified, Deleted */
+    status: "A" | "M" | "D";
+    /** File path */
+    file: string;
+};
+
+/**
+ * ISyncStateModule - State Synchronization Interface
+ *
+ * Defines the contract for state synchronization between local working tree
+ * and a shared state branch. Implementations handle the I/O specifics:
+ * - FsSyncStateModule: Uses local filesystem + git CLI (packages/core/src/sync_state/fs_sync/)
+ * - Future: GithubSyncStateModule via GitHub API
+ *
+ * @module sync_state
+ */
+
+/**
+ * State synchronization module interface.
+ *
+ * Provides push/pull/resolve operations for syncing .gitgov/ records
+ * with a shared state branch (e.g., gitgov-state).
+ */
+interface ISyncStateModule {
+    /** Returns the configured state branch name (default: "gitgov-state") */
+    getStateBranchName(): Promise<string>;
+    /** Ensures the state branch exists (creates if missing) */
+    ensureStateBranch(): Promise<void>;
+    /** Calculates the file delta between source branch and state branch */
+    calculateStateDelta(sourceBranch: string): Promise<StateDeltaFile[]>;
+    /** Checks if a rebase operation is currently in progress */
+    isRebaseInProgress(): Promise<boolean>;
+    /** Returns list of files that still contain conflict markers */
+    checkConflictMarkers(filePaths: string[]): Promise<string[]>;
+    /** Returns structured diff information for conflicted files */
+    getConflictDiff(filePaths?: string[]): Promise<ConflictDiff>;
+    /** Verifies that all rebase commits have corresponding resolution commits */
+    verifyResolutionIntegrity(): Promise<IntegrityViolation[]>;
+    /** Audits the state branch for integrity violations and structural issues */
+    auditState(options?: AuditStateOptions): Promise<AuditStateReport>;
+    /** Pushes local .gitgov/ state to the shared state branch */
+    pushState(options: SyncStatePushOptions): Promise<SyncStatePushResult>;
+    /** Pulls remote state changes into local .gitgov/ */
+    pullState(options?: SyncStatePullOptions): Promise<SyncStatePullResult>;
+    /** Resolves a rebase conflict with signed resolution commit */
+    resolveConflict(options: SyncStateResolveOptions): Promise<SyncStateResolveResult>;
+}
+
+/**
+ * ExecutionAdapter Dependencies - Facade + Dependency Injection Pattern
+ */
+type ExecutionAdapterDependencies = {
+    stores: Required<Pick<RecordStores$1, 'tasks' | 'executions'>>;
+    identity: IdentityAdapter;
+    eventBus: IEventStream;
+};
+/**
+ * ExecutionAdapter Interface - The Chronicler of the System
+ */
+interface IExecutionAdapter {
+    /**
+     * Records a new execution event.
+     */
+    create(payload: Partial<ExecutionRecord>, actorId: string): Promise<ExecutionRecord>;
+    /**
+     * Gets a specific ExecutionRecord by its ID.
+     */
+    getExecution(executionId: string): Promise<ExecutionRecord | null>;
+    /**
+     * Gets all ExecutionRecords for a specific Task.
+     */
+    getExecutionsByTask(taskId: string): Promise<ExecutionRecord[]>;
+    /**
+     * Gets all ExecutionRecords in the system.
+     */
+    getAllExecutions(): Promise<ExecutionRecord[]>;
+}
+
+/**
+ * Union type of all supported engines.
+ */
+type Engine = AgentRecord["engine"];
+/**
+ * Supported engine types by the runner.
+ */
+type EngineType = Engine["type"];
+/**
+ * Local engine configuration.
+ * Agent executes in the same process.
+ */
+type LocalEngine = Extract<Engine, {
+    type: "local";
+}>;
+/**
+ * API engine configuration.
+ * Agent executes on a remote server via HTTP.
+ */
+type ApiEngine = Extract<Engine, {
+    type: "api";
+}>;
+/**
+ * MCP engine configuration.
+ * Agent executes as MCP server (Model Context Protocol).
+ */
+type McpEngine = Extract<Engine, {
+    type: "mcp";
+}>;
+/**
+ * Custom engine configuration.
+ * Allows extensibility via registered protocol handlers.
+ */
+type CustomEngine = Extract<Engine, {
+    type: "custom";
+}>;
+/**
+ * Authentication configuration for remote backends (API/MCP).
+ * Extracted from the API engine's auth field.
+ */
+type AuthConfig = NonNullable<ApiEngine["auth"]>;
+/**
+ * Authentication types for remote backends.
+ */
+type AuthType = NonNullable<AuthConfig["type"]>;
+/**
+ * Execution context passed to each agent.
+ * Includes all information needed for traceability.
+ */
+type AgentExecutionContext = {
+    /** Agent ID being executed (e.g., "agent:source-audit") */
+    agentId: string;
+    /** ActorRecord executing (type "agent") */
+    actorId: string;
+    /** TaskRecord that triggered this execution (required) */
+    taskId: string;
+    /** Unique UUID for this execution */
+    runId: string;
+    /** Optional input passed to the agent (from RunOptions.input) */
+    input?: unknown;
+};
+/**
+ * Options for executing an agent.
+ */
+type RunOptions = {
+    /** Agent ID to execute (e.g., "agent:source-audit") */
+    agentId: string;
+    /** TaskRecord that triggers this execution (required) */
+    taskId: string;
+    /** Actor executing. If not provided, uses agentId */
+    actorId?: string;
+    /** Specific tool to invoke (MCP engines only) */
+    tool?: string;
+    /** Input to pass to the agent */
+    input?: unknown;
+};
+/**
+ * Structured output from the agent.
+ * Captured by the runner from each backend.
+ */
+type AgentOutput = {
+    /** Response data from agent (free structure) */
+    data?: unknown;
+    /** Text message (summary or description) */
+    message?: string;
+    /** Generated artifacts (file paths, record IDs, etc.) */
+    artifacts?: string[];
+    /** Additional agent metadata */
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Complete response from an agent execution.
+ * Returned by runner.runOnce().
+ */
+type AgentResponse = {
+    /** Unique UUID for this execution */
+    runId: string;
+    /** Executed agent ID */
+    agentId: string;
+    /** Execution status */
+    status: "success" | "error";
+    /** Agent output (only if status: "success") */
+    output?: AgentOutput;
+    /** Error message (only if status: "error") */
+    error?: string;
+    /** Created ExecutionRecord ID */
+    executionRecordId: string;
+    /** Start timestamp */
+    startedAt: string;
+    /** Completion timestamp */
+    completedAt: string;
+    /** Duration in milliseconds */
+    durationMs: number;
+};
+/**
+ * AgentRunner module dependencies (filesystem implementation).
+ */
+type AgentRunnerDependencies = {
+    /** Path to project root (REQUIRED, injected from CLI/bootstrap) */
+    projectRoot: string;
+    /** Path to .gitgov directory (optional, defaults to projectRoot/.gitgov) */
+    gitgovPath?: string;
+    /** IdentityAdapter for actor-signature auth (required if that auth type is used) */
+    identityAdapter?: IIdentityAdapter;
+    /** ExecutionAdapter for persisting executions (REQUIRED) */
+    executionAdapter: IExecutionAdapter;
+    /** EventBus for emitting events (optional, no events if not provided) */
+    eventBus?: IEventStream;
+    /** Protocol handler registry (for engine.type: "custom") */
+    protocolHandlers?: ProtocolHandlerRegistry;
+    /** Runtime handler registry (for engine.runtime in local engines) */
+    runtimeHandlers?: RuntimeHandlerRegistry;
+};
+/**
+ * Events emitted by the runner via EventBus.
+ */
+type AgentRunnerEvent = {
+    type: "agent:started";
+    payload: {
+        runId: string;
+        agentId: string;
+        taskId: string;
+        startedAt: string;
+    };
+} | {
+    type: "agent:completed";
+    payload: {
+        runId: string;
+        agentId: string;
+        taskId: string;
+        status: "success";
+        durationMs: number;
+        executionRecordId: string;
+    };
+} | {
+    type: "agent:error";
+    payload: {
+        runId: string;
+        agentId: string;
+        taskId: string;
+        status: "error";
+        error: string;
+        durationMs: number;
+        executionRecordId: string;
+    };
+};
+
+/**
+ * Interface for agent loader (allows mocking in tests).
+ */
+interface IAgentLoader {
+    loadAgent(agentId: string): Promise<AgentRecord>;
+}
+/**
+ * Interface for AgentRunner implementations.
+ * Allows different backends (filesystem, memory, serverless).
+ */
+interface IAgentRunner {
+    /**
+     * Executes an agent once and returns the response.
+     * TaskRecord must exist before calling this method.
+     */
+    runOnce(opts: RunOptions): Promise<AgentResponse>;
+}
+/**
+ * Registry for protocol handlers (engine.type: "custom").
+ */
+interface ProtocolHandlerRegistry {
+    register(protocol: string, handler: ProtocolHandler): void;
+    get(protocol: string): ProtocolHandler | undefined;
+}
+/**
+ * Handler for engine.type: "custom".
+ */
+type ProtocolHandler = (engine: CustomEngine, ctx: AgentExecutionContext) => Promise<AgentOutput>;
+/**
+ * Registry for runtime handlers (engine.runtime in local engines).
+ */
+interface RuntimeHandlerRegistry {
+    register(runtime: string, handler: RuntimeHandler): void;
+    get(runtime: string): RuntimeHandler | undefined;
+}
+/**
+ * Handler for engine.runtime in local engines.
+ */
+type RuntimeHandler = (engine: LocalEngine, ctx: AgentExecutionContext) => Promise<AgentOutput>;
+
+export { type GitGovChangelogRecord as $, type AuditStateOptions as A, type ActorPayload as B, ConfigManager as C, type ActorRecord as D, type EnvironmentValidation as E, type FixRecordOptions as F, type GitGovRecord as G, type AgentPayload as H, type ILintModule as I, type AgentRecord as J, type ChangelogPayload as K, type LintOptions as L, type ChangelogRecord as M, type CustomRecord as N, type CyclePayload as O, type ProtocolHandlerRegistry as P, type CycleRecord as Q, type RecordStores as R, SessionManager as S, type EmbeddedMetadataHeader as T, type EmbeddedMetadataRecord as U, type ExecutionPayload as V, type ExecutionRecord as W, type FeedbackPayload as X, type FeedbackRecord as Y, type GitGovActorRecord as Z, type GitGovAgentRecord as _, type LintReport as a, type ConflictFileDiff as a$, type GitGovCycleRecord as a0, GitGovError as a1, type GitGovExecutionRecord as a2, type GitGovFeedbackRecord as a3, type GitGovRecordPayload as a4, type GitGovRecordType as a5, type GitGovTaskRecord as a6, type Signature as a7, type TaskPayload as a8, type TaskRecord as a9, type TaskCreatedEvent as aA, type TaskStatusChangedEvent as aB, eventBus as aC, publishEvent as aD, subscribeToEvent as aE, type IndexerAdapterDependencies as aF, type IndexGenerationReport as aG, type IndexData as aH, type IntegrityReport as aI, type AllRecords as aJ, type DerivedStates as aK, type EnrichedTaskRecord as aL, type DerivedStateSets as aM, type IntegrityError as aN, type IntegrityWarning as aO, type IIdentityAdapter as aP, IdentityAdapter as aQ, type IdentityAdapterDependencies as aR, type LintModuleDependencies as aS, type FixResult as aT, type LintSummary as aU, type RecordEntry as aV, type ValidationContext as aW, type ValidatorType as aX, type IExecutionAdapter as aY, type ExecutionAdapterDependencies as aZ, type AuditScope as a_, type RecordStores$1 as aa, type CollaborationMetrics as ab, type IMetricsAdapter as ac, type IPlatformApi as ad, MetricsAdapter as ae, type MetricsAdapterDependencies as af, type ProductivityMetrics as ag, type SystemStatus as ah, type TaskHealthReport as ai, type TokenConsumption as aj, type ActivityEvent as ak, type ActorCreatedEvent as al, type ActorRevokedEvent as am, type AgentRegisteredEvent as an, type BaseEvent as ao, type ChangelogCreatedEvent as ap, type CycleCreatedEvent as aq, type CycleStatusChangedEvent as ar, EventBus as as, type EventHandler as at, type EventMetadata as au, type EventSubscription as av, type ExecutionCreatedEvent as aw, type FeedbackCreatedEvent as ax, type GitGovEvent as ay, type SystemDailyTickEvent as az, type FixReport as b, type ConflictInfo as b0, type ConflictType as b1, type ExpectedFilesScope as b2, type AgentExecutionContext as b3, type AgentOutput as b4, type AgentRunnerEvent as b5, type ApiEngine as b6, type AuthConfig as b7, type AuthType as b8, type CustomEngine as b9, type Engine as ba, type EngineType as bb, type IAgentLoader as bc, type LocalEngine as bd, type McpEngine as be, type ProtocolHandler as bf, type RuntimeHandler as bg, type RuntimeHandlerRegistry as bh, type IIndexerAdapter as c, type LintRecordContext as d, type LintResult as e, type IProjectInitializer as f, type ISyncStateModule as g, type SyncStateModuleDependencies as h, type StateDeltaFile as i, type ConflictDiff as j, type IntegrityViolation as k, type AuditStateReport as l, type SyncStatePushOptions as m, type SyncStatePushResult as n, type SyncStatePullOptions as o, type SyncStatePullResult as p, type SyncStateResolveOptions as q, type SyncStateResolveResult as r, type IEventStream as s, type IAgentRunner as t, type AgentRunnerDependencies as u, type RunOptions as v, type AgentResponse as w, FsKeyProvider as x, type FsKeyProviderOptions as y, FsFileLister as z };