@finsys/core 4.3.0 → 4.5.0

package/dist/index.d.cts

@@ -974,6 +974,11 @@ type CanonicalFieldValues = Partial<Record<CanonicalFieldName, CanonicalFieldVal
  * MUST be stable across re-extractions so the storage layer can
  * replace-in-place rather than accumulating duplicates. Conventions:
  *   - For periodic data: encode the period (`'2026-Q1'`, `'2026-03'`)
+   * NOTE (SYS-3002): that is the multi-INSTANCE axis — one snapshot per
+   * instance. Do NOT encode a within-document period into the instance
+   * key; period-scoped values belong in `periods` (contractual 1-based
+   * positions). The two axes compose: instance = which document/snapshot,
+   * period = which declared position within it.
  *   - For per-line data: encode the line id (`'msisdn-60123456789'`,
  *     `'card-last4-1234'`)
  *   - For natively single-instance adapters: use the empty string `''`
@@ -1014,6 +1019,62 @@ interface AdapterExtraction {
      * matching IhsFieldProvenance.origin semantics).
      */
     readonly confidence?: Partial<Record<CanonicalFieldName, number | null>>;
+    /**
+     * SYS-3002: per-period value sets for adapters whose category
+     * declares a period axis (see `AdapterManifest.periods`). Each entry
+     * carries the values for ONE contractual position; `position` is
+     * 1-based — period1 is the first declared period, there is no
+     * period0.
+     *
+     * An instance carrying `periods` uses them for period-scoped fields,
+     * while the instance-level `values` above remains the home for
+     * period-less (singleton / instance-scoped) fields. Instances of
+     * single-period adapters (no `periods` on the manifest) omit this
+     * entirely and keep everything in `values` — the existing flat path
+     * is unchanged and remains the single-period path.
+     *
+     * Periods are scoped WITHIN this instance: this instance's period1
+     * and another instance's period1 are unrelated data points.
+     */
+    readonly periods?: ReadonlyArray<PeriodValues>;
+}
+/**
+ * SYS-3002: one period's value set within an AdapterExtraction
+ * instance. Identity is `position` — the 1-based index into the
+ * manifest's declared `periods` array — never the dates: declared
+ * positions may overlap, nest, vary in length, or be staggered (e.g.
+ * period1 = an annual table, periods 2–5 = the four quarters
+ * overlapping it), so dates cannot identify a period and recency
+ * ordering across positions is meaningless.
+ */
+interface PeriodValues {
+    /**
+     * 1-based contractual position into the manifest's `periods`
+     * declaration. MUST be >= 1 — period1 is the first declared period;
+     * there is no period0. This IS the period's identity.
+     */
+    readonly position: number;
+    /**
+     * ISO-8601 date the period starts — display/temporal metadata only,
+     * NEVER identity.
+     */
+    readonly start?: string;
+    /**
+     * ISO-8601 date the period ends — display/temporal metadata only,
+     * NEVER identity.
+     */
+    readonly end?: string;
+    /**
+     * The canonical field values for this period, same shape as the
+     * instance-level `values`.
+     */
+    readonly values: CanonicalFieldValues;
+    /**
+     * Optional per-field extraction confidence for this period's values,
+     * same semantics as the instance-level `confidence` (0..1 keyed by
+     * canonical field name; `null` marks a derived/computed value).
+     */
+    readonly confidence?: Partial<Record<CanonicalFieldName, number | null>>;
 }
 /**
  * Allowed value shapes for canonical fields. Per-field type narrowing
@@ -1418,8 +1479,15 @@ interface AdapterManifest {
      *     post-extraction. `produces` IS the override surface (a separate
      *     list could only duplicate or contradict it); the host's
      *     override endpoints gate on membership.
+     *   - `extraction-pipeline` — SYS-2998: declaration-only adapter whose
+     *     implementation IS the host application's own document-extraction
+     *     pipeline. No code is loaded and neither fetch() nor extract()
+     *     ever runs — the host's pipeline writes the canonical rows and
+     *     records the adapter runs itself; the manifest exists purely as
+     *     the declaration plane (produces, cardinality,
+     *     fieldAuthorizations) for data the host was already producing.
      */
