@gitgov/core 1.8.0 → 1.9.0

package/README.md

@@ -4,7 +4,7 @@
 [![License: MPL-2.0](https://img.shields.io/badge/License-MPL%202.0-brightgreen.svg)](https://opensource.org/licenses/MPL-2.0)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](./tsconfig.json)
 
-`@gitgov/core` is the **SDK** for the GitGovernance ecosystem. It provides a type-safe, local-first, and schema-driven API to manage identities, agents, and workflows in software projects.
+`@gitgov/core` is the **SDK** for the GitGovernance ecosystem. It provides a type-safe, local-first, and schema-driven API to manage identities, agents, tasks, and workflows in software projects.
 
 ## 🚀 Quick Start
 

package/dist/src/index.d.ts

@@ -54,7 +54,7 @@ interface ActorRecord {
 /**
  * Canonical schema for agent operational manifests.
  */
-interface AgentRecord {
+interface AgentRecord<TMetadata = object> {
     /**
      * Unique identifier for the agent, linking to an ActorRecord.
      */
@@ -87,9 +87,7 @@ interface AgentRecord {
      * This field does NOT affect agent execution - it is purely informational.
      *
      */
-    metadata?: {
-        [k: string]: unknown | undefined;
-    };
+    metadata?: TMetadata;
     engine: {
         type: 'local';
         /**
@@ -274,7 +272,7 @@ interface CycleRecord {
 /**
  * Canonical schema for execution log records - the universal event stream
  */
-interface ExecutionRecord {
+interface ExecutionRecord<TMetadata = object> {
     /**
      * Unique identifier for the execution log entry (10 timestamp + 1 dash + 4 'exec' + 1 dash + max 50 slug = 66 max)
      */
@@ -317,6 +315,15 @@ interface ExecutionRecord {
      *
      */
     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;
 }
 
 /**
@@ -754,7 +761,7 @@ declare class GitGovError extends Error {
 type index$m_ActorPayload = ActorPayload;
 type index$m_ActorRecord = ActorRecord;
 type index$m_AgentPayload = AgentPayload;
-type index$m_AgentRecord = AgentRecord;
+type index$m_AgentRecord<TMetadata = object> = AgentRecord<TMetadata>;
 type index$m_ChangelogPayload = ChangelogPayload;
 type index$m_ChangelogRecord = ChangelogRecord;
 type index$m_CustomRecord = CustomRecord;
@@ -763,7 +770,7 @@ type index$m_CycleRecord = CycleRecord;
 type index$m_EmbeddedMetadataHeader = EmbeddedMetadataHeader;
 type index$m_EmbeddedMetadataRecord<T extends GitGovRecordPayload> = EmbeddedMetadataRecord<T>;
 type index$m_ExecutionPayload = ExecutionPayload;
-type index$m_ExecutionRecord = ExecutionRecord;
+type index$m_ExecutionRecord<TMetadata = object> = ExecutionRecord<TMetadata>;
 type index$m_FeedbackPayload = FeedbackPayload;
 type index$m_FeedbackRecord = FeedbackRecord;
 type index$m_GitGovActorRecord = GitGovActorRecord;
@@ -1218,7 +1225,7 @@ interface IIdentityAdapter {
     resolveCurrentActorId(originalActorId: string): Promise<string>;
     getCurrentActor(): Promise<ActorRecord>;
     getEffectiveActorForAgent(agentId: string): Promise<ActorRecord | null>;
-    signRecord(record: GitGovRecord, actorId: string, role: string): Promise<GitGovRecord>;
+    signRecord(record: GitGovRecord, actorId: string, role: string, notes: string): Promise<GitGovRecord>;
     rotateActorKey(actorId: string): Promise<{
         oldActor: ActorRecord;
         newActor: ActorRecord;
@@ -1249,7 +1256,7 @@ declare class IdentityAdapter implements IIdentityAdapter {
     createActor(payload: ActorPayload, _signerId: string): Promise<ActorRecord>;
     getActor(actorId: string): Promise<ActorRecord | null>;
     listActors(): Promise<ActorRecord[]>;
-    signRecord(record: GitGovRecord, actorId: string, role: string): Promise<GitGovRecord>;
+    signRecord(record: GitGovRecord, actorId: string, role: string, notes: string): Promise<GitGovRecord>;
     /**
      * Resolves the current active ActorRecord ID by following the succession chain.
      * This is critical for AgentRecord operations after key rotation.
@@ -1887,8 +1894,15 @@ declare class ConfigManager {
     loadConfig(): Promise<GitGovConfig | null>;
     /**
      * Load GitGovernance session state
+     * [EARS-53] Auto-detects actor from .key files if no session or no actorId exists
      */
     loadSession(): Promise<GitGovSession | null>;
+    /**
+     * [EARS-53] Detect actor from .key files in .gitgov/actors/
+     * Returns the actor ID if exactly one .key file exists, or the first one if multiple exist.
+     * Private keys (.key files) indicate which actors can sign on this machine.
+     */
+    detectActorFromKeyFiles(): Promise<string | null>;
     /**
      * Get root cycle from configuration
      */
@@ -2139,7 +2153,7 @@ interface IBacklogAdapter {
     getAllTasks(): Promise<TaskRecord[]>;
     submitTask(taskId: string, actorId: string): Promise<TaskRecord>;
     approveTask(taskId: string, actorId: string): Promise<TaskRecord>;
-    updateTask(taskId: string, payload: Partial<TaskRecord>): Promise<TaskRecord>;
+    updateTask(taskId: string, payload: Partial<TaskRecord>, actorId: string): Promise<TaskRecord>;
     activateTask(taskId: string, actorId: string): Promise<TaskRecord>;
     completeTask(taskId: string, actorId: string): Promise<TaskRecord>;
     pauseTask(taskId: string, actorId: string, reason?: string): Promise<TaskRecord>;
@@ -2252,8 +2266,9 @@ declare class BacklogAdapter implements IBacklogAdapter {
     deleteTask(taskId: string, actorId: string): Promise<void>;
     /**
      * Updates a task with new payload
+     * [EARS-28] Signs the updated record with the editor's signature
      */
-    updateTask(taskId: string, payload: Partial<TaskRecord>): Promise<TaskRecord>;
+    updateTask(taskId: string, payload: Partial<TaskRecord>, actorId: string): Promise<TaskRecord>;
     /**
      * Gets tasks assigned to a specific actor
      */
@@ -3748,12 +3763,23 @@ declare function createCycleRecord(payload: Partial<CycleRecord>): CycleRecord;
 declare function loadCycleRecord(data: unknown): GitGovCycleRecord;
 
 /**
- * Creates a complete ExecutionRecord with validation
+ * Creates a complete ExecutionRecord with validation.
+ *
+ * The factory is generic to preserve the metadata type for compile-time safety.
+ *
+ * @param payload - Partial ExecutionRecord payload with optional typed metadata
+ * @returns ExecutionRecord<TMetadata> - The validated ExecutionRecord with preserved metadata type
  *
- * @param payload - Partial ExecutionRecord payload
- * @returns ExecutionRecord - The validated ExecutionRecord
+ * @example
+ * interface AuditMetadata { scannedFiles: number; }
+ * const record = createExecutionRecord<AuditMetadata>({
+ *   taskId: '1752274500-task-audit',
+ *   result: 'Audit complete',
+ *   metadata: { scannedFiles: 245 }
+ * });
+ * // record.metadata?.scannedFiles is typed as number
  */
-declare function createExecutionRecord(payload: Partial<ExecutionRecord>): ExecutionRecord;
+declare function createExecutionRecord<TMetadata extends object = object>(payload: Partial<ExecutionRecord<TMetadata>>): ExecutionRecord<TMetadata>;
 /**
  * Loads and validates an existing ExecutionRecord from untrusted data.
  * Used by RecordStore to validate records when reading from disk.
@@ -5667,8 +5693,29 @@ declare const Schemas: {
                 default: never[];
                 description: string;
             };
+            metadata: {
+                type: string;
+                additionalProperties: boolean;
+                description: string;
+                examples: ({
+                    findings: {
+                        type: string;
+                        file: string;
+                        line: number;
+                    }[];
+                    scannedFiles: number;
+                    metrics?: never;
+                } | {
+                    metrics: {
+                        duration_ms: number;
+                        memory_mb: number;
+                    };
+                    findings?: never;
+                    scannedFiles?: never;
+                })[];
+            };
         };
-        examples: {
+        examples: ({
             id: string;
             taskId: string;
             type: string;
@@ -5676,7 +5723,34 @@ declare const Schemas: {
             result: string;
             notes: string;
             references: string[];
-        }[];
+            metadata?: never;
+        } | {
+            id: string;
+            taskId: string;
+            type: string;
+            title: string;
+            result: string;
+            notes: string;
+            references: string[];
+            metadata: {
+                scannedFiles: number;
+                scannedLines: number;
+                duration_ms: number;
+                findings: {
+                    id: string;
+                    severity: string;
+                    file: string;
+                    line: number;
+                    type: string;
+                }[];
+                summary: {
+                    critical: number;
+                    high: number;
+                    medium: number;
+                    low: number;
+                };
+            };
+        })[];
     };
     readonly FeedbackRecord: {
         $schema: string;
@@ -7451,8 +7525,29 @@ declare function getSchema(name: SchemaName): {
             default: never[];
             description: string;
         };
+        metadata: {
+            type: string;
+            additionalProperties: boolean;
+            description: string;
+            examples: ({
+                findings: {
+                    type: string;
+                    file: string;
+                    line: number;
+                }[];
+                scannedFiles: number;
+                metrics?: never;
+            } | {
+                metrics: {
+                    duration_ms: number;
+                    memory_mb: number;
+                };
+                findings?: never;
+                scannedFiles?: never;
+            })[];
+        };
     };
-    examples: {
+    examples: ({
         id: string;
         taskId: string;
         type: string;
@@ -7460,7 +7555,34 @@ declare function getSchema(name: SchemaName): {
         result: string;
         notes: string;
         references: string[];
-    }[];
+        metadata?: never;
+    } | {
+        id: string;
+        taskId: string;
+        type: string;
+        title: string;
+        result: string;
+        notes: string;
+        references: string[];
+        metadata: {
+            scannedFiles: number;
+            scannedLines: number;
+            duration_ms: number;
+            findings: {
+                id: string;
+                severity: string;
+                file: string;
+                line: number;
+                type: string;
+            }[];
+            summary: {
+                critical: number;
+                high: number;
+                medium: number;
+                low: number;
+            };
+        };
+    })[];
 } | {
     $schema: string;
     $id: string;
@@ -8296,6 +8418,15 @@ interface SyncPushResult {
     conflictInfo?: ConflictInfo;
     /** Error message if operation failed */
     error?: string;
+    /** [EARS-54] 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
@@ -8303,6 +8434,8 @@ interface SyncPushResult {
 interface SyncPullOptions {
     /** Force re-indexing even if there are no new changes */
     forceReindex?: boolean;
+    /** [EARS-62] Force pull even if local changes would be overwritten */
+    force?: boolean;
 }
 /**
  * Result of pullState operation
@@ -8322,6 +8455,8 @@ interface SyncPullResult {
     conflictInfo?: ConflictInfo;
     /** Error message if operation failed */
     error?: string;
+    /** [EARS-62] Files that were forcefully overwritten (when force: true) */
+    forcedOverwrites?: string[];
 }
 /**
  * Options for resolveConflict operation
@@ -8366,8 +8501,13 @@ interface ConflictInfo {
 }
 /**
  * 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-61)
+ * - integrity_violation: Used when resolution commits are missing
  */
-type ConflictType = "rebase_conflict" | "merge_conflict" | "integrity_violation" | "unresolved_markers";
+type ConflictType = "rebase_conflict" | "integrity_violation" | "local_changes_conflict";
 /**
  * Information about a detected integrity violation
  */
@@ -8541,6 +8681,17 @@ declare class SyncModule {
      * [EARS-5]
      */
     calculateStateDelta(sourceBranch: string): Promise<StateDeltaFile[]>;
+    /**
+     * [EARS-60] Detect file-level conflicts and identify remote-only changes.
+     *
+     * A conflict exists when:
+     * 1. A file was modified by the remote during implicit pull
+     * 2. AND the LOCAL USER also modified that same file (content in tempDir differs from what was in git before pull)
+     *
+     * This catches conflicts that git rebase can't detect because we copy files AFTER the pull.
+     *
+     * @param tempDir - Directory containing local .gitgov/ files (preserved before checkout)
+     * @param repoRoot - Repository root path
     /**
      * Checks if a rebase is in progress.
      *
@@ -8591,9 +8742,20 @@ declare class SyncModule {
      */
     pullState(options?: SyncPullOptions): Promise<SyncPullResult>;
     /**
-     * Resolves state conflicts in a governed manner.
-     * Updates resolved Records (recalculates checksum and adds resolver signature),
-     * creates rebase and resolution commits signed according to protocol.
+     * Resolves state conflicts in a governed manner (Git-Native).
+     *
+     * Git-Native Flow:
+     * 1. User resolves conflicts using standard Git tools (edit files, remove markers)
+     * 2. User stages resolved files: git add .gitgov/
+     * 3. User runs: gitgov sync resolve --reason "reason"
+     *
+     * This method:
+     * - Verifies that a rebase is in progress
+     * - Checks that no conflict markers remain in staged files
+     * - Updates resolved Records with new checksums and signatures
+     * - Continues the git rebase (git rebase --continue)
+     * - Creates a signed resolution commit
+     * - Regenerates the index
      *
      * [EARS-17 through EARS-23]
      */