@finsys/core 4.6.0 → 4.7.0

package/dist/data/adapter-categories.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "1.0.0",
+  "schemaVersion": "1.1.0",
   "categories": [
     {
       "id": "telco-carrier",
@@ -653,7 +653,8 @@
         {
           "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 — the SSM Form 9 extraction category attests the same fact from its own document."
         },
         {
           "name": "financialYearEnd",
@@ -1372,6 +1373,121 @@
           "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 — 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 — 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 — 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 — 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."
+        }
+      ]
     }
   ]
 }

package/dist/index.cjs

@@ -61,11 +61,13 @@ __export(index_exports, {
   buildDocumentRows: () => buildDocumentRows,
   buildFileFieldTables: () => buildFileFieldTables,
   buildFileFieldTablesFromInstances: () => buildFileFieldTablesFromInstances,
+  categoriesAttestingFact: () => categoriesAttestingFact,
   categoryFieldsOf: () => categoryFieldsOf,
   categoryForField: () => categoryForField,
   categorySchemaOf: () => categorySchemaOf,
   evaluateExpression: () => evaluateExpression,
   extractTimePeriods: () => extractTimePeriods,
+  factOf: () => factOf,
   formatDocumentSize: () => formatDocumentSize,
   formatDocumentType: () => formatDocumentType,
   formatDocumentUploaded: () => formatDocumentUploaded,
@@ -10321,7 +10323,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",
@@ -10975,7 +10977,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",
@@ -11694,6 +11697,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."
+        }
+      ]
     }
   ]
 };
@@ -11716,6 +11834,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) {
@@ -11750,11 +11871,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}"`
@@ -11777,10 +11921,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,
@@ -11797,7 +11957,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);
@@ -11820,6 +11987,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);
 }
@@ -11864,11 +12037,13 @@ function assertAdapterCategory(id) {
   buildDocumentRows,
   buildFileFieldTables,
   buildFileFieldTablesFromInstances,
+  categoriesAttestingFact,
   categoryFieldsOf,
   categoryForField,
   categorySchemaOf,
   evaluateExpression,
   extractTimePeriods,
+  factOf,
   formatDocumentSize,
   formatDocumentType,
   formatDocumentUploaded,