@finsys/core 4.6.0 → 4.8.0

package/dist/index.d.cts

@@ -842,6 +842,35 @@ interface CanonicalFieldSpec {
     readonly unit?: string;
     readonly range?: readonly [number, number];
     readonly description: string;
+    /**
+     * Global fact identifier marking this field as an ATTESTATION of a
+     * shared real-world fact (e.g. a company has exactly one
+     * incorporation date, no matter which document it was extracted
+     * from). Multiple categories may declare the SAME field name iff
+     * every declaring category carries the same `fact` id — each
+     * category's value is then an independent attestation of one fact,
+     * comparable across sources (the future disagreement-comparison
+     * feature's unit of comparison). A `fact` id is bound to exactly one
+     * field name registry-wide; by convention the field name IS the fact
+     * id. Uniquely-declared fields need no `fact` (but may carry one).
+     */
+    readonly fact?: string;
+    /**
+     * Field kind — a semantic refinement of `type`. Currently the only
+     * kind is `"enum"`: the field's value is one label out of a closed
+     * set. The category declares ONLY that the field is enumerated —
+     * never the values, never an ordering. Value sets are vendor
+     * territory: each adapter declares the exact labels it emits in its
+     * manifest's `enumValues` (host-validated), because two vendors
+     * implementing the same category may bucket differently. Ordering
+     * and scoring interpretation live even further out, in the consumer
+     * (an eval model's per-value mapping) — an enum label is data, what
+     * it is worth is opinion, and opinions don't belong in the data
+     * contract. An enum field MUST be `type: "string"` (labels are
+     * string-normalized) and MUST NOT declare a `range` (labels are
+     * unordered).
+     */
+    readonly kind?: "enum";
 }
 /**
  * Per-category schema bundle. Used by:
@@ -883,11 +912,30 @@ declare function allCategories(): ReadonlyArray<CategorySchema>;
 /**
  * Reverse lookup: which category declares a given canonical field?
  * 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. O(1).
+ * this version of finsys-core — AND for shared-fact names (declared by
+ * more than one category), where "the" category is genuinely ambiguous.
+ * The null is deliberate: a caller holding a shared-fact name must
+ * decide per-attestation, via `categoriesAttestingFact(factOf(name))`,
+ * rather than being handed one arbitrary declarer. Useful when the
+ * host app is reading canonical field values back from storage + wants
+ * to identify the producing category for rendering. O(1).
  */
 declare function categoryForField(field: CanonicalFieldName): AdapterCategory | null;
+/**
+ * The fact id a canonical field attests, or null when the field
+ * declares no fact (or isn't declared at all). By convention the fact
+ * id equals the field name, but callers must not assume it — read it
+ * from here. O(1).
+ */
+declare function factOf(field: CanonicalFieldName): string | null;
+/**
+ * Every category attesting a given shared fact, in data-file order.
+ * Empty for an unknown fact id. This is the lookup the disagreement-
+ * comparison feature keys on: each attesting category's value for the
+ * fact's field is an independent observation of the same real-world
+ * fact, so cross-category mismatches are surfaceable.
+ */
+declare function categoriesAttestingFact(factId: string): ReadonlyArray<AdapterCategory>;
 /**
  * Runtime membership check — is `id` a category declared by this
  * version of finsys-core? Use this at trust boundaries (parsing a
@@ -1597,6 +1645,34 @@ interface AdapterManifest {
      * adapter is implemented.
      */
     readonly periods?: ReadonlyArray<PeriodDeclaration>;
