@abloatai/transaction 0.51.0 → 0.53.0

package/src/schema/ddl.ts

@@ -117,7 +117,7 @@ export function sqlType(fieldType: ModelJSON['fields'][string]['type']): string
   }
 }
 
-const BASE_COLUMNS = new Set(['id', 'organization_id', 'created_by', 'created_at', 'updated_at']);
+const BASE_COLUMNS = new Set(['id']);
 
 // ── Foreign keys (relation-driven, sync-safe) ────────────────────────────────
 
@@ -154,11 +154,11 @@ interface ForeignKeyDdl {
  * in by setting `{ fk: true }`.
  *
  * The `fk` marker is deliberately separate from `parent`: `parent` controls
- * sync-group fan-out and visibility, while `fk` requests physical referential
+ * sync-group fan-out and visibility, while `fk` requests database referential
  * integrity in the database. A relation sets `fk` only when its target lives in
  * the same database, is written in the same commit, and is a strong, contained
  * entity. Soft references — provenance or template pointers such as
- * `sourceSlideId` or `templateId` — stay plain columns; a hard foreign key there
+ * `sourceDocumentId` or `templateId` — stay plain columns; a hard foreign key there
  * would reject a write that points across scopes or at an absent row and break
  * sync.
  *
@@ -204,7 +204,7 @@ function foreignKeyStatements(
   // The model's provisioned column set — guard so a relation whose FK field
   // isn't actually declared (no column) never produces a broken ALTER.
   const orgCol = tenancyColumn(resolveTenancy(model));
-  const columns = new Set<string>(['id', 'created_by', 'created_at', 'updated_at']);
+  const columns = new Set<string>(['id']);
   if (orgCol) columns.add(orgCol);
   for (const [fieldName, meta] of Object.entries(model.fields)) {
     columns.add(meta.column ?? camelToSnake(fieldName));
@@ -275,8 +275,7 @@ export function generateProvisionPlan(
     // declared boundary is what makes the set of tables a customer's own
     // database receives derivable instead of hand-coded.
     if ((model.plane ?? 'tenant') === 'control') continue;
-
-    // Default the physical table to the model key when `tableName` is omitted —
+    // Default the database table to the model key when `tableName` is omitted —
     // same fallback the migration path uses (`tableOfModel: m.tableName ?? key`).
     // Without this, a schema that doesn't set `tableName` (e.g. the `ablo init`
     // starter) provisions zero tables.
@@ -294,13 +293,10 @@ export function generateProvisionPlan(
     // no tenancy column — they're scoped via a parent FK or not at all.
     const orgCol = tenancyColumn(resolveTenancy(model));
     const baseColumns = [
-      `  ${q('id')} TEXT PRIMARY KEY,`,
-      ...(orgCol ? [`  ${q(orgCol)} TEXT NOT NULL,`] : []),
-      `  ${q('created_by')} TEXT,`,
-      `  ${q('created_at')} TIMESTAMPTZ NOT NULL DEFAULT NOW(),`,
-      `  ${q('updated_at')} TIMESTAMPTZ NOT NULL DEFAULT NOW()`,
+      `  ${q('id')} TEXT PRIMARY KEY`,
+      ...(orgCol ? [`  ${q(orgCol)} TEXT NOT NULL`] : []),
     ];
-    statements.push(`CREATE TABLE IF NOT EXISTS ${qt} (\n${baseColumns.join('\n')}\n);`);
+    statements.push(`CREATE TABLE IF NOT EXISTS ${qt} (\n${baseColumns.join(',\n')}\n);`);
 
     for (const [fieldName, meta] of Object.entries(model.fields)) {
       const col = meta.column ?? camelToSnake(fieldName);
@@ -458,7 +454,7 @@ export function generateMigrationPlan(
       case 'rename_model': {
         const fromTable = tableOfModel(prev, step.from);
         const toTable = tableOfModel(next, step.to);
-        // A logical model rename only needs SQL when the physical table name
+        // A logical model rename only needs SQL when the database table name
         // actually changes; if tableName is unchanged the rename is metadata.
         if (fromTable && toTable && fromTable !== toTable) {
           statements.push(`ALTER TABLE ${qtFor(fromTable)} RENAME TO ${q(toTable)};`);

package/src/schema/field.ts

@@ -9,7 +9,7 @@
  * Usage:
  *   import { field } from '@abloatai/transaction/schema';
  *
- *   const tasks = model({
+ *   const items = model({
  *     title: field.string(),
  *     projectId: field.string().indexed(),     // fluent chain
  *     priority: field.number().optional(),
@@ -19,7 +19,7 @@
  * Or use Zod directly (no metadata, but still works):
  *   import { z } from 'zod';
  *
- *   const tasks = model({
+ *   const items = model({
  *     title: z.string(),
  *   });
  */
@@ -199,7 +199,7 @@ export function resolveFieldMeta(schema: z.ZodType): FieldMeta {
 
 /** A Zod schema returned by a {@link field} builder — the underlying Zod type plus
  *  two chainable methods: `indexed()` marks the field for a database index, and
- *  `from(column)` overrides the physical column name it maps to. */
+ *  `from(column)` overrides the database column name it maps to. */
 export type FieldBuilder<T extends z.ZodType> = T & {
   indexed(): FieldBuilder<T>;
   from(column: string): FieldBuilder<T>;

package/src/schema/fieldRef.ts

@@ -24,7 +24,7 @@
  * `string`.
  *
  * `model` rides along so a reference carries where it came from. Claiming
- * `users.email` through `ablo.tasks` is a mistake nothing can currently see.
+ * `users.email` through `ablo.items` is a mistake nothing can currently see.
  */
 export interface FieldRef<
   Model extends string = string,

package/src/schema/generate.ts

@@ -10,9 +10,8 @@
  * that same schema, so the types you code against, the rows the database stores, and
  * the entities the sync layer moves all describe the same thing.
  *
- * The generated interface covers the base columns plus each declared field, with
- * enums emitted as string-literal unions. Relations are not expanded here — the
- * runtime SDK resolves those through its typed accessors.
+ * The generated interface covers storage-mode fields plus each declared field,
+ * with enums emitted as string-literal unions. Relations are not expanded here.
  */
 
 import type { FieldMeta } from './field.js';
@@ -70,12 +69,7 @@ export function generateTypes(schema: SchemaJSON): string {
   for (const [key, model] of Object.entries(schema.models)) {
     lines.push(`export interface ${nameByKey.get(key)!} {`);
     lines.push('  id: string;');
-    lines.push('  createdAt: Date;');
-    lines.push('  updatedAt: Date;');
-    lines.push('  organizationId?: string;');
-    lines.push('  createdBy?: string;');
     for (const [fieldName, meta] of Object.entries(model.fields)) {
-      // A model that redeclares a base column doesn't double-emit it.
       if ((BASE_FIELDS as readonly string[]).includes(fieldName)) continue;
       lines.push(`  ${fieldName}${meta.isOptional ? '?' : ''}: ${tsType(meta)};`);
     }

package/src/schema/index.ts

@@ -8,7 +8,7 @@
  * import { defineSchema, model, relation } from '@abloatai/transaction/schema';
  *
  * export const schema = defineSchema({
- *   tasks: model({
+ *   items: model({
  *     title: z.string(),
  *     status: z.enum(['todo', 'doing', 'done']).default('todo'),
  *     projectId: z.string().optional(),
@@ -17,7 +17,7 @@
  *   }),
  * });
  *
- * type Task = Model<typeof schema, 'tasks'>;
+ * type Item = Model<typeof schema, 'items'>;
  * ```
  */
 
@@ -27,7 +27,7 @@ export { z } from 'zod';
 // Field helpers (optional convenience wrappers around Zod)
 export { field, indexed, getFieldMeta, type FieldBuilder, type FieldMeta } from './field.js';
 
-// A field as a value rather than a quoted name — `schema.fields.tasks.status`.
+// A field as a value rather than a quoted name — `schema.fields.items.status`.
 // Surfaces that name a field (claims today) take one of these so a name that
 // does not exist stops compiling.
 export {

package/src/schema/model.ts

@@ -8,7 +8,7 @@
  *   import { z } from 'zod';
  *   import { model, relation } from '@abloatai/transaction/schema';
  *
- *   const tasks = model({
+ *   const items = model({
  *     title: z.string(),
  *     status: z.enum(['todo', 'doing', 'done']).default('todo'),
  *     projectId: z.string().optional(),
@@ -90,13 +90,13 @@ export interface ModelOptions {
    * Edges from this model to others, keyed by the accessor name they create. The
    * engine reads them to index foreign keys, to order inserts so a parent row lands
    * before the rows referencing it, and to generate the accessors that let you read
-   * `task.project` or `project.tasks` directly. Built with the {@link relation}
+   * `item.project` or `project.items` directly. Built with the {@link relation}
    * factories.
    *
    * ```ts
    * relations: {
    *   project: relation.belongsTo('projects', 'projectId'),
-   *   comments: relation.hasMany('comments', 'taskId'),
+   *   comments: relation.hasMany('comments', 'itemId'),
    * }
    * ```
    */
@@ -110,8 +110,8 @@ export interface ModelOptions {
   /**
    * The wire type name for this model — the value that identifies its rows on the
    * wire (the `__typename`). The loader stamps it onto incoming rows and uses it to
-   * find the matching model class. It defaults to the schema key (`tasks` →
-   * `'tasks'`); set it explicitly when the wire shape uses different casing, such as
+   * find the matching model class. It defaults to the schema key (`items` →
+   * `'items'`); set it explicitly when the wire shape uses different casing, such as
    * schema key `block` mapping to typename `'Block'`.
    *
    * This is the one value that identifies the model on the wire; the client-side
@@ -178,7 +178,7 @@ export interface ModelOptions {
    *   inbox. Accepts one role or many.
    *
    * ```ts
-   * // dataroomMember: { userId, dataroomId }
+   * // archiveMember: { userId, archiveId }
    * groups: { grants: { subject: 'user', scope: 'workspace' } }
    * // a message → its addressee's inbox, keyed on `toId`
    * groups: { roles: [entityRole({ kind: 'inbox', source: 'toId' })] }
@@ -395,7 +395,7 @@ export interface ModelDef<
  * const tags = model({ label: z.string() });
  *
  * // Loaded at bootstrap (the default), with an edge to its project
- * const tasks = model({
+ * const items = model({
  *   title: z.string(),
  *   status: z.enum(['todo', 'doing', 'done']).default('todo'),
  *   projectId: z.string().optional(),

package/src/schema/openapi.ts

@@ -36,6 +36,7 @@ import {
   commitRecordListSchema,
   commitRecordWhereSchema,
 } from '../wire/commit.js';
+import { CURSOR_PARAM, CURSOR_PARAM_ALIAS } from '../wire/listEnvelope.js';
 import {
   claimRequestSchema,
   claimHeartbeatRequestSchema,
@@ -185,6 +186,43 @@ function fieldSchema(f: FieldMeta): Json {
 
 const pascal = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
 const idParam = (): Json => ({ name: 'id', in: 'path', required: true, schema: { type: 'string' } });
+const idempotencyKeyParam = (): Json => ({
+  name: 'Idempotency-Key',
+  in: 'header',
+  schema: { type: 'string', maxLength: 255 },
+  description: 'Replay identity. Reuse the same key only for an identical request.',
+});
+const collectionPageParams = (): Json[] => [
+  {
+    name: 'limit',
+    in: 'query',
+    schema: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+  },
+  cursorParam(),
+  retiredCursorParam(),
+];
+
+/** The cursor parameter, named from the wire contract that issues its value. */
+const cursorParam = (): Json => ({
+  name: CURSOR_PARAM,
+  in: 'query',
+  schema: { type: 'string' },
+  description: 'The opaque next_cursor returned by the preceding page.',
+});
+
+/**
+ * The retired spelling, documented as deprecated so a caller still sending it
+ * can see it is going. Declared once: `queryParams` reaches for it too, and a
+ * second copy is how the model list came to document the same parameter without
+ * the deprecation the collection routes carried.
+ */
+const retiredCursorParam = (): Json => ({
+  name: CURSOR_PARAM_ALIAS,
+  in: 'query',
+  deprecated: true,
+  schema: { type: 'string' },
+  description: `Deprecated spelling of ${CURSOR_PARAM}, honoured until it is removed. Send ${CURSOR_PARAM}.`,
+});
 const jsonBody = (schema: Json): Json => ({
   required: true,
   content: { 'application/json': { schema } },
@@ -208,8 +246,9 @@ const namedResp = (description: string, name: string): Json =>
  *
  * - `$schema` belongs on a standalone JSON Schema document, not every embedded
  *   OpenAPI Schema Object;
- * - `propertyNames: { type: 'string' }` is redundant for JSON objects and is
- *   unsupported by Stainless;
+ * - `propertyNames` constraining keys to strings is redundant for JSON objects,
+ *   whatever else it constrains, and is unsupported by Stainless. The key rule
+ *   still binds at runtime, where the Zod schema parses;
  * - `additionalProperties: {}` means "any JSON value", but Stainless requires
  *   the equivalent, explicit `true`.
  *
@@ -228,7 +267,6 @@ function portableSchema(value: unknown): unknown {
       key === 'propertyNames' &&
       typeof child === 'object' &&
       child !== null &&
-      Object.keys(child).length === 1 &&
       (child as Record<string, unknown>).type === 'string'
     ) {
       continue;
@@ -267,7 +305,7 @@ const modelParam = (): Json => ({
   in: 'path',
   required: true,
   schema: { type: 'string' },
-  description: 'A model name from your pushed schema, e.g. `task`.',
+  description: 'A model name from your pushed schema, e.g. `item`.',
 });
 const genericRow = (): Json => ({ type: 'object', additionalProperties: true });
 
@@ -313,16 +351,22 @@ function withGenericRows(derived: Json): Json {
  */
 function queryParams(schema: z.ZodType): Json[] {
   const props = (derive(schema, 'input').properties ?? {}) as Record<string, Json>;
-  return Object.entries(props).map(([name, s]) => ({
-    name,
-    in: 'query',
-    // Query strings arrive at the server as text, but OpenAPI describes the
-    // caller-facing value before serialization. Generated clients should take
-    // an integer here and encode it, not expose a stringly typed page size.
-    schema: name === 'limit'
-      ? { type: 'integer', minimum: 1 }
-      : s,
-  }));
+  return Object.entries(props).map(([name, s]) => {
+    // The retired cursor spelling is documented the same way wherever it
+    // appears. Derived from the schema it still lives in, so the flag cannot be
+    // present on one route's copy of the parameter and absent on another's.
+    if (name === CURSOR_PARAM_ALIAS) return retiredCursorParam();
+    return {
+      name,
+      in: 'query',
+      // Query strings arrive at the server as text, but OpenAPI describes the
+      // caller-facing value before serialization. Generated clients should take
+      // an integer here and encode it, not expose a stringly typed page size.
+      schema: name === 'limit'
+        ? { type: 'integer', minimum: 1 }
+        : s,
+    };
+  });
 }
 
 const commitRecordListQuerySchema = commitRecordWhereSchema.safeExtend({
@@ -492,8 +536,8 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
         parameters: [modelParam(), ...queryParams(listQuerySchema)],
         responses: {
           '200': namedResp(
-            'A page of rows. `next_cursor` feeds `starting_after` on the next ' +
-              'call; `stamp` is the watermark the page was read at.',
+            'A page of rows. `next_cursor` feeds `cursor` on the next call; ' +
+              '`stamp` is the watermark the page was read at.',
             'ModelPage',
           ),
         },
@@ -591,9 +635,6 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
         description:
           'Call this first: every other route needs the key it returns. Requires a ' +
           'secret (`sk_`) key — a session cannot mint itself.',
-        parameters: [
-          { name: 'Idempotency-Key', in: 'header', schema: { type: 'string' }, description: 'Replay-safe key; the server returns the cached credential on retry.' },
-        ],
         requestBody: jsonBody(derive(ephemeralKeyRequestSchema, 'input')),
         responses: { '201': jsonResp('The minted credential', derive(EphemeralKeyResponseSchema, 'output')) },
       },
@@ -602,6 +643,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
       get: {
         tags: ['branches'],
         summary: 'List transaction branches for the credential project',
+        parameters: collectionPageParams(),
         responses: {
           '200': jsonResp(
             'The root and every active child branch.',
@@ -614,6 +656,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
         summary: 'Create an isolated child branch',
         description:
           'The returned id is immutable; retain it for automation. The slug is a project-scoped human handle.',
+        parameters: [idempotencyKeyParam()],
         requestBody: jsonBody(derive(createBranchRequestSchema, 'input')),
         responses: {
           '201': jsonResp('The ready branch.', derive(branchResponseSchema, 'output')),
@@ -869,7 +912,7 @@ export function abloOpenApi(options: SchemaToOpenApiOptions = {}): Json {
       post: {
         tags: ['commits'],
         summary: 'Commit a batch of operations atomically, and/or register durable premises',
-        parameters: [{ name: 'Idempotency-Key', in: 'header', schema: { type: 'string' }, description: 'Replay-safe key; the server returns the cached receipt on retry.' }],
+        parameters: [idempotencyKeyParam()],
         requestBody: commitBody(),
         responses: { '200': commitReceipt() },
       },
@@ -996,7 +1039,7 @@ export function schemaToOpenApi<S extends SchemaRecord>(
     post: {
       tags: ['commits'],
       summary: 'Commit a batch of operations atomically, and/or register durable premises',
-      parameters: [{ name: 'Idempotency-Key', in: 'header', schema: { type: 'string' }, description: 'Replay-safe key; the server returns the cached receipt on retry.' }],
+      parameters: [idempotencyKeyParam()],
       requestBody: commitBody(),
       responses: { '200': commitReceipt() },
     },

package/src/schema/queries.ts

@@ -44,7 +44,7 @@
  *    the factory and defers the cross-reference check to schema assembly.
  *
  *  - A query carries no `name` until `defineQueries()` assigns one from its
- *    record key — the same pattern `defineSchema({ tasks: model(...) })`
+ *    record key — the same pattern `defineSchema({ items: model(...) })`
  *    uses, where the model's name is the record key rather than a field on
  *    the factory.
  *

package/src/schema/relation.ts

@@ -4,15 +4,15 @@
  * {@link relation} factories; the engine reads them to index foreign keys for
  * fast child lookups, to order inserts so a parent row lands before the rows
  * that reference it, and to generate the accessor properties that let you read
- * `task.project` or `project.tasks` directly.
+ * `item.project` or `project.items` directly.
  *
  * Usage:
  *   import { relation } from '@abloatai/transaction/schema';
  *
- *   const taskRelations = {
+ *   const itemRelations = {
  *     project: relation.belongsTo('projects', 'projectId'),
  *     assignee: relation.belongsTo('users', 'assigneeId'),
- *     comments: relation.hasMany('comments', 'taskId'),
+ *     comments: relation.hasMany('comments', 'itemId'),
  *   };
  */
 
@@ -28,9 +28,9 @@
  * way often, such as a block's `sectionId`.
  *
  * `enrich: true` auto-populates the parent reference on an incoming change
- * before the child data lands. A change to `Task { teamId: 't1' }` picks up the
+ * before the child data lands. A change to `Item { teamId: 't1' }` picks up the
  * already-loaded `teams:t1` record and attaches it as `data.team`, so you can
- * read `task.team` without a second lookup. Enrichment is best-effort: if the
+ * read `item.team` without a second lookup. Enrichment is best-effort: if the
  * parent has not loaded yet it quietly does nothing, and the child data still
  * applies.
  *
@@ -71,7 +71,7 @@ export interface BelongsToOptions {
    * provenance or as a template, such as `sourceSectionId` or `templateId`; doing
    * so would leak the record into an unrelated scope. The engine also cannot
    * infer the parent from whether a field is optional — many real parent keys
-   * are optional, like a root folder or an inbox task — so you must declare the
+   * are optional, like a root folder or an inbox item — so you must declare the
    * parent edge explicitly.
    *
    * It reads naturally at the call site:
@@ -218,7 +218,7 @@ class RelationBuilder<
 export const relation = {
   /**
    * This model belongs to another model via a foreign key.
-   * e.g., Task belongs to Project via projectId
+   * e.g., Item belongs to Project via projectId
    *
    * ```ts
    * // Simple reference (no options)
@@ -252,7 +252,7 @@ export const relation = {
 
   /**
    * This model has many of another model — for example, a project has many
-   * tasks via `Task.projectId`.
+   * items via `Item.projectId`.
    *
    * At runtime the engine adds a getter to the parent model that returns every
    * child whose foreign key matches, and registers the foreign-key index on the

package/src/schema/residency.ts

@@ -27,4 +27,3 @@ export type ModelResidency = z.infer<typeof residencySchema>;
 
 /** Default residency for a model that doesn't declare one — the tenant data plane. */
 export const DEFAULT_RESIDENCY: ModelResidency = 'tenant';
-