@gitgov/core 1.8.3 → 1.10.0

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;
 }
 
 /**
@@ -327,7 +334,7 @@ interface ExecutionRecord {
 /**
  * Canonical schema for feedback records - structured conversation about work
  */
-interface FeedbackRecord {
+interface FeedbackRecord<TMetadata = object> {
     /**
      * Unique identifier for the feedback entry
      */
@@ -370,6 +377,13 @@ interface FeedbackRecord {
      * 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;
 }
 
 /**
@@ -754,7 +768,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,9 +777,9 @@ 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_FeedbackRecord<TMetadata = object> = FeedbackRecord<TMetadata>;
 type index$m_GitGovActorRecord = GitGovActorRecord;
 type index$m_GitGovAgentRecord = GitGovAgentRecord;
 type index$m_GitGovChangelogRecord = GitGovChangelogRecord;
@@ -3756,12 +3770,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.
@@ -3792,12 +3817,14 @@ declare function createChangelogRecord(payload: Partial<ChangelogRecord>): Chang
 declare function loadChangelogRecord(data: unknown): GitGovChangelogRecord;
 
 /**
- * Creates a complete FeedbackRecord with validation
+ * Creates a complete FeedbackRecord with validation.
+ *
+ * The factory is generic to preserve the metadata type for compile-time safety.
  *
- * @param payload - Partial FeedbackRecord payload
- * @returns FeedbackRecord - The validated FeedbackRecord
+ * @param payload - Partial FeedbackRecord payload with optional typed metadata
+ * @returns FeedbackRecord<TMetadata> - The validated FeedbackRecord with preserved metadata type
  */
-declare function createFeedbackRecord(payload: Partial<FeedbackRecord>): FeedbackRecord;
+declare function createFeedbackRecord<TMetadata extends object = object>(payload: Partial<FeedbackRecord<TMetadata>>): FeedbackRecord<TMetadata>;
 /**
  * Loads and validates an existing FeedbackRecord from untrusted data.
  * Used by RecordStore to validate records when reading from disk.
@@ -5675,8 +5702,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;
@@ -5684,7 +5732,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;
@@ -5745,6 +5820,18 @@ declare const Schemas: {
                 description: string;
                 examples: string[];
             };
+            metadata: {
+                type: string;
+                additionalProperties: boolean;
+                description: string;
+                examples: {
+                    fingerprint: string;
+                    ruleId: string;
+                    file: string;
+                    line: number;
+                    expiresAt: string;
+                }[];
+            };
         };
         examples: ({
             id: string;
@@ -7459,8 +7546,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;
@@ -7468,7 +7576,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;
@@ -7528,6 +7663,18 @@ declare function getSchema(name: SchemaName): {
             description: string;
             examples: string[];
         };
+        metadata: {
+            type: string;
+            additionalProperties: boolean;
+            description: string;
+            examples: {
+                fingerprint: string;
+                ruleId: string;
+                file: string;
+                line: number;
+                expiresAt: string;
+            }[];
+        };
     };
     examples: ({
         id: string;

package/dist/src/index.js

@@ -1388,6 +1388,29 @@ var execution_record_schema_default = {
       },
       default: [],
       description: "Optional list of typed references to relevant commits, files, PRs, or external documents.\nShould use typed prefixes for clarity and trazabilidad (see execution_protocol_appendix.md):\n- commit:     Git commit SHA\n- pr:         Pull Request number\n- file:       File path (relative to repo root)\n- url:        External URL\n- issue:      GitHub Issue number\n- task:       TaskRecord ID\n- exec:       ExecutionRecord ID (for corrections or dependencies)\n- changelog:  ChangelogRecord ID\n"
+    },
+    metadata: {
+      type: "object",
+      additionalProperties: true,
+      description: "Optional structured data for machine consumption.\nUse this field for data that needs to be programmatically processed (e.g., audit findings,\nperformance metrics, scan results). This complements result (human-readable WHAT) and\nnotes (narrative HOW/WHY) by providing structured, queryable data.\nCommon use cases: audit findings arrays, performance metrics, tool outputs, scan summaries.\n",
+      examples: [
+        {
+          findings: [
+            {
+              type: "PII",
+              file: "src/user.ts",
+              line: 42
+            }
+          ],
+          scannedFiles: 245
+        },
+        {
+          metrics: {
+            duration_ms: 1250,
+            memory_mb: 512
+          }
+        }
+      ]
     }
   },
   examples: [
@@ -1460,6 +1483,52 @@ var execution_record_schema_default = {
       references: [
         "exec:1752275500-exec-refactor-queries"
       ]
+    },
+    {
+      id: "1752276000-exec-gdpr-audit-scan",
+      taskId: "1752274500-task-gdpr-compliance",
+      type: "analysis",
+      title: "GDPR Audit Scan - 2025-01-15",
+      result: "Escaneados 245 archivos. Encontrados 10 findings (3 critical, 4 high, 3 medium). Ver metadata para detalles estructurados.",
+      notes: "Scan ejecutado con RegexDetector + HeuristicDetector. LLM calls: 0 (tier free).",
+      references: [
+        "file:src/config/db.ts",
+        "file:src/auth/keys.ts"
+      ],
+      metadata: {
+        scannedFiles: 245,
+        scannedLines: 18420,
+        duration_ms: 1250,
+        findings: [
+          {
+            id: "SEC-001",
+            severity: "critical",
+            file: "src/config/db.ts",
+            line: 5,
+            type: "api_key"
+          },
+          {
+            id: "SEC-003",
+            severity: "critical",
+            file: "src/auth/keys.ts",
+            line: 2,
+            type: "private_key"
+          },
+          {
+            id: "PII-003",
+            severity: "critical",
+            file: "src/payments/stripe.ts",
+            line: 8,
+            type: "credit_card"
+          }
+        ],
+        summary: {
+          critical: 3,
+          high: 4,
+          medium: 3,
+          low: 0
+        }
+      }
     }
   ]
 };
@@ -1565,6 +1634,20 @@ var feedback_record_schema_default = {
       examples: [
         "1752788100-feedback-blocking-rest-api"
       ]
+    },
+    metadata: {
+      type: "object",
+      additionalProperties: true,
+      description: "Optional structured data for machine consumption.\nUse this field for domain-specific data that needs to be programmatically processed.\nCommon use cases: waiver details (fingerprint, ruleId, file, line), approval context, assignment metadata.\n",
+      examples: [
+        {
+          fingerprint: "abc123def456",
+          ruleId: "PII-001",
+          file: "src/user.ts",
+          line: 42,
+          expiresAt: "2025-12-31T23:59:59Z"
+        }
+      ]
     }
   },
   examples: [
@@ -4032,7 +4115,7 @@ function createFeedbackRecord(payload) {
     content: payload.content || "",
     assignee: payload.assignee,
     resolvesFeedbackId: payload.resolvesFeedbackId,
-    ...payload
+    metadata: payload.metadata
   };
   const validation = validateFeedbackRecordDetailed(feedback);
   if (!validation.isValid) {
@@ -4320,7 +4403,7 @@ function createExecutionRecord(payload) {
     title: payload.title,
     notes: payload.notes,
     references: payload.references,
-    ...payload
+    metadata: payload.metadata
   };
   const validation = validateExecutionRecordDetailed(execution);
   if (!validation.isValid) {