@finsys/core 4.5.0 → 4.7.0

package/dist/index.d.cts

@@ -842,6 +842,19 @@ interface CanonicalFieldSpec {
     readonly unit?: string;
     readonly range?: readonly [number, number];
     readonly description: string;
+    /**
+     * Global fact identifier marking this field as an ATTESTATION of a
+     * shared real-world fact (e.g. a company has exactly one
+     * incorporation date, no matter which document it was extracted
+     * from). Multiple categories may declare the SAME field name iff
+     * every declaring category carries the same `fact` id — each
+     * category's value is then an independent attestation of one fact,
+     * comparable across sources (the future disagreement-comparison
+     * feature's unit of comparison). A `fact` id is bound to exactly one
+     * field name registry-wide; by convention the field name IS the fact
+     * id. Uniquely-declared fields need no `fact` (but may carry one).
+     */
+    readonly fact?: string;
 }
 /**
  * Per-category schema bundle. Used by:
@@ -883,11 +896,30 @@ declare function allCategories(): ReadonlyArray<CategorySchema>;
 /**
  * Reverse lookup: which category declares a given canonical field?
  * Returns null if the field name isn't declared by any category in
- * this version of finsys-core. Useful when the host app is reading
- * canonical field values back from storage + wants to identify the
- * producing category for rendering. O(1).
+ * this version of finsys-core — AND for shared-fact names (declared by
+ * more than one category), where "the" category is genuinely ambiguous.
+ * The null is deliberate: a caller holding a shared-fact name must
+ * decide per-attestation, via `categoriesAttestingFact(factOf(name))`,
+ * rather than being handed one arbitrary declarer. Useful when the
+ * host app is reading canonical field values back from storage + wants
+ * to identify the producing category for rendering. O(1).
  */
 declare function categoryForField(field: CanonicalFieldName): AdapterCategory | null;
+/**
+ * The fact id a canonical field attests, or null when the field
+ * declares no fact (or isn't declared at all). By convention the fact
+ * id equals the field name, but callers must not assume it — read it
+ * from here. O(1).
+ */
+declare function factOf(field: CanonicalFieldName): string | null;
+/**
+ * Every category attesting a given shared fact, in data-file order.
+ * Empty for an unknown fact id. This is the lookup the disagreement-
+ * comparison feature keys on: each attesting category's value for the
+ * fact's field is an independent observation of the same real-world
+ * fact, so cross-category mismatches are surfaceable.
+ */
+declare function categoriesAttestingFact(factId: string): ReadonlyArray<AdapterCategory>;
 /**
  * Runtime membership check — is `id` a category declared by this
  * version of finsys-core? Use this at trust boundaries (parsing a
@@ -1097,8 +1129,8 @@ type CanonicalFieldValue = number | string | boolean | null;
  * stay assignment-compatible. A telco adapter that needs an MSISDN
  * declares it once at the interface level:
  *
- *     interface CelcomExt { msisdn: string }
- *     const celcomTelco: SourceAdapter<CelcomExt> = {
+ *     interface TelcoPartnerExt { msisdn: string }
+ *     const telcoAdapter: SourceAdapter<TelcoPartnerExt> = {
  *       async fetch(identity) {
  *         identity.msisdn  // string  (typed via E)
  *         identity.ic      // string  (core)
@@ -1112,7 +1144,7 @@ type CanonicalFieldValue = number | string | boolean | null;
 interface SourceAdapter<E extends Record<string, unknown> = {}> {
     /**
      * Globally unique id for this adapter instance. By convention:
-     * `<vendor>-<category-short>-v<n>` — e.g. `celcom-telco-v1`. Vendor
+     * `<vendor>-<category-short>-v<n>` — e.g. `example-telco-v1`. Vendor
      * names appear here in deployment-specific code, NEVER in
      * finsys-core. The id is what the registry uses to dedupe + what
      * provenance records pin to.
@@ -1249,10 +1281,10 @@ interface SourceAdapter<E extends Record<string, unknown> = {}> {
  *
  * Narrowing example (the ergonomics win this type is designed to deliver):
  *
- *     interface CelcomExt { msisdn: string; accountRef: string }
+ *     interface TelcoPartnerExt { msisdn: string; accountRef: string }
  *
  *     // declare adapter with the extension shape baked in:
- *     const celcom: SourceAdapter<CelcomExt> = {
+ *     const telcoAdapter: SourceAdapter<TelcoPartnerExt> = {
  *       async fetch(identity) {
  *         identity.ic        // string
  *         identity.msisdn    // string  (NOT unknown — narrowed by E)
@@ -1434,7 +1466,7 @@ interface AdapterManifest {
     readonly manifestVersion: 1;
     /**
      * Globally unique adapter id. Conventional pattern:
-     * `<vendor>-<category-short>-v<n>` (e.g. `celcom-telco-v1`). The id is
+     * `<vendor>-<category-short>-v<n>` (e.g. `example-telco-v1`). The id is
      * what `SourceAdapter#id` returns + what provenance records pin to.
      */
     readonly id: string;
