@gitgov/core 2.6.0 → 2.7.1

package/README.md

@@ -107,6 +107,7 @@ graph LR
         GhGit["GitHubGitModule"]
         GhConfig["GitHubConfigStore"]
         GhFiles["GitHubFileLister"]
+        GhSync["GithubSyncStateModule"]
     end
 
     subgraph "@gitgov/core/memory — Testing"
@@ -144,7 +145,7 @@ graph LR
 |--------|----------|-----|
 | `@gitgov/core` | Interfaces, types, pure logic, factories, validators | No |
 | `@gitgov/core/fs` | Filesystem implementations (FsRecordStore, FsRecordProjection, LocalGitModule, FsLintModule, ...) | Local |
-| `@gitgov/core/github` | GitHub API implementations (GitHubRecordStore, GitHubGitModule, GitHubConfigStore, GitHubFileLister) | Remote |
+| `@gitgov/core/github` | GitHub API implementations (GitHubRecordStore, GitHubGitModule, GitHubConfigStore, GitHubFileLister, GithubSyncStateModule) | Remote |
 | `@gitgov/core/memory` | In-memory implementations for testing (MemoryRecordStore, MemoryRecordProjection, MemoryGitModule, ...) | No |
 | `@gitgov/core/prisma` | Database-backed implementations via Prisma-compatible client (PrismaRecordProjection) | Remote |
 

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

