@superpanel-sdk/runtime 0.2.3 → 0.5.0

package/dist/core/slot/row.js

@@ -2,11 +2,23 @@ import { emptyFieldValue } from './field.js';
 import { ROW_ID_FIELD } from './schema.js';
 /** Reserved snapshot key; cannot be a company / sequence table name. */
 export const SNAPSHOT_CURRENT_KEY = 'current';
+/**
+ * `derivedOrder` / `reverseDeps`: keys a compiled schema carried before derived fields were removed
+ * (13-data-model-v1 §21); older builds still have them, so they stay reserved and are skipped.
+ */
 const RESERVED_TABLE_NAMES = new Set([SNAPSHOT_CURRENT_KEY, 'derivedOrder', 'reverseDeps']);
 export function isReservedTableName(tableName) {
     return RESERVED_TABLE_NAMES.has(tableName);
 }
-/** App-minted row id for jsonb-hosted tables. */
+/**
+ * Multi-row tables with a bound row (the conversation's contact): a write without `rowId`
+ * goes to it. Contacts are created through `ctx.api.contact`, never inserted by a write.
+ */
+const BOUND_ROW_TABLES = new Set(['contact']);
+export function hasBoundRow(tableName) {
+    return BOUND_ROW_TABLES.has(tableName);
+}
+/** App-minted row id for multi-row tables (the Record's id). */
 export function mintRowId() {
     return crypto.randomUUID();
 }
