@superpanel-sdk/runtime 0.0.1-internal.1

package/dist/core/slot/value.js

@@ -0,0 +1,97 @@
+const DATE_RE = /^\d{4}(-\d{2}(-\d{2})?)?$/;
+// ISO-8601 datetime with timezone offset or Z
+const DATETIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+export function isValidDataTypeValue(dataType, value) {
+    if (value === null)
+        return true;
+    switch (dataType) {
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'date':
+            return typeof value === 'string' && DATE_RE.test(value);
+        case 'datetime':
+            return typeof value === 'string' && DATETIME_RE.test(value);
+    }
+}
+export function validateExtractedField(field, extracted, path) {
+    const issues = [];
+    if (typeof extracted.reason !== 'string' || extracted.reason.length === 0) {
+        issues.push({
+            code: 'missing-reason',
+            message: 'Extracted field requires a non-empty reason',
+            path,
+        });
+    }
+    if (extracted.state !== 'filled' && extracted.state !== 'asked_unknown' && extracted.state !== 'declined') {
+        issues.push({
+            code: 'invalid-state',
+            message: `Invalid extracted state: ${String(extracted.state)}`,
+            path,
+        });
+        return issues;
+    }
+    if (extracted.state === 'declined' && extracted.value !== null) {
+        issues.push({
+            code: 'declined-non-null',
+            message: 'declined fields must have value null',
+            path,
+        });
+    }
+    if (extracted.state === 'filled' && extracted.value === null && !field.nullable) {
+        issues.push({
+            code: 'filled-null',
+            message: 'filled requires non-null value unless nullable: true',
+            path,
+        });
+    }
+    if (extracted.value !== null && !isValidDataTypeValue(field.dataType, extracted.value)) {
+        issues.push({
+            code: 'type-mismatch',
+            message: `value does not match dataType ${field.dataType}`,
+            path,
+        });
+    }
+    if (extracted.value !== null && field.enum && !field.enum.includes(extracted.value)) {
+        issues.push({
+            code: 'enum-mismatch',
+            message: `value ${String(extracted.value)} not in enum`,
+            path,
+        });
+    }
+    return issues;
+}
+/** Validate a bare write value for a normal or derived field. */
+export function validateBareValue(field, value, path, options = {}) {
+    const issues = [];
+    const allowNull = options.allowNull ?? true;
+    if (value === null || value === undefined) {
+        if (!allowNull && !(field.derived === false && field.nullable)) {
+            issues.push({
+                code: 'null-not-allowed',
+                message: 'null is not allowed for this field',
+                path,
+            });
+        }
+        return issues;
+    }
+    if (!isValidDataTypeValue(field.dataType, value)) {
+        issues.push({
+            code: 'type-mismatch',
+            message: `value does not match dataType ${field.dataType}`,
+            path,
+        });
+    }
+    if (!field.derived && field.enum && !field.enum.includes(value)) {
+        issues.push({
+            code: 'enum-mismatch',
+            message: `value ${String(value)} not in enum`,
+            path,
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=value.js.map

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

@@ -0,0 +1,41 @@
+import type { FieldState, Writes } from '../context/types.js';
+import type { FieldPath } from './path.js';
+import type { ApplyWritesOptions, ApplyWritesResult, CompiledSlotSchema, RuntimeSlotsSnapshot, SlotFillingOutput, UpdatedBy } from './types.js';
+/**
+ * Apply bare Writes (function / human / import / platform) onto a snapshot.
+ * Validates type/enum and write permissions. Detects C5 changes and appends history.
+ */
+export declare function applyWrites(schema: CompiledSlotSchema, snapshot: RuntimeSlotsSnapshot, writes: Writes | null | undefined, options: ApplyWritesOptions): ApplyWritesResult;
+export type FieldPatchInput = {
+    path: FieldPath;
+    rowId?: string;
+    value: string | number | boolean | null;
+    state: FieldState;
+    reason?: string | null;
+};
+/**
+ * Apply one human/admin field edit, including explicit slot state.
+ * Unlike bare writes, this supports a selected row in a multi-row entity table.
+ */
+export declare function applyFieldPatch(schema: CompiledSlotSchema, snapshot: RuntimeSlotsSnapshot, patch: FieldPatchInput, options: {
+    source: UpdatedBy;
+    now?: number;
+}): ApplyWritesResult;
+export type ApplySlotFillingOptions = {
+    now?: number;
+    /** Map SF placeholder row keys (`new-1`) → allocated row ids (mutated in place). */
+    rowKeyMap?: Map<string, string>;
+};
+/**
+ * C4: apply accepted Slot Filling projection (full replace for present fields/rows).
+ * Multi-row: projection is the full set of rows; omitted existing rows are deleted.
+ */
+export declare function applySlotFilling(schema: CompiledSlotSchema, snapshot: RuntimeSlotsSnapshot, output: SlotFillingOutput, options?: ApplySlotFillingOptions): ApplyWritesResult;
+/**
+ * Mark remaining conversation fields as asked_unknown (Topic move-on).
+ */
+export declare function markAskedUnknown(schema: CompiledSlotSchema, snapshot: RuntimeSlotsSnapshot, fields: Iterable<FieldPath>, options?: {
+    now?: number;
+    reason?: string;
+}): ApplyWritesResult;
+//# sourceMappingURL=write.d.ts.map

package/dist/core/slot/write.js

@@ -0,0 +1,319 @@
+import { getCompiledTable, isSnapshotSingleRow } from './compile-schema.js';
+import { commitFieldWrite, makeFieldValue } from './field.js';
+import { formatFieldPath, parseFieldPath, requireFieldPath } from './path.js';
+import { getRowField, isReservedTableName, isRowIdField, mintRowId, slotFieldNames } from './row.js';
+import { cloneSnapshot, getSnapshotTable } from './snapshot.js';
+import { validateBareValue, validateExtractedField } from './value.js';
+function extractedToFieldValue(extracted, updatedBy, now) {
+    return makeFieldValue({
+        reason: extracted.reason,
+        value: extracted.value,
+        state: extracted.state,
+        updatedBy,
+        updatedAt: now,
+    });
+}
+function assertWritableNormal(schema, path, options) {
+    const { table, field: fieldName } = requireFieldPath(path);
+    const tableDef = getCompiledTable(schema, table);
+    const field = tableDef?.fields[fieldName];
+    if (!tableDef || !field) {
+        return [{ code: 'unknown-field', message: `Unknown field: ${path}`, path }];
+    }
+    if (isRowIdField(fieldName)) {
+        return [
+            {
+                code: 'id-readonly',
+                message: `Cannot write row id: ${path}`,
+                path,
+            },
+        ];
+    }
+    if (field.derived) {
+        return [
+            {
+                code: 'derived-readonly',
+                message: `Cannot write derived field: ${path}`,
+                path,
+            },
+        ];
+    }
+    const systemOnly = options.systemOnly ??
+        (options.source === 'function' || options.source === 'platform' || options.source === 'import');
+    if (systemOnly && field.source !== 'system') {
+        return [
+            {
+                code: 'write-forbidden',
+                message: `Source ${options.source} cannot write conversation field ${path}`,
+                path,
+            },
+        ];
+    }
+    if (!isSnapshotSingleRow(tableDef)) {
+        return [
+            {
+                code: 'multi-path-write',
+                message: `Use Slot Filling / row APIs to write multi-row field ${path}`,
+                path,
+            },
+        ];
+    }
+    return [];
+}
+/**
+ * Apply bare Writes (function / human / import / platform) onto a snapshot.
+ * Validates type/enum and write permissions. Detects C5 changes and appends history.
+ */
+export function applyWrites(schema, snapshot, writes, options) {
+    if (!writes || Object.keys(writes).length === 0) {
+        return { snapshot, changed: [], history: [] };
+    }
+    const now = options.now ?? Date.now();
+    const next = cloneSnapshot(snapshot);
+    const changed = [];
+    const history = [];
+    const errors = [];
+    for (const [path, value] of Object.entries(writes)) {
+        const writeIssues = assertWritableNormal(schema, path, options);
+        if (writeIssues.length > 0) {
+            errors.push(...writeIssues);
+            continue;
+        }
+        const parsed = parseFieldPath(path);
+        const field = getCompiledTable(schema, parsed.table).fields[parsed.field];
+        const valueIssues = validateBareValue(field, value, path, {
+            allowNull: !field.derived && field.nullable,
+        });
+        if (valueIssues.length > 0) {
+            errors.push(...valueIssues);
+            continue;
+        }
+        const tableData = getSnapshotTable(next, parsed.table);
+        const prev = getRowField(tableData, parsed.field);
+        if (!prev)
+            continue;
+        const committed = commitFieldWrite(prev, makeFieldValue({
+            value: (value ?? null),
+            state: 'filled',
+            reason: null,
+            updatedBy: options.source,
+            updatedAt: now,
+        }));
+        tableData[parsed.field] = committed.field;
+        if (committed.changed) {
+            changed.push(parsed.path);
+            if (committed.historyEntry) {
+                history.push({ path: parsed.path, entry: committed.historyEntry });
+            }
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(`applyWrites failed:\n${errors.map((e) => `- ${e.path ?? ''}: ${e.message}`).join('\n')}`);
+    }
+    return { snapshot: next, changed, history };
+}
+/**
+ * Apply one human/admin field edit, including explicit slot state.
+ * Unlike bare writes, this supports a selected row in a multi-row entity table.
+ */
+export function applyFieldPatch(schema, snapshot, patch, options) {
+    const parsed = requireFieldPath(patch.path);
+    const table = getCompiledTable(schema, parsed.table);
+    const field = table?.fields[parsed.field];
+    if (!table || !field)
+        throw new Error(`Unknown field: ${patch.path}`);
+    if (isRowIdField(parsed.field))
+        throw new Error(`Cannot write row id: ${patch.path}`);
+    if (field.derived)
+        throw new Error(`Cannot write derived field: ${patch.path}`);
+    const value = patch.state === 'filled' ? patch.value : null;
+    if (patch.state !== 'empty') {
+        const issues = validateExtractedField(field, {
+            value,
+            state: patch.state,
+            reason: patch.reason ?? 'Human edit',
+        }, patch.path);
+        if (issues.length > 0) {
+            throw new Error(`applyFieldPatch failed:\n${issues.map((issue) => `- ${issue.path ?? ''}: ${issue.message}`).join('\n')}`);
+        }
+    }
+    const now = options.now ?? Date.now();
+    const next = cloneSnapshot(snapshot);
+    const data = getSnapshotTable(next, parsed.table);
+    const row = isSnapshotSingleRow(table)
+        ? data
+        : data?.find((candidate) => candidate.id === patch.rowId);
+    if (!row)
+        throw new Error(`Slot row not found: ${parsed.table}:${patch.rowId ?? 'single'}`);
+    const previous = getRowField(row, parsed.field);
+    if (!previous)
+        throw new Error(`Slot field not initialized: ${patch.path}`);
+    const committed = commitFieldWrite(previous, makeFieldValue({
+        value,
+        state: patch.state,
+        reason: patch.reason ?? 'Human edit',
+        updatedBy: options.source,
+        updatedAt: now,
+    }));
+    row[parsed.field] = committed.field;
+    if (!committed.changed)
+        return { snapshot: next, changed: [], history: [] };
+    return {
+        snapshot: next,
+        changed: [parsed.path],
+        history: committed.historyEntry ? [{ path: parsed.path, entry: committed.historyEntry }] : [],
+    };
+}
+/**
+ * C4: apply accepted Slot Filling projection (full replace for present fields/rows).
+ * Multi-row: projection is the full set of rows; omitted existing rows are deleted.
+ */
+export function applySlotFilling(schema, snapshot, output, options = {}) {
+    const now = options.now ?? Date.now();
+    const next = cloneSnapshot(snapshot);
+    const changed = new Set();
+    const history = [];
+    const rowKeyMap = options.rowKeyMap ?? new Map();
+    for (const [tableName, projection] of Object.entries(output)) {
+        if (isReservedTableName(tableName))
+            continue;
+        const table = getCompiledTable(schema, tableName);
+        if (!table)
+            continue;
+        if (isSnapshotSingleRow(table)) {
+            const tableData = getSnapshotTable(next, tableName);
+            for (const [fieldName, extracted] of Object.entries(projection)) {
+                const field = table.fields[fieldName];
+                if (!field || field.derived || field.source !== 'conversation')
+                    continue;
+                const path = formatFieldPath(tableName, fieldName);
+                const issues = validateExtractedField(field, extracted, path);
+                if (issues.length > 0) {
+                    throw new Error(issues.map((i) => i.message).join('; '));
+                }
+                if (isRowIdField(fieldName))
+                    continue;
+                const prev = getRowField(tableData, fieldName);
+                if (!prev)
+                    continue;
+                const committed = commitFieldWrite(prev, extractedToFieldValue(extracted, 'slot-filling', now));
+                tableData[fieldName] = committed.field;
+                if (committed.changed) {
+                    changed.add(path);
+                    if (committed.historyEntry) {
+                        history.push({ path, entry: committed.historyEntry });
+                    }
+                }
+            }
+        }
+        else {
+            const prevRows = getSnapshotTable(snapshot, tableName) ?? [];
+            const prevById = new Map(prevRows.map((r) => [r.id, r]));
+            const projectionRows = projection;
+            const nextRows = [];
+            let structuralChange = false;
+            for (const row of projectionRows) {
+                let id = row.rowKey;
+                if (row.rowKey.startsWith('new-')) {
+                    id = rowKeyMap.get(row.rowKey) ?? mintRowId();
+                    rowKeyMap.set(row.rowKey, id);
+                    structuralChange = true;
+                }
+                else if (!prevById.has(row.rowKey)) {
+                    structuralChange = true;
+                }
+                const prevRow = prevById.get(id);
+                const nextRow = { id };
+                for (const fieldName of slotFieldNames(table.fields)) {
+                    const field = table.fields[fieldName];
+                    if (field.derived)
+                        continue;
+                    const extracted = row.fields[fieldName];
+                    const prevFv = prevRow ? getRowField(prevRow, fieldName) : undefined;
+                    if (extracted) {
+                        const path = formatFieldPath(tableName, fieldName);
+                        const issues = validateExtractedField(field, extracted, path);
+                        if (issues.length > 0) {
+                            throw new Error(issues.map((i) => i.message).join('; '));
+                        }
+                        const committed = commitFieldWrite(prevFv, extractedToFieldValue(extracted, 'slot-filling', now));
+                        nextRow[fieldName] = committed.field;
+                        if (committed.changed) {
+                            changed.add(path);
+                            if (committed.historyEntry) {
+                                history.push({ path, entry: committed.historyEntry });
+                            }
+                        }
+                    }
+                    else if (prevFv) {
+                        nextRow[fieldName] = prevFv;
+                    }
+                    else {
+                        nextRow[fieldName] = makeFieldValue({
+                            value: null,
+                            state: 'empty',
+                            updatedBy: 'slot-filling',
+                            updatedAt: now,
+                        });
+                    }
+                }
+                nextRows.push(nextRow);
+            }
+            const prevIds = new Set(prevRows.map((r) => r.id));
+            const nextIds = new Set(nextRows.map((r) => r.id));
+            for (const id of prevIds) {
+                if (!nextIds.has(id))
+                    structuralChange = true;
+            }
+            if (prevRows.length !== nextRows.length)
+                structuralChange = true;
+            next[tableName] = nextRows;
+            if (structuralChange) {
+                for (const fieldName of slotFieldNames(table.fields)) {
+                    changed.add(formatFieldPath(tableName, fieldName));
+                }
+            }
+        }
+    }
+    return { snapshot: next, changed: [...changed], history };
+}
+/**
+ * Mark remaining conversation fields as asked_unknown (Topic move-on).
+ */
+export function markAskedUnknown(schema, snapshot, fields, options = {}) {
+    const now = options.now ?? Date.now();
+    const next = cloneSnapshot(snapshot);
+    const changed = [];
+    const history = [];
+    for (const path of fields) {
+        const parsed = requireFieldPath(path);
+        const table = getCompiledTable(schema, parsed.table);
+        const field = table?.fields[parsed.field];
+        if (!table || !field || field.derived)
+            continue;
+        if (field.source !== 'conversation')
+            continue;
+        if (!isSnapshotSingleRow(table))
+            continue;
+        const tableData = getSnapshotTable(next, parsed.table);
+        const prev = getRowField(tableData, parsed.field);
+        if (!prev || prev.state !== 'empty')
+            continue;
+        const committed = commitFieldWrite(prev, makeFieldValue({
+            value: null,
+            state: 'asked_unknown',
+            reason: options.reason ?? 'move-on',
+            updatedBy: 'platform',
+            updatedAt: now,
+        }));
+        tableData[parsed.field] = committed.field;
+        if (committed.changed) {
+            changed.push(parsed.path);
+            if (committed.historyEntry) {
+                history.push({ path: parsed.path, entry: committed.historyEntry });
+            }
+        }
+    }
+    return { snapshot: next, changed, history };
+}
+//# sourceMappingURL=write.js.map

package/dist/core/stage/builders.d.ts

@@ -0,0 +1,36 @@
+import type { FuncRef } from '../functions/func-ref.js';
+import type { FieldPath } from '../slot/path.js';
+import type { ActionNode, AgendaHeader, AgendaTree, AuthoringNode, AuthoringWhen, BranchNode, FinishWhen, OnNoProgress, SectionNode, SwitchOnNode, TopicNode, TransferNode } from './types.js';
+export declare function topic(id: string, config: {
+    label: string;
+    applyWhen: AuthoringWhen;
+    instructions: string;
+    fields: FieldPath[] | null;
+    finishWhen: FinishWhen;
+    onNoProgress: OnNoProgress | null;
+}): TopicNode;
+export declare function action(id: string, config: {
+    label: string;
+    applyWhen: AuthoringWhen;
+    finishWhen: FinishWhen;
+    run: FuncRef;
+    say: string | null;
+}): ActionNode;
+export declare function transfer(id: string, config: {
+    label: string;
+    applyWhen: AuthoringWhen;
+    numbers: string[];
+    mode: 'cold' | 'warm';
+    say: string;
+    unsuccessfulSay: string | null;
+}): TransferNode;
+export declare function section(id: string, config: {
+    label: string;
+    applyWhen: AuthoringWhen;
+}, children: AuthoringNode[]): SectionNode;
+export declare function branch(children: AuthoringNode[]): BranchNode;
+export declare function switchOn(field: FieldPath, cases: Record<string, AuthoringNode[]> & {
+    otherwise?: AuthoringNode[];
+}): SwitchOnNode;
+export declare function agenda(id: string, header: AgendaHeader | null, tree: AuthoringNode[]): AgendaTree;
+//# sourceMappingURL=builders.d.ts.map

package/dist/core/stage/builders.js

@@ -0,0 +1,28 @@
+export function topic(id, config) {
+    return { kind: 'topic', id, ...config };
+}
+export function action(id, config) {
+    return { kind: 'action', id, ...config };
+}
+export function transfer(id, config) {
+    return { kind: 'transfer', id, ...config };
+}
+export function section(id, config, children) {
+    return { kind: 'section', id, label: config.label, applyWhen: config.applyWhen, children };
+}
+export function branch(children) {
+    return { kind: 'branch', children };
+}
+export function switchOn(field, cases) {
+    const { otherwise: otherwiseChildren, ...rest } = cases;
+    return {
+        kind: 'switchOn',
+        field,
+        cases: rest,
+        ...(otherwiseChildren ? { otherwise: otherwiseChildren } : {}),
+    };
+}
+export function agenda(id, header, tree) {
+    return { kind: 'agenda', id, header, tree };
+}
+//# sourceMappingURL=builders.js.map

package/dist/core/stage/condition.d.ts

@@ -0,0 +1,17 @@
+import type { FieldPath } from '../slot/path.js';
+import type { Condition, JsonRulesCondition, OtherwiseSentinel } from './types.js';
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export declare function isOtherwise(value: unknown): value is OtherwiseSentinel;
+export declare function looksLikeJsonRules(value: string): boolean;
+export declare function jsonRules(rules: Condition | Condition[] | string): Condition;
+export declare function otherwise(): OtherwiseSentinel;
+export declare function parseJsonRules(input: string): JsonRulesCondition;
+export declare function normalizeJsonRules(raw: unknown): JsonRulesCondition;
+export declare function collectJsonRulesFacts(condition: JsonRulesCondition | null | undefined): FieldPath[];
+export type ConditionEval = {
+    pass: boolean;
+    failedFields: FieldPath[];
+};
+export declare function evaluateJsonRules(condition: JsonRulesCondition, caseContext: unknown): Promise<ConditionEval>;
+export declare function extractTemplateFields(text: string): FieldPath[];
+//# sourceMappingURL=condition.d.ts.map