@superpanel-sdk/runtime 0.0.1-internal.1

package/dist/core/slot/deps.d.ts

@@ -0,0 +1,15 @@
+import type { FieldPath } from './path.js';
+import type { RuntimeTableDef, ValidationIssue } from './types.js';
+export type DependencyGraphResult = {
+    derivedOrder: FieldPath[];
+    reverseDeps: Record<FieldPath, FieldPath[]>;
+    issues: ValidationIssue[];
+};
+/**
+ * Build topological order of derived fields and reverse dependency index.
+ * Reports cycles instead of throwing.
+ */
+export declare function buildDependencyGraph(tables: Record<string, RuntimeTableDef>): DependencyGraphResult;
+/** Collect derived fields affected by changed columns, in topo order. */
+export declare function affectedDerivedFields(changed: Iterable<FieldPath>, reverseDeps: Record<FieldPath, FieldPath[]>, derivedOrder: FieldPath[]): FieldPath[];
+//# sourceMappingURL=deps.d.ts.map

package/dist/core/slot/deps.js

@@ -0,0 +1,88 @@
+import { formatFieldPath, parseFieldPath } from './path.js';
+/**
+ * Build topological order of derived fields and reverse dependency index.
+ * Reports cycles instead of throwing.
+ */
+export function buildDependencyGraph(tables) {
+    const issues = [];
+    const derivedPaths = [];
+    const edges = new Map();
+    const reverseDeps = {};
+    for (const [tableName, table] of Object.entries(tables)) {
+        for (const [fieldName, field] of Object.entries(table.fields)) {
+            if (!field.derived)
+                continue;
+            const path = formatFieldPath(tableName, fieldName);
+            derivedPaths.push(path);
+            const deps = [];
+            for (const dep of field.dependsOn) {
+                const parsed = parseFieldPath(dep);
+                if (!parsed) {
+                    issues.push({
+                        code: 'invalid-depends-on',
+                        message: `Invalid dependsOn path: ${dep}`,
+                        path,
+                    });
+                    continue;
+                }
+                deps.push(parsed.path);
+                if (!reverseDeps[parsed.path])
+                    reverseDeps[parsed.path] = [];
+                reverseDeps[parsed.path].push(path);
+            }
+            edges.set(path, deps);
+        }
+    }
+    // Kahn topological sort over derived nodes only; edges point to dependencies.
+    const indegree = new Map();
+    const dependents = new Map();
+    for (const path of derivedPaths) {
+        indegree.set(path, 0);
+        dependents.set(path, []);
+    }
+    for (const [path, deps] of edges) {
+        for (const dep of deps) {
+            if (!indegree.has(dep))
+                continue; // dependency is a normal field
+            indegree.set(path, (indegree.get(path) ?? 0) + 1);
+            dependents.get(dep).push(path);
+        }
+    }
+    const queue = derivedPaths.filter((p) => (indegree.get(p) ?? 0) === 0);
+    const derivedOrder = [];
+    while (queue.length > 0) {
+        const path = queue.shift();
+        derivedOrder.push(path);
+        for (const next of dependents.get(path) ?? []) {
+            const nextDeg = (indegree.get(next) ?? 0) - 1;
+            indegree.set(next, nextDeg);
+            if (nextDeg === 0)
+                queue.push(next);
+        }
+    }
+    if (derivedOrder.length !== derivedPaths.length) {
+        const remaining = derivedPaths.filter((p) => !derivedOrder.includes(p));
+        issues.push({
+            code: 'cyclic-dependency',
+            message: `Cyclic derived dependency involving: ${remaining.join(' → ')}`,
+            path: remaining[0],
+        });
+    }
+    return { derivedOrder, reverseDeps, issues };
+}
+/** Collect derived fields affected by changed columns, in topo order. */
+export function affectedDerivedFields(changed, reverseDeps, derivedOrder) {
+    const hit = new Set();
+    const stack = [...changed];
+    while (stack.length > 0) {
+        const path = stack.pop();
+        for (const derived of reverseDeps[path] ?? []) {
+            if (hit.has(derived))
+                continue;
+            hit.add(derived);
+            stack.push(derived);
+        }
+    }
+    return derivedOrder.filter((path) => hit.has(path));
+}
+//# sourceMappingURL=deps.js.map

