@ai-matrx/records 0.44.1 → 0.45.0

package/dist/index.d.cts

@@ -153,6 +153,129 @@ declare function holdsARetiredChoice(document: RecordDocument | undefined, field
 /** True when a token looks like a uuid — which a choice value is no longer allowed to be. */
 declare function looksLikeAnId(value: unknown): boolean;
 
+/**
+ * EVERYTHING THIS FILE NEEDS TO KNOW ABOUT A FIELD, AND NOTHING ELSE.
+ *
+ * A full `Field` satisfies it, and so does every narrower shape the store
+ * hands to a screen — `CaptureField` on a phone with no network, the Field
+ * documents `custom.form_public` and `custom.booking_public` publish to a
+ * stranger. Asking for the whole `Field` would have meant the capture sheet
+ * keeping its own `Number(raw)`, which is exactly the duplication this file
+ * exists to end.
+ */
+interface CoercibleField {
+    /** Named so the doc above is checkable: a full {@link Field} satisfies this. */
+    key: string;
+    label?: string | null;
+    name?: string | null;
+    /** FLD-1. One of five behaviours; an unknown word is treated as text. */
+    type?: string | null;
+    multi?: boolean | null;
+    unit?: string | null;
+    format?: string | null;
+    config?: Record<string, unknown> | null | undefined;
+    relation_target?: string | null;
+}
+/**
+ * The kind of value one Field holds, resolved from its DECLARATION only — the
+ * behaviour, the modifiers, the format, the relation target and the config,
+ * because those are what the store stores. A screen that guessed from a value
+ * would answer differently for an empty record.
+ *
+ * `plain_text`, `long_text`, `number` and `boolean` are behaviours that carry
+ * no parity type of their own; every other word here is a parity type.
+ */
+declare const FIELD_KINDS: readonly ["attachment", "checkbox", "currency", "datetime", "email", "formula", "json", "long_text", "lookup", "member", "multi_select", "number", "percent", "phone", "relation", "rollup", "select", "text", "url"];
+/**
+ * 🚨 THE UNION IS DERIVED FROM THE LIST ABOVE, and the list is what the
+ * coverage test walks. Add a kind here and the test drives it; give it no arm
+ * in `coerceTypedAnswer` and the test says so, instead of the new kind falling
+ * quietly through `default:` and a value of the wrong shape reaching the store
+ * — which is the whole defect this file closes.
+ */
+type FieldKind = (typeof FIELD_KINDS)[number];
+/** The kernel Table ids REC-31 pins the two special relations to. */
+interface KernelTargets {
+    /** The kernel `File` Table — a relation pointing here is an attachment. */
+    file?: string | undefined;
+    /** The kernel `Person` Table — a relation pointing here names a person. */
+    person?: string | undefined;
+}
+/**
+ * Which kind of value this Field holds.
+ *
+ * This is the ONE classifier. `@ai-matrx/records-ui`'s `editorKindFor` — which
+ * decides which editor to DRAW — delegates to it, so the editor a person types
+ * into and the coercion applied to what they typed can never disagree about
+ * the same column. They did disagree before this moved here; that is the whole
+ * class of grid defect September was spent closing.
+ */
+declare function fieldKindFor(field: CoercibleField, kernel?: KernelTargets): FieldKind;
+/** One Field's options, indexed the way a typed word has to be looked up. */
+interface ChoiceOptions {
+    /**
+     * Lower-cased label, option key and option id, each pointing at the OPTION
+     * RECORD'S ID — which is what a list Field stores (FLD-5/FLD-6).
+     */
+    byWord: Map<string, string>;
+    /** The labels, in order, so a refusal can say what is on offer. */
+    labels: string[];
+}
+/** What one answer became, or the sentence saying why it did not. */
+type Coerced = {
+    value: unknown;
+} | {
+    refusal: string;
+    unmatched?: string[];
+};
+interface CoerceOptions {
+    /** This Field's choices, when the caller has loaded them. */
+    options?: ChoiceOptions | undefined;
+    /** The kernel File/Person Table ids, for classifying relations. */
+    kernel?: KernelTargets | undefined;
+    /**
+     * The Field's name as this caller writes it. Defaults to the Field's own
+     * label. A screen passes the same words it printed above the box.
+     */
+    label?: string | undefined;
+}
+/** The Field's name in plain words — never its key on a screen. */
+declare function coercionLabel(field: CoercibleField): string;
+/**
+ * Turn ONE typed-in string into the value this Field holds — or say, in a
+ * sentence a person can act on, why it is not one.
+ *
+ * An empty answer is `null` for every kind: a blank means "no answer here",
+ * and clearing a value is a thing a person means to do. Whether the Field may
+ * be blank is the store's question, asked with the Field's `required` and its
+ * Rules, not this one's.
+ */
+declare function coerceTypedAnswer(field: CoercibleField, raw: string, opts?: CoerceOptions): Coerced;
+/** What a whole set of typed-in answers became. */
+interface CoercedAnswers {
+    /** Ready to send to the store. Only the keys that coerced cleanly. */
+    values: Record<string, unknown>;
+    /** Field key → the sentence saying why that answer was not written. */
+    refusals: Record<string, string>;
+    /** The field keys the caller sent that this table has no Field for. */
+    unknownKeys: string[];
+}
+/**
+ * Every typed-in answer on one screen, coerced together — the shape the two
+ * public doors and the import wizard actually need.
+ *
+ * Keys the table has no Field for are reported rather than dropped: the store
+ * refuses an unknown key by name and a caller that quietly deleted it would
+ * hide a real mismatch between a page and its table.
+ */
+declare function coerceTypedAnswers(fields: readonly CoercibleField[], answers: Readonly<Record<string, unknown>>, opts?: {
+    kernel?: KernelTargets | undefined;
+    /** Choices per Field key, for the list columns. */
+    options?: ReadonlyMap<string, ChoiceOptions> | undefined;
+    /** Field key → the words that screen printed above the box. */
+    labels?: Readonly<Record<string, string>> | undefined;
+}): CoercedAnswers;
+
 /** The seven table types. Only these two carry custom fields (REC-34, DD-011). */
 type CustomFieldTableType = "entity" | "detail";
 /** What `custom.entity_table` answers about a registry token. */
@@ -2894,4 +3017,4 @@ interface ConversationScopeContext {
 /** `About: Acme Industrial` — the chip a bound chat wears. */
 declare function scopeChip(scope: ConversationScope): string;
 
-export { Actor, type AggregateBucket, type AggregateFilter, type AggregateMeasure, type AggregateOperation, type AggregateRow, type AggregateWindow, type AnonTokenBinding, type BookingAvailability, type BookingDeclared, type BookingSummary, type BookingWindow, type CaptureField, type CaptureFileRef, type CaptureOutcome, type CaptureQuestion, type CaptureQueue, type CaptureQueueCounts, type CaptureQueueOptions, type CaptureQueuePorts, type CaptureQueueStore, type CaptureSheetFace, type CaptureSheetSummary, type CaptureSyncReport, type ChecklistDeclared, type ChecklistRequirement, type ChecklistRequirementKind, type ChecklistRoleSpec, type ChecklistRunStarted, type ChecklistRunStep, type ChecklistRunSummary, type ChecklistSpec, type ChecklistStepCompleted, type ChecklistStepSpec, type ChecklistTemplateShape, type ChecklistTemplateSummary, type ChecklistTrigger, type ChecklistTriggerKind, type ChoiceOption, type CommentThreadRead, type CommentWritten, type ConversationScope, type ConversationScopeContext, type CustomFieldTableType, type DashboardBlock, type DashboardBlockKind, type DashboardBlockResult, type DashboardRunResult, type DashboardSummary, Delivery, type DigestPreview, type DocRenderRow, type DocSignatureCheck, type DocSignatureRow, type DocTemplateRow, type DocToken, type DocUnresolvedToken, type EnrichAlternate, type EnrichCell, type EnrichDeclared, type EnrichDueRow, type EnrichRun, type EnrichSource, type Enrichment, type EnrichmentSummary, type EntityFieldRights, type EntityFieldValue, type EntityRecordMatch, type EntityRecordRead, type EntityRecordsFound, type EntityTableFacts, type ExternalPrincipalCard, Field, type FieldHistoryEntry, type FormSummary, Freshness, type HistoryActor, type HistoryActorKind, type HistoryChange, type Home, type ImportBatchResult, type ImportColumnPlan, type ImportFinished, type ImportOpened, type ImportOutcome, type ImportPlan, type ImportPolicy, type ImportProposal, type ImportReport, type ImportRun, type InboundAddress, type InboundDeclared, type MergeField, MergeFieldModifier, type MergeFieldProvenance, type MergeFieldResolution, MergeFieldSemanticType, MergeFieldSource, type MergeFieldTransform, type MissingBehavior, type MyLevel, type MySubscription, type NewEntityFieldDeclaration, OnDelete, OverridePolicy, PERMISSION_LEVELS, PIPELINE_RULE_KINDS, ParityFieldType, type PermissionLevel, PgError, type Pipeline, type PipelineColumn, type PipelineDeclared, type PipelineGate, type PipelineGatePreview, type PipelineMissingField, type PipelineMoveResult, type PipelineRule, type PipelineRuleKind, type PipelineSpec, type PipelineStage, type PipelineVerdict, type PortalCard, type PortalInvitation, type PortalPreviewRow, type PortalPrincipal, type PortalRevocation, type PortalSummary, type PortalTableExposure, type PublishBinding, type QueuedCapture, type QueuedCaptureFile, type QueuedCaptureState, type QuietHours, REFUSALS_WORTH_REPEATING, type RecordComment, RecordDocument, type RecordHistoryEntry, type RecordScopeComment, type RecordScopeContext, type RecordScopeField, type RecordScopeHistoryEntry, type RecordScopeRelation, type RecordScopeWithheld, type RecordsActor, type RecordsChangeSink, type RecordsConfig, type RecordsDataSource, type RecordsErrorSink, type RecordsFilter, type RecordsRealtimePort, type RecordsResolverPort, type RecordsResponse, type RecordsTableQuery, type RegisteredTable, type Relation, RelationBinding, RelationCardinality, type RelationCarries, type RelationCoordinate, RelationFlavor, type RelationProperties, type RelationTarget, type ResolutionTriple, type ResolvedPublishBinding, type RestorePreview, type RestoreResult, type Rule, type RuleAnswer, type RuleExpression, RuleNodeKind, RuleUse, STAGE_RULE_ENFORCEMENT, STAGE_RULE_ON_FAIL, type SavedViewRow, type SavedViewSpecIn, type StagePending, type StagePendingOnBoard, type StageRuleEnforcement, type StageRuleOnFail, type StageRuleWarning, StorageMode, StoredRecord, type StuckRow, type Subscription, type SubscriptionBlock, type SubscriptionCadence, type SubscriptionSpec, type Table, type TableCapacity, TableDisplay, TableOrigin, TableType, Timestamp, Uuid, type WorkApprovalDecision, type WorkApprovalFiled, type WorkApprover, type WorkAssignment, type WorkAssignmentField, type WorkChange, type WorkDueState, type WorkGraph, type WorkInboxItem, type WorkInboxKind, type WorkInstantiation, type WorkListFlavour, type WorkListItem, type WorkOrigin, type WorkRecordState, type WorkSlotHold, type WorkState, type WorkTemplateNode, type WorkTemplateRelation, type WorkTurn, asPermissionLevel, atLeast, bookingPath, choiceSlug, choiceValuesOf, choicesOf, forgetAllOps, highestLevel, holdsARetiredChoice, indexedDbStore, isDecided, isOwnOp, isTheChosen, looksLikeAnId, mayDrag, measureKey, memoryStore, mintClientKey, mintOpId, openCaptureQueue, optionKey, optionLabel, portalPath, publicFormPath, rememberedOpCount, scopeChip };
+export { Actor, type AggregateBucket, type AggregateFilter, type AggregateMeasure, type AggregateOperation, type AggregateRow, type AggregateWindow, type AnonTokenBinding, type BookingAvailability, type BookingDeclared, type BookingSummary, type BookingWindow, type CaptureField, type CaptureFileRef, type CaptureOutcome, type CaptureQuestion, type CaptureQueue, type CaptureQueueCounts, type CaptureQueueOptions, type CaptureQueuePorts, type CaptureQueueStore, type CaptureSheetFace, type CaptureSheetSummary, type CaptureSyncReport, type ChecklistDeclared, type ChecklistRequirement, type ChecklistRequirementKind, type ChecklistRoleSpec, type ChecklistRunStarted, type ChecklistRunStep, type ChecklistRunSummary, type ChecklistSpec, type ChecklistStepCompleted, type ChecklistStepSpec, type ChecklistTemplateShape, type ChecklistTemplateSummary, type ChecklistTrigger, type ChecklistTriggerKind, type ChoiceOption, type ChoiceOptions, type CoerceOptions, type Coerced, type CoercedAnswers, type CoercibleField, type CommentThreadRead, type CommentWritten, type ConversationScope, type ConversationScopeContext, type CustomFieldTableType, type DashboardBlock, type DashboardBlockKind, type DashboardBlockResult, type DashboardRunResult, type DashboardSummary, Delivery, type DigestPreview, type DocRenderRow, type DocSignatureCheck, type DocSignatureRow, type DocTemplateRow, type DocToken, type DocUnresolvedToken, type EnrichAlternate, type EnrichCell, type EnrichDeclared, type EnrichDueRow, type EnrichRun, type EnrichSource, type Enrichment, type EnrichmentSummary, type EntityFieldRights, type EntityFieldValue, type EntityRecordMatch, type EntityRecordRead, type EntityRecordsFound, type EntityTableFacts, type ExternalPrincipalCard, FIELD_KINDS, Field, type FieldHistoryEntry, type FieldKind, type FormSummary, Freshness, type HistoryActor, type HistoryActorKind, type HistoryChange, type Home, type ImportBatchResult, type ImportColumnPlan, type ImportFinished, type ImportOpened, type ImportOutcome, type ImportPlan, type ImportPolicy, type ImportProposal, type ImportReport, type ImportRun, type InboundAddress, type InboundDeclared, type KernelTargets, type MergeField, MergeFieldModifier, type MergeFieldProvenance, type MergeFieldResolution, MergeFieldSemanticType, MergeFieldSource, type MergeFieldTransform, type MissingBehavior, type MyLevel, type MySubscription, type NewEntityFieldDeclaration, OnDelete, OverridePolicy, PERMISSION_LEVELS, PIPELINE_RULE_KINDS, ParityFieldType, type PermissionLevel, PgError, type Pipeline, type PipelineColumn, type PipelineDeclared, type PipelineGate, type PipelineGatePreview, type PipelineMissingField, type PipelineMoveResult, type PipelineRule, type PipelineRuleKind, type PipelineSpec, type PipelineStage, type PipelineVerdict, type PortalCard, type PortalInvitation, type PortalPreviewRow, type PortalPrincipal, type PortalRevocation, type PortalSummary, type PortalTableExposure, type PublishBinding, type QueuedCapture, type QueuedCaptureFile, type QueuedCaptureState, type QuietHours, REFUSALS_WORTH_REPEATING, type RecordComment, RecordDocument, type RecordHistoryEntry, type RecordScopeComment, type RecordScopeContext, type RecordScopeField, type RecordScopeHistoryEntry, type RecordScopeRelation, type RecordScopeWithheld, type RecordsActor, type RecordsChangeSink, type RecordsConfig, type RecordsDataSource, type RecordsErrorSink, type RecordsFilter, type RecordsRealtimePort, type RecordsResolverPort, type RecordsResponse, type RecordsTableQuery, type RegisteredTable, type Relation, RelationBinding, RelationCardinality, type RelationCarries, type RelationCoordinate, RelationFlavor, type RelationProperties, type RelationTarget, type ResolutionTriple, type ResolvedPublishBinding, type RestorePreview, type RestoreResult, type Rule, type RuleAnswer, type RuleExpression, RuleNodeKind, RuleUse, STAGE_RULE_ENFORCEMENT, STAGE_RULE_ON_FAIL, type SavedViewRow, type SavedViewSpecIn, type StagePending, type StagePendingOnBoard, type StageRuleEnforcement, type StageRuleOnFail, type StageRuleWarning, StorageMode, StoredRecord, type StuckRow, type Subscription, type SubscriptionBlock, type SubscriptionCadence, type SubscriptionSpec, type Table, type TableCapacity, TableDisplay, TableOrigin, TableType, Timestamp, Uuid, type WorkApprovalDecision, type WorkApprovalFiled, type WorkApprover, type WorkAssignment, type WorkAssignmentField, type WorkChange, type WorkDueState, type WorkGraph, type WorkInboxItem, type WorkInboxKind, type WorkInstantiation, type WorkListFlavour, type WorkListItem, type WorkOrigin, type WorkRecordState, type WorkSlotHold, type WorkState, type WorkTemplateNode, type WorkTemplateRelation, type WorkTurn, asPermissionLevel, atLeast, bookingPath, choiceSlug, choiceValuesOf, choicesOf, coerceTypedAnswer, coerceTypedAnswers, coercionLabel, fieldKindFor, forgetAllOps, highestLevel, holdsARetiredChoice, indexedDbStore, isDecided, isOwnOp, isTheChosen, looksLikeAnId, mayDrag, measureKey, memoryStore, mintClientKey, mintOpId, openCaptureQueue, optionKey, optionLabel, portalPath, publicFormPath, rememberedOpCount, scopeChip };

package/dist/index.d.ts

@@ -153,6 +153,129 @@ declare function holdsARetiredChoice(document: RecordDocument | undefined, field
 /** True when a token looks like a uuid — which a choice value is no longer allowed to be. */
 declare function looksLikeAnId(value: unknown): boolean;
 
+/**
+ * EVERYTHING THIS FILE NEEDS TO KNOW ABOUT A FIELD, AND NOTHING ELSE.
+ *
+ * A full `Field` satisfies it, and so does every narrower shape the store
+ * hands to a screen — `CaptureField` on a phone with no network, the Field
+ * documents `custom.form_public` and `custom.booking_public` publish to a
+ * stranger. Asking for the whole `Field` would have meant the capture sheet
+ * keeping its own `Number(raw)`, which is exactly the duplication this file
+ * exists to end.
+ */
+interface CoercibleField {
+    /** Named so the doc above is checkable: a full {@link Field} satisfies this. */
+    key: string;
+    label?: string | null;
+    name?: string | null;
+    /** FLD-1. One of five behaviours; an unknown word is treated as text. */
+    type?: string | null;
+    multi?: boolean | null;
+    unit?: string | null;
+    format?: string | null;
+    config?: Record<string, unknown> | null | undefined;
+    relation_target?: string | null;
+}
+/**
+ * The kind of value one Field holds, resolved from its DECLARATION only — the
+ * behaviour, the modifiers, the format, the relation target and the config,
+ * because those are what the store stores. A screen that guessed from a value
+ * would answer differently for an empty record.
+ *
+ * `plain_text`, `long_text`, `number` and `boolean` are behaviours that carry
+ * no parity type of their own; every other word here is a parity type.
+ */
+declare const FIELD_KINDS: readonly ["attachment", "checkbox", "currency", "datetime", "email", "formula", "json", "long_text", "lookup", "member", "multi_select", "number", "percent", "phone", "relation", "rollup", "select", "text", "url"];
+/**
+ * 🚨 THE UNION IS DERIVED FROM THE LIST ABOVE, and the list is what the
+ * coverage test walks. Add a kind here and the test drives it; give it no arm
+ * in `coerceTypedAnswer` and the test says so, instead of the new kind falling
+ * quietly through `default:` and a value of the wrong shape reaching the store
+ * — which is the whole defect this file closes.
+ */
+type FieldKind = (typeof FIELD_KINDS)[number];
+/** The kernel Table ids REC-31 pins the two special relations to. */
+interface KernelTargets {
+    /** The kernel `File` Table — a relation pointing here is an attachment. */
+    file?: string | undefined;
+    /** The kernel `Person` Table — a relation pointing here names a person. */
+    person?: string | undefined;
+}
+/**
+ * Which kind of value this Field holds.
+ *
+ * This is the ONE classifier. `@ai-matrx/records-ui`'s `editorKindFor` — which
+ * decides which editor to DRAW — delegates to it, so the editor a person types
+ * into and the coercion applied to what they typed can never disagree about
+ * the same column. They did disagree before this moved here; that is the whole
+ * class of grid defect September was spent closing.
+ */
+declare function fieldKindFor(field: CoercibleField, kernel?: KernelTargets): FieldKind;
+/** One Field's options, indexed the way a typed word has to be looked up. */
+interface ChoiceOptions {
+    /**
+     * Lower-cased label, option key and option id, each pointing at the OPTION
+     * RECORD'S ID — which is what a list Field stores (FLD-5/FLD-6).
+     */
+    byWord: Map<string, string>;
+    /** The labels, in order, so a refusal can say what is on offer. */
+    labels: string[];
+}
+/** What one answer became, or the sentence saying why it did not. */
+type Coerced = {
+    value: unknown;
+} | {
+    refusal: string;
+    unmatched?: string[];
+};
+interface CoerceOptions {
+    /** This Field's choices, when the caller has loaded them. */
+    options?: ChoiceOptions | undefined;
+    /** The kernel File/Person Table ids, for classifying relations. */
+    kernel?: KernelTargets | undefined;
+    /**
+     * The Field's name as this caller writes it. Defaults to the Field's own
+     * label. A screen passes the same words it printed above the box.
+     */
+    label?: string | undefined;
+}
+/** The Field's name in plain words — never its key on a screen. */
+declare function coercionLabel(field: CoercibleField): string;
+/**
+ * Turn ONE typed-in string into the value this Field holds — or say, in a
+ * sentence a person can act on, why it is not one.
+ *
+ * An empty answer is `null` for every kind: a blank means "no answer here",
+ * and clearing a value is a thing a person means to do. Whether the Field may
+ * be blank is the store's question, asked with the Field's `required` and its
+ * Rules, not this one's.
+ */
+declare function coerceTypedAnswer(field: CoercibleField, raw: string, opts?: CoerceOptions): Coerced;
+/** What a whole set of typed-in answers became. */
+interface CoercedAnswers {
+    /** Ready to send to the store. Only the keys that coerced cleanly. */
+    values: Record<string, unknown>;
+    /** Field key → the sentence saying why that answer was not written. */
+    refusals: Record<string, string>;
+    /** The field keys the caller sent that this table has no Field for. */
+    unknownKeys: string[];
+}
+/**
+ * Every typed-in answer on one screen, coerced together — the shape the two
+ * public doors and the import wizard actually need.
+ *
+ * Keys the table has no Field for are reported rather than dropped: the store
+ * refuses an unknown key by name and a caller that quietly deleted it would
+ * hide a real mismatch between a page and its table.
+ */
+declare function coerceTypedAnswers(fields: readonly CoercibleField[], answers: Readonly<Record<string, unknown>>, opts?: {
+    kernel?: KernelTargets | undefined;
+    /** Choices per Field key, for the list columns. */
+    options?: ReadonlyMap<string, ChoiceOptions> | undefined;
+    /** Field key → the words that screen printed above the box. */
+    labels?: Readonly<Record<string, string>> | undefined;
+}): CoercedAnswers;
+
 /** The seven table types. Only these two carry custom fields (REC-34, DD-011). */
 type CustomFieldTableType = "entity" | "detail";
 /** What `custom.entity_table` answers about a registry token. */
@@ -2894,4 +3017,4 @@ interface ConversationScopeContext {
 /** `About: Acme Industrial` — the chip a bound chat wears. */
 declare function scopeChip(scope: ConversationScope): string;
 
-export { Actor, type AggregateBucket, type AggregateFilter, type AggregateMeasure, type AggregateOperation, type AggregateRow, type AggregateWindow, type AnonTokenBinding, type BookingAvailability, type BookingDeclared, type BookingSummary, type BookingWindow, type CaptureField, type CaptureFileRef, type CaptureOutcome, type CaptureQuestion, type CaptureQueue, type CaptureQueueCounts, type CaptureQueueOptions, type CaptureQueuePorts, type CaptureQueueStore, type CaptureSheetFace, type CaptureSheetSummary, type CaptureSyncReport, type ChecklistDeclared, type ChecklistRequirement, type ChecklistRequirementKind, type ChecklistRoleSpec, type ChecklistRunStarted, type ChecklistRunStep, type ChecklistRunSummary, type ChecklistSpec, type ChecklistStepCompleted, type ChecklistStepSpec, type ChecklistTemplateShape, type ChecklistTemplateSummary, type ChecklistTrigger, type ChecklistTriggerKind, type ChoiceOption, type CommentThreadRead, type CommentWritten, type ConversationScope, type ConversationScopeContext, type CustomFieldTableType, type DashboardBlock, type DashboardBlockKind, type DashboardBlockResult, type DashboardRunResult, type DashboardSummary, Delivery, type DigestPreview, type DocRenderRow, type DocSignatureCheck, type DocSignatureRow, type DocTemplateRow, type DocToken, type DocUnresolvedToken, type EnrichAlternate, type EnrichCell, type EnrichDeclared, type EnrichDueRow, type EnrichRun, type EnrichSource, type Enrichment, type EnrichmentSummary, type EntityFieldRights, type EntityFieldValue, type EntityRecordMatch, type EntityRecordRead, type EntityRecordsFound, type EntityTableFacts, type ExternalPrincipalCard, Field, type FieldHistoryEntry, type FormSummary, Freshness, type HistoryActor, type HistoryActorKind, type HistoryChange, type Home, type ImportBatchResult, type ImportColumnPlan, type ImportFinished, type ImportOpened, type ImportOutcome, type ImportPlan, type ImportPolicy, type ImportProposal, type ImportReport, type ImportRun, type InboundAddress, type InboundDeclared, type MergeField, MergeFieldModifier, type MergeFieldProvenance, type MergeFieldResolution, MergeFieldSemanticType, MergeFieldSource, type MergeFieldTransform, type MissingBehavior, type MyLevel, type MySubscription, type NewEntityFieldDeclaration, OnDelete, OverridePolicy, PERMISSION_LEVELS, PIPELINE_RULE_KINDS, ParityFieldType, type PermissionLevel, PgError, type Pipeline, type PipelineColumn, type PipelineDeclared, type PipelineGate, type PipelineGatePreview, type PipelineMissingField, type PipelineMoveResult, type PipelineRule, type PipelineRuleKind, type PipelineSpec, type PipelineStage, type PipelineVerdict, type PortalCard, type PortalInvitation, type PortalPreviewRow, type PortalPrincipal, type PortalRevocation, type PortalSummary, type PortalTableExposure, type PublishBinding, type QueuedCapture, type QueuedCaptureFile, type QueuedCaptureState, type QuietHours, REFUSALS_WORTH_REPEATING, type RecordComment, RecordDocument, type RecordHistoryEntry, type RecordScopeComment, type RecordScopeContext, type RecordScopeField, type RecordScopeHistoryEntry, type RecordScopeRelation, type RecordScopeWithheld, type RecordsActor, type RecordsChangeSink, type RecordsConfig, type RecordsDataSource, type RecordsErrorSink, type RecordsFilter, type RecordsRealtimePort, type RecordsResolverPort, type RecordsResponse, type RecordsTableQuery, type RegisteredTable, type Relation, RelationBinding, RelationCardinality, type RelationCarries, type RelationCoordinate, RelationFlavor, type RelationProperties, type RelationTarget, type ResolutionTriple, type ResolvedPublishBinding, type RestorePreview, type RestoreResult, type Rule, type RuleAnswer, type RuleExpression, RuleNodeKind, RuleUse, STAGE_RULE_ENFORCEMENT, STAGE_RULE_ON_FAIL, type SavedViewRow, type SavedViewSpecIn, type StagePending, type StagePendingOnBoard, type StageRuleEnforcement, type StageRuleOnFail, type StageRuleWarning, StorageMode, StoredRecord, type StuckRow, type Subscription, type SubscriptionBlock, type SubscriptionCadence, type SubscriptionSpec, type Table, type TableCapacity, TableDisplay, TableOrigin, TableType, Timestamp, Uuid, type WorkApprovalDecision, type WorkApprovalFiled, type WorkApprover, type WorkAssignment, type WorkAssignmentField, type WorkChange, type WorkDueState, type WorkGraph, type WorkInboxItem, type WorkInboxKind, type WorkInstantiation, type WorkListFlavour, type WorkListItem, type WorkOrigin, type WorkRecordState, type WorkSlotHold, type WorkState, type WorkTemplateNode, type WorkTemplateRelation, type WorkTurn, asPermissionLevel, atLeast, bookingPath, choiceSlug, choiceValuesOf, choicesOf, forgetAllOps, highestLevel, holdsARetiredChoice, indexedDbStore, isDecided, isOwnOp, isTheChosen, looksLikeAnId, mayDrag, measureKey, memoryStore, mintClientKey, mintOpId, openCaptureQueue, optionKey, optionLabel, portalPath, publicFormPath, rememberedOpCount, scopeChip };
+export { Actor, type AggregateBucket, type AggregateFilter, type AggregateMeasure, type AggregateOperation, type AggregateRow, type AggregateWindow, type AnonTokenBinding, type BookingAvailability, type BookingDeclared, type BookingSummary, type BookingWindow, type CaptureField, type CaptureFileRef, type CaptureOutcome, type CaptureQuestion, type CaptureQueue, type CaptureQueueCounts, type CaptureQueueOptions, type CaptureQueuePorts, type CaptureQueueStore, type CaptureSheetFace, type CaptureSheetSummary, type CaptureSyncReport, type ChecklistDeclared, type ChecklistRequirement, type ChecklistRequirementKind, type ChecklistRoleSpec, type ChecklistRunStarted, type ChecklistRunStep, type ChecklistRunSummary, type ChecklistSpec, type ChecklistStepCompleted, type ChecklistStepSpec, type ChecklistTemplateShape, type ChecklistTemplateSummary, type ChecklistTrigger, type ChecklistTriggerKind, type ChoiceOption, type ChoiceOptions, type CoerceOptions, type Coerced, type CoercedAnswers, type CoercibleField, type CommentThreadRead, type CommentWritten, type ConversationScope, type ConversationScopeContext, type CustomFieldTableType, type DashboardBlock, type DashboardBlockKind, type DashboardBlockResult, type DashboardRunResult, type DashboardSummary, Delivery, type DigestPreview, type DocRenderRow, type DocSignatureCheck, type DocSignatureRow, type DocTemplateRow, type DocToken, type DocUnresolvedToken, type EnrichAlternate, type EnrichCell, type EnrichDeclared, type EnrichDueRow, type EnrichRun, type EnrichSource, type Enrichment, type EnrichmentSummary, type EntityFieldRights, type EntityFieldValue, type EntityRecordMatch, type EntityRecordRead, type EntityRecordsFound, type EntityTableFacts, type ExternalPrincipalCard, FIELD_KINDS, Field, type FieldHistoryEntry, type FieldKind, type FormSummary, Freshness, type HistoryActor, type HistoryActorKind, type HistoryChange, type Home, type ImportBatchResult, type ImportColumnPlan, type ImportFinished, type ImportOpened, type ImportOutcome, type ImportPlan, type ImportPolicy, type ImportProposal, type ImportReport, type ImportRun, type InboundAddress, type InboundDeclared, type KernelTargets, type MergeField, MergeFieldModifier, type MergeFieldProvenance, type MergeFieldResolution, MergeFieldSemanticType, MergeFieldSource, type MergeFieldTransform, type MissingBehavior, type MyLevel, type MySubscription, type NewEntityFieldDeclaration, OnDelete, OverridePolicy, PERMISSION_LEVELS, PIPELINE_RULE_KINDS, ParityFieldType, type PermissionLevel, PgError, type Pipeline, type PipelineColumn, type PipelineDeclared, type PipelineGate, type PipelineGatePreview, type PipelineMissingField, type PipelineMoveResult, type PipelineRule, type PipelineRuleKind, type PipelineSpec, type PipelineStage, type PipelineVerdict, type PortalCard, type PortalInvitation, type PortalPreviewRow, type PortalPrincipal, type PortalRevocation, type PortalSummary, type PortalTableExposure, type PublishBinding, type QueuedCapture, type QueuedCaptureFile, type QueuedCaptureState, type QuietHours, REFUSALS_WORTH_REPEATING, type RecordComment, RecordDocument, type RecordHistoryEntry, type RecordScopeComment, type RecordScopeContext, type RecordScopeField, type RecordScopeHistoryEntry, type RecordScopeRelation, type RecordScopeWithheld, type RecordsActor, type RecordsChangeSink, type RecordsConfig, type RecordsDataSource, type RecordsErrorSink, type RecordsFilter, type RecordsRealtimePort, type RecordsResolverPort, type RecordsResponse, type RecordsTableQuery, type RegisteredTable, type Relation, RelationBinding, RelationCardinality, type RelationCarries, type RelationCoordinate, RelationFlavor, type RelationProperties, type RelationTarget, type ResolutionTriple, type ResolvedPublishBinding, type RestorePreview, type RestoreResult, type Rule, type RuleAnswer, type RuleExpression, RuleNodeKind, RuleUse, STAGE_RULE_ENFORCEMENT, STAGE_RULE_ON_FAIL, type SavedViewRow, type SavedViewSpecIn, type StagePending, type StagePendingOnBoard, type StageRuleEnforcement, type StageRuleOnFail, type StageRuleWarning, StorageMode, StoredRecord, type StuckRow, type Subscription, type SubscriptionBlock, type SubscriptionCadence, type SubscriptionSpec, type Table, type TableCapacity, TableDisplay, TableOrigin, TableType, Timestamp, Uuid, type WorkApprovalDecision, type WorkApprovalFiled, type WorkApprover, type WorkAssignment, type WorkAssignmentField, type WorkChange, type WorkDueState, type WorkGraph, type WorkInboxItem, type WorkInboxKind, type WorkInstantiation, type WorkListFlavour, type WorkListItem, type WorkOrigin, type WorkRecordState, type WorkSlotHold, type WorkState, type WorkTemplateNode, type WorkTemplateRelation, type WorkTurn, asPermissionLevel, atLeast, bookingPath, choiceSlug, choiceValuesOf, choicesOf, coerceTypedAnswer, coerceTypedAnswers, coercionLabel, fieldKindFor, forgetAllOps, highestLevel, holdsARetiredChoice, indexedDbStore, isDecided, isOwnOp, isTheChosen, looksLikeAnId, mayDrag, measureKey, memoryStore, mintClientKey, mintOpId, openCaptureQueue, optionKey, optionLabel, portalPath, publicFormPath, rememberedOpCount, scopeChip };

package/dist/index.js

@@ -124,6 +124,209 @@ function looksLikeAnId(value) {
   return typeof value === "string" && UUID.test(value);
 }
 
+// src/coerce.ts
+var FIELD_KINDS = [
+  "attachment",
+  "checkbox",
+  "currency",
+  "datetime",
+  "email",
+  "formula",
+  "json",
+  "long_text",
+  "lookup",
+  "member",
+  "multi_select",
+  "number",
+  "percent",
+  "phone",
+  "relation",
+  "rollup",
+  "select",
+  "text",
+  "url"
+];
+function fieldKindFor(field, kernel) {
+  const format = (field.format ?? "").toLowerCase();
+  const config = field.config ?? {};
+  switch (field.type) {
+    case "boolean":
+      return "checkbox";
+    case "text":
+      if (format === "email") return "email";
+      if (format === "phone") return "phone";
+      if (format === "url") return "url";
+      if (format === "json" || config["json"] === true) return "json";
+      if (format === "long" || config["multiline"] === true) return "long_text";
+      return "text";
+    case "range": {
+      const kind = String(config["kind"] ?? "number");
+      if (kind === "date" || kind === "datetime") return "datetime";
+      if (format === "currency") return "currency";
+      if (format === "percent" || field.unit === "%") return "percent";
+      return "number";
+    }
+    case "list":
+      return field.multi ? "multi_select" : "select";
+    case "relation": {
+      const parity = String(config["parity"] ?? "");
+      if (parity === "attachment" || parity === "member") return parity;
+      if (kernel?.file && field.relation_target === kernel.file) return "attachment";
+      if (kernel?.person && field.relation_target === kernel.person) return "member";
+      return "relation";
+    }
+    case "formula": {
+      const via = config["via"];
+      if (via && config["agg"]) return "rollup";
+      if (via) return "lookup";
+      return "formula";
+    }
+    default:
+      return "text";
+  }
+}
+var TRUE_WORDS = /* @__PURE__ */ new Set(["true", "yes", "y", "1", "\u2713", "x", "checked", "on"]);
+var FALSE_WORDS = /* @__PURE__ */ new Set(["false", "no", "n", "0", "", "unchecked", "off"]);
+function coercionLabel(field) {
+  const label = (field.label ?? "").trim();
+  if (label !== "") return label;
+  const name = (field.name ?? "").trim();
+  if (name !== "") return name;
+  return field.key.replace(/[_-]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()).trim();
+}
+function coerceTypedAnswer(field, raw, opts = {}) {
+  const label = opts.label ?? coercionLabel(field);
+  const text = raw.trim();
+  const kind = fieldKindFor(field, opts.kernel);
+  if (text === "" && kind !== "checkbox") return { value: null };
+  switch (kind) {
+    case "checkbox": {
+      const word = text.toLowerCase();
+      if (TRUE_WORDS.has(word)) return { value: true };
+      if (FALSE_WORDS.has(word)) return { value: word === "" ? null : false };
+      return {
+        refusal: `${label} is a tick box, so it takes yes or no \u2014 \u201C${raw}\u201D is neither. Write TRUE/FALSE, yes/no or 1/0.`
+      };
+    }
+    case "number":
+    case "currency":
+    case "percent": {
+      const negative = /^\(.*\)$/.test(text);
+      const bare = text.replace(/^\(|\)$/g, "").replace(/[\s,]/g, "").replace(/^[^\d.\-+]+/, "").replace(/[^\d.\-+eE]+$/, "");
+      const n = Number(bare);
+      if (bare === "" || Number.isNaN(n)) {
+        return {
+          refusal: `${label} holds a number, and \u201C${raw}\u201D is not one. Write digits \u2014 a currency symbol, a percent sign, commas and brackets for a negative are all fine.`
+        };
+      }
+      return { value: negative ? -n : n };
+    }
+    case "datetime": {
+      const wantsTime = String(field.config?.["kind"] ?? "date") === "datetime";
+      const plainDay = /^\s*(\d{4})-(\d{2})-(\d{2})\s*$/.exec(raw);
+      if (!wantsTime && plainDay) return { value: `${plainDay[1]}-${plainDay[2]}-${plainDay[3]}` };
+      const at = Date.parse(text);
+      if (Number.isNaN(at)) {
+        return {
+          refusal: `${label} holds a date, and \u201C${raw}\u201D is not one this can read. Write it as 2026-09-21, or the way your spreadsheet writes dates.`
+        };
+      }
+      const parsed = new Date(at);
+      if (wantsTime) return { value: parsed.toISOString() };
+      const y = parsed.getFullYear();
+      const m = String(parsed.getMonth() + 1).padStart(2, "0");
+      const d = String(parsed.getDate()).padStart(2, "0");
+      return { value: `${y}-${m}-${d}` };
+    }
+    case "json": {
+      try {
+        return { value: JSON.parse(text) };
+      } catch {
+        return {
+          refusal: `${label} holds a document, and \u201C${raw}\u201D is not valid JSON. Write the whole object, braces and all.`
+        };
+      }
+    }
+    case "select":
+    case "multi_select": {
+      if (!opts.options) {
+        return {
+          refusal: `${label} is a list and its options have not been read yet, so nothing can be matched to \u201C${raw}\u201D. Try again once the column's choices have loaded.`
+        };
+      }
+      const wanted = kind === "multi_select" ? text.split(/[,;]/).map((w) => w.trim()).filter((w) => w.length > 0) : [text];
+      if (wanted.length === 0) return { value: kind === "multi_select" ? [] : null };
+      const matched = [];
+      const unmatched = [];
+      for (const word of wanted) {
+        const hit = opts.options.byWord.get(word.toLowerCase());
+        if (hit === void 0) unmatched.push(word);
+        else matched.push(hit);
+      }
+      if (unmatched.length > 0) {
+        const offered = opts.options.labels.length > 0 ? opts.options.labels.join(", ") : "it has none yet";
+        return {
+          refusal: `${label} does not have ${unmatched.map((w) => `\u201C${w}\u201D`).join(" or ")} among its options. It offers: ${offered}.`,
+          unmatched
+        };
+      }
+      return { value: kind === "multi_select" ? matched : matched[0] };
+    }
+    // AN IDENTITY IS NOT A WORD. Writing the word would put a string where an
+    // id belongs, and every filter, colour and rollup built on that column
+    // would stop agreeing with it. So it is refused and the person is told
+    // which control does hold it.
+    case "member":
+      return {
+        refusal: `${label} names a person in this organization, so it is chosen rather than typed. Open it and pick them.`
+      };
+    case "attachment":
+      return {
+        refusal: `${label} holds a file, which cannot arrive as typed-in text. Open it and attach the file.`
+      };
+    case "relation":
+      return {
+        refusal: `${label} points at another record, so it is chosen rather than typed. Open it and pick the record.`
+      };
+    case "formula":
+    case "lookup":
+    case "rollup":
+      return {
+        refusal: `${label} is worked out by the system, so nothing can be written into it.`
+      };
+    default:
+      return { value: raw };
+  }
+}
+function coerceTypedAnswers(fields, answers, opts = {}) {
+  const byKey = new Map(fields.map((f) => [f.key, f]));
+  const values = {};
+  const refusals = {};
+  const unknownKeys = [];
+  for (const [key, given] of Object.entries(answers)) {
+    const field = byKey.get(key);
+    if (!field) {
+      unknownKeys.push(key);
+      values[key] = given;
+      continue;
+    }
+    if (typeof given !== "string") {
+      values[key] = given;
+      continue;
+    }
+    const opt = {};
+    const choices = opts.options?.get(key);
+    if (choices) opt.options = choices;
+    if (opts.kernel) opt.kernel = opts.kernel;
+    const label = opts.labels?.[key];
+    if (label) opt.label = label;
+    const answered = coerceTypedAnswer(field, given, opt);
+    if ("refusal" in answered) refusals[key] = answered.refusal;
+    else values[key] = answered.value;
+  }
+  return { values, refusals, unknownKeys };
+}
+
 // src/pipeline.ts
 var PIPELINE_RULE_KINDS = ["moves", "requires", "who", "limit", "entry"];
 var STAGE_RULE_ON_FAIL = ["refuse", "require_approval"];
@@ -2201,6 +2404,7 @@ export {
   CONTEXT_POLICIES,
   DELIVERIES,
   ENTITY_TOKENS,
+  FIELD_KINDS,
   FIELD_SENSITIVITIES,
   FIELD_SOURCES,
   FRESHNESS,
@@ -2238,7 +2442,11 @@ export {
   choiceSlug,
   choiceValuesOf,
   choicesOf,
+  coerceTypedAnswer,
+  coerceTypedAnswers,
+  coercionLabel,
   err,
+  fieldKindFor,
   forgetAllOps,
   highestLevel,
   holdsARetiredChoice,