@finsys/core 3.2.0 → 3.3.0

package/dist/index.d.cts

@@ -405,6 +405,27 @@ declare enum FileFieldTableType {
     TIME_SERIES = "timeSeries",
     KEY_VALUE = "keyValue"
 }
+/**
+ * Per-field extraction provenance (SYS-2737/SYS-2741). The single canonical
+ * envelope — finsys-api writes it (ihs_field_metadata), finsys-core surfaces it
+ * onto detail cells, both consumers render it. Vocabulary mirrors adapter_runs
+ * (SYS-2441) so FinXtract + adapter provenance converge at SYS-2499 Phase 5.
+ *
+ *   source      — who produced the value, e.g. "finxtract:ssm"
+ *   confidence  — normalized 0..1; null when derived/computed (no score)
+ *   observedAt  — ISO wall-clock of the extraction run
+ *   sourceRunId — the extraction run/job id that wrote it
+ *   origin      — "extracted" (a real {value,confidence} leaf) vs "derived"
+ *                 (computed / no-confidence path). A "derived" field must render
+ *                 as "no confidence available", never a fabricated low score.
+ */
+interface IhsFieldProvenance {
+    source: string;
+    confidence: number | null;
+    observedAt: string;
+    sourceRunId: string | null;
+    origin: 'extracted' | 'derived';
+}
 interface FileFieldTableItem {
     displayName: string;
     timePeriods: string[];
@@ -412,6 +433,14 @@ interface FileFieldTableItem {
     formattedData: Record<string, string>;
     type: FileFieldTableType;
     isNumeric: boolean;
+    /**
+     * SYS-2741: per-cell extraction provenance, keyed exactly like `data` (period
+     * key for TIME_SERIES, `'value'` for KEY_VALUE). `confidence` carries only
+     * scored (origin 'extracted') cells so a numeric dot never renders for a
+     * derived value; `provenance` carries the full envelope for every known cell.
+     */
+    confidence?: Record<string, number>;
+    provenance?: Record<string, IhsFieldProvenance>;
 }
 interface FileFieldTableData {
     name: string;
@@ -430,7 +459,7 @@ declare function groupColumnsByTimePeriod(columnNames: string[]): Record<string,
 declare function groupFieldsByPattern(fields: FieldData[]): Record<string, FieldData[]>;
 /** Returns human-friendly display names for field groups. */
 declare function getGroupDisplayNames(): Record<string, string>;
-declare function buildFileFieldTables(ihsData: Record<string, unknown>): Record<string, FileFieldTableData>;
+declare function buildFileFieldTables(ihsData: Record<string, unknown>, fieldProvenance?: Record<string, IhsFieldProvenance>): Record<string, FileFieldTableData>;
 declare function processIhsDetails(ihsData: Record<string, unknown>): IhsFieldDetail[];
 declare function groupDetailsByCategory(details: IhsFieldDetail[]): IhsDetailCategory[];
 
@@ -1220,4 +1249,4 @@ interface FieldMapEntry {
     readonly transform?: "identity" | "pct_to_ratio01" | "to_boolean" | "to_integer";
 }
 
-export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DropdownOption, type EditorValidator, ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, IhsStatus, IhsValueFormat, type InstanceValue, type PageConfig, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TypescriptImplementation, type UnifiedFormConfig, type Validator, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, buildFileFieldTables, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsStatus, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };
+export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DropdownOption, type EditorValidator, ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceValue, type PageConfig, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TypescriptImplementation, type UnifiedFormConfig, type Validator, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, buildFileFieldTables, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsStatus, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };

package/dist/index.d.ts

@@ -405,6 +405,27 @@ declare enum FileFieldTableType {
     TIME_SERIES = "timeSeries",
     KEY_VALUE = "keyValue"
 }
