@superpanel-sdk/runtime 0.2.2 → 0.5.0

package/dist/core/page/workspace.js

@@ -0,0 +1,231 @@
+export function workspaceText(page, options = {}) {
+    const out = [];
+    const notes = options.notes ?? [];
+    if (notes.length) {
+        out.push('<notes>');
+        for (const n of notes)
+            out.push(element('note', { id: n.id, about: n.about, value: n.text }));
+        out.push('</notes>');
+    }
+    const root = page.root;
+    if (root.guide)
+        out.push(element('guide', { value: root.guide }));
+    out.push(open('page', { title: root.title, description: root.description, fallback: page.fallback ? (page.fallback.stale ? 'stale' : 'empty') : undefined }));
+    if (page.fallback) {
+        out.push(element('text', {
+            key: 'fallback',
+            value: page.fallback.stale
+                ? 'This page could not be refreshed: its values may be out of date, and nothing on it can be changed now.'
+                : 'The case page could not be loaded: nothing is known about the case here, and nothing can be changed now.',
+        }));
+    }
+    const defined = definedCells(page);
+    if (defined.size) {
+        out.push('<definitions>');
+        for (const [kind, cell] of defined)
+            out.push(element('definition', { for: kind, ...definitionAttrs(page, cell) }));
+        out.push('</definitions>');
+    }
+    for (const child of root.children)
+        walk(page, child, defined, false, out);
+    out.push('</page>');
+    return out.join('\n');
+}
+const kindOf = (cell) => `${cell.ref.table}.${cell.ref.field}`;
+/** Each `table.field` some field on the page shows expanded, in page order: the page gives its definition once. */
+function definedCells(page) {
+    const out = new Map();
+    const visit = (node) => {
+        if (node.kind === 'cell' && node.expand) {
+            const cell = page.cells[node.slotId];
+            if (!out.has(kindOf(cell)))
+                out.set(kindOf(cell), cell);
+        }
+        if (node.kind === 'block')
+            node.children.forEach(visit);
+    };
+    page.root.children.forEach(visit);
+    return out;
+}
+function walk(page, node, defined, inList, out) {
+    switch (node.kind) {
+        case 'block': {
+            const tag = node.list ? 'list' : 'block';
+            out.push(open(tag, { key: inList ? undefined : node.key, title: node.title, description: node.description }));
+            for (const child of node.children)
+                walk(page, child, defined, node.list, out);
+            out.push(`</${tag}>`);
+            return;
+        }
+        case 'cell': {
+            const cell = page.cells[node.slotId];
+            // A field the AI cannot change needs no definition: no `more` on it (26 §16.2 #5b).
+            out.push(element('field', fieldAttrs(page, node, cell, editable(node, cell) && !defined.has(kindOf(cell)), inList)));
+            return;
+        }
+        case 'text':
+            // null: the page put nothing here now (a region that does not apply yet, a value it has not got).
+            // In a list it has no key of its own, only its place, as a block there (26 §16.2 #10).
+            out.push(element('text', { key: inList ? undefined : node.key, value: node.value }));
+            return;
+        case 'action':
+            out.push(...buttonLines(page.actions[node.actionId]));
+    }
+}
+const editable = (node, cell) => !node.readOnly && cell.writable;
+/**
+ * A field's value (26 §16.2): `key` always (#10; in a list, where it has only its place, none); `readonly`
+ * only on one the AI cannot change (#6a); `more` when its definition is not shown, with its type (#6);
+ * `state` only when it holds no value (#6a: a value is filled; `[]` too). A ref field (#7) writes the rows
+ * it may be set to as `one-of` {name: label}; read-only, who its value is as `value-label`, when the page
+ * labelled it.
+ */
+function fieldAttrs(page, node, cell, more, inList = false) {
+    const value = valueOf(cell, page);
+    const open = editable(node, cell);
+    const labels = cell.optionLabels ?? {};
+    return {
+        id: cell.slotId,
+        key: inList ? undefined : node.key,
+        readonly: !open,
+        more,
+        type: more ? cell.type : undefined,
+        value,
+        'value-label': !open && typeof value === 'string' && value in labels ? labels[value] : undefined,
+        'one-of': open && cell.options ? Object.fromEntries(cell.options.map((name) => [name, labels[name] ?? name])) : undefined,
+        state: cell.state === 'filled' ? undefined : cell.state,
+        reason: (cell.state === 'asked_unknown' || cell.state === 'declined') && cell.reason ? cell.reason : undefined,
+    };
+}
+/** The value as JSON holds it; a value that is a row's id is the row's page name; null when not filled. */
+function valueOf(cell, page) {
+    if (cell.state !== 'filled')
+        return null;
+    if (typeof cell.value === 'string') {
+        const name = Object.entries(page.rows).find(([, row]) => row.id === cell.value)?.[0];
+        if (name)
+            return name;
+    }
+    return cell.value ?? null;
+}
+/**
+ * What a field means and takes (26 §15.3): label, type, allowed values (`one-of`; a ref field's rows are
+ * on the field itself, 26 §16.2 #7), and `help` — the schema's description and how to fill it, the
+ * page's `$extraction` for its `table.field` replacing the schema's (a ref field's too, #5). How each type
+ * is written is the system message's (`PAGE_FORMAT`), once for every field.
+ */
+function definitionAttrs(page, cell) {
+    const help = [];
+    if (cell.description)
+        help.push(cell.description);
+    const own = page.extractions?.[kindOf(cell)];
+    if (own !== undefined) {
+        if (own)
+            help.push(own);
+    }
+    else if (cell.extraction)
+        help.push(cell.extraction);
+    return {
+        label: cell.label,
+        type: cell.type,
+        'one-of': cell.choices ?? undefined,
+        help: help.length ? help.join(' · ') : undefined,
+    };
+}
+function buttonLines(action) {
+    const attrs = { id: action.id, title: action.name, does: action.description };
+    const props = action.input?.properties ?? {};
+    if (!Object.keys(props).length)
+        return [element('button', attrs)];
+    const out = [open('button', attrs)];
+    for (const [name, prop] of Object.entries(props))
+        argLines(name, prop, action.input.required.includes(name), out);
+    out.push('</button>');
+    return out;
+}
+/**
+ * An argument, its type named as a field's (26 §15.8); a list's items are an `<item>`, an object's
+ * properties (a `contact_schedule`'s parts too) `<arg>`s inside it.
+ */
+function argLines(name, prop, required, out) {
+    const tag = name === null ? 'item' : 'arg';
+    const base = { name: name ?? undefined, required };
+    if (prop.type === 'array') {
+        out.push(open(tag, { ...base, type: 'list', help: prop.description }));
+        argLines(null, prop.items, false, out);
+        out.push(`</${tag}>`);
+        return;
+    }
+    if (prop.type === 'object') {
+        out.push(open(tag, { ...base, type: prop['x-type'] ?? 'object', nullable: Boolean(prop.nullable), help: prop.description }));
+        for (const [key, inner] of Object.entries(prop.properties))
+            argLines(key, inner, (prop.required ?? []).includes(key), out);
+        out.push(`</${tag}>`);
+        return;
+    }
+    // A row choice: each row with its label (26 §16.2 #7), as a ref field's candidates.
+    const oneOf = prop.type === 'ref' && prop.labels ? Object.fromEntries(prop.enum.map((name) => [name, prop.labels[name] ?? name])) : prop.enum;
+    out.push(element(tag, { ...base, type: prop.type, 'one-of': oneOf, help: prop.description }));
+}
+/** The block at `path` (`''`: the root). */
+export function blockAt(page, path) {
+    if (path === '')
+        return page.root;
+    let found = null;
+    const visit = (node) => {
+        if (found || node.kind !== 'block')
+            return;
+        if (node.path === path)
+            found = node;
+        else if (path.startsWith(`${node.path}.`) || node.path === '')
+            node.children.forEach(visit);
+    };
+    page.root.children.forEach(visit);
+    return found;
+}
+/** What `view` shows of one thing on the page (24 §3.2): a field with its definition, a button with its arguments. */
+export function viewText(page, id) {
+    const cell = page.cells[id];
+    if (cell) {
+        const node = findCellNode(page, id);
+        if (!node)
+            return null;
+        const { type: _type, 'one-of': rows, ...own } = fieldAttrs(page, node, cell, false);
+        const definition = definitionAttrs(page, cell);
+        // The field, then its definition; a ref field's rows are its own (`one-of` on the field).
+        return element('field', { ...own, ...definition, 'one-of': rows ?? definition['one-of'] });
+    }
+    const action = page.actions[id];
+    return action ? buttonLines(action).join('\n') : null;
+}
+function findCellNode(page, slotId) {
+    let found = null;
+    const visit = (node) => {
+        if (found)
+            return;
+        if (node.kind === 'cell' && node.slotId === slotId)
+            found = node;
+        if (node.kind === 'block')
+            node.children.forEach(visit);
+    };
+    visit(page.root);
+    return found;
+}
+// ---------------------------------------------------------------------------------------------
+// Writing elements
+/** `true`: a bare flag; `false` / `undefined`: left out; anything else `name=<JSON>`. `value` always prints, null included. */
+function attrText(attrs) {
+    const parts = [];
+    for (const [k, v] of Object.entries(attrs)) {
+        if (k === 'value')
+            parts.push(`value=${JSON.stringify(v ?? null)}`);
+        else if (v === true)
+            parts.push(k);
+        else if (v !== undefined && v !== false)
+            parts.push(`${k}=${JSON.stringify(v)}`);
+    }
+    return parts.length ? ` ${parts.join(' ')}` : '';
+}
+const open = (tag, attrs) => `<${tag}${attrText(attrs)}>`;
+const element = (tag, attrs) => `<${tag}${attrText(attrs)}/>`;
+//# sourceMappingURL=workspace.js.map