@@ -0,0 +1,610 @@
+import { S as SessionStore } from './session_store-I4Z6PW2c.js';
+import { k as ISessionManager, a as GitGovSession, A as ActorState, S as SyncPreferencesUpdate, K as KeyProvider, h as FileLister, F as FsFileListerOptions, i as FileListOptions, j as FileStats, G as GitGovConfig } from './index-LULVRsCZ.js';
+import { q as IIdentityAdapter, u as IdentityAdapterDependencies, S as SyncStateModuleDependencies, p as IEventStream } from './sync_state-C2a2RuBQ.js';
+import { A as ActorPayload, d as ActorRecord, G as GitGovRecord, l as ExecutionRecord, y as RecordStores, f as AgentRecord } from './record_projection.types-D9NkQbL_.js';
+
+/**
+ * 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.
+ */
+
+/**
+ * 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 in .gitgov/keys/{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 (e.g., .gitgov/keys) */
+    keysDir: 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 in a dedicated directory with .key extension.
+ *
+ * @example
+ * ```typescript
+ * const provider = new FsKeyProvider({ keysDir: '.gitgov/keys' });
+ * await provider.setPrivateKey('actor:human:alice', 'base64PrivateKey...');
+ * const key = await provider.getPrivateKey('actor:human:alice');
+ * ```
+ */
+declare class FsKeyProvider implements KeyProvider {
+    private readonly keysDir;
+    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 keysDir if not exists.
+     * [EARS-FKP02] Writes key to {keysDir}/{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;
+}
+
+/**
+ * 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;
+}
+
+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>;
+}
+
+/**
+ * Reutiliza las mismas dependencias que FsSyncStateModule.
+ * No requiere dependencias adicionales.
+ */
+type FsWorktreeSyncStateDependencies = SyncStateModuleDependencies;
+/**
+ * Configuration for worktree-based sync module.
+ */
+type FsWorktreeSyncStateConfig = {
+    /** Root directory of the git repository */
+    repoRoot: string;
+    /** State branch name (default: "gitgov-state") */
+    stateBranchName?: string;
+    /** Absolute path to worktree. Default: path.join(repoRoot, '.gitgov-worktree') */
+    worktreePath?: string;
+};
+/** Default state branch name */
+declare const DEFAULT_STATE_BRANCH: "gitgov-state";
+
+/**
+ * ExecutionAdapter Dependencies - Facade + Dependency Injection Pattern
+ */
+type ExecutionAdapterDependencies = {
+    stores: Required<Pick<RecordStores, '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 AgentRunnerDependencies as A, type CustomEngine as C, DEFAULT_STATE_BRANCH as D, type EnvironmentValidation as E, type FsWorktreeSyncStateDependencies as F, type IProjectInitializer as I, type LocalEngine as L, type McpEngine as M, type ProtocolHandlerRegistry as P, type RunOptions as R, SessionManager as S, type FsWorktreeSyncStateConfig as a, type IAgentRunner as b, type AgentResponse as c, FsKeyProvider as d, type FsKeyProviderOptions as e, FsFileLister as f, IdentityAdapter as g, type IExecutionAdapter as h, type ExecutionAdapterDependencies as i, type AgentExecutionContext as j, type AgentOutput as k, type AgentRunnerEvent as l, type ApiEngine as m, type AuthConfig as n, type AuthType as o, type Engine as p, type EngineType as q, type IAgentLoader as r, type ProtocolHandler as s, type RuntimeHandler as t, type RuntimeHandlerRegistry as u };

package/dist/src/fs.d.ts

@@ -1,11 +1,11 @@
-import { R as RecordStore, I as IdEncoder } from './record_store-BXKWqon5.js';
-export { D as DEFAULT_ID_ENCODER } from './record_store-BXKWqon5.js';
-import { C as ConfigStore, G as GitGovConfig, I as IGitModule, a as GitModuleDependencies, E as ExecOptions, b as ExecResult, c as ChangedFile, d as GetCommitHistoryOptions, e as CommitInfo, f as CommitAuthor } from './index-Bhc341pf.js';
-export { F as FsFileListerOptions } from './index-Bhc341pf.js';
-import { C as ConfigManager, S as SessionManager, I as ILintModule, L as LintOptions, a as LintReport, F as FixRecordOptions, b as FixReport, R as RecordStores, c as LintRecordContext, d as LintResult, e as IProjectInitializer, E as EnvironmentValidation, f as ISyncStateModule, g as SyncStateModuleDependencies, h as StateDeltaFile, i as ConflictDiff, j as IntegrityViolation, A as AuditStateOptions, k as AuditStateReport, l as SyncStatePushOptions, m as SyncStatePushResult, n as SyncStatePullOptions, o as SyncStatePullResult, p as SyncStateResolveOptions, q as SyncStateResolveResult, r as IEventStream, s as IAgentRunner, P as ProtocolHandlerRegistry, t as AgentRunnerDependencies, u as RunOptions, v as AgentResponse } from './agent_runner-pr7h-9cV.js';
-export { y as FsFileLister, w as FsKeyProvider, x as FsKeyProviderOptions } from './agent_runner-pr7h-9cV.js';
-import { S as SessionStore, G as GitGovSession } from './key_provider-jjWek3w1.js';
-import { I as IRecordProjector, G as GitGovRecord, a as IRecordProjection, b as IndexData, P as ProjectionContext } from './record_projection.types-B8AM7u8U.js';
+import { R as RecordStore, I as IdEncoder, a as IRecordProjector, G as GitGovRecord, b as IRecordProjection, c as IndexData, P as ProjectionContext } from './record_projection.types-D9NkQbL_.js';
+export { D as DEFAULT_ID_ENCODER } from './record_projection.types-D9NkQbL_.js';
+import { C as ConfigStore, G as GitGovConfig, a as GitGovSession, I as IGitModule, b as GitModuleDependencies, E as ExecOptions, c as ExecResult, d as ChangedFile, e as GetCommitHistoryOptions, f as CommitInfo, g as CommitAuthor } from './index-LULVRsCZ.js';
+export { F as FsFileListerOptions } from './index-LULVRsCZ.js';
+import { C as ConfigManager, I as ILintModule, L as LintOptions, a as LintReport, F as FixRecordOptions, b as FixReport, R as RecordStores, c as LintRecordContext, d as LintResult, e as ISyncStateModule, S as SyncStateModuleDependencies, f as StateDeltaFile, g as ConflictDiff, h as IntegrityViolation, A as AuditStateOptions, i as AuditStateReport, j as SyncStatePushOptions, k as SyncStatePushResult, l as SyncStatePullOptions, m as SyncStatePullResult, n as SyncStateResolveOptions, o as SyncStateResolveResult, p as IEventStream } from './sync_state-C2a2RuBQ.js';
+import { S as SessionStore } from './session_store-I4Z6PW2c.js';
+import { S as SessionManager, I as IProjectInitializer, E as EnvironmentValidation, F as FsWorktreeSyncStateDependencies, a as FsWorktreeSyncStateConfig, b as IAgentRunner, P as ProtocolHandlerRegistry, A as AgentRunnerDependencies, R as RunOptions, c as AgentResponse } from './agent_runner-DijNVjaF.js';
+export { f as FsFileLister, d as FsKeyProvider, e as FsKeyProviderOptions } from './agent_runner-DijNVjaF.js';
 
 /**
  * Serializer for FsRecordStore - allows custom serialization
@@ -313,6 +313,10 @@ declare class FsLintModule implements IFsLintModule {
      * Delegates to LintModule.lintRecord() for pure validation.
      */
     lintRecord(record: GitGovRecord, context: LintRecordContext): LintResult[];
+    /**
+     * Delegates to LintModule.lintRecordReferences() for prefix validation.
+     */
+    lintRecordReferences(record: GitGovRecord, context: LintRecordContext): LintResult[];
     /**
      * Delegates to LintModule.fixRecord() for pure fix.
      */
@@ -1224,23 +1228,6 @@ declare class FsSyncStateModule implements ISyncStateModule {
     resolveConflict(options: SyncStateResolveOptions): Promise<SyncStateResolveResult>;
 }
 
-/**
- * Reutiliza las mismas dependencias que FsSyncStateModule.
- * No requiere dependencias adicionales.
- */
-type FsWorktreeSyncStateDependencies = SyncStateModuleDependencies;
-/**
- * Configuration for worktree-based sync module.
- */
-type FsWorktreeSyncStateConfig = {
-    /** Root directory of the git repository */
-    repoRoot: string;
-    /** State branch name (default: "gitgov-state") */
-    stateBranchName?: string;
-    /** Absolute path to worktree. Default: path.join(repoRoot, '.gitgov-worktree') */
-    worktreePath?: string;
-};
-
 /**
  * Worktree-based implementation of ISyncStateModule.
  *
@@ -1451,6 +1438,7 @@ declare function createAgentRunner(deps: AgentRunnerDependencies): IAgentRunner;
 type FsRecordProjectionOptions = {
     basePath: string;
 };
+
 /**
  * FsRecordProjection - Filesystem IRecordProjection for CLI.
  *