@finsys/core 3.5.0 → 4.1.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
@@ -519,10 +553,42 @@ declare function getDisplayNames(): Record<string, string>;
 declare function getDisplayName(fieldName: string): string;
 declare function extractTimePeriods(columnNames: string[]): string[];
 declare function groupColumnsByTimePeriod(columnNames: string[]): Record<string, Record<string, string>>;
+/**
+ * Groups fields by their catalog-declared document_group (falling back to
+ * the field's own name for anything untagged). Was a hardcoded, closed
+ * prefix-matching table (FIELD_GROUP_PREFIXES) requiring a code edit for
+ * every new document type; now reads the same document_group tag the
+ * catalog already carries for document-types.ts, so adding a document
+ * type is a catalog-only data change.
+ */
 declare function groupFieldsByPattern(fields: FieldData[]): Record<string, FieldData[]>;
-/** Returns human-friendly display names for field groups. */
 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). */
@@ -583,19 +649,56 @@ declare enum ExtractionJobStatus {
     Failed = "failed"
 }
 /**
- * Document types that go through FinXtract extraction.
- * Values must match the `type` field on finsys-api File entity
- * and the config keys in finXtractApi.api.
+ * Document types that go through FinXtract extraction. Values must match
+ * the `type` field on finsys-api's File entity and the config keys in
+ * finXtractApi.api.
+ *
+ * Was a closed enum (FinancialStatement/BankStatement/Epf/Payslip/Ssm/
+ * Form9/Ic) requiring a core release to add a new document type, even
+ * though nothing outside finsys-api's own request validation actually
+ * needed it to be a closed set (confirmed: zero external consumers
+ * import a specific member by name). Now an open string, matching the
+ * AdapterCategory precedent (SYS-2500) -- the authoritative set of valid
+ * values lives in document-types.ts, derived from the field-spec catalog.
+ * Use isDocumentType()/assertDocumentType() from document-types.ts for
+ * the runtime validation that used to be the enum's job.
  */
-declare enum ExtractionFileType {
-    FinancialStatement = "financialStatements",
-    BankStatement = "bankStatements",
-    Epf = "epfStatements",
-    Payslip = "payslips",
-    Ssm = "ssm",
-    Form9 = "form9",
-    Ic = "ic"
+type ExtractionFileType = string;
+
+type WireFormat = 'path_array' | 'url_string' | 'path_only';
+type TimePeriodUnit = 'month' | 'year';
+interface DocumentTypeGroup {
+    /** Wire/dispatch value, e.g. "bankStatements". */
+    readonly documentType: string;
+    /** Render/table grouping key, e.g. "ssm_documents". Distinct from documentType -- see module doc. */
+    readonly documentGroup: string;
+    /** Human-friendly label, e.g. "Bank Statements". */
+    readonly label: string;
+    /** Reserved for a future borrower-client payload-routing consolidation. Taken from the group's first entry; not enforced consistent across entries (all groups agree today, but a future mixed-format group would silently inherit the first entry's value). */
+    readonly wireFormat?: WireFormat;
+    /**
+     * The catalog's own `type: 'file'` entries belonging to this group, in
+     * catalog order. Each entry may carry its own document_slot/
+     * time_period_unit -- see TaggedFieldData and the module doc.
+     */
+    readonly fields: readonly TaggedFieldData[];
 }
+interface TaggedFieldData extends FieldData {
+    document_type?: string;
+    document_group?: string;
+    document_group_label?: string;
+    wire_format?: WireFormat;
+    /** Which upload position this field represents (1st document, 2nd, etc). See module doc for why this is distinct from a "time period". */
+    document_slot?: number;
+    /** What unit document_slot's number measures for this field. */
+    time_period_unit?: TimePeriodUnit;
+}
+/** Every registered document type, in catalog declaration order. */
+declare function getDocumentTypeGroups(): readonly DocumentTypeGroup[];
+/** True if `id` is a registered document type (the wire/dispatch value). */
+declare function isDocumentType(id: string): boolean;
+/** Returns `id` if it's a registered document type, otherwise throws. */
+declare function assertDocumentType(id: string): string;
 
 /**
  * IHS application status — canonical source of truth, mirroring finsys-api's
@@ -608,11 +711,19 @@ declare enum ExtractionFileType {
  * 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",
@@ -1348,4 +1459,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 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, 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 TypescriptImplementation, type UnifiedFormConfig, type Validator, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, buildDocumentRows, buildFileFieldTables, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, 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, 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 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
@@ -519,10 +553,42 @@ declare function getDisplayNames(): Record<string, string>;
 declare function getDisplayName(fieldName: string): string;
 declare function extractTimePeriods(columnNames: string[]): string[];
 declare function groupColumnsByTimePeriod(columnNames: string[]): Record<string, Record<string, string>>;
+/**
+ * Groups fields by their catalog-declared document_group (falling back to
+ * the field's own name for anything untagged). Was a hardcoded, closed
+ * prefix-matching table (FIELD_GROUP_PREFIXES) requiring a code edit for
+ * every new document type; now reads the same document_group tag the
+ * catalog already carries for document-types.ts, so adding a document
+ * type is a catalog-only data change.
+ */
 declare function groupFieldsByPattern(fields: FieldData[]): Record<string, FieldData[]>;
-/** Returns human-friendly display names for field groups. */
 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). */
