@aglyn/aglyn 1.0.0-beta.220 → 1.0.0-beta.222

package/src/lib/app-utils/automation-placeholders.d.ts

@@ -1,72 +0,0 @@
-/**
- * @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 HostAction, type HostActionStep, type HostActionStepType } from './actions';
-/**
- * PLACEHOLDERS IN AN AUTOMATION (AGL-2919).
- *
- * A placeholder is a value a person still has to supply, written in square
- * brackets where the value belongs: `[newsletter]` where a list is named,
- * `[your phone number]` in an email's body. An automation drafted for somebody
- * to review carries one wherever the draft could not name a real record or
- * did not know a fact.
- *
- * Square brackets because they are inert everywhere an automation reads a
- * value. A bracketed list, campaign or workflow name matches no record by
- * name, so the step reports the unknown name in the run history rather than
- * acting on the wrong record; a bracketed condition value equals no field an
- * event carries, so a trigger never fires on a guess; and the Reference health
- * audit already reports a name that resolves to nothing.
- *
- * Only the fields a person types words into are read. Selectors, class names,
- * HTML and scripts use brackets as syntax and never hold a placeholder.
- */
-/**
- * A bracketed placeholder inside a value. Not one followed by `(`, which is a
- * written link (`[our menu](https://…)`) rather than a gap, and never across a
- * line or longer than a phrase.
- */
-export declare const AUTOMATION_PLACEHOLDER_PATTERN: RegExp;
-/** The longest words a placeholder keeps. */
-export declare const AUTOMATION_PLACEHOLDER_MAX_CHARS = 100;
-/** The words inside the first placeholder in a value, or `null` when it holds none. */
-export declare function automationPlaceholderIn(value: unknown): string | null;
-/**
- * `words` as a placeholder: on one line, without brackets of their own, cut
- * to a phrase. Empty words still make a placeholder, so a value that must be
- * supplied is never written as an empty string a validator would refuse.
- */
-export declare function automationPlaceholder(words: string): string;
-/** What a placeholder stands in for, in the words the editor labels that field with. */
-export type AutomationPlaceholderField = 'condition' | 'list' | 'campaign' | 'workflow' | 'webhook' | 'dataset' | 'overlay' | 'subject' | 'body' | 'title' | 'message' | 'tag';
-export interface AutomationPlaceholder {
-    /** The 1-based step holding it; `null` for the trigger's own conditions. */
-    step: number | null;
-    field: AutomationPlaceholderField;
-    /** The words inside the brackets. */
-    text: string;
-}
-/**
- * Each typed field a step type holds, and the placeholder field it reports
- * as. A step type absent here holds no field a person writes words into.
- */
-export declare const AUTOMATION_PLACEHOLDER_FIELDS: Readonly<Partial<Record<HostActionStepType, ReadonlyArray<readonly [string, AutomationPlaceholderField]>>>>;
-/** The placeholders one step holds, in its fields' order. */
-export declare function automationStepPlaceholders(step: HostActionStep, index: number): AutomationPlaceholder[];
-/** Every placeholder an automation holds: its trigger's conditions first, then each step's. */
-export declare function automationPlaceholders(action: Pick<HostAction, 'trigger' | 'steps'> | null | undefined): AutomationPlaceholder[];
-/** One placeholder as a person reads it: where it is, and what it stands in for. */
-export declare function describeAutomationPlaceholder(placeholder: AutomationPlaceholder): string;

package/src/lib/app-utils/automation-placeholders.js