@@ -1740,4 +1772,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 CategorySpec, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DocumentFileMetadata, type DocumentRow, type DocumentRowCapabilities, type DocumentTypeGroup, type DropdownOption, type EditorValidator, type ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionPipelineImplementation, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldAuthorization, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, type FormIntakeFieldMapEntry, type FormIntakeImplementation, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_FIELD_ORIGINS, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldOrigin, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceRow, type InstanceValue, type ManualOverrideImplementation, type PageConfig, type PeriodDeclaration, type PeriodValues, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TaggedFieldData, type TimePeriodUnit, type TypescriptImplementation, type UnifiedFormConfig, type Validator, type WireFormat, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, assertDocumentType, buildDocumentRows, buildFileFieldTables, buildFileFieldTablesFromInstances, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getDocumentTypeGroups, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByInstance, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isDocumentType, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsFieldOrigin, isValidIhsStatus, parseFileField, 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 CategorySpec, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DocumentFileMetadata, type DocumentRow, type DocumentRowCapabilities, type DocumentTypeGroup, type DropdownOption, type EditorValidator, type ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionPipelineImplementation, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldAuthorization, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, type FormIntakeFieldMapEntry, type FormIntakeImplementation, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_FIELD_ORIGINS, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldOrigin, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceRow, type InstanceValue, type ManualOverrideImplementation, type PageConfig, type PeriodDeclaration, type PeriodValues, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TaggedFieldData, type TimePeriodUnit, type TypescriptImplementation, type UnifiedFormConfig, type Validator, type WireFormat, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, assertDocumentType, buildDocumentRows, buildFileFieldTables, buildFileFieldTablesFromInstances, categoriesAttestingFact, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, factOf, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getDocumentTypeGroups, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByInstance, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isDocumentType, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsFieldOrigin, isValidIhsStatus, parseFileField, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };

package/dist/index.d.ts

@@ -842,6 +842,19 @@ interface CanonicalFieldSpec {
     readonly unit?: string;
     readonly range?: readonly [number, number];
     readonly description: string;
+    /**
+     * Global fact identifier marking this field as an ATTESTATION of a
+     * shared real-world fact (e.g. a company has exactly one
+     * incorporation date, no matter which document it was extracted
+     * from). Multiple categories may declare the SAME field name iff
+     * every declaring category carries the same `fact` id — each
+     * category's value is then an independent attestation of one fact,
+     * comparable across sources (the future disagreement-comparison
+     * feature's unit of comparison). A `fact` id is bound to exactly one
+     * field name registry-wide; by convention the field name IS the fact
+     * id. Uniquely-declared fields need no `fact` (but may carry one).
+     */
+    readonly fact?: string;
 }
 /**
  * Per-category schema bundle. Used by:
@@ -883,11 +896,30 @@ declare function allCategories(): ReadonlyArray<CategorySchema>;
 /**
  * Reverse lookup: which category declares a given canonical field?
  * Returns null if the field name isn't declared by any category in
- * this version of finsys-core. Useful when the host app is reading
- * canonical field values back from storage + wants to identify the
- * producing category for rendering. O(1).
+ * this version of finsys-core — AND for shared-fact names (declared by
+ * more than one category), where "the" category is genuinely ambiguous.
+ * The null is deliberate: a caller holding a shared-fact name must
+ * decide per-attestation, via `categoriesAttestingFact(factOf(name))`,
+ * rather than being handed one arbitrary declarer. Useful when the
+ * host app is reading canonical field values back from storage + wants
+ * to identify the producing category for rendering. O(1).
  */
 declare function categoryForField(field: CanonicalFieldName): AdapterCategory | null;
