@finsys/core 4.0.0 → 4.2.0

package/dist/index.d.cts

@@ -416,16 +416,34 @@ declare enum FileFieldTableType {
  *   observedAt  — ISO wall-clock of the extraction run
  *   sourceRunId — the extraction run/job id that wrote it
  *   origin      — "extracted" (a real {value,confidence} leaf) vs "derived"
- *                 (computed / no-confidence path). A "derived" field must render
- *                 as "no confidence available", never a fabricated low score.
+ *                 (computed / no-confidence path) vs "manual" (SYS-2806, a
+ *                 lender-entered correction, committed once its edit overlay
+ *                 is approved). A "derived" field must render as "no
+ *                 confidence available", never a fabricated low score; a
+ *                 "manual" field must render as an edit indicator, not a
+ *                 confidence dot — confidence is always null for it too.
  */
+/**
+ * Canonical origin values, single source of truth (Gemini-review finding:
+ * avoids duplicating the literal strings between the type and the runtime
+ * guard) -- mirrors the IhsStatus/IHS_VALID_STATUSES pattern in
+ * ihs-status.ts.
+ */
+declare const IHS_FIELD_ORIGINS: readonly ["extracted", "derived", "manual"];
+type IhsFieldOrigin = (typeof IHS_FIELD_ORIGINS)[number];
 interface IhsFieldProvenance {
     source: string;
     confidence: number | null;
     observedAt: string;
     sourceRunId: string | null;
-    origin: 'extracted' | 'derived';
+    origin: IhsFieldOrigin;
 }
+/**
+ * Type guard: narrows an unknown value to `IhsFieldOrigin` iff it is one of
+ * the three canonical origin strings. `origin` was previously validated
+ * only by the TS union — this is the first runtime check.
+ */
+declare function isValidIhsFieldOrigin(origin: unknown): origin is IhsFieldOrigin;
 interface FileFieldTableItem {
     displayName: string;
     timePeriods: string[];
@@ -449,6 +467,22 @@ interface FileFieldTableData {
     items: FileFieldTableItem[];
     hasData: boolean;
 }
+/**
+ * One sibling-table row as finsys-api's `docInstanceStorageService` writes
+ * it (SYS-2842) -- the unbounded counterpart to a T{n}-suffixed wide-table
+ * slot. `instanceKey` is the real, collision-free per-document key;
+ * `sourceLabel` is a human label when the doc type has one (e.g. a bank
+ * name); `timePeriod` is the same descriptive value column the legacy
+ * T{n} scheme used, kept for period-labeling and legacy provenance lookup
+ * (SYS-2886 Phase 5) -- no longer the row's key. Metric fields are the
+ * category's own base (unsuffixed) column names.
+ */
+interface InstanceRow {
+    instanceKey: string;
+    sourceLabel?: string | null;
+    timePeriod?: string | null;
+    [metricKey: string]: unknown;
+}
 /**
  * Per-document File metadata attached by finsys-api `getIhsDetailsById` as the
  * `documentMetadata` sibling map (SYS-2765), keyed by the document's raw stored
@@ -530,6 +564,31 @@ declare function groupColumnsByTimePeriod(columnNames: string[]): Record<string,
 declare function groupFieldsByPattern(fields: FieldData[]): Record<string, FieldData[]>;
 declare function getGroupDisplayNames(): Record<string, string>;
 declare function buildFileFieldTables(ihsData: Record<string, unknown>, fieldProvenance?: Record<string, IhsFieldProvenance>): Record<string, FileFieldTableData>;
+/**
+ * Groups instance rows by base metric name -- the unbounded analog of
+ * groupColumnsByTimePeriod. `baseColumnNames` is the category's base
+ * (unsuffixed) field list; each returned group maps instance column
+ * label -> that metric's value on that row. Labels are disambiguated
+ * (see instanceColumnLabels) so two rows can never collide into the
+ * same key.
+ */
+declare function groupColumnsByInstance(baseColumnNames: string[], instanceRows: InstanceRow[]): Record<string, Record<string, unknown>>;
+/**
+ * Explicit base-column declaration for a category with NO catalog `file`
+ * spec -- e.g. invoice (SYS-2842 Phase 3), which was deliberately never
+ * registered in form-field-base-specs.json because getDocumentTypeGroups()
+ * is shared with resolveExtractionStatus, which assumes a category's wide-
+ * table columns exist to check "is this populated" against -- invoice has
+ * none (sibling-table only, no wideTableMirror). Registering it there would
+ * silently break resolveExtractionStatus's invoice status reporting. This
+ * override lets a category be instance-rendered without entering that
+ * shared registry at all.
+ */
+interface CategorySpec {
+    displayName: string;
+    baseColumnNames: string[];
+}
+declare function buildFileFieldTablesFromInstances(instancesByCategory?: Record<string, InstanceRow[]>, fieldProvenance?: Record<string, IhsFieldProvenance>, categoryOverrides?: Record<string, CategorySpec>): Record<string, FileFieldTableData>;
 /** IHS doc-field key → human label (the fields that become document sections). */
 declare function getDocDisplayNames(): Record<string, string>;
 /** Doc types eligible for extraction (re-extract / view-JSON). */
@@ -652,11 +711,19 @@ declare function assertDocumentType(id: string): string;
  * Lender rejection is not represented by a distinct status: when a lender
  * rejects an application, finsys-api transitions the record back to
  * `APPLICATION_FINALIZED` from `LENDER_EVALUATION`.
+ *
+ * `EditingApplication` (SYS-2806) is a lender-scoped detour off
+ * `LenderEvaluation` for manually editing extracted field values — not
+ * reachable from `ApplicationFinalized`. A lender toggles into it and back
+ * out to `LenderEvaluation`; it never appears on a record no lender has
+ * claimed. See finsys-api's `updateIhsStatusByLender` for the transition
+ * guard.
  */
 declare enum IhsStatus {
     CreatingApplication = "CREATING_APPLICATION",
     ApplicationFinalized = "APPLICATION_FINALIZED",
     LenderEvaluation = "LENDER_EVALUATION",
+    EditingApplication = "EDITING_APPLICATION",
     Approved = "APPROVED",
     LouDelivered = "LOU_DELIVERED",
     AwaitingDisbursement = "AWAITING_DISBURSEMENT",
@@ -923,6 +990,30 @@ interface AdapterExtraction {
      * The canonical field values for this instance.
      */
     readonly values: CanonicalFieldValues;
+    /**
+     * SYS-2502: when this instance's data was OBSERVED at the source
+     * (ISO-8601) — the statement's own date, the partner snapshot's
+     * timestamp — as distinct from when the adapter RAN. Optional for
+     * backward compatibility with already-shipped adapters (the host
+     * falls back to the run's ranAt when absent, exactly the inference
+     * it always did), but new adapters should treat it as required:
+     * ranAt-inference conflates "when we fetched" with "when it was
+     * true", which corrupts recency ordering for backfilled or delayed
+     * data. Expected to become mandatory at the next major version.
+     */
+    readonly observedAt?: string;
+    /**
+     * SYS-2502 (prototyped in finsys-api under SYS-2977): optional
+     * per-field extraction confidence, 0..1, keyed by canonical field
+     * name. This is the provenance slot SYS-2819 identified as the
+     * missing precondition for FinXtract-as-adapter — probabilistic
+     * extractors (OCR/LLM) carry real per-field confidence; partner-API
+     * adapters (a telco returning a number) simply omit it. `null` marks
+     * a field whose value is derived/computed rather than directly
+     * extracted (renders as "no confidence" rather than low confidence,
+     * matching IhsFieldProvenance.origin semantics).
+     */
+    readonly confidence?: Partial<Record<CanonicalFieldName, number | null>>;
 }
 /**
  * Allowed value shapes for canonical fields. Per-field type narrowing
@@ -1316,8 +1407,47 @@ interface AdapterManifest {
      *     code is loaded.
      *   - `typescript` — TS/JS adapter; `entryPoint` is required, the
      *     host imports it dynamically.
+     *   - `form-intake` — SYS-2501: data-only adapter declaring
+     *     form-field-id → canonical-field mappings. No code is loaded and
+     *     no fetch()/extract() ever runs; the host's form submission
+     *     handler IS the runtime, and this manifest is how a
+     *     borrower-entered scalar becomes a canonical, provenance-carrying
+     *     field instead of a hand-wired column write.
+     *   - `manual-override` — SYS-2501: data-only adapter declaring that
+     *     this category's fields may be operator-overridden
+     *     post-extraction. `produces` IS the override surface (a separate
+     *     list could only duplicate or contradict it); the host's
+     *     override endpoints gate on membership.
+     */
+    readonly implementation: DeclarativeImplementation | TypescriptImplementation | FormIntakeImplementation | ManualOverrideImplementation;
+    /**
+     * SYS-2502: explicit instance cardinality.
+     *
+     *   - `single` — at most one instance per applicant; extract() returns
+     *     one AdapterExtraction with `instanceKey: ""`.
+     *   - `multi` — unbounded instances per applicant, each with a stable,
+     *     non-empty instanceKey.
+     *
+     * OPTIONAL for backward compatibility: manifests written before this
+     * field existed rely on the original implicit convention
+     * (instanceKey `""` → single, non-empty → multi), and the host infers
+     * accordingly when the field is absent. New manifests should declare
+     * it — an explicit declaration lets the host REJECT a mismatched
+     * extraction (a multi-keyed instance from a declared-single adapter,
+     * or vice versa) at persistence time instead of silently storing it.
+     */
+    readonly cardinality?: "single" | "multi";
+    /**
+     * SYS-2502: per-applicant singleton fields on a multi-instance
+     * category — fields whose value describes the APPLICANT (one value
+     * regardless of how many instances exist) rather than the instance,
+     * e.g. accountHolderName on bank statements. Every entry MUST also
+     * appear in `produces` (host validates at registration, same as
+     * `produces` ⊆ category fields). Only meaningful when cardinality is
+     * `multi`; the host treats a singleton field's value as shared across
+     * the instance set.
      */
-    readonly implementation: DeclarativeImplementation | TypescriptImplementation;
+    readonly singletonFields?: ReadonlyArray<CanonicalFieldName>;
     /**
      * v2.7.0 — partner-specific identity fields the adapter needs from
      * the IHS row when fetch() is invoked. Strings name the keys that
@@ -1365,6 +1495,45 @@ interface TypescriptImplementation {
      */
     readonly entryPoint: string;
 }
+/**
+ * SYS-2501: data-only implementation for borrower/operator form intake.
+ * The manifest declares which form fields feed which canonical fields;
+ * the host's form submission handler applies the mapping — no adapter
+ * code exists to load, and neither fetch() nor extract() ever runs.
+ */
+interface FormIntakeImplementation {
+    readonly type: "form-intake";
+    /**
+     * form-field-id → canonical-field mappings. `formFieldId` is the form
+     * spec's field name (the same identifier UnifiedFormConfig fields
+     * carry); `canonical` MUST be declared by the adapter's category —
+     * host validates at registration, exactly like declarative fieldMap
+     * entries. Values arrive already typed from the form layer, so there
+     * is deliberately no transform slot here: a form field needing value
+     * transformation is a form-spec concern, not an adapter one.
+     */
+    readonly fieldMap: ReadonlyArray<FormIntakeFieldMapEntry>;
+}
+interface FormIntakeFieldMapEntry {
+    /** The form spec's field name this mapping consumes. */
+    readonly formFieldId: string;
+    /**
+     * Canonical field name this maps to. MUST be declared by the
+     * adapter's category. Host validates at registration.
+     */
+    readonly canonical: CanonicalFieldName;
+}
+/**
+ * SYS-2501: data-only implementation declaring that the adapter's
+ * `produces` list is operator-overridable post-extraction. The manifest
+ * gates the override surface; the host's override endpoints check
+ * membership in `produces` before accepting a manual value. No code, no
+ * fetch(), no extract() — the discriminator alone carries the meaning,
+ * so this shape is intentionally empty beyond `type`.
+ */
+interface ManualOverrideImplementation {
+    readonly type: "manual-override";
+}
 interface FieldMapEntry {
     /**
      * JSONPath expression into the raw payload. E.g.
@@ -1392,4 +1561,4 @@ interface FieldMapEntry {
     readonly transform?: "identity" | "pct_to_ratio01" | "to_boolean" | "to_integer";
 }
 
-export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DocumentFileMetadata, type DocumentRow, type DocumentRowCapabilities, type DocumentTypeGroup, type DropdownOption, type EditorValidator, type ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceValue, type PageConfig, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TaggedFieldData, type TimePeriodUnit, type TypescriptImplementation, type UnifiedFormConfig, type Validator, type WireFormat, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, assertDocumentType, buildDocumentRows, buildFileFieldTables, 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, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isDocumentType, isFailureIhsStatus, isTerminalIhsStatus, 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 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, 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 };

package/dist/index.d.ts

@@ -416,16 +416,34 @@ declare enum FileFieldTableType {
  *   observedAt  — ISO wall-clock of the extraction run
  *   sourceRunId — the extraction run/job id that wrote it
  *   origin      — "extracted" (a real {value,confidence} leaf) vs "derived"
- *                 (computed / no-confidence path). A "derived" field must render
- *                 as "no confidence available", never a fabricated low score.
+ *                 (computed / no-confidence path) vs "manual" (SYS-2806, a
+ *                 lender-entered correction, committed once its edit overlay
+ *                 is approved). A "derived" field must render as "no
+ *                 confidence available", never a fabricated low score; a
+ *                 "manual" field must render as an edit indicator, not a
+ *                 confidence dot — confidence is always null for it too.
  */
+/**
+ * Canonical origin values, single source of truth (Gemini-review finding:
+ * avoids duplicating the literal strings between the type and the runtime
+ * guard) -- mirrors the IhsStatus/IHS_VALID_STATUSES pattern in
+ * ihs-status.ts.
+ */
+declare const IHS_FIELD_ORIGINS: readonly ["extracted", "derived", "manual"];
+type IhsFieldOrigin = (typeof IHS_FIELD_ORIGINS)[number];
 interface IhsFieldProvenance {
     source: string;
     confidence: number | null;
     observedAt: string;
     sourceRunId: string | null;
-    origin: 'extracted' | 'derived';
+    origin: IhsFieldOrigin;
 }
+/**
+ * Type guard: narrows an unknown value to `IhsFieldOrigin` iff it is one of
+ * the three canonical origin strings. `origin` was previously validated
+ * only by the TS union — this is the first runtime check.
+ */
+declare function isValidIhsFieldOrigin(origin: unknown): origin is IhsFieldOrigin;
 interface FileFieldTableItem {
     displayName: string;
     timePeriods: string[];
@@ -449,6 +467,22 @@ interface FileFieldTableData {
     items: FileFieldTableItem[];
     hasData: boolean;
 }
+/**
+ * One sibling-table row as finsys-api's `docInstanceStorageService` writes
+ * it (SYS-2842) -- the unbounded counterpart to a T{n}-suffixed wide-table
+ * slot. `instanceKey` is the real, collision-free per-document key;
+ * `sourceLabel` is a human label when the doc type has one (e.g. a bank
+ * name); `timePeriod` is the same descriptive value column the legacy
+ * T{n} scheme used, kept for period-labeling and legacy provenance lookup
+ * (SYS-2886 Phase 5) -- no longer the row's key. Metric fields are the
+ * category's own base (unsuffixed) column names.
+ */
+interface InstanceRow {
+    instanceKey: string;
+    sourceLabel?: string | null;
+    timePeriod?: string | null;
+    [metricKey: string]: unknown;
+}
 /**
  * Per-document File metadata attached by finsys-api `getIhsDetailsById` as the
  * `documentMetadata` sibling map (SYS-2765), keyed by the document's raw stored
@@ -530,6 +564,31 @@ declare function groupColumnsByTimePeriod(columnNames: string[]): Record<string,
 declare function groupFieldsByPattern(fields: FieldData[]): Record<string, FieldData[]>;
 declare function getGroupDisplayNames(): Record<string, string>;
 declare function buildFileFieldTables(ihsData: Record<string, unknown>, fieldProvenance?: Record<string, IhsFieldProvenance>): Record<string, FileFieldTableData>;
+/**
+ * Groups instance rows by base metric name -- the unbounded analog of
+ * groupColumnsByTimePeriod. `baseColumnNames` is the category's base
+ * (unsuffixed) field list; each returned group maps instance column
+ * label -> that metric's value on that row. Labels are disambiguated
+ * (see instanceColumnLabels) so two rows can never collide into the
+ * same key.
+ */
+declare function groupColumnsByInstance(baseColumnNames: string[], instanceRows: InstanceRow[]): Record<string, Record<string, unknown>>;
+/**
+ * Explicit base-column declaration for a category with NO catalog `file`
+ * spec -- e.g. invoice (SYS-2842 Phase 3), which was deliberately never
+ * registered in form-field-base-specs.json because getDocumentTypeGroups()
+ * is shared with resolveExtractionStatus, which assumes a category's wide-
+ * table columns exist to check "is this populated" against -- invoice has
+ * none (sibling-table only, no wideTableMirror). Registering it there would
+ * silently break resolveExtractionStatus's invoice status reporting. This
+ * override lets a category be instance-rendered without entering that
+ * shared registry at all.
+ */
+interface CategorySpec {
+    displayName: string;
+    baseColumnNames: string[];
+}
+declare function buildFileFieldTablesFromInstances(instancesByCategory?: Record<string, InstanceRow[]>, fieldProvenance?: Record<string, IhsFieldProvenance>, categoryOverrides?: Record<string, CategorySpec>): Record<string, FileFieldTableData>;
 /** IHS doc-field key → human label (the fields that become document sections). */
 declare function getDocDisplayNames(): Record<string, string>;
 /** Doc types eligible for extraction (re-extract / view-JSON). */
@@ -652,11 +711,19 @@ declare function assertDocumentType(id: string): string;
  * Lender rejection is not represented by a distinct status: when a lender
  * rejects an application, finsys-api transitions the record back to
  * `APPLICATION_FINALIZED` from `LENDER_EVALUATION`.
+ *
+ * `EditingApplication` (SYS-2806) is a lender-scoped detour off
+ * `LenderEvaluation` for manually editing extracted field values — not
+ * reachable from `ApplicationFinalized`. A lender toggles into it and back
+ * out to `LenderEvaluation`; it never appears on a record no lender has
+ * claimed. See finsys-api's `updateIhsStatusByLender` for the transition
+ * guard.
  */
 declare enum IhsStatus {
     CreatingApplication = "CREATING_APPLICATION",
     ApplicationFinalized = "APPLICATION_FINALIZED",
     LenderEvaluation = "LENDER_EVALUATION",
+    EditingApplication = "EDITING_APPLICATION",
     Approved = "APPROVED",
     LouDelivered = "LOU_DELIVERED",
     AwaitingDisbursement = "AWAITING_DISBURSEMENT",
@@ -923,6 +990,30 @@ interface AdapterExtraction {
      * The canonical field values for this instance.
      */
     readonly values: CanonicalFieldValues;
+    /**
+     * SYS-2502: when this instance's data was OBSERVED at the source
+     * (ISO-8601) — the statement's own date, the partner snapshot's
+     * timestamp — as distinct from when the adapter RAN. Optional for
+     * backward compatibility with already-shipped adapters (the host
+     * falls back to the run's ranAt when absent, exactly the inference
+     * it always did), but new adapters should treat it as required:
+     * ranAt-inference conflates "when we fetched" with "when it was
+     * true", which corrupts recency ordering for backfilled or delayed
+     * data. Expected to become mandatory at the next major version.
+     */
+    readonly observedAt?: string;
+    /**
+     * SYS-2502 (prototyped in finsys-api under SYS-2977): optional
+     * per-field extraction confidence, 0..1, keyed by canonical field
+     * name. This is the provenance slot SYS-2819 identified as the
+     * missing precondition for FinXtract-as-adapter — probabilistic
+     * extractors (OCR/LLM) carry real per-field confidence; partner-API
+     * adapters (a telco returning a number) simply omit it. `null` marks
+     * a field whose value is derived/computed rather than directly
+     * extracted (renders as "no confidence" rather than low confidence,
+     * matching IhsFieldProvenance.origin semantics).
+     */
+    readonly confidence?: Partial<Record<CanonicalFieldName, number | null>>;
 }
 /**
  * Allowed value shapes for canonical fields. Per-field type narrowing
@@ -1316,8 +1407,47 @@ interface AdapterManifest {
      *     code is loaded.
      *   - `typescript` — TS/JS adapter; `entryPoint` is required, the
      *     host imports it dynamically.
+     *   - `form-intake` — SYS-2501: data-only adapter declaring
+     *     form-field-id → canonical-field mappings. No code is loaded and
+     *     no fetch()/extract() ever runs; the host's form submission
+     *     handler IS the runtime, and this manifest is how a
+     *     borrower-entered scalar becomes a canonical, provenance-carrying
+     *     field instead of a hand-wired column write.
+     *   - `manual-override` — SYS-2501: data-only adapter declaring that
+     *     this category's fields may be operator-overridden
+     *     post-extraction. `produces` IS the override surface (a separate
+     *     list could only duplicate or contradict it); the host's
+     *     override endpoints gate on membership.
+     */
+    readonly implementation: DeclarativeImplementation | TypescriptImplementation | FormIntakeImplementation | ManualOverrideImplementation;
+    /**
+     * SYS-2502: explicit instance cardinality.
+     *
+     *   - `single` — at most one instance per applicant; extract() returns
+     *     one AdapterExtraction with `instanceKey: ""`.
+     *   - `multi` — unbounded instances per applicant, each with a stable,
+     *     non-empty instanceKey.
+     *
+     * OPTIONAL for backward compatibility: manifests written before this
+     * field existed rely on the original implicit convention
+     * (instanceKey `""` → single, non-empty → multi), and the host infers
+     * accordingly when the field is absent. New manifests should declare
+     * it — an explicit declaration lets the host REJECT a mismatched
+     * extraction (a multi-keyed instance from a declared-single adapter,
+     * or vice versa) at persistence time instead of silently storing it.
+     */
+    readonly cardinality?: "single" | "multi";
+    /**
+     * SYS-2502: per-applicant singleton fields on a multi-instance
+     * category — fields whose value describes the APPLICANT (one value
+     * regardless of how many instances exist) rather than the instance,
+     * e.g. accountHolderName on bank statements. Every entry MUST also
+     * appear in `produces` (host validates at registration, same as
+     * `produces` ⊆ category fields). Only meaningful when cardinality is
+     * `multi`; the host treats a singleton field's value as shared across
+     * the instance set.
      */
-    readonly implementation: DeclarativeImplementation | TypescriptImplementation;
+    readonly singletonFields?: ReadonlyArray<CanonicalFieldName>;
     /**
      * v2.7.0 — partner-specific identity fields the adapter needs from
      * the IHS row when fetch() is invoked. Strings name the keys that
@@ -1365,6 +1495,45 @@ interface TypescriptImplementation {
      */
     readonly entryPoint: string;
 }
+/**
+ * SYS-2501: data-only implementation for borrower/operator form intake.
+ * The manifest declares which form fields feed which canonical fields;
+ * the host's form submission handler applies the mapping — no adapter
+ * code exists to load, and neither fetch() nor extract() ever runs.
+ */
+interface FormIntakeImplementation {
+    readonly type: "form-intake";
+    /**
+     * form-field-id → canonical-field mappings. `formFieldId` is the form
+     * spec's field name (the same identifier UnifiedFormConfig fields
+     * carry); `canonical` MUST be declared by the adapter's category —
+     * host validates at registration, exactly like declarative fieldMap
+     * entries. Values arrive already typed from the form layer, so there
+     * is deliberately no transform slot here: a form field needing value
+     * transformation is a form-spec concern, not an adapter one.
+     */
+    readonly fieldMap: ReadonlyArray<FormIntakeFieldMapEntry>;
+}
+interface FormIntakeFieldMapEntry {
+    /** The form spec's field name this mapping consumes. */
+    readonly formFieldId: string;
+    /**
+     * Canonical field name this maps to. MUST be declared by the
+     * adapter's category. Host validates at registration.
+     */
+    readonly canonical: CanonicalFieldName;
+}
+/**
+ * SYS-2501: data-only implementation declaring that the adapter's
+ * `produces` list is operator-overridable post-extraction. The manifest
+ * gates the override surface; the host's override endpoints check
+ * membership in `produces` before accepting a manual value. No code, no
+ * fetch(), no extract() — the discriminator alone carries the meaning,
+ * so this shape is intentionally empty beyond `type`.
+ */
+interface ManualOverrideImplementation {
+    readonly type: "manual-override";
+}
 interface FieldMapEntry {
     /**
      * JSONPath expression into the raw payload. E.g.
@@ -1392,4 +1561,4 @@ interface FieldMapEntry {
     readonly transform?: "identity" | "pct_to_ratio01" | "to_boolean" | "to_integer";
 }
 
-export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DocumentFileMetadata, type DocumentRow, type DocumentRowCapabilities, type DocumentTypeGroup, type DropdownOption, type EditorValidator, type ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceValue, type PageConfig, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TaggedFieldData, type TimePeriodUnit, type TypescriptImplementation, type UnifiedFormConfig, type Validator, type WireFormat, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, assertDocumentType, buildDocumentRows, buildFileFieldTables, 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, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isDocumentType, isFailureIhsStatus, isTerminalIhsStatus, 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 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, 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 };