@@ -1,207 +0,0 @@
-/**
- * @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 { normalizeTriggerConditions } from "./actions.js";
-/**
- * PLACEHOLDERS IN AN AUTOMATION (AGL-2919).
- *
- * A placeholder is a value a person still has to supply, written in square
- * brackets where the value belongs: `[newsletter]` where a list is named,
- * `[your phone number]` in an email's body. An automation drafted for somebody
- * to review carries one wherever the draft could not name a real record or
- * did not know a fact.
- *
- * Square brackets because they are inert everywhere an automation reads a
- * value. A bracketed list, campaign or workflow name matches no record by
- * name, so the step reports the unknown name in the run history rather than
- * acting on the wrong record; a bracketed condition value equals no field an
- * event carries, so a trigger never fires on a guess; and the Reference health
- * audit already reports a name that resolves to nothing.
- *
- * Only the fields a person types words into are read. Selectors, class names,
- * HTML and scripts use brackets as syntax and never hold a placeholder.
- */ /**
- * A bracketed placeholder inside a value. Not one followed by `(`, which is a
- * written link (`[our menu](https://…)`) rather than a gap, and never across a
- * line or longer than a phrase.
- */ export const AUTOMATION_PLACEHOLDER_PATTERN = /\[([^[\]\n]{1,120})\](?!\()/;
-/** The longest words a placeholder keeps. */ export const AUTOMATION_PLACEHOLDER_MAX_CHARS = 100;
-/** The words inside the first placeholder in a value, or `null` when it holds none. */ export function automationPlaceholderIn(value) {
-    var _match_;
-    if (typeof value !== 'string') return null;
-    const match = AUTOMATION_PLACEHOLDER_PATTERN.exec(value);
-    const words = match == null ? void 0 : (_match_ = match[1]) == null ? void 0 : _match_.trim();
-    return words ? words : null;
-}
-/**
- * `words` as a placeholder: on one line, without brackets of their own, cut
- * to a phrase. Empty words still make a placeholder, so a value that must be
- * supplied is never written as an empty string a validator would refuse.
- */ export function automationPlaceholder(words) {
-    const clean = words.replace(/[[\]\n\r]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, AUTOMATION_PLACEHOLDER_MAX_CHARS).trim();
-    return `[${clean || 'to fill in'}]`;
-}
-/**
- * Each typed field a step type holds, and the placeholder field it reports
- * as. A step type absent here holds no field a person writes words into.
- */ export const AUTOMATION_PLACEHOLDER_FIELDS = {
-    enrollList: [
-        [
-            'listName',
-            'list'
-        ]
-    ],
-    assignCampaign: [
-        [
-            'campaignName',
-            'campaign'
-        ]
-    ],
-    runWorkflow: [
-        [
-            'workflowName',
-            'workflow'
-        ]
-    ],
-    webhookPost: [
-        [
-            'webhookName',
-            'webhook'
-        ]
-    ],
-    datasetAppend: [
-        [
-            'datasetName',
-            'dataset'
-        ]
-    ],
-    updateDataset: [
-        [
-            'datasetName',
-            'dataset'
-        ]
-    ],
-    showOverlay: [
-        [
-            'overlayName',
-            'overlay'
-        ]
-    ],
-    sendEmail: [
-        [
-            'subject',
-            'subject'
-        ],
-        [
-            'body',
-            'body'
-        ]
-    ],
-    notifyAdmins: [
-        [
-            'title',
-            'title'
-        ],
-        [
-            'body',
-            'body'
-        ]
-    ],
-    siteAlert: [
-        [
-            'message',
-            'message'
-        ]
-    ],
-    createCrmTask: [
-        [
-            'title',
-            'title'
-        ]
-    ],
-    logCrmActivity: [
-        [
-            'body',
-            'body'
-        ]
-    ],
-    addContactTag: [
-        [
-            'tag',
-            'tag'
-        ]
-    ]
-};
-/** The placeholders one step holds, in its fields' order. */ export function automationStepPlaceholders(step, index) {
-    var _ref, _AUTOMATION_PLACEHOLDER_FIELDS_step_type;
-    var _step_when;
-    const found = [];
-    const number = index + 1;
-    for (const clause of (_ref = (_step_when = step.when) == null ? void 0 : _step_when.conditions) != null ? _ref : []){
-        const text = automationPlaceholderIn(clause == null ? void 0 : clause.value);
-        if (text) found.push({
-            step: number,
-            field: 'condition',
-            text
-        });
-    }
-    for (const [key, field] of (_AUTOMATION_PLACEHOLDER_FIELDS_step_type = AUTOMATION_PLACEHOLDER_FIELDS[step.type]) != null ? _AUTOMATION_PLACEHOLDER_FIELDS_step_type : []){
-        const text = automationPlaceholderIn(step[key]);
-        if (text) found.push({
-            step: number,
-            field,
-            text
-        });
-    }
-    return found;
-}
-/** Every placeholder an automation holds: its trigger's conditions first, then each step's. */ export function automationPlaceholders(action) {
-    var _action_steps;
-    if (!action) return [];
-    const found = [];
-    for (const condition of normalizeTriggerConditions(action.trigger)){
-        const text = automationPlaceholderIn(condition == null ? void 0 : condition.value);
-        if (text) found.push({
-            step: null,
-            field: 'condition',
-            text
-        });
-    }
-    ;
-    ((_action_steps = action.steps) != null ? _action_steps : []).forEach((step, index)=>{
-        if (step) found.push(...automationStepPlaceholders(step, index));
-    });
-    return found;
-}
-/** One placeholder as a person reads it: where it is, and what it stands in for. */ export function describeAutomationPlaceholder(placeholder) {
-    const where = placeholder.step === null ? 'The trigger' : `Step ${placeholder.step}`;
-    const what = {
-        condition: 'a condition value',
-        list: 'the list',
-        campaign: 'the campaign',
-        workflow: 'the workflow',
-        webhook: 'the webhook',
-        dataset: 'the dataset',
-        overlay: 'the popup or bar',
-        subject: 'the subject',
-        body: 'the text',
-        title: 'the title',
-        message: 'the message',
-        tag: 'the tag'
-    };
-    return `${where}: ${what[placeholder.field]} (“${placeholder.text}”)`;
-}
-
-//# sourceMappingURL=automation-placeholders.js.map

package/src/lib/app-utils/automation-placeholders.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/automation-placeholders.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\nimport {\n  type HostAction,\n  type HostActionStep,\n  type HostActionStepType,\n  normalizeTriggerConditions,\n} from './actions'\n\n/**\n * PLACEHOLDERS IN AN AUTOMATION (AGL-2919).\n *\n * A placeholder is a value a person still has to supply, written in square\n * brackets where the value belongs: `[newsletter]` where a list is named,\n * `[your phone number]` in an email's body. An automation drafted for somebody\n * to review carries one wherever the draft could not name a real record or\n * did not know a fact.\n *\n * Square brackets because they are inert everywhere an automation reads a\n * value. A bracketed list, campaign or workflow name matches no record by\n * name, so the step reports the unknown name in the run history rather than\n * acting on the wrong record; a bracketed condition value equals no field an\n * event carries, so a trigger never fires on a guess; and the Reference health\n * audit already reports a name that resolves to nothing.\n *\n * Only the fields a person types words into are read. Selectors, class names,\n * HTML and scripts use brackets as syntax and never hold a placeholder.\n */\n\n/**\n * A bracketed placeholder inside a value. Not one followed by `(`, which is a\n * written link (`[our menu](https://…)`) rather than a gap, and never across a\n * line or longer than a phrase.\n */\nexport const AUTOMATION_PLACEHOLDER_PATTERN = /\\[([^[\\]\\n]{1,120})\\](?!\\()/\n\n/** The longest words a placeholder keeps. */\nexport const AUTOMATION_PLACEHOLDER_MAX_CHARS = 100\n\n/** The words inside the first placeholder in a value, or `null` when it holds none. */\nexport function automationPlaceholderIn(value: unknown): string | null {\n  if (typeof value !== 'string') return null\n  const match = AUTOMATION_PLACEHOLDER_PATTERN.exec(value)\n  const words = match?.[1]?.trim()\n  return words ? words : null\n}\n\n/**\n * `words` as a placeholder: on one line, without brackets of their own, cut\n * to a phrase. Empty words still make a placeholder, so a value that must be\n * supplied is never written as an empty string a validator would refuse.\n */\nexport function automationPlaceholder(words: string): string {\n  const clean = words\n    .replace(/[[\\]\\n\\r]+/g, ' ')\n    .replace(/\\s+/g, ' ')\n    .trim()\n    .slice(0, AUTOMATION_PLACEHOLDER_MAX_CHARS)\n    .trim()\n  return `[${clean || 'to fill in'}]`\n}\n\n/** What a placeholder stands in for, in the words the editor labels that field with. */\nexport type AutomationPlaceholderField =\n  | 'condition'\n  | 'list'\n  | 'campaign'\n  | 'workflow'\n  | 'webhook'\n  | 'dataset'\n  | 'overlay'\n  | 'subject'\n  | 'body'\n  | 'title'\n  | 'message'\n  | 'tag'\n\nexport interface AutomationPlaceholder {\n  /** The 1-based step holding it; `null` for the trigger's own conditions. */\n  step: number | null\n  field: AutomationPlaceholderField\n  /** The words inside the brackets. */\n  text: string\n}\n\n/**\n * Each typed field a step type holds, and the placeholder field it reports\n * as. A step type absent here holds no field a person writes words into.\n */\nexport const AUTOMATION_PLACEHOLDER_FIELDS: Readonly<\n  Partial<Record<HostActionStepType, ReadonlyArray<readonly [string, AutomationPlaceholderField]>>>\n> = {\n  enrollList: [['listName', 'list']],\n  assignCampaign: [['campaignName', 'campaign']],\n  runWorkflow: [['workflowName', 'workflow']],\n  webhookPost: [['webhookName', 'webhook']],\n  datasetAppend: [['datasetName', 'dataset']],\n  updateDataset: [['datasetName', 'dataset']],\n  showOverlay: [['overlayName', 'overlay']],\n  sendEmail: [\n    ['subject', 'subject'],\n    ['body', 'body'],\n  ],\n  notifyAdmins: [\n    ['title', 'title'],\n    ['body', 'body'],\n  ],\n  siteAlert: [['message', 'message']],\n  createCrmTask: [['title', 'title']],\n  logCrmActivity: [['body', 'body']],\n  addContactTag: [['tag', 'tag']],\n}\n\n/** The placeholders one step holds, in its fields' order. */\nexport function automationStepPlaceholders(\n  step: HostActionStep,\n  index: number,\n): AutomationPlaceholder[] {\n  const found: AutomationPlaceholder[] = []\n  const number = index + 1\n  for (const clause of step.when?.conditions ?? []) {\n    const text = automationPlaceholderIn(clause?.value)\n    if (text) found.push({ step: number, field: 'condition', text })\n  }\n  for (const [key, field] of AUTOMATION_PLACEHOLDER_FIELDS[step.type] ?? []) {\n    const text = automationPlaceholderIn((step as unknown as Record<string, unknown>)[key])\n    if (text) found.push({ step: number, field, text })\n  }\n  return found\n}\n\n/** Every placeholder an automation holds: its trigger's conditions first, then each step's. */\nexport function automationPlaceholders(\n  action: Pick<HostAction, 'trigger' | 'steps'> | null | undefined,\n): AutomationPlaceholder[] {\n  if (!action) return []\n  const found: AutomationPlaceholder[] = []\n  for (const condition of normalizeTriggerConditions(action.trigger)) {\n    const text = automationPlaceholderIn(condition?.value)\n    if (text) found.push({ step: null, field: 'condition', text })\n  }\n  ;(action.steps ?? []).forEach((step, index) => {\n    if (step) found.push(...automationStepPlaceholders(step, index))\n  })\n  return found\n}\n\n/** One placeholder as a person reads it: where it is, and what it stands in for. */\nexport function describeAutomationPlaceholder(placeholder: AutomationPlaceholder): string {\n  const where = placeholder.step === null ? 'The trigger' : `Step ${placeholder.step}`\n  const what: Record<AutomationPlaceholderField, string> = {\n    condition: 'a condition value',\n    list: 'the list',\n    campaign: 'the campaign',\n    workflow: 'the workflow',\n    webhook: 'the webhook',\n    dataset: 'the dataset',\n    overlay: 'the popup or bar',\n    subject: 'the subject',\n    body: 'the text',\n    title: 'the title',\n    message: 'the message',\n    tag: 'the tag',\n  }\n  return `${where}: ${what[placeholder.field]} (“${placeholder.text}”)`\n}\n"],"names":["normalizeTriggerConditions","AUTOMATION_PLACEHOLDER_PATTERN","AUTOMATION_PLACEHOLDER_MAX_CHARS","automationPlaceholderIn","value","match","exec","words","trim","automationPlaceholder","clean","replace","slice","AUTOMATION_PLACEHOLDER_FIELDS","enrollList","assignCampaign","runWorkflow","webhookPost","datasetAppend","updateDataset","showOverlay","sendEmail","notifyAdmins","siteAlert","createCrmTask","logCrmActivity","addContactTag","automationStepPlaceholders","step","index","found","number","clause","when","conditions","text","push","field","key","type","automationPlaceholders","action","condition","trigger","steps","forEach","describeAutomationPlaceholder","placeholder","where","what","list","campaign","workflow","webhook","dataset","overlay","subject","body","title","message","tag"],"mappings":"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"}

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

@@ -1,339 +0,0 @@
-/**
- * @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 every record write — the console, `/v1`,
- * a bound form's submission and an automation step — through the shared
- * `validateDocument`/`coerceDocumentValues` pair so they can't disagree. The
- * form and the automation step reach the pair through
- * `prepareDatasetRecordWrite` (AGL-2773).
- *
- * 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[];
-    filterKeys?: string[];
-    filterValues?: DatasetFilterValues;
-};
-/**
- * `datasetIntegrityFields` for a MERGING write (`update`, `set` with
- * `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. The filter
- * fields are cleared the same way, so a record emptied of every filterable
- * value stops answering the filters its old values did.
- *
- * ⚠️ `filterValues` is a MAP, and it is written WHOLE: `update` and
- * `mergeFields` replace a field outright, so a value cleared since the last
- * write leaves the map with it. `set(…, { merge: true })` does NOT — it merges
- * maps key by key and would keep the cleared value answering its old
- * equality — so a record write never uses it; list the fields in
- * `mergeFields` instead.
- */
-export declare function datasetIntegrityUpdate<TClear>(model: DatasetModel, values: Record<string, unknown> | undefined, clear: TClear): {
-    referencedIds: string[] | TClear;
-    filterKeys: string[] | TClear;
-    filterValues: DatasetFilterValues | TClear;
-};
-/**
- * A dataset record's FILTER TOKENS: every word-level question the records
- * table can ask of a record, flattened into one array of strings Firestore
- * indexes on its own. Its twin, {@link datasetFilterValues}, holds the
- * equalities.
- *
- * ## Why these fields, and not the values
- *
- * A record's fields live under `values`, a user-defined, unbounded map that
- * the index configuration exempts from indexing — auto-indexing it can exceed
- * Firestore's per-document index-entry limit — so `where('values.<field>', …)`
- * is refused. A composite index per dataset would need an admin call per
- * dataset, runs into the project's composite-index cap, and is deleted by the
- * next `firestore:indexes` deploy of a file that does not list it.
- *
- * `filterKeys` and `filterValues` need none of that. Firestore's AUTOMATIC
- * single-field indexes serve `where('filterKeys', 'array-contains', token)`
- * and `where('filterValues.<field>', '==', value)`, and every automatic index
- * ends in the document name — so any number of those equalities and ONE
- * `array-contains`, under `orderBy(documentId())`, compose by index merging,
- * with no composite index and no index deploy, on any dataset of any project
- * (AGL-3321).
- *
- * ## The token grammar
- *
- *   `f:<fieldId>=<value>`   a field equals a value. Enum (a text field with
- *                           `validation.options`) values are kept exactly;
- *                           plain text is lower-cased, trimmed and clipped to
- *                           {@link DATASET_FILTER_VALUE_MAX} characters;
- *                           booleans are `true`/`false`; numbers are
- *                           `String(number)`; a `sorted` list contributes one
- *                           token per member.
- *   `f:<fieldId>^<prefix>`  a word of a plain text field starts with this.
- *   `s:<prefix>`            a word of ANY text value (enums and list members
- *                           included) starts with this — the quick search.
- *
- * Timestamps, references, maps, bytes, coordinates and nil fields carry no
- * field tokens: a timestamp is asked in ranges, which one token cannot serve,
- * and the rest are not asked about by value.
- *
- * The array is sorted, de-duplicated and capped at
- * {@link DATASET_FILTER_KEYS_MAX}. Past the cap, the `=` tokens are kept
- * first, then the per-field word prefixes, then the search prefixes, so a
- * very long record loses search reach before it loses exact matches.
- */
-export declare const DATASET_FILTER_KEYS_MAX = 500;
-/** Plain text values are clipped to this many characters in an `=` token. */
-export declare const DATASET_FILTER_VALUE_MAX = 64;
-/** Word prefixes run from 1 to this many characters. */
-export declare const DATASET_FILTER_PREFIX_MAX = 12;
-/** Only the first this-many words of a value contribute prefixes. */
-export declare const DATASET_FILTER_WORDS_MAX = 40;
-/** One clause of the records table's filter: `{ field, op, value }`. */
-export interface DatasetFilterClause {
-    field: string;
-    op: string;
-    value: string;
-}
-/**
- * The words of a text value: split on anything that is not a letter or a
- * digit, lower-cased, at most {@link DATASET_FILTER_WORDS_MAX} of them.
- */
-export declare function datasetFilterWords(text: string): string[];
-/**
- * Plain text as its stored key — its `=` token's value and its
- * `filterValues` entry: lower-cased, trimmed, clipped to
- * {@link DATASET_FILTER_VALUE_MAX} characters. What the records table asks a
- * typed value to equal.
- */
-export declare function datasetFilterTextKey(value: string): string;
-/** The tokens described in {@link DATASET_FILTER_KEYS_MAX}'s comment. */
-export declare function datasetFilterKeys(model: DatasetModel, values: Record<string, unknown> | undefined): string[];
-/** A record's `filterValues`: field id → the value an equality asks for. */
-export type DatasetFilterValues = Record<string, string | number | boolean>;
-/**
- * The query path of a field's `filterValues` entry, or null for a field id
- * no path can name — such a field is stamped no entry, and the records table
- * offers it no equality (its `contains`, served by `filterKeys`, stands).
- */
-export declare function datasetFilterValuePath(fieldId: string): string | null;
-/**
- * A dataset record's FILTER VALUES: `{ [fieldId]: value }`, one scalar per
- * field an equality can be asked of, so the records table puts every
- * equality on its query (AGL-3321).
- *
- *   enum text (`validation.options`)  the value exactly, as its `=` token;
- *   plain text                        {@link datasetFilterTextKey};
- *   bool                              a boolean;
- *   int32 / int64 / float             a number.
- *
- * A form or an automation stores every value as text, so `'19.50'` is the
- * number 19.5 and `'true'` the boolean, as in {@link datasetFilterKeys}.
- * Fields with no value, and timestamps, lists, references, maps, bytes,
- * coordinates and nil fields, carry no entry: a list is asked by member
- * (`f:<id>=<member>` in `filterKeys`), and the rest are not asked about by
- * value.
- *
- * ## What it costs
- *
- * Unlike `values`, this map is NOT exempt from indexing — that is its whole
- * point. Each entry is a scalar and costs two automatic index entries
- * (ascending, descending), so a record costs at most two per model field —
- * bounded by the model's field count (the `/v1` API caps a model at 100
- * fields), far inside Firestore's 40,000 entries per document, where
- * `values` was unbounded because a `map` or `sorted` value may hold anything.
- */
-export declare function datasetFilterValues(model: DatasetModel, values: Record<string, unknown> | undefined): DatasetFilterValues;
-/**
- * The `filterKeys` token a word-level clause asks for, or null when it is
- * not one:
- *
- *  - plain text `contains` → the `^` token of the value's FIRST word, so a
- *    `contains` is a word-prefix match, not a mid-string one, and one word
- *    of several is asked (the records table says so);
- *  - list `contains` (and `equals`) → the member's `=` token;
- *  - enum, boolean, number and plain text `equals` → the `=` token of the
- *    value. The records table asks these of `filterValues` instead, which
- *    composes with a `contains`; the token remains what the quick search and
- *    older readers match.
- *  - everything else — ranges, dates, `isEmpty`, `isAnyOf`, negations — null.
- *
- * `clause.field` is the field id. The operator names are the grid's: a
- * select's `equals`, a number's `=`, a boolean's `is`, a list's `contains`.
- */
-export declare function datasetFilterToken(model: DatasetModel, clause: DatasetFilterClause): string | null;
-/**
- * The quick-search token for one typed word, or null for a word with no
- * letters or digits. A word with punctuation inside it is asked by its first
- * run — split the search text with {@link datasetFilterWords} to ask for
- * every run.
- */
-export declare function datasetSearchToken(word: string): string | null;