@@ -583,19 +649,56 @@ declare enum ExtractionJobStatus {
     Failed = "failed"
 }
 /**
- * Document types that go through FinXtract extraction.
- * Values must match the `type` field on finsys-api File entity
- * and the config keys in finXtractApi.api.
+ * Document types that go through FinXtract extraction. Values must match
+ * the `type` field on finsys-api's File entity and the config keys in
+ * finXtractApi.api.
+ *
+ * Was a closed enum (FinancialStatement/BankStatement/Epf/Payslip/Ssm/
+ * Form9/Ic) requiring a core release to add a new document type, even
+ * though nothing outside finsys-api's own request validation actually
+ * needed it to be a closed set (confirmed: zero external consumers
+ * import a specific member by name). Now an open string, matching the
+ * AdapterCategory precedent (SYS-2500) -- the authoritative set of valid
+ * values lives in document-types.ts, derived from the field-spec catalog.
+ * Use isDocumentType()/assertDocumentType() from document-types.ts for
+ * the runtime validation that used to be the enum's job.
  */
-declare enum ExtractionFileType {
-    FinancialStatement = "financialStatements",
-    BankStatement = "bankStatements",
-    Epf = "epfStatements",
-    Payslip = "payslips",
-    Ssm = "ssm",
-    Form9 = "form9",
-    Ic = "ic"
+type ExtractionFileType = string;
+
+type WireFormat = 'path_array' | 'url_string' | 'path_only';
+type TimePeriodUnit = 'month' | 'year';
+interface DocumentTypeGroup {
+    /** Wire/dispatch value, e.g. "bankStatements". */
+    readonly documentType: string;
+    /** Render/table grouping key, e.g. "ssm_documents". Distinct from documentType -- see module doc. */
+    readonly documentGroup: string;
+    /** Human-friendly label, e.g. "Bank Statements". */
+    readonly label: string;
+    /** Reserved for a future borrower-client payload-routing consolidation. Taken from the group's first entry; not enforced consistent across entries (all groups agree today, but a future mixed-format group would silently inherit the first entry's value). */
+    readonly wireFormat?: WireFormat;
+    /**
+     * The catalog's own `type: 'file'` entries belonging to this group, in
+     * catalog order. Each entry may carry its own document_slot/
+     * time_period_unit -- see TaggedFieldData and the module doc.
+     */
+    readonly fields: readonly TaggedFieldData[];
 }
+interface TaggedFieldData extends FieldData {
+    document_type?: string;
+    document_group?: string;
+    document_group_label?: string;
+    wire_format?: WireFormat;
+    /** Which upload position this field represents (1st document, 2nd, etc). See module doc for why this is distinct from a "time period". */
+    document_slot?: number;
+    /** What unit document_slot's number measures for this field. */
+    time_period_unit?: TimePeriodUnit;
+}
+/** Every registered document type, in catalog declaration order. */
+declare function getDocumentTypeGroups(): readonly DocumentTypeGroup[];
+/** True if `id` is a registered document type (the wire/dispatch value). */
+declare function isDocumentType(id: string): boolean;
+/** Returns `id` if it's a registered document type, otherwise throws. */
+declare function assertDocumentType(id: string): string;
 
 /**
  * IHS application status — canonical source of truth, mirroring finsys-api's
@@ -608,11 +711,19 @@ declare enum ExtractionFileType {
  * 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",
@@ -1348,4 +1459,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 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, 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 TypescriptImplementation, type UnifiedFormConfig, type Validator, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, buildDocumentRows, buildFileFieldTables, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, 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, 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 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 };