+/**
+ * Per-field extraction provenance (SYS-2737/SYS-2741). The single canonical
+ * envelope — finsys-api writes it (ihs_field_metadata), finsys-core surfaces it
+ * onto detail cells, both consumers render it. Vocabulary mirrors adapter_runs
+ * (SYS-2441) so FinXtract + adapter provenance converge at SYS-2499 Phase 5.
+ *
+ *   source      — who produced the value, e.g. "finxtract:ssm"
+ *   confidence  — normalized 0..1; null when derived/computed (no score)
+ *   observedAt  — ISO wall-clock of the extraction run
+ *   sourceRunId — the extraction run/job id that wrote it
+ *   origin      — "extracted" (a real {value,confidence} leaf) vs "derived"
+ *                 (computed / no-confidence path). A "derived" field must render
+ *                 as "no confidence available", never a fabricated low score.
+ */
+interface IhsFieldProvenance {
+    source: string;
+    confidence: number | null;
+    observedAt: string;
+    sourceRunId: string | null;
+    origin: 'extracted' | 'derived';
+}
 interface FileFieldTableItem {
     displayName: string;
     timePeriods: string[];
@@ -412,6 +433,14 @@ interface FileFieldTableItem {
     formattedData: Record<string, string>;
     type: FileFieldTableType;
     isNumeric: boolean;
+    /**
+     * SYS-2741: per-cell extraction provenance, keyed exactly like `data` (period
+     * key for TIME_SERIES, `'value'` for KEY_VALUE). `confidence` carries only
+     * scored (origin 'extracted') cells so a numeric dot never renders for a
+     * derived value; `provenance` carries the full envelope for every known cell.
+     */
+    confidence?: Record<string, number>;
+    provenance?: Record<string, IhsFieldProvenance>;
 }
 interface FileFieldTableData {
     name: string;
@@ -430,7 +459,7 @@ declare function groupColumnsByTimePeriod(columnNames: string[]): Record<string,
 declare function groupFieldsByPattern(fields: FieldData[]): Record<string, FieldData[]>;
 /** Returns human-friendly display names for field groups. */
 declare function getGroupDisplayNames(): Record<string, string>;
-declare function buildFileFieldTables(ihsData: Record<string, unknown>): Record<string, FileFieldTableData>;
+declare function buildFileFieldTables(ihsData: Record<string, unknown>, fieldProvenance?: Record<string, IhsFieldProvenance>): Record<string, FileFieldTableData>;
 declare function processIhsDetails(ihsData: Record<string, unknown>): IhsFieldDetail[];
 declare function groupDetailsByCategory(details: IhsFieldDetail[]): IhsDetailCategory[];
 
@@ -1220,4 +1249,4 @@ interface FieldMapEntry {
     readonly transform?: "identity" | "pct_to_ratio01" | "to_boolean" | "to_integer";
 }
 
-export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DropdownOption, type EditorValidator, ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, IhsStatus, IhsValueFormat, type InstanceValue, type PageConfig, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TypescriptImplementation, type UnifiedFormConfig, type Validator, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, buildFileFieldTables, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsStatus, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };
+export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DropdownOption, type EditorValidator, ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceValue, type PageConfig, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TypescriptImplementation, type UnifiedFormConfig, type Validator, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, buildFileFieldTables, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsStatus, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };

package/dist/index.js

@@ -9365,7 +9365,7 @@ function formatValue(value, numeric) {
   }
   return String(value);
 }
-function buildTableForGroup(groupName, fields, ihsData) {
+function buildTableForGroup(groupName, fields, ihsData, fieldProvenance) {
   const allColumns = [];
   for (const field of fields) {
     if (field.ihs_column_names) {
@@ -9384,11 +9384,20 @@ function buildTableForGroup(groupName, fields, ihsData) {
       const numeric = isNumericField(baseName);
       const data = {};
       const formattedData = {};
+      const confidence = {};
+      const provenance = {};
       for (const period of periods) {
         const colName = periodMap[period];
         const value = colName ? ihsData[colName] ?? null : null;
         data[period] = value;
         formattedData[period] = formatValue(value, numeric);
+        const prov = colName ? fieldProvenance?.[colName] : void 0;
+        if (prov) {
+          provenance[period] = prov;
+          if (prov.origin === "extracted" && typeof prov.confidence === "number" && !Number.isNaN(prov.confidence)) {
+            confidence[period] = prov.confidence;
+          }
+        }
       }
       items.push({
         displayName: getDisplayName(baseName),
@@ -9396,7 +9405,9 @@ function buildTableForGroup(groupName, fields, ihsData) {
         data,
         formattedData,
         type: tableType,
-        isNumeric: numeric
+        isNumeric: numeric,
+        ...Object.keys(confidence).length ? { confidence } : {},
+        ...Object.keys(provenance).length ? { provenance } : {}
       });
     }
     const hasData = items.some(
@@ -9408,13 +9419,16 @@ function buildTableForGroup(groupName, fields, ihsData) {
     for (const colName of allColumns) {
       const value = ihsData[colName] ?? null;
       const numeric = isNumericField(colName);
+      const prov = fieldProvenance?.[colName];
       items.push({
         displayName: getDisplayName(colName),
         timePeriods: [],
         data: { value },
         formattedData: { value: formatValue(value, numeric) },
         type: tableType,
-        isNumeric: numeric
+        isNumeric: numeric,
+        ...prov && prov.origin === "extracted" && typeof prov.confidence === "number" && !Number.isNaN(prov.confidence) ? { confidence: { value: prov.confidence } } : {},
+        ...prov ? { provenance: { value: prov } } : {}
       });
     }
     const hasData = items.some((item) => {
@@ -9424,13 +9438,13 @@ function buildTableForGroup(groupName, fields, ihsData) {
     return { name: groupName, displayName: groupDisplayName, type: tableType, items, hasData };
   }
 }
-function buildFileFieldTables(ihsData) {
+function buildFileFieldTables(ihsData, fieldProvenance) {
   const specs = getBaseFieldSpecs();
   const fileFields = specs.filter((f) => f.type === "file" && f.ihs_column_names?.length);
   const grouped = groupFieldsByPattern(fileFields);
   const tables = {};
   for (const [groupName, fields] of Object.entries(grouped)) {
-    const table = buildTableForGroup(groupName, fields, ihsData);
+    const table = buildTableForGroup(groupName, fields, ihsData, fieldProvenance);
     if (table && table.hasData) {
       tables[groupName] = table;
     }