+    /**
+     * Vendor-specific value sets for the enum-kind fields this adapter
+     * produces. The category declares only THAT a field is enumerated
+     * (`kind: "enum"` — no values, no ordering); the manifest declares
+     * exactly WHICH labels this vendor emits, because two vendors
+     * implementing the same category may bucket differently. Scoring
+     * interpretation lives further out still, in the consumer (an eval
+     * model's per-value mapping with a mandatory fallback) — never here.
+     *
+     * Host-validated at registration (same posture as `produces` ⊆
+     * category fields):
+     *   - every key MUST appear in `produces`;
+     *   - every key MUST be declared `kind: "enum"` by the adapter's
+     *     category — a non-enum field with declared values is refused;
+     *   - every enum-kind field in `produces` MUST have an entry here —
+     *     an adapter that promises an enum field but not its labels
+     *     gives clients nothing to render or map against;
+     *   - each value set is a non-empty array of unique, string-
+     *     normalized labels (non-empty, no leading/trailing whitespace).
+     *
+     * At runtime the adapter emits labels from its declared set
+     * VERBATIM; the host refuses out-of-set values at ingest, so a
+     * vendor-side vocabulary change is a loud manifest-version bump,
+     * never silent data drift. Clients (form-spec and eval-model
+     * editors) read these sets through the registry-metadata surface to
+     * offer the labels without hardcoding any vendor's vocabulary.
+     */
+    readonly enumValues?: Readonly<Record<CanonicalFieldName, ReadonlyArray<string>>>;
     /**
      * Optional free-form notes — useful for partner-side documentation
      * (where to find the adapter's source, who owns it, what version of
@@ -1740,4 +1816,4 @@ interface FieldMapEntry {
     readonly transform?: "identity" | "pct_to_ratio01" | "to_boolean" | "to_integer";
 }
 
-export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type CategorySpec, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DocumentFileMetadata, type DocumentRow, type DocumentRowCapabilities, type DocumentTypeGroup, type DropdownOption, type EditorValidator, type ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionPipelineImplementation, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldAuthorization, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, type FormIntakeFieldMapEntry, type FormIntakeImplementation, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_FIELD_ORIGINS, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldOrigin, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceRow, type InstanceValue, type ManualOverrideImplementation, type PageConfig, type PeriodDeclaration, type PeriodValues, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TaggedFieldData, type TimePeriodUnit, type TypescriptImplementation, type UnifiedFormConfig, type Validator, type WireFormat, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, assertDocumentType, buildDocumentRows, buildFileFieldTables, buildFileFieldTablesFromInstances, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getDocumentTypeGroups, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByInstance, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isDocumentType, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsFieldOrigin, isValidIhsStatus, parseFileField, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };
+export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type CategorySpec, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DocumentFileMetadata, type DocumentRow, type DocumentRowCapabilities, type DocumentTypeGroup, type DropdownOption, type EditorValidator, type ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionPipelineImplementation, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldAuthorization, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, type FormIntakeFieldMapEntry, type FormIntakeImplementation, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_FIELD_ORIGINS, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldOrigin, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceRow, type InstanceValue, type ManualOverrideImplementation, type PageConfig, type PeriodDeclaration, type PeriodValues, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TaggedFieldData, type TimePeriodUnit, type TypescriptImplementation, type UnifiedFormConfig, type Validator, type WireFormat, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, assertDocumentType, buildDocumentRows, buildFileFieldTables, buildFileFieldTablesFromInstances, categoriesAttestingFact, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, factOf, 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

@@ -842,6 +842,35 @@ interface CanonicalFieldSpec {
     readonly unit?: string;
     readonly range?: readonly [number, number];
     readonly description: string;
+    /**
+     * Global fact identifier marking this field as an ATTESTATION of a
+     * shared real-world fact (e.g. a company has exactly one
+     * incorporation date, no matter which document it was extracted
+     * from). Multiple categories may declare the SAME field name iff
+     * every declaring category carries the same `fact` id — each
+     * category's value is then an independent attestation of one fact,
+     * comparable across sources (the future disagreement-comparison
+     * feature's unit of comparison). A `fact` id is bound to exactly one
+     * field name registry-wide; by convention the field name IS the fact
+     * id. Uniquely-declared fields need no `fact` (but may carry one).
+     */
+    readonly fact?: string;
+    /**
+     * Field kind — a semantic refinement of `type`. Currently the only
+     * kind is `"enum"`: the field's value is one label out of a closed
+     * set. The category declares ONLY that the field is enumerated —
+     * never the values, never an ordering. Value sets are vendor
+     * territory: each adapter declares the exact labels it emits in its
+     * manifest's `enumValues` (host-validated), because two vendors
+     * implementing the same category may bucket differently. Ordering
+     * and scoring interpretation live even further out, in the consumer
+     * (an eval model's per-value mapping) — an enum label is data, what
+     * it is worth is opinion, and opinions don't belong in the data
+     * contract. An enum field MUST be `type: "string"` (labels are
+     * string-normalized) and MUST NOT declare a `range` (labels are
+     * unordered).
+     */
+    readonly kind?: "enum";
 }
 /**
  * Per-category schema bundle. Used by:
@@ -883,11 +912,30 @@ declare function allCategories(): ReadonlyArray<CategorySchema>;
 /**
  * Reverse lookup: which category declares a given canonical field?
  * 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. O(1).
+ * this version of finsys-core — AND for shared-fact names (declared by
+ * more than one category), where "the" category is genuinely ambiguous.
+ * The null is deliberate: a caller holding a shared-fact name must
+ * decide per-attestation, via `categoriesAttestingFact(factOf(name))`,
+ * rather than being handed one arbitrary declarer. Useful when the
+ * host app is reading canonical field values back from storage + wants
+ * to identify the producing category for rendering. O(1).
  */
 declare function categoryForField(field: CanonicalFieldName): AdapterCategory | null;
