@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/core/page/memory-reader.js

@@ -0,0 +1,299 @@
+/**
+ * A page's `db` over rows a test gives (the runtime's page unit tests, `testing.ts`): the same reads the
+ * platform's reader (services `slot/page/records.ts`) answers from the database, answered from memory.
+ * What a where, orderBy, paging, include and select mean, and which reads are refused, is the shared
+ * `records-query.ts`; only where the candidate rows come from differs (every row of the table the test
+ * gave, in the order it gave them). Two things it does not do: limits on bytes and rows read (a test's
+ * data is small), and putting a phone operand in stored form (write test data and where values in
+ * E.164, `+14155550123`).
+ */
+import { parentOf, SESSION_TABLE } from '../slot/company-metadata.js';
+import { getCompiledTable, getTableField, relationsOf } from '../slot/compile-schema.js';
+import { emptyFieldValue, makeFieldValue } from '../slot/field.js';
+import { slotFieldNames } from '../slot/row.js';
+import { afterOf, checkListSizes, findAnchors, isPlainObject, limitExceeded, matches, optionalCount, orderKeys, orderRows, pageRows, RECORDS_LIMITS, RecordsQueryError, refuseSearch, relatedKey, relationFilters, RELATION_INCLUDE_KEYS, selectFields, toSlot, unstartableWhy, wayBackFilters, } from './records-query.js';
+const SLOT_STATES = ['filled', 'empty', 'asked_unknown', 'declined'];
+/** A field given as `{ $slot: { value, state, reason } }`, or null for a plain value. */
+function slotGiven(value) {
+    if (!isPlainObject(value) || !('$slot' in value))
+        return null;
+    const slot = value.$slot;
+    if (!isPlainObject(slot) || !SLOT_STATES.includes(slot.state)) {
+        throw new Error(`renderPage: a $slot is { value, state, reason } with state one of ${SLOT_STATES.join(', ')}`);
+    }
+    return slot;
+}
+export function createMemoryReader(input) {
+    const { schema, rows: given, now } = input;
+    const read = new Map();
+    const truth = new Map();
+    const parents = new Map();
+    const calls = [];
+    const tableOf = (name) => {
+        if (name === SESSION_TABLE)
+            throw new RecordsQueryError(`records.${name}: the session is ctx.session, not a table`);
+        const table = getCompiledTable(schema, name);
+        if (!table)
+            throw new RecordsQueryError(`records.${name}: no such table in this sequence`);
+        return table;
+    };
+    // The test's data is checked whole, up front: a mistake in a row the page never reads still shows.
+    for (const [name, rows] of Object.entries(given)) {
+        const table = getCompiledTable(schema, name);
+        if (!table)
+            throw new Error(`renderPage: data.${name}: no such table in the company schema`);
+        for (const row of rows) {
+            if (typeof row.id !== 'string' || !row.id)
+                throw new Error(`renderPage: data.${name}: every row needs a string id`);
+            for (const key of Object.keys(row)) {
+                if (key !== 'id' && key !== 'createdAt' && key !== 'updatedAt' && !getTableField(table, key)) {
+                    throw new Error(`renderPage: data.${name} row ${row.id}: ${key} is not a field of ${name}`);
+                }
+            }
+        }
+    }
+    const relationOf = (tableName, name) => relationsOf(schema, tableName).find((r) => r.name === name);
+    /** A given row as `db` hands it out: each schema field a slot, filled when the test gave a value. */
+    const toRowOut = (tableName, data) => {
+        const table = tableOf(tableName);
+        const id = String(data.id);
+        const out = { id };
+        for (const key of ['createdAt', 'updatedAt'])
+            if (typeof data[key] === 'string')
+                out[key] = data[key];
+        for (const field of slotFieldNames(table.fields)) {
+            const value = data[field];
+            const slot = slotGiven(value);
+            const fv = slot
+                ? makeFieldValue({ value: (slot.value ?? null), state: slot.state, reason: slot.reason ?? null, updatedAt: now })
+                : value === undefined || value === null
+                    ? emptyFieldValue(now)
+                    : makeFieldValue({ value: value, state: 'filled', updatedAt: now });
+            out[field] = toSlot(tableName, id, field, fv);
+        }
+        if (!read.has(id))
+            read.set(id, { table: tableName });
+        truth.set(id, out);
+        return out;
+    };
+    const allRows = (tableName) => (given[tableName] ?? []).map((data) => toRowOut(tableName, data));
+    const noteParents = (tableName, table, field, ids) => {
+        if (parentOf(table)?.field !== field)
+            return;
+        const set = parents.get(tableName) ?? new Set();
+        for (const id of ids)
+            set.add(id);
+        parents.set(tableName, set);
+    };
+    /** The rows of a way back for each parent, in the order the test gave them. */
+    const childrenOf = (relation, parentIds) => {
+        const children = allRows(relation.table);
+        const out = new Map();
+        for (const id of parentIds)
+            out.set(id, children.filter((child) => child[relation.field].value === id));
+        return out;
+    };
+    const filterRows = (tableName, rows, where) => {
+        const table = tableOf(tableName);
+        const relations = relationFilters(table, where);
+        const ways = wayBackFilters(tableName, where, relationOf);
+        const nested = (target, sub) => sub.some((w) => isPlainObject(w) && (relationFilters(tableOf(target), w).length > 0 || wayBackFilters(target, w, relationOf).length > 0));
+        for (const { field, target, sub } of relations) {
+            if (nested(target, sub)) {
+                throw new RecordsQueryError(`records.${tableName}: where.${field}.is filters one level only; read the related rows first, then filter by their ids (in)`);
+            }
+        }
+        for (const { relation, sub } of ways) {
+            if (nested(relation.table, sub)) {
+                throw new RecordsQueryError(`records.${tableName}: where.${relation.name} filters one level only; read those rows first, then filter by their ids (in)`);
+            }
+        }
+        const targets = new Map();
+        for (const { target } of relations)
+            for (const row of allRows(target))
+                targets.set(row.id, row);
+        const related = new Map();
+        for (const { relation } of ways) {
+            const key = relatedKey(tableName, relation.name);
+            if (!related.has(key))
+                related.set(key, childrenOf(relation, rows.map((row) => row.id)));
+        }
+        const context = { schema, targets, related, relationOf };
+        return rows.filter((row) => matches(context, tableName, row, where));
+    };
+    const includeRelation = (tableName, rows, relation, spec, depth) => {
+        const options = isPlainObject(spec) ? spec : {};
+        for (const key of Object.keys(options)) {
+            if (!RELATION_INCLUDE_KEYS.has(key)) {
+                throw new RecordsQueryError(`records.${tableName}: include.${relation.name}.${key} is not supported (where, orderBy, skip, take, include)`);
+            }
+        }
+        if (options.where !== undefined)
+            refuseSearch(relation.table, options.where, `include.${relation.name}.where`);
+        const children = childrenOf(relation, rows.map((row) => row.id));
+        const all = [...children.values()].flat();
+        const kept = options.where === undefined ? null : new Set(filterRows(relation.table, all, options.where).map((row) => row.id));
+        const childTable = tableOf(relation.table);
+        const skip = optionalCount(options.skip, `include.${relation.name}.skip`) ?? 0;
+        const take = optionalCount(options.take, `include.${relation.name}.take`);
+        const shown = [];
+        for (const row of rows) {
+            let list = (children.get(row.id) ?? []).filter((child) => !kept || kept.has(child.id));
+            list = orderRows(orderKeys(childTable, options.orderBy), list).slice(skip, take === undefined ? undefined : skip + take);
+            row[relation.name] = list;
+            shown.push(...list);
+        }
+        include(relation.table, shown, options.include, depth + 1);
+    };
+    const include = (tableName, rows, spec, depth) => {
+        if (spec === undefined || spec === null || spec === false)
+            return;
+        if (!isPlainObject(spec))
+            throw new RecordsQueryError(`records.${tableName}: include must be an object`);
+        if (depth > RECORDS_LIMITS.includeDepth)
+            throw limitExceeded(`records.${tableName}: include goes deeper than ${RECORDS_LIMITS.includeDepth} levels`);
+        const table = tableOf(tableName);
+        for (const [field, nested] of Object.entries(spec)) {
+            if (nested === false || nested === undefined)
+                continue;
+            const ref = getTableField(table, field)?.ref;
+            if (!ref) {
+                const relation = relationOf(tableName, field);
+                if (relation) {
+                    includeRelation(tableName, rows, relation, nested, depth);
+                    continue;
+                }
+                throw new RecordsQueryError(`records.${tableName}: include.${field} is not a lookup nor a way back (relatedName) of ${tableName}`);
+            }
+            if (ref.kind !== 'lookup')
+                throw new RecordsQueryError(`records.${tableName}: include.${field} is the parent; read the parent by id`);
+            tableOf(ref.table);
+            const byId = new Map(allRows(ref.table).map((row) => [row.id, row]));
+            const nestedInclude = isPlainObject(nested) ? nested.include : undefined;
+            include(ref.table, [...byId.values()], nestedInclude, depth + 1);
+            for (const row of rows) {
+                const slot = row[field];
+                slot.row = typeof slot.value === 'string' ? (byId.get(slot.value) ?? null) : null;
+            }
+        }
+    };
+    /** The where as the platform takes it: an email operand lower-cased, as it is stored. */
+    const normalizeWhere = (table, where) => {
+        const out = {};
+        for (const [field, cond] of Object.entries(where)) {
+            if (field === 'AND' || field === 'OR' || field === 'NOT') {
+                out[field] = Array.isArray(cond) ? cond.map((part) => (isPlainObject(part) ? normalizeWhere(table, part) : part)) : isPlainObject(cond) ? normalizeWhere(table, cond) : cond;
+                continue;
+            }
+            const def = Object.hasOwn(table.fields, field) ? table.fields[field] : undefined;
+            out[field] = def?.dataType === 'email' ? lowerEmail(cond) : cond;
+        }
+        return out;
+    };
+    const findMany = (tableName, args) => {
+        const table = tableOf(tableName);
+        const where = normalizeWhere(table, (args.where ?? {}));
+        refuseSearch(tableName, where);
+        checkListSizes(tableName, where);
+        const keys = orderKeys(table, args.orderBy);
+        const place = afterOf(tableName, keys, args);
+        const anchors = findAnchors(table, where);
+        if (anchors.length === 0) {
+            const why = unstartableWhy(tableName, table, where);
+            if (why)
+                throw new RecordsQueryError(why);
+        }
+        else {
+            noteParents(tableName, table, anchors[0].field, anchors[0].ids);
+        }
+        let rows = filterRows(tableName, allRows(tableName), where);
+        rows = orderRows(keys, rows);
+        rows = pageRows(keys, rows, place, args);
+        include(tableName, rows, args.include, 1);
+        return rows.map((row) => selectFields(tableName, table, row, args.select));
+    };
+    const run = (call) => {
+        calls.push(call);
+        const args = (call.args ?? {});
+        if (!isPlainObject(args))
+            throw new RecordsQueryError(`records.${call.table}.${call.method}: arguments must be an object`);
+        switch (call.method) {
+            case 'findMany':
+                return findMany(call.table, args);
+            case 'findFirst':
+                return findMany(call.table, { ...args, take: 1 })[0] ?? null;
+            case 'findUnique': {
+                const where = (args.where ?? {});
+                const keys = Object.keys(where);
+                if (keys.length !== 1 || keys[0] !== 'id' || typeof where.id !== 'string') {
+                    throw new RecordsQueryError(`records.${call.table}.findUnique: where is { id }`);
+                }
+                return findMany(call.table, { ...args, take: 1 })[0] ?? null;
+            }
+            case 'count':
+                return findMany(call.table, { where: args.where, take: RECORDS_LIMITS.rowsPerCall }).length;
+            default:
+                throw new RecordsQueryError(`records.${call.table}: no method ${String(call.method)} (records is read-only)`);
+        }
+    };
+    return {
+        calls,
+        async execute(batch) {
+            return batch.map((call) => {
+                try {
+                    return { ok: true, value: run(call) };
+                }
+                catch (error) {
+                    if (error instanceof RecordsQueryError)
+                        return { ok: false, error: error.message, code: error.code };
+                    throw error;
+                }
+            });
+        },
+        row(tableName, id) {
+            tableOf(tableName);
+            const data = (given[tableName] ?? []).find((row) => String(row.id) === id);
+            return data ? toRowOut(tableName, data) : null;
+        },
+        rowInfo(id) {
+            const seen = read.get(id);
+            const row = truth.get(id);
+            if (!seen || !row)
+                return undefined;
+            const slots = {};
+            for (const [field, slot] of Object.entries(row)) {
+                if (!slot || typeof slot !== 'object' || Array.isArray(slot))
+                    continue;
+                const { value, state, reason, updatedAt } = slot;
+                slots[field] = { value, state, reason, updatedAt };
+            }
+            return { table: seen.table, slots };
+        },
+        parentsOf(table) {
+            return [...(parents.get(table) ?? [])];
+        },
+        adoptRow(table, row) {
+            read.set(row.id, { table });
+            truth.set(row.id, row);
+        },
+    };
+}
+function lowerEmail(cond) {
+    if (typeof cond === 'string')
+        return cond.trim().toLowerCase();
+    if (!isPlainObject(cond))
+        return cond;
+    const out = {};
+    for (const [op, operand] of Object.entries(cond)) {
+        if (op === 'equals' || op === 'startsWith')
+            out[op] = typeof operand === 'string' ? operand.trim().toLowerCase() : operand;
+        else if (op === 'in' || op === 'notIn')
+            out[op] = Array.isArray(operand) ? operand.map((v) => (typeof v === 'string' ? v.trim().toLowerCase() : v)) : operand;
+        else if (op === 'not')
+            out[op] = lowerEmail(operand);
+        else
+            out[op] = operand;
+    }
+    return out;
+}
+//# sourceMappingURL=memory-reader.js.map

