@finsys/core 2.6.0 → 3.1.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
@@ -744,8 +766,26 @@ type CanonicalFieldValue = number | string | boolean | null;
  * host app's discovery mechanism (SYS-2444); the host app constructs
  * the adapter from its manifest + extract module, then registers it
  * against the registry by `id`.
+ *
+ * Type parameter `E` lets adapter authors declare the partner-specific
+ * extension shape on ApplicantIdentity. v2.7.0+ — defaults to `{}` so
+ * v2.6.0 adapters (which didn't have fetch and never read identity)
+ * 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> = {
+ *       async fetch(identity) {
+ *         identity.msisdn  // string  (typed via E)
+ *         identity.ic      // string  (core)
+ *       },
+ *       ...
+ *     }
+ *
+ * The generic flows from interface → method, so implementations
+ * don't have to redeclare it on fetch.
  */
-interface SourceAdapter {
+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
@@ -803,7 +843,129 @@ interface SourceAdapter {
      * expected-failure path.
      */
     extract(raw: RawPayload): Promise<AdapterExtraction[]>;
+    /**
+     * Optional partner-data fetch path. v2.7.0+ — adapters that own their
+     * partner-API integration declare this method; the host invokes it
+     * before extract() and passes the result through. Adapters that
+     * receive raw payload from elsewhere (e.g., bank-statement adapters
+     * reading FinXtract OCR output, or webhook-driven push ingest) omit
+     * fetch() entirely and the host treats raw as already-staged.
+     *
+     * The host builds `identity` from the IHS row (ic, fullName, etc.)
+     * plus any partner-specific fields the adapter declared via the
+     * manifest's `requiredIdentityFields`. If a required field is missing
+     * from the IHS, the host logs + skips this adapter for the run
+     * (no extract call, no canonical rows).
+     *
+     * Implementations should:
+     *   - Throw AdapterError('source_unavailable') ONLY on transient,
+     *     retryable upstream failures (timeouts, 5xx, rate limits). The
+     *     host runner is free to retry these; misclassifying a permanent
+     *     failure here will burn retry budget for nothing.
+     *   - Throw AdapterError('not_applicable') on permanent
+     *     no-relationship signals — 404 ("applicant unknown to partner"),
+     *     410, an explicit "not a subscriber" response. Communicates
+     *     'we asked and they said no' so the host records the run + skips
+     *     retry. This is the correct reason for most non-retryable
+     *     upstream conditions.
+     *   - Throw AdapterError('payload_invalid') if the partner returned
+     *     a malformed response (200 with garbage body, schema violation).
+     *   - Return a RawPayload that extract() will translate. The same
+     *     adapter's extract() is the only consumer; the host doesn't
+     *     inspect the shape.
+     *
+     * Strict additive — v2.6.0 read-only adapters that omit fetch()
+     * keep working without change.
+     *
+     * @example WRONG — recurses into the adapter method:
+     * ```ts
+     * const adapter: SourceAdapter = {
+     *   async fetch(identity) {
+     *     const res = await fetch(`/api/lookup/${identity.ic}`)  // infinite recursion
+     *     return res.json()
+     *   },
+     *   ...
+     * }
+     * ```
+     *
+     * @example RIGHT — explicit globalThis access:
+     * ```ts
+     * const adapter: SourceAdapter = {
+     *   async fetch(identity) {
+     *     const res = await globalThis.fetch(`/api/lookup/${identity.ic}`)
+     *     return res.json()
+     *   },
+     *   ...
+     * }
+     * ```
+     *
+     * Implementation note: this method is named `fetch` which shadows
+     * the global `fetch()` inside the method body — see the @example
+     * blocks above. The fake-* reference adapters in
+     * @finsys/adapter-toolkit use the explicit-globalThis pattern.
+     * Partner repos can also pin this with the lint rule
+     * `no-restricted-syntax`: `CallExpression[callee.name='fetch']`
+     * inside any method literal named `fetch`.
+     */
+    fetch?(identity: ApplicantIdentity<E>): Promise<RawPayload>;
 }
+/**
+ * Identity payload the host hands to fetch() so adapters can call
+ * partner APIs with the right per-applicant identifiers.
+ *
+ * The shape is an intersection of three pieces:
+ *   - Core fields (`ihsId`, `ic`, `fullName`) — always present, the
+ *     host populates them from the IHS row before invoking fetch().
+ *   - Partner extensions (`E`) — typed declaratively per adapter.
+ *     Defaults to `{}` (no extra typed fields) for adapters that only
+ *     need the core trio.
+ *   - Open index signature (`[k: string]: unknown`) — catches any
+ *     ad-hoc field a host might pass through; reads land on `unknown`
+ *     so partners must validate before use.
+ *
+ * Narrowing example (the ergonomics win this type is designed to deliver):
+ *
+ *     interface CelcomExt { msisdn: string; accountRef: string }
+ *
+ *     // declare adapter with the extension shape baked in:
+ *     const celcom: SourceAdapter<CelcomExt> = {
+ *       async fetch(identity) {
+ *         identity.ic        // string
+ *         identity.msisdn    // string  (NOT unknown — narrowed by E)
+ *         identity.foo       // unknown (falls through to index signature)
+ *         // ...
+ *       },
+ *       // ...
+ *     }
+ *
+ * The intersection puts narrowed members at the root, so partners get
+ * `identity.msisdn` (not `identity.extensions?.msisdn`) — matching the
+ * pattern the host actually uses (it spreads partner-required fields
+ * onto the root identity object, no nested 'extensions' envelope).
+ *
+ * Examples:
+ *   - Telco adapter declares `requiredIdentityFields: ['msisdn']`.
+ *     Identity arrives with msisdn populated; adapter calls partner API.
+ *     (Don't include 'ihsId', 'ic', or 'fullName' in
+ *     `requiredIdentityFields` — those are core fields. `ic` in
+ *     particular can be legitimately empty for non-MY scope, so
+ *     declaring it required would cause the host to skip every applicant.)
+ *   - Payment-network adapter declares `requiredIdentityFields:
+ *     ['businessRegistrationNumber']`. Adapter looks it up + calls.
+ *   - An adapter that only needs the IHS id declares no extra
+ *     fields; identity has just the core trio.
+ */
+type ApplicantIdentity<E extends Record<string, unknown> = {}> = {
+    /** Internal IHS id — always present. */
+    readonly ihsId: number;
+    /** Malaysian IC (or analogous national id). May be empty for non-MY scope. */
+    readonly ic: string;
+    /** Applicant full legal name. */
+    readonly fullName: string;
+} & E & {
+    /** Catch-all for ad-hoc reads (typed `unknown` — validate before use). */
+    readonly [key: string]: unknown;
+};
 /**
  * Typed error thrown by adapters on expected failure paths. The
  * `reason` discriminator lets the host app's adapter runner classify
@@ -984,6 +1146,28 @@ interface AdapterManifest {
      *     host imports it dynamically.
      */
     readonly implementation: DeclarativeImplementation | TypescriptImplementation;
+    /**
+     * v2.7.0 — partner-specific identity fields the adapter needs from
+     * the IHS row when fetch() is invoked. Strings name the keys that
+     * MUST be present on the ApplicantIdentity payload — the host
+     * validates per-applicant before calling fetch() and skips the
+     * adapter (with a logged warning) if any required field is missing.
+     *
+     * Examples:
+     *   - Telco adapter: `["ic", "msisdn"]`
+     *   - Payment-network adapter: `["businessRegistrationNumber"]`
+     *   - Bank-statement-from-OCR adapter: `[]` (no fetch — extract
+     *     reads from FinXtract output staged elsewhere)
+     *
+     * Omit entirely (or use empty array) for adapters that don't
+     * implement fetch() — the host then passes an empty raw payload
+     * to extract() and the adapter is responsible for sourcing data
+     * via some other path (FinXtract output, webhook ingest, etc.).
+     *
+     * Core identity fields (`ihsId`, `ic`, `fullName`) are always
+     * present — declaring them is harmless but unnecessary.
+     */
+    readonly requiredIdentityFields?: ReadonlyArray<string>;
     /**
      * Optional free-form notes — useful for partner-side documentation
      * (where to find the adapter's source, who owns it, what version of
@@ -1036,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, 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
@@ -744,8 +766,26 @@ type CanonicalFieldValue = number | string | boolean | null;
  * host app's discovery mechanism (SYS-2444); the host app constructs
  * the adapter from its manifest + extract module, then registers it
  * against the registry by `id`.
+ *
+ * Type parameter `E` lets adapter authors declare the partner-specific
+ * extension shape on ApplicantIdentity. v2.7.0+ — defaults to `{}` so
+ * v2.6.0 adapters (which didn't have fetch and never read identity)
+ * 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> = {
+ *       async fetch(identity) {
+ *         identity.msisdn  // string  (typed via E)
+ *         identity.ic      // string  (core)
+ *       },
+ *       ...
+ *     }
+ *
+ * The generic flows from interface → method, so implementations
+ * don't have to redeclare it on fetch.
  */
-interface SourceAdapter {
+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
@@ -803,7 +843,129 @@ interface SourceAdapter {
      * expected-failure path.
      */
     extract(raw: RawPayload): Promise<AdapterExtraction[]>;
+    /**
+     * Optional partner-data fetch path. v2.7.0+ — adapters that own their
+     * partner-API integration declare this method; the host invokes it
+     * before extract() and passes the result through. Adapters that
+     * receive raw payload from elsewhere (e.g., bank-statement adapters
+     * reading FinXtract OCR output, or webhook-driven push ingest) omit
+     * fetch() entirely and the host treats raw as already-staged.
+     *
+     * The host builds `identity` from the IHS row (ic, fullName, etc.)
+     * plus any partner-specific fields the adapter declared via the
+     * manifest's `requiredIdentityFields`. If a required field is missing
+     * from the IHS, the host logs + skips this adapter for the run
+     * (no extract call, no canonical rows).
+     *
+     * Implementations should:
+     *   - Throw AdapterError('source_unavailable') ONLY on transient,
+     *     retryable upstream failures (timeouts, 5xx, rate limits). The
+     *     host runner is free to retry these; misclassifying a permanent
+     *     failure here will burn retry budget for nothing.
+     *   - Throw AdapterError('not_applicable') on permanent
+     *     no-relationship signals — 404 ("applicant unknown to partner"),
+     *     410, an explicit "not a subscriber" response. Communicates
+     *     'we asked and they said no' so the host records the run + skips
+     *     retry. This is the correct reason for most non-retryable
+     *     upstream conditions.
+     *   - Throw AdapterError('payload_invalid') if the partner returned
+     *     a malformed response (200 with garbage body, schema violation).
+     *   - Return a RawPayload that extract() will translate. The same
+     *     adapter's extract() is the only consumer; the host doesn't
+     *     inspect the shape.
+     *
+     * Strict additive — v2.6.0 read-only adapters that omit fetch()
+     * keep working without change.
+     *
+     * @example WRONG — recurses into the adapter method:
+     * ```ts
+     * const adapter: SourceAdapter = {
+     *   async fetch(identity) {
+     *     const res = await fetch(`/api/lookup/${identity.ic}`)  // infinite recursion
+     *     return res.json()
+     *   },
+     *   ...
+     * }
+     * ```
+     *
+     * @example RIGHT — explicit globalThis access:
+     * ```ts
+     * const adapter: SourceAdapter = {
+     *   async fetch(identity) {
+     *     const res = await globalThis.fetch(`/api/lookup/${identity.ic}`)
+     *     return res.json()
+     *   },
+     *   ...
+     * }
+     * ```
+     *
+     * Implementation note: this method is named `fetch` which shadows
+     * the global `fetch()` inside the method body — see the @example
+     * blocks above. The fake-* reference adapters in
+     * @finsys/adapter-toolkit use the explicit-globalThis pattern.
+     * Partner repos can also pin this with the lint rule
+     * `no-restricted-syntax`: `CallExpression[callee.name='fetch']`
+     * inside any method literal named `fetch`.
+     */
+    fetch?(identity: ApplicantIdentity<E>): Promise<RawPayload>;
 }
+/**
+ * Identity payload the host hands to fetch() so adapters can call
+ * partner APIs with the right per-applicant identifiers.
+ *
+ * The shape is an intersection of three pieces:
+ *   - Core fields (`ihsId`, `ic`, `fullName`) — always present, the
+ *     host populates them from the IHS row before invoking fetch().
+ *   - Partner extensions (`E`) — typed declaratively per adapter.
+ *     Defaults to `{}` (no extra typed fields) for adapters that only
+ *     need the core trio.
+ *   - Open index signature (`[k: string]: unknown`) — catches any
+ *     ad-hoc field a host might pass through; reads land on `unknown`
+ *     so partners must validate before use.
+ *
+ * Narrowing example (the ergonomics win this type is designed to deliver):
+ *
+ *     interface CelcomExt { msisdn: string; accountRef: string }
+ *
+ *     // declare adapter with the extension shape baked in:
+ *     const celcom: SourceAdapter<CelcomExt> = {
+ *       async fetch(identity) {
+ *         identity.ic        // string
+ *         identity.msisdn    // string  (NOT unknown — narrowed by E)
+ *         identity.foo       // unknown (falls through to index signature)
+ *         // ...
+ *       },
+ *       // ...
+ *     }
+ *
+ * The intersection puts narrowed members at the root, so partners get
+ * `identity.msisdn` (not `identity.extensions?.msisdn`) — matching the
+ * pattern the host actually uses (it spreads partner-required fields
+ * onto the root identity object, no nested 'extensions' envelope).
+ *
+ * Examples:
+ *   - Telco adapter declares `requiredIdentityFields: ['msisdn']`.
+ *     Identity arrives with msisdn populated; adapter calls partner API.
+ *     (Don't include 'ihsId', 'ic', or 'fullName' in
+ *     `requiredIdentityFields` — those are core fields. `ic` in
+ *     particular can be legitimately empty for non-MY scope, so
+ *     declaring it required would cause the host to skip every applicant.)
+ *   - Payment-network adapter declares `requiredIdentityFields:
+ *     ['businessRegistrationNumber']`. Adapter looks it up + calls.
+ *   - An adapter that only needs the IHS id declares no extra
+ *     fields; identity has just the core trio.
+ */
+type ApplicantIdentity<E extends Record<string, unknown> = {}> = {
+    /** Internal IHS id — always present. */
+    readonly ihsId: number;
+    /** Malaysian IC (or analogous national id). May be empty for non-MY scope. */
+    readonly ic: string;
+    /** Applicant full legal name. */
+    readonly fullName: string;
+} & E & {
+    /** Catch-all for ad-hoc reads (typed `unknown` — validate before use). */
+    readonly [key: string]: unknown;
+};
 /**
  * Typed error thrown by adapters on expected failure paths. The
  * `reason` discriminator lets the host app's adapter runner classify
@@ -984,6 +1146,28 @@ interface AdapterManifest {
      *     host imports it dynamically.
      */
     readonly implementation: DeclarativeImplementation | TypescriptImplementation;
+    /**
+     * v2.7.0 — partner-specific identity fields the adapter needs from
+     * the IHS row when fetch() is invoked. Strings name the keys that
+     * MUST be present on the ApplicantIdentity payload — the host
+     * validates per-applicant before calling fetch() and skips the
+     * adapter (with a logged warning) if any required field is missing.
+     *
+     * Examples:
+     *   - Telco adapter: `["ic", "msisdn"]`
+     *   - Payment-network adapter: `["businessRegistrationNumber"]`
+     *   - Bank-statement-from-OCR adapter: `[]` (no fetch — extract
+     *     reads from FinXtract output staged elsewhere)
+     *
+     * Omit entirely (or use empty array) for adapters that don't
+     * implement fetch() — the host then passes an empty raw payload
+     * to extract() and the adapter is responsible for sourcing data
+     * via some other path (FinXtract output, webhook ingest, etc.).
+     *
+     * Core identity fields (`ihsId`, `ic`, `fullName`) are always
+     * present — declaring them is harmless but unnecessary.
+     */
+    readonly requiredIdentityFields?: ReadonlyArray<string>;
     /**
      * Optional free-form notes — useful for partner-side documentation
      * (where to find the adapter's source, who owns it, what version of
@@ -1036,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, 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 };