@@ -16,12 +28,6 @@ export function isRowIdField(name) {
 export function isFieldValue(value) {
     return typeof value === 'object' && value !== null && 'state' in value && 'value' in value;
 }
-export function getRowField(row, fieldName) {
-    if (isRowIdField(fieldName))
-        return undefined;
-    const value = row[fieldName];
-    return isFieldValue(value) ? value : undefined;
-}
 /** Schema fields that store envelopes — excludes row `id`. */
 export function slotFieldEntries(fields) {
     return Object.entries(fields).filter(([name]) => !isRowIdField(name));
@@ -29,22 +35,6 @@ export function slotFieldEntries(fields) {
 export function slotFieldNames(fields) {
     return slotFieldEntries(fields).map(([name]) => name);
 }
-/** Envelope cells on a runtime row — excludes `id`. */
-export function rowValueEntries(row) {
-    const out = [];
-    for (const [name, value] of Object.entries(row)) {
-        if (isRowIdField(name) || !isFieldValue(value))
-            continue;
-        out.push([name, value]);
-    }
-    return out;
-}
-export function emptySlotRow(fields, options = {}) {
-    return fillRowFields({ id: options.id ?? '' }, fields, options.now ?? 0);
-}
-export function emptyMultiRow(fields, id, now = 0) {
-    return fillRowFields({ id }, fields, now);
-}
 function fillRowFields(row, fields, now) {
     for (const name of slotFieldNames(fields)) {
         row[name] = emptyFieldValue(now);

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

@@ -0,0 +1,16 @@
+import type { CompiledCompanyMetadata } from './schema.js';
+/**
+ * Why `after`'s company schema cannot replace `before`'s without breaking slot data stored under
+ * it; empty for an additive (01-slot-db §2.3) evolution. One pass covers the whole repo: sequence
+ * overlays only change usage. The session fields (`schema/session.ts`) follow the same rules, since
+ * `Session.data` keeps their values (11-remove-sequence-schema §3.1).
+ *
+ * Compatible: new tables (with their parent), fields (lookups included), more options, a widened
+ * type (`string` → `text`, `select` / `time` → `string`), and presentation changes (label,
+ * description, extraction, deprecated); a new field may be `unique`. Incompatible: removing a table or
+ * field (mark it `deprecated` instead); any other change of a field's dataType, `unique` added to or
+ * dropped from a field (18-record-search-index §4.5), any ref change (added, removed, retargeted, parent ↔ lookup), a parent added to a
+ * table `before` has (its stored rows have no parent edge, 13-data-model-v1 §22.5), a removed option.
+ */
+export declare function companyMetadataCompatibilityIssues(before: CompiledCompanyMetadata, after: CompiledCompanyMetadata): string[];
+//# sourceMappingURL=schema-compat.d.ts.map

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

@@ -0,0 +1,112 @@
+function formatValues(values) {
+    return values.join(', ');
+}
+/**
+ * Type changes that only widen: every stored value of `before` is a valid value of `after`
+ * (18-record-search-index §5, 27 §2.3): a short value as a long one; an option or a time of day as
+ * a short value.
+ */
+const WIDENINGS = new Set(['string>text', 'select>string', 'select>text', 'time>string', 'time>text']);
+function normalFieldIssues(path, before, after) {
+    const issues = [];
+    if (before.dataType !== after.dataType && !WIDENINGS.has(`${before.dataType}>${after.dataType}`)) {
+        issues.push(`field '${path}' dataType: ${before.dataType} → ${after.dataType}`);
+    }
+    // More options only widen; a dropped one may be stored.
+    if (before.dataType === after.dataType && before.options && after.options) {
+        const kept = new Set(after.options);
+        const removed = before.options.filter((value) => !kept.has(value));
+        if (removed.length > 0)
+            issues.push(`field '${path}' removed options: ${formatValues(removed)}`);
+    }
+    issues.push(...refIssues(path, before, after));
+    // `unique` is the field's from its first release (18-record-search-index §4.5): adding it would need
+    // stored values checked and the index marked, dropping it the marks cleared, both racing writes.
+    if (Boolean(before.unique) !== Boolean(after.unique)) {
+        issues.push(`field '${path}' unique: ${before.unique ? 'yes' : 'no'} → ${after.unique ? 'yes' : 'no'} (unique is set when a field is added; add a new field instead)`);
+    }
+    return issues;
+}
+/**
+ * What to do instead of changing a parent (13-data-model-v1 §22.5): which row a row belongs to is
+ * data, set once when the row is created, so no schema change can move or add it for stored rows.
+ */
+const PARENT_FIXED = 'a parent is fixed once released: create a new table and move the data instead';
+/**
+ * A ref only ever stays as it is (13-data-model-v1 §11.9). Adding or retargeting one invalidates
+ * stored ids. Dropping one leaves its `RecordRef` projections behind (nothing deletes them once the
+ * field is no longer a ref), blocking the target's delete. A parent and a lookup are stored apart
+ * (a lookup in the row's data, a parent only in `RecordRef`). To change a lookup, mark the field
+ * deprecated and add a new one; a parent cannot change at all (§22.5).
+ */
+function refIssues(path, before, after) {
+    if (!before.ref && !after.ref)
+        return [];
+    const parentInvolved = before.ref?.kind === 'parent' || after.ref?.kind === 'parent';
+    const instead = parentInvolved ? PARENT_FIXED : 'mark it deprecated instead';
+    if (!after.ref)
+        return [`field '${path}' ref to ${before.ref.table} was removed (${instead})`];
+    if (after.ref.table !== before.ref?.table) {
+        return [`field '${path}' ref: ${before.ref?.table ?? 'none'} → ${after.ref.table}${parentInvolved ? ` (${PARENT_FIXED})` : ''}`];
+    }
+    if (after.ref.kind !== before.ref.kind) {
+        return [`field '${path}' ref kind: ${before.ref.kind} → ${after.ref.kind}${parentInvolved ? ` (${PARENT_FIXED})` : ''}`];
+    }
+    return [];
+}
+function fieldIssues(path, before, after) {
+    return normalFieldIssues(path, before, after);
+}
+/** A session field has no ref: the rest of a company field's rules. */
+function sessionFieldIssues(path, before, after) {
+    return normalFieldIssues(path, before, after);
+}
+/**
+ * Why `after`'s company schema cannot replace `before`'s without breaking slot data stored under
+ * it; empty for an additive (01-slot-db §2.3) evolution. One pass covers the whole repo: sequence
+ * overlays only change usage. The session fields (`schema/session.ts`) follow the same rules, since
+ * `Session.data` keeps their values (11-remove-sequence-schema §3.1).
+ *
+ * Compatible: new tables (with their parent), fields (lookups included), more options, a widened
+ * type (`string` → `text`, `select` / `time` → `string`), and presentation changes (label,
+ * description, extraction, deprecated); a new field may be `unique`. Incompatible: removing a table or
+ * field (mark it `deprecated` instead); any other change of a field's dataType, `unique` added to or
+ * dropped from a field (18-record-search-index §4.5), any ref change (added, removed, retargeted, parent ↔ lookup), a parent added to a
+ * table `before` has (its stored rows have no parent edge, 13-data-model-v1 §22.5), a removed option.
+ */
+export function companyMetadataCompatibilityIssues(before, after) {
+    const issues = [];
+    for (const [tableName, beforeTable] of Object.entries(before.tables)) {
+        const afterTable = after.tables[tableName];
+        if (!afterTable) {
+            issues.push(`table '${tableName}' was removed`);
+            continue;
+        }
+        for (const [fieldName, beforeField] of Object.entries(beforeTable.fields)) {
+            const path = `${tableName}.${fieldName}`;
+            const afterField = afterTable.fields[fieldName];
+            if (!afterField) {
+                const instead = beforeField.ref?.kind === 'parent' ? PARENT_FIXED : 'mark it deprecated instead';
+                issues.push(`field '${path}' was removed (${instead})`);
+                continue;
+            }
+            issues.push(...fieldIssues(path, beforeField, afterField));
+        }
+        for (const [fieldName, afterField] of Object.entries(afterTable.fields)) {
+            if (fieldName in beforeTable.fields || afterField.ref?.kind !== 'parent')
+                continue;
+            issues.push(`table '${tableName}' gained a parent '${fieldName}': its stored rows have none (${PARENT_FIXED})`);
+        }
+    }
+    for (const [fieldName, beforeField] of Object.entries(before.session.fields)) {
+        const path = `session.${fieldName}`;
+        const afterField = after.session.fields[fieldName];
+        if (!afterField) {
+            issues.push(`field '${path}' was removed (mark it deprecated instead)`);
+            continue;
+        }
+        issues.push(...sessionFieldIssues(path, beforeField, afterField));
+    }
+    return issues;
+}
+//# sourceMappingURL=schema-compat.js.map