package/dist/core/page/ops.d.ts

@@ -0,0 +1,58 @@
+import type { SlotState } from './define.js';
+import type { RenderedAction, RenderedCell, RenderedPage } from './render.js';
+import type { RowNames } from './render.js';
+/** `add` / `remove`: options added to or taken from a `multi_select`'s value, the rest kept (27 §3.3). */
+export type SlotOp = {
+    slot: string;
+    value?: unknown;
+    add?: unknown;
+    remove?: unknown;
+    state?: SlotState;
+    reason?: string;
+};
+export type ActionOp = {
+    action: string;
+    arguments?: Record<string, unknown>;
+};
+export type OpenOp = {
+    open: string;
+    why?: string;
+};
+export type PageOp = SlotOp | ActionOp | OpenOp;
+export type PageOpsAllowed = {
+    /** Slot ids the AI may change (the page's writable cells). */
+    slots: readonly string[];
+    /** Action ids the AI may press. */
+    actions: readonly string[];
+    /** Block paths the AI may open; empty: no `open`. */
+    open: readonly string[];
+};
+export type ResolvedSlotOp = {
+    kind: 'slot';
+    cell: RenderedCell;
+    value: unknown;
+    /** `empty`: cleared (the customer took it back). */
+    state: SlotState;
+    reason: string | null;
+};
+/** `args`: what the AI filled, rows as ids; the page's prefilled arguments are added when it runs. */
+export type ResolvedActionOp = {
+    kind: 'action';
+    action: RenderedAction;
+    args: Record<string, unknown>;
+};
+export type ResolvedOpenOp = {
+    kind: 'open';
+    path: string;
+    why: string;
+};
+export type ResolvedOp = ResolvedSlotOp | ResolvedActionOp | ResolvedOpenOp;
+export type DroppedOp = {
+    op: unknown;
+    why: string;
+};
+export declare function resolvePageOps(page: RenderedPage, names: RowNames, answer: unknown, allowed: PageOpsAllowed): {
+    ops: ResolvedOp[];
+    dropped: DroppedOp[];
+};
+//# sourceMappingURL=ops.d.ts.map