+/**
+ * The fact id a canonical field attests, or null when the field
+ * declares no fact (or isn't declared at all). By convention the fact
+ * id equals the field name, but callers must not assume it — read it
+ * from here. O(1).
+ */
+declare function factOf(field: CanonicalFieldName): string | null;
+/**
+ * Every category attesting a given shared fact, in data-file order.
+ * Empty for an unknown fact id. This is the lookup the disagreement-
+ * comparison feature keys on: each attesting category's value for the
+ * fact's field is an independent observation of the same real-world
+ * fact, so cross-category mismatches are surfaceable.
+ */
+declare function categoriesAttestingFact(factId: string): ReadonlyArray<AdapterCategory>;
 /**
  * Runtime membership check — is `id` a category declared by this
  * version of finsys-core? Use this at trust boundaries (parsing a
@@ -1097,8 +1129,8 @@ type CanonicalFieldValue = number | string | boolean | null;
  * stay assignment-compatible. A telco adapter that needs an MSISDN
  * declares it once at the interface level:
  *
- *     interface CelcomExt { msisdn: string }
- *     const celcomTelco: SourceAdapter<CelcomExt> = {
+ *     interface TelcoPartnerExt { msisdn: string }
+ *     const telcoAdapter: SourceAdapter<TelcoPartnerExt> = {
  *       async fetch(identity) {
  *         identity.msisdn  // string  (typed via E)
  *         identity.ic      // string  (core)
@@ -1112,7 +1144,7 @@ type CanonicalFieldValue = number | string | boolean | null;
 interface SourceAdapter<E extends Record<string, unknown> = {}> {
     /**
      * Globally unique id for this adapter instance. By convention:
-     * `<vendor>-<category-short>-v<n>` — e.g. `celcom-telco-v1`. Vendor
+     * `<vendor>-<category-short>-v<n>` — e.g. `example-telco-v1`. Vendor
      * names appear here in deployment-specific code, NEVER in
      * finsys-core. The id is what the registry uses to dedupe + what
      * provenance records pin to.
@@ -1249,10 +1281,10 @@ interface SourceAdapter<E extends Record<string, unknown> = {}> {
  *
  * Narrowing example (the ergonomics win this type is designed to deliver):
  *
- *     interface CelcomExt { msisdn: string; accountRef: string }
+ *     interface TelcoPartnerExt { msisdn: string; accountRef: string }
  *
  *     // declare adapter with the extension shape baked in:
- *     const celcom: SourceAdapter<CelcomExt> = {
+ *     const telcoAdapter: SourceAdapter<TelcoPartnerExt> = {
  *       async fetch(identity) {
  *         identity.ic        // string
  *         identity.msisdn    // string  (NOT unknown — narrowed by E)
@@ -1434,7 +1466,7 @@ interface AdapterManifest {
     readonly manifestVersion: 1;
     /**
      * Globally unique adapter id. Conventional pattern:
-     * `<vendor>-<category-short>-v<n>` (e.g. `celcom-telco-v1`). The id is
+     * `<vendor>-<category-short>-v<n>` (e.g. `example-telco-v1`). The id is
      * what `SourceAdapter#id` returns + what provenance records pin to.
      */
     readonly id: string;
@@ -1740,4 +1772,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 CategorySpec, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DocumentFileMetadata, type DocumentRow, type DocumentRowCapabilities, type DocumentTypeGroup, type DropdownOption, type EditorValidator, type ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionPipelineImplementation, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldAuthorization, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, type FormIntakeFieldMapEntry, type FormIntakeImplementation, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_FIELD_ORIGINS, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldOrigin, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceRow, type InstanceValue, type ManualOverrideImplementation, type PageConfig, type PeriodDeclaration, type PeriodValues, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TaggedFieldData, type TimePeriodUnit, type TypescriptImplementation, type UnifiedFormConfig, type Validator, type WireFormat, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, assertDocumentType, buildDocumentRows, buildFileFieldTables, buildFileFieldTablesFromInstances, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getDocumentTypeGroups, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByInstance, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isDocumentType, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsFieldOrigin, isValidIhsStatus, parseFileField, 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 CategorySpec, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DocumentFileMetadata, type DocumentRow, type DocumentRowCapabilities, type DocumentTypeGroup, type DropdownOption, type EditorValidator, type ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionPipelineImplementation, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldAuthorization, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, type FormIntakeFieldMapEntry, type FormIntakeImplementation, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_FIELD_ORIGINS, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldOrigin, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceRow, type InstanceValue, type ManualOverrideImplementation, type PageConfig, type PeriodDeclaration, type PeriodValues, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TaggedFieldData, type TimePeriodUnit, type TypescriptImplementation, type UnifiedFormConfig, type Validator, type WireFormat, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, assertDocumentType, buildDocumentRows, buildFileFieldTables, buildFileFieldTablesFromInstances, categoriesAttestingFact, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, factOf, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getDocumentTypeGroups, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByInstance, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isDocumentType, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsFieldOrigin, isValidIhsStatus, parseFileField, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };