zitejs 0.9.110 → 0.9.112

package/dist/cjs/backend/index.d.ts

@@ -61,7 +61,13 @@ export type ZiteStreamInterface = {
 export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream extends boolean = false, TSchedule extends ZiteSchedule | undefined = undefined, TWebhook extends ZiteWebhook | undefined = undefined, TRawInput = TInput> {
     description?: string;
     inputSchema?: SchemaLike<TInput, TRawInput>;
-    outputSchema?: SchemaLike<TOutput>;
+    /**
+     * Documentation only — never validated, and `unknown` so it cannot compete
+     * with `execute` for `TOutput`. A nullable column reads as `T | undefined`
+     * while its schema says `.nullable()`; making both inference sites failed the
+     * build on the difference.
+     */
+    outputSchema?: SchemaLike<unknown>;
     stream?: TStream;
     authenticated?: boolean;
     /**

package/dist/cjs/sync/lib.d.ts

@@ -1,5 +1,6 @@
 import type { PublicFieldDefinition } from "../types/fields.js";
 import type { Database } from "../types/tables.js";
+import { type SdkNameRename } from "./sdkNames.js";
 export type ZiteSchemaField = {
     id: string;
     sdkName: string;
@@ -8,6 +9,7 @@ export type ZiteSchemaField = {
 export type ZiteSchemaTable = {
     id: string;
     sdkName: string;
+    name?: string;
     primaryFieldId?: string;
     fields: ZiteSchemaField[];
 };
@@ -44,6 +46,7 @@ export type AirtableLockField = {
 export type AirtableLockTable = {
     id: string;
     sdkName: string;
+    name?: string;
     primaryFieldId: string;
     fields: AirtableLockField[];
 };
@@ -51,7 +54,33 @@ export type AirtableLock = {
     integrationId: string;
     tables: AirtableLockTable[];
 };
-export declare function generateAirtableTs(lock: AirtableLock): string | null;
+/**
+ * Make every table sdkName in the lock unique, so a duplicated lock can't emit
+ * a file that cannot compile (TS2300/TS2451) and that no app can edit or
+ * exclude.
+ *
+ * A contested name goes to NOBODY. The lock cannot say which table app code
+ * meant, and lock order is no oracle: a rename leaves the original owner
+ * first, while reordering or multi-base flattening can put the newcomer
+ * first. Guessing wrong would keep stale references compiling against the
+ * other table's data (the client is addressed by `tableId`, so the binding
+ * follows whichever table holds the name). With the bare name gone, a stale
+ * reference fails as an unresolved import instead: visible and fixable.
+ *
+ * Field sdkNames are left untouched. They are wire keys, resolved by the
+ * server from stored nameMappings that a generate-time rename can never
+ * update, so a renamed field would type-check yet read `undefined` and fail
+ * every write. Unlike tables, duplicates cannot form there: the producer
+ * seeds field allocation from the stored mappings.
+ *
+ * Names are assigned in declaration order, so an unchanged lock regenerates
+ * the identical file.
+ */
+export declare function normalizeAirtableLockNames(lock: AirtableLock): {
+    lock: AirtableLock;
+    renames: SdkNameRename[];
+};
+export declare function generateAirtableTs(inputLock: AirtableLock): string | null;
 export declare function generateBackendWrapperTs(envVarNames?: string[]): string;
 /**
  * Generate `.zite/integrations/email.ts` — the `Email` client for an app with

package/dist/cjs/sync/lib.js

@@ -4,6 +4,7 @@ exports.toSdkName = exports.toCamelCase = exports.toPascalCase = void 0;
 exports.generateSchema = generateSchema;
 exports.generateDbTs = generateDbTs;
 exports.generateApiTs = generateApiTs;
+exports.normalizeAirtableLockNames = normalizeAirtableLockNames;
 exports.generateAirtableTs = generateAirtableTs;
 exports.generateBackendWrapperTs = generateBackendWrapperTs;
 exports.generateEmailSdk = generateEmailSdk;
@@ -267,9 +268,12 @@ function fieldJsdoc(schemaField, table, schema) {
         const tpl = def.template;
         if (tpl.tableId) {
             // The SDK name, not the raw `tbl...` id — the id appears nowhere the
-            // reader can act on, while the SDK name is the property on `zite`.
+            // reader can act on, while the SDK name is the property on `zite`. Its
+            // display name rides along, since after a rename the two differ.
             const linked = schema?.tables.find((t) => t.id === tpl.tableId);
-            parts.push(`Links to ${linked ? linked.sdkName : tpl.tableId}`);
+            parts.push(linked
+                ? `Links to ${linked.sdkName}${linked.name ? ` ("${linked.name}")` : ""}`
+                : `Links to ${tpl.tableId}`);
         }
         if (tpl.allowMultiple === false)
             parts.push("Single record only");
@@ -382,6 +386,10 @@ function generateSchema(database, existingSchema) {
             table: {
                 id: table.id,
                 sdkName: "",
+                // Always the live name — never `existingTable?.name`. Locking it the way
+                // `sdkName` is locked would freeze it at the first name the table ever
+                // had, which is the one thing this is here to avoid.
+                name: table.name,
                 primaryFieldId: table.primaryFieldId,
                 fields: [],
             },
@@ -440,6 +448,13 @@ function buildLinkTableComments(schema) {
     const tablesById = new Map();
     for (const t of schema.tables)
         tablesById.set(t.id, t);
+    // The link name itself is a literal SQL identifier ("use these exact names"),
+    // so it stays sdkName-derived; the display names ride alongside as a gloss.
+    const displayByPascal = new Map();
+    for (const t of schema.tables) {
+        if (t.name)
+            displayByPascal.set((0, sdkNames_js_1.toPascalCase)(t.sdkName), t.name);
+    }
     const seen = new Set();
     const entries = [];
     for (const table of schema.tables) {
@@ -469,7 +484,15 @@ function buildLinkTableComments(schema) {
             const col2 = isSelf
                 ? `target${second}Id`
                 : `${second.charAt(0).toLowerCase()}${second.slice(1)}Id`;
-            entries.push({ name: linkName, cols: [col1, col2] });
+            const firstName = displayByPascal.get(first);
+            const secondName = displayByPascal.get(second);
+            entries.push({
+                name: linkName,
+                cols: [col1, col2],
+                gloss: firstName && secondName
+                    ? `joins "${firstName}" and "${secondName}"`
+                    : undefined,
+            });
         }
     }
     if (entries.length === 0)
@@ -479,7 +502,8 @@ function buildLinkTableComments(schema) {
         "// Link tables for zite.sql() JOINs (use these exact names):",
     ];
     for (const e of entries) {
-        lines.push(`//   "${commentSafe(e.name)}" — columns: "${commentSafe(e.cols[0])}", "${commentSafe(e.cols[1])}"`);
+        lines.push(`//   "${commentSafe(e.name)}" — columns: "${commentSafe(e.cols[0])}", "${commentSafe(e.cols[1])}"` +
+            (e.gloss ? ` (${commentSafe(e.gloss)})` : ""));
     }
     return lines;
 }
@@ -566,7 +590,12 @@ function generateDbTs(inputSchema) {
     for (const table of tables) {
         const className = (0, sdkNames_js_1.toPascalCase)(table.sdkName);
         const recordType = `${className}RecordType`;
-        lines.push(`/** A ${table.sdkName} record as it is read back. */`);
+        // A schema written before `name` existed keeps the old wording exactly —
+        // sandbox boot regenerates unconditionally, so any drift here would show up
+        // as an unexplained diff in every project's next commit.
+        lines.push(table.name
+            ? `/** A record in the "${commentSafe(table.name)}" table, as it is read back. */`
+            : `/** A ${table.sdkName} record as it is read back. */`);
         lines.push(`export type ${recordType} = {`);
         lines.push("  id: string;");
         for (const field of table.fields) {
@@ -590,7 +619,9 @@ function generateDbTs(inputSchema) {
         // input than they store (an attachments field takes a URL string; a linked
         // record takes one id or many).
         const writableFields = table.fields.filter((f) => f.sdkName !== "id" && !READ_ONLY_FIELD_TYPES.has(f.definition.type));
-        lines.push(`/** What you may write when creating or updating a ${table.sdkName}. */`);
+        lines.push(table.name
+            ? `/** What you may write when creating or updating a record in the "${commentSafe(table.name)}" table. */`
+            : `/** What you may write when creating or updating a ${table.sdkName}. */`);
         lines.push(`export type ${className}RecordInput = {`);
         for (const field of writableFields) {
             lines.push(`  ${field.sdkName}: ${tsTypeForSchemaField(field.definition, "write")};`);
@@ -602,7 +633,8 @@ function generateDbTs(inputSchema) {
     lines.push("export const zite = {");
     for (const table of tables) {
         const className = (0, sdkNames_js_1.toPascalCase)(table.sdkName);
-        lines.push(`  ${table.sdkName}: createTableClient<${className}RecordType, ${className}RecordInput>('${className}'),`);
+        lines.push(`  ${table.sdkName}: createTableClient<${className}RecordType, ${className}RecordInput>('${className}'),` +
+            (table.name ? ` // "${commentSafe(table.name)}"` : ""));
     }
     lines.push(`  sql: createSqlClient(),`);
     // No `notifications` here: it is a platform primitive, not something backed
@@ -1001,7 +1033,9 @@ function airtableFieldJsdoc(field, table, lock) {
         const linkedTableId = field.config?.linkedTableId;
         if (linkedTableId) {
             const linked = lock?.tables.find((t) => t.id === linkedTableId);
-            parts.push(`Links to ${linked ? linked.sdkName : linkedTableId}`);
+            parts.push(linked
+                ? `Links to ${linked.sdkName}${linked.name ? ` ("${linked.name}")` : ""}`
+                : `Links to ${linkedTableId}`);
         }
         if (field.config?.prefersSingleRecordLink)
             parts.push("Single record only");
@@ -1054,9 +1088,71 @@ function airtableFieldJsdoc(field, table, lock) {
         return undefined;
     return parts.join(". ");
 }
-function generateAirtableTs(lock) {
-    if (lock.tables.length === 0)
+// A table client is a `const`, so only value-space bindings can collide with
+// one. `AirtableAttachment` is a type, and types and consts coexist.
+const RESERVED_AIRTABLE_NAMES = ["createAirtableClient"];
+/**
+ * Make every table sdkName in the lock unique, so a duplicated lock can't emit
+ * a file that cannot compile (TS2300/TS2451) and that no app can edit or
+ * exclude.
+ *
+ * A contested name goes to NOBODY. The lock cannot say which table app code
+ * meant, and lock order is no oracle: a rename leaves the original owner
+ * first, while reordering or multi-base flattening can put the newcomer
+ * first. Guessing wrong would keep stale references compiling against the
+ * other table's data (the client is addressed by `tableId`, so the binding
+ * follows whichever table holds the name). With the bare name gone, a stale
+ * reference fails as an unresolved import instead: visible and fixable.
+ *
+ * Field sdkNames are left untouched. They are wire keys, resolved by the
+ * server from stored nameMappings that a generate-time rename can never
+ * update, so a renamed field would type-check yet read `undefined` and fail
+ * every write. Unlike tables, duplicates cannot form there: the producer
+ * seeds field allocation from the stored mappings.
+ *
+ * Names are assigned in declaration order, so an unchanged lock regenerates
+ * the identical file.
+ */
+function normalizeAirtableLockNames(lock) {
+    const owners = new Map();
+    for (const table of lock.tables) {
+        owners.set(table.sdkName, (owners.get(table.sdkName) ?? 0) + 1);
+    }
+    const contested = [...owners.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([name]) => name);
+    const tableNames = new sdkNames_js_1.SdkNameAllocator({
+        reserved: [...RESERVED_AIRTABLE_NAMES, ...contested],
+    });
+    // Sole owners claim their names before any contender is suffixed, so a
+    // contender can never displace a table legitimately named `GroupCalls2`.
+    const kept = lock.tables.map((table) => owners.get(table.sdkName) === 1 && tableNames.available(table.sdkName)
+        ? tableNames.allocate(table.sdkName)
+        : undefined);
+    const renames = [];
+    const tables = lock.tables.map((table, i) => {
+        const sdkName = kept[i] ?? tableNames.allocate(table.sdkName);
+        if (sdkName !== table.sdkName) {
+            renames.push({
+                kind: "table",
+                tableId: table.id,
+                from: table.sdkName,
+                to: sdkName,
+            });
+        }
+        return { ...table, sdkName };
+    });
+    return { lock: { ...lock, tables }, renames };
+}
+function generateAirtableTs(inputLock) {
+    if (inputLock.tables.length === 0)
         return null;
+    const { lock, renames } = normalizeAirtableLockNames(inputLock);
+    if (renames.length > 0) {
+        for (const line of (0, sdkNames_js_1.describeRenames)(renames)) {
+            console.warn(`[zitejs] SDK name conflict in zite.lock; the generated Airtable SDK uses: ${line}`);
+        }
+    }
     const lines = [
         "// Auto-generated by zitejs generate from zite.lock. Do not edit manually.",
         "// Airtable SDK — uses createAirtableClient from zitejs/runtime.",
@@ -1097,7 +1193,9 @@ function generateAirtableTs(lock) {
     lines.push(...AIRTABLE_ATTACHMENT_TYPE);
     for (const table of lock.tables) {
         const recordType = `${table.sdkName}RecordType`;
-        lines.push(`/** A ${commentSafe(table.sdkName)} record as it is read back. */`);
+        lines.push(table.name
+            ? `/** A record in the "${commentSafe(table.name)}" table, as it is read back. */`
+            : `/** A ${commentSafe(table.sdkName)} record as it is read back. */`);
         lines.push(`export type ${recordType} = {`);
         lines.push("  id: string;");
         for (const field of table.fields) {
@@ -1119,7 +1217,9 @@ function generateAirtableTs(lock) {
         // Read-only fields are omitted rather than typed: Airtable rejects a write
         // to a formula, rollup, lookup or autonumber with a 422.
         const writableFields = table.fields.filter((f) => f.sdkName !== "id" && !READ_ONLY_AIRTABLE_FIELDS.has(f.type));
-        lines.push(`/** What you may write when creating or updating a ${commentSafe(table.sdkName)}. */`);
+        lines.push(table.name
+            ? `/** What you may write when creating or updating a record in the "${commentSafe(table.name)}" table. */`
+            : `/** What you may write when creating or updating a ${commentSafe(table.sdkName)}. */`);
         lines.push(`export type ${table.sdkName}RecordInput = {`);
         for (const field of writableFields) {
             lines.push(`  ${field.sdkName}: ${airtableTsType(field, lock, 0, "write")};`);
@@ -1129,7 +1229,8 @@ function generateAirtableTs(lock) {
         lines.push(`export const ${table.sdkName} = createAirtableClient<${recordType}, ${table.sdkName}RecordInput>(`);
         lines.push(`  '${lock.integrationId}',`);
         lines.push(`  '${table.sdkName}',`);
-        lines.push(`  { tableId: '${table.id}' },`);
+        lines.push(`  { tableId: '${table.id}' },` +
+            (table.name ? ` // "${commentSafe(table.name)}"` : ""));
         lines.push(`);`);
         lines.push("");
     }
@@ -1225,7 +1326,9 @@ function generateBackendWrapperTs(envVarNames = []) {
         "export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream extends boolean = false, TSchedule extends ZiteSchedule | undefined = undefined, TWebhook extends ZiteWebhook | undefined = undefined, TRawInput = TInput> {",
         "  description?: string;",
         "  inputSchema?: SchemaLike<TInput, TRawInput>;",
-        "  outputSchema?: SchemaLike<TOutput>;",
+        // Apps compile against this copy, not the base module's.
+        "  /** Documentation only. Never validated, and not an inference site for TOutput. */",
+        "  outputSchema?: SchemaLike<unknown>;",
         "  stream?: TStream;",
         "  authenticated?: boolean;",
         "  /** When set, the endpoint also fires on this cron schedule. It stays request-callable — declaring one widens `context`, so `context.user` must be null-checked. */",

package/dist/cjs/sync/lib.test.js

@@ -51,6 +51,173 @@ const schemaWithSelectOption = (label) => ({
         (0, vitest_1.expect)(out).toContain('"The \\"Premium\\" tier"');
     });
 });
+/** TS2300/TS2451, which `syntaxErrorsIn` can't see — a duplicate export parses fine. */
+const duplicateIdentifierErrorsIn = (source) => {
+    const AMBIENT = `declare module 'zitejs/runtime' {
+    export function createAirtableClient<T, TInput = T>(
+      integrationId: string,
+      className: string,
+      implicitParams: Record<string, unknown>,
+    ): unknown;
+  }`;
+    const sources = {
+        'ambient.d.ts': AMBIENT,
+        'airtable.ts': source,
+    };
+    const host = typescript_1.default.createCompilerHost({});
+    const original = host.getSourceFile.bind(host);
+    host.getSourceFile = (fileName, langVersion, onError, shouldCreate) => sources[fileName] !== undefined
+        ? typescript_1.default.createSourceFile(fileName, sources[fileName], langVersion, true)
+        : original(fileName, langVersion, onError, shouldCreate);
+    host.fileExists = f => sources[f] !== undefined || typescript_1.default.sys.fileExists(f);
+    host.readFile = f => sources[f] ?? typescript_1.default.sys.readFile(f);
+    const program = typescript_1.default.createProgram(Object.keys(sources), { strict: true, noEmit: true, skipLibCheck: true }, host);
+    return typescript_1.default
+        .getPreEmitDiagnostics(program)
+        .filter(d => d.code === 2300 || d.code === 2451)
+        .map(d => typescript_1.default.flattenDiagnosticMessageText(d.messageText, ' '));
+};
+(0, vitest_1.describe)('generateAirtableTs duplicate SDK names', () => {
+    // ZIT-5032: two tables both resolved to `GroupCalls`.
+    const collidingLock = (name) => ({
+        integrationId: 'airtable',
+        tables: [
+            {
+                id: 'tblV204b5ogVasPKc',
+                sdkName: name,
+                primaryFieldId: 'fld1',
+                fields: [
+                    { id: 'fld1', sdkName: 'title', type: 'singleLineText', name: 'Title' },
+                ],
+            },
+            {
+                id: 'tblt474V0WyNlrHX9',
+                sdkName: name,
+                primaryFieldId: 'fld2',
+                fields: [
+                    { id: 'fld2', sdkName: 'title', type: 'singleLineText', name: 'Title' },
+                ],
+            },
+        ],
+    });
+    (0, vitest_1.it)('compiles when two tables resolve to the same SDK name', () => {
+        (0, vitest_1.expect)(duplicateIdentifierErrorsIn((0, lib_js_1.generateAirtableTs)(collidingLock('GroupCalls')) ?? '')).toEqual([]);
+    });
+    // Lock order cannot say which table originally owned the name, and handing
+    // it to the wrong one would leave stale references compiling against the
+    // other table's data. Suffixing every contender turns them into unresolved
+    // imports instead.
+    (0, vitest_1.it)('gives a contested name to neither table', () => {
+        const out = (0, lib_js_1.generateAirtableTs)(collidingLock('GroupCalls')) ?? '';
+        (0, vitest_1.expect)(out).not.toContain('export const GroupCalls = ');
+        (0, vitest_1.expect)(out).toContain('export const GroupCalls2 = ');
+        (0, vitest_1.expect)(out).toContain('export const GroupCalls3 = ');
+    });
+    (0, vitest_1.it)('still addresses each table by its own id, so data access is unchanged', () => {
+        const out = (0, lib_js_1.generateAirtableTs)(collidingLock('GroupCalls')) ?? '';
+        (0, vitest_1.expect)(out).toContain("'GroupCalls2',\n  { tableId: 'tblV204b5ogVasPKc' }");
+        (0, vitest_1.expect)(out).toContain("'GroupCalls3',\n  { tableId: 'tblt474V0WyNlrHX9' }");
+    });
+    (0, vitest_1.it)('never displaces the legitimate owner of a suffixed name', () => {
+        const table = (id, sdkName) => ({
+            id,
+            sdkName,
+            primaryFieldId: 'fld1',
+            fields: [
+                { id: 'fld1', sdkName: 'title', type: 'singleLineText', name: 'Title' },
+            ],
+        });
+        const out = (0, lib_js_1.generateAirtableTs)({
+            integrationId: 'airtable',
+            tables: [
+                table('tblA', 'GroupCalls'),
+                table('tblB', 'GroupCalls'),
+                table('tblC', 'GroupCalls2'),
+            ],
+        }) ?? '';
+        (0, vitest_1.expect)(out).toContain("'GroupCalls2',\n  { tableId: 'tblC' }");
+        (0, vitest_1.expect)(out).toContain('export const GroupCalls3 = ');
+        (0, vitest_1.expect)(out).toContain('export const GroupCalls4 = ');
+        (0, vitest_1.expect)(out).not.toContain('export const GroupCalls = ');
+        (0, vitest_1.expect)(duplicateIdentifierErrorsIn(out)).toEqual([]);
+    });
+    (0, vitest_1.it)('does not rename anything when names are already unique', () => {
+        const out = (0, lib_js_1.generateAirtableTs)({
+            integrationId: 'airtable',
+            tables: [
+                {
+                    id: 'tbl1',
+                    sdkName: 'Calls',
+                    primaryFieldId: 'fld1',
+                    fields: [
+                        { id: 'fld1', sdkName: 'title', type: 'singleLineText', name: 'Title' },
+                    ],
+                },
+            ],
+        }) ?? '';
+        (0, vitest_1.expect)(out).toContain('export const Calls = ');
+        (0, vitest_1.expect)(out).not.toContain('Calls2');
+    });
+    // A field's sdkName is a wire key: the server resolves it from the stored
+    // nameMappings, which a generate-time rename can never update. A renamed
+    // field would type-check yet read `undefined` and fail every write, so
+    // fields are never renamed here.
+    (0, vitest_1.it)('leaves field names alone, even when they collide', () => {
+        const out = (0, lib_js_1.generateAirtableTs)({
+            integrationId: 'airtable',
+            tables: [
+                {
+                    id: 'tbl1',
+                    sdkName: 'Calls',
+                    primaryFieldId: 'fldA',
+                    fields: [
+                        { id: 'fldA', sdkName: 'notes', type: 'singleLineText', name: 'Notes' },
+                        { id: 'fldB', sdkName: 'notes', type: 'singleLineText', name: 'Notes copy' },
+                    ],
+                },
+            ],
+        }) ?? '';
+        (0, vitest_1.expect)(out).not.toContain('notes2');
+    });
+    (0, vitest_1.it)('still skips a field named `id` instead of renaming it', () => {
+        const out = (0, lib_js_1.generateAirtableTs)({
+            integrationId: 'airtable',
+            tables: [
+                {
+                    id: 'tbl1',
+                    sdkName: 'Calls',
+                    primaryFieldId: 'fldA',
+                    fields: [
+                        { id: 'fldA', sdkName: 'id', type: 'singleLineText', name: 'ID' },
+                        { id: 'fldB', sdkName: 'title', type: 'singleLineText', name: 'Title' },
+                    ],
+                },
+            ],
+        }) ?? '';
+        (0, vitest_1.expect)(out).not.toContain('id2');
+        (0, vitest_1.expect)(out).not.toContain('id?:');
+        // the record id, emitted by hand, stays the only `id`
+        (0, vitest_1.expect)(out).toContain('id: string;');
+    });
+    (0, vitest_1.it)('leaves a table named after the attachment type alone', () => {
+        const out = (0, lib_js_1.generateAirtableTs)({
+            integrationId: 'airtable',
+            tables: [
+                {
+                    id: 'tbl1',
+                    sdkName: 'AirtableAttachment',
+                    primaryFieldId: 'fld1',
+                    fields: [
+                        { id: 'fld1', sdkName: 'title', type: 'singleLineText', name: 'Title' },
+                    ],
+                },
+            ],
+        }) ?? '';
+        (0, vitest_1.expect)(duplicateIdentifierErrorsIn(out)).toEqual([]);
+        (0, vitest_1.expect)(out).toContain('export const AirtableAttachment = ');
+        (0, vitest_1.expect)(out).not.toContain('AirtableAttachment2');
+    });
+});
 (0, vitest_1.describe)('generateAirtableTs attachment type', () => {
     const lockWithAttachment = {
         integrationId: 'airtable',
@@ -115,6 +282,56 @@ const schemaWithSelectOption = (label) => ({
         (0, vitest_1.expect)(syntaxErrorsIn((0, lib_js_1.generateDbTs)(schemaWithFieldNamed(name)))).toEqual([]);
     });
 });
+(0, vitest_1.describe)('generateDbTs table names in comments', () => {
+    const schemaWithTableNamed = (name) => ({
+        tables: [
+            {
+                id: 'tbl1',
+                sdkName: 'table1',
+                ...(name === undefined ? {} : { name }),
+                primaryFieldId: 'fld1',
+                fields: [
+                    {
+                        id: 'fld1',
+                        sdkName: 'slot',
+                        definition: {
+                            type: 'single_line_text',
+                            name: 'Slot',
+                            template: {},
+                        },
+                    },
+                ],
+            },
+        ],
+    });
+    // The whole point: `sdkName` is locked to the table's id, so after a rename
+    // `table1` is the only thing a reader sees. The display name is what says
+    // which table that is.
+    (0, vitest_1.it)('names the table beside its locked sdkName', () => {
+        const out = (0, lib_js_1.generateDbTs)(schemaWithTableNamed('Time Slots'));
+        (0, vitest_1.expect)(out).toContain('/** A record in the "Time Slots" table, as it is read back. */');
+        (0, vitest_1.expect)(out).toContain('/** What you may write when creating or updating a record in the "Time Slots" table. */');
+        (0, vitest_1.expect)(out).toContain(`table1: createTableClient<Table1RecordType, Table1RecordInput>('Table1'), // "Time Slots"`);
+    });
+    // Sandbox boot regenerates unconditionally against the committed schema, so a
+    // schema written before `name` existed has to keep producing what it did
+    // before — otherwise every project's next commit carries an unexplained diff.
+    (0, vitest_1.it)('emits the pre-name wording when the schema carries no name', () => {
+        const out = (0, lib_js_1.generateDbTs)(schemaWithTableNamed(undefined));
+        (0, vitest_1.expect)(out).toContain('/** A table1 record as it is read back. */');
+        (0, vitest_1.expect)(out).toContain('/** What you may write when creating or updating a table1. */');
+        (0, vitest_1.expect)(out).toContain(`('Table1'),\n`);
+        (0, vitest_1.expect)(out).not.toContain('" table, as it is read back');
+    });
+    // Same hazard as a field name, one level up: a table's display name is user
+    // text and now reaches a JSDoc.
+    vitest_1.it.each([
+        ['a comment-close sequence', 'Slots */ console.log(1); /*'],
+        ['a newline', 'Time\nSlots'],
+    ])('emits parseable TypeScript for a table named with %s', (_what, name) => {
+        (0, vitest_1.expect)(syntaxErrorsIn((0, lib_js_1.generateDbTs)(schemaWithTableNamed(name)))).toEqual([]);
+    });
+});
 (0, vitest_1.describe)('generateApiTs endpoint file names', () => {
     // An endpoint filename is the LLM's raw `writeFile` path argument — nothing
     // validates its characters — and it lands in an import specifier, a comment

package/dist/cjs/sync/sdkNames.d.ts

@@ -66,6 +66,33 @@ export interface SdkNameRename {
     from: string;
     to: string;
 }
+/**
+ * Unique identifiers within one namespace.
+ *
+ * `derive` names the extra keys an allocation also occupies. A table needs it:
+ * its sdkName becomes both a property on `zite` and, PascalCased, a pair of
+ * exported type declarations, so `orders` and `Orders` are distinct accessors
+ * that would emit `OrdersRecordType` twice.
+ */
+export declare class SdkNameAllocator {
+    private readonly taken;
+    private readonly reserved;
+    private readonly derive;
+    constructor(opts?: {
+        reserved?: readonly string[];
+        derive?: (name: string) => string[];
+    });
+    private keysFor;
+    private isFree;
+    /** Free right now, without claiming it. */
+    available(name: string): boolean;
+    private claim;
+    /**
+     * `name`, or the first `name2`, `name3`… that is free. Suffixes start at 2
+     * because that is what the name means: the second table called Notifications.
+     */
+    allocate(preferred: string): string;
+}
 /**
  * Existing sdkNames are preserved across syncs so user code keeps compiling,
  * but a schema written before the sanitizer stripped trailing symbols can carry

package/dist/cjs/sync/sdkNames.js

@@ -22,7 +22,7 @@
  * cannot compile.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RESERVED_FIELD_ACCESSORS = exports.RESERVED_IDENTIFIERS = exports.RESERVED_TABLE_ACCESSORS = void 0;
+exports.SdkNameAllocator = exports.RESERVED_FIELD_ACCESSORS = exports.RESERVED_IDENTIFIERS = exports.RESERVED_TABLE_ACCESSORS = void 0;
 exports.toPascalCase = toPascalCase;
 exports.toCamelCase = toCamelCase;
 exports.toSdkName = toSdkName;
@@ -146,6 +146,7 @@ class SdkNameAllocator {
         throw new Error(`Could not allocate a unique SDK name for "${preferred}" after ${MAX_SUFFIX_ATTEMPTS} attempts`);
     }
 }
+exports.SdkNameAllocator = SdkNameAllocator;
 /**
  * Existing sdkNames are preserved across syncs so user code keeps compiling,
  * but a schema written before the sanitizer stripped trailing symbols can carry

package/dist/cjs/sync/sdkNames.test.js

@@ -207,3 +207,31 @@ const recordTypeKeys = (source, typeName) => {
         (0, vitest_1.expect)(keys).toContain("sql2");
     });
 });
+(0, vitest_1.describe)("table display names", () => {
+    // `sdkName` is locked to the id so user code keeps compiling; `name` is the
+    // opposite and must always take the live value. Locking it too — the easy
+    // mistake, since the line above it does exactly that — freezes it at the
+    // table's first name and defeats the point.
+    (0, vitest_1.it)("follows a rename while the sdkName stays locked", () => {
+        const first = (0, lib_js_1.generateSchema)(database([{ id: "tbl_1", name: "Slots", fields: [field("fld_1", "At")] }]));
+        (0, vitest_1.expect)(first.tables[0].sdkName).toBe("slots");
+        (0, vitest_1.expect)(first.tables[0].name).toBe("Slots");
+        const renamed = (0, lib_js_1.generateSchema)(database([
+            { id: "tbl_1", name: "Time Slots", fields: [field("fld_1", "At")] },
+        ]), first);
+        (0, vitest_1.expect)(renamed.tables[0].sdkName).toBe("slots");
+        (0, vitest_1.expect)(renamed.tables[0].name).toBe("Time Slots");
+        (0, vitest_1.expect)((0, lib_js_1.generateDbTs)(renamed)).toContain('/** A record in the "Time Slots" table, as it is read back. */');
+    });
+    // `buildLegacySchemaSeed` (restly, migration) builds a seed carrying only
+    // `sdkName`. Reading `name` off the seed would emit `undefined` for every
+    // table on every newly migrated project.
+    (0, vitest_1.it)("takes the live name even when the seed has none", () => {
+        const seed = {
+            tables: [{ id: "tbl_1", sdkName: "salesDeals", fields: [] }],
+        };
+        const schema = (0, lib_js_1.generateSchema)(database([{ id: "tbl_1", name: "Deals", fields: [] }]), seed);
+        (0, vitest_1.expect)(schema.tables[0].sdkName).toBe("salesDeals");
+        (0, vitest_1.expect)(schema.tables[0].name).toBe("Deals");
+    });
+});

package/dist/esm/backend/index.d.ts

@@ -61,7 +61,13 @@ export type ZiteStreamInterface = {
 export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream extends boolean = false, TSchedule extends ZiteSchedule | undefined = undefined, TWebhook extends ZiteWebhook | undefined = undefined, TRawInput = TInput> {
     description?: string;
     inputSchema?: SchemaLike<TInput, TRawInput>;
-    outputSchema?: SchemaLike<TOutput>;
+    /**
+     * Documentation only — never validated, and `unknown` so it cannot compete
+     * with `execute` for `TOutput`. A nullable column reads as `T | undefined`
+     * while its schema says `.nullable()`; making both inference sites failed the
+     * build on the difference.
+     */
+    outputSchema?: SchemaLike<unknown>;
     stream?: TStream;
     authenticated?: boolean;
     /**

package/dist/esm/sync/lib.d.ts

@@ -1,5 +1,6 @@
 import type { PublicFieldDefinition } from "../types/fields.js";
 import type { Database } from "../types/tables.js";
+import { type SdkNameRename } from "./sdkNames.js";
 export type ZiteSchemaField = {
     id: string;
     sdkName: string;
@@ -8,6 +9,7 @@ export type ZiteSchemaField = {
 export type ZiteSchemaTable = {
     id: string;
     sdkName: string;
+    name?: string;
     primaryFieldId?: string;
     fields: ZiteSchemaField[];
 };
@@ -44,6 +46,7 @@ export type AirtableLockField = {
 export type AirtableLockTable = {
     id: string;
     sdkName: string;
+    name?: string;
     primaryFieldId: string;
     fields: AirtableLockField[];
 };
@@ -51,7 +54,33 @@ export type AirtableLock = {
     integrationId: string;
     tables: AirtableLockTable[];
 };
-export declare function generateAirtableTs(lock: AirtableLock): string | null;
+/**
+ * Make every table sdkName in the lock unique, so a duplicated lock can't emit
+ * a file that cannot compile (TS2300/TS2451) and that no app can edit or
+ * exclude.
+ *
+ * A contested name goes to NOBODY. The lock cannot say which table app code
+ * meant, and lock order is no oracle: a rename leaves the original owner
+ * first, while reordering or multi-base flattening can put the newcomer
+ * first. Guessing wrong would keep stale references compiling against the
+ * other table's data (the client is addressed by `tableId`, so the binding
+ * follows whichever table holds the name). With the bare name gone, a stale
+ * reference fails as an unresolved import instead: visible and fixable.
+ *
+ * Field sdkNames are left untouched. They are wire keys, resolved by the
+ * server from stored nameMappings that a generate-time rename can never
+ * update, so a renamed field would type-check yet read `undefined` and fail
+ * every write. Unlike tables, duplicates cannot form there: the producer
+ * seeds field allocation from the stored mappings.
+ *
+ * Names are assigned in declaration order, so an unchanged lock regenerates
+ * the identical file.
+ */
+export declare function normalizeAirtableLockNames(lock: AirtableLock): {
+    lock: AirtableLock;
+    renames: SdkNameRename[];
+};
+export declare function generateAirtableTs(inputLock: AirtableLock): string | null;
 export declare function generateBackendWrapperTs(envVarNames?: string[]): string;
 /**
  * Generate `.zite/integrations/email.ts` — the `Email` client for an app with

package/dist/esm/sync/lib.js

@@ -1,5 +1,5 @@
 import { parse } from "@babel/parser";
-import { allocateSchemaNames, describeRenames, keepValidSdkName, normalizeSchemaNames, toCamelCase, toPascalCase, toSdkName, } from "./sdkNames.js";
+import { allocateSchemaNames, describeRenames, keepValidSdkName, normalizeSchemaNames, SdkNameAllocator, toCamelCase, toPascalCase, toSdkName, } from "./sdkNames.js";
 const AUTH_USERS_TABLE_ID = "zite_user";
 /**
  * What a field's value looks like when a record is READ back.
@@ -255,9 +255,12 @@ function fieldJsdoc(schemaField, table, schema) {
         const tpl = def.template;
         if (tpl.tableId) {
             // The SDK name, not the raw `tbl...` id — the id appears nowhere the
-            // reader can act on, while the SDK name is the property on `zite`.
+            // reader can act on, while the SDK name is the property on `zite`. Its
+            // display name rides along, since after a rename the two differ.
             const linked = schema?.tables.find((t) => t.id === tpl.tableId);
-            parts.push(`Links to ${linked ? linked.sdkName : tpl.tableId}`);
+            parts.push(linked
+                ? `Links to ${linked.sdkName}${linked.name ? ` ("${linked.name}")` : ""}`
+                : `Links to ${tpl.tableId}`);
         }
         if (tpl.allowMultiple === false)
             parts.push("Single record only");
@@ -370,6 +373,10 @@ export function generateSchema(database, existingSchema) {
             table: {
                 id: table.id,
                 sdkName: "",
+                // Always the live name — never `existingTable?.name`. Locking it the way
+                // `sdkName` is locked would freeze it at the first name the table ever
+                // had, which is the one thing this is here to avoid.
+                name: table.name,
                 primaryFieldId: table.primaryFieldId,
                 fields: [],
             },
@@ -428,6 +435,13 @@ function buildLinkTableComments(schema) {
     const tablesById = new Map();
     for (const t of schema.tables)
         tablesById.set(t.id, t);
+    // The link name itself is a literal SQL identifier ("use these exact names"),
+    // so it stays sdkName-derived; the display names ride alongside as a gloss.
+    const displayByPascal = new Map();
+    for (const t of schema.tables) {
+        if (t.name)
+            displayByPascal.set(toPascalCase(t.sdkName), t.name);
+    }
     const seen = new Set();
     const entries = [];
     for (const table of schema.tables) {
@@ -457,7 +471,15 @@ function buildLinkTableComments(schema) {
             const col2 = isSelf
                 ? `target${second}Id`
                 : `${second.charAt(0).toLowerCase()}${second.slice(1)}Id`;
-            entries.push({ name: linkName, cols: [col1, col2] });
+            const firstName = displayByPascal.get(first);
+            const secondName = displayByPascal.get(second);
+            entries.push({
+                name: linkName,
+                cols: [col1, col2],
+                gloss: firstName && secondName
+                    ? `joins "${firstName}" and "${secondName}"`
+                    : undefined,
+            });
         }
     }
     if (entries.length === 0)
@@ -467,7 +489,8 @@ function buildLinkTableComments(schema) {
         "// Link tables for zite.sql() JOINs (use these exact names):",
     ];
     for (const e of entries) {
-        lines.push(`//   "${commentSafe(e.name)}" — columns: "${commentSafe(e.cols[0])}", "${commentSafe(e.cols[1])}"`);
+        lines.push(`//   "${commentSafe(e.name)}" — columns: "${commentSafe(e.cols[0])}", "${commentSafe(e.cols[1])}"` +
+            (e.gloss ? ` (${commentSafe(e.gloss)})` : ""));
     }
     return lines;
 }
@@ -554,7 +577,12 @@ export function generateDbTs(inputSchema) {
     for (const table of tables) {
         const className = toPascalCase(table.sdkName);
         const recordType = `${className}RecordType`;
-        lines.push(`/** A ${table.sdkName} record as it is read back. */`);
+        // A schema written before `name` existed keeps the old wording exactly —
+        // sandbox boot regenerates unconditionally, so any drift here would show up
+        // as an unexplained diff in every project's next commit.
+        lines.push(table.name
+            ? `/** A record in the "${commentSafe(table.name)}" table, as it is read back. */`
+            : `/** A ${table.sdkName} record as it is read back. */`);
         lines.push(`export type ${recordType} = {`);
         lines.push("  id: string;");
         for (const field of table.fields) {
@@ -578,7 +606,9 @@ export function generateDbTs(inputSchema) {
         // input than they store (an attachments field takes a URL string; a linked
         // record takes one id or many).
         const writableFields = table.fields.filter((f) => f.sdkName !== "id" && !READ_ONLY_FIELD_TYPES.has(f.definition.type));
-        lines.push(`/** What you may write when creating or updating a ${table.sdkName}. */`);
+        lines.push(table.name
+            ? `/** What you may write when creating or updating a record in the "${commentSafe(table.name)}" table. */`
+            : `/** What you may write when creating or updating a ${table.sdkName}. */`);
         lines.push(`export type ${className}RecordInput = {`);
         for (const field of writableFields) {
             lines.push(`  ${field.sdkName}: ${tsTypeForSchemaField(field.definition, "write")};`);
@@ -590,7 +620,8 @@ export function generateDbTs(inputSchema) {
     lines.push("export const zite = {");
     for (const table of tables) {
         const className = toPascalCase(table.sdkName);
-        lines.push(`  ${table.sdkName}: createTableClient<${className}RecordType, ${className}RecordInput>('${className}'),`);
+        lines.push(`  ${table.sdkName}: createTableClient<${className}RecordType, ${className}RecordInput>('${className}'),` +
+            (table.name ? ` // "${commentSafe(table.name)}"` : ""));
     }
     lines.push(`  sql: createSqlClient(),`);
     // No `notifications` here: it is a platform primitive, not something backed
@@ -989,7 +1020,9 @@ function airtableFieldJsdoc(field, table, lock) {
         const linkedTableId = field.config?.linkedTableId;
         if (linkedTableId) {
             const linked = lock?.tables.find((t) => t.id === linkedTableId);
-            parts.push(`Links to ${linked ? linked.sdkName : linkedTableId}`);
+            parts.push(linked
+                ? `Links to ${linked.sdkName}${linked.name ? ` ("${linked.name}")` : ""}`
+                : `Links to ${linkedTableId}`);
         }
         if (field.config?.prefersSingleRecordLink)
             parts.push("Single record only");
@@ -1042,9 +1075,71 @@ function airtableFieldJsdoc(field, table, lock) {
         return undefined;
     return parts.join(". ");
 }
-export function generateAirtableTs(lock) {
-    if (lock.tables.length === 0)
+// A table client is a `const`, so only value-space bindings can collide with
+// one. `AirtableAttachment` is a type, and types and consts coexist.
+const RESERVED_AIRTABLE_NAMES = ["createAirtableClient"];
+/**
+ * Make every table sdkName in the lock unique, so a duplicated lock can't emit
+ * a file that cannot compile (TS2300/TS2451) and that no app can edit or
+ * exclude.
+ *
+ * A contested name goes to NOBODY. The lock cannot say which table app code
+ * meant, and lock order is no oracle: a rename leaves the original owner
+ * first, while reordering or multi-base flattening can put the newcomer
+ * first. Guessing wrong would keep stale references compiling against the
+ * other table's data (the client is addressed by `tableId`, so the binding
+ * follows whichever table holds the name). With the bare name gone, a stale
+ * reference fails as an unresolved import instead: visible and fixable.
+ *
+ * Field sdkNames are left untouched. They are wire keys, resolved by the
+ * server from stored nameMappings that a generate-time rename can never
+ * update, so a renamed field would type-check yet read `undefined` and fail
+ * every write. Unlike tables, duplicates cannot form there: the producer
+ * seeds field allocation from the stored mappings.
+ *
+ * Names are assigned in declaration order, so an unchanged lock regenerates
+ * the identical file.
+ */
+export function normalizeAirtableLockNames(lock) {
+    const owners = new Map();
+    for (const table of lock.tables) {
+        owners.set(table.sdkName, (owners.get(table.sdkName) ?? 0) + 1);
+    }
+    const contested = [...owners.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([name]) => name);
+    const tableNames = new SdkNameAllocator({
+        reserved: [...RESERVED_AIRTABLE_NAMES, ...contested],
+    });
+    // Sole owners claim their names before any contender is suffixed, so a
+    // contender can never displace a table legitimately named `GroupCalls2`.
+    const kept = lock.tables.map((table) => owners.get(table.sdkName) === 1 && tableNames.available(table.sdkName)
+        ? tableNames.allocate(table.sdkName)
+        : undefined);
+    const renames = [];
+    const tables = lock.tables.map((table, i) => {
+        const sdkName = kept[i] ?? tableNames.allocate(table.sdkName);
+        if (sdkName !== table.sdkName) {
+            renames.push({
+                kind: "table",
+                tableId: table.id,
+                from: table.sdkName,
+                to: sdkName,
+            });
+        }
+        return { ...table, sdkName };
+    });
+    return { lock: { ...lock, tables }, renames };
+}
+export function generateAirtableTs(inputLock) {
+    if (inputLock.tables.length === 0)
         return null;
+    const { lock, renames } = normalizeAirtableLockNames(inputLock);
+    if (renames.length > 0) {
+        for (const line of describeRenames(renames)) {
+            console.warn(`[zitejs] SDK name conflict in zite.lock; the generated Airtable SDK uses: ${line}`);
+        }
+    }
     const lines = [
         "// Auto-generated by zitejs generate from zite.lock. Do not edit manually.",
         "// Airtable SDK — uses createAirtableClient from zitejs/runtime.",
@@ -1085,7 +1180,9 @@ export function generateAirtableTs(lock) {
     lines.push(...AIRTABLE_ATTACHMENT_TYPE);
     for (const table of lock.tables) {
         const recordType = `${table.sdkName}RecordType`;
-        lines.push(`/** A ${commentSafe(table.sdkName)} record as it is read back. */`);
+        lines.push(table.name
+            ? `/** A record in the "${commentSafe(table.name)}" table, as it is read back. */`
+            : `/** A ${commentSafe(table.sdkName)} record as it is read back. */`);
         lines.push(`export type ${recordType} = {`);
         lines.push("  id: string;");
         for (const field of table.fields) {
@@ -1107,7 +1204,9 @@ export function generateAirtableTs(lock) {
         // Read-only fields are omitted rather than typed: Airtable rejects a write
         // to a formula, rollup, lookup or autonumber with a 422.
         const writableFields = table.fields.filter((f) => f.sdkName !== "id" && !READ_ONLY_AIRTABLE_FIELDS.has(f.type));
-        lines.push(`/** What you may write when creating or updating a ${commentSafe(table.sdkName)}. */`);
+        lines.push(table.name
+            ? `/** What you may write when creating or updating a record in the "${commentSafe(table.name)}" table. */`
+            : `/** What you may write when creating or updating a ${commentSafe(table.sdkName)}. */`);
         lines.push(`export type ${table.sdkName}RecordInput = {`);
         for (const field of writableFields) {
             lines.push(`  ${field.sdkName}: ${airtableTsType(field, lock, 0, "write")};`);
@@ -1117,7 +1216,8 @@ export function generateAirtableTs(lock) {
         lines.push(`export const ${table.sdkName} = createAirtableClient<${recordType}, ${table.sdkName}RecordInput>(`);
         lines.push(`  '${lock.integrationId}',`);
         lines.push(`  '${table.sdkName}',`);
-        lines.push(`  { tableId: '${table.id}' },`);
+        lines.push(`  { tableId: '${table.id}' },` +
+            (table.name ? ` // "${commentSafe(table.name)}"` : ""));
         lines.push(`);`);
         lines.push("");
     }
@@ -1213,7 +1313,9 @@ export function generateBackendWrapperTs(envVarNames = []) {
         "export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream extends boolean = false, TSchedule extends ZiteSchedule | undefined = undefined, TWebhook extends ZiteWebhook | undefined = undefined, TRawInput = TInput> {",
         "  description?: string;",
         "  inputSchema?: SchemaLike<TInput, TRawInput>;",
-        "  outputSchema?: SchemaLike<TOutput>;",
+        // Apps compile against this copy, not the base module's.
+        "  /** Documentation only. Never validated, and not an inference site for TOutput. */",
+        "  outputSchema?: SchemaLike<unknown>;",
         "  stream?: TStream;",
         "  authenticated?: boolean;",
         "  /** When set, the endpoint also fires on this cron schedule. It stays request-callable — declaring one widens `context`, so `context.user` must be null-checked. */",

package/dist/esm/sync/lib.test.js

@@ -46,6 +46,173 @@ describe('generateDbTs select option literals', () => {
         expect(out).toContain('"The \\"Premium\\" tier"');
     });
 });
+/** TS2300/TS2451, which `syntaxErrorsIn` can't see — a duplicate export parses fine. */
+const duplicateIdentifierErrorsIn = (source) => {
+    const AMBIENT = `declare module 'zitejs/runtime' {
+    export function createAirtableClient<T, TInput = T>(
+      integrationId: string,
+      className: string,
+      implicitParams: Record<string, unknown>,
+    ): unknown;
+  }`;
+    const sources = {
+        'ambient.d.ts': AMBIENT,
+        'airtable.ts': source,
+    };
+    const host = ts.createCompilerHost({});
+    const original = host.getSourceFile.bind(host);
+    host.getSourceFile = (fileName, langVersion, onError, shouldCreate) => sources[fileName] !== undefined
+        ? ts.createSourceFile(fileName, sources[fileName], langVersion, true)
+        : original(fileName, langVersion, onError, shouldCreate);
+    host.fileExists = f => sources[f] !== undefined || ts.sys.fileExists(f);
+    host.readFile = f => sources[f] ?? ts.sys.readFile(f);
+    const program = ts.createProgram(Object.keys(sources), { strict: true, noEmit: true, skipLibCheck: true }, host);
+    return ts
+        .getPreEmitDiagnostics(program)
+        .filter(d => d.code === 2300 || d.code === 2451)
+        .map(d => ts.flattenDiagnosticMessageText(d.messageText, ' '));
+};
+describe('generateAirtableTs duplicate SDK names', () => {
+    // ZIT-5032: two tables both resolved to `GroupCalls`.
+    const collidingLock = (name) => ({
+        integrationId: 'airtable',
+        tables: [
+            {
+                id: 'tblV204b5ogVasPKc',
+                sdkName: name,
+                primaryFieldId: 'fld1',
+                fields: [
+                    { id: 'fld1', sdkName: 'title', type: 'singleLineText', name: 'Title' },
+                ],
+            },
+            {
+                id: 'tblt474V0WyNlrHX9',
+                sdkName: name,
+                primaryFieldId: 'fld2',
+                fields: [
+                    { id: 'fld2', sdkName: 'title', type: 'singleLineText', name: 'Title' },
+                ],
+            },
+        ],
+    });
+    it('compiles when two tables resolve to the same SDK name', () => {
+        expect(duplicateIdentifierErrorsIn(generateAirtableTs(collidingLock('GroupCalls')) ?? '')).toEqual([]);
+    });
+    // Lock order cannot say which table originally owned the name, and handing
+    // it to the wrong one would leave stale references compiling against the
+    // other table's data. Suffixing every contender turns them into unresolved
+    // imports instead.
+    it('gives a contested name to neither table', () => {
+        const out = generateAirtableTs(collidingLock('GroupCalls')) ?? '';
+        expect(out).not.toContain('export const GroupCalls = ');
+        expect(out).toContain('export const GroupCalls2 = ');
+        expect(out).toContain('export const GroupCalls3 = ');
+    });
+    it('still addresses each table by its own id, so data access is unchanged', () => {
+        const out = generateAirtableTs(collidingLock('GroupCalls')) ?? '';
+        expect(out).toContain("'GroupCalls2',\n  { tableId: 'tblV204b5ogVasPKc' }");
+        expect(out).toContain("'GroupCalls3',\n  { tableId: 'tblt474V0WyNlrHX9' }");
+    });
+    it('never displaces the legitimate owner of a suffixed name', () => {
+        const table = (id, sdkName) => ({
+            id,
+            sdkName,
+            primaryFieldId: 'fld1',
+            fields: [
+                { id: 'fld1', sdkName: 'title', type: 'singleLineText', name: 'Title' },
+            ],
+        });
+        const out = generateAirtableTs({
+            integrationId: 'airtable',
+            tables: [
+                table('tblA', 'GroupCalls'),
+                table('tblB', 'GroupCalls'),
+                table('tblC', 'GroupCalls2'),
+            ],
+        }) ?? '';
+        expect(out).toContain("'GroupCalls2',\n  { tableId: 'tblC' }");
+        expect(out).toContain('export const GroupCalls3 = ');
+        expect(out).toContain('export const GroupCalls4 = ');
+        expect(out).not.toContain('export const GroupCalls = ');
+        expect(duplicateIdentifierErrorsIn(out)).toEqual([]);
+    });
+    it('does not rename anything when names are already unique', () => {
+        const out = generateAirtableTs({
+            integrationId: 'airtable',
+            tables: [
+                {
+                    id: 'tbl1',
+                    sdkName: 'Calls',
+                    primaryFieldId: 'fld1',
+                    fields: [
+                        { id: 'fld1', sdkName: 'title', type: 'singleLineText', name: 'Title' },
+                    ],
+                },
+            ],
+        }) ?? '';
+        expect(out).toContain('export const Calls = ');
+        expect(out).not.toContain('Calls2');
+    });
+    // A field's sdkName is a wire key: the server resolves it from the stored
+    // nameMappings, which a generate-time rename can never update. A renamed
+    // field would type-check yet read `undefined` and fail every write, so
+    // fields are never renamed here.
+    it('leaves field names alone, even when they collide', () => {
+        const out = generateAirtableTs({
+            integrationId: 'airtable',
+            tables: [
+                {
+                    id: 'tbl1',
+                    sdkName: 'Calls',
+                    primaryFieldId: 'fldA',
+                    fields: [
+                        { id: 'fldA', sdkName: 'notes', type: 'singleLineText', name: 'Notes' },
+                        { id: 'fldB', sdkName: 'notes', type: 'singleLineText', name: 'Notes copy' },
+                    ],
+                },
+            ],
+        }) ?? '';
+        expect(out).not.toContain('notes2');
+    });
+    it('still skips a field named `id` instead of renaming it', () => {
+        const out = generateAirtableTs({
+            integrationId: 'airtable',
+            tables: [
+                {
+                    id: 'tbl1',
+                    sdkName: 'Calls',
+                    primaryFieldId: 'fldA',
+                    fields: [
+                        { id: 'fldA', sdkName: 'id', type: 'singleLineText', name: 'ID' },
+                        { id: 'fldB', sdkName: 'title', type: 'singleLineText', name: 'Title' },
+                    ],
+                },
+            ],
+        }) ?? '';
+        expect(out).not.toContain('id2');
+        expect(out).not.toContain('id?:');
+        // the record id, emitted by hand, stays the only `id`
+        expect(out).toContain('id: string;');
+    });
+    it('leaves a table named after the attachment type alone', () => {
+        const out = generateAirtableTs({
+            integrationId: 'airtable',
+            tables: [
+                {
+                    id: 'tbl1',
+                    sdkName: 'AirtableAttachment',
+                    primaryFieldId: 'fld1',
+                    fields: [
+                        { id: 'fld1', sdkName: 'title', type: 'singleLineText', name: 'Title' },
+                    ],
+                },
+            ],
+        }) ?? '';
+        expect(duplicateIdentifierErrorsIn(out)).toEqual([]);
+        expect(out).toContain('export const AirtableAttachment = ');
+        expect(out).not.toContain('AirtableAttachment2');
+    });
+});
 describe('generateAirtableTs attachment type', () => {
     const lockWithAttachment = {
         integrationId: 'airtable',
@@ -110,6 +277,56 @@ describe('generateDbTs field names in comments', () => {
         expect(syntaxErrorsIn(generateDbTs(schemaWithFieldNamed(name)))).toEqual([]);
     });
 });
+describe('generateDbTs table names in comments', () => {
+    const schemaWithTableNamed = (name) => ({
+        tables: [
+            {
+                id: 'tbl1',
+                sdkName: 'table1',
+                ...(name === undefined ? {} : { name }),
+                primaryFieldId: 'fld1',
+                fields: [
+                    {
+                        id: 'fld1',
+                        sdkName: 'slot',
+                        definition: {
+                            type: 'single_line_text',
+                            name: 'Slot',
+                            template: {},
+                        },
+                    },
+                ],
+            },
+        ],
+    });
+    // The whole point: `sdkName` is locked to the table's id, so after a rename
+    // `table1` is the only thing a reader sees. The display name is what says
+    // which table that is.
+    it('names the table beside its locked sdkName', () => {
+        const out = generateDbTs(schemaWithTableNamed('Time Slots'));
+        expect(out).toContain('/** A record in the "Time Slots" table, as it is read back. */');
+        expect(out).toContain('/** What you may write when creating or updating a record in the "Time Slots" table. */');
+        expect(out).toContain(`table1: createTableClient<Table1RecordType, Table1RecordInput>('Table1'), // "Time Slots"`);
+    });
+    // Sandbox boot regenerates unconditionally against the committed schema, so a
+    // schema written before `name` existed has to keep producing what it did
+    // before — otherwise every project's next commit carries an unexplained diff.
+    it('emits the pre-name wording when the schema carries no name', () => {
+        const out = generateDbTs(schemaWithTableNamed(undefined));
+        expect(out).toContain('/** A table1 record as it is read back. */');
+        expect(out).toContain('/** What you may write when creating or updating a table1. */');
+        expect(out).toContain(`('Table1'),\n`);
+        expect(out).not.toContain('" table, as it is read back');
+    });
+    // Same hazard as a field name, one level up: a table's display name is user
+    // text and now reaches a JSDoc.
+    it.each([
+        ['a comment-close sequence', 'Slots */ console.log(1); /*'],
+        ['a newline', 'Time\nSlots'],
+    ])('emits parseable TypeScript for a table named with %s', (_what, name) => {
+        expect(syntaxErrorsIn(generateDbTs(schemaWithTableNamed(name)))).toEqual([]);
+    });
+});
 describe('generateApiTs endpoint file names', () => {
     // An endpoint filename is the LLM's raw `writeFile` path argument — nothing
     // validates its characters — and it lands in an import specifier, a comment

package/dist/esm/sync/sdkNames.d.ts

@@ -66,6 +66,33 @@ export interface SdkNameRename {
     from: string;
     to: string;
 }
+/**
+ * Unique identifiers within one namespace.
+ *
+ * `derive` names the extra keys an allocation also occupies. A table needs it:
+ * its sdkName becomes both a property on `zite` and, PascalCased, a pair of
+ * exported type declarations, so `orders` and `Orders` are distinct accessors
+ * that would emit `OrdersRecordType` twice.
+ */
+export declare class SdkNameAllocator {
+    private readonly taken;
+    private readonly reserved;
+    private readonly derive;
+    constructor(opts?: {
+        reserved?: readonly string[];
+        derive?: (name: string) => string[];
+    });
+    private keysFor;
+    private isFree;
+    /** Free right now, without claiming it. */
+    available(name: string): boolean;
+    private claim;
+    /**
+     * `name`, or the first `name2`, `name3`… that is free. Suffixes start at 2
+     * because that is what the name means: the second table called Notifications.
+     */
+    allocate(preferred: string): string;
+}
 /**
  * Existing sdkNames are preserved across syncs so user code keeps compiling,
  * but a schema written before the sanitizer stripped trailing symbols can carry

package/dist/esm/sync/sdkNames.js

@@ -91,7 +91,7 @@ const MAX_SUFFIX_ATTEMPTS = 10_000;
  * exported type declarations, so `orders` and `Orders` are distinct accessors
  * that would emit `OrdersRecordType` twice.
  */
-class SdkNameAllocator {
+export class SdkNameAllocator {
     taken = new Set();
     reserved;
     derive;

package/dist/esm/sync/sdkNames.test.js

@@ -205,3 +205,31 @@ describe("normalizeSchemaNames", () => {
         expect(keys).toContain("sql2");
     });
 });
+describe("table display names", () => {
+    // `sdkName` is locked to the id so user code keeps compiling; `name` is the
+    // opposite and must always take the live value. Locking it too — the easy
+    // mistake, since the line above it does exactly that — freezes it at the
+    // table's first name and defeats the point.
+    it("follows a rename while the sdkName stays locked", () => {
+        const first = generateSchema(database([{ id: "tbl_1", name: "Slots", fields: [field("fld_1", "At")] }]));
+        expect(first.tables[0].sdkName).toBe("slots");
+        expect(first.tables[0].name).toBe("Slots");
+        const renamed = generateSchema(database([
+            { id: "tbl_1", name: "Time Slots", fields: [field("fld_1", "At")] },
+        ]), first);
+        expect(renamed.tables[0].sdkName).toBe("slots");
+        expect(renamed.tables[0].name).toBe("Time Slots");
+        expect(generateDbTs(renamed)).toContain('/** A record in the "Time Slots" table, as it is read back. */');
+    });
+    // `buildLegacySchemaSeed` (restly, migration) builds a seed carrying only
+    // `sdkName`. Reading `name` off the seed would emit `undefined` for every
+    // table on every newly migrated project.
+    it("takes the live name even when the seed has none", () => {
+        const seed = {
+            tables: [{ id: "tbl_1", sdkName: "salesDeals", fields: [] }],
+        };
+        const schema = generateSchema(database([{ id: "tbl_1", name: "Deals", fields: [] }]), seed);
+        expect(schema.tables[0].sdkName).toBe("salesDeals");
+        expect(schema.tables[0].name).toBe("Deals");
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zitejs",
-  "version": "0.9.110",
+  "version": "0.9.112",
   "description": "The Zite framework — build apps on Zite Database",
   "type": "module",
   "main": "./dist/cjs/index.js",