@ai-matrx/records 0.44.1 → 0.45.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog — @ai-matrx/records
 
+## 0.45.0
+
+**One coercion primitive: what a typed-in answer means to a Field, in one place.**
+
+AGENT-BUILDS-2's closing walk, 2026-09-21, found Ironclad Mobile Mechanic's public booking
+page **unbookable over any table with a number field**. A customer picked 2:00 PM, typed a
+2019 Honda CR-V, pressed "Book it" and read:
+
+> Vehicle Year takes a number, and it was given a string
+
+and got no appointment. A browser input hands over a STRING; a Field takes a value. The
+grid's paste and the CSV import each carried their own coercion — the two doors a STRANGER
+uses carried none.
+
+New, headless, and now the only body that answers the question:
+
+- **`fieldKindFor(field, kernel)`** — the ONE classifier (behaviour, modifiers, format, unit,
+  relation target, config). `@ai-matrx/records-ui`'s `editorKindFor` is this function with
+  the kernel File/Person ids bound, so the editor a person types into and the coercion
+  applied to what they typed cannot disagree about a column.
+- **`coerceTypedAnswer(field, raw, opts)`** — one string → the Field's value, or a refusal
+  naming the field **in plain words**, never its key. It coerces and never guesses: `0` for
+  "about twelve" is how a table quietly becomes untrue.
+- **`coerceTypedAnswers(fields, answers, opts)`** — a whole screen at once. Values already
+  of the right shape are left alone; keys the table has no Field for are REPORTED rather
+  than dropped, because naming an unknown key is the store's sentence to say.
+- **`CoercibleField`** — the structural shape the primitive needs, so `CaptureField` and the
+  Field documents `custom.form_public` / `custom.booking_public` publish to a stranger all
+  satisfy it. Demanding a whole `Field` is how the capture sheet kept its own `Number(raw)`.
+- **`FIELD_KINDS`** — the runtime list `FieldKind` is derived from, so a coverage test walks
+  the source of truth rather than a retyped copy.
+- **`ChoiceOptions`** moved here from records-ui, which re-exports it.
+
+*Consumer action:* none required — everything is additive. A host that coerces typed-in text
+itself should delete that code and call `coerceTypedAnswer`.
+
 ## 0.43.0
 
 **The realtime port stops being half a contract, and a nudge re-reads only what moved.**

package/dist/core/index.cjs

@@ -40,6 +40,7 @@ __export(core_exports, {
   DELIVERIES: () => DELIVERIES,
   DOORS: () => DOORS,
   ENTITY_TOKENS: () => ENTITY_TOKENS,
+  FIELD_KINDS: () => FIELD_KINDS,
   FIELD_SENSITIVITIES: () => FIELD_SENSITIVITIES,
   FIELD_SOURCES: () => FIELD_SOURCES,
   FRESHNESS: () => FRESHNESS,
@@ -80,6 +81,9 @@ __export(core_exports, {
   choiceSlug: () => choiceSlug,
   choiceValuesOf: () => choiceValuesOf,
   choicesOf: () => choicesOf,
+  coerceTypedAnswer: () => coerceTypedAnswer,
+  coerceTypedAnswers: () => coerceTypedAnswers,
+  coercionLabel: () => coercionLabel,
   createRecordsClient: () => createRecordsClient,
   doorAbsent: () => doorAbsent,
   doorCensus: () => doorCensus,
@@ -87,6 +91,7 @@ __export(core_exports, {
   err: () => err,
   exportCsv: () => exportCsv,
   exportXlsx: () => exportXlsx,
+  fieldKindFor: () => fieldKindFor,
   forgetAllOps: () => forgetAllOps,
   highestLevel: () => highestLevel,
   holdsARetiredChoice: () => holdsARetiredChoice,
@@ -251,6 +256,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"];