package/dist/core/slot/derived.d.ts

@@ -0,0 +1,32 @@
+import type { Writes } from '../context/types.js';
+import type { FieldPath } from './path.js';
+import type { ApplyWritesOptions, CompiledSlotSchema, RecomputeResult, RuntimeSlotsSnapshot, SlotFillingOutput } from './types.js';
+import { createLocalComputeHost, resolveComputeHost, type ComputeFnMap, type ComputeHost, type ComputeHostOrFns, type LocalComputeHostOptions } from '../../compute-host/compute-host.js';
+import { createSourceComputeHost } from '../../compute-host/source-compute-host.js';
+import { type ApplySlotFillingOptions, type FieldPatchInput } from './write.js';
+export type { ComputeFnMap, ComputeHost, ComputeHostOrFns, LocalComputeHostOptions };
+export { createLocalComputeHost, createSourceComputeHost, resolveComputeHost };
+export type RecomputeOptions = {
+    now?: number;
+    /**
+     * When true, recompute every derived field in topo order (session start heal).
+     * When false (default), only fields affected by `changed`.
+     */
+    all?: boolean;
+    changed?: Iterable<FieldPath>;
+};
+/**
+ * C6: recompute derived fields in topological order via {@link ComputeHost}.
+ * `null` return means no conclusion yet (stored as filled+null).
+ */
+export declare function recomputeDerived(schema: CompiledSlotSchema, snapshot: RuntimeSlotsSnapshot, hostOrFns: ComputeHostOrFns, options?: RecomputeOptions): Promise<RecomputeResult>;
+/** C4→C6: apply normal writes then recompute affected derived fields. */
+export declare function applyWritesAndRecompute(schema: CompiledSlotSchema, snapshot: RuntimeSlotsSnapshot, writes: Writes | null | undefined, hostOrFns: ComputeHostOrFns, writeOptions: ApplyWritesOptions): Promise<RecomputeResult>;
+/** Apply an explicit-state field edit, then recompute every affected derived field. */
+export declare function applyFieldPatchAndRecompute(schema: CompiledSlotSchema, snapshot: RuntimeSlotsSnapshot, patch: FieldPatchInput, hostOrFns: ComputeHostOrFns, options: {
+    source: ApplyWritesOptions['source'];
+    now?: number;
+}): Promise<RecomputeResult>;
+/** C4→C6 for accepted Slot Filling output. */
+export declare function applySlotFillingAndRecompute(schema: CompiledSlotSchema, snapshot: RuntimeSlotsSnapshot, output: SlotFillingOutput, hostOrFns: ComputeHostOrFns, options?: ApplySlotFillingOptions): Promise<RecomputeResult>;
+//# sourceMappingURL=derived.d.ts.map

package/dist/core/slot/derived.js

