@abloatai/ablo 0.34.1 → 0.35.0

package/dist/transaction/schema/openapi.js

@@ -0,0 +1,340 @@
+// Pulled from the endpoints module to keep this schema file free of the client's
+// error-handling and credential dependencies.
+import { ABLO_HOSTED_HTTP_BASE_URL } from '../auth/hostedEndpoints.js';
+// The commit body is DERIVED from the schema the server validates against —
+// one definition site, so the documented surface cannot drift from the
+// enforced one.
+import { z } from 'zod';
+import { commitRequestSchema, commitReceiptSchema } from '../wire/commit.js';
+import { claimRequestSchema, claimHeartbeatRequestSchema, listQuerySchema, claimStateSchema, claimAcquiredResponseSchema, claimQueuedResponseSchema, claimHeartbeatReplySchema, } from '../wire/claims.js';
+import { modelReadResponseSchema, modelListResponseSchema } from '../wire/modelResponses.js';
+import { ephemeralKeyRequestSchema, capabilityRequestSchema } from '../wire/auth.js';
+import { EphemeralKeyResponseSchema } from '../auth/schemas.js';
+function fieldSchema(f) {
+    switch (f.type) {
+        case 'number':
+            return { type: 'number' };
+        case 'boolean':
+            return { type: 'boolean' };
+        case 'date':
+            return { type: 'string', format: 'date-time' };
+        case 'enum':
+            return f.enumValues ? { type: 'string', enum: [...f.enumValues] } : { type: 'string' };
+        case 'json':
+            return { type: 'object', additionalProperties: true };
+        case 'string':
+        default:
+            return { type: 'string' };
+    }
+}
+const pascal = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+const idParam = () => ({ name: 'id', in: 'path', required: true, schema: { type: 'string' } });
+const jsonBody = (schema) => ({
+    required: true,
+    content: { 'application/json': { schema } },
+});
+/** For routes where an empty body is meaningful — a bare claim, a plain beat. */
+const optionalJsonBody = (schema) => ({
+    required: false,
+    content: { 'application/json': { schema } },
+});
+const jsonResp = (description, schema) => ({
+    description,
+    content: { 'application/json': { schema } },
+});
+/**
+ * Derive a JSON Schema from a wire schema.
+ *
+ * `io` is not optional by accident. A request is what the caller SENDS, so it
+ * derives from the input type; a response is what the server RETURNS, so it
+ * derives from the output type. Reversing them is silent — the document still
+ * looks like a working spec — which is why the direction is stated at every
+ * call site rather than defaulted.
+ */
+const derive = (schema, io) => z.toJSONSchema(schema, { io, unrepresentable: 'any' });
+const commitReceipt = () => jsonResp('Commit receipt', derive(commitReceiptSchema, 'output'));
+const modelParam = () => ({
+    name: 'model',
+    in: 'path',
+    required: true,
+    schema: { type: 'string' },
+    description: 'A model name from your pushed schema, e.g. `task`.',
+});
+const genericRow = () => ({ type: 'object', additionalProperties: true });
+/**
+ * Fill in `data` on a derived model-response schema.
+ *
+ * The wire schemas type a row as `unknown`, because the transport that reads
+ * them serves every schema and knows none of them. A reference has the opposite
+ * need — a reader wants to see that `data` holds rows — so the envelope is
+ * still derived, and only the one deliberately-open field is described. Both
+ * shapes of that field are handled: an array for a list, a bare object for a
+ * single read.
+ */
+function withGenericRows(derived) {
+    const properties = { ...derived.properties };
+    if (!('data' in properties))
+        return derived;
+    properties.data =
+        properties.data?.type === 'array'
+            ? { type: 'array', items: genericRow() }
+            : genericRow();
+    return { ...derived, properties };
+}
+/** Query parameters derived from the schema the route reads them with. */
+function listQueryParams() {
+    const props = (derive(listQuerySchema, 'input').properties ?? {});
+    return Object.entries(props).map(([name, schema]) => ({ name, in: 'query', schema }));
+}
+/**
+ * The `POST /v1/commits` body, derived from {@link commitRequestSchema} — the
+ * same schema the server validates the request against.
+ *
+ * Deriving rather than describing is the point: a hand-written copy of this
+ * shape would drift silently, and the tests would pin the copy to itself.
+ */
+const commitBody = () => jsonBody(derive(commitRequestSchema, 'input'));
+/** The envelope shared by both specs — same server, same auth, same version. */
+function envelope(options, description, paths, schemas) {
+    return {
+        openapi: '3.1.0',
+        info: {
+            title: options.title ?? 'Ablo API',
+            version: options.version ?? '1.0.0',
+            description,
+        },
+        servers: [{ url: options.serverUrl ?? `${ABLO_HOSTED_HTTP_BASE_URL}/api` }],
+        security: [{ bearerAuth: [] }],
+        components: {
+            securitySchemes: {
+                bearerAuth: { type: 'http', scheme: 'bearer', description: 'Your Ablo API key (sk_… / rk_…).' },
+            },
+            schemas,
+        },
+        paths,
+    };
+}
+/**
+ * The protocol reference: the five route templates the server actually serves,
+ * plus `/v1/commits`.
+ *
+ * This takes no schema, and that is the point. The server registers one
+ * parameterised route family (`/api/v1/models/:model/...`), so the API is five
+ * routes no matter how many models a tenant defines — and a spec that cannot see
+ * a schema cannot grow with one. It is publishable once, identical for every
+ * caller, and stable across every schema push: the document a Python or Go
+ * client is generated from, and the surface an agent is handed.
+ *
+ * Payload shapes are generic here by design. A caller that wants them typed
+ * either reads the schema at runtime or generates the per-tenant expansion with
+ * {@link schemaToOpenApi}.
+ */
+export function abloOpenApi(options = {}) {
+    const rowResp = jsonResp('The row, with the watermark it was read at and who holds it.', withGenericRows(derive(modelReadResponseSchema, 'output')));
+    const writeBody = jsonBody(genericRow());
+    const tags = ['models'];
+    const paths = {
+        '/v1/models/{model}': {
+            get: {
+                tags,
+                summary: 'List rows of a model',
+                parameters: [modelParam(), ...listQueryParams()],
+                responses: {
+                    '200': jsonResp('A page of rows. `next_cursor` feeds `starting_after` on the next ' +
+                        'call; `stamp` is the watermark the page was read at.', withGenericRows(derive(modelListResponseSchema, 'output'))),
+                },
+            },
+            post: { tags, summary: 'Create a row', parameters: [modelParam()], requestBody: writeBody, responses: { '200': commitReceipt() } },
+        },
+        '/v1/models/{model}/{id}': {
+            get: { tags, summary: 'Retrieve a row', parameters: [modelParam(), idParam()], responses: { '200': rowResp } },
+            patch: { tags, summary: 'Update a row', parameters: [modelParam(), idParam()], requestBody: writeBody, responses: { '200': commitReceipt() } },
+            delete: { tags, summary: 'Delete a row', parameters: [modelParam(), idParam()], responses: { '200': commitReceipt() } },
+        },
+        '/v1/models/{model}/{id}/claim': {
+            post: {
+                tags: ['claims'],
+                summary: 'Claim a row (acquire lease)',
+                parameters: [modelParam(), idParam()],
+                requestBody: optionalJsonBody(derive(claimRequestSchema, 'input')),
+                responses: {
+                    '201': jsonResp('The lease is yours. `claim.fenceToken` is set when the coordinator ' +
+                        'minted one; carry it on writes made under the lease.', derive(claimAcquiredResponseSchema, 'output')),
+                    '202': jsonResp('The row was already held and you asked to queue. You are in line at ' +
+                        '`position` — heartbeat to keep the slot, and poll ' +
+                        '`GET /v1/claims/{claimId}` for the grant.', derive(claimQueuedResponseSchema, 'output')),
+                },
+            },
+            delete: { tags: ['claims'], summary: 'Release a claim', parameters: [modelParam(), idParam()], responses: { '200': jsonResp('Released', { type: 'object' }) } },
+        },
+        '/v1/models/{model}/{id}/claim/heartbeat': {
+            post: {
+                tags: ['claims'],
+                summary: 'Heartbeat a held claim (extend the lease for long-running work)',
+                parameters: [modelParam(), idParam()],
+                requestBody: optionalJsonBody(derive(claimHeartbeatRequestSchema, 'input')),
+                responses: {
+                    '200': jsonResp('Lease extended (or queued slot refreshed)', derive(claimHeartbeatReplySchema, 'output')),
+                },
+            },
+        },
+        '/v1/models/{model}/{id}/claim/reorder': {
+            post: { tags: ['claims'], summary: 'Reorder the wait-line (privileged)', parameters: [modelParam(), idParam()], responses: { '200': jsonResp('Reordered', { type: 'object' }) } },
+        },
+        '/v1/ephemeral_keys': {
+            post: {
+                tags: ['credentials'],
+                summary: 'Mint a short-lived session credential',
+                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: { '200': jsonResp('The minted credential', derive(EphemeralKeyResponseSchema, 'output')) },
+            },
+        },
+        '/v1/claims/{claimId}': {
+            get: {
+                tags: ['claims'],
+                summary: 'Poll a claim for its current state',
+                description: 'How a caller without a persistent connection learns its queued claim ' +
+                    'was granted. `position` is advisory — a privileged reorder can move it ' +
+                    'up — so branch on `status`, never on position.',
+                parameters: [{ name: 'claimId', in: 'path', required: true, schema: { type: 'string' } }],
+                responses: { '200': jsonResp('The claim state', derive(claimStateSchema, 'output')) },
+            },
+            delete: {
+                tags: ['claims'],
+                summary: 'Release a claim, or leave the wait line',
+                description: 'The same call for both: releasing a held lease and abandoning a queued ' +
+                    'position are one operation, because a queue entry is a lease in a ' +
+                    'different state.',
+                parameters: [{ name: 'claimId', in: 'path', required: true, schema: { type: 'string' } }],
+                responses: { '200': jsonResp('Released', { type: 'object' }) },
+            },
+        },
+        '/v1/capabilities': {
+            post: {
+                tags: ['credentials'],
+                summary: 'Mint a capability for an agent or system',
+                description: 'A scoped, revocable grant. Narrow by default: an agent or system ' +
+                    'capability must name its `syncGroups` and `operations`.',
+                requestBody: jsonBody(derive(capabilityRequestSchema, 'input')),
+                responses: { '200': jsonResp('The minted capability', { type: 'object' }) },
+            },
+        },
+        '/v1/capabilities/{id}': {
+            get: {
+                tags: ['credentials'],
+                summary: 'Inspect a capability',
+                parameters: [idParam()],
+                responses: { '200': jsonResp('The capability', { type: 'object' }) },
+            },
+            delete: {
+                tags: ['credentials'],
+                summary: 'Revoke a capability',
+                parameters: [idParam()],
+                responses: { '200': jsonResp('Revoked', { type: 'object' }) },
+            },
+        },
+        '/v1/capabilities/{id}/rotate': {
+            post: {
+                tags: ['credentials'],
+                summary: 'Rotate a capability, keeping its grant',
+                parameters: [idParam()],
+                responses: { '200': jsonResp('The rotated capability', { type: 'object' }) },
+            },
+        },
+        '/v1/commits': {
+            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.' }],
+                requestBody: commitBody(),
+                responses: { '200': commitReceipt() },
+            },
+        },
+    };
+    return envelope(options, 'The Ablo transaction layer: commit, read, and claim. `{model}` is any model ' +
+        'from your pushed schema — the routes are the same whichever it is. ' +
+        'Authenticate every request with your API key as a Bearer token.', paths, {});
+}
+/**
+ * The per-tenant expansion: every model's routes written out with typed payloads.
+ *
+ * Useful when you want generated types for one schema — five paths per model, so
+ * it grows with the schema and is regenerated on every push. It documents the
+ * same five routes {@link abloOpenApi} describes; it does not describe a
+ * different API.
+ */
+export function schemaToOpenApi(schema, options = {}) {
+    const models = schema.models;
+    const paths = {};
+    const schemas = {};
+    for (const [key, def] of Object.entries(models)) {
+        const ref = { $ref: `#/components/schemas/${pascal(key)}` };
+        const properties = { id: { type: 'string' } };
+        const required = ['id'];
+        const createProps = {};
+        for (const [fname, fmeta] of Object.entries(def.fields)) {
+            const fs = fieldSchema(fmeta);
+            properties[fname] = fs;
+            createProps[fname] = fs;
+            if (!fmeta.isOptional)
+                required.push(fname);
+        }
+        schemas[pascal(key)] = { type: 'object', properties, required };
+        const createBody = jsonBody({ type: 'object', properties: createProps });
+        paths[`/v1/models/${key}`] = {
+            get: {
+                tags: [key],
+                summary: `List ${key}`,
+                parameters: listQueryParams(),
+                responses: {
+                    '200': jsonResp('List of rows', {
+                        type: 'object',
+                        properties: { object: { type: 'string', enum: ['list'] }, data: { type: 'array', items: ref } },
+                    }),
+                },
+            },
+            post: { tags: [key], summary: `Create a ${key}`, requestBody: createBody, responses: { '200': commitReceipt() } },
+        };
+        paths[`/v1/models/${key}/{id}`] = {
+            get: {
+                tags: [key],
+                summary: `Retrieve a ${key}`,
+                parameters: [idParam()],
+                responses: {
+                    '200': jsonResp('The row', {
+                        type: 'object',
+                        properties: { data: ref, stamp: { type: 'integer' } },
+                    }),
+                },
+            },
+            patch: { tags: [key], summary: `Update a ${key}`, parameters: [idParam()], requestBody: createBody, responses: { '200': commitReceipt() } },
+            delete: { tags: [key], summary: `Delete a ${key}`, parameters: [idParam()], responses: { '200': commitReceipt() } },
+        };
+        paths[`/v1/models/${key}/{id}/claim`] = {
+            post: { tags: [key], summary: `Claim a ${key} (acquire lease)`, parameters: [idParam()], responses: { '200': jsonResp('Claim acquired', { type: 'object' }) } },
+            delete: { tags: [key], summary: `Release a ${key} claim`, parameters: [idParam()], responses: { '200': jsonResp('Released', { type: 'object' }) } },
+        };
+        paths[`/v1/models/${key}/{id}/claim/heartbeat`] = {
+            post: { tags: [key], summary: `Heartbeat a held ${key} claim (extend the lease for long-running work)`, parameters: [idParam()], responses: { '200': jsonResp('Lease extended (or queued slot refreshed)', derive(claimHeartbeatReplySchema, 'output')) } },
+        };
+        paths[`/v1/models/${key}/{id}/claim/reorder`] = {
+            post: { tags: [key], summary: `Reorder the ${key} wait-line (privileged)`, parameters: [idParam()], responses: { '200': jsonResp('Reordered', { type: 'object' }) } },
+        };
+    }
+    paths['/v1/commits'] = {
+        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.' }],
+            requestBody: commitBody(),
+            responses: { '200': commitReceipt() },
+        },
+    };
+    return envelope(options, 'Generated from your pushed Ablo schema — these routes are your models. ' +
+        'Authenticate every request with your API key as a Bearer token.', paths, schemas);
+}