-    readonly implementation: DeclarativeImplementation | TypescriptImplementation | FormIntakeImplementation | ManualOverrideImplementation;
+    readonly implementation: DeclarativeImplementation | TypescriptImplementation | FormIntakeImplementation | ManualOverrideImplementation | ExtractionPipelineImplementation;
     /**
      * SYS-2502: explicit instance cardinality.
      *
@@ -1494,6 +1562,41 @@ interface AdapterManifest {
      * not producing the field.
      */
     readonly fieldAuthorizations?: Readonly<Partial<Record<CanonicalFieldName, FieldAuthorization>>>;
+    /**
+     * SYS-3002: ordered period declarations — the contract for the
+     * period axis of this adapter's category.
+     *
+     * The period axis is ordered BY CONTRACT: `periodN` is a POSITIONAL
+     * identifier into this array. Numbering is 1-BASED — period1 is the
+     * FIRST declared period (array index 0); there is no period0.
+     * Position is the period's IDENTITY: two extractions' period1 values
+     * are comparable because they occupy the same contractual slot, not
+     * because their dates match.
+     *
+     * Declared positions may overlap, nest, vary in length, or be
+     * staggered — e.g. period1 = an annual table, periods 2–5 = the four
+     * quarters overlapping it. The declaration makes no statement about
+     * dates; each extraction-time period carries its own dated metadata
+     * (see `PeriodValues.start`/`end`) for display and temporal
+     * reasoning, never for identity. Periods are scoped WITHIN one
+     * instance: one document's period1 and another document's period1
+     * are unrelated data points.
+     *
+     * ABSENT means the single-period convention: the adapter's output
+     * has exactly one implicit period, and instance-level `values` is
+     * that period's value set. Single-period categories (bank
+     * statements, EPF, payslips) never need to declare. Non-empty when
+     * present — declaring zero periods would contradict the implicit
+     * single-period convention, so the schema requires at least one
+     * entry.
+     *
+     * The motivating consumer is financial statements — one document
+     * carries period1 (its current fiscal year) plus period2 (its prior
+     * comparative year) — but any implementation type may declare
+     * periods: the axis is a property of the contract, not of how the
+     * adapter is implemented.
+     */
+    readonly periods?: ReadonlyArray<PeriodDeclaration>;
     /**
      * Optional free-form notes — useful for partner-side documentation
      * (where to find the adapter's source, who owns it, what version of
@@ -1501,6 +1604,22 @@ interface AdapterManifest {
      */
     readonly notes?: string;
 }
