@finsys/core 4.7.0 → 4.8.0

package/dist/index.d.cts

@@ -855,6 +855,22 @@ interface CanonicalFieldSpec {
      * 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:
@@ -1629,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

package/dist/index.d.ts

@@ -855,6 +855,22 @@ interface CanonicalFieldSpec {
      * 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:
@@ -1629,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

package/dist/index.js

@@ -10211,7 +10211,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",
@@ -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)."
         }
       ]
     },
@@ -11710,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");
@@ -11777,6 +11802,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) {
@@ -11792,6 +11823,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`
@@ -11810,14 +11858,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) {