@finsys/core 4.7.0 → 4.9.0

package/dist/data/adapter-categories.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "1.1.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)."
         }
       ]
     },

package/dist/index.cjs

@@ -33,6 +33,7 @@ __export(index_exports, {
   ADAPTER_CATEGORY_IDS: () => ADAPTER_CATEGORY_IDS,
   ALL_AGGREGATION_OPS: () => ALL_AGGREGATION_OPS,
   AdapterError: () => AdapterError,
+  AdapterExecutionMode: () => AdapterExecutionMode,
   BASE_FIELD_SPECS: () => BASE_FIELD_SPECS,
   BasicFormField: () => BasicFormField,
   DEFAULT_VALIDATOR_DEFINITIONS: () => DEFAULT_VALIDATOR_DEFINITIONS,
@@ -66,6 +67,7 @@ __export(index_exports, {
   categoryForField: () => categoryForField,
   categorySchemaOf: () => categorySchemaOf,
   evaluateExpression: () => evaluateExpression,
+  executionModeOf: () => executionModeOf,
   extractTimePeriods: () => extractTimePeriods,
   factOf: () => factOf,
   formatDocumentSize: () => formatDocumentSize,
@@ -10323,7 +10325,7 @@ function applyAggregation(op, instances) {
 
 // src/data/adapter-categories.json
 var adapter_categories_default = {
-  schemaVersion: "1.1.0",
+  schemaVersion: "1.2.0",
   categories: [
     {
       id: "telco-carrier",
@@ -10375,6 +10377,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)."
         }
       ]
     },
@@ -11822,6 +11848,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");
@@ -11889,6 +11916,12 @@ function buildCategoryRegistry(raw) {
             `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) {
@@ -11904,6 +11937,23 @@ function buildCategoryRegistry(raw) {
           `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`
@@ -11922,14 +11972,15 @@ function buildCategoryRegistry(raw) {
         ...f.unit !== void 0 ? { unit: f.unit } : {},
         ...f.range !== void 0 ? { range: Object.freeze([f.range[0], f.range[1]]) } : {},
         description: f.description,
-        ...f.fact !== void 0 ? { fact: f.fact } : {}
+        ...f.fact !== void 0 ? { fact: f.fact } : {},
+        ...f.kind !== void 0 ? { kind: f.kind } : {}
       });
       fields.push(spec);
       if (prior) {
         prior.categories.push(cat.id);
         fieldToCategory.delete(f.name);
       } else {
-        declarations.set(f.name, { fact: f.fact, categories: [cat.id] });
+        declarations.set(f.name, { fact: f.fact, kind: f.kind, categories: [cat.id] });
         fieldToCategory.set(f.name, cat.id);
       }
       if (f.fact !== void 0) {
@@ -12004,11 +12055,38 @@ function assertAdapterCategory(id) {
   }
   return id;
 }
+
+// src/adapter-manifest.ts
+var AdapterExecutionMode = /* @__PURE__ */ ((AdapterExecutionMode2) => {
+  AdapterExecutionMode2["Runnable"] = "runnable";
+  AdapterExecutionMode2["DeclarationOnly"] = "declaration-only";
+  AdapterExecutionMode2["ExternallyAsserted"] = "externally-asserted";
+  return AdapterExecutionMode2;
+})(AdapterExecutionMode || {});
+function executionModeOf(manifest) {
+  const implementationType = manifest.implementation.type;
+  switch (implementationType) {
+    case "declarative":
+    case "typescript":
+      return "runnable" /* Runnable */;
+    case "form-intake":
+    case "manual-override":
+    case "extraction-pipeline":
+      return "declaration-only" /* DeclarationOnly */;
+    case "external-assertion":
+      return "externally-asserted" /* ExternallyAsserted */;
+    default: {
+      const unhandled = implementationType;
+      throw new Error(`unknown adapter implementation type: ${String(unhandled)}`);
+    }
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ADAPTER_CATEGORY_IDS,
   ALL_AGGREGATION_OPS,
   AdapterError,
+  AdapterExecutionMode,
   BASE_FIELD_SPECS,
   BasicFormField,
   DEFAULT_VALIDATOR_DEFINITIONS,
@@ -12042,6 +12120,7 @@ function assertAdapterCategory(id) {
   categoryForField,
   categorySchemaOf,
   evaluateExpression,
+  executionModeOf,
   extractTimePeriods,
   factOf,
   formatDocumentSize,