@@ -0,0 +1,115 @@
+import { getCompiledTable, isSnapshotSingleRow } from './compile-schema.js';
+import { createLocalComputeHost, resolveComputeHost, } from '../../compute-host/compute-host.js';
+import { createSourceComputeHost } from '../../compute-host/source-compute-host.js';
+import { affectedDerivedFields } from './deps.js';
+import { commitFieldWrite, makeFieldValue } from './field.js';
+import { requireFieldPath } from './path.js';
+import { getRowField } from './row.js';
+import { cloneSnapshot, getSnapshotTable } from './snapshot.js';
+import { validateBareValue } from './value.js';
+import { applyFieldPatch, applySlotFilling, applyWrites, } from './write.js';
+export { createLocalComputeHost, createSourceComputeHost, resolveComputeHost };
+/**
+ * C6: recompute derived fields in topological order via {@link ComputeHost}.
+ * `null` return means no conclusion yet (stored as filled+null).
+ */
+export async function recomputeDerived(schema, snapshot, hostOrFns, options = {}) {
+    const host = resolveComputeHost(hostOrFns);
+    const now = options.now ?? Date.now();
+    const next = cloneSnapshot(snapshot);
+    const changedOut = [];
+    const history = [];
+    const targets = options.all
+        ? schema.derivedOrder
+        : affectedDerivedFields(options.changed ?? [], schema.reverseDeps, schema.derivedOrder);
+    for (const path of targets) {
+        const parsed = requireFieldPath(path);
+        const table = getCompiledTable(schema, parsed.table);
+        const field = table?.fields[parsed.field];
+        if (!table || !field || !field.derived)
+            continue;
+        if (!isSnapshotSingleRow(table))
+            continue;
+        const raw = await host.execute(field.computeFn, [next]);
+        const issues = validateBareValue(field, raw, path, { allowNull: true });
+        if (issues.length > 0) {
+            throw new Error(`Derived ${path} returned invalid value: ${issues.map((i) => i.message).join('; ')}`);
+        }
+        const tableData = getSnapshotTable(next, parsed.table);
+        const prev = getRowField(tableData, parsed.field);
+        if (!prev)
+            continue;
+        const committed = commitFieldWrite(prev, makeFieldValue({
+            value: (raw ?? null),
+            state: 'filled',
+            reason: null,
+            updatedBy: 'derived',
+            updatedAt: now,
+        }));
+        tableData[parsed.field] = committed.field;
+        if (committed.changed) {
+            changedOut.push(path);
+            if (committed.historyEntry) {
+                history.push({ path, entry: committed.historyEntry });
+            }
+        }
+    }
+    return { snapshot: next, changed: changedOut, history };
+}
+/** C4→C6: apply normal writes then recompute affected derived fields. */
+export async function applyWritesAndRecompute(schema, snapshot, writes, hostOrFns, writeOptions) {
+    const applied = applyWrites(schema, snapshot, writes, writeOptions);
+    if (applied.changed.length === 0) {
+        return {
+            snapshot: applied.snapshot,
+            changed: [],
+            history: applied.history,
+        };
+    }
+    const recomputed = await recomputeDerived(schema, applied.snapshot, hostOrFns, {
+        now: writeOptions.now,
+        changed: applied.changed,
+    });
+    return {
+        snapshot: recomputed.snapshot,
+        changed: [...applied.changed, ...recomputed.changed],
+        history: [...applied.history, ...recomputed.history],
+    };
+}
+/** Apply an explicit-state field edit, then recompute every affected derived field. */
+export async function applyFieldPatchAndRecompute(schema, snapshot, patch, hostOrFns, options) {
+    const applied = applyFieldPatch(schema, snapshot, patch, options);
+    if (applied.changed.length === 0) {
+        return { snapshot: applied.snapshot, changed: [], history: applied.history };
+    }
+    const recomputed = await recomputeDerived(schema, applied.snapshot, hostOrFns, {
+        now: options.now,
+        changed: applied.changed,
+    });
+    return {
+        snapshot: recomputed.snapshot,
+        changed: [...applied.changed, ...recomputed.changed],
+        history: [...applied.history, ...recomputed.history],
+    };
+}
+/** C4→C6 for accepted Slot Filling output. */
+export async function applySlotFillingAndRecompute(schema, snapshot, output, hostOrFns, options = {}) {
+    const applied = applySlotFilling(schema, snapshot, output, options);
+    if (applied.changed.length === 0) {
+        return {
+            snapshot: applied.snapshot,
+            changed: [],
+            history: applied.history,
+        };
+    }
+    const recomputed = await recomputeDerived(schema, applied.snapshot, hostOrFns, {
+        now: options.now,
+        changed: applied.changed,
+    });
+    return {
+        snapshot: recomputed.snapshot,
+        changed: [...applied.changed, ...recomputed.changed],
+        history: [...applied.history, ...recomputed.history],
+    };
+}
+//# sourceMappingURL=derived.js.map

