@superpanel-sdk/runtime 0.2.3 → 0.5.0

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

@@ -1,36 +1,14 @@
 import type { FieldState } from '../context/types.js';
-import type { FieldHistoryEntry, FieldValue, UpdatedBy } from './types.js';
+import type { FieldHistoryEntry, FieldValue, SlotValue, UpdatedBy } from './types.js';
 /** Stage done checks use resolved, not "has a value". */
 export declare function isResolved(field: FieldValue | null | undefined): boolean;
 export declare function emptyFieldValue(now?: number): FieldValue;
 export declare function makeFieldValue(partial: {
-    value: string | number | boolean | null;
+    value: SlotValue;
     state: FieldState;
     reason?: string | null;
     updatedBy?: UpdatedBy;
     updatedAt?: number;
     history?: FieldHistoryEntry[];
 }): FieldValue;
-/**
- * C5 change detection: value or state changed.
- * reason-only updates do not count (01-slot-design §2 iron rule).
- */
-export declare function fieldChanged(prev: FieldValue | undefined, next: FieldValue): boolean;
-export declare function toHistoryEntry(field: FieldValue): FieldHistoryEntry;
-export type CommitFieldWriteResult = {
-    field: FieldValue;
-    changed: boolean;
-    /** Previous generation archived into `field.history` (absent when unchanged or prev was empty). */
-    historyEntry?: FieldHistoryEntry;
-};
-/**
- * Apply a write onto a field envelope.
- * - C5 change: archive previous non-empty generation into `history`, then replace current
- * - reason-only: update reason, keep value/state/history/updated*
- */
-export declare function commitFieldWrite(prev: FieldValue | undefined, next: FieldValue): CommitFieldWriteResult;
-/** Last N generation values: prior history entries + current value (01-slot-db §4.2). */
-export declare function getLastThreeValues(field: FieldValue, n?: number): Array<string | number | boolean | null>;
-export declare function getFieldValue(field: FieldValue | null | undefined): string | number | boolean | null;
-export declare function getFieldState(field: FieldValue | null | undefined): FieldState;
 //# sourceMappingURL=field.d.ts.map

package/dist/core/slot/field.js

@@ -25,73 +25,4 @@ export function makeFieldValue(partial) {
         history: partial.history ?? [],
     };
 }
-/**
- * C5 change detection: value or state changed.
- * reason-only updates do not count (01-slot-design §2 iron rule).
- */
-export function fieldChanged(prev, next) {
-    if (!prev) {
-        return next.state !== 'empty' || next.value !== null;
-    }
-    return prev.value !== next.value || prev.state !== next.state;
-}
-export function toHistoryEntry(field) {
-    return {
-        value: field.value,
-        state: field.state,
-        at: field.updatedAt,
-        by: field.updatedBy,
-    };
-}
-/**
- * Apply a write onto a field envelope.
- * - C5 change: archive previous non-empty generation into `history`, then replace current
- * - reason-only: update reason, keep value/state/history/updated*
- */
-export function commitFieldWrite(prev, next) {
-    if (!fieldChanged(prev, next)) {
-        if (!prev) {
-            return {
-                field: makeFieldValue({ ...next, history: [] }),
-                changed: false,
-            };
-        }
-        return {
-            field: {
-                ...prev,
-                reason: next.reason,
-            },
-            changed: false,
-        };
-    }
-    const history = [...(prev?.history ?? [])];
-    let historyEntry;
-    if (prev && prev.state !== 'empty') {
-        historyEntry = toHistoryEntry(prev);
-        history.push(historyEntry);
-    }
-    return {
-        field: makeFieldValue({
-            value: next.value,
-            state: next.state,
-            reason: next.reason,
-            updatedBy: next.updatedBy,
-            updatedAt: next.updatedAt,
-            history,
-        }),
-        changed: true,
-        ...(historyEntry ? { historyEntry } : {}),
-    };
-}
-/** Last N generation values: prior history entries + current value (01-slot-db §4.2). */
-export function getLastThreeValues(field, n = 3) {
-    const generations = [...field.history.map((h) => h.value), field.value];
-    return generations.slice(-n);
-}
-export function getFieldValue(field) {
-    return field?.value ?? null;
-}
-export function getFieldState(field) {
-    return field?.state ?? 'empty';
-}
 //# sourceMappingURL=field.js.map