package/dist/core/party/index.d.ts

@@ -0,0 +1,3 @@
+export * from './schema.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/party/index.js

@@ -0,0 +1,3 @@
+export * from './schema.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/core/party/schema.d.ts

@@ -0,0 +1,137 @@
+import { z } from 'zod';
+/** How a contact is reached: a phone number or an email address. */
+export declare const partyAddress: z.ZodObject<{
+    kind: z.ZodEnum<{
+        email: "email";
+        phone: "phone";
+    }>;
+    value: z.ZodString;
+}, z.core.$strip>;
+export type PartyAddress = z.infer<typeof partyAddress>;
+/**
+ * The other side as a conversation arrives: a phone number or an email address, or the SIP URI of a
+ * SIP caller whose URI is not a phone number (`sip:alice@pbx.example.com`): no contact field holds it,
+ * so `resolve` finds the contact by what the call carries (`sip.headers`).
+ */
+export declare const arrivalAddress: z.ZodObject<{
+    kind: z.ZodEnum<{
+        email: "email";
+        phone: "phone";
+        sip: "sip";
+    }>;
+    value: z.ZodString;
+}, z.core.$strip>;
+export type ArrivalAddress = z.infer<typeof arrivalAddress>;
+/**
+ * A call that came through our SIP Domain: its URIs as they came, the domain, and the headers the far
+ * end sent (`X-…` ones and `User-to-User`, by name: `X-Case-Id`). A system that puts the call through
+ * to us says in them what it is about.
+ */
+export declare const sipArrival: z.ZodObject<{
+    fromUri: z.ZodNullable<z.ZodString>;
+    toUri: z.ZodNullable<z.ZodString>;
+    domain: z.ZodNullable<z.ZodString>;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>;
+export type SipArrival = z.infer<typeof sipArrival>;
+/**
+ * `ctx.params` of the company `resolve` (§18.2): an inbound conversation, before its sequence is known.
+ * `to.name` is our number's or mailbox's name in the environment (22 §7), the same in test and prod.
+ */
+export declare const companyResolveInput: z.ZodObject<{
+    channel: z.ZodEnum<{
+        call: "call";
+        email: "email";
+        sms: "sms";
+    }>;
+    from: z.ZodObject<{
+        kind: z.ZodEnum<{
+            email: "email";
+            phone: "phone";
+            sip: "sip";
+        }>;
+        value: z.ZodString;
+    }, z.core.$strip>;
+    threadId: z.ZodNullable<z.ZodString>;
+    sip: z.ZodOptional<z.ZodObject<{
+        fromUri: z.ZodNullable<z.ZodString>;
+        toUri: z.ZodNullable<z.ZodString>;
+        domain: z.ZodNullable<z.ZodString>;
+        headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>;
+    to: z.ZodObject<{
+        kind: z.ZodEnum<{
+            email: "email";
+            phone: "phone";
+        }>;
+        value: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CompanyResolveInput = z.infer<typeof companyResolveInput>;
+/**
+ * What the company `resolve` returns: the sequence (its name) the conversation goes to, or `decline`
+ * (we do not take it; §18.5): a call is transferred to the environment's fallback number, a text or
+ * an email gets `reply` when given.
+ */
+export declare const companyResolveResult: z.ZodUnion<readonly [z.ZodObject<{
+    sequence: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    decline: z.ZodObject<{
+        reply: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>]>;
+export type CompanyResolveResult = z.infer<typeof companyResolveResult>;
+/** `ctx.params` of a sequence's `resolve` (§18.3): the conversation, on this sequence. */
+export declare const resolveInput: z.ZodObject<{
+    channel: z.ZodEnum<{
+        call: "call";
+        email: "email";
+        sms: "sms";
+    }>;
+    from: z.ZodObject<{
+        kind: z.ZodEnum<{
+            email: "email";
+            phone: "phone";
+            sip: "sip";
+        }>;
+        value: z.ZodString;
+    }, z.core.$strip>;
+    to: z.ZodObject<{
+        kind: z.ZodEnum<{
+            email: "email";
+            phone: "phone";
+        }>;
+        value: z.ZodString;
+    }, z.core.$strip>;
+    threadId: z.ZodNullable<z.ZodString>;
+    sip: z.ZodOptional<z.ZodObject<{
+        fromUri: z.ZodNullable<z.ZodString>;
+        toUri: z.ZodNullable<z.ZodString>;
+        domain: z.ZodNullable<z.ZodString>;
+        headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>>;
+    direction: z.ZodEnum<{
+        inbound: "inbound";
+        outbound: "outbound";
+    }>;
+    sequence: z.ZodString;
+}, z.core.$strip>;
+export type ResolveInput = z.infer<typeof resolveInput>;
+/**
+ * What a sequence's `resolve` returns: the contact the conversation is with, and either an active
+ * instance of this sequence to join or a new one of this sequence to start (on a row of its subject
+ * table; when another start won the race for the same row, the conversation joins that one).
+ */
+export declare const resolveResult: z.ZodUnion<readonly [z.ZodObject<{
+    contactId: z.ZodString;
+    instanceId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    contactId: z.ZodString;
+    start: z.ZodObject<{
+        subjectRecordId: z.ZodString;
+        variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+}, z.core.$strict>]>;
+export type ResolveResult = z.infer<typeof resolveResult>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/core/party/schema.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+/** How a contact is reached: a phone number or an email address. */
+export const partyAddress = z.object({
+    kind: z.enum(['phone', 'email']),
+    value: z.string().min(1),
+});
+/**
+ * The other side as a conversation arrives: a phone number or an email address, or the SIP URI of a
+ * SIP caller whose URI is not a phone number (`sip:alice@pbx.example.com`): no contact field holds it,
+ * so `resolve` finds the contact by what the call carries (`sip.headers`).
+ */
+export const arrivalAddress = z.object({
+    kind: z.enum(['phone', 'email', 'sip']),
+    value: z.string().min(1),
+});
+/**
+ * A call that came through our SIP Domain: its URIs as they came, the domain, and the headers the far
+ * end sent (`X-…` ones and `User-to-User`, by name: `X-Case-Id`). A system that puts the call through
+ * to us says in them what it is about.
+ */
+export const sipArrival = z.object({
+    fromUri: z.string().nullable(),
+    toUri: z.string().nullable(),
+    domain: z.string().nullable(),
+    headers: z.record(z.string(), z.string()),
+});
+/**
+ * What both resolves get (14-sequence-instance §18): the conversation as it arrives, no facts looked
+ * up. They look up what they need (`ctx.api.contact.find`, `ctx.api.instances.findForContact`,
+ * `ctx.api.exchanges`).
+ */
+const conversationArrival = z.object({
+    channel: z.enum(['call', 'sms', 'email']),
+    /** The other side: the caller or sender on inbound, the one called on outbound. Normalized. */
+    from: arrivalAddress,
+    /** Our side: the number or mailbox the conversation came in on (inbound) or goes out from. */
+    to: partyAddress,
+    /** Email: the provider thread id, when the message belongs to one. */
+    threadId: z.string().nullable(),
+    /** A call through our SIP Domain; absent on any other conversation. */
+    sip: sipArrival.optional(),
+});
+/**
+ * `ctx.params` of the company `resolve` (§18.2): an inbound conversation, before its sequence is known.
+ * `to.name` is our number's or mailbox's name in the environment (22 §7), the same in test and prod.
+ */
+export const companyResolveInput = conversationArrival.extend({
+    to: partyAddress.extend({ name: z.string().nullable() }),
+});
+/**
+ * What the company `resolve` returns: the sequence (its name) the conversation goes to, or `decline`
+ * (we do not take it; §18.5): a call is transferred to the environment's fallback number, a text or
+ * an email gets `reply` when given.
+ */
+export const companyResolveResult = z.union([
+    z.strictObject({ sequence: z.string().min(1) }),
+    z.strictObject({ decline: z.strictObject({ reply: z.string().min(1).optional() }) }),
+]);
+/** `ctx.params` of a sequence's `resolve` (§18.3): the conversation, on this sequence. */
+export const resolveInput = conversationArrival.extend({
+    direction: z.enum(['inbound', 'outbound']),
+    /** This sequence (its name): the only one whose instances `resolve` may return or start. */
+    sequence: z.string(),
+});
+/**
+ * What a sequence's `resolve` returns: the contact the conversation is with, and either an active
+ * instance of this sequence to join or a new one of this sequence to start (on a row of its subject
+ * table; when another start won the race for the same row, the conversation joins that one).
+ */
+export const resolveResult = z.union([
+    z.strictObject({ contactId: z.string().min(1), instanceId: z.string().min(1) }),
+    z.strictObject({
+        contactId: z.string().min(1),
+        start: z.strictObject({
+            subjectRecordId: z.string().min(1),
+            variables: z.record(z.string(), z.unknown()).optional(),
+        }),
+    }),
+]);
+//# sourceMappingURL=schema.js.map

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

@@ -0,0 +1,40 @@
+import type { FunctionCtx, NoCaseFn } from '../functions/types.js';
+import type { PageTablesDesc } from '../page/typed.js';
+import type { CompanyResolveInput, CompanyResolveResult, ResolveInput, ResolveResult } from './schema.js';
+/**
+ * Who an inbound conversation goes to is decided in two steps (14-sequence-instance §18): the company
+ * repo's root `resolve.ts` picks the sequence, then that sequence's `sequences/<id>/resolve.ts` picks
+ * the instance of it (an active one, or a new one). Both export `resolve`.
+ */
+export declare const RESOLVE_MODULE = "resolve";
+/** Reserved export of `resolve.ts` and its name in the build's `functions`. */
+export declare const RESOLVE_FUNCTION = "resolve";
+/** `ctx.meta.entry` / RunScope entry of a `resolve` call. */
+export declare const RESOLVE_ENTRY = "resolve";
+/** The company `resolve.ts` compiled into every sequence's build, under this reserved name (§18.2). */
+export declare const COMPANY_RESOLVE_FUNCTION = "companyResolve";
+/** `ctx.meta.entry` / RunScope entry of a company `resolve` call. */
+export declare const COMPANY_RESOLVE_ENTRY = "companyResolve";
+/**
+ * The company `resolve.ts` (§18.2): `export const resolve: CompanyResolve = async (ctx) => …`. Runs for
+ * inbound calls, texts and emails only, before the sequence is known: returns `{ sequence }` (a name)
+ * or `{ decline: { reply? } }`. It reads with `ctx.api` like any function; the repository root's
+ * `__gen/` binds `D` to the company's tables, so `ctx.api.db` is typed.
+ */
+export type CompanyResolve<D extends PageTablesDesc | undefined = undefined> = NoCaseFn<CompanyResolveInput, CompanyResolveResult, D>;
+/**
+ * `ctx` of a sequence's `resolve`: the usual function ctx (it finds and creates through
+ * `ctx.api.contact`, reads and writes records through `ctx.api.db`, finds instances through
+ * `ctx.api.instances` and exchanges through `ctx.api.exchanges`) with the conversation as `params`.
+ * `meta.instanceId` is null.
+ */
+export type ResolveContext<D extends PageTablesDesc | undefined = undefined> = FunctionCtx<ResolveInput, D>;
+/**
+ * `sequences/<id>/resolve.ts`: `export const resolve: Resolve = async (ctx) => …`, with `Resolve`
+ * imported from the sequence's `__gen`. A `noCase` function: the conversation in, `{ contactId,
+ * instanceId }` or `{ contactId, start }` out, on this sequence only. The platform gives it what is
+ * left of the time limit, checks the ids (an active instance of this sequence, a contact, a row of
+ * its subject table, all of this company and environment), and fails the conversation when not.
+ */
+export type Resolve<D extends PageTablesDesc | undefined = undefined> = NoCaseFn<ResolveInput, ResolveResult, D>;
+//# sourceMappingURL=types.d.ts.map

package/dist/core/party/types.js

@@ -0,0 +1,15 @@
+/**
+ * Who an inbound conversation goes to is decided in two steps (14-sequence-instance §18): the company
+ * repo's root `resolve.ts` picks the sequence, then that sequence's `sequences/<id>/resolve.ts` picks
+ * the instance of it (an active one, or a new one). Both export `resolve`.
+ */
+export const RESOLVE_MODULE = 'resolve';
+/** Reserved export of `resolve.ts` and its name in the build's `functions`. */
+export const RESOLVE_FUNCTION = 'resolve';
+/** `ctx.meta.entry` / RunScope entry of a `resolve` call. */
+export const RESOLVE_ENTRY = 'resolve';
+/** The company `resolve.ts` compiled into every sequence's build, under this reserved name (§18.2). */
+export const COMPANY_RESOLVE_FUNCTION = 'companyResolve';
+/** `ctx.meta.entry` / RunScope entry of a company `resolve` call. */
+export const COMPANY_RESOLVE_ENTRY = 'companyResolve';
+//# sourceMappingURL=types.js.map

package/dist/core/sequence/define.d.ts

@@ -0,0 +1,57 @@
+/**
+ * What a sequence's `index.ts` and `variables.ts` declare with (14-sequence-instance §4.4–§4.5). Part of
+ * the company API (`src/index.ts`), so it imports nothing: the checks live in `./index.ts`.
+ */
+/** `sequences/<id>/index.ts` default export. */
+export type SequenceDefinition<S extends string = string> = {
+    meta?: {
+        name?: string;
+        label?: string;
+        description?: string;
+    };
+    /** The company table each run is about: one row of it is the instance's business root. */
+    subject: S;
+};
+export declare function defineSequence<const S extends string>(definition: SequenceDefinition<S>): SequenceDefinition<S>;
+/** A JSON variable's marker; the type argument is only an editor hint (the platform checks it serializes). */
+export type JsonVariableType<T = unknown> = {
+    readonly kind: 'json';
+    readonly __type?: T;
+};
+export declare function json<T = unknown>(): JsonVariableType<T>;
+/** One run variable as declared. */
+export type VariableDecl = {
+    options: readonly (string | number | boolean)[];
+    default?: string | number | boolean | null;
+} | {
+    type: 'string';
+    default?: string | null;
+} | {
+    type: 'number';
+    default?: number | null;
+} | {
+    type: 'boolean';
+    default?: boolean | null;
+} | {
+    type: JsonVariableType;
+    default?: unknown;
+};
+export type VariableDecls = Record<string, VariableDecl>;
+export declare function defineVariables<const V extends VariableDecls>(variables: V): V;
+type VariableValue<D> = D extends {
+    options: readonly (infer O)[];
+} ? O : D extends {
+    type: 'string';
+} ? string : D extends {
+    type: 'number';
+} ? number : D extends {
+    type: 'boolean';
+} ? boolean : D extends {
+    type: JsonVariableType<infer T>;
+} ? T : never;
+/** The values of a `defineVariables` declaration, by name (null when unset and without a default). */
+export type VariablesOf<V> = {
+    [K in keyof V]: VariableValue<V[K]> | null;
+};
+export {};
+//# sourceMappingURL=define.d.ts.map

package/dist/core/sequence/define.js

@@ -0,0 +1,10 @@
+export function defineSequence(definition) {
+    return definition;
+}
+export function json() {
+    return { kind: 'json' };
+}
+export function defineVariables(variables) {
+    return variables;
+}
+//# sourceMappingURL=define.js.map

package/dist/core/sequence/index.d.ts

@@ -0,0 +1,63 @@
+export { defineSequence, defineVariables, json, type JsonVariableType, type SequenceDefinition, type VariableDecl, type VariableDecls, type VariablesOf, } from './define.js';
+/** One experiment: an enum variable and the share each of its values gets when a run does not set it. */
+export type ExperimentDecl = {
+    variable: string;
+    split: Record<string, number>;
+};
+/** `SequenceBuild.variables`: every declared variable, normalized. */
+export type CompiledVariable = {
+    type: 'enum';
+    options: Array<string | number | boolean>;
+    default: string | number | boolean | null;
+} | {
+    type: 'string';
+    default: string | null;
+} | {
+    type: 'number';
+    default: number | null;
+} | {
+    type: 'boolean';
+    default: boolean | null;
+} | {
+    type: 'json';
+    default: unknown;
+};
+export type CompiledVariables = Record<string, CompiledVariable>;
+export type CompiledExperiments = Record<string, ExperimentDecl>;
+/**
+ * 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 declare const SYSTEM_VARIABLES: readonly ['responsePolicy', 'slotFillingPolicy', 'voice'];
+export type SystemVariableName = (typeof SYSTEM_VARIABLES)[number];
+export declare function isSystemVariable(name: string): name is SystemVariableName;
+export type CompileVariablesResult = {
+    variables: CompiledVariables;
+    experiments: CompiledExperiments;
+    issues: string[];
+};
+/** Normalize and check a sequence's `variables.ts` (14 §4.4). */
+export declare function compileVariables(declared: unknown, experiments: unknown): CompileVariablesResult;
+/** Why `value` cannot be stored in the variable; null when it can. `null` always can (unset). */
+export declare function variableValueIssue(name: string, variable: CompiledVariable | undefined, value: unknown): string | null;
+/** Issues of a whole write of variables (unknown names, wrong types); empty when it may be stored. */
+export declare function variablesWriteIssues(variables: CompiledVariables, values: Record<string, unknown>): string[];
+/**
+ * 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 declare function startVariables(instanceId: string, declared: CompiledVariables, experiments: CompiledExperiments, given: Record<string, unknown>): {
+    variables: Record<string, unknown>;
+    experiments: Record<string, string>;
+};
+/**
+ * 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 declare function readVariables(declared: CompiledVariables, stored: Record<string, unknown>, onStale?: (name: string, value: unknown) => void): Record<string, unknown>;
+/** Bytes of `variables` serialized: what {@link LIMITS.variablesBytes} bounds. */
+export declare function variablesSize(variables: Record<string, unknown>): number;
+//# sourceMappingURL=index.d.ts.map