package/dist/core/slot/field.d.ts

@@ -0,0 +1,36 @@
+import type { FieldState } from '../context/types.js';
+import type { FieldHistoryEntry, FieldValue, UpdatedBy } from './types.js';
+/** Stage done checks use resolved, not "has a value". */
+export declare function isResolved(field: FieldValue | null | undefined): boolean;
+export declare function emptyFieldValue(now?: number): FieldValue;
+export declare function makeFieldValue(partial: {
+    value: string | number | boolean | null;
+    state: FieldState;
+    reason?: string | null;
+    updatedBy?: UpdatedBy;
+    updatedAt?: number;
+    history?: FieldHistoryEntry[];
+}): FieldValue;
+/**
+ * C5 change detection: value or state changed.
+ * reason-only updates do not count (01-slot-design §2 iron rule).
+ */
+export declare function fieldChanged(prev: FieldValue | undefined, next: FieldValue): boolean;
+export declare function toHistoryEntry(field: FieldValue): FieldHistoryEntry;
+export type CommitFieldWriteResult = {
+    field: FieldValue;
+    changed: boolean;
+    /** Previous generation archived into `field.history` (absent when unchanged or prev was empty). */
+    historyEntry?: FieldHistoryEntry;
+};
+/**
+ * Apply a write onto a field envelope.
+ * - C5 change: archive previous non-empty generation into `history`, then replace current
+ * - reason-only: update reason, keep value/state/history/updated*
+ */
+export declare function commitFieldWrite(prev: FieldValue | undefined, next: FieldValue): CommitFieldWriteResult;
+/** Last N generation values: prior history entries + current value (01-slot-db §4.2). */
+export declare function getLastThreeValues(field: FieldValue, n?: number): Array<string | number | boolean | null>;
+export declare function getFieldValue(field: FieldValue | null | undefined): string | number | boolean | null;
+export declare function getFieldState(field: FieldValue | null | undefined): FieldState;
+//# sourceMappingURL=field.d.ts.map

package/dist/core/slot/field.js

@@ -0,0 +1,97 @@
+const RESOLVED = new Set(['filled', 'asked_unknown', 'declined']);
+/** Stage done checks use resolved, not "has a value". */
+export function isResolved(field) {
+    if (!field)
+        return false;
+    return RESOLVED.has(field.state);
+}
+export function emptyFieldValue(now = 0) {
+    return {
+        reason: null,
+        value: null,
+        state: 'empty',
+        updatedAt: now,
+        updatedBy: 'platform',
+        history: [],
+    };
+}
+export function makeFieldValue(partial) {
+    return {
+        reason: partial.reason ?? null,
+        value: partial.value,
+        state: partial.state,
+        updatedAt: partial.updatedAt ?? 0,
+        updatedBy: partial.updatedBy ?? 'platform',
+        history: partial.history ?? [],
+    };
+}
+/**
+ * C5 change detection: value or state changed.
+ * reason-only updates do not count (01-slot-design §2 iron rule).
+ */
+export function fieldChanged(prev, next) {
+    if (!prev) {
+        return next.state !== 'empty' || next.value !== null;
+    }
+    return prev.value !== next.value || prev.state !== next.state;
+}
+export function toHistoryEntry(field) {
+    return {
+        value: field.value,
+        state: field.state,
+        at: field.updatedAt,
+        by: field.updatedBy,
+    };
+}
+/**
+ * Apply a write onto a field envelope.
+ * - C5 change: archive previous non-empty generation into `history`, then replace current
+ * - reason-only: update reason, keep value/state/history/updated*
+ */
+export function commitFieldWrite(prev, next) {
+    if (!fieldChanged(prev, next)) {
+        if (!prev) {
+            return {
+                field: makeFieldValue({ ...next, history: [] }),
+                changed: false,
+            };
+        }
+        return {
+            field: {
+                ...prev,
+                reason: next.reason,
+            },
+            changed: false,
+        };
+    }
+    const history = [...(prev?.history ?? [])];
+    let historyEntry;
+    if (prev && prev.state !== 'empty') {
+        historyEntry = toHistoryEntry(prev);
+        history.push(historyEntry);
+    }
+    return {
+        field: makeFieldValue({
+            value: next.value,
+            state: next.state,
+            reason: next.reason,
+            updatedBy: next.updatedBy,
+            updatedAt: next.updatedAt,
+            history,
+        }),
+        changed: true,
+        ...(historyEntry ? { historyEntry } : {}),
+    };
+}
+/** Last N generation values: prior history entries + current value (01-slot-db §4.2). */
+export function getLastThreeValues(field, n = 3) {
+    const generations = [...field.history.map((h) => h.value), field.value];
+    return generations.slice(-n);
+}
+export function getFieldValue(field) {
+    return field?.value ?? null;
+}
+export function getFieldState(field) {
+    return field?.state ?? 'empty';
+}
+//# sourceMappingURL=field.js.map

