@superpanel-sdk/runtime 0.0.1-internal.1

package/dist/core/slot/schema.js

@@ -0,0 +1,17 @@
+/** Reserved row-identity field name. Authors should not invent another. */
+export const ROW_ID_FIELD = 'id';
+export const idFieldCore = {
+    derived: false,
+    label: 'Id',
+    dataType: 'string',
+    source: 'system',
+    extraction: 'Row identity',
+    enum: null,
+    nullable: false,
+};
+/** Unified row id. Write `id: idField` on every table. */
+export const idField = {
+    ...idFieldCore,
+    identifier: null,
+};
+//# sourceMappingURL=schema.js.map

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

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

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

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

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

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

package/dist/core/slot/snapshot.js

@@ -0,0 +1,138 @@
+import { compiledTableEntries, getCompiledTable, isSnapshotSingleRow } from './compile-schema.js';
+import { emptyFieldValue, makeFieldValue } from './field.js';
+import { parseFieldPath } from './path.js';
+import { emptySlotRow, getRowField, isReservedTableName, isRowIdField, slotFieldNames } from './row.js';
+import { validateBareValue } from './value.js';
+function seedToFieldValue(seed, now) {
+    if (seed && typeof seed === 'object' && !Array.isArray(seed) && 'state' in seed) {
+        const s = seed;
+        return makeFieldValue({
+            value: (s.value ?? null),
+            state: s.state,
+            reason: s.reason ?? null,
+            updatedBy: s.updatedBy ?? 'import',
+            updatedAt: s.updatedAt ?? now,
+            history: s.history ?? [],
+        });
+    }
+    if (seed === undefined) {
+        return emptyFieldValue(now);
+    }
+    return makeFieldValue({
+        value: seed,
+        state: 'filled',
+        reason: null,
+        updatedBy: 'import',
+        updatedAt: now,
+    });
+}
+/**
+ * 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 function snapshotFrom(schema, seed = {}, options = {}) {
+    const now = options.now ?? 0;
+    const snapshot = {};
+    for (const [tableName, table] of compiledTableEntries(schema)) {
+        if (isSnapshotSingleRow(table)) {
+            snapshot[tableName] = emptySlotRow(table.fields, { now });
+        }
+        else {
+            snapshot[tableName] = [];
+        }
+    }
+    for (const [key, value] of Object.entries(seed)) {
+        const parsed = parseFieldPath(key);
+        if (parsed) {
+            const table = getCompiledTable(schema, parsed.table);
+            if (!table) {
+                throw new Error(`Unknown table in seed: ${parsed.table}`);
+            }
+            if (!isSnapshotSingleRow(table)) {
+                throw new Error(`Field path seed ${key} is only for single-row tables; seed multi rows by table name`);
+            }
+            if (isRowIdField(parsed.field)) {
+                snapshot[parsed.table].id = value == null ? '' : String(value);
+                continue;
+            }
+            const field = table.fields[parsed.field];
+            if (!field) {
+                throw new Error(`Unknown field in seed: ${key}`);
+            }
+            const fv = seedToFieldValue(value, now);
+            if (fv.state === 'filled' || fv.state === 'asked_unknown') {
+                const issues = validateBareValue(field, fv.value, key, {
+                    allowNull: field.derived || (field.derived === false && field.nullable),
+                });
+                if (issues.length > 0) {
+                    throw new Error(issues.map((i) => i.message).join('; '));
+                }
+            }
+            snapshot[parsed.table][parsed.field] = fv;
+            continue;
+        }
+        const table = getCompiledTable(schema, key);
+        if (!table) {
+            throw new Error(`Unknown seed key: ${key}`);
+        }
+        if (isSnapshotSingleRow(table)) {
+            throw new Error(`Seed key ${key} is not a multi-row table`);
+        }
+        if (!Array.isArray(value)) {
+            throw new Error(`Multi-row seed ${key} must be an array`);
+        }
+        const rows = [];
+        let i = 0;
+        for (const rowSeed of value) {
+            if (!rowSeed || typeof rowSeed !== 'object') {
+                throw new Error(`Invalid row seed in ${key}`);
+            }
+            const rowObj = rowSeed;
+            const seededId = rowObj.id ?? rowObj.rowId;
+            const id = typeof seededId === 'string' && seededId.length > 0 ? seededId : `r${++i}`;
+            const row = { id };
+            for (const fieldName of slotFieldNames(table.fields)) {
+                if (fieldName in rowObj) {
+                    row[fieldName] = seedToFieldValue(rowObj[fieldName], now);
+                }
+                else {
+                    row[fieldName] = emptyFieldValue(now);
+                }
+            }
+            rows.push(row);
+        }
+        snapshot[key] = rows;
+    }
+    return snapshot;
+}
+/** Deep-clone a snapshot (structuredClone when available). */
+export function cloneSnapshot(snapshot) {
+    return typeof structuredClone === 'function'
+        ? structuredClone(snapshot)
+        : JSON.parse(JSON.stringify(snapshot));
+}
+export function getSnapshotTable(snapshot, tableName) {
+    if (isReservedTableName(tableName))
+        return undefined;
+    const value = snapshot[tableName];
+    if (value == null)
+        return undefined;
+    if (Array.isArray(value))
+        return value;
+    if (typeof value === 'object' && 'id' in value)
+        return value;
+    return undefined;
+}
+export function getSingleField(snapshot, path) {
+    const parsed = parseFieldPath(path);
+    if (!parsed)
+        return undefined;
+    const table = getSnapshotTable(snapshot, parsed.table);
+    if (!table || Array.isArray(table))
+        return undefined;
+    return getRowField(table, parsed.field);
+}
+//# sourceMappingURL=snapshot.js.map

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

