@finsys/core 4.7.0 → 4.9.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:
@@ -1518,8 +1534,18 @@ interface AdapterManifest {
      *     records the adapter runs itself; the manifest exists purely as
      *     the declaration plane (produces, cardinality,
      *     fieldAuthorizations) for data the host was already producing.
+     *   - `external-assertion` — SYS-3036 (ownership moved here from a
+     *     host-local extension): declaration-only adapter that is executed
+     *     entirely OUTSIDE the host. An externally-orchestrated process
+     *     completes its own ceremony/extraction and PUSHES the result to
+     *     the host's assertion-ingest surface. No code is loaded and
+     *     neither fetch() nor extract() ever runs — the same
+     *     declaration-only shape as `form-intake`/`manual-override`/
+     *     `extraction-pipeline`, but data arrives via an external push
+     *     rather than the host's own pipeline, form submission, or a
+     *     dynamic-imported/declarative extract() call.
      */
-    readonly implementation: DeclarativeImplementation | TypescriptImplementation | FormIntakeImplementation | ManualOverrideImplementation | ExtractionPipelineImplementation;
+    readonly implementation: DeclarativeImplementation | TypescriptImplementation | FormIntakeImplementation | ManualOverrideImplementation | ExtractionPipelineImplementation | ExternalAssertionImplementation;
     /**
      * SYS-2502: explicit instance cardinality.
      *
@@ -1629,6 +1655,45 @@ 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.
+     *
+     * Matching is EXACT-STRING — case and whitespace variations from a
+     * declared label are treated as distinct (and therefore out-of-set),
+     * deliberately. `uniqueItems` at the schema layer is likewise
+     * exact-match, so e.g. `["High", "high"]` is a legal (if unusual)
+     * two-label set; nothing here folds case or reconciles near-miss
+     * spelling. Silently normalizing would band-aid over a vendor-side
+     * inconsistency instead of surfacing it — a vendor emitting `"high"`
+     * when its manifest declares `"High"` is a vendor bug that should be
+     * refused loudly, not coerced into matching. Vendors own their exact
+     * label byte-for-byte; hosts never guess at reconciliation.
+     */
+    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
@@ -1745,6 +1810,64 @@ interface ManualOverrideImplementation {
 interface ExtractionPipelineImplementation {
     readonly type: "extraction-pipeline";
 }
+/**
+ * SYS-3036: declaration-only implementation for adapters that are
+ * executed entirely OUTSIDE the host application. An externally-
+ * orchestrated process (a partner-run ceremony, an out-of-band
+ * verification flow, etc.) completes its own extraction and PUSHES the
+ * result to the host's assertion-ingest surface, rather than the host
+ * pulling it via `fetch()`/`extract()` or a form submission. No code,
+ * no fetch(), no extract(); like `manual-override` and
+ * `extraction-pipeline`, the discriminator alone carries the meaning —
+ * the shape is intentionally empty beyond `type`.
+ *
+ * Ownership note: this type + its schema branch were previously a
+ * host-local extension (a runtime clone of the compiled schema with one
+ * extra `oneOf` branch bolted on) because core hadn't yet published the
+ * concept. Publishing it here means every host validates the SAME
+ * schema — no more per-host schema patches for this discriminator.
+ */
+interface ExternalAssertionImplementation {
+    readonly type: "external-assertion";
+}
+/**
+ * SYS-3036: how a registered adapter participates at execution time,
+ * derived purely from `implementation.type`. Published here (rather than
+ * re-derived per host) so every host classifies manifests identically:
+ *
+ *   - `Runnable` — the host loads (declarative) or dynamic-imports
+ *     (typescript) a `SourceAdapter`; the host's run loop executes it.
+ *   - `DeclarationOnly` — the manifest is pure declaration plane
+ *     (`form-intake`, `manual-override`, `extraction-pipeline`). No code
+ *     exists to load; the entry is registered so `list()`-style
+ *     consumers (field-authorization gating, provenance rendering,
+ *     diagnostics) see the manifest, and every execution path skips it.
+ *   - `ExternallyAsserted` — the manifest declares
+ *     `implementation.type: "external-assertion"`. Same "no code, host
+ *     never calls fetch()/extract()" shape as `DeclarationOnly`, but data
+ *     arrives via an external push rather than the host's own
+ *     extraction pipeline or form intake. Hosts that used to fork on
+ *     this case separately can safely fold it into the same "not
+ *     Runnable" branch that already skips `DeclarationOnly` entries.
+ *
+ * String values mirror the discriminators they classify so a logged
+ * `executionMode` reads naturally alongside `implementation.type`.
+ */
+declare enum AdapterExecutionMode {
+    Runnable = "runnable",
+    DeclarationOnly = "declaration-only",
+    ExternallyAsserted = "externally-asserted"
+}
+/**
+ * SYS-3036: classify a manifest's `implementation.type` into its
+ * `AdapterExecutionMode`. Exhaustive over every discriminator this
+ * version of `@finsys/core` publishes — the switch has an explicit case
+ * per type and THROWS on anything else (Ajv should already have refused
+ * an unrecognized discriminator at validation time, but a schema/host
+ * version skew must surface as a loud refusal here too, never as a
+ * silently-guessed mode; no fallback branch assigns one).
+ */
+declare function executionModeOf(manifest: Pick<AdapterManifest, "implementation">): AdapterExecutionMode;
 interface FieldMapEntry {
     /**
      * JSONPath expression into the raw payload. E.g.
@@ -1772,4 +1895,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, 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 };
+export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, AdapterExecutionMode, 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 ExternalAssertionImplementation, 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, executionModeOf, 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

@@ -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:
@@ -1518,8 +1534,18 @@ interface AdapterManifest {
      *     records the adapter runs itself; the manifest exists purely as
      *     the declaration plane (produces, cardinality,
      *     fieldAuthorizations) for data the host was already producing.
+     *   - `external-assertion` — SYS-3036 (ownership moved here from a
+     *     host-local extension): declaration-only adapter that is executed
+     *     entirely OUTSIDE the host. An externally-orchestrated process
+     *     completes its own ceremony/extraction and PUSHES the result to
+     *     the host's assertion-ingest surface. No code is loaded and
+     *     neither fetch() nor extract() ever runs — the same
+     *     declaration-only shape as `form-intake`/`manual-override`/
+     *     `extraction-pipeline`, but data arrives via an external push
+     *     rather than the host's own pipeline, form submission, or a
+     *     dynamic-imported/declarative extract() call.
      */
-    readonly implementation: DeclarativeImplementation | TypescriptImplementation | FormIntakeImplementation | ManualOverrideImplementation | ExtractionPipelineImplementation;
+    readonly implementation: DeclarativeImplementation | TypescriptImplementation | FormIntakeImplementation | ManualOverrideImplementation | ExtractionPipelineImplementation | ExternalAssertionImplementation;
     /**
      * SYS-2502: explicit instance cardinality.
      *
@@ -1629,6 +1655,45 @@ 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.
+     *
+     * Matching is EXACT-STRING — case and whitespace variations from a
+     * declared label are treated as distinct (and therefore out-of-set),
+     * deliberately. `uniqueItems` at the schema layer is likewise
+     * exact-match, so e.g. `["High", "high"]` is a legal (if unusual)
+     * two-label set; nothing here folds case or reconciles near-miss
+     * spelling. Silently normalizing would band-aid over a vendor-side
+     * inconsistency instead of surfacing it — a vendor emitting `"high"`
+     * when its manifest declares `"High"` is a vendor bug that should be
+     * refused loudly, not coerced into matching. Vendors own their exact
+     * label byte-for-byte; hosts never guess at reconciliation.
+     */
+    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
@@ -1745,6 +1810,64 @@ interface ManualOverrideImplementation {
 interface ExtractionPipelineImplementation {
     readonly type: "extraction-pipeline";
 }
+/**
+ * SYS-3036: declaration-only implementation for adapters that are
+ * executed entirely OUTSIDE the host application. An externally-
+ * orchestrated process (a partner-run ceremony, an out-of-band
+ * verification flow, etc.) completes its own extraction and PUSHES the
+ * result to the host's assertion-ingest surface, rather than the host
+ * pulling it via `fetch()`/`extract()` or a form submission. No code,
+ * no fetch(), no extract(); like `manual-override` and
+ * `extraction-pipeline`, the discriminator alone carries the meaning —
+ * the shape is intentionally empty beyond `type`.
+ *
+ * Ownership note: this type + its schema branch were previously a
+ * host-local extension (a runtime clone of the compiled schema with one
+ * extra `oneOf` branch bolted on) because core hadn't yet published the
+ * concept. Publishing it here means every host validates the SAME
+ * schema — no more per-host schema patches for this discriminator.
+ */
+interface ExternalAssertionImplementation {
+    readonly type: "external-assertion";
+}
+/**
+ * SYS-3036: how a registered adapter participates at execution time,
+ * derived purely from `implementation.type`. Published here (rather than
+ * re-derived per host) so every host classifies manifests identically:
+ *
+ *   - `Runnable` — the host loads (declarative) or dynamic-imports
+ *     (typescript) a `SourceAdapter`; the host's run loop executes it.
+ *   - `DeclarationOnly` — the manifest is pure declaration plane
+ *     (`form-intake`, `manual-override`, `extraction-pipeline`). No code
+ *     exists to load; the entry is registered so `list()`-style
+ *     consumers (field-authorization gating, provenance rendering,
+ *     diagnostics) see the manifest, and every execution path skips it.
+ *   - `ExternallyAsserted` — the manifest declares
+ *     `implementation.type: "external-assertion"`. Same "no code, host
+ *     never calls fetch()/extract()" shape as `DeclarationOnly`, but data
+ *     arrives via an external push rather than the host's own
+ *     extraction pipeline or form intake. Hosts that used to fork on
+ *     this case separately can safely fold it into the same "not
+ *     Runnable" branch that already skips `DeclarationOnly` entries.
+ *
+ * String values mirror the discriminators they classify so a logged
+ * `executionMode` reads naturally alongside `implementation.type`.
+ */
+declare enum AdapterExecutionMode {
+    Runnable = "runnable",
+    DeclarationOnly = "declaration-only",
+    ExternallyAsserted = "externally-asserted"
+}
+/**
+ * SYS-3036: classify a manifest's `implementation.type` into its
+ * `AdapterExecutionMode`. Exhaustive over every discriminator this
+ * version of `@finsys/core` publishes — the switch has an explicit case
+ * per type and THROWS on anything else (Ajv should already have refused
+ * an unrecognized discriminator at validation time, but a schema/host
+ * version skew must surface as a loud refusal here too, never as a
+ * silently-guessed mode; no fallback branch assigns one).
+ */
+declare function executionModeOf(manifest: Pick<AdapterManifest, "implementation">): AdapterExecutionMode;
 interface FieldMapEntry {
     /**
      * JSONPath expression into the raw payload. E.g.
@@ -1772,4 +1895,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, 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 };
+export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, AdapterExecutionMode, 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 ExternalAssertionImplementation, 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, executionModeOf, 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.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) {
@@ -11892,10 +11941,37 @@ 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)}`);
+    }
+  }
+}
 export {
   ADAPTER_CATEGORY_IDS,
   ALL_AGGREGATION_OPS,
   AdapterError,
+  AdapterExecutionMode,
   BASE_FIELD_SPECS,
   BasicFormField,
   DEFAULT_VALIDATOR_DEFINITIONS,
@@ -11929,6 +12005,7 @@ export {
   categoryForField,
   categorySchemaOf,
   evaluateExpression,
+  executionModeOf,
   extractTimePeriods,
   factOf,
   formatDocumentSize,