package/dist/core/slot/id-ref.d.ts

@@ -0,0 +1,4 @@
+import type { CompanyNormalFieldDef } from './schema.js';
+/** System string field that stores `{table}.id`. */
+export declare function idRef(table: string, extras?: Pick<Partial<CompanyNormalFieldDef>, 'label' | 'nullable' | 'extraction'>): CompanyNormalFieldDef;
+//# sourceMappingURL=id-ref.d.ts.map

package/dist/core/slot/id-ref.js

@@ -0,0 +1,15 @@
+/** System string field that stores `{table}.id`. */
+export function idRef(table, extras) {
+    return {
+        derived: false,
+        label: extras?.label ?? table,
+        dataType: 'string',
+        source: 'system',
+        extraction: extras?.extraction ?? `Reference to ${table}.id`,
+        enum: null,
+        nullable: extras?.nullable ?? false,
+        identifier: null,
+        ref: { table },
+    };
+}
+//# sourceMappingURL=id-ref.js.map

package/dist/core/slot/index.d.ts

@@ -0,0 +1,15 @@
+export { ROW_ID_FIELD, idField, idFieldCore } from './schema.js';
+export { idRef } from './id-ref.js';
+export { emptyMultiRow, emptySlotRow, getRowField, isFieldValue, isReservedTableName, isRowIdField, mintRowId, SNAPSHOT_CURRENT_KEY, rowValueEntries, slotFieldEntries, slotFieldNames, type SlotRow, } from './row.js';
+export { parseFieldPath, requireFieldPath, formatFieldPath, type FieldPath, type ParsedFieldPath } from './path.js';
+export { isResolved, emptyFieldValue, makeFieldValue, fieldChanged, commitFieldWrite, getLastThreeValues, toHistoryEntry, getFieldValue, getFieldState, type CommitFieldWriteResult, } from './field.js';
+export { buildDependencyGraph, affectedDerivedFields, type DependencyGraphResult } from './deps.js';
+export { compileSlotSchema, compiledTableEntries, getCompiledTable, validateFieldRefs, toEffectiveSchema, listConversationFields, isSnapshotSingleRow, } from './compile-schema.js';
+export { isValidDataTypeValue, validateExtractedField, validateBareValue } from './value.js';
+export { buildSlotFillingJsonSchema, buildFieldCatalog, type SfSchemaOptions } from './sf-schema.js';
+export { validateSlotFillingOutput, type ValidateSlotFillingOptions } from './sf-validate.js';
+export { snapshotFrom, cloneSnapshot, getSingleField, getSnapshotTable, type SnapshotSeed } from './snapshot.js';
+export { applyFieldPatch, applyWrites, applySlotFilling, markAskedUnknown, type ApplySlotFillingOptions, type FieldPatchInput, } from './write.js';
+export type { ComputeFnMap, ComputeHost, ComputeHostOrFns, LocalComputeHostOptions, RecomputeOptions, } from './derived.js';
+export { createLocalComputeHost, createSourceComputeHost, resolveComputeHost, recomputeDerived, applyFieldPatchAndRecompute, applyWritesAndRecompute, applySlotFillingAndRecompute, } from './derived.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/slot/index.js