+/**
+ * SYS-3002: one declared period on the adapter's period axis. See
+ * {@link AdapterManifest.periods} for the positional (1-based) identity
+ * semantics — the entry's position in the `periods` array IS the
+ * period's identity; the entry itself only labels the role.
+ */
+interface PeriodDeclaration {
+    /**
+     * Human role label for the position, e.g. "Current fiscal year",
+     * "Prior comparative year". Rendered in operator UIs; carries no
+     * identity semantics.
+     */
+    readonly name: string;
+    /** Optional longer description of what this position holds. */
+    readonly description?: string;
+}
 /**
  * SYS-2503: one field's authorization gate. See
  * {@link AdapterManifest.fieldAuthorizations} for semantics.
@@ -1574,6 +1693,26 @@ interface FormIntakeFieldMapEntry {
 interface ManualOverrideImplementation {
     readonly type: "manual-override";
 }
+/**
+ * SYS-2998: declaration-only implementation for adapters whose
+ * implementation IS the host application's own extraction pipeline
+ * (e.g. the FinXtract document-processing pipeline wrapped as
+ * "finxtract-bank-statement-v1"). The host's pipeline code performs the
+ * extraction, writes the canonical rows, and records the adapter runs —
+ * this manifest is how that pipeline's output becomes declared,
+ * provenance-carrying, per-field-gateable adapter data instead of
+ * hand-wired writes. No code, no fetch(), no extract(); like
+ * `manual-override`, the discriminator alone carries the meaning.
+ *
+ * Distinct from `form-intake` (whose runtime is the form submission
+ * handler and which needs a fieldMap) and from `manual-override` (which
+ * declares an override SURFACE): an extraction-pipeline manifest
+ * declares the pipeline's produced fields verbatim — `produces` is the
+ * contract, and the host validates the pipeline's writes against it.
+ */
+interface ExtractionPipelineImplementation {
+    readonly type: "extraction-pipeline";
+}
 interface FieldMapEntry {
     /**
      * JSONPath expression into the raw payload. E.g.
@@ -1601,4 +1740,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 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 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, 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 };

package/dist/index.d.ts

@@ -974,6 +974,11 @@ type CanonicalFieldValues = Partial<Record<CanonicalFieldName, CanonicalFieldVal
  * MUST be stable across re-extractions so the storage layer can
  * replace-in-place rather than accumulating duplicates. Conventions:
  *   - For periodic data: encode the period (`'2026-Q1'`, `'2026-03'`)
+   * NOTE (SYS-3002): that is the multi-INSTANCE axis — one snapshot per
+   * instance. Do NOT encode a within-document period into the instance
+   * key; period-scoped values belong in `periods` (contractual 1-based
+   * positions). The two axes compose: instance = which document/snapshot,
+   * period = which declared position within it.
  *   - For per-line data: encode the line id (`'msisdn-60123456789'`,
  *     `'card-last4-1234'`)
  *   - For natively single-instance adapters: use the empty string `''`
@@ -1014,6 +1019,62 @@ interface AdapterExtraction {
      * matching IhsFieldProvenance.origin semantics).
      */
     readonly confidence?: Partial<Record<CanonicalFieldName, number | null>>;
+    /**
+     * SYS-3002: per-period value sets for adapters whose category
+     * declares a period axis (see `AdapterManifest.periods`). Each entry
+     * carries the values for ONE contractual position; `position` is
+     * 1-based — period1 is the first declared period, there is no
+     * period0.
+     *
+     * An instance carrying `periods` uses them for period-scoped fields,
+     * while the instance-level `values` above remains the home for
+     * period-less (singleton / instance-scoped) fields. Instances of
+     * single-period adapters (no `periods` on the manifest) omit this
+     * entirely and keep everything in `values` — the existing flat path
+     * is unchanged and remains the single-period path.
+     *
+     * Periods are scoped WITHIN this instance: this instance's period1
+     * and another instance's period1 are unrelated data points.
+     */
+    readonly periods?: ReadonlyArray<PeriodValues>;
+}
+/**
+ * SYS-3002: one period's value set within an AdapterExtraction
+ * instance. Identity is `position` — the 1-based index into the
+ * manifest's declared `periods` array — never the dates: declared
+ * positions may overlap, nest, vary in length, or be staggered (e.g.
+ * period1 = an annual table, periods 2–5 = the four quarters
+ * overlapping it), so dates cannot identify a period and recency
+ * ordering across positions is meaningless.
+ */
+interface PeriodValues {
+    /**
+     * 1-based contractual position into the manifest's `periods`
+     * declaration. MUST be >= 1 — period1 is the first declared period;
+     * there is no period0. This IS the period's identity.
+     */
+    readonly position: number;
+    /**
+     * ISO-8601 date the period starts — display/temporal metadata only,
+     * NEVER identity.
+     */
+    readonly start?: string;
+    /**
+     * ISO-8601 date the period ends — display/temporal metadata only,
+     * NEVER identity.
+     */
+    readonly end?: string;
+    /**
+     * The canonical field values for this period, same shape as the
+     * instance-level `values`.
+     */
+    readonly values: CanonicalFieldValues;
+    /**
+     * Optional per-field extraction confidence for this period's values,
+     * same semantics as the instance-level `confidence` (0..1 keyed by
+     * canonical field name; `null` marks a derived/computed value).
+     */
+    readonly confidence?: Partial<Record<CanonicalFieldName, number | null>>;
 }
 /**
  * Allowed value shapes for canonical fields. Per-field type narrowing
@@ -1418,8 +1479,15 @@ interface AdapterManifest {
      *     post-extraction. `produces` IS the override surface (a separate
      *     list could only duplicate or contradict it); the host's
      *     override endpoints gate on membership.
+     *   - `extraction-pipeline` — SYS-2998: declaration-only adapter whose
+     *     implementation IS the host application's own document-extraction
+     *     pipeline. No code is loaded and neither fetch() nor extract()
+     *     ever runs — the host's pipeline writes the canonical rows and
+     *     records the adapter runs itself; the manifest exists purely as
+     *     the declaration plane (produces, cardinality,
+     *     fieldAuthorizations) for data the host was already producing.
      */