package/dist/core/page/ops.js

@@ -0,0 +1,220 @@
+/**
+ * What the AI may do to a page (15 §10.6.2, 17b §4): change a slot (a value, `asked_unknown` /
+ * `declined`, or `empty` to clear it; a `multi_select` also by adding or removing options, 27 §3.3) and
+ * press an action. The check that turns its operations into ones
+ * the platform can run — every operation resolved against the page the AI saw, invalid ones dropped one
+ * by one with the reason.
+ */
+import { contactScheduleValueSchema } from '../slot/schema.js';
+import { TIME_VALUE_PATTERN } from '../slot/value.js';
+export function resolvePageOps(page, names, answer, allowed) {
+    const ops = [];
+    const dropped = [];
+    const list = Array.isArray(answer)
+        ? answer
+        : answer && typeof answer === 'object' && Array.isArray(answer.ops)
+            ? answer.ops
+            : null;
+    if (!list)
+        return { ops, dropped: answer == null ? [] : [{ op: answer, why: 'not { ops: [...] }' }] };
+    const slots = new Set(allowed.slots);
+    const actions = new Set(allowed.actions);
+    const opens = new Set(allowed.open);
+    for (const op of list) {
+        if (!op || typeof op !== 'object') {
+            dropped.push({ op, why: 'not an object' });
+            continue;
+        }
+        const o = op;
+        try {
+            if (typeof o.slot === 'string') {
+                if (!slots.has(o.slot))
+                    throw new OpError(`slot ${o.slot} is not editable here`);
+                ops.push(resolveSlot(page, names, page.cells[o.slot], o));
+            }
+            else if (typeof o.action === 'string') {
+                if (!actions.has(o.action))
+                    throw new OpError(`action ${o.action} is not on the page here`);
+                const action = page.actions[o.action];
+                ops.push({ kind: 'action', action, args: resolveArguments(names, action, o.arguments) });
+            }
+            else if (typeof o.open === 'string') {
+                if (!opens.has(o.open))
+                    throw new OpError(`cannot open ${o.open}`);
+                ops.push({ kind: 'open', path: o.open, why: typeof o.why === 'string' ? o.why : '' });
+            }
+            else {
+                throw new OpError('neither slot, action nor open');
+            }
+        }
+        catch (error) {
+            if (!(error instanceof OpError))
+                throw error;
+            dropped.push({ op, why: error.message });
+        }
+    }
+    return { ops, dropped };
+}
+class OpError extends Error {
+}
+const TIME_RE = new RegExp(TIME_VALUE_PATTERN);
+const STATES = new Set(['filled', 'asked_unknown', 'declined', 'empty']);
+function resolveSlot(page, names, cell, o) {
+    const state = (o.state ?? 'filled');
+    if (!STATES.has(state))
+        throw new OpError(`${cell.slotId}: state ${state} is not filled / asked_unknown / declined / empty`);
+    const reason = typeof o.reason === 'string' && o.reason ? o.reason : null;
+    const edits = ['add', 'remove'].filter((key) => key in o);
+    if (edits.length && cell.type !== 'multi_select')
+        throw new OpError(`${cell.slotId}: ${edits.join(' / ')} is for a multi_select field; write value`);
+    if (state !== 'filled') {
+        if (edits.length)
+            throw new OpError(`${cell.slotId}: ${edits.join(' / ')} goes with state filled`);
+        return { kind: 'slot', cell, value: null, state: state, reason };
+    }
+    if (cell.type === 'multi_select')
+        return { kind: 'slot', cell, value: multiSelectValue(cell, o, edits), state: 'filled', reason };
+    if (!('value' in o) || o.value === null || o.value === undefined || o.value === '') {
+        throw new OpError(`${cell.slotId}: filled needs a value`);
+    }
+    let value = o.value;
+    if (cell.options) {
+        // A lookup: the AI names one of the rows on the page.
+        if (typeof value !== 'string' || !cell.options.includes(value)) {
+            throw new OpError(`${cell.slotId}: ${JSON.stringify(value)} is not one of ${cell.options.join(', ') || '(no rows on the page)'}`);
+        }
+        const row = names.resolve(value);
+        if (!row)
+            throw new OpError(`${cell.slotId}: ${value} is not a row on the page`);
+        value = row.id;
+    }
+    else {
+        value = coerce(cell.slotId, cell.type, cell.choices, value);
+    }
+    return { kind: 'slot', cell, value, state: 'filled', reason };
+}
+/**
+ * A `multi_select`'s new value (27 §3.3): `value` replaces the list, `add` / `remove` change the one
+ * the AI saw on the page and keep the rest. In the options' order, each once.
+ */
+function multiSelectValue(cell, o, edits) {
+    const choices = cell.choices ?? [];
+    const given = edits.length ? edits : ['value'];
+    if (given.length + (edits.length && 'value' in o ? 1 : 0) > 1)
+        throw new OpError(`${cell.slotId}: one of value, add or remove at a time`);
+    const key = given[0];
+    const raw = o[key];
+    if (raw === null || raw === undefined)
+        throw new OpError(`${cell.slotId}: filled needs ${key}`);
+    // One option alone is taken as a list of one.
+    const list = Array.isArray(raw) ? raw : [raw];
+    const outside = list.filter((item) => typeof item !== 'string' || !choices.includes(item));
+    if (outside.length) {
+        throw new OpError(`${cell.slotId}: ${outside.map((v) => JSON.stringify(v)).join(', ')} not one of ${choices.map((v) => JSON.stringify(v)).join(', ')}`);
+    }
+    const now = cell.state === 'filled' && Array.isArray(cell.value) ? cell.value : [];
+    const next = new Set(key === 'value' ? list : now);
+    if (key === 'add')
+        for (const item of list)
+            next.add(item);
+    if (key === 'remove')
+        for (const item of list)
+            next.delete(item);
+    return choices.filter((choice) => next.has(choice));
+}
+function resolveArguments(names, action, raw) {
+    if (!action.input) {
+        if (raw && typeof raw === 'object' && Object.keys(raw).length)
+            throw new OpError(`${action.id}: takes no arguments`);
+        return {};
+    }
+    return resolveObject(names, action.id, action.input.properties, action.input.required, raw ?? {});
+}
+function resolveObject(names, where, properties, required, raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        throw new OpError(`${where}: arguments must be an object`);
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        const prop = properties[key];
+        if (!prop)
+            throw new OpError(`${where}: ${key} is not an argument here`);
+        if (value === null || value === undefined || value === '')
+            continue;
+        out[key] = resolveValue(names, `${where}.${key}`, prop, value);
+    }
+    for (const key of required ?? []) {
+        if (!(key in out))
+            throw new OpError(`${where}: ${key} is required`);
+    }
+    return out;
+}
+function resolveValue(names, where, prop, value) {
+    if (prop.type === 'array') {
+        if (!Array.isArray(value))
+            throw new OpError(`${where}: must be a list`);
+        return value.map((item, i) => resolveValue(names, `${where}[${i}]`, prop.items, item));
+    }
+    if (prop.type === 'object' && prop['x-type'] === 'contact_schedule') {
+        // Checked as the field checks it; `run` gets the schedule as it is.
+        const parsed = contactScheduleValueSchema.safeParse(value);
+        if (parsed.success)
+            return value;
+        const issue = parsed.error.issues[0];
+        throw new OpError(`${where}: not a contact schedule (${issue.path.join('.') || 'value'}: ${issue.message})`);
+    }
+    if (prop.type === 'object')
+        return resolveObject(names, where, prop.properties, prop.required, value);
+    if (prop.type === 'ref') {
+        // A row choice: one of the rows on the page, by page name; `run` gets its id.
+        const row = typeof value === 'string' && prop.enum.includes(value) ? names.resolve(value) : undefined;
+        if (!row)
+            throw new OpError(`${where}: must be one of ${prop.enum.join(', ') || '(no rows on the page)'}`);
+        return row.id;
+    }
+    if (prop.type === 'multi_select') {
+        // As a fill writes it: one option alone is a list of one; each once, in the options' order.
+        const list = Array.isArray(value) ? value : [value];
+        const outside = list.filter((item) => !prop.enum.includes(item));
+        if (outside.length)
+            throw new OpError(`${where}: ${outside.map((v) => JSON.stringify(v)).join(', ')} not one of ${prop.enum.map((v) => JSON.stringify(v)).join(', ')}`);
+        return prop.enum.filter((option) => list.includes(option));
+    }
+    // A schema field's argument is checked as a fill of the field is.
+    return coerce(where, prop.type === 'integer' ? 'number' : prop.type, prop.enum ?? null, value);
+}
+function coerce(where, type, enumValues, value) {
+    let out = value;
+    if (type === 'number') {
+        out = typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value)) ? Number(value) : value;
+        if (typeof out !== 'number' || !Number.isFinite(out))
+            throw new OpError(`${where}: ${JSON.stringify(value)} is not a number`);
+    }
+    else if (type === 'boolean') {
+        out = value === 'true' ? true : value === 'false' ? false : value;
+        if (typeof out !== 'boolean')
+            throw new OpError(`${where}: ${JSON.stringify(value)} is not true / false`);
+    }
+    else if (type === 'date') {
+        if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+            throw new OpError(`${where}: ${JSON.stringify(value)} is not YYYY-MM-DD`);
+    }
+    else if (type === 'datetime') {
+        if (typeof value !== 'string' || Number.isNaN(Date.parse(value)))
+            throw new OpError(`${where}: ${JSON.stringify(value)} is not a date-time`);
+    }
+    else if (type === 'time') {
+        if (typeof value !== 'string' || !TIME_RE.test(value))
+            throw new OpError(`${where}: ${JSON.stringify(value)} is not a time of day HH:mm, 24-hour (15:30)`);
+    }
+    else if (type === 'string' || type === 'select' || type === 'text' || type === 'phone' || type === 'email') {
+        if (typeof value === 'number' || typeof value === 'boolean')
+            out = String(value);
+        if (typeof out !== 'string')
+            throw new OpError(`${where}: ${JSON.stringify(value)} is not text`);
+    }
+    if (enumValues && !enumValues.includes(out)) {
+        throw new OpError(`${where}: ${JSON.stringify(value)} is not one of ${enumValues.map((v) => JSON.stringify(v)).join(', ')}`);
+    }
+    return out;
+}
+//# sourceMappingURL=ops.js.map