@@ -0,0 +1,14 @@
+export { ROW_ID_FIELD, idField, idFieldCore } from './schema.js';
+export { idRef } from './id-ref.js';
+export { emptyMultiRow, emptySlotRow, getRowField, isFieldValue, isReservedTableName, isRowIdField, mintRowId, SNAPSHOT_CURRENT_KEY, rowValueEntries, slotFieldEntries, slotFieldNames, } from './row.js';
+export { parseFieldPath, requireFieldPath, formatFieldPath } from './path.js';
+export { isResolved, emptyFieldValue, makeFieldValue, fieldChanged, commitFieldWrite, getLastThreeValues, toHistoryEntry, getFieldValue, getFieldState, } from './field.js';
+export { buildDependencyGraph, affectedDerivedFields } from './deps.js';
+export { compileSlotSchema, compiledTableEntries, getCompiledTable, validateFieldRefs, toEffectiveSchema, listConversationFields, isSnapshotSingleRow, } from './compile-schema.js';
+export { isValidDataTypeValue, validateExtractedField, validateBareValue } from './value.js';
+export { buildSlotFillingJsonSchema, buildFieldCatalog } from './sf-schema.js';
+export { validateSlotFillingOutput } from './sf-validate.js';
+export { snapshotFrom, cloneSnapshot, getSingleField, getSnapshotTable } from './snapshot.js';
+export { applyFieldPatch, applyWrites, applySlotFilling, markAskedUnknown, } from './write.js';
+export { createLocalComputeHost, createSourceComputeHost, resolveComputeHost, recomputeDerived, applyFieldPatchAndRecompute, applyWritesAndRecompute, applySlotFillingAndRecompute, } from './derived.js';
+//# sourceMappingURL=index.js.map

package/dist/core/slot/path.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Field path: `table.field`
+ *
+ * Defined here, next to its parse/format helpers, so the lowest layers
+ * (`functions`, `context`) can name a field without reaching into `schema.js`.
+ */
+export type FieldPath = `${string}.${string}`;
+export type ParsedFieldPath = {
+    table: string;
+    field: string;
+    path: FieldPath;
+};
+/** Parse a `table.field` reference. Returns null when the shape is invalid. */
+export declare function parseFieldPath(ref: string): ParsedFieldPath | null;
+/** Require a valid `table.field` path or throw. */
+export declare function requireFieldPath(ref: string): ParsedFieldPath;
+export declare function formatFieldPath(table: string, field: string): FieldPath;
+//# sourceMappingURL=path.d.ts.map

package/dist/core/slot/path.js

@@ -0,0 +1,22 @@
+const FIELD_PATH_RE = /^([A-Za-z_][A-Za-z0-9_]*)\.([A-Za-z_][A-Za-z0-9_]*)$/;
+/** Parse a `table.field` reference. Returns null when the shape is invalid. */
+export function parseFieldPath(ref) {
+    const match = FIELD_PATH_RE.exec(ref);
+    if (!match)
+        return null;
+    const table = match[1];
+    const field = match[2];
+    return { table, field, path: `${table}.${field}` };
+}
+/** Require a valid `table.field` path or throw. */
+export function requireFieldPath(ref) {
+    const parsed = parseFieldPath(ref);
+    if (!parsed) {
+        throw new Error(`Invalid field path: ${ref}`);
+    }
+    return parsed;
+}
+export function formatFieldPath(table, field) {
+    return `${table}.${field}`;
+}
+//# sourceMappingURL=path.js.map

