@finsys/core 4.6.0 → 4.8.0

package/dist/data/adapter-categories.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "1.0.0",
+  "schemaVersion": "1.2.0",
   "categories": [
     {
       "id": "telco-carrier",
@@ -51,6 +51,30 @@
           "unit": "MYR",
           "range": [0, 10000],
           "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)."
         }
       ]
     },
@@ -653,7 +677,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 +1397,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.2.0",
   categories: [
     {
       id: "telco-carrier",
@@ -10373,6 +10375,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)."
         }
       ]
     },
@@ -10975,7 +11001,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 +11721,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."
+        }
+      ]
     }
   ]
 };
@@ -11704,6 +11846,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");
@@ -11716,6 +11859,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,16 +11896,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`
@@ -11777,10 +11969,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,
@@ -11797,7 +12006,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 +12036,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 +12086,13 @@ function assertAdapterCategory(id) {
   buildDocumentRows,
   buildFileFieldTables,
   buildFileFieldTablesFromInstances,
+  categoriesAttestingFact,
   categoryFieldsOf,
   categoryForField,
   categorySchemaOf,
   evaluateExpression,
   extractTimePeriods,
+  factOf,
   formatDocumentSize,
   formatDocumentType,
   formatDocumentUploaded,