@superpanel-sdk/runtime 0.2.2 → 0.5.0

package/dist/core/slot/write.js

@@ -1,319 +0,0 @@
-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

@@ -1,36 +0,0 @@
-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

@@ -1,28 +0,0 @@
-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

@@ -1,17 +0,0 @@
-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

package/dist/core/stage/condition.js

@@ -1,198 +0,0 @@
-import { Engine } from 'json-rules-engine';
-import { emptyFieldValue } from '../slot/field.js';
-import { parseFieldPath } from '../slot/path.js';
-import { getRowField } from '../slot/row.js';
-const OPERATORS = new Set([
-    'equal',
-    'notEqual',
-    'in',
-    'notIn',
-    'contains',
-    'doesNotContain',
-    'lessThan',
-    'lessThanInclusive',
-    'greaterThan',
-    'greaterThanInclusive',
-]);
-const PASS_EVENT = 'pass';
-export function isPlainObject(value) {
-    return value != null && typeof value === 'object' && !Array.isArray(value);
-}
-export function isOtherwise(value) {
-    return isPlainObject(value) && value.op === 'otherwise' && !('fact' in value) && !('operator' in value);
-}
-export function looksLikeJsonRules(value) {
-    const trimmed = value.trim();
-    return trimmed.startsWith('{') || trimmed.startsWith('[');
-}
-export function jsonRules(rules) {
-    if (typeof rules === 'string')
-        return parseJsonRules(rules);
-    if (Array.isArray(rules))
-        return { all: rules };
-    return rules;
-}
-export function otherwise() {
-    return { op: 'otherwise' };
-}
-export function parseJsonRules(input) {
-    let parsed;
-    try {
-        parsed = JSON.parse(input);
-    }
-    catch {
-        throw new Error('Invalid json-rules JSON');
-    }
-    return normalizeJsonRules(parsed);
-}
-export function normalizeJsonRules(raw) {
-    if (Array.isArray(raw)) {
-        if (raw.length === 0)
-            throw new Error('json-rules array must not be empty');
-        return { all: raw.map(normalizeJsonRules) };
-    }
-    if (!isPlainObject(raw)) {
-        throw new Error('Invalid json-rules condition');
-    }
-    if ('conditions' in raw) {
-        return normalizeJsonRules(raw.conditions);
-    }
-    if ('all' in raw) {
-        if (!Array.isArray(raw.all))
-            throw new Error('json-rules `all` must be an array');
-        return { all: raw.all.map(normalizeJsonRules) };
-    }
-    if ('any' in raw) {
-        if (!Array.isArray(raw.any))
-            throw new Error('json-rules `any` must be an array');
-        return { any: raw.any.map(normalizeJsonRules) };
-    }
-    if ('not' in raw) {
-        return { not: normalizeJsonRules(raw.not) };
-    }
-    if (typeof raw.fact !== 'string' || typeof raw.operator !== 'string') {
-        throw new Error('json-rules leaf requires `fact` and `operator`');
-    }
-    if (!OPERATORS.has(raw.operator)) {
-        throw new Error(`Unknown json-rules-engine operator: ${raw.operator}`);
-    }
-    const leaf = {
-        fact: raw.fact,
-        operator: raw.operator,
-        value: 'value' in raw ? raw.value : undefined,
-    };
-    if (typeof raw.path === 'string')
-        leaf.path = raw.path;
-    return leaf;
-}
-export function collectJsonRulesFacts(condition) {
-    if (!condition)
-        return [];
-    const out = [];
-    const seen = new Set();
-    visit(condition);
-    return out;
-    function visit(node) {
-        if ('all' in node) {
-            for (const child of node.all)
-                visit(child);
-            return;
-        }
-        if ('any' in node) {
-            for (const child of node.any)
-                visit(child);
-            return;
-        }
-        if ('not' in node) {
-            visit(node.not);
-            return;
-        }
-        if ('fact' in node && node.fact && !seen.has(node.fact)) {
-            seen.add(node.fact);
-            out.push(node.fact);
-        }
-    }
-}
-export async function evaluateJsonRules(condition, caseContext) {
-    const engine = new Engine([], { allowUndefinedFacts: true });
-    engine.addRule({
-        conditions: toEngineConditions(condition),
-        event: { type: PASS_EVENT },
-    });
-    const { events, failureResults } = await engine.run(factsFromCaseContext(condition, caseContext));
-    const pass = events.some((event) => event.type === PASS_EVENT);
-    return {
-        pass,
-        failedFields: pass ? [] : collectFailedFacts(failureResults[0]?.conditions),
-    };
-}
-function toEngineConditions(condition) {
-    const node = applyDefaultPath(condition);
-    if ('all' in node || 'any' in node || 'not' in node)
-        return node;
-    return { all: [node] };
-}
-function applyDefaultPath(condition) {
-    if ('all' in condition)
-        return { ...condition, all: condition.all.map(applyDefaultPath) };
-    if ('any' in condition)
-        return { ...condition, any: condition.any.map(applyDefaultPath) };
-    if ('not' in condition)
-        return { ...condition, not: applyDefaultPath(condition.not) };
-    if ('path' in condition && condition.path)
-        return condition;
-    return { ...condition, path: '$.value' };
-}
-function factsFromCaseContext(condition, caseContext) {
-    const facts = {};
-    for (const fact of collectJsonRulesFacts(condition)) {
-        facts[fact] = getContextField(caseContext, fact) ?? emptyFieldValue();
-    }
-    return facts;
-}
-function getContextField(caseContext, path) {
-    const parsed = parseFieldPath(path);
-    if (!parsed || !isPlainObject(caseContext))
-        return undefined;
-    const row = caseContext[parsed.table];
-    if (!row || typeof row !== 'object' || Array.isArray(row))
-        return undefined;
-    return getRowField(row, parsed.field);
-}
-function collectFailedFacts(node) {
-    const out = [];
-    const seen = new Set();
-    visit(node);
-    return out;
-    function visit(value) {
-        if (value == null || typeof value !== 'object')
-            return;
-        const rec = value;
-        if (typeof rec.fact === 'string' && rec.result === false && !seen.has(rec.fact)) {
-            seen.add(rec.fact);
-            out.push(rec.fact);
-        }
-        if (Array.isArray(rec.all))
-            for (const child of rec.all)
-                visit(child);
-        if (Array.isArray(rec.any))
-            for (const child of rec.any)
-                visit(child);
-        if (rec.not)
-            visit(rec.not);
-    }
-}
-const TEMPLATE_RE = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
-export function extractTemplateFields(text) {
-    const out = [];
-    const seen = new Set();
-    for (const match of text.matchAll(TEMPLATE_RE)) {
-        const path = match[1];
-        if (!seen.has(path)) {
-            seen.add(path);
-            out.push(path);
-        }
-    }
-    return out;
-}
-//# sourceMappingURL=condition.js.map

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