package/dist/core/slot/row.d.ts

@@ -0,0 +1,22 @@
+import { ROW_ID_FIELD } from './schema.js';
+import type { FieldValue, MultiRowRecord, SingleRowTableData } from './types.js';
+export type SlotRow = SingleRowTableData | MultiRowRecord;
+/** Reserved snapshot key; cannot be a company / sequence table name. */
+export declare const SNAPSHOT_CURRENT_KEY = "current";
+export declare function isReservedTableName(tableName: string): boolean;
+/** App-minted row id for jsonb-hosted tables. */
+export declare function mintRowId(): string;
+export declare function isRowIdField(name: string): name is typeof ROW_ID_FIELD;
+export declare function isFieldValue(value: unknown): value is FieldValue;
+export declare function getRowField(row: SlotRow, fieldName: string): FieldValue | undefined;
+/** Schema fields that store envelopes — excludes row `id`. */
+export declare function slotFieldEntries<T>(fields: Record<string, T>): Array<[string, T]>;
+export declare function slotFieldNames(fields: Record<string, unknown>): string[];
+/** Envelope cells on a runtime row — excludes `id`. */
+export declare function rowValueEntries(row: SlotRow): Array<[string, FieldValue]>;
+export declare function emptySlotRow(fields: Record<string, unknown>, options?: {
+    id?: string;
+    now?: number;
+}): SingleRowTableData;
+export declare function emptyMultiRow(fields: Record<string, unknown>, id: string, now?: number): MultiRowRecord;
+//# sourceMappingURL=row.d.ts.map

package/dist/core/slot/row.js

@@ -0,0 +1,54 @@
+import { emptyFieldValue } from './field.js';
+import { ROW_ID_FIELD } from './schema.js';
+/** Reserved snapshot key; cannot be a company / sequence table name. */
+export const SNAPSHOT_CURRENT_KEY = 'current';
+const RESERVED_TABLE_NAMES = new Set([SNAPSHOT_CURRENT_KEY, 'derivedOrder', 'reverseDeps']);
+export function isReservedTableName(tableName) {
+    return RESERVED_TABLE_NAMES.has(tableName);
+}
+/** App-minted row id for jsonb-hosted tables. */
+export function mintRowId() {
+    return crypto.randomUUID();
+}
+export function isRowIdField(name) {
+    return name === ROW_ID_FIELD;
+}
+export function isFieldValue(value) {
+    return typeof value === 'object' && value !== null && 'state' in value && 'value' in value;
+}
+export function getRowField(row, fieldName) {
+    if (isRowIdField(fieldName))
+        return undefined;
+    const value = row[fieldName];
+    return isFieldValue(value) ? value : undefined;
+}
+/** Schema fields that store envelopes — excludes row `id`. */
+export function slotFieldEntries(fields) {
+    return Object.entries(fields).filter(([name]) => !isRowIdField(name));
+}
+export function slotFieldNames(fields) {
+    return slotFieldEntries(fields).map(([name]) => name);
+}
+/** Envelope cells on a runtime row — excludes `id`. */
+export function rowValueEntries(row) {
+    const out = [];
+    for (const [name, value] of Object.entries(row)) {
+        if (isRowIdField(name) || !isFieldValue(value))
+            continue;
+        out.push([name, value]);
+    }
+    return out;
+}
+export function emptySlotRow(fields, options = {}) {
+    return fillRowFields({ id: options.id ?? '' }, fields, options.now ?? 0);
+}
+export function emptyMultiRow(fields, id, now = 0) {
+    return fillRowFields({ id }, fields, now);
+}
+function fillRowFields(row, fields, now) {
+    for (const name of slotFieldNames(fields)) {
+        row[name] = emptyFieldValue(now);
+    }
+    return row;
+}
+//# sourceMappingURL=row.js.map