+/**
+ * The fact id a canonical field attests, or null when the field
+ * declares no fact (or isn't declared at all). By convention the fact
+ * id equals the field name, but callers must not assume it — read it
+ * from here. O(1).
+ */
+declare function factOf(field: CanonicalFieldName): string | null;
+/**
+ * Every category attesting a given shared fact, in data-file order.
+ * Empty for an unknown fact id. This is the lookup the disagreement-
+ * comparison feature keys on: each attesting category's value for the
+ * fact's field is an independent observation of the same real-world
+ * fact, so cross-category mismatches are surfaceable.
+ */
+declare function categoriesAttestingFact(factId: string): ReadonlyArray<AdapterCategory>;
 /**
  * Runtime membership check — is `id` a category declared by this
  * version of finsys-core? Use this at trust boundaries (parsing a
@@ -1597,6 +1645,34 @@ interface AdapterManifest {
      * adapter is implemented.
      */
     readonly periods?: ReadonlyArray<PeriodDeclaration>;
+    /**
+     * Vendor-specific value sets for the enum-kind fields this adapter
+     * produces. The category declares only THAT a field is enumerated
+     * (`kind: "enum"` — no values, no ordering); the manifest declares
+     * exactly WHICH labels this vendor emits, because two vendors
+     * implementing the same category may bucket differently. Scoring
+     * interpretation lives further out still, in the consumer (an eval
+     * model's per-value mapping with a mandatory fallback) — never here.
+     *
+     * Host-validated at registration (same posture as `produces` ⊆
+     * category fields):
+     *   - every key MUST appear in `produces`;
+     *   - every key MUST be declared `kind: "enum"` by the adapter's
+     *     category — a non-enum field with declared values is refused;
+     *   - every enum-kind field in `produces` MUST have an entry here —
+     *     an adapter that promises an enum field but not its labels
+     *     gives clients nothing to render or map against;
+     *   - each value set is a non-empty array of unique, string-
+     *     normalized labels (non-empty, no leading/trailing whitespace).
+     *
+     * At runtime the adapter emits labels from its declared set
+     * VERBATIM; the host refuses out-of-set values at ingest, so a
+     * vendor-side vocabulary change is a loud manifest-version bump,
+     * never silent data drift. Clients (form-spec and eval-model
+     * editors) read these sets through the registry-metadata surface to
+     * offer the labels without hardcoding any vendor's vocabulary.
+     */
+    readonly enumValues?: Readonly<Record<CanonicalFieldName, ReadonlyArray<string>>>;
     /**
      * Optional free-form notes — useful for partner-side documentation
      * (where to find the adapter's source, who owns it, what version of
@@ -1740,4 +1816,4 @@ interface FieldMapEntry {
     readonly transform?: "identity" | "pct_to_ratio01" | "to_boolean" | "to_integer";
 }
 
-export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type CategorySpec, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DocumentFileMetadata, type DocumentRow, type DocumentRowCapabilities, type DocumentTypeGroup, type DropdownOption, type EditorValidator, type ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionPipelineImplementation, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldAuthorization, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, type FormIntakeFieldMapEntry, type FormIntakeImplementation, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_FIELD_ORIGINS, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldOrigin, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceRow, type InstanceValue, type ManualOverrideImplementation, type PageConfig, type PeriodDeclaration, type PeriodValues, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TaggedFieldData, type TimePeriodUnit, type TypescriptImplementation, type UnifiedFormConfig, type Validator, type WireFormat, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, assertDocumentType, buildDocumentRows, buildFileFieldTables, buildFileFieldTablesFromInstances, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getDocumentTypeGroups, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByInstance, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isDocumentType, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsFieldOrigin, isValidIhsStatus, parseFileField, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };
+export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type CategorySpec, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DocumentFileMetadata, type DocumentRow, type DocumentRowCapabilities, type DocumentTypeGroup, type DropdownOption, type EditorValidator, type ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionPipelineImplementation, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldAuthorization, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, type FormIntakeFieldMapEntry, type FormIntakeImplementation, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_FIELD_ORIGINS, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldOrigin, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceRow, type InstanceValue, type ManualOverrideImplementation, type PageConfig, type PeriodDeclaration, type PeriodValues, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TaggedFieldData, type TimePeriodUnit, type TypescriptImplementation, type UnifiedFormConfig, type Validator, type WireFormat, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, assertDocumentType, buildDocumentRows, buildFileFieldTables, buildFileFieldTablesFromInstances, categoriesAttestingFact, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, factOf, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getDocumentTypeGroups, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByInstance, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isDocumentType, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsFieldOrigin, isValidIhsStatus, parseFileField, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };

package/dist/index.js

@@ -10211,7 +10211,7 @@ function applyAggregation(op, instances) {
 
 // src/data/adapter-categories.json
 var adapter_categories_default = {
-  schemaVersion: "1.0.0",
+  schemaVersion: "1.2.0",
   categories: [
     {
       id: "telco-carrier",
@@ -10263,6 +10263,30 @@ var adapter_categories_default = {
           unit: "MYR",
           range: [0, 1e4],
           description: "Average Revenue Per User (monthly) in Malaysian Ringgit. Coarse spending-capacity proxy."
+        },
+        {
+          name: "telcoPaymentReliabilityTier",
+          type: "string",
+          kind: "enum",
+          description: "Coarse bill-payment reliability bucket, for partners that return a tier label instead of a continuous ratio. Parallel signal to telcoOnTimePaymentRatio24m. Labels are vendor-declared (see the adapter manifest's enumValues); ordering and scoring live in the consumer's per-value mapping."
+        },
+        {
+          name: "telcoTenureTier",
+          type: "string",
+          kind: "enum",
+          description: "Coarse account-age bucket, for partners that return a tenure tier label instead of a continuous month count. Parallel signal to telcoTenureMonths. Labels are vendor-declared (see the adapter manifest's enumValues)."
+        },
+        {
+          name: "telcoDistressTier",
+          type: "string",
+          kind: "enum",
+          description: "Coarse account-distress bucket, for partners that return a distress tier label instead of discrete counts. Parallel signal to telcoSuspensionsCount24m / telcoLateDays24m. Labels are vendor-declared (see the adapter manifest's enumValues)."
+        },
+        {
+          name: "telcoHandsetRiskTier",
+          type: "string",
+          kind: "enum",
+          description: "Coarse handset-financing risk bucket, for partners that return a tier label instead of the discrete handset flags. Parallel signal to telcoHandsetFinancingActive / telcoHandsetFinancingDelinquent. Labels are vendor-declared (see the adapter manifest's enumValues)."
         }
       ]
     },
@@ -10865,7 +10889,8 @@ var adapter_categories_default = {
         {
           name: "companyName",
           type: "string",
-          description: "Company name as stated on the document."
+          fact: "companyName",
+          description: "Company name as stated on the document. Attestation of the shared companyName fact \u2014 the SSM Form 9 extraction category attests the same fact from its own document."
         },
         {
           name: "financialYearEnd",
@@ -11584,6 +11609,121 @@ var adapter_categories_default = {
           description: "Cash-flow statement: cash and cash equivalents at the end of the financial year."
         }
       ]
+    },
+    {
+      id: "finxtract-form9",
+      displayName: "SSM Form 9 (Document Extraction)",
+      description: "Fields extracted from an uploaded SSM Form 9 (Certificate of Incorporation of Private Company) document by the host's extraction pipeline. One instance per uploaded document. The company name and incorporation date are attestations of shared facts \u2014 the company-profile and financial-statement extraction categories attest the same real-world facts from their own documents.",
+      canonicalTable: "ihs_alt_data_form9",
+      fields: [
+        {
+          name: "companyName",
+          type: "string",
+          fact: "companyName",
+          description: "Company name as printed on the certificate. Attestation of the shared companyName fact."
+        },
+        {
+          name: "companyRegNo",
+          type: "string",
+          description: "Company registration number as printed on the certificate."
+        },
+        {
+          name: "companyIncorporationDate",
+          type: "string",
+          fact: "companyIncorporationDate",
+          description: "Date of incorporation as printed on the certificate, normalized to ISO YYYY-MM-DD. Attestation of the shared companyIncorporationDate fact \u2014 a company has exactly one incorporation date regardless of which document it was extracted from."
+        }
+      ]
+    },
+    {
+      id: "finxtract-ssm",
+      displayName: "SSM Company Profile (Document Extraction)",
+      description: "Fields extracted from an uploaded SSM company-profile document (company or business registration extract) by the host's extraction pipeline. One instance per uploaded document. Covers registration identity, status, key dates, registered address, capital, and the officer/shareholder registers. The incorporation date is an attestation of a shared fact \u2014 the Form 9 extraction category attests the same real-world fact from its own document.",
+      canonicalTable: "ihs_alt_data_ssm",
+      fields: [
+        {
+          name: "ssmCompanyEntityType",
+          type: "string",
+          description: "Entity type stated on the profile (e.g. private limited company, enterprise)."
+        },
+        {
+          name: "ssmCompanyName",
+          type: "string",
+          description: "Business or company name as stated on the profile."
+        },
+        {
+          name: "ssmCompanyRegNo",
+          type: "string",
+          description: "Business or company registration number as stated on the profile."
+        },
+        {
+          name: "companyStatus",
+          type: "string",
+          description: "Registration status as stated on the profile (e.g. existing, dissolved)."
+        },
+        {
+          name: "businessOrigin",
+          type: "string",
+          description: "Business origin as stated on the profile."
+        },
+        {
+          name: "companyIncorporationDate",
+          type: "string",
+          fact: "companyIncorporationDate",
+          description: "Incorporation (or registration) date as stated on the profile, normalized to ISO YYYY-MM-DD. Attestation of the shared companyIncorporationDate fact \u2014 a company has exactly one incorporation date regardless of which document it was extracted from."
+        },
+        {
+          name: "businessCommencementDate",
+          type: "string",
+          description: "Business commencement (or start) date as stated on the profile, normalized to ISO YYYY-MM-DD."
+        },
+        {
+          name: "businessNature",
+          type: "string",
+          description: "Nature of business as stated on the profile."
+        },
+        {
+          name: "registeredAddress",
+          type: "string",
+          description: "Registered business address as stated on the profile."
+        },
+        {
+          name: "totalShareIssued",
+          type: "number",
+          description: "Total shares issued as stated on the profile."
+        },
+        {
+          name: "ssmPaidUpCapital",
+          type: "number",
+          unit: "MYR",
+          description: "Paid-up capital as stated on the profile (falls back to total shares issued when the profile omits an explicit paid-up figure)."
+        },
+        {
+          name: "directors",
+          type: "string",
+          description: "JSON-encoded list of current directors/officers (for enterprises, the business owner normalized into the same shape)."
+        },
+        {
+          name: "shareholders",
+          type: "string",
+          description: "JSON-encoded list of shareholders (for enterprises, the business owner normalized into the same shape)."
+        },
+        {
+          name: "previousDirectors",
+          type: "string",
+          description: "JSON-encoded list of previous directors/officers."
+        },
+        {
+          name: "companyLastOldName",
+          type: "string",
+          description: "The company's most recent former name, when the profile records a name change."
+        },
+        {
+          name: "companyNameDateOfChange",
+          type: "string",
+          description: "Date of the most recent name change, normalized to ISO YYYY-MM-DD."
+        }
+      ]
     }
   ]
 };
@@ -11594,6 +11734,7 @@ var VALID_FIELD_TYPES = [
   "boolean",
   "string"
 ];
+var VALID_FIELD_KINDS = ["enum"];
 function buildCategoryRegistry(raw) {
   if (!raw || typeof raw !== "object") {
     throw new Error("adapter category data: expected an object");
@@ -11606,6 +11747,9 @@ function buildCategoryRegistry(raw) {
   }
   const byId = /* @__PURE__ */ new Map();
   const fieldToCategory = /* @__PURE__ */ new Map();
