@finsys/core 2.7.0 → 3.2.0

package/dist/index.d.cts

@@ -571,16 +571,28 @@ interface ExtractionStatusResult {
 declare function resolveExtractionStatus(ihsRecord: Record<string, unknown>, jobRecords?: ExtractionJobRecord[]): ExtractionStatusResult;
 
 /**
- * Generic categories declared in this package. The set is union-typed
- * so consumers get TypeScript autocomplete (`'telco-carrier' |
- * 'payment-network' | ...`) and a compile-time error if they reference
- * a category that doesn't exist.
+ * Adapter category identifier.
  *
- * NB: adding a new category is a finsys-core minor version bump.
- * Vendor adapters can ship freely (deployment-time, no core change)
- * but the CATEGORY they implement must exist here.
+ * Open `string` type (SYS-2500). The authoritative set lives in the
+ * runtime registry built from `data/adapter-categories.json`; there is
+ * no compile-time union to enumerate. The trade-off vs. the old
+ * literal union is the loss of autocomplete + exhaustiveness on
+ * category ids — validate at boundaries with `isAdapterCategory()` /
+ * `assertAdapterCategory()` instead, and read the canonical set from
+ * `ADAPTER_CATEGORY_IDS` / `allCategories()`.
  */
-type AdapterCategory = "telco-carrier" | "payment-network" | "bank-statement";
+type AdapterCategory = string;
+/**
+ * Union of all canonical field names declared by any category. Loose-
+ * typed (string) because the set grows with each category-added minor;
+ * the runtime registry narrows against the data file.
+ *
+ * Adapter `produces` lists are typed as ReadonlyArray<CanonicalFieldName>
+ * — the host validates membership against the adapter's category at
+ * registration time, refusing adapters that promise fields outside
+ * their category.
+ */
+type CanonicalFieldName = string;
 /**
  * Per-field metadata for a canonical field declared by a category.
  * Frozen at module load — the data file is authoritative.
@@ -607,20 +619,14 @@ interface CategorySchema {
     readonly fields: ReadonlyArray<CanonicalFieldSpec>;
 }
 /**
- * Union of all canonical field names declared by any category in this
- * package. Loose-typed at compile time (string) because the actual
- * union grows with each category-added minor; runtime helpers below
- * narrow against the data.
- *
- * Adapter `produces` lists are typed as ReadonlyArray<CanonicalFieldName>
- * — the host validates membership against the adapter's category at
- * registration time, refusing adapters that promise fields outside
- * their category.
+ * Every category id declared by this version of finsys-core, in
+ * data-file order. The runtime equivalent of the old hardcoded union —
+ * derived from the single source of truth rather than maintained by
+ * hand. Treat order as unstable across versions.
  */
-type CanonicalFieldName = string;
+declare const ADAPTER_CATEGORY_IDS: ReadonlyArray<AdapterCategory>;
 /**
- * Look up a category schema by id. Throws if the id is unknown — this
- * is a programmer error (the type system should prevent it).
+ * Look up a category schema by id. Throws if the id is unknown.
  */
 declare function categorySchemaOf(id: AdapterCategory): CategorySchema;
 /**
@@ -640,9 +646,25 @@ declare function allCategories(): ReadonlyArray<CategorySchema>;
  * 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.
+ * producing category for rendering. O(1).
  */
 declare function categoryForField(field: CanonicalFieldName): AdapterCategory | null;
+/**
+ * Runtime membership check — is `id` a category declared by this
+ * version of finsys-core? Use this at trust boundaries (parsing a
+ * manifest, validating an API parameter) now that `AdapterCategory` is
+ * an open `string` and the compiler can no longer reject unknown ids.
+ */
+declare function isAdapterCategory(id: string): boolean;
+/**
+ * Assert membership: returns `id` if it names a declared category,
+ * throws otherwise. Note this is a RUNTIME guard only — `AdapterCategory`
+ * is an open `string`, so there is no type-level narrowing to apply.
+ * The companion to `isAdapterCategory` for call sites that want a hard
+ * failure (e.g. the host rejecting a manifest whose category isn't in
+ * this finsys-core version's catalogue).
+ */
+declare function assertAdapterCategory(id: string): AdapterCategory;
 
 /**
  * Source Adapter contract — the framework for ingesting unstructured
@@ -1198,4 +1220,4 @@ interface FieldMapEntry {
     readonly transform?: "identity" | "pct_to_ratio01" | "to_boolean" | "to_integer";
 }
 
-export { 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, buildFileFieldTables, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, 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, 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

@@ -571,16 +571,28 @@ interface ExtractionStatusResult {
 declare function resolveExtractionStatus(ihsRecord: Record<string, unknown>, jobRecords?: ExtractionJobRecord[]): ExtractionStatusResult;
 
 /**
- * Generic categories declared in this package. The set is union-typed
- * so consumers get TypeScript autocomplete (`'telco-carrier' |
- * 'payment-network' | ...`) and a compile-time error if they reference
- * a category that doesn't exist.
+ * Adapter category identifier.
  *
- * NB: adding a new category is a finsys-core minor version bump.
- * Vendor adapters can ship freely (deployment-time, no core change)
- * but the CATEGORY they implement must exist here.
+ * Open `string` type (SYS-2500). The authoritative set lives in the
+ * runtime registry built from `data/adapter-categories.json`; there is
+ * no compile-time union to enumerate. The trade-off vs. the old
+ * literal union is the loss of autocomplete + exhaustiveness on
+ * category ids — validate at boundaries with `isAdapterCategory()` /
+ * `assertAdapterCategory()` instead, and read the canonical set from
+ * `ADAPTER_CATEGORY_IDS` / `allCategories()`.
  */
-type AdapterCategory = "telco-carrier" | "payment-network" | "bank-statement";
+type AdapterCategory = string;
+/**
+ * Union of all canonical field names declared by any category. Loose-
+ * typed (string) because the set grows with each category-added minor;
+ * the runtime registry narrows against the data file.
+ *
+ * Adapter `produces` lists are typed as ReadonlyArray<CanonicalFieldName>
+ * — the host validates membership against the adapter's category at
+ * registration time, refusing adapters that promise fields outside
+ * their category.
+ */
+type CanonicalFieldName = string;
 /**
  * Per-field metadata for a canonical field declared by a category.
  * Frozen at module load — the data file is authoritative.
@@ -607,20 +619,14 @@ interface CategorySchema {
     readonly fields: ReadonlyArray<CanonicalFieldSpec>;
 }
 /**
- * Union of all canonical field names declared by any category in this
- * package. Loose-typed at compile time (string) because the actual
- * union grows with each category-added minor; runtime helpers below
- * narrow against the data.
- *
- * Adapter `produces` lists are typed as ReadonlyArray<CanonicalFieldName>
- * — the host validates membership against the adapter's category at
- * registration time, refusing adapters that promise fields outside
- * their category.
+ * Every category id declared by this version of finsys-core, in
+ * data-file order. The runtime equivalent of the old hardcoded union —
+ * derived from the single source of truth rather than maintained by
+ * hand. Treat order as unstable across versions.
  */
-type CanonicalFieldName = string;
+declare const ADAPTER_CATEGORY_IDS: ReadonlyArray<AdapterCategory>;
 /**
- * Look up a category schema by id. Throws if the id is unknown — this
- * is a programmer error (the type system should prevent it).
+ * Look up a category schema by id. Throws if the id is unknown.
  */
 declare function categorySchemaOf(id: AdapterCategory): CategorySchema;
 /**
@@ -640,9 +646,25 @@ declare function allCategories(): ReadonlyArray<CategorySchema>;
  * 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.
+ * producing category for rendering. O(1).
  */
 declare function categoryForField(field: CanonicalFieldName): AdapterCategory | null;
+/**
+ * Runtime membership check — is `id` a category declared by this
+ * version of finsys-core? Use this at trust boundaries (parsing a
+ * manifest, validating an API parameter) now that `AdapterCategory` is
+ * an open `string` and the compiler can no longer reject unknown ids.
+ */
+declare function isAdapterCategory(id: string): boolean;
+/**
+ * Assert membership: returns `id` if it names a declared category,
+ * throws otherwise. Note this is a RUNTIME guard only — `AdapterCategory`
+ * is an open `string`, so there is no type-level narrowing to apply.
+ * The companion to `isAdapterCategory` for call sites that want a hard
+ * failure (e.g. the host rejecting a manifest whose category isn't in
+ * this finsys-core version's catalogue).
+ */
+declare function assertAdapterCategory(id: string): AdapterCategory;
 
 /**
  * Source Adapter contract — the framework for ingesting unstructured
@@ -1198,4 +1220,4 @@ interface FieldMapEntry {
     readonly transform?: "identity" | "pct_to_ratio01" | "to_boolean" | "to_integer";
 }
 
-export { 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, buildFileFieldTables, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, 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, 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 };