@superpanel-sdk/runtime 0.2.3 → 0.5.0

package/dist/core/slot/deps.js

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

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

@@ -1,115 +0,0 @@
-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/platform-session-fields.d.ts

@@ -1,38 +0,0 @@
-import type { RuntimeTableDef } from './types.js';
-export declare const PLATFORM_SESSION_FIELDS: {
-    readonly is_inbound_call: {
-        readonly derived: false;
-        readonly label: 'Inbound call';
-        readonly dataType: 'boolean';
-        readonly source: 'system';
-        readonly extraction: 'Set by the conversation entry pipeline';
-        readonly enum: null;
-        readonly nullable: false;
-        readonly identifier: null;
-        readonly ref: null;
-    };
-    readonly is_first_call: {
-        readonly derived: false;
-        readonly label: 'First call';
-        readonly dataType: 'boolean';
-        readonly source: 'system';
-        readonly extraction: 'No prior session for this case contact';
-        readonly enum: null;
-        readonly nullable: false;
-        readonly identifier: null;
-        readonly ref: null;
-    };
-    readonly is_new_user: {
-        readonly derived: false;
-        readonly label: 'New user';
-        readonly dataType: 'boolean';
-        readonly source: 'system';
-        readonly extraction: 'No existing contact for this party';
-        readonly enum: null;
-        readonly nullable: false;
-        readonly identifier: null;
-        readonly ref: null;
-    };
-};
-export declare function createPlatformSessionTable(): RuntimeTableDef;
-//# sourceMappingURL=platform-session-fields.d.ts.map

package/dist/core/slot/platform-session-fields.js

@@ -1,48 +0,0 @@
-import { idField } from './schema.js';
-export const PLATFORM_SESSION_FIELDS = {
-    is_inbound_call: {
-        derived: false,
-        label: 'Inbound call',
-        dataType: 'boolean',
-        source: 'system',
-        extraction: 'Set by the conversation entry pipeline',
-        enum: null,
-        nullable: false,
-        identifier: null,
-        ref: null,
-    },
-    is_first_call: {
-        derived: false,
-        label: 'First call',
-        dataType: 'boolean',
-        source: 'system',
-        extraction: 'No prior session for this case contact',
-        enum: null,
-        nullable: false,
-        identifier: null,
-        ref: null,
-    },
-    is_new_user: {
-        derived: false,
-        label: 'New user',
-        dataType: 'boolean',
-        source: 'system',
-        extraction: 'No existing contact for this party',
-        enum: null,
-        nullable: false,
-        identifier: null,
-        ref: null,
-    },
-};
-export function createPlatformSessionTable() {
-    return {
-        label: 'Session',
-        rows: 'single',
-        description: 'Per-conversation session fields',
-        fields: {
-            id: { ...idField, ref: null },
-            ...PLATFORM_SESSION_FIELDS,
-        },
-    };
-}
-//# sourceMappingURL=platform-session-fields.js.map

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

@@ -1,23 +0,0 @@
-import type { FieldPath } from './path.js';
-import type { CompiledSlotSchema } from './types.js';
-type JsonSchema = Record<string, unknown>;
-export type SfSchemaOptions = {
-    /**
-     * Field paths included with full definitions.
-     * When omitted, all conversation fields are included (full-schema / hangup pass).
-     */
-    focusFields?: Iterable<FieldPath>;
-};
-/**
- * Build JSON Schema for Slot Filling structured output.
- * Derived and `source: system` fields are never included.
- */
-export declare function buildSlotFillingJsonSchema(schema: CompiledSlotSchema, options?: SfSchemaOptions): JsonSchema;
-/** Compact catalog for out-of-focus conversation fields (C1). */
-export declare function buildFieldCatalog(schema: CompiledSlotSchema, exclude?: Iterable<FieldPath>): Array<{
-    path: FieldPath;
-    label: string;
-    extraction: string;
-}>;
-export {};
-//# sourceMappingURL=sf-schema.d.ts.map

package/dist/core/slot/sf-schema.js

