@finsys/core 4.6.0 → 4.7.0

package/dist/index.d.cts

@@ -842,6 +842,19 @@ 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;
 }
 /**
  * Per-category schema bundle. Used by:
@@ -883,11 +896,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
@@ -1740,4 +1772,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,19 @@ 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;
 }
 /**
  * Per-category schema bundle. Used by:
@@ -883,11 +896,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
@@ -1740,4 +1772,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.1.0",
   categories: [
     {
       id: "telco-carrier",
@@ -10865,7 +10865,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 +11585,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."
+        }
+      ]
     }
   ]
 };
@@ -11606,6 +11722,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,11 +11759,34 @@ 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 (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}"`
@@ -11667,10 +11809,26 @@ 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 } : {}
       });
       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, 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 +11845,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 +11875,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 +11924,13 @@ export {
   buildDocumentRows,
   buildFileFieldTables,
   buildFileFieldTablesFromInstances,
+  categoriesAttestingFact,
   categoryFieldsOf,
   categoryForField,
   categorySchemaOf,
   evaluateExpression,
   extractTimePeriods,
+  factOf,
   formatDocumentSize,
   formatDocumentType,
   formatDocumentUploaded,