@superpanel-sdk/runtime 0.2.2 → 0.5.0

package/dist/core/sequence/index.js

@@ -0,0 +1,231 @@
+/**
+ * Sequence-level declarations (14-sequence-instance §4.4–§4.5): the business root a sequence runs
+ * about (`index.ts`: `defineSequence({ subject })`) and its run variables and experiments
+ * (`variables.ts`). Compiled into `SequenceBuild.subject` / `.variables` / `.experiments`; the
+ * platform validates writes and assigns experiments with the helpers here.
+ */
+import { POLICY_IDS } from '../slot/company-metadata.js';
+export { defineSequence, defineVariables, json, } from './define.js';
+/**
+ * Run variable names the platform reserves (14 §4.4). It reads `voice` when it opens a session;
+ * `responsePolicy` and `slotFillingPolicy` are reserved and not read yet. A sequence may leave them
+ * out (the platform default) or declare them as enums whose values the platform knows.
+ */
+export const SYSTEM_VARIABLES = ['responsePolicy', 'slotFillingPolicy', 'voice'];
+export function isSystemVariable(name) {
+    return SYSTEM_VARIABLES.includes(name);
+}
+const VARIABLE_NAME = /^[a-zA-Z][a-zA-Z0-9_]{0,63}$/;
+/** The values a system variable may take: the policy catalog. */
+function systemVariableValues(name) {
+    switch (name) {
+        case 'responsePolicy':
+            return POLICY_IDS.response;
+        case 'slotFillingPolicy':
+            return POLICY_IDS.slotFilling;
+        case 'voice':
+            return POLICY_IDS.voice;
+    }
+}
+/** Normalize and check a sequence's `variables.ts` (14 §4.4). */
+export function compileVariables(declared, experiments) {
+    const issues = [];
+    const variables = {};
+    const decls = declared && typeof declared === 'object' && !Array.isArray(declared) ? declared : {};
+    if (declared !== undefined && decls !== declared)
+        issues.push('variables must be an object of declarations');
+    for (const [name, raw] of Object.entries(decls)) {
+        if (!VARIABLE_NAME.test(name)) {
+            issues.push(`variable '${name}': a name is a letter then letters, digits or _ (at most 64)`);
+            continue;
+        }
+        const compiled = compileVariable(name, raw, issues);
+        if (!compiled)
+            continue;
+        if (isSystemVariable(name)) {
+            const allowed = systemVariableValues(name);
+            if (compiled.type !== 'enum') {
+                issues.push(`variable '${name}' is the platform's: declare it with options (one of ${allowed.join(', ') || 'none'})`);
+                continue;
+            }
+            const unknown = compiled.options.filter((value) => typeof value !== 'string' || !allowed.includes(value));
+            if (unknown.length > 0) {
+                issues.push(`variable '${name}': ${unknown.join(', ')} not one of ${allowed.join(', ') || '(none)'}`);
+                continue;
+            }
+        }
+        variables[name] = compiled;
+    }
+    const compiledExperiments = {};
+    const exps = experiments && typeof experiments === 'object' && !Array.isArray(experiments)
+        ? experiments
+        : {};
+    for (const [name, raw] of Object.entries(exps)) {
+        const exp = raw;
+        const variable = exp && typeof exp.variable === 'string' ? variables[exp.variable] : undefined;
+        if (!exp || typeof exp.variable !== 'string' || !variable) {
+            issues.push(`experiment '${name}': variable must name a declared variable`);
+            continue;
+        }
+        if (variable.type !== 'enum') {
+            issues.push(`experiment '${name}': only an enum variable (one declared with options) can be split`);
+            continue;
+        }
+        const split = exp.split && typeof exp.split === 'object' ? exp.split : {};
+        const entries = Object.entries(split);
+        const options = variable.options.map(String);
+        const bad = entries.filter(([value, share]) => !options.includes(value) || typeof share !== 'number' || share < 0);
+        if (entries.length === 0 || bad.length > 0 || entries.every(([, share]) => share === 0)) {
+            issues.push(`experiment '${name}': split gives non-negative shares to values of '${exp.variable}' (${options.join(', ')})`);
+            continue;
+        }
+        if (Object.values(compiledExperiments).some((other) => other.variable === exp.variable)) {
+            issues.push(`experiment '${name}': '${exp.variable}' is already split by another experiment`);
+            continue;
+        }
+        compiledExperiments[name] = { variable: exp.variable, split: Object.fromEntries(entries) };
+    }
+    return { variables, experiments: compiledExperiments, issues };
+}
+function compileVariable(name, raw, issues) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        issues.push(`variable '${name}': a declaration is an object ({ options } or { type })`);
+        return null;
+    }
+    const decl = raw;
+    const hasDefault = Object.hasOwn(decl, 'default') && decl.default !== undefined;
+    if (Array.isArray(decl.options)) {
+        const options = decl.options;
+        if (options.length === 0 || options.some((value) => !['string', 'number', 'boolean'].includes(typeof value))) {
+            issues.push(`variable '${name}': options are a non-empty list of strings, numbers or booleans`);
+            return null;
+        }
+        if (hasDefault && decl.default !== null && !options.includes(decl.default)) {
+            issues.push(`variable '${name}': default ${String(decl.default)} is not one of its options`);
+            return null;
+        }
+        return {
+            type: 'enum',
+            options: options,
+            default: hasDefault ? decl.default : null,
+        };
+    }
+    const type = decl.type;
+    if (type === 'string' || type === 'number' || type === 'boolean') {
+        if (hasDefault && decl.default !== null && typeof decl.default !== type) {
+            issues.push(`variable '${name}': default must be a ${type}`);
+            return null;
+        }
+        return { type, default: hasDefault ? decl.default : null };
+    }
+    if (type && typeof type === 'object' && type.kind === 'json') {
+        if (hasDefault && !serializes(decl.default)) {
+            issues.push(`variable '${name}': default must serialize as JSON`);
+            return null;
+        }
+        return { type: 'json', default: hasDefault ? decl.default : null };
+    }
+    issues.push(`variable '${name}': declare options, or type 'string' | 'number' | 'boolean' | json()`);
+    return null;
+}
+function serializes(value) {
+    try {
+        return JSON.stringify(value) !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/** Why `value` cannot be stored in the variable; null when it can. `null` always can (unset). */
+export function variableValueIssue(name, variable, value) {
+    if (!variable)
+        return `unknown variable '${name}' (declare it in variables.ts)`;
+    if (value === null)
+        return null;
+    switch (variable.type) {
+        case 'enum':
+            return variable.options.includes(value) ? null : `'${name}' must be one of ${variable.options.join(', ')}`;
+        case 'string':
+        case 'number':
+        case 'boolean':
+            return typeof value === variable.type ? null : `'${name}' must be a ${variable.type}`;
+        case 'json':
+            return value !== undefined && serializes(value) ? null : `'${name}' must serialize as JSON`;
+    }
+}
+/** Issues of a whole write of variables (unknown names, wrong types); empty when it may be stored. */
+export function variablesWriteIssues(variables, values) {
+    return Object.entries(values)
+        .map(([name, value]) => variableValueIssue(name, variables[name], value))
+        .filter((issue) => issue !== null);
+}
+/**
+ * The variables a new run starts with: every declared default, then the values given, then each
+ * experiment whose variable was not given assigns a value by `hash(instanceId + experiment)`, so the
+ * same instance always lands in the same group (14 §4.4). Returns the assigned groups too.
+ */
+export function startVariables(instanceId, declared, experiments, given) {
+    const variables = {};
+    for (const [name, variable] of Object.entries(declared)) {
+        if (variable.default !== null && variable.default !== undefined)
+            variables[name] = variable.default;
+    }
+    Object.assign(variables, given);
+    const assigned = {};
+    for (const [name, experiment] of Object.entries(experiments)) {
+        if (Object.hasOwn(given, experiment.variable))
+            continue;
+        const value = pickByShare(`${instanceId}:${name}`, experiment.split);
+        const variable = declared[experiment.variable];
+        // A split value is a string key; the variable's option may be a number or boolean.
+        const option = variable?.type === 'enum' ? (variable.options.find((candidate) => String(candidate) === value) ?? value) : value;
+        variables[experiment.variable] = option;
+        assigned[name] = value;
+    }
+    return { variables, experiments: assigned };
+}
+/**
+ * The current value of each variable as a run reads it (14 §4.4 "sequence 版本变化"): a stored value
+ * the declaration no longer allows (a removed variable or option) falls back to the default.
+ * `onStale` hears each fallback. Stored values are not changed.
+ */
+export function readVariables(declared, stored, onStale) {
+    const out = {};
+    for (const [name, variable] of Object.entries(declared)) {
+        const has = Object.hasOwn(stored, name);
+        const value = has ? stored[name] : variable.default;
+        if (has && variableValueIssue(name, variable, value) !== null) {
+            onStale?.(name, value);
+            out[name] = variable.default ?? null;
+            continue;
+        }
+        out[name] = value ?? null;
+    }
+    for (const [name, value] of Object.entries(stored)) {
+        if (!Object.hasOwn(declared, name))
+            onStale?.(name, value);
+    }
+    return out;
+}
+/** Deterministic weighted pick: FNV-1a of `key` into the cumulative shares. */
+function pickByShare(key, split) {
+    const entries = Object.entries(split).filter(([, share]) => share > 0);
+    const total = entries.reduce((sum, [, share]) => sum + share, 0);
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < key.length; i += 1) {
+        hash ^= key.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    let point = (hash / 0x100000000) * total;
+    for (const [value, share] of entries) {
+        if (point < share)
+            return value;
+        point -= share;
+    }
+    return entries[entries.length - 1][0];
+}
+/** Bytes of `variables` serialized: what {@link LIMITS.variablesBytes} bounds. */
+export function variablesSize(variables) {
+    return new TextEncoder().encode(JSON.stringify(variables)).length;
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,40 @@
+import type { FieldState } from '../context/types.js';
+/**
+ * Where a slot cell is stored, as the generated `Rows` type marks it: a cell's
+ * `(table, row id, field)` and a row's `(table, id)`.
+ */
+/** Where a cell is stored: `(table, row id, field)`. */
+export type CellRef<T extends string = string, F extends string = string> = {
+    table: T;
+    rowId: string;
+    field: F;
+};
+/** A row's binding: `(table, row id)`. */
+export type RowRef<T extends string = string> = {
+    table: T;
+    id: string;
+};
+declare const cellMode: unique symbol;
+declare const cellKind: unique symbol;
+/**
+ * The binding part of a cell type: `ref`, and phantom marks codegen adds to every field of
+ * `Rows`. Mode `'rw'`: a page may open it with `field(...)`; `'ro'`: the row id
+ * or the parent, which no page opens (19-page-writable-cells). Kind `'ref'`: a ref field (another row's id), which a region never lists.
+ */
+export type CellBinding<T extends string = string, F extends string = string, M extends 'rw' | 'ro' = 'rw' | 'ro', K extends 'value' | 'ref' = 'value' | 'ref'> = {
+    ref: CellRef<T, F>;
+    readonly [cellMode]?: M;
+    readonly [cellKind]?: K;
+};
+/** A slot cell as a view receives it: the value and state, and where it is stored. */
+export type Cell<T extends string = string, F extends string = string, V = unknown, M extends 'rw' | 'ro' = 'rw' | 'ro'> = {
+    value: V;
+    state: FieldState;
+} & CellBinding<T, F, M>;
+/** A bound row as a view receives it. */
+export type BoundRow = {
+    id: string;
+    $ref: RowRef<string>;
+};
+export {};
+//# sourceMappingURL=binding.d.ts.map

package/dist/core/slot/binding.js

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

package/dist/core/slot/company-metadata.d.ts

@@ -0,0 +1,113 @@
+import type { CompanyFieldDef, CompanySchema, CompiledCompanyMetadata, SessionSchema, TableRef } from './schema.js';
+import type { ValidationIssue, ValidationResult } from './types.js';
+export { PLATFORM_CONTACT_FIELDS, PLATFORM_SESSION_FIELDS } from './platform-fields.js';
+/** The one table every company has: the only thing the platform contacts (14-sequence-instance §5). */
+export declare const CONTACT_TABLE = "contact";
+/** The conversation's table: its fields are the company's `schema/session.ts`; no company table has this name. */
+export declare const SESSION_TABLE = "session";
+export declare const CONTACT_OPT_OUT_FIELDS: readonly ['opted_out', 'call_opted_out', 'sms_opted_out', 'email_opted_out'];
+/** Platform limits (14-sequence-instance §16.1). */
+export declare const LIMITS: {
+    /** Longest parent chain: a table's parent's parent … at most this many hops to a table without one. */
+    readonly parentDepth: 5;
+    /** Rows one load step (one table) may read. */
+    readonly loadRowsPerStep: 500;
+    /** `follow` hops chained in one load expression. */
+    readonly followDepth: 3;
+    /** A load's time budget, ms. */
+    readonly loadTimeoutMs: 2000;
+    /** An instance's `variables`, serialized, bytes. */
+    readonly variablesBytes: number;
+    /** Company tables per company and environment (18-record-search-index §4.7). */
+    readonly tables: 100;
+    /** Fields per table, platform fields included. */
+    readonly fieldsPerTable: 300;
+    /** `options` of one `select` / `multi_select` field (a longer list is a table and a lookupRef). */
+    readonly options: 200;
+    /** Characters of one option: a short code, not a sentence (its meaning goes in `extraction`). */
+    readonly optionChars: 60;
+    /** A `string` value, characters. */
+    readonly stringChars: 255;
+    /** A `text` value, UTF-8 bytes. */
+    readonly textBytes: number;
+    /** One row's stored data, serialized, UTF-8 bytes. */
+    readonly rowDataBytes: number;
+};
+/**
+ * The policy ids a run can name, per layer: the values of the platform's run variables
+ * `responsePolicy`, `slotFillingPolicy` and `voice` (14 §4.4). Customers write them, so an id is only
+ * ever added; removing or renaming one breaks the companies that use it.
+ */
+export declare const POLICY_IDS: {
+    readonly response: readonly ['default'];
+    readonly slotFilling: readonly ['default'];
+    readonly voice: readonly ['default'];
+};
+export type ResponsePolicyId = (typeof POLICY_IDS.response)[number];
+export type SlotFillingPolicyId = (typeof POLICY_IDS.slotFilling)[number];
+export type VoiceProfileId = (typeof POLICY_IDS.voice)[number];
+/** Session fields with the platform's only: what a company without fields of its own declares. */
+export declare const PLATFORM_SESSION_SCHEMA: SessionSchema;
+/** Each table's platform fields, with the name its issue codes use (`missing-platform-<name>-field`). */
+export declare const PLATFORM_TABLE_FIELDS: Readonly<Record<string, {
+    name: string;
+    fields: Record<string, CompanyFieldDef>;
+}>>;
+/**
+ * A company table other than `contact`: one the company defines whole. Every company table (contact
+ * included) is stored as `Record` rows; `session` is the sequence's, stored on the session.
+ */
+export declare function isCustomTable(tableName: string): boolean;
+/** A table whose rows are `Record` rows: every company table, contact included. */
+export declare function isRecordTable(tableName: string): boolean;
+type FieldsOf = {
+    fields: Record<string, {
+        ref?: TableRef | null;
+    } | CompanyFieldDef>;
+};
+/** A table's parent: the field name and the table it points at; null when it has none. */
+export declare function parentOf(table: FieldsOf | undefined): {
+    field: string;
+    table: string;
+} | null;
+/**
+ * Whether `fieldName` is the table's parent. Its value is the row's owner: filled by the platform or
+ * given once on insert, never written after, and stored as the row's parent edge in `RecordRef`, not
+ * in its data.
+ */
+export declare function isParentField(table: FieldsOf | undefined, fieldName: string): boolean;
+export type CompileCompanyMetadataResult = {
+    metadata: CompiledCompanyMetadata | null;
+    validation: ValidationResult;
+};
+/**
+ * The company schema as authored, without the reserved names (as `compileSlotSchema` leaves them
+ * out). It is plain data.
+ */
+export declare function compileCompanySchema(company: CompanySchema): CompanySchema;
+/**
+ * Why `schema/session.ts` is not a session schema (11-remove-sequence-schema §3.1): its fields are
+ * simple values, with no `ref` (the session is related to no other table).
+ */
+export declare function sessionSchemaIssues(session: SessionSchema): ValidationIssue[];
+/**
+ * The company's metadata: its tables (`schema/index.ts`) and its session fields (`schema/session.ts`,
+ * none when the file is missing). `session` is reserved: no company table has the name.
+ */
+export declare function compileCompanyMetadata(company: CompanySchema, session?: SessionSchema): CompileCompanyMetadataResult;
+/** The issue for a field that still names its `source` (19-page-writable-cells). */
+export declare function sourceRemovedIssue(path: string, prefix?: string): ValidationIssue;
+/** The issue for a field that still names `nullable`, which no write checked. */
+export declare function nullableRemovedIssue(path: string, prefix?: string): ValidationIssue;
+/** The issue for a field that still names `identifier`, which nothing used. */
+export declare function identifierRemovedIssue(path: string, prefix?: string): ValidationIssue;
+/**
+ * A field's choices (27 §2–§3): no `enum` (now a `select`); `options` on a `select` / `multi_select`
+ * only, and there required: 1 to `LIMITS.options` distinct short codes.
+ */
+export declare function optionIssues(path: string, field: Record<string, unknown>, prefix?: string): ValidationIssue[];
+/** The issue for a table that writes the row id, which is the platform's. */
+export declare function idIsPlatformIssue(path: string): ValidationIssue;
+/** The company table a sequence names as its business root, checked (14 §4.5). */
+export declare function subjectTableIssues(company: CompanySchema, subject: unknown): ValidationIssue[];
+//# sourceMappingURL=company-metadata.d.ts.map