@@ -1,43 +0,0 @@
-import type { Writes } from '../context/types.js';
-import type { ComputeHost } from '../../compute-host/compute-host.js';
-import type { FieldPath } from '../slot/path.js';
-import type { RuntimeSlotsSnapshot } from '../slot/types.js';
-import { type WalkResult } from './walk.js';
-import type { FlatActionItem, FlatAgendaItem, FlatTransferItem } from './types.js';
-export declare const DEFAULT_MAX_ACTIONS_PER_TURN = 10;
-export type StageDriveHooks = {
-    runAction: (item: FlatActionItem, snapshot: RuntimeSlotsSnapshot) => Promise<Writes | null>;
-    applyWrites: (writes: Writes, snapshot: RuntimeSlotsSnapshot) => Promise<RuntimeSlotsSnapshot>;
-};
-export type StageDriveState = {
-    snapshot: RuntimeSlotsSnapshot;
-    currentPlacementId: string | null;
-};
-export type StageDriveResult = {
-    snapshot: RuntimeSlotsSnapshot;
-    currentPlacementId: string | null;
-    walk: WalkResult;
-    actionsRun: number;
-    fused: boolean;
-};
-/**
- * Walk until a topic/transfer/complete, executing actions inline.
- * Action returning null is skipped for this tick; writes trigger a full re-walk.
- */
-export declare function driveAgenda(items: FlatAgendaItem[], state: StageDriveState, compute: ComputeHost, hooks: StageDriveHooks, options?: {
-    maxActions?: number;
-}): Promise<StageDriveResult>;
-export type AdvanceResult = {
-    ok: true;
-    drive: StageDriveResult;
-} | {
-    ok: false;
-    missing: FieldPath[];
-    item: FlatAgendaItem;
-};
-export declare function advanceAgenda(items: FlatAgendaItem[], state: StageDriveState, compute: ComputeHost, hooks: StageDriveHooks, options?: {
-    maxActions?: number;
-}): Promise<AdvanceResult>;
-export declare function watchdogHint(item: FlatAgendaItem | null, snapshot: RuntimeSlotsSnapshot, compute?: ComputeHost): Promise<string | null>;
-export declare function transferWrites(item: FlatTransferItem, result: 'connected' | 'failed'): Writes;
-//# sourceMappingURL=drive.d.ts.map