@@ -1,125 +0,0 @@
-import { compiledTableEntries, isSnapshotSingleRow } from './compile-schema.js';
-import { formatFieldPath, parseFieldPath } from './path.js';
-function dataTypeToJsonSchema(dataType, enumValues, nullable) {
-    let base;
-    if (enumValues && enumValues.length > 0) {
-        base = { enum: [...enumValues] };
-    }
-    else {
-        switch (dataType) {
-            case 'string':
-            case 'date':
-            case 'datetime':
-                base = { type: 'string' };
-                break;
-            case 'number':
-                base = { type: 'number' };
-                break;
-            case 'boolean':
-                base = { type: 'boolean' };
-                break;
-        }
-    }
-    if (nullable) {
-        if (base.enum) {
-            return { enum: [...base.enum, null] };
-        }
-        return { type: [base.type, 'null'] };
-    }
-    return base;
-}
-function extractedFieldSchema(field) {
-    return {
-        type: 'object',
-        additionalProperties: false,
-        required: ['reason', 'value', 'state'],
-        properties: {
-            reason: { type: 'string', minLength: 1 },
-            value: dataTypeToJsonSchema(field.dataType, field.enum, true),
-            state: { type: 'string', enum: ['filled', 'asked_unknown', 'declined'] },
-        },
-    };
-}
-/**
- * Build JSON Schema for Slot Filling structured output.
- * Derived and `source: system` fields are never included.
- */
-export function buildSlotFillingJsonSchema(schema, options = {}) {
-    const focus = options.focusFields
-        ? new Set([...options.focusFields].map((p) => {
-            const parsed = parseFieldPath(p);
-            if (!parsed)
-                throw new Error(`Invalid focus field: ${p}`);
-            return parsed.path;
-        }))
-        : null;
-    const tableSchemas = {};
-    for (const [tableName, table] of compiledTableEntries(schema)) {
-        const fieldProps = {};
-        for (const [fieldName, field] of Object.entries(table.fields)) {
-            if (field.derived)
-                continue;
-            if (field.source !== 'conversation')
-                continue;
-            const path = formatFieldPath(tableName, fieldName);
-            if (focus && !focus.has(path))
-                continue;
-            fieldProps[fieldName] = extractedFieldSchema(field);
-        }
-        if (Object.keys(fieldProps).length === 0)
-            continue;
-        if (isSnapshotSingleRow(table)) {
-            tableSchemas[tableName] = {
-                type: 'object',
-                additionalProperties: false,
-                properties: fieldProps,
-            };
-        }
-        else {
-            tableSchemas[tableName] = {
-                type: 'array',
-                items: {
-                    type: 'object',
-                    additionalProperties: false,
-                    required: ['rowKey', 'fields'],
-                    properties: {
-                        rowKey: { type: 'string', minLength: 1 },
-                        fields: {
-                            type: 'object',
-                            additionalProperties: false,
-                            properties: fieldProps,
-                        },
-                    },
-                },
-            };
-        }
-    }
-    return {
-        type: 'object',
-        additionalProperties: false,
-        properties: tableSchemas,
-    };
-}
-/** Compact catalog for out-of-focus conversation fields (C1). */
-export function buildFieldCatalog(schema, exclude = []) {
-    const excluded = new Set([...exclude].map((p) => parseFieldPath(p)?.path).filter(Boolean));
-    const catalog = [];
-    for (const [tableName, table] of compiledTableEntries(schema)) {
-        for (const [fieldName, field] of Object.entries(table.fields)) {
-            if (field.derived)
-                continue;
-            if (field.source !== 'conversation')
-                continue;
-            const path = formatFieldPath(tableName, fieldName);
-            if (excluded.has(path))
-                continue;
-            catalog.push({
-                path,
-                label: field.label,
-                extraction: field.extraction,
-            });
-        }
-    }
-    return catalog;
-}
-//# sourceMappingURL=sf-schema.js.map

package/dist/core/slot/sf-validate.d.ts

@@ -1,14 +0,0 @@
-import type { CompiledSlotSchema, SlotFillingValidateResult } from './types.js';
-export type ValidateSlotFillingOptions = {
-    /** Conversation version carried by the SF task. */
-    taskVersion: number;
-    /** Current conversation version; mismatch → whole pack discarded. */
-    currentVersion: number;
-};
-/**
- * C3 gates for Slot Filling output: version gate, type/enum, write protection.
- * Derived / system fields in the payload are dropped (write protection).
- * Type/enum failures are rejected per-field; valid fields stay accepted.
- */
-export declare function validateSlotFillingOutput(schema: CompiledSlotSchema, raw: unknown, options: ValidateSlotFillingOptions): SlotFillingValidateResult;
-//# sourceMappingURL=sf-validate.d.ts.map

package/dist/core/slot/sf-validate.js