+  const fieldToFact = /* @__PURE__ */ new Map();
+  const factToCategories = /* @__PURE__ */ new Map();
+  const declarations = /* @__PURE__ */ new Map();
   const tables = /* @__PURE__ */ new Set();
   const all = [];
   for (const cat of raw.categories) {
@@ -11640,16 +11784,62 @@ function buildCategoryRegistry(raw) {
       if (typeof f.name !== "string" || f.name.length === 0) {
         throw new Error(`adapter category data: ${where} has a field with no name`);
       }
-      if (fieldToCategory.has(f.name)) {
+      if (f.fact !== void 0 && (typeof f.fact !== "string" || f.fact.length === 0)) {
         throw new Error(
-          `adapter category data: canonical field "${f.name}" declared by more than one category (${fieldToCategory.get(f.name)} + ${cat.id}) \u2014 field names must be globally unique`
+          `adapter category data: field "${f.name}" (${where}) has an invalid fact \u2014 expected a non-empty string`
         );
       }
+      const prior = declarations.get(f.name);
+      if (prior) {
+        if (prior.categories.includes(cat.id)) {
+          throw new Error(
+            `adapter category data: ${where} declares field "${f.name}" more than once`
+          );
+        }
+        if (prior.fact === void 0 || f.fact === void 0 || prior.fact !== f.fact) {
+          const describeFact = (fact) => fact === void 0 ? "no fact" : `fact "${fact}"`;
+          throw new Error(
+            `adapter category data: canonical field "${f.name}" declared by more than one category (${prior.categories.join(" + ")} with ${describeFact(prior.fact)} + ${cat.id} with ${describeFact(f.fact)}) \u2014 field names must be globally unique unless every declaring category attests the same fact`
+          );
+        }
+        if (prior.kind !== f.kind) {
+          const describeKind = (kind) => kind === void 0 ? "no kind" : `kind "${kind}"`;
+          throw new Error(
+            `adapter category data: canonical field "${f.name}" declared with ${describeKind(prior.kind)} by ${prior.categories.join(" + ")} but ${describeKind(f.kind)} by ${cat.id} \u2014 shared-fact attestations must agree on kind`
+          );
+        }
+      }
+      if (f.fact !== void 0) {
+        for (const [otherName, otherFact] of fieldToFact) {
+          if (otherFact === f.fact && otherName !== f.name) {
+            throw new Error(
+              `adapter category data: fact "${f.fact}" is carried by two different field names ("${otherName}" + "${f.name}") \u2014 a fact id must map to exactly one canonical field name`
+            );
+          }
+        }
+      }
       if (!VALID_FIELD_TYPES.includes(f.type)) {
         throw new Error(
           `adapter category data: field "${f.name}" (${where}) has invalid type "${f.type}"`
         );
       }
+      if (f.kind !== void 0) {
+        if (!VALID_FIELD_KINDS.includes(f.kind)) {
+          throw new Error(
+            `adapter category data: field "${f.name}" (${where}) has invalid kind "${String(f.kind)}"`
+          );
+        }
+        if (f.type !== "string") {
+          throw new Error(
+            `adapter category data: field "${f.name}" (${where}) is kind "enum" but type "${f.type}" \u2014 enum labels are string-normalized, so an enum field must be type "string"`
+          );
+        }
+        if (f.range !== void 0) {
+          throw new Error(
+            `adapter category data: field "${f.name}" (${where}) is kind "enum" but declares a range \u2014 enum labels are unordered; ordering belongs to the consumer, never the data contract`
+          );
+        }
+      }
       if (typeof f.description !== "string" || f.description.length === 0) {
         throw new Error(
           `adapter category data: field "${f.name}" (${where}) needs a non-empty description`
@@ -11667,10 +11857,27 @@ function buildCategoryRegistry(raw) {
         type: f.type,
         ...f.unit !== void 0 ? { unit: f.unit } : {},
         ...f.range !== void 0 ? { range: Object.freeze([f.range[0], f.range[1]]) } : {},
-        description: f.description
+        description: f.description,
+        ...f.fact !== void 0 ? { fact: f.fact } : {},
+        ...f.kind !== void 0 ? { kind: f.kind } : {}
       });
       fields.push(spec);
-      fieldToCategory.set(f.name, cat.id);
+      if (prior) {
+        prior.categories.push(cat.id);
+        fieldToCategory.delete(f.name);
+      } else {
+        declarations.set(f.name, { fact: f.fact, kind: f.kind, categories: [cat.id] });
+        fieldToCategory.set(f.name, cat.id);
+      }
+      if (f.fact !== void 0) {
+        fieldToFact.set(f.name, f.fact);
+        const attesters = factToCategories.get(f.fact);
+        if (attesters) {
+          attesters.push(cat.id);
+        } else {
+          factToCategories.set(f.fact, [cat.id]);
+        }
+      }
     }
     const schema = Object.freeze({
       id: cat.id,
@@ -11687,7 +11894,14 @@ function buildCategoryRegistry(raw) {
     all: Object.freeze(all),
     ids: Object.freeze(all.map((c) => c.id)),
     byId,
-    fieldToCategory
+    fieldToCategory,
+    fieldToFact,
+    factToCategories: new Map(
+      [...factToCategories].map(([fact, cats]) => [
+        fact,
+        Object.freeze(cats)
+      ])
+    )
   });
 }
 var registry = buildCategoryRegistry(adapter_categories_default);
@@ -11710,6 +11924,12 @@ function allCategories() {
 function categoryForField(field) {
   return registry.fieldToCategory.get(field) ?? null;
 }
+function factOf(field) {
+  return registry.fieldToFact.get(field) ?? null;
+}
+function categoriesAttestingFact(factId) {
+  return registry.factToCategories.get(factId) ?? [];
+}
 function isAdapterCategory(id) {
   return registry.byId.has(id);
 }
@@ -11753,11 +11973,13 @@ export {
   buildDocumentRows,
   buildFileFieldTables,
   buildFileFieldTablesFromInstances,
+  categoriesAttestingFact,
   categoryFieldsOf,
   categoryForField,
   categorySchemaOf,
   evaluateExpression,
   extractTimePeriods,
+  factOf,
   formatDocumentSize,
   formatDocumentType,
   formatDocumentUploaded,