package/dist/{schema → transaction/schema}/relation.d.ts

@@ -22,7 +22,7 @@
  * `index: true` registers a foreign-key index for the child model when the
  * engine starts, turning "every child that points at this parent" from a full
  * scan into a constant-time lookup. Reach for it on relations you query this
- * way often, such as a slide layer's `slideId`.
+ * 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
@@ -44,11 +44,11 @@
  * relax the foreign-key check itself. For example:
  *
  *   ```ts
- *   layouts: model({ deckId: z.string().nullish() }, {
- *     // The deck-owns-layout link is nullable and the layout is always
- *     // created first; marking it `defer` lets the deck commit ahead of the
+ *   layouts: model({ reportId: z.string().nullish() }, {
+ *     // The report-owns-layout link is nullable and the layout is always
+ *     // created first; marking it `defer` lets the report commit ahead of the
  *     // layout instead of sharing its insert-order slot.
- *     deck: relation.belongsTo('slideDecks', 'deckId', { defer: true }),
+ *     report: relation.belongsTo('reports', 'reportId', { defer: true }),
  *   }),
  *   ```
  */
@@ -65,14 +65,14 @@ export interface BelongsToOptions {
      * container to the things it holds, as a folder does to its files.
      *
      * Do not set `parent` on a reference that merely points at another record for
-     * provenance or as a template, such as `sourceSlideId` or `templateId`; doing
+     * 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
      * parent edge explicitly.
      *
      * It reads naturally at the call site:
-     * `belongsTo('deck', 'deckId', { parent: true })` — the deck is the parent.
+     * `belongsTo('report', 'reportId', { parent: true })` — the report is the parent.
      */
     readonly parent?: boolean;
     /**
@@ -84,7 +84,7 @@ export interface BelongsToOptions {
      *
      * Set `fk: true` only when the target row lives in the same database and is
      * written in the same commit as this row, and points at a strong, contained
-     * entity. Leave it off provenance or template pointers (`sourceSlideId`,
+     * entity. Leave it off provenance or template pointers (`sourceSectionId`,
      * `templateId`), cross-tenant references, or anything that may be written in a
      * different transaction than its target — a hard constraint there would reject
      * the write and break out-of-order sync. The constraint is emitted as
@@ -157,7 +157,7 @@ export declare const relation: {
      * project: relation.belongsTo('projects', 'projectId'),
      *
      * // Register an FK index for O(1) child lookups
-     * slide: relation.belongsTo('slides', 'slideId', { index: true }),
+     * section: relation.belongsTo('sections', 'sectionId', { index: true }),
      *
      * // Auto-populate the parent on delta arrival
      * team: relation.belongsTo('teams', 'teamId', { enrich: true }),
@@ -167,7 +167,7 @@ export declare const relation: {
      *
      * // Mark the soft side of a cycle so the priority computer breaks
      * // the cycle deterministically instead of tying the two models.
-     * deck: relation.belongsTo('slideDecks', 'deckId', { defer: true }),
+     * report: relation.belongsTo('reports', 'reportId', { defer: true }),
      * ```
      */
     readonly belongsTo: <Target extends string, Field extends string, const Opts extends BelongsToOptions = Record<string, never>>(target: Target, foreignKey: Field, options?: Opts) => RelationDef<"belongsTo", Target, Field, Opts>;
@@ -180,11 +180,11 @@ export declare const relation: {
      * child model automatically.
      *
      * ```ts
-     * slides: relation.hasMany('slideLayers', 'slideId'),
-     * // → deck.slides returns all SlideLayer[] where slideId === deck.id
+     * blocks: relation.hasMany('blocks', 'sectionId'),
+     * // → section.blocks returns all Block[] where sectionId === section.id
      *
-     * slides: relation.hasMany('slideLayers', 'slideId', { orderBy: 'zIndex' }),
-     * // → deck.slides returns SlideLayer[] sorted by zIndex ascending
+     * blocks: relation.hasMany('blocks', 'sectionId', { orderBy: 'zIndex' }),
+     * // → section.blocks returns Block[] sorted by zIndex ascending
      * ```
      */
     readonly hasMany: <Target extends string, Field extends string>(target: Target, foreignKey: Field, options?: {

package/dist/{schema → transaction/schema}/relation.js

@@ -33,7 +33,7 @@ class RelationBuilder {
      * Stashed by `hasMany` when the caller provides `{ orderBy }`. Read
      * back in `createSyncEngine` to install the sort comparator on the
      * generated relation getter. Declared on the builder so both writer
-     * and reader stay type-safe — no `as unknown as Record<...>` smuggle.
+     * and reader stay type-safe — no double-cast smuggle through `Record<...>`.
      */
     _orderBy;
     constructor(type, target, foreignKey, options) {
@@ -55,7 +55,7 @@ export const relation = {
      * project: relation.belongsTo('projects', 'projectId'),
      *
      * // Register an FK index for O(1) child lookups
-     * slide: relation.belongsTo('slides', 'slideId', { index: true }),
+     * section: relation.belongsTo('sections', 'sectionId', { index: true }),
      *
      * // Auto-populate the parent on delta arrival
      * team: relation.belongsTo('teams', 'teamId', { enrich: true }),
@@ -65,7 +65,7 @@ export const relation = {
      *
      * // Mark the soft side of a cycle so the priority computer breaks
      * // the cycle deterministically instead of tying the two models.
-     * deck: relation.belongsTo('slideDecks', 'deckId', { defer: true }),
+     * report: relation.belongsTo('reports', 'reportId', { defer: true }),
      * ```
      */
     belongsTo(target, foreignKey, options) {
@@ -80,11 +80,11 @@ export const relation = {
      * child model automatically.
      *
      * ```ts
-     * slides: relation.hasMany('slideLayers', 'slideId'),
-     * // → deck.slides returns all SlideLayer[] where slideId === deck.id
+     * blocks: relation.hasMany('blocks', 'sectionId'),
+     * // → section.blocks returns all Block[] where sectionId === section.id
      *
-     * slides: relation.hasMany('slideLayers', 'slideId', { orderBy: 'zIndex' }),
-     * // → deck.slides returns SlideLayer[] sorted by zIndex ascending
+     * blocks: relation.hasMany('blocks', 'sectionId', { orderBy: 'zIndex' }),
+     * // → section.blocks returns Block[] sorted by zIndex ascending
      * ```
      */
     hasMany(target, foreignKey, options) {

package/dist/{schema → transaction/schema}/residency.d.ts

@@ -27,12 +27,3 @@ export declare const residencySchema: z.ZodEnum<{
 export type ModelResidency = z.infer<typeof residencySchema>;
 /** Default residency for a model that doesn't declare one — the tenant data plane. */
 export declare const DEFAULT_RESIDENCY: ModelResidency;
-/** @deprecated Use `residencySchema`. */
-export declare const planeSchema: z.ZodEnum<{
-    tenant: "tenant";
-    control: "control";
-}>;
-/** @deprecated Use `ModelResidency`. */
-export type SchemaPlane = ModelResidency;
-/** @deprecated Use `DEFAULT_RESIDENCY`. */
-export declare const DEFAULT_PLANE: "tenant";

package/dist/{schema → transaction/schema}/residency.js

@@ -23,8 +23,3 @@ import { z } from 'zod';
 export const residencySchema = z.enum(['tenant', 'control']);
 /** Default residency for a model that doesn't declare one — the tenant data plane. */
 export const DEFAULT_RESIDENCY = 'tenant';
-// ── Deprecated aliases (published schema subpath) ───────────────────────────
-/** @deprecated Use `residencySchema`. */
-export const planeSchema = residencySchema;
-/** @deprecated Use `DEFAULT_RESIDENCY`. */
-export const DEFAULT_PLANE = DEFAULT_RESIDENCY;

package/dist/{schema → transaction/schema}/roles.d.ts

@@ -14,7 +14,7 @@ import { z } from 'zod';
  *     Reads fields off an identity context (`organizationId`, `teamIds`).
  *
  *   • {@link EntityRole} — "which groups does this *record* live in?" Reads
- *     fields off the record itself (`id`, `deckId`), so the server can fan a
+ *     fields off the record itself (`id`, `reportId`), so the server can fan a
  *     committed delta to the right entity streams regardless of what the
  *     committer was subscribed to.
  *
@@ -110,11 +110,11 @@ export type Role = z.infer<typeof roleSchema>;
 export type IdentityRole = Role;
 /**
  * Record-anchored role. Reads a record field; `kind` names the group. A record
- * can route to a group keyed by its own `id` *or* a foreign key like `deckId`.
+ * can route to a group keyed by its own `id` *or* a foreign key like `reportId`.
  *
  * ```ts
- * entityRole({ kind: 'deck', source: 'id' })      // a deck → deck:<id>
- * entityRole({ kind: 'deck', source: 'deckId' })  // a layer → its parent deck
+ * entityRole({ kind: 'report', source: 'id' })        // a report → report:<id>
+ * entityRole({ kind: 'report', source: 'reportId' })  // a block → its parent report
  * ```
  */
 export type EntityRole = Role;
@@ -203,7 +203,7 @@ export declare function entityRole(spec: {
 /**
  * Evaluate a {@link RoleSource} against a context. Absent or falsy fields yield
  * `[]`, so a role whose field isn't present (a user with no `teamIds`, a record
- * with no `deckId`) is a silent no-op.
+ * with no `reportId`) is a silent no-op.
  */
 export declare function extractRoleIds(context: RoleContext, source: RoleSource): readonly string[];
 /** Identity-side name for {@link extractRoleIds}. */

package/dist/{schema → transaction/schema}/roles.js

@@ -14,7 +14,7 @@ import { z } from 'zod';
  *     Reads fields off an identity context (`organizationId`, `teamIds`).
  *
  *   • {@link EntityRole} — "which groups does this *record* live in?" Reads
- *     fields off the record itself (`id`, `deckId`), so the server can fan a
+ *     fields off the record itself (`id`, `reportId`), so the server can fan a
  *     committed delta to the right entity streams regardless of what the
  *     committer was subscribed to.
  *
@@ -73,7 +73,7 @@ export function identityAnchor(kind, id) {
 // ── Role source ─────────────────────────────────────────────────────────────
 /** Validates how a role pulls ids out of a context (identity or record). */
 export const roleSourceSchema = z.object({
-    /** The context field to read, e.g. `'organizationId'`, `'id'`, `'deckId'`. */
+    /** The context field to read, e.g. `'organizationId'`, `'id'`, `'reportId'`. */
     field: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, 'source must be a valid identifier'),
     /**
      * When `true`, `field` holds an array; every non-empty string element yields
@@ -88,7 +88,7 @@ export const roleSourceSchema = z.object({
  * no template/placeholder for the author to get wrong.
  */
 export const roleSchema = z.object({
-    kind: z.string().regex(/^[a-z][a-z0-9_]*$/, 'kind must be a lowercase identifier, e.g. "deck"'),
+    kind: z.string().regex(/^[a-z][a-z0-9_]*$/, 'kind must be a lowercase identifier, e.g. "report"'),
     source: roleSourceSchema,
 });
 /** Validates an {@link IdentityRole}. */
@@ -102,7 +102,7 @@ export const entityRoleSchema = roleSchema;
  */
 export const scopeSchema = z.union([
     z.boolean(),
-    z.string().regex(/^[a-z][a-z0-9_]*$/, 'scope kind must be a lowercase identifier, e.g. "dataroom"'),
+    z.string().regex(/^[a-z][a-z0-9_]*$/, 'scope kind must be a lowercase identifier, e.g. "workspace"'),
 ]);
 /**
  * Validates a model's `grants` membership edge. Both values are relation names
@@ -148,7 +148,7 @@ export function entityRole(spec) {
 /**
  * Evaluate a {@link RoleSource} against a context. Absent or falsy fields yield
  * `[]`, so a role whose field isn't present (a user with no `teamIds`, a record
- * with no `deckId`) is a silent no-op.
+ * with no `reportId`) is a silent no-op.
  */
 export function extractRoleIds(context, source) {
     const raw = context[source.field];

package/dist/{schema → transaction/schema}/schema.d.ts

@@ -141,7 +141,7 @@ export type BaseModelFields = z.infer<typeof baseFieldsSchema>;
  * input types, since methods are not valid input.
  */
 export interface BaseModelMethods {
-    /** Wire-format model name (e.g. `'Slide'`, `'Comment'`). */
+    /** Wire-format model name (e.g. `'Section'`, `'Comment'`). */
     getModelName(): string;
     /** Plain-object serialization suitable for sending over the wire. */
     toJSON(): Record<string, unknown>;
@@ -208,9 +208,11 @@ type RegisteredSchema = import('../types/global.js').Register extends {
  */
 export type Model<A, B = never> = [B] extends [never] ? A extends keyof RegisteredSchema['models'] ? InferModel<RegisteredSchema, A> : never : A extends Schema ? InferModel<A, B extends keyof A['models'] ? B : never> : never;
 /**
- * @deprecated Use {@link Model} instead — `Model<typeof schema, 'tasks'>` reads
- * as the domain ("the Task model from my schema") rather than the machinery.
- * Kept as an alias with no behavioral difference.
+ * The row type {@link Model} resolves to. Internal: `Model<typeof schema,
+ * 'tasks'>` is the published spelling, because it reads as the domain rather
+ * than the machinery. This one is no longer exported from any subpath — it
+ * stays because `Model` is defined in terms of it, not as a second name for
+ * the same idea.
  */
 export type InferModel<S extends Schema, ModelName extends keyof S['models']> = S['models'][ModelName] extends ModelDef<infer Shape, infer R, infer C> ? // `Omit<…, keyof BaseModelFields>` so a model that (wrongly) redeclares a
 Omit<z.infer<z.ZodObject<Shape>>, keyof BaseModelFields> & BaseModelFields & BaseModelMethods & InferComputed<C> & InferRelations<S, R> : never;
@@ -218,7 +220,7 @@ Omit<z.infer<z.ZodObject<Shape>>, keyof BaseModelFields> & BaseModelFields & Bas
  * Infer the relation accessor types from a model's relations record.
  *
  * At runtime the engine installs a getter for each declared relation, so this
- * type mirrors them and you can read `slide.layers` and `slide.deck` without a
+ * type mirrors them and you can read `section.blocks` and `section.report` without a
  * cast.
  *
  * - `hasMany` → `InferModel<S, Target>[]`
@@ -226,7 +228,7 @@ Omit<z.infer<z.ZodObject<Shape>>, keyof BaseModelFields> & BaseModelFields & Bas
  *   when the foreign key is unset or the parent has not loaded yet)
  *
  * Kept `readonly` because the accessors are getters with no setter — assigning
- * to `slide.layers` would have no effect at runtime.
+ * to `section.blocks` would have no effect at runtime.
  */
 export type InferRelations<S extends Schema, R extends RelationRecord> = string extends keyof R ? unknown : {
     readonly [K in keyof R]: R[K] extends RelationDef<infer Type, infer Target> ? Target extends keyof S['models'] ? Type extends 'hasMany' ? InferModel<S, Target>[] : Type extends 'hasOne' | 'belongsTo' ? InferModel<S, Target> | undefined : never : never : never;
@@ -239,7 +241,7 @@ export type InferRelations<S extends Schema, R extends RelationRecord> = string
  *
  * Relations (`hasMany` / `belongsTo`) are store-backed getters that exist only
  * on the pool's model instances, so a reactive row honestly omits them —
- * reading `row.layers` is a compile error instead of a silent `undefined`.
+ * reading `row.blocks` is a compile error instead of a silent `undefined`.
  * Compose relations through a selector or hook instead.
  *
  * The same pairing other data layers converged on: Zero's data-only `Row<...>`
@@ -253,12 +255,12 @@ Omit<z.infer<z.ZodObject<Shape>>, keyof BaseModelFields> & BaseModelFields & Inf
  * `ablo/register.ts` registers the schema, a single argument is all it takes:
  *
  * ```ts
- * type SlideRow = Row<'slides'>;    // data fields + computeds, no relations
- * type Slide    = Model<'slides'>;  // the pool's model instance
+ * type SectionRow = Row<'sections'>;    // data fields + computeds, no relations
+ * type Section    = Model<'sections'>;  // the pool's model instance
  * ```
  *
  * Without that registration, or for a second schema, pass the schema
- * explicitly: `Row<typeof schema, 'slides'>`.
+ * explicitly: `Row<typeof schema, 'sections'>`.
  */
 export type Row<A, B = never> = [B] extends [never] ? A extends keyof RegisteredSchema['models'] ? InferRow<RegisteredSchema, A> : never : A extends Schema ? InferRow<A, B extends keyof A['models'] ? B : never> : never;
 /**