@@ -1,132 +0,0 @@
-import { getCompiledTable, isSnapshotSingleRow } from './compile-schema.js';
-import { formatFieldPath } from './path.js';
-import { isReservedTableName } from './row.js';
-import { validateExtractedField } from './value.js';
-function isExtractedField(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const v = value;
-    return (typeof v.reason === 'string' &&
-        'value' in v &&
-        (v.state === 'filled' || v.state === 'asked_unknown' || v.state === 'declined'));
-}
-/**
- * C3 gates for Slot Filling output: version gate, type/enum, write protection.
- * Derived / system fields in the payload are dropped (write protection).
- * Type/enum failures are rejected per-field; valid fields stay accepted.
- */
-export function validateSlotFillingOutput(schema, raw, options) {
-    if (options.taskVersion !== options.currentVersion) {
-        return {
-            ok: false,
-            reason: 'stale-version',
-            issues: [
-                {
-                    code: 'stale-version',
-                    message: `SF version ${options.taskVersion} != current ${options.currentVersion}`,
-                },
-            ],
-        };
-    }
-    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
-        return {
-            ok: false,
-            reason: 'invalid-shape',
-            issues: [
-                {
-                    code: 'invalid-shape',
-                    message: 'SlotFillingOutput must be an object of table projections',
-                },
-            ],
-        };
-    }
-    const accepted = {};
-    const rejected = [];
-    const shapeIssues = [];
-    for (const [tableName, projection] of Object.entries(raw)) {
-        if (isReservedTableName(tableName))
-            continue;
-        const table = getCompiledTable(schema, tableName);
-        if (!table) {
-            continue;
-        }
-        if (isSnapshotSingleRow(table)) {
-            if (!projection || typeof projection !== 'object' || Array.isArray(projection)) {
-                shapeIssues.push({
-                    code: 'invalid-projection',
-                    message: `single-row table ${tableName} expects an object projection`,
-                    path: tableName,
-                });
-                continue;
-            }
-            const outFields = {};
-            for (const [fieldName, extracted] of Object.entries(projection)) {
-                const path = formatFieldPath(tableName, fieldName);
-                const field = table.fields[fieldName];
-                if (!field || field.derived || field.source !== 'conversation') {
-                    continue; // write protection: drop
-                }
-                if (!isExtractedField(extracted)) {
-                    rejected.push(path);
-                    continue;
-                }
-                const issues = validateExtractedField(field, extracted, path);
-                if (issues.length > 0) {
-                    rejected.push(path);
-                    continue;
-                }
-                outFields[fieldName] = extracted;
-            }
-            if (Object.keys(outFields).length > 0) {
-                accepted[tableName] = outFields;
-            }
-        }
-        else {
-            if (!Array.isArray(projection)) {
-                shapeIssues.push({
-                    code: 'invalid-projection',
-                    message: `multi-row table ${tableName} expects an array projection`,
-                    path: tableName,
-                });
-                continue;
-            }
-            const outRows = [];
-            for (const row of projection) {
-                if (!row || typeof row !== 'object' || typeof row.rowKey !== 'string') {
-                    shapeIssues.push({
-                        code: 'invalid-row',
-                        message: `multi-row table ${tableName} row missing rowKey`,
-                        path: tableName,
-                    });
-                    continue;
-                }
-                const fieldsIn = row.fields ?? {};
-                const outFields = {};
-                for (const [fieldName, extracted] of Object.entries(fieldsIn)) {
-                    const path = formatFieldPath(tableName, fieldName);
-                    const field = table.fields[fieldName];
-                    if (!field || field.derived || field.source !== 'conversation') {
-                        continue;
-                    }
-                    if (!isExtractedField(extracted)) {
-                        rejected.push(path);
-                        continue;
-                    }
-                    const issues = validateExtractedField(field, extracted, path);
-                    if (issues.length > 0) {
-                        rejected.push(path);
-                        continue;
-                    }
-                    outFields[fieldName] = extracted;
-                }
-                outRows.push({ rowKey: row.rowKey, fields: outFields });
-            }
-            accepted[tableName] = outRows;
-        }
-    }
-    if (shapeIssues.length > 0) {
-        return { ok: false, reason: 'invalid-shape', issues: shapeIssues };
-    }
-    return { ok: true, accepted, rejected };
-}
-//# sourceMappingURL=sf-validate.js.map

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

@@ -1,18 +0,0 @@
-import type { FieldPath } from './path.js';
-import type { CompiledSlotSchema, FieldValue, RuntimeSlotsSnapshot, TableData } from './types.js';
-export type SnapshotSeed = Record<string, unknown>;
-/**
- * Build a runtime snapshot for local tests.
- *
- * - `table.field` keys seed single-row (or current-party) fields
- * - bare multi-table name keys seed row arrays:
- *   `children: [{ id?: string, name: 'Lily', age: 8 }]`
- */
-export declare function snapshotFrom(schema: CompiledSlotSchema, seed?: SnapshotSeed, options?: {
-    now?: number;
-}): RuntimeSlotsSnapshot;
-/** Deep-clone a snapshot (structuredClone when available). */
-export declare function cloneSnapshot(snapshot: RuntimeSlotsSnapshot): RuntimeSlotsSnapshot;
-export declare function getSnapshotTable(snapshot: RuntimeSlotsSnapshot, tableName: string): TableData | undefined;
-export declare function getSingleField(snapshot: RuntimeSlotsSnapshot, path: FieldPath): FieldValue | undefined;
-//# sourceMappingURL=snapshot.d.ts.map