@finsys/core 3.1.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;
     }
@@ -10101,6 +10115,99 @@ var adapter_categories_default = {
           description: "Cash Conversion Cycle (DSO + days-inventory-outstanding \u2212 DPO). Working-capital efficiency; negative values (collect before paying suppliers) are strongest, very high values indicate cash tied up in operations."
         }
       ]
+    },
+    {
+      id: "geolocation",
+      displayName: "Geolocation",
+      description: "Hourly-granularity movement track plus derived mobility signals for an applicant, sourced from any location-capable provider (telco network location, mobile-SDK GPS, GIS / address-verification services). Two instance kinds share this category: point instances (instanceKey 'pt:<ISO-hour>') carry one observed position per hourly bucket, mirroring the bank-statement multi-instance pattern; a single summary instance (instanceKey 'summary') carries adapter-derived behaviour signals \u2014 most importantly work-pattern regularity (sustained weekday dwell at a stable work anchor corroborates income reliability), residential stability, vacation windows, and dwell in operator-flagged hotspot zones. Vendor-agnostic: the source classifies or the adapter infers place labels; no provider-specific semantics leak into the field set. Raw coordinates are sensitive personal data \u2014 product-plane persistence is gated on PDPA consent + CRA Act 710 s25 retention review.",
+      canonicalTable: "ihs_alt_data_geolocation",
+      fields: [
+        {
+          name: "geoLatitude",
+          type: "number",
+          unit: "deg",
+          range: [-90, 90],
+          description: "Observed latitude for this hourly bucket (point instances only)."
+        },
+        {
+          name: "geoLongitude",
+          type: "number",
+          unit: "deg",
+          range: [-180, 180],
+          description: "Observed longitude for this hourly bucket (point instances only)."
+        },
+        {
+          name: "geoAccuracyM",
+          type: "number",
+          unit: "meters",
+          range: [0, 1e5],
+          description: "Source-reported horizontal accuracy radius of the observation. Cell-tower fixes are typically hundreds of meters; GPS fixes tens."
+        },
+        {
+          name: "geoBucket",
+          type: "string",
+          description: "ISO-8601 hour bucket of the observation, e.g. '2026-06-01T08'. Redundant with the instance key (pt:<bucket>) so consumers can query without parsing keys."
+        },
+        {
+          name: "geoPlaceLabel",
+          type: "string",
+          description: "Classified place for the bucket: home | work | commute | leisure | travel | hotspot | other. Classified by the source or inferred by the adapter from anchor dwell."
+        },
+        {
+          name: "geoWorkAttendanceRatio30d",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Fraction of the last 30 weekdays with >= 6 hours of dwell at the inferred work anchor. The income-reliability headline: regular full-time work patterns corroborate declared employment income (summary instance only)."
+        },
+        {
+          name: "geoWorkDailyHoursAvg30d",
+          type: "number",
+          unit: "hours",
+          range: [0, 24],
+          description: "Mean daily hours of work-anchor dwell across the last 30 weekdays (summary instance only)."
+        },
+        {
+          name: "geoLocationStabilityScore",
+          type: "number",
+          unit: "score",
+          range: [0, 1],
+          description: "Residential stability: share of nights spent at the primary home anchor over the observation window. 1 = every night at home (summary instance only)."
+        },
+        {
+          name: "geoCommuteRegularityRatio",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Consistency of the weekday home->work->home rhythm: fraction of weekdays matching the dominant commute pattern within an hour's tolerance (summary instance only)."
+        },
+        {
+          name: "geoVacationDays90d",
+          type: "number",
+          unit: "days",
+          range: [0, 90],
+          description: "Days in the last 90 spent fully away from both home and work anchors (contiguous travel windows; summary instance only)."
+        },
+        {
+          name: "geoHotspotDwellRatio",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Share of observed buckets spent inside operator-flagged hotspot zones (known fraud / illicit-activity locations supplied to the adapter). Non-zero values warrant review, not automatic decline (summary instance only)."
+        },
+        {
+          name: "geoPrimaryStateCode",
+          type: "string",
+          description: "Malaysian state / federal-territory code of the primary home anchor, e.g. PNG, KUL, JHR (summary instance only)."
+        },
+        {
+          name: "geoAddressMatchScore",
+          type: "number",
+          unit: "score",
+          range: [0, 1],
+          description: "Agreement between the inferred home anchor and the applicant's registered residential address. 1 = same premises, 0 = different state (summary instance only)."
+        }
+      ]
     }
   ]
 };