package/dist/core/slot/schema.d.ts

@@ -0,0 +1,102 @@
+import type { FuncRef } from '../functions/func-ref.js';
+import type { FieldPath } from './path.js';
+export type DataType = 'string' | 'number' | 'boolean' | 'date' | 'datetime';
+/** Shared core for normal (non-derived) fields — company + session. */
+export type NormalFieldCore = {
+    derived: false;
+    label: string;
+    dataType: DataType;
+    source: 'conversation' | 'system';
+    extraction: string;
+    enum: Array<string | number> | null;
+    nullable: boolean;
+};
+/** Reserved row-identity field name. Authors should not invent another. */
+export declare const ROW_ID_FIELD = "id";
+export declare const idFieldCore: {
+    readonly derived: false;
+    readonly label: 'Id';
+    readonly dataType: 'string';
+    readonly source: 'system';
+    readonly extraction: 'Row identity';
+    readonly enum: null;
+    readonly nullable: false;
+};
+/** Unified row id. Write `id: idField` on every table. */
+export declare const idField: {
+    readonly derived: false;
+    readonly label: 'Id';
+    readonly dataType: 'string';
+    readonly source: 'system';
+    readonly extraction: 'Row identity';
+    readonly enum: null;
+    readonly nullable: false;
+    readonly identifier: null;
+};
+export type CompanyNormalFieldDef = NormalFieldCore & {
+    /**
+     * Whether this field can reverse-look up a party.
+     * Sequence configs must not override this.
+     */
+    identifier: null | {
+        kind: 'phone' | 'email';
+    };
+    /** Present only on reference fields. Always points at `{table}.id`. */
+    ref?: {
+        table: string;
+    };
+    deprecated?: boolean;
+};
+export type CompanyDerivedFieldDef = {
+    derived: true;
+    label: string;
+    dataType: DataType;
+    dependsOn: FieldPath[];
+    /** String name or `functions.<key>` registration object. */
+    computeFn: FuncRef;
+    deprecated?: boolean;
+};
+export type CompanyFieldDef = CompanyNormalFieldDef | CompanyDerivedFieldDef;
+export type CompanyTableDef = {
+    label: string;
+    rows: 'single' | 'multi';
+    description: string;
+    fields: Record<string, CompanyFieldDef>;
+};
+export type CompanySchema = Record<string, CompanyTableDef>;
+/** Usage-only overrides; structural keys are forbidden. */
+export type FieldOverride = {
+    label?: string;
+    description?: string;
+    extraction?: string;
+};
+/** Overlay on an inherited company table. Keys here override usage; other company fields stay as-is. */
+export type SequenceCompanyTableView = {
+    fields: Record<string, FieldOverride>;
+};
+/** Session is sequence-owned; always single-row; no derived / identifier. */
+export type SessionTableDef = {
+    label: string;
+    rows: 'single';
+    description: string;
+    fields: Record<string, NormalFieldCore>;
+};
+export type SequenceSlots = {
+    [table: string]: SequenceCompanyTableView | SessionTableDef;
+    session: SessionTableDef;
+};
+/** Effective field shape used for Slots codegen. */
+export type EffectiveFieldDef = {
+    dataType: DataType;
+    enum: Array<string | number> | null;
+    nullable: boolean;
+    ref: null | {
+        table: string;
+    };
+};
+export type EffectiveTableDef = {
+    rows: 'single' | 'multi';
+    fields: Record<string, EffectiveFieldDef>;
+};
+export type EffectiveSchema = Record<string, EffectiveTableDef>;
+//# sourceMappingURL=schema.d.ts.map