package/dist/core/page/page-host.d.ts

@@ -0,0 +1,20 @@
+import type { HostResult } from './sandbox.js';
+/** The zone a page reads time in when the contact gives none. */
+export declare const DEFAULT_PAGE_ZONE = "America/New_York";
+/** A row as `db` hands it out, as far as its time zone goes: each field a slot with a `value`. */
+type CallerRow = Record<string, unknown> | null;
+/** The contact's zone (their `timezone`, else from postal code, state or phone) and today there (25 §11). */
+export declare function timeOfCaller(caller: CallerRow, now: Date): {
+    zone: string;
+    today: string;
+};
+/** `ctx.time.format` (25 §11). */
+export declare function timeCall(args: unknown[]): HostResult;
+/** `ctx.time.day` (25 §11). */
+export declare function dayCall(args: unknown[]): HostResult;
+/** `ctx.time.at` (74 §4.7): a day and a wall time in a zone, as an instant. */
+export declare function atCall(args: unknown[]): HostResult;
+/** `ctx.time.parts` (74 §4.7): an instant's wall-clock parts in a zone. */
+export declare function partsCall(args: unknown[]): HostResult;
+export {};
+//# sourceMappingURL=page-host.d.ts.map

package/dist/core/page/page-host.js

@@ -0,0 +1,57 @@
+/**
+ * The page script's host calls that read no data (25 §11, 74 §4.7): `ctx.time.format`, `.day`, `.at` and `.parts`, done
+ * outside the sandbox where `Intl` is, and the caller's zone and today. The platform's render and the
+ * runtime's page unit tests answer them with these.
+ */
+import { contactTimezone } from '../slot/contact-timezone.js';
+import { dayIn, formatTime, timeAt, timeParts } from './time-format.js';
+/** The zone a page reads time in when the contact gives none. */
+export const DEFAULT_PAGE_ZONE = 'America/New_York';
+/** The contact's zone (their `timezone`, else from postal code, state or phone) and today there (25 §11). */
+export function timeOfCaller(caller, now) {
+    const value = (name) => caller?.[name]?.value;
+    const zone = contactTimezone({ timezone: value('timezone'), postal_code: value('postal_code'), state: value('state'), country: value('country'), phone: value('phone') }, DEFAULT_PAGE_ZONE).timezone;
+    return { zone, today: dayIn(now, zone) };
+}
+/** `ctx.time.format` (25 §11). */
+export function timeCall(args) {
+    const [at, options] = args;
+    try {
+        if (typeof at !== 'string' && typeof at !== 'number')
+            throw new Error('time.format: give an ISO time');
+        return { ok: true, value: formatTime(at, { timeZone: String(options?.timeZone ?? DEFAULT_PAGE_ZONE), ...(options?.style ? { style: options.style } : {}) }) };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** `ctx.time.day` (25 §11). */
+export function dayCall(args) {
+    const [at, timeZone] = args;
+    try {
+        if (typeof at !== 'string' && typeof at !== 'number')
+            throw new Error('time.day: give an ISO time');
+        return { ok: true, value: dayIn(at, String(timeZone ?? DEFAULT_PAGE_ZONE)) };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** `ctx.time.at` / `ctx.time.parts` (74 §4.7). */
+function hostTime(work) {
+    try {
+        return { ok: true, value: work() };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** `ctx.time.at` (74 §4.7): a day and a wall time in a zone, as an instant. */
+export function atCall(args) {
+    return hostTime(() => timeAt(String(args[0]), String(args[1]), String(args[2] ?? DEFAULT_PAGE_ZONE)));
+}
+/** `ctx.time.parts` (74 §4.7): an instant's wall-clock parts in a zone. */
+export function partsCall(args) {
+    return hostTime(() => timeParts(args[0], String(args[1] ?? DEFAULT_PAGE_ZONE)));
+}
+//# sourceMappingURL=page-host.js.map