-    readonly implementation: DeclarativeImplementation | TypescriptImplementation | FormIntakeImplementation | ManualOverrideImplementation;
+    readonly implementation: DeclarativeImplementation | TypescriptImplementation | FormIntakeImplementation | ManualOverrideImplementation | ExtractionPipelineImplementation;
     /**
      * SYS-2502: explicit instance cardinality.
      *
@@ -1494,6 +1562,41 @@ interface AdapterManifest {
      * not producing the field.
      */
     readonly fieldAuthorizations?: Readonly<Partial<Record<CanonicalFieldName, FieldAuthorization>>>;
+    /**
+     * SYS-3002: ordered period declarations — the contract for the
+     * period axis of this adapter's category.
+     *
+     * The period axis is ordered BY CONTRACT: `periodN` is a POSITIONAL
+     * identifier into this array. Numbering is 1-BASED — period1 is the
+     * FIRST declared period (array index 0); there is no period0.
+     * Position is the period's IDENTITY: two extractions' period1 values
+     * are comparable because they occupy the same contractual slot, not
+     * because their dates match.
+     *
+     * Declared positions may overlap, nest, vary in length, or be
+     * staggered — e.g. period1 = an annual table, periods 2–5 = the four
+     * quarters overlapping it. The declaration makes no statement about
+     * dates; each extraction-time period carries its own dated metadata
+     * (see `PeriodValues.start`/`end`) for display and temporal
+     * reasoning, never for identity. Periods are scoped WITHIN one
+     * instance: one document's period1 and another document's period1
+     * are unrelated data points.
+     *
+     * ABSENT means the single-period convention: the adapter's output
+     * has exactly one implicit period, and instance-level `values` is
+     * that period's value set. Single-period categories (bank
+     * statements, EPF, payslips) never need to declare. Non-empty when
+     * present — declaring zero periods would contradict the implicit
+     * single-period convention, so the schema requires at least one
+     * entry.
+     *
+     * The motivating consumer is financial statements — one document
+     * carries period1 (its current fiscal year) plus period2 (its prior
+     * comparative year) — but any implementation type may declare
+     * periods: the axis is a property of the contract, not of how the
+     * adapter is implemented.
+     */
+    readonly periods?: ReadonlyArray<PeriodDeclaration>;
     /**
      * Optional free-form notes — useful for partner-side documentation
      * (where to find the adapter's source, who owns it, what version of
@@ -1501,6 +1604,22 @@ interface AdapterManifest {
      */
     readonly notes?: string;
 }
