@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/dataset-csv.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/dataset-csv.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Dataset CSV/JSON serialization (AGL-182). The predictable inverse of\n * `coerceDocumentValues`: ISO dates, `lat, lon` coordinates, comma-joined\n * lists, JSON maps, reference ids — so an export re-imports losslessly\n * through the same coercion.\n *\n * **Why this lives in core rather than in `@aglyn/plugins-data`** (AGL-2335).\n * AGL-413 moved dataset io out to the plugin, and the dataset-shaped half of\n * the import machinery — column mapping against a `DatasetModel` — is still\n * there, correctly: nothing outside that plugin maps a file onto a dataset.\n *\n * Writing one is different now. `/api/orgs/datasets/export` streams a\n * dataset from the server, and `scope:app` may not import a lib tagged\n * `aglyn:addons` — apps reach plugins only through the generated loader\n * manifests (AGL-417/419). The choice was a second copy of the escaper in\n * the console or one copy somewhere both may reach. There are already five\n * divergent hand-rolled CSV escapers in this repo; this is not becoming the\n * sixth. `dataset-io.ts` re-exports every name below, so the plugin's own\n * imports are unchanged.\n *\n * READING one is shared for the same reason. The email list importer parses\n * a merchant's contact file, and it lives in `@aglyn/plugins-email`, which\n * may not import `@aglyn/plugins-data` either. So {@link parseCsv} sits here\n * beside the escaper that is its inverse, and `dataset-io.ts` re-exports it\n * exactly as it re-exports the writing half.\n */\n\nimport type { DatasetFieldDefinition, DatasetModel } from './dataset-models'\n\n\n/** Storage value → portable string (CSV cell / JSON value). */\nexport function serializeDatasetValue(\n  field: DatasetFieldDefinition,\n  value: unknown,\n): string {\n  if (value == null) return ''\n  switch (field.type) {\n    case 'timestamp':\n      return typeof value === 'number' && Number.isFinite(value)\n        ? new Date(value).toISOString()\n        : String(value)\n    case 'coordinates': {\n      const coordinates = value as { latitude?: number; longitude?: number }\n      return coordinates &&\n        typeof coordinates.latitude === 'number' &&\n        typeof coordinates.longitude === 'number'\n        ? `${coordinates.latitude}, ${coordinates.longitude}`\n        : String(value)\n    }\n    case 'sorted':\n    case 'reference':\n      return Array.isArray(value) ? value.join(', ') : String(value)\n    case 'map':\n      try {\n        return JSON.stringify(value)\n      } catch {\n        return String(value)\n      }\n    default:\n      return String(value)\n  }\n}\n\nconst csvEscape = (cell: string): string =>\n  /[\",\\r\\n]/.test(cell) ? `\"${cell.replace(/\"/g, '\"\"')}\"` : cell\n\n/**\n * The header line — field ids, in model order (AGL-2335).\n *\n * Split out of {@link datasetRecordsToCsv} so a server export can emit the\n * file a page at a time. The whole point of that export is that it is not\n * bounded by what one process can hold in memory, and a helper that only\n * takes a complete `rows` array cannot serve it. Everything below shares\n * one escaper: there are already five divergent hand-rolled CSV escapers in\n * this repo and this is not becoming the sixth.\n */\nexport function datasetCsvHeader(model: DatasetModel): string {\n  return model.order.map(csvEscape).join(',')\n}\n\n/** One record's values (storage form) → one CSV line, no terminator. */\nexport function datasetCsvRow(\n  model: DatasetModel,\n  row: Record<string, unknown>,\n): string {\n  return model.order\n    .map((fieldId) => {\n      const field = model.fields[fieldId]\n      return csvEscape(field ? serializeDatasetValue(field, row[fieldId]) : '')\n    })\n    .join(',')\n}\n\n/** One record's values → the portable JSON object the JSON export emits. */\nexport function datasetRecordToJson(\n  model: DatasetModel,\n  row: Record<string, unknown>,\n): Record<string, string> {\n  return Object.fromEntries(\n    model.order.map((fieldId) => {\n      const field = model.fields[fieldId]\n      return [fieldId, field ? serializeDatasetValue(field, row[fieldId]) : '']\n    }),\n  )\n}\n\n/**\n * Data rows in a CSV document — the header excluded, quoted newlines not\n * counted as row breaks (AGL-2335).\n *\n * This exists so a download can be CHECKED against the row count the server\n * promised, rather than trusted. A truncated export is the defect this whole\n * area is about, and a stream that dies halfway produces a perfectly\n * well-formed shorter file: nothing about the bytes says they are short.\n *\n * Single pass, no array building — {@link parseCsv} answers the same\n * question but materializes every cell, which is the wrong trade when the\n * file may be hundreds of thousands of rows and the only thing wanted is\n * how many there are.\n */\nexport function countCsvDataRows(text: string): number {\n  const source = String(text ?? '')\n  if (!source) return 0\n  let rows = 0\n  let quoted = false\n  let cellsSeen = false\n  for (let index = 0; index < source.length; index += 1) {\n    const char = source[index]\n    if (quoted) {\n      if (char === '\"') {\n        if (source[index + 1] === '\"') index += 1\n        else quoted = false\n      }\n      cellsSeen = true\n      continue\n    }\n    if (char === '\"') {\n      quoted = true\n      cellsSeen = true\n      continue\n    }\n    if (char === '\\n') {\n      rows += 1\n      cellsSeen = false\n      continue\n    }\n    if (char !== '\\r') cellsSeen = true\n  }\n  // A file that does not end in a newline still has a final row.\n  if (cellsSeen) rows += 1\n  // The header is not data.\n  return Math.max(0, rows - 1)\n}\n\n/**\n * Did a downloaded export arrive whole? (AGL-2335)\n *\n * The server streams and reports its `count()` aggregate in a header, so the\n * client can CHECK rather than trust. This is the check, kept here as a pure\n * function because a guard living inline in a component is a guard nobody\n * can force red — and this one exists precisely to catch a silent shortfall.\n *\n * `short` is only true when the count is both KNOWN and lower. A missing or\n * unparseable header is not evidence of truncation, and refusing a download\n * on the strength of a header that never arrived would fail the user for the\n * server's bookkeeping. More rows than promised is not short either — the\n * count is a snapshot taken before the first page, so a concurrent insert\n * can legitimately overtake it.\n */\nexport function exportShortfall(\n  promisedHeader: string | null | undefined,\n  body: string,\n  format: 'csv' | 'json',\n): { promised: number; received: number; short: boolean } {\n  const promised = Number(promisedHeader)\n  let received: number\n  if (format === 'csv') {\n    received = countCsvDataRows(body)\n  } else {\n    try {\n      const parsed = JSON.parse(body) as unknown\n      received = Array.isArray(parsed) ? parsed.length : 0\n    } catch {\n      // A body that is not JSON at all did not arrive whole.\n      return { promised, received: 0, short: true }\n    }\n  }\n  return {\n    promised,\n    received,\n    short: Number.isFinite(promised) && promisedHeader != null && received < promised,\n  }\n}\n\n/** Rows (storage-form value maps) → CSV with a fieldId header row. */\nexport function datasetRecordsToCsv(\n  model: DatasetModel,\n  rows: Array<Record<string, unknown>>,\n): string {\n  return [\n    datasetCsvHeader(model),\n    ...rows.map((row) => datasetCsvRow(model, row)),\n  ].join('\\n')\n}\n\n/**\n * Minimal RFC-4180 CSV parser (quoted fields, escaped quotes, CRLF).\n *\n * The inverse of the escaper above, and the one parser in the repo — see the\n * module note for why the email list importer reaches this rather than\n * writing its own.\n *\n * A wholly blank row is dropped. Every spreadsheet writes a trailing newline\n * and a row of empty cells is not a record; carrying it through would give\n * every caller the same off-by-one to remember.\n */\nexport function parseCsv(text: string): string[][] {\n  const rows: string[][] = []\n  let row: string[] = []\n  let cell = ''\n  let quoted = false\n  const source = String(text ?? '')\n  for (let index = 0; index < source.length; index += 1) {\n    const char = source[index]\n    if (quoted) {\n      if (char === '\"') {\n        if (source[index + 1] === '\"') {\n          cell += '\"'\n          index += 1\n        } else {\n          quoted = false\n        }\n      } else {\n        cell += char\n      }\n      continue\n    }\n    if (char === '\"') {\n      quoted = true\n    } else if (char === ',') {\n      row.push(cell)\n      cell = ''\n    } else if (char === '\\n' || char === '\\r') {\n      if (char === '\\r' && source[index + 1] === '\\n') index += 1\n      row.push(cell)\n      cell = ''\n      rows.push(row)\n      row = []\n    } else {\n      cell += char\n    }\n  }\n  if (cell !== '' || row.length) {\n    row.push(cell)\n    rows.push(row)\n  }\n  return rows.filter((cells) => cells.some((value) => value.trim() !== ''))\n}\n\n"],"names":["serializeDatasetValue","field","value","type","Number","isFinite","Date","toISOString","String","coordinates","latitude","longitude","Array","isArray","join","JSON","stringify","csvEscape","cell","test","replace","datasetCsvHeader","model","order","map","datasetCsvRow","row","fieldId","fields","datasetRecordToJson","Object","fromEntries","countCsvDataRows","text","source","rows","quoted","cellsSeen","index","length","char","Math","max","exportShortfall","promisedHeader","body","format","promised","received","parsed","parse","short","datasetRecordsToCsv","parseCsv","push","filter","cells","some","trim"],"mappings":"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"}