package/dist/core/slot/id-ref.d.ts

@@ -1,4 +1,19 @@
 import type { CompanyNormalFieldDef } from './schema.js';
-/** System string field that stores `{table}.id`. */
-export declare function idRef(table: string, extras?: Pick<Partial<CompanyNormalFieldDef>, 'label' | 'nullable' | 'extraction'>): CompanyNormalFieldDef;
+/**
+ * What a ref may say of itself beyond its target: `relatedName`, the name of the way back from the
+ * target row to the rows that point at it (13-data-model-v1 §23.4 item 3), e.g.
+ * `case_file: parentRef('case_file', { relatedName: 'injuries' })` gives `case_file.injuries`.
+ */
+type RefOptions = {
+    relatedName?: string;
+};
+/** String field that stores `{table}.id`: a lookup (13-data-model-v1 §11.2). */
+export declare function lookupRef(table: string, extras?: Pick<Partial<CompanyNormalFieldDef>, 'label' | 'extraction'> & RefOptions): CompanyNormalFieldDef;
+/**
+ * The row's owner (13-data-model-v1 §11.2, §22.4, 14-sequence-instance §16.1), e.g.
+ * `matter: parentRef('matter')`. Required; filled by the platform when it points at the sequence's
+ * business root, otherwise given once on insert. A parent row has any number of rows under it.
+ */
+export declare function parentRef(table: string, options?: Pick<Partial<CompanyNormalFieldDef>, 'label' | 'extraction'> & RefOptions): CompanyNormalFieldDef;
+export {};
 //# sourceMappingURL=id-ref.d.ts.map

package/dist/core/slot/id-ref.js