+/**
+ * SYS-3002: one declared period on the adapter's period axis. See
+ * {@link AdapterManifest.periods} for the positional (1-based) identity
+ * semantics — the entry's position in the `periods` array IS the
+ * period's identity; the entry itself only labels the role.
+ */
+interface PeriodDeclaration {
+    /**
+     * Human role label for the position, e.g. "Current fiscal year",
+     * "Prior comparative year". Rendered in operator UIs; carries no
+     * identity semantics.
+     */
+    readonly name: string;
+    /** Optional longer description of what this position holds. */
+    readonly description?: string;
+}
 /**
  * SYS-2503: one field's authorization gate. See
  * {@link AdapterManifest.fieldAuthorizations} for semantics.
@@ -1574,6 +1693,26 @@ interface FormIntakeFieldMapEntry {
 interface ManualOverrideImplementation {
     readonly type: "manual-override";
 }
+/**
+ * SYS-2998: declaration-only implementation for adapters whose
+ * implementation IS the host application's own extraction pipeline
+ * (e.g. the FinXtract document-processing pipeline wrapped as
+ * "finxtract-bank-statement-v1"). The host's pipeline code performs the
+ * extraction, writes the canonical rows, and records the adapter runs —
+ * this manifest is how that pipeline's output becomes declared,
+ * provenance-carrying, per-field-gateable adapter data instead of
+ * hand-wired writes. No code, no fetch(), no extract(); like
+ * `manual-override`, the discriminator alone carries the meaning.
+ *
+ * Distinct from `form-intake` (whose runtime is the form submission
+ * handler and which needs a fieldMap) and from `manual-override` (which
+ * declares an override SURFACE): an extraction-pipeline manifest
+ * declares the pipeline's produced fields verbatim — `produces` is the
+ * contract, and the host validates the pipeline's writes against it.
+ */
+interface ExtractionPipelineImplementation {
+    readonly type: "extraction-pipeline";
+}
 interface FieldMapEntry {
     /**
      * JSONPath expression into the raw payload. E.g.
@@ -1601,4 +1740,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 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 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, 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 };

package/dist/index.js

@@ -10596,6 +10596,260 @@ var adapter_categories_default = {
           description: "Agreement between the inferred home anchor and the applicant's registered residential address. 1 = same premises, 0 = different state (summary instance only)."
         }
       ]
+    },
+    {
+      id: "ic",
+      displayName: "Identity Document (IC / Passport)",
+      description: "Identity fields extracted from a Malaysian IC (MyKad) or passport document. Produced by the host's document-extraction pipeline; one instance per identity document.",
+      canonicalTable: "ihs_alt_data_ic",
+      fields: [
+        {
+          name: "icName",
+          type: "string",
+          description: "Full name as printed on the identity document."
+        },
+        {
+          name: "icNumber",
+          type: "string",
+          description: "IC (MyKad) number, or passport number for passport documents."
+        },
+        {
+          name: "icAddress",
+          type: "string",
+          description: "Registered address as printed on the document."
+        },
+        {
+          name: "icGender",
+          type: "string",
+          description: "Gender as stated on the document."
+        },
+        {
+          name: "icReligion",
+          type: "string",
+          description: "Religion as stated on the document (MyKad-only; absent on passports)."
+        },
+        {
+          name: "icDateOfBirth",
+          type: "string",
+          description: "Date of birth as stated on the document."
+        },
+        {
+          name: "icPlaceOfBirth",
+          type: "string",
+          description: "Place of birth as stated on the document."
+        },
+        {
+          name: "icNationality",
+          type: "string",
+          description: "Nationality as stated on the document."
+        },
+        {
+          name: "icRace",
+          type: "string",
+          description: "Race as stated on the document (MyKad-only; absent on passports)."
+        }
+      ]
+    },
+    {
+      id: "finxtract-bank-statement",
+      displayName: "Bank Statement (Document Extraction)",
+      description: "Fields extracted from an uploaded bank-statement document by the host's extraction pipeline. One instance per statement document; each statement covers a single month. Distinct from the partner-API 'bank-statement' category: same real-world domain, different source and different canonical vocabulary.",
+      canonicalTable: "ihsbankstatement",
+      fields: [
+        {
+          name: "bankName",
+          type: "string",
+          description: "Issuing bank's name as printed on the statement."
+        },
+        {
+          name: "accountHolderName",
+          type: "string",
+          description: "Account holder's name as printed on the statement."
+        },
+        {
+          name: "accountNumber",
+          type: "string",
+          description: "Bank account number as printed on the statement."
+        },
+        {
+          name: "statementDate",
+          type: "string",
+          description: "Statement date, normalized to ISO YYYY-MM-DD."
+        },
+        {
+          name: "openingBalance",
+          type: "number",
+          unit: "MYR",
+          description: "Opening balance for the statement period."
+        },
+        {
+          name: "bankBalance",
+          type: "number",
+          unit: "MYR",
+          description: "Closing balance for the statement period."
+        },
+        {
+          name: "totalCredits",
+          type: "number",
+          unit: "MYR",
+          description: "Sum of credit transactions in the statement period."
+        },
+        {
+          name: "totalDebits",
+          type: "number",
+          unit: "MYR",
+          description: "Sum of debit transactions in the statement period."
+        }
+      ]
+    },
+    {
+      id: "finxtract-epf",
+      displayName: "EPF Statement (Document Extraction)",
+      description: "Fields extracted from an uploaded EPF (KWSP) statement document by the host's extraction pipeline. One instance per statement document. Field names carry the 'epf' prefix \u2014 the same prefix-namespaced vocabulary the host's flat read path and the eval engine already use, which also keeps canonical names globally unique across categories.",
+      canonicalTable: "ihsepfstatement",
+      fields: [
+        {
+          name: "epfAccountHolderName",
+          type: "string",
+          description: "Member's name as printed on the statement."
+        },
+        {
+          name: "epfAccountHolderAddress",
+          type: "string",
+          description: "Member's address as printed on the statement."
+        },
+        {
+          name: "epfStatementYear",
+          type: "string",
+          description: "The contribution year the statement covers."
+        },
+        {
+          name: "epfKwspMemberNumber",
+          type: "string",
+          description: "KWSP membership number."
+        },
+        {
+          name: "epfIcNumber",
+          type: "string",
+          description: "Member's IC number as printed on the statement."
+        },
+        {
+          name: "epfEmployerNumber",
+          type: "string",
+          description: "Employer's KWSP reference number."
+        },
+        {
+          name: "epfDateOfStatement",
+          type: "string",
+          description: "Statement issue date, normalized to ISO YYYY-MM-DD."
+        },
+        {
+          name: "epfTotalContribution",
+          type: "number",
+          unit: "MYR",
+          description: "Cumulative EPF balance as at the statement date."
+        },
+        {
+          name: "epfTotalCurrentContribution",
+          type: "number",
+          unit: "MYR",
+          description: "Contributions made within the statement's coverage year."
+        }
+      ]
+    },
+    {
+      id: "finxtract-payslip",
+      displayName: "Payslip (Document Extraction)",
+      description: "Fields extracted from an uploaded payslip document by the host's extraction pipeline. One instance per payslip document; each payslip covers a single pay period. Field names carry the 'payslip' prefix \u2014 the same prefix-namespaced vocabulary the host's flat read path and the eval engine already use, which also keeps canonical names globally unique across categories.",
+      canonicalTable: "ihspayslip",
+      fields: [
+        {
+          name: "payslipEmployerName",
+          type: "string",
+          description: "Employer's name as printed on the payslip."
+        },
+        {
+          name: "payslipEmployeeName",
+          type: "string",
+          description: "Employee's name as printed on the payslip."
+        },
+        {
+          name: "payslipPayPeriod",
+          type: "string",
+          description: "The pay period the payslip covers, as printed."
+        },
+        {
+          name: "payslipPayDate",
+          type: "string",
+          description: "Payment date, as printed."
+        },
+        {
+          name: "payslipBasicPay",
+          type: "number",
+          unit: "MYR",
+          description: "Basic salary for the period."
+        },
+        {
+          name: "payslipGrossPay",
+          type: "number",
+          unit: "MYR",
+          description: "Gross pay for the period."
+        },
+        {
+          name: "payslipFixedAllowances",
+          type: "number",
+          unit: "MYR",
+          description: "Fixed allowances for the period."
+        },
+        {
+          name: "payslipVariableIncome",
+          type: "number",
+          unit: "MYR",
+          description: "Variable income (overtime, commission, bonus) for the period."
+        },
+        {
+          name: "payslipDeduction",
+          type: "number",
+          unit: "MYR",
+          description: "Total statutory deductions for the period."
+        },
+        {
+          name: "payslipOtherDeduction",
+          type: "number",
+          unit: "MYR",
+          description: "Other (non-statutory) deductions for the period."
+        },
+        {
+          name: "payslipEmployeeEpfContribution",
+          type: "number",
+          unit: "MYR",
+          description: "Employee EPF contribution for the period."
+        },
+        {
+          name: "payslipEmployeeSocsoContribution",
+          type: "number",
+          unit: "MYR",
+          description: "Employee SOCSO contribution for the period."
+        },
+        {
+          name: "payslipEmployeeEisContribution",
+          type: "number",
+          unit: "MYR",
+          description: "Employee EIS contribution for the period."
+        },
+        {
+          name: "payslipEmployeeTax",
+          type: "number",
+          unit: "MYR",
+          description: "Employee income-tax (PCB) deduction for the period."
+        },
+        {
+          name: "payslipNetPay",
+          type: "number",
+          unit: "MYR",
+          description: "Net pay for the period."
+        }
+      ]
     }
   ]
 };
@@ -10634,9 +10888,9 @@ function buildCategoryRegistry(raw) {
     if (typeof cat.description !== "string" || cat.description.length === 0) {
       throw new Error(`adapter category data: ${where} needs a non-empty description`);
     }
-    if (typeof cat.canonicalTable !== "string" || !/^ihs_alt_data_/.test(cat.canonicalTable)) {
+    if (typeof cat.canonicalTable !== "string" || !/^ihs[a-z0-9_]*$/.test(cat.canonicalTable)) {
       throw new Error(
-        `adapter category data: ${where} canonicalTable must start with "ihs_alt_data_" (got "${cat.canonicalTable}")`
+        `adapter category data: ${where} canonicalTable must be an "ihs"-prefixed table identifier (got "${cat.canonicalTable}")`
       );
     }
     if (tables.has(cat.canonicalTable)) {