package/src/lib/app-utils/dataset-models.d.ts

@@ -0,0 +1,194 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type DatasetFieldEntry } from './datasets';
+/**
+ * Dataset models (AGL-177): the runtime promotion of the type-level
+ * blueprint in `libs/shared/data/types/src/lib/dod.ts` (kept as the
+ * referenced design doc — this module is the single runtime source of
+ * truth). A model lives on the dataset doc
+ * (`orgs/{orgId}/datasets/{id}.model`) and drives the typed editor, import
+ * and site-restore validation, and the console and `/v1` record writes
+ * through the shared `validateDocument`/`coerceDocumentValues` pair so they
+ * can't disagree. Form submissions and automation steps write through
+ * `buildDatasetRecordValues` instead, which stores each value as text and
+ * validates nothing.
+ *
+ * Storage conventions (Firestore-safe): timestamps as epoch millis
+ * numbers, coordinates as `{ latitude, longitude }`, `sorted` as arrays,
+ * `map` as plain objects, references as target-document id strings.
+ */
+/** dod.ts `FT.Tag` vocabulary plus `reference` (AGL-180 builds on it). */
+export type DatasetFieldType = 'bool' | 'bytes' | 'timestamp' | 'float' | 'int32' | 'int64' | 'nil' | 'text' | 'coordinates' | 'map' | 'sorted' | 'reference';
+export declare const DATASET_FIELD_TYPES: DatasetFieldType[];
+/** Display names, mirroring dod.ts `lbl`. */
+export declare const DATASET_FIELD_TYPE_LABELS: Record<DatasetFieldType, string>;
+/**
+ * Plain-JSON validation vocabulary (the dod.ts `Eval` shape, extended
+ * with min/max and options, serialized flat instead of enum-keyed).
+ */
+export interface DatasetFieldValidation {
+    required?: boolean;
+    /** Source of a RegExp applied to text values. */
+    regex?: string;
+    /** Numbers/timestamps: value bound. Text: length bound. */
+    min?: number;
+    max?: number;
+    /** Enum: value must be one of these (text fields). */
+    options?: string[];
+}
+export interface DatasetFieldDefinition {
+    /**
+     * Human-facing display label only. The stable reference id is the KEY in
+     * `DatasetModel.fields` (and `order`), NOT this name — bindings resolve
+     * `{{item.<fieldId>}}` against that key. The default id is derived from
+     * this name once at creation but is user-overridable (AGL-578); renaming
+     * the label afterwards never changes the id.
+     */
+    name: string;
+    type: DatasetFieldType;
+    /**
+     * Plugin-declared custom type riding this base type (AGL-434) — see
+     * plugin-manager/custom-fields. Unknown names degrade to the base type.
+     */
+    customType?: string;
+    description?: string;
+    required?: boolean;
+    /** Default applied by editors when creating documents; never coerced. */
+    default?: unknown;
+    validation?: DatasetFieldValidation;
+    /**
+     * Reference fields (AGL-180): target collection + display field id.
+     * `multiple` stores a `sorted` array of FKeys (small-cardinality
+     * many-to-many per the dod.ts guidance); `onDelete` is the referenced-
+     * document delete policy (default `setNull` — never cascade in v2).
+     */
+    reference?: {
+        datasetId: string;
+        displayFieldId?: string;
+        multiple?: boolean;
+        onDelete?: 'restrict' | 'setNull';
+    };
+}
+export interface DatasetModel {
+    fields: Record<string, DatasetFieldDefinition>;
+    /** Field ids in display order. */
+    order: string[];
+}
+/**
+ * Migration shim (v1 → v2): datasets created before models carry flat
+ * `fields: string[]` — derive a model where every column is an optional
+ * text field whose id is the column name, so the editor and AGL-103
+ * bindings keep working on unmigrated docs during rollout.
+ */
+export declare function deriveModelFromFields(fields: string[]): DatasetModel;
+/**
+ * Model from quick-creator entries (AGL-558): stable slug ids with the
+ * human display names preserved — "Roast preference" → id
+ * `roast_preference`, name "Roast preference".
+ */
+export declare function modelFromFieldEntries(entries: readonly DatasetFieldEntry[]): DatasetModel;
+/** The dataset's model, deriving one from v1 `fields` when absent. */
+export declare function effectiveDatasetModel(dataset: {
+    model?: DatasetModel;
+    fields?: string[];
+}): DatasetModel;
+/**
+ * Validates a document's values against a model, returning fieldId →
+ * human-readable error (empty object = valid). Values are expected in
+ * storage form (see the module doc); use `coerceDocumentValues` first
+ * when starting from user input strings.
+ */
+export declare function validateDocument(model: DatasetModel, values: Record<string, unknown>): Record<string, string>;
+/** Storage value → grid display string (AGL-179). */
+export declare function formatDatasetValue(field: DatasetFieldDefinition, value: unknown): string;
+/**
+ * Storage value → form-input string (AGL-179): the inverse of
+ * `coerceDocumentValues` for populating type-appropriate inputs
+ * (timestamps as `datetime-local` values, coordinates as "lat, lon").
+ */
+export declare function datasetValueToInput(field: DatasetFieldDefinition, value: unknown): string;
+/**
+ * Coerces user-input strings (form fields, CSV cells) into storage form
+ * per the field type. Unparseable input is passed through untouched so
+ * `validateDocument` reports it instead of silently mangling it.
+ */
+export declare function coerceDocumentValues(model: DatasetModel, input: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Every reference id a record holds, flattened out of its `reference` fields
+ * into one de-duplicated list.
+ *
+ * A reference field stores either a single target id or — when
+ * `reference.multiple` is set — an array of them, and a model may declare
+ * several. Both shapes flatten into the same list because the question asked
+ * of it is never "which field", it is "does this record still point at that
+ * document".
+ *
+ * Fields are read from `order` UNIONED with the keys of `fields`. Every other
+ * pass over a model walks `order` alone, which is right for anything the user
+ * sees — but a reference declared without a display slot still holds a real
+ * FKey, and an integrity index that skipped it would under-report.
+ */
+export declare function datasetReferencedIds(model: DatasetModel, values: Record<string, unknown> | undefined): string[];
+/**
+ * The integrity index a record write carries, so referential integrity can be
+ * decided by a QUERY rather than by the rows a listener happened to fetch.
+ *
+ * Deleting a record has to answer "is anything still pointing at this?", and
+ * `restrict` refuses the delete on a yes while `setNull` strips the FKey. That
+ * question cannot be asked where the answer is stored: dataset fields are
+ * user-defined, so `records.values` carries a deliberate index exemption in
+ * `cloud/firebase-firestore.indexes.json` — auto-indexing an unbounded map
+ * blows Firestore's per-document index-entry limit — and
+ * `where('values.<fieldId>', '==', id)` is therefore FAILED_PRECONDITION.
+ * Reading a page of records and filtering them in the browser answers only for
+ * the rows in that page, which is a browse window standing in for a
+ * correctness check: a reference held outside it reads as no reference at all,
+ * the delete proceeds, and `restrict` silently fails to restrict.
+ *
+ * `referencedIds` is that same reference, denormalized to a top-level array
+ * Firestore will index, so one `array-contains` reaches every record.
+ *
+ * ⚠️ OMITTED when a record references nothing, rather than written as `[]`.
+ * `isNotEmpty` is served as `!= null` and an empty array is not null, so a
+ * record stamped `[]` answers "holds a reference" for a dataset that holds
+ * none.
+ *
+ * ⚠️ Spread this at EVERY write that sets a record's `values`. A write that
+ * sets values without it leaves the index describing the PREVIOUS values, and
+ * a stale integrity index is the exact failure it exists to prevent — with the
+ * UI reporting the record as safe to delete. On a merging write use
+ * `datasetIntegrityUpdate` instead: omission leaves a stale array in place
+ * where clearing the last reference has to remove the field.
+ */
+export declare function datasetIntegrityFields(model: DatasetModel, values: Record<string, unknown> | undefined): {
+    referencedIds?: string[];
+};
+/**
+ * `datasetIntegrityFields` for a MERGING write (`update`, `set` with `merge`
+ * or `mergeFields`), where leaving the field out preserves what is stored
+ * rather than clearing it.
+ *
+ * A record whose last reference is cleared has to have the field REMOVED, or
+ * it goes on answering the `array-contains` for a document it no longer points
+ * at — a `restrict` that refuses a delete nothing is holding. `clear` is the
+ * caller's delete sentinel: `deleteField()` in the web SDK,
+ * `FieldValue.delete()` in the Admin SDK. It is passed in rather than imported
+ * because this module is shared by both and must stay SDK-free.
+ */
+export declare function datasetIntegrityUpdate<TClear>(model: DatasetModel, values: Record<string, unknown> | undefined, clear: TClear): {
+    referencedIds: string[] | TClear;
+};

package/src/lib/app-utils/dataset-models.js

@@ -0,0 +1,409 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { validateCustomFieldValue } from "../plugin-manager/custom-fields.js";
+import { humanizeDatasetFieldId } from "./datasets.js";
+export const DATASET_FIELD_TYPES = [
+    'text',
+    'bool',
+    'int32',
+    'int64',
+    'float',
+    'timestamp',
+    'coordinates',
+    'map',
+    'sorted',
+    'bytes',
+    'nil',
+    'reference'
+];
+/** Display names, mirroring dod.ts `lbl`. */ export const DATASET_FIELD_TYPE_LABELS = {
+    text: 'Text',
+    bool: 'Boolean',
+    int32: 'Integer',
+    int64: 'Big integer',
+    float: 'Number',
+    timestamp: 'Date & time',
+    coordinates: 'Coordinates',
+    map: 'Map',
+    sorted: 'List',
+    bytes: 'Bytes',
+    nil: 'Null',
+    reference: 'Reference'
+};
+/**
+ * Migration shim (v1 → v2): datasets created before models carry flat
+ * `fields: string[]` — derive a model where every column is an optional
+ * text field whose id is the column name, so the editor and AGL-103
+ * bindings keep working on unmigrated docs during rollout.
+ */ export function deriveModelFromFields(fields) {
+    const model = {
+        fields: {},
+        order: []
+    };
+    for (const name of fields){
+        // Raw snake_case ids read as titles in table headers and pickers;
+        // the id stays the stable key (AGL-558).
+        model.fields[name] = {
+            name: humanizeDatasetFieldId(name),
+            type: 'text'
+        };
+        model.order.push(name);
+    }
+    return model;
+}
+/**
+ * Model from quick-creator entries (AGL-558): stable slug ids with the
+ * human display names preserved — "Roast preference" → id
+ * `roast_preference`, name "Roast preference".
+ */ export function modelFromFieldEntries(entries) {
+    const model = {
+        fields: {},
+        order: []
+    };
+    for (const entry of entries){
+        model.fields[entry.id] = {
+            name: entry.name,
+            type: 'text'
+        };
+        model.order.push(entry.id);
+    }
+    return model;
+}
+/** The dataset's model, deriving one from v1 `fields` when absent. */ export function effectiveDatasetModel(dataset) {
+    var _dataset_fields;
+    var _dataset_model, _dataset_model_order;
+    if (((_dataset_model = dataset.model) == null ? void 0 : _dataset_model.fields) && ((_dataset_model_order = dataset.model.order) == null ? void 0 : _dataset_model_order.length)) {
+        return dataset.model;
+    }
+    return deriveModelFromFields((_dataset_fields = dataset.fields) != null ? _dataset_fields : []);
+}
+const isFiniteNumber = (value)=>typeof value === 'number' && Number.isFinite(value);
+/**
+ * Validates a document's values against a model, returning fieldId →
+ * human-readable error (empty object = valid). Values are expected in
+ * storage form (see the module doc); use `coerceDocumentValues` first
+ * when starting from user input strings.
+ */ export function validateDocument(model, values) {
+    const errors = {};
+    for (const fieldId of model.order){
+        var _field_validation;
+        var _field_validation1;
+        const field = model.fields[fieldId];
+        if (!field) continue;
+        const value = values[fieldId];
+        const required = field.required || ((_field_validation1 = field.validation) == null ? void 0 : _field_validation1.required);
+        if (value == null || value === '') {
+            if (required) errors[fieldId] = `${field.name} is required`;
+            continue;
+        }
+        const rules = (_field_validation = field.validation) != null ? _field_validation : {};
+        switch(field.type){
+            case 'text':
+                {
+                    var _rules_options;
+                    if (typeof value !== 'string') {
+                        errors[fieldId] = `${field.name} must be text`;
+                        break;
+                    }
+                    if (rules.min != null && value.length < rules.min) {
+                        errors[fieldId] = `${field.name} must be at least ${rules.min} characters`;
+                    } else if (rules.max != null && value.length > rules.max) {
+                        errors[fieldId] = `${field.name} must be at most ${rules.max} characters`;
+                    } else if (rules.regex) {
+                        try {
+                            if (!new RegExp(rules.regex).test(value)) {
+                                errors[fieldId] = `${field.name} has an invalid format`;
+                            }
+                        } catch (unused) {
+                        // Broken pattern in the model never blocks writes.
+                        }
+                    }
+                    if (!errors[fieldId] && ((_rules_options = rules.options) == null ? void 0 : _rules_options.length) && !rules.options.includes(value)) {
+                        errors[fieldId] = `${field.name} must be one of: ${rules.options.join(', ')}`;
+                    }
+                    break;
+                }
+            case 'bool':
+                if (typeof value !== 'boolean') {
+                    errors[fieldId] = `${field.name} must be true or false`;
+                }
+                break;
+            case 'int32':
+            case 'int64':
+                if (!isFiniteNumber(value) || !Number.isInteger(value)) {
+                    errors[fieldId] = `${field.name} must be a whole number`;
+                    break;
+                }
+                if (rules.min != null && value < rules.min) {
+                    errors[fieldId] = `${field.name} must be ≥ ${rules.min}`;
+                } else if (rules.max != null && value > rules.max) {
+                    errors[fieldId] = `${field.name} must be ≤ ${rules.max}`;
+                }
+                break;
+            case 'float':
+            case 'timestamp':
+                if (!isFiniteNumber(value)) {
+                    errors[fieldId] = field.type === 'timestamp' ? `${field.name} must be a date` : `${field.name} must be a number`;
+                    break;
+                }
+                if (rules.min != null && value < rules.min) {
+                    errors[fieldId] = `${field.name} must be ≥ ${rules.min}`;
+                } else if (rules.max != null && value > rules.max) {
+                    errors[fieldId] = `${field.name} must be ≤ ${rules.max}`;
+                }
+                break;
+            case 'coordinates':
+                {
+                    const coordinates = value;
+                    if (!isFiniteNumber(coordinates == null ? void 0 : coordinates.latitude) || !isFiniteNumber(coordinates == null ? void 0 : coordinates.longitude) || Math.abs(coordinates.latitude) > 90 || Math.abs(coordinates.longitude) > 180) {
+                        errors[fieldId] = `${field.name} must be valid coordinates`;
+                    }
+                    break;
+                }
+            case 'sorted':
+                if (!Array.isArray(value)) {
+                    errors[fieldId] = `${field.name} must be a list`;
+                }
+                break;
+            case 'map':
+                if (typeof value !== 'object' || Array.isArray(value)) {
+                    errors[fieldId] = `${field.name} must be a map`;
+                }
+                break;
+            case 'reference':
+                var _field_reference;
+                if ((_field_reference = field.reference) == null ? void 0 : _field_reference.multiple) {
+                    if (!Array.isArray(value) || value.some((entry)=>typeof entry !== 'string' || !entry)) {
+                        errors[fieldId] = `${field.name} must reference documents`;
+                    }
+                } else if (typeof value !== 'string' || !value) {
+                    errors[fieldId] = `${field.name} must reference a document`;
+                }
+                break;
+            case 'bytes':
+            case 'nil':
+                break;
+        }
+    }
+    // Custom field types (AGL-434): plugin validators run after the base
+    // checks, only on fields that passed them.
+    for (const fieldId of model.order){
+        const field = model.fields[fieldId];
+        if (!(field == null ? void 0 : field.customType) || errors[fieldId]) continue;
+        const customError = validateCustomFieldValue(field.customType, values[fieldId]);
+        if (customError) errors[fieldId] = `${field.name}: ${customError}`;
+    }
+    return errors;
+}
+/** Storage value → grid display string (AGL-179). */ export function formatDatasetValue(field, value) {
+    if (value == null || value === '') return '';
+    switch(field.type){
+        case 'bool':
+            return value === true ? '✓' : value === false ? '—' : String(value);
+        case 'timestamp':
+            return isFiniteNumber(value) ? new Date(value).toISOString().slice(0, 16).replace('T', ' ') : String(value);
+        case 'coordinates':
+            {
+                const coordinates = value;
+                return isFiniteNumber(coordinates == null ? void 0 : coordinates.latitude) && isFiniteNumber(coordinates == null ? void 0 : coordinates.longitude) ? `${coordinates.latitude}, ${coordinates.longitude}` : String(value);
+            }
+        case 'sorted':
+            return Array.isArray(value) ? value.join(', ') : String(value);
+        case 'map':
+            try {
+                return JSON.stringify(value);
+            } catch (unused) {
+                return String(value);
+            }
+        default:
+            return String(value);
+    }
+}
+/**
+ * Storage value → form-input string (AGL-179): the inverse of
+ * `coerceDocumentValues` for populating type-appropriate inputs
+ * (timestamps as `datetime-local` values, coordinates as "lat, lon").
+ */ export function datasetValueToInput(field, value) {
+    if (value == null) return '';
+    if (field.type === 'timestamp' && isFiniteNumber(value)) {
+        return new Date(value).toISOString().slice(0, 16);
+    }
+    if (field.type === 'bool') {
+        return value === true ? 'true' : value === false ? 'false' : String(value);
+    }
+    if (field.type === 'coordinates' || field.type === 'sorted') {
+        return formatDatasetValue(field, value);
+    }
+    if (field.type === 'map') return formatDatasetValue(field, value);
+    return String(value);
+}
+/**
+ * Coerces user-input strings (form fields, CSV cells) into storage form
+ * per the field type. Unparseable input is passed through untouched so
+ * `validateDocument` reports it instead of silently mangling it.
+ */ export function coerceDocumentValues(model, input) {
+    const values = {};
+    for (const fieldId of model.order){
+        const field = model.fields[fieldId];
+        const raw = input[fieldId];
+        if (!field || raw == null || raw === '') continue;
+        if (typeof raw !== 'string') {
+            values[fieldId] = raw;
+            continue;
+        }
+        switch(field.type){
+            case 'bool':
+                values[fieldId] = raw === 'true' ? true : raw === 'false' ? false : raw;
+                break;
+            case 'int32':
+            case 'int64':
+                {
+                    const parsed = Number(raw);
+                    values[fieldId] = Number.isInteger(parsed) ? parsed : raw;
+                    break;
+                }
+            case 'float':
+                {
+                    const parsed = Number(raw);
+                    values[fieldId] = Number.isFinite(parsed) ? parsed : raw;
+                    break;
+                }
+            case 'timestamp':
+                {
+                    const millis = Date.parse(raw);
+                    values[fieldId] = Number.isFinite(millis) ? millis : raw;
+                    break;
+                }
+            case 'coordinates':
+                {
+                    const [latitude, longitude] = raw.split(',').map((part)=>Number(part.trim()));
+                    values[fieldId] = Number.isFinite(latitude) && Number.isFinite(longitude) ? {
+                        latitude,
+                        longitude
+                    } : raw;
+                    break;
+                }
+            case 'sorted':
+                values[fieldId] = raw.split(',').map((part)=>part.trim()).filter(Boolean);
+                break;
+            case 'map':
+                try {
+                    values[fieldId] = JSON.parse(raw);
+                } catch (unused) {
+                    values[fieldId] = raw;
+                }
+                break;
+            case 'reference':
+                var _field_reference;
+                values[fieldId] = ((_field_reference = field.reference) == null ? void 0 : _field_reference.multiple) ? raw.split(',').map((part)=>part.trim()).filter(Boolean) : raw;
+                break;
+            default:
+                values[fieldId] = raw;
+        }
+    }
+    return values;
+}
+/**
+ * Every reference id a record holds, flattened out of its `reference` fields
+ * into one de-duplicated list.
+ *
+ * A reference field stores either a single target id or — when
+ * `reference.multiple` is set — an array of them, and a model may declare
+ * several. Both shapes flatten into the same list because the question asked
+ * of it is never "which field", it is "does this record still point at that
+ * document".
+ *
+ * Fields are read from `order` UNIONED with the keys of `fields`. Every other
+ * pass over a model walks `order` alone, which is right for anything the user
+ * sees — but a reference declared without a display slot still holds a real
+ * FKey, and an integrity index that skipped it would under-report.
+ */ export function datasetReferencedIds(model, values) {
+    var _model_order, _model_fields;
+    const ids = new Set();
+    const fieldIds = new Set([
+        ...(_model_order = model.order) != null ? _model_order : [],
+        ...Object.keys((_model_fields = model.fields) != null ? _model_fields : {})
+    ]);
+    for (const fieldId of fieldIds){
+        var _model_fields_fieldId, _model_fields1;
+        if (((_model_fields1 = model.fields) == null ? void 0 : (_model_fields_fieldId = _model_fields1[fieldId]) == null ? void 0 : _model_fields_fieldId.type) !== 'reference') continue;
+        const stored = values == null ? void 0 : values[fieldId];
+        for (const entry of Array.isArray(stored) ? stored : [
+            stored
+        ]){
+            const id = typeof entry === 'string' ? entry.trim() : '';
+            if (id) ids.add(id);
+        }
+    }
+    return [
+        ...ids
+    ];
+}
+/**
+ * The integrity index a record write carries, so referential integrity can be
+ * decided by a QUERY rather than by the rows a listener happened to fetch.
+ *
+ * Deleting a record has to answer "is anything still pointing at this?", and
+ * `restrict` refuses the delete on a yes while `setNull` strips the FKey. That
+ * question cannot be asked where the answer is stored: dataset fields are
+ * user-defined, so `records.values` carries a deliberate index exemption in
+ * `cloud/firebase-firestore.indexes.json` — auto-indexing an unbounded map
+ * blows Firestore's per-document index-entry limit — and
+ * `where('values.<fieldId>', '==', id)` is therefore FAILED_PRECONDITION.
+ * Reading a page of records and filtering them in the browser answers only for
+ * the rows in that page, which is a browse window standing in for a
+ * correctness check: a reference held outside it reads as no reference at all,
+ * the delete proceeds, and `restrict` silently fails to restrict.
+ *
+ * `referencedIds` is that same reference, denormalized to a top-level array
+ * Firestore will index, so one `array-contains` reaches every record.
+ *
+ * ⚠️ OMITTED when a record references nothing, rather than written as `[]`.
+ * `isNotEmpty` is served as `!= null` and an empty array is not null, so a
+ * record stamped `[]` answers "holds a reference" for a dataset that holds
+ * none.
+ *
+ * ⚠️ Spread this at EVERY write that sets a record's `values`. A write that
+ * sets values without it leaves the index describing the PREVIOUS values, and
+ * a stale integrity index is the exact failure it exists to prevent — with the
+ * UI reporting the record as safe to delete. On a merging write use
+ * `datasetIntegrityUpdate` instead: omission leaves a stale array in place
+ * where clearing the last reference has to remove the field.
+ */ export function datasetIntegrityFields(model, values) {
+    const referencedIds = datasetReferencedIds(model, values);
+    return referencedIds.length ? {
+        referencedIds
+    } : {};
+}
+/**
+ * `datasetIntegrityFields` for a MERGING write (`update`, `set` with `merge`
+ * or `mergeFields`), where leaving the field out preserves what is stored
+ * rather than clearing it.
+ *
+ * A record whose last reference is cleared has to have the field REMOVED, or
+ * it goes on answering the `array-contains` for a document it no longer points
+ * at — a `restrict` that refuses a delete nothing is holding. `clear` is the
+ * caller's delete sentinel: `deleteField()` in the web SDK,
+ * `FieldValue.delete()` in the Admin SDK. It is passed in rather than imported
+ * because this module is shared by both and must stay SDK-free.
+ */ export function datasetIntegrityUpdate(model, values, clear) {
+    const referencedIds = datasetReferencedIds(model, values);
+    return {
+        referencedIds: referencedIds.length ? referencedIds : clear
+    };
+}
+
+//# sourceMappingURL=dataset-models.js.map