@@ -0,0 +1,144 @@
+import type { DataType } from './schema.js';
+import type { FieldPath } from './path.js';
+import type { FieldState } from '../context/types.js';
+export type UpdatedBy = 'slot-filling' | 'derived' | 'function' | 'human' | 'import' | 'platform';
+/** Prior generation archived into FieldValue.history (no reason — 01-slot-db §4.1). */
+export type FieldHistoryEntry = {
+    value: string | number | boolean | null;
+    state: FieldState;
+    at: number;
+    by: UpdatedBy;
+};
+/** In-memory field envelope (01-slot-design §2 + 01-slot-db §4 history). */
+export type FieldValue = {
+    reason: string | null;
+    value: string | number | boolean | null;
+    state: FieldState;
+    updatedAt: number;
+    updatedBy: UpdatedBy;
+    /** Past generations ascending; excludes current. Appended only on C5 change. */
+    history: FieldHistoryEntry[];
+};
+/** One history append produced by a write batch (for platform write_log). */
+export type HistoryAppend = {
+    path: FieldPath;
+    entry: FieldHistoryEntry;
+};
+export type ExtractedField = {
+    reason: string;
+    value: string | number | boolean | null;
+    state: 'filled' | 'asked_unknown' | 'declined';
+};
+export type SingleRowProjection = Record<string, ExtractedField>;
+export type MultiRowProjection = Array<{
+    rowKey: string;
+    fields: Record<string, ExtractedField>;
+}>;
+export type SlotFillingOutput = Record<string, SingleRowProjection | MultiRowProjection>;
+export type RuntimeNormalFieldDef = {
+    derived: false;
+    label: string;
+    dataType: DataType;
+    source: 'conversation' | 'system';
+    extraction: string;
+    enum: Array<string | number> | null;
+    nullable: boolean;
+    identifier: null | {
+        kind: 'phone' | 'email';
+    };
+    ref: null | {
+        table: string;
+    };
+    deprecated?: boolean;
+};
+export type RuntimeDerivedFieldDef = {
+    derived: true;
+    label: string;
+    dataType: DataType;
+    dependsOn: FieldPath[];
+    computeFn: string;
+    deprecated?: boolean;
+};
+export type RuntimeFieldDef = RuntimeNormalFieldDef | RuntimeDerivedFieldDef;
+export type RuntimeTableDef = {
+    label: string;
+    rows: 'single' | 'multi';
+    description: string;
+    fields: Record<string, RuntimeFieldDef>;
+};
+/**
+ * Compiled schema: one key per table, plus derived graph.
+ * `derivedOrder` / `reverseDeps` are reserved and cannot be table names.
+ */
+export type CompiledSlotSchema = {
+    /** Derived fields in topological order (dependencies first). */
+    derivedOrder: FieldPath[];
+    /** `table.field` → derived fields that list it in dependsOn. */
+    reverseDeps: Record<FieldPath, FieldPath[]>;
+    [table: string]: RuntimeTableDef | FieldPath[] | Record<FieldPath, FieldPath[]>;
+};
+export type SlotCurrent = {
+    contactId: string;
+    caseContactId: string;
+    caseFileId: string;
+    sessionId: string | null;
+};
+export type SingleRowTableData = {
+    id: string;
+    [field: string]: FieldValue | string;
+};
+/** Multi-row table row: `id` plus field envelopes (codegen mirrors this). */
+export type MultiRowRecord = {
+    id: string;
+    [field: string]: FieldValue | string;
+};
+export type MultiRowTableData = MultiRowRecord[];
+export type TableData = SingleRowTableData | MultiRowTableData;
+/**
+ * Runtime snapshot: `current` plus one key per table.
+ * `current` is reserved and cannot be a table name.
+ */
+export type RuntimeSlotsSnapshot = {
+    current?: SlotCurrent;
+    [table: string]: TableData | SlotCurrent | undefined;
+};
+export type ValidationIssue = {
+    code: string;
+    message: string;
+    path?: string;
+};
+export type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+};
+export type WriteSource = Exclude<UpdatedBy, 'derived'>;
+export type ApplyWritesOptions = {
+    source: WriteSource;
+    now?: number;
+    /** When true (default for function/platform), only `source: system` normals. */
+    systemOnly?: boolean;
+};
+export type ApplyWritesResult = {
+    snapshot: RuntimeSlotsSnapshot;
+    changed: FieldPath[];
+    /** Previous generations archived into field envelopes this batch. */
+    history: HistoryAppend[];
+};
+export type RecomputeResult = {
+    snapshot: RuntimeSlotsSnapshot;
+    changed: FieldPath[];
+    history: HistoryAppend[];
+};
+export type SlotFillingValidateResult = {
+    ok: true;
+    accepted: SlotFillingOutput;
+    /** Fields that failed type/enum checks — caller may re-extract. */
+    rejected: FieldPath[];
+} | {
+    ok: false;
+    reason: 'stale-version' | 'invalid-shape';
+    issues: ValidationIssue[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/core/slot/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,9 @@
+import type { DataType } from './schema.js';
+import type { ExtractedField, RuntimeFieldDef, RuntimeNormalFieldDef, ValidationIssue } from './types.js';
+export declare function isValidDataTypeValue(dataType: DataType, value: unknown): boolean;
+export declare function validateExtractedField(field: RuntimeNormalFieldDef, extracted: ExtractedField, path: string): ValidationIssue[];
+/** Validate a bare write value for a normal or derived field. */
+export declare function validateBareValue(field: RuntimeFieldDef, value: unknown, path: string, options?: {
+    allowNull?: boolean;
+}): ValidationIssue[];
+//# sourceMappingURL=value.d.ts.map