@@ -1,15 +1,23 @@
-/** System string field that stores `{table}.id`. */
-export function idRef(table, extras) {
+/** String field that stores `{table}.id`: a lookup (13-data-model-v1 §11.2). */
+export function lookupRef(table, extras) {
     return {
-        derived: false,
         label: extras?.label ?? table,
         dataType: 'string',
-        source: 'system',
         extraction: extras?.extraction ?? `Reference to ${table}.id`,
-        enum: null,
-        nullable: extras?.nullable ?? false,
-        identifier: null,
-        ref: { table },
+        ref: { table, kind: 'lookup', ...(extras?.relatedName !== undefined ? { relatedName: extras.relatedName } : {}) },
+    };
+}
+/**
+ * The row's owner (13-data-model-v1 §11.2, §22.4, 14-sequence-instance §16.1), e.g.
+ * `matter: parentRef('matter')`. Required; filled by the platform when it points at the sequence's
+ * business root, otherwise given once on insert. A parent row has any number of rows under it.
+ */
+export function parentRef(table, options) {
+    return {
+        label: options?.label ?? table,
+        dataType: 'string',
+        extraction: options?.extraction ?? `The ${table} this row belongs to`,
+        ref: { table, kind: 'parent', ...(options?.relatedName !== undefined ? { relatedName: options.relatedName } : {}) },
     };
 }
 //# sourceMappingURL=id-ref.js.map

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

@@ -1,15 +1,14 @@
-export { ROW_ID_FIELD, idField, idFieldCore } from './schema.js';
-export { idRef } from './id-ref.js';
-export { emptyMultiRow, emptySlotRow, getRowField, isFieldValue, isReservedTableName, isRowIdField, mintRowId, SNAPSHOT_CURRENT_KEY, rowValueEntries, slotFieldEntries, slotFieldNames, type SlotRow, } from './row.js';
+export { ROW_ID_FIELD, ROW_SYSTEM_KEYS, ROW_TIME_KEYS, isRowTimeKey, type RowSystemKey, type RowTimeKey, idFieldCore, normalFieldCoreSchema, companyNormalFieldDefSchema, compiledCompanyMetadataSchema, companyFieldDefSchema, companyTableDefSchema, companySchemaSchema, contactScheduleValueSchema, localTimeRangeSchema, isCompanySchema, } from './schema.js';
+export { CONTACT_OPT_OUT_FIELDS, CONTACT_TABLE, LIMITS, PLATFORM_CONTACT_FIELDS, POLICY_IDS, SESSION_TABLE, compileCompanyMetadata, isCustomTable, isParentField, isRecordTable, parentOf, subjectTableIssues, compileCompanySchema, type CompileCompanyMetadataResult, type ResponsePolicyId, type SlotFillingPolicyId, type VoiceProfileId, } from './company-metadata.js';
+export { lookupRef, parentRef } from './id-ref.js';
+export { isFieldValue, isReservedTableName, isRowIdField, mintRowId, SNAPSHOT_CURRENT_KEY, slotFieldEntries, slotFieldNames, type SlotRow, } from './row.js';
 export { parseFieldPath, requireFieldPath, formatFieldPath, type FieldPath, type ParsedFieldPath } from './path.js';
-export { isResolved, emptyFieldValue, makeFieldValue, fieldChanged, commitFieldWrite, getLastThreeValues, toHistoryEntry, getFieldValue, getFieldState, type CommitFieldWriteResult, } from './field.js';
-export { buildDependencyGraph, affectedDerivedFields, type DependencyGraphResult } from './deps.js';
-export { compileSlotSchema, compiledTableEntries, getCompiledTable, validateFieldRefs, toEffectiveSchema, listConversationFields, isSnapshotSingleRow, } from './compile-schema.js';
-export { isValidDataTypeValue, validateExtractedField, validateBareValue } from './value.js';
-export { buildSlotFillingJsonSchema, buildFieldCatalog, type SfSchemaOptions } from './sf-schema.js';
-export { validateSlotFillingOutput, type ValidateSlotFillingOptions } from './sf-validate.js';
-export { snapshotFrom, cloneSnapshot, getSingleField, getSnapshotTable, type SnapshotSeed } from './snapshot.js';
-export { applyFieldPatch, applyWrites, applySlotFilling, markAskedUnknown, isRowWrite, isStructuredWrites, normalizeWrites, type ApplySlotFillingOptions, type FieldPatchInput, } from './write.js';
-export type { ComputeFnMap, ComputeHost, ComputeHostOrFns, LocalComputeHostOptions, RecomputeOptions, } from './derived.js';
-export { createLocalComputeHost, createSourceComputeHost, resolveComputeHost, recomputeDerived, applyFieldPatchAndRecompute, applyWritesAndRecompute, applySlotFillingAndRecompute, } from './derived.js';
+export { isResolved, emptyFieldValue, makeFieldValue, } from './field.js';
+export { compileSlotSchema, compiledTableEntries, getCompiledTable, getTableField, relationsOf, type TableRelation, validateFieldRefs, companyFieldToRuntime, } from './compile-schema.js';
+export { companyMetadataCompatibilityIssues } from './schema-compat.js';
+export { DATE_VALUE_FORMAT, DATE_VALUE_PATTERN, DATETIME_VALUE_FORMAT, DATETIME_VALUE_PATTERN, isValidDataTypeValue, validateBareValue, } from './value.js';
+export { refKind, refValueIssues, type RefKind } from './ref.js';
+export type { ComputeFnMap, ComputeHost, ComputeHostOrFns } from '../../compute-host/compute-host.js';
+export { createLocalComputeHost, resolveComputeHost } from '../../compute-host/compute-host.js';
+export { createSourceComputeHost } from '../../compute-host/source-compute-host.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/slot/index.js

@@ -1,14 +1,13 @@
-export { ROW_ID_FIELD, idField, idFieldCore } from './schema.js';
-export { idRef } from './id-ref.js';
-export { emptyMultiRow, emptySlotRow, getRowField, isFieldValue, isReservedTableName, isRowIdField, mintRowId, SNAPSHOT_CURRENT_KEY, rowValueEntries, slotFieldEntries, slotFieldNames, } from './row.js';
+export { ROW_ID_FIELD, ROW_SYSTEM_KEYS, ROW_TIME_KEYS, isRowTimeKey, idFieldCore, normalFieldCoreSchema, companyNormalFieldDefSchema, compiledCompanyMetadataSchema, companyFieldDefSchema, companyTableDefSchema, companySchemaSchema, contactScheduleValueSchema, localTimeRangeSchema, isCompanySchema, } from './schema.js';
+export { CONTACT_OPT_OUT_FIELDS, CONTACT_TABLE, LIMITS, PLATFORM_CONTACT_FIELDS, POLICY_IDS, SESSION_TABLE, compileCompanyMetadata, isCustomTable, isParentField, isRecordTable, parentOf, subjectTableIssues, compileCompanySchema, } from './company-metadata.js';
+export { lookupRef, parentRef } from './id-ref.js';
+export { isFieldValue, isReservedTableName, isRowIdField, mintRowId, SNAPSHOT_CURRENT_KEY, slotFieldEntries, slotFieldNames, } from './row.js';
 export { parseFieldPath, requireFieldPath, formatFieldPath } from './path.js';
-export { isResolved, emptyFieldValue, makeFieldValue, fieldChanged, commitFieldWrite, getLastThreeValues, toHistoryEntry, getFieldValue, getFieldState, } from './field.js';
-export { buildDependencyGraph, affectedDerivedFields } from './deps.js';
-export { compileSlotSchema, compiledTableEntries, getCompiledTable, validateFieldRefs, toEffectiveSchema, listConversationFields, isSnapshotSingleRow, } from './compile-schema.js';
-export { isValidDataTypeValue, validateExtractedField, validateBareValue } from './value.js';
-export { buildSlotFillingJsonSchema, buildFieldCatalog } from './sf-schema.js';
-export { validateSlotFillingOutput } from './sf-validate.js';
-export { snapshotFrom, cloneSnapshot, getSingleField, getSnapshotTable } from './snapshot.js';
-export { applyFieldPatch, applyWrites, applySlotFilling, markAskedUnknown, isRowWrite, isStructuredWrites, normalizeWrites, } from './write.js';
-export { createLocalComputeHost, createSourceComputeHost, resolveComputeHost, recomputeDerived, applyFieldPatchAndRecompute, applyWritesAndRecompute, applySlotFillingAndRecompute, } from './derived.js';
+export { isResolved, emptyFieldValue, makeFieldValue, } from './field.js';
+export { compileSlotSchema, compiledTableEntries, getCompiledTable, getTableField, relationsOf, validateFieldRefs, companyFieldToRuntime, } from './compile-schema.js';
+export { companyMetadataCompatibilityIssues } from './schema-compat.js';
+export { DATE_VALUE_FORMAT, DATE_VALUE_PATTERN, DATETIME_VALUE_FORMAT, DATETIME_VALUE_PATTERN, isValidDataTypeValue, validateBareValue, } from './value.js';
+export { refKind, refValueIssues } from './ref.js';
+export { createLocalComputeHost, resolveComputeHost } from '../../compute-host/compute-host.js';
+export { createSourceComputeHost } from '../../compute-host/source-compute-host.js';
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,15 @@
+/**
+ * Naming rules for the company schema (13-data-model-v1 §23.4 item 6): table names, field names
+ * (session fields included) and relation names. A name ends up as a path segment (`table.field`,
+ * `injury#1.severity`), an object key at runtime and a property in generated TypeScript, so it is
+ * kept to what is safe in all three.
+ */
+/** Postgres's identifier limit: a field can become a real column without a rename. */
+export declare const NAME_MAX_LENGTH = 63;
+export type NameProblem = {
+    code: 'invalid-name' | 'reserved-name';
+    reason: string;
+};
+/** Why `name` cannot name a table, field or relation; null when it can. */
+export declare function nameProblem(name: string): NameProblem | null;
+//# sourceMappingURL=naming.d.ts.map

package/dist/core/slot/naming.js

@@ -0,0 +1,96 @@
+/**
+ * Naming rules for the company schema (13-data-model-v1 §23.4 item 6): table names, field names
+ * (session fields included) and relation names. A name ends up as a path segment (`table.field`,
+ * `injury#1.severity`), an object key at runtime and a property in generated TypeScript, so it is
+ * kept to what is safe in all three.
+ */
+/** Lowercase letters, digits and `_`, starting with a letter: never `.`, `-`, `#`, `*`, `$` or a space. */
+const NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+/** Postgres's identifier limit: a field can become a real column without a rename. */
+export const NAME_MAX_LENGTH = 63;
+/**
+ * JavaScript's reserved words. A row's `case` still works as `row.case`, but `const { case } = row`
+ * does not parse; a schema is written by an AI, so another name costs nothing.
+ */
+const JS_RESERVED_WORDS = new Set([
+    'await',
+    'break',
+    'case',
+    'catch',
+    'class',
+    'const',
+    'continue',
+    'debugger',
+    'default',
+    'delete',
+    'do',
+    'else',
+    'enum',
+    'export',
+    'extends',
+    'false',
+    'finally',
+    'for',
+    'function',
+    'if',
+    'implements',
+    'import',
+    'in',
+    'instanceof',
+    'interface',
+    'let',
+    'new',
+    'null',
+    'package',
+    'private',
+    'protected',
+    'public',
+    'return',
+    'static',
+    'super',
+    'switch',
+    'this',
+    'throw',
+    'true',
+    'try',
+    'typeof',
+    'var',
+    'void',
+    'while',
+    'with',
+    'yield',
+]);
+/**
+ * Properties every object has. A table or field by one of these names is found on the prototype by a
+ * plain lookup (`tables[name]`) when it is not there, or replaces it when it is.
+ */
+const OBJECT_PROPERTY_NAMES = new Set([
+    'constructor',
+    'hasOwnProperty',
+    'isPrototypeOf',
+    'propertyIsEnumerable',
+    'prototype',
+    'toLocaleString',
+    'toString',
+    'valueOf',
+    '__proto__',
+    '__defineGetter__',
+    '__defineSetter__',
+    '__lookupGetter__',
+    '__lookupSetter__',
+]);
+/** Why `name` cannot name a table, field or relation; null when it can. */
+export function nameProblem(name) {
+    if (!NAME_PATTERN.test(name)) {
+        return { code: 'invalid-name', reason: 'use lowercase letters, digits and _, starting with a letter' };
+    }
+    if (name.length > NAME_MAX_LENGTH) {
+        return { code: 'invalid-name', reason: `at most ${NAME_MAX_LENGTH} characters` };
+    }
+    if (JS_RESERVED_WORDS.has(name))
+        return { code: 'reserved-name', reason: 'a JavaScript reserved word' };
+    if (OBJECT_PROPERTY_NAMES.has(name))
+        return { code: 'reserved-name', reason: 'a property every object has' };
+    return null;
+}
+//# sourceMappingURL=naming.js.map

package/dist/core/slot/platform-fields.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The contact table's platform fields. The company schema spreads them into `contact` and the runtime
+ * checks them against these definitions, so a field added here reaches every company without editing
+ * its schema. Every sequence carries them and none may override them. Before adding one, check no
+ * company's live schema has a field of that name (14 §5.3).
+ */
+export declare const PLATFORM_CONTACT_FIELDS: {
+    readonly kind: {
+        readonly label: 'Kind';
+        readonly dataType: 'select';
+        readonly extraction: 'Whether the contact is a person or an organization';
+        readonly options: ["person", "organization"];
+    };
+    readonly phone: {
+        readonly label: 'Phone';
+        readonly dataType: 'phone';
+        readonly extraction: "The contact's main phone number, the one to call back; only when they give one.";
+    };
+    readonly email: {
+        readonly label: 'Email';
+        readonly dataType: 'email';
+        readonly extraction: "The contact's main email address; only when they give one.";
+    };
+    readonly first_name: {
+        readonly label: 'First name';
+        readonly dataType: 'string';
+        readonly extraction: "The contact's first (given) name. They may spell it; keep their spelling.";
+    };
+    readonly last_name: {
+        readonly label: 'Last name';
+        readonly dataType: 'string';
+        readonly extraction: "The contact's last (family) name. They may spell it; keep their spelling.";
+    };
+    readonly street: {
+        readonly label: 'Street address';
+        readonly dataType: 'string';
+        readonly extraction: 'The street line of the contact\'s home or mailing address: number and street, with the unit or apartment (e.g. "1450 NE 2nd Ave, Apt 7"). Not the city, state or postal code.';
+    };
+    readonly city: {
+        readonly label: 'City';
+        readonly dataType: 'string';
+        readonly extraction: "The city of the contact's home or mailing address.";
+    };
+    readonly state: {
+        readonly label: 'State or province';
+        readonly dataType: 'select';
+        readonly extraction: "The two-letter code (FL, TX, ON) of the state or province they live in; from a city only when it is unambiguous.";
+        readonly options: ("AB" | "AK" | "AL" | "AR" | "AS" | "AZ" | "BC" | "CA" | "CO" | "CT" | "DC" | "DE" | "FL" | "GA" | "GU" | "HI" | "IA" | "ID" | "IL" | "IN" | "KS" | "KY" | "LA" | "MA" | "MB" | "MD" | "ME" | "MI" | "MN" | "MO" | "MP" | "MS" | "MT" | "NB" | "NC" | "ND" | "NE" | "NH" | "NJ" | "NL" | "NM" | "NS" | "NT" | "NU" | "NV" | "NY" | "OH" | "OK" | "ON" | "OR" | "PA" | "PE" | "PR" | "QC" | "RI" | "SC" | "SD" | "SK" | "TN" | "TX" | "UT" | "VA" | "VI" | "VT" | "WA" | "WI" | "WV" | "WY" | "YT")[];
+    };
+    readonly postal_code: {
+        readonly label: 'Postal code';
+        readonly dataType: 'string';
+        readonly extraction: "The ZIP code (5 digits, or ZIP+4) or Canadian postal code of the contact's home or mailing address.";
+    };
+    readonly country: {
+        readonly label: 'Country';
+        readonly dataType: 'string';
+        readonly extraction: 'ISO two-letter code (US, CA); only when they say they live outside the US.';
+    };
+    readonly timezone: {
+        readonly label: 'Timezone';
+        readonly dataType: 'string';
+        readonly extraction: 'An IANA timezone, only when they state one or a place that fixes one; never from a phone number.';
+    };
+    readonly language: {
+        readonly label: 'Language';
+        readonly dataType: 'select';
+        readonly extraction: 'The language they speak with us, when they speak or ask for one of these; the platform then speaks it.';
+        readonly options: ["english", "spanish"];
+    };
+    readonly opted_out: {
+        readonly label: 'Opted out';
+        readonly dataType: 'boolean';
+        readonly extraction: 'true when they clearly ask us to stop contacting them at all; false only when they agree to be contacted again. Not for one channel.';
+    };
+    readonly call_opted_out: {
+        readonly label: 'Call opted out';
+        readonly dataType: 'boolean';
+        readonly extraction: 'true when they clearly ask not to be called; false only when they agree to calls again.';
+    };
+    readonly sms_opted_out: {
+        readonly label: 'SMS opted out';
+        readonly dataType: 'boolean';
+        readonly extraction: 'true when they clearly ask not to be texted; false only when they agree to texts again.';
+    };
+    readonly email_opted_out: {
+        readonly label: 'Email opted out';
+        readonly dataType: 'boolean';
+        readonly extraction: 'true when they clearly ask not to be emailed; false only when they agree to emails again.';
+    };
+    readonly contact_schedule: {
+        readonly label: 'Contact schedule';
+        readonly dataType: 'contact_schedule';
+        readonly extraction: 'When they may be contacted, only when they say: the whole schedule with their change applied. Relative dates from today in their timezone; split overnight windows; do not guess an unclear time.';
+    };
+    readonly assigned_phone_number: {
+        readonly label: 'Assigned phone number';
+        readonly dataType: 'phone';
+        readonly extraction: 'Our phone number (E.164) this contact is reached from; set by the platform';
+    };
+    readonly assigned_mailbox: {
+        readonly label: 'Assigned mailbox';
+        readonly dataType: 'email';
+        readonly extraction: 'Our mailbox address this contact is emailed from; set by the platform';
+    };
+};
+/**
+ * The session's platform fields (24 §5.2): `schema/session.ts` spreads them into its fields, checked
+ * like the contact's. `stuck`: the AI marked the call stuck (its `stuck` action); the page reads it,
+ * decides what to do, and clears it.
+ */
+export declare const PLATFORM_SESSION_FIELDS: {
+    readonly stuck: {
+        readonly label: 'Stuck';
+        readonly dataType: 'boolean';
+        readonly extraction: 'Set by the platform when the AI marks the conversation stuck; the page clears it once handled.';
+    };
+};
+//# sourceMappingURL=platform-fields.d.ts.map

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

@@ -0,0 +1,121 @@
+import { SPOKEN_LANGUAGES } from '../conversation/index.js';
+import { STATE_CODES } from './contact-timezone.js';
+/**
+ * The contact table's platform fields. The company schema spreads them into `contact` and the runtime
+ * checks them against these definitions, so a field added here reaches every company without editing
+ * its schema. Every sequence carries them and none may override them. Before adding one, check no
+ * company's live schema has a field of that name (14 §5.3).
+ */
+export const PLATFORM_CONTACT_FIELDS = {
+    kind: {
+        label: 'Kind',
+        dataType: 'select',
+        extraction: 'Whether the contact is a person or an organization',
+        options: ['person', 'organization'],
+    },
+    phone: {
+        label: 'Phone',
+        dataType: 'phone',
+        extraction: "The contact's main phone number, the one to call back; only when they give one.",
+    },
+    email: {
+        label: 'Email',
+        dataType: 'email',
+        extraction: "The contact's main email address; only when they give one.",
+    },
+    first_name: {
+        label: 'First name',
+        dataType: 'string',
+        extraction: "The contact's first (given) name. They may spell it; keep their spelling.",
+    },
+    last_name: {
+        label: 'Last name',
+        dataType: 'string',
+        extraction: "The contact's last (family) name. They may spell it; keep their spelling.",
+    },
+    street: {
+        label: 'Street address',
+        dataType: 'string',
+        extraction: 'The street line of the contact\'s home or mailing address: number and street, with the unit or apartment (e.g. "1450 NE 2nd Ave, Apt 7"). Not the city, state or postal code.',
+    },
+    city: {
+        label: 'City',
+        dataType: 'string',
+        extraction: "The city of the contact's home or mailing address.",
+    },
+    state: {
+        label: 'State or province',
+        dataType: 'select',
+        extraction: "The two-letter code (FL, TX, ON) of the state or province they live in; from a city only when it is unambiguous.",
+        options: [...STATE_CODES],
+    },
+    postal_code: {
+        label: 'Postal code',
+        dataType: 'string',
+        extraction: "The ZIP code (5 digits, or ZIP+4) or Canadian postal code of the contact's home or mailing address.",
+    },
+    country: {
+        label: 'Country',
+        dataType: 'string',
+        extraction: 'ISO two-letter code (US, CA); only when they say they live outside the US.',
+    },
+    timezone: {
+        label: 'Timezone',
+        dataType: 'string',
+        extraction: 'An IANA timezone, only when they state one or a place that fixes one; never from a phone number.',
+    },
+    language: {
+        label: 'Language',
+        dataType: 'select',
+        extraction: 'The language they speak with us, when they speak or ask for one of these; the platform then speaks it.',
+        options: [...SPOKEN_LANGUAGES],
+    },
+    opted_out: {
+        label: 'Opted out',
+        dataType: 'boolean',
+        extraction: 'true when they clearly ask us to stop contacting them at all; false only when they agree to be contacted again. Not for one channel.',
+    },
+    call_opted_out: {
+        label: 'Call opted out',
+        dataType: 'boolean',
+        extraction: 'true when they clearly ask not to be called; false only when they agree to calls again.',
+    },
+    sms_opted_out: {
+        label: 'SMS opted out',
+        dataType: 'boolean',
+        extraction: 'true when they clearly ask not to be texted; false only when they agree to texts again.',
+    },
+    email_opted_out: {
+        label: 'Email opted out',
+        dataType: 'boolean',
+        extraction: 'true when they clearly ask not to be emailed; false only when they agree to emails again.',
+    },
+    contact_schedule: {
+        label: 'Contact schedule',
+        dataType: 'contact_schedule',
+        extraction: 'When they may be contacted, only when they say: the whole schedule with their change applied. Relative dates from today in their timezone; split overnight windows; do not guess an unclear time.',
+    },
+    assigned_phone_number: {
+        label: 'Assigned phone number',
+        dataType: 'phone',
+        extraction: 'Our phone number (E.164) this contact is reached from; set by the platform',
+    },
+    assigned_mailbox: {
+        label: 'Assigned mailbox',
+        dataType: 'email',
+        extraction: 'Our mailbox address this contact is emailed from; set by the platform',
+    },
+};
+/**
+ * The session's platform fields (24 §5.2): `schema/session.ts` spreads them into its fields, checked
+ * like the contact's. `stuck`: the AI marked the call stuck (its `stuck` action); the page reads it,
+ * decides what to do, and clears it.
+ */
+export const PLATFORM_SESSION_FIELDS = {
+    stuck: {
+        label: 'Stuck',
+        dataType: 'boolean',
+        extraction: 'Set by the platform when the AI marks the conversation stuck; the page clears it once handled.',
+    },
+};
+//# sourceMappingURL=platform-fields.js.map

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

@@ -0,0 +1,16 @@
+/**
+ * Ref fields (`ref: { table }`): a field whose value is another row's id (13-data-model-v1 §10.6).
+ * Writes check the value is a uuid here; whether the target row exists is checked where the ref is
+ * stored (services `syncLookupRefs`), which sees every write path and the database.
+ */
+import type { TableRef } from './schema.js';
+import type { RuntimeFieldDef, ValidationIssue } from './types.js';
+/** `parent`: the row's owner (`case_file`); `lookup`: any other ref (13-data-model-v1 §11.2). */
+export type RefKind = 'parent' | 'lookup';
+/** The kind a ref field declares (`ref.kind`); a field without a ref is not a ref. */
+export declare function refKind(field: {
+    ref?: TableRef | null;
+}): RefKind | null;
+/** A ref value must be a row id; anything else can never resolve. */
+export declare function refValueIssues(field: RuntimeFieldDef, value: unknown, path: string): ValidationIssue[];
+//# sourceMappingURL=ref.d.ts.map

package/dist/core/slot/ref.js

@@ -0,0 +1,14 @@
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** The kind a ref field declares (`ref.kind`); a field without a ref is not a ref. */
+export function refKind(field) {
+    return field.ref?.kind ?? null;
+}
+/** A ref value must be a row id; anything else can never resolve. */
+export function refValueIssues(field, value, path) {
+    if (!field.ref || value === null || value === undefined)
+        return [];
+    if (typeof value === 'string' && UUID.test(value))
+        return [];
+    return [{ code: 'ref-not-uuid', message: `${path} must be a ${field.ref.table} row id`, path }];
+}
+//# sourceMappingURL=ref.js.map

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

@@ -4,19 +4,12 @@ export type SlotRow = SingleRowTableData | MultiRowRecord;
 /** Reserved snapshot key; cannot be a company / sequence table name. */
 export declare const SNAPSHOT_CURRENT_KEY = "current";
 export declare function isReservedTableName(tableName: string): boolean;
-/** App-minted row id for jsonb-hosted tables. */
+export declare function hasBoundRow(tableName: string): boolean;
+/** App-minted row id for multi-row tables (the Record's id). */
 export declare function mintRowId(): string;
 export declare function isRowIdField(name: string): name is typeof ROW_ID_FIELD;
 export declare function isFieldValue(value: unknown): value is FieldValue;
-export declare function getRowField(row: SlotRow, fieldName: string): FieldValue | undefined;
 /** Schema fields that store envelopes — excludes row `id`. */
 export declare function slotFieldEntries<T>(fields: Record<string, T>): Array<[string, T]>;
 export declare function slotFieldNames(fields: Record<string, unknown>): string[];
-/** Envelope cells on a runtime row — excludes `id`. */
-export declare function rowValueEntries(row: SlotRow): Array<[string, FieldValue]>;
-export declare function emptySlotRow(fields: Record<string, unknown>, options?: {
-    id?: string;
-    now?: number;
-}): SingleRowTableData;
-export declare function emptyMultiRow(fields: Record<string, unknown>, id: string, now?: number): MultiRowRecord;
 //# sourceMappingURL=row.d.ts.map