@abloatai/ablo 0.34.0 → 0.35.0

package/dist/transaction/schema/loadStrategy.d.ts

@@ -0,0 +1,45 @@
+/**
+ * When a model's rows are loaded from the server.
+ *
+ *   - `instant` — loaded during bootstrap, before the model is first used.
+ *   - `lazy`    — loaded all at once on first access.
+ *
+ * One declaration serves both sides of the seam. `LoadStrategy.instant` is the
+ * value the engine branches on once a model is registered; `'instant'` is the
+ * word an author writes in `model(…, { load })`. They are the same name because
+ * they are the same axis — a const object merged with the type of its own
+ * values, rather than an enum, because a string enum is nominal and would
+ * refuse the plain `'instant'` an author actually types.
+ *
+ * The set is deliberately this small. It previously named `partial`,
+ * `explicitlyRequested`, and `local` on the runtime side and `manual` on the
+ * authoring side, and not one of those was reachable end to end: `manual` had
+ * no implementation and resolved to `lazy`, while the other three had no way to
+ * be declared. A member no schema can produce, or no branch can observe, is a
+ * promise the engine has no way to keep.
+ */
+export declare const LoadStrategy: {
+    /** Loaded during startup, before it is first used — for models needed right away. */
+    readonly instant: "instant";
+    /** Loaded all at once the first time it is needed — for secondary models. */
+    readonly lazy: "lazy";
+};
+export type LoadStrategy = (typeof LoadStrategy)[keyof typeof LoadStrategy];
+/** The strategy a model gets when it declares none. */
+export declare const DEFAULT_LOAD_STRATEGY: LoadStrategy;
+/**
+ * Whether a model's rows arrive in the bootstrap payload rather than on first
+ * access. This is the question the client asks when it builds the bootstrap
+ * subscription and the question the server asks when it assembles the payload,
+ * and the two must answer it identically or a model is requested by one side
+ * and withheld by the other.
+ *
+ * It is a function rather than a comparison spelled at each site because the
+ * sites disagreed about how to spell it: one asked `load !== 'lazy'`, another
+ * `load === 'instant'`, a third `load === 'lazy' ? … : …`. Against a two-member
+ * set those are the same predicate, so nothing failed. Against a third member
+ * they are three different predicates, and the first would have enrolled it in
+ * bootstrap while the second withheld it — the kind of split that surfaces as
+ * rows that never arrive, far from the line that caused it.
+ */
+export declare function loadsAtBootstrap(load: LoadStrategy | undefined): boolean;

package/dist/transaction/schema/loadStrategy.js

@@ -0,0 +1,46 @@
+/**
+ * When a model's rows are loaded from the server.
+ *
+ *   - `instant` — loaded during bootstrap, before the model is first used.
+ *   - `lazy`    — loaded all at once on first access.
+ *
+ * One declaration serves both sides of the seam. `LoadStrategy.instant` is the
+ * value the engine branches on once a model is registered; `'instant'` is the
+ * word an author writes in `model(…, { load })`. They are the same name because
+ * they are the same axis — a const object merged with the type of its own
+ * values, rather than an enum, because a string enum is nominal and would
+ * refuse the plain `'instant'` an author actually types.
+ *
+ * The set is deliberately this small. It previously named `partial`,
+ * `explicitlyRequested`, and `local` on the runtime side and `manual` on the
+ * authoring side, and not one of those was reachable end to end: `manual` had
+ * no implementation and resolved to `lazy`, while the other three had no way to
+ * be declared. A member no schema can produce, or no branch can observe, is a
+ * promise the engine has no way to keep.
+ */
+export const LoadStrategy = {
+    /** Loaded during startup, before it is first used — for models needed right away. */
+    instant: 'instant',
+    /** Loaded all at once the first time it is needed — for secondary models. */
+    lazy: 'lazy',
+};
+/** The strategy a model gets when it declares none. */
+export const DEFAULT_LOAD_STRATEGY = LoadStrategy.instant;
+/**
+ * Whether a model's rows arrive in the bootstrap payload rather than on first
+ * access. This is the question the client asks when it builds the bootstrap
+ * subscription and the question the server asks when it assembles the payload,
+ * and the two must answer it identically or a model is requested by one side
+ * and withheld by the other.
+ *
+ * It is a function rather than a comparison spelled at each site because the
+ * sites disagreed about how to spell it: one asked `load !== 'lazy'`, another
+ * `load === 'instant'`, a third `load === 'lazy' ? … : …`. Against a two-member
+ * set those are the same predicate, so nothing failed. Against a third member
+ * they are three different predicates, and the first would have enrolled it in
+ * bootstrap while the second withheld it — the kind of split that surfaces as
+ * rows that never arrive, far from the line that caused it.
+ */
+export function loadsAtBootstrap(load) {
+    return (load ?? DEFAULT_LOAD_STRATEGY) === LoadStrategy.instant;
+}

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

@@ -1,7 +1,8 @@
 /**
- * Defines a model — one table's worth of fields plus its relations and options. A
- * model is a Zod object schema paired with optional relation definitions; the row
- * type is inferred directly from Zod, with no separate type system to keep in sync.
+ * Defines a model — one table's worth of fields, and one options object holding
+ * everything else the engine needs to know about it. A model is a Zod object schema
+ * paired with those options; the row type is inferred directly from Zod, with no
+ * separate type system to keep in sync.
  *
  * Usage:
  *   import { z } from 'zod';
@@ -12,7 +13,8 @@
  *     status: z.enum(['todo', 'doing', 'done']).default('todo'),
  *     projectId: z.string().optional(),
  *   }, {
- *     project: relation.belongsTo('projects', 'projectId'),
+ *     relations: { project: relation.belongsTo('projects', 'projectId') },
+ *     load: 'lazy',
  *   });
  */
 import { z } from 'zod';
@@ -24,14 +26,8 @@ export type { ScopedViaRef, Tenancy, PolicyInput } from './tenancy.js';
 import { type ModelResidency } from './residency.js';
 import type { ConflictAxis } from '../policy/types.js';
 export type { ConflictAxis } from '../policy/types.js';
-/**
- * Controls when model data is loaded from the server.
- *
- * - `'instant'` — loaded during bootstrap (appears immediately on page load)
- * - `'lazy'`    — loaded on first access (e.g., when you navigate to a page that needs it)
- * - `'manual'`  — only loaded when you explicitly call sync.model.load()
- */
-export type LoadStrategy = 'instant' | 'lazy' | 'manual';
+import { LoadStrategy } from './loadStrategy.js';
+export { LoadStrategy, DEFAULT_LOAD_STRATEGY, loadsAtBootstrap } from './loadStrategy.js';
 /** A record of relation definitions */
 export type RelationRecord = Record<string, RelationDef>;
 /**
@@ -58,11 +54,26 @@ export interface PersistOptions {
 export interface GrantsRef {
     /** Relation name pointing at the identity that gains access (e.g. `'user'`). */
     subject: string;
-    /** Relation name pointing at the scope-root entity (e.g. `'dataroom'`). */
+    /** Relation name pointing at the scope-root entity (e.g. `'workspace'`). */
     scope: string;
 }
 /** Options for model() */
 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}
+     * factories.
+     *
+     * ```ts
+     * relations: {
+     *   project: relation.belongsTo('projects', 'projectId'),
+     *   comments: relation.hasMany('comments', 'taskId'),
+     * }
+     * ```
+     */
+    relations?: RelationRecord;
     /** When to load this model's data. Default: 'instant' */
     load?: LoadStrategy;
     /** Max records to bootstrap. Default: unlimited. Only applies to 'instant' strategy. */
@@ -74,7 +85,7 @@ export interface ModelOptions {
      * 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
-     * schema key `slideLayer` mapping to typename `'SlideLayer'`.
+     * schema key `block` mapping to typename `'Block'`.
      *
      * This is the one value that identifies the model on the wire; the client-side
      * store name, query result references, and delta routing all resolve through it.
@@ -98,8 +109,8 @@ export interface ModelOptions {
      *   omitted). `column` overrides the column name, which defaults to
      *   `organization_id`.
      * - `{ by: 'parent', fk, parent }` — inherit tenancy through a foreign key when the
-     *   table has no tenancy column of its own (for example `slide_layers` → slide →
-     *   deck → organization). In place of `organization_id = $1` the read emits
+     *   table has no tenancy column of its own (for example `blocks` → section →
+     *   report → organization). In place of `organization_id = $1` the read emits
      *   `WHERE <table>.<fk> IN (SELECT <parentKey> FROM <parent> WHERE
      *   <parentTenantColumn> = $1)`. Use it for any `load: 'instant'` child table that
      *   would otherwise expose other tenants' rows at bootstrap.
@@ -125,8 +136,8 @@ export interface ModelOptions {
      * optional parts:
      *
      * - `root` — marks this model a scope root, so each of its records forms the group
-     *   `<kind>:<id>`. The kind defaults to the lowercased typename (`Deck` →
-     *   `deck:<id>`); pass a string to override it (`root: 'matter'`). Child models
+     *   `<kind>:<id>`. The kind defaults to the lowercased typename (`Report` →
+     *   `report:<id>`); pass a string to override it (`root: 'matter'`). Child models
      *   inherit a root's group through their `belongsTo` relations.
      * - `grants` — a membership edge that grants an identity access to a scope root.
      *   Both values name `belongsTo` relations on this model (`subject` names the
@@ -138,7 +149,7 @@ export interface ModelOptions {
      *
      * ```ts
      * // dataroomMember: { userId, dataroomId }
-     * groups: { grants: { subject: 'user', scope: 'dataroom' } }
+     * groups: { grants: { subject: 'user', scope: 'workspace' } }
      * // a message → its addressee's inbox, keyed on `toId`
      * groups: { roles: [entityRole({ kind: 'inbox', source: 'toId' })] }
      * ```
@@ -196,7 +207,7 @@ export interface ModelOptions {
      * value.
      *
      * @example
-     * model({ title: z.string(), metadata: z.string() }, {}, {
+     * model({ title: z.string(), metadata: z.string() }, {
      *   computed: {
      *     displayTitle: (self) => self.title || `Untitled`,
      *     metadataObject: (self) => {
@@ -233,7 +244,7 @@ export interface ModelOptions {
      * loaded. Use it for foreign keys whose absence would crash code that depends on
      * them — for example a child row that cannot be placed without its parent's id.
      *
-     * @example requiredFields: ['slideId']
+     * @example requiredFields: ['sectionId']
      */
     requiredFields?: readonly string[];
 }
@@ -321,40 +332,44 @@ export interface ModelDef<Shape extends z.ZodRawShape = z.ZodRawShape, R extends
     readonly requiredFields?: readonly string[];
 }
 /**
- * Defines a model from a Zod shape, with optional relations and options. The row
- * type is inferred from the shape; fields built with the {@link field} builders
- * carry extra metadata, while plain Zod fields get metadata inferred from their Zod
- * type. The third argument sets options such as the {@link LoadStrategy}.
+ * Defines a model from a Zod shape and its options. The row type is inferred from
+ * the shape; fields built with the {@link field} builders carry extra metadata,
+ * while plain Zod fields get metadata inferred from their Zod type. Everything else
+ * about the model — its {@link ModelOptions.relations}, its {@link LoadStrategy},
+ * the table it maps to — lives in the second argument, so a model that needs one
+ * setting never has to name the settings it does not use.
  *
  * ```ts
  * import { z } from 'zod';
  * import { model, relation } from '@abloatai/ablo/schema';
  *
- * // Loaded at bootstrap (the default)
+ * // Fields alone
+ * const tags = model({ label: z.string() });
+ *
+ * // Loaded at bootstrap (the default), with an edge to its project
  * const tasks = model({
  *   title: z.string(),
  *   status: z.enum(['todo', 'doing', 'done']).default('todo'),
  *   projectId: z.string().optional(),
  * }, {
- *   project: relation.belongsTo('projects', 'projectId'),
+ *   relations: { project: relation.belongsTo('projects', 'projectId') },
  * });
  *
  * // Loaded on first access
- * const slideLayers = model({ slideId: z.string(), type: z.string() }, {
- *   slide: relation.belongsTo('slides', 'slideId'),
- * }, { load: 'lazy' });
- *
- * // Loaded only when explicitly requested
- * const auditLogs = model({ action: z.string() }, {}, { load: 'manual' });
+ * const blocks = model({ sectionId: z.string(), type: z.string() }, {
+ *   relations: { section: relation.belongsTo('sections', 'sectionId') },
+ *   load: 'lazy',
+ * });
  * ```
  */
-export declare function model<Shape extends z.ZodRawShape, R extends RelationRecord = Record<string, never>, C extends ComputedRecord = Record<string, never>>(shape: Shape, relations?: R, options?: ModelOptions & {
+export declare function model<Shape extends z.ZodRawShape, R extends RelationRecord = Record<string, never>, C extends ComputedRecord = Record<string, never>>(shape: Shape, options?: ModelOptions & {
+    relations?: R;
     computed?: C;
 }): ModelDef<Shape, R, C>;
 /**
  * Returns the sync-group kind a scope-root model produces, or `undefined` when the
  * model is not a scope root. `scope: true` derives the kind from the lowercased
- * typename (`SlideDeck` → `slidedeck`); `scope: 'deck'` sets it explicitly, which
+ * typename (`ReportSection` → `reportsection`); `scope: 'section'` sets it explicitly, which
  * you use when the wire kind must differ from the typename. This is the single place
  * that decides a record's own group, so every layer that reads it agrees.
  */

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

@@ -1,7 +1,8 @@
 /**
- * Defines a model — one table's worth of fields plus its relations and options. A
- * model is a Zod object schema paired with optional relation definitions; the row
- * type is inferred directly from Zod, with no separate type system to keep in sync.
+ * Defines a model — one table's worth of fields, and one options object holding
+ * everything else the engine needs to know about it. A model is a Zod object schema
+ * paired with those options; the row type is inferred directly from Zod, with no
+ * separate type system to keep in sync.
  *
  * Usage:
  *   import { z } from 'zod';
@@ -12,7 +13,8 @@
  *     status: z.enum(['todo', 'doing', 'done']).default('todo'),
  *     projectId: z.string().optional(),
  *   }, {
- *     project: relation.belongsTo('projects', 'projectId'),
+ *     relations: { project: relation.belongsTo('projects', 'projectId') },
+ *     load: 'lazy',
  *   });
  */
 import { z } from 'zod';
@@ -28,36 +30,44 @@ function normalizeEntityRoles(input) {
         return undefined;
     return Array.isArray(input) ? input : [input];
 }
+// ── Load strategies ───────────────────────────────────────────────────────
+// Defined in `./loadStrategy.ts`. Imported as well as re-exported: a bare
+// `export … from` would not bind the name for the `load` fields below.
+import { LoadStrategy, DEFAULT_LOAD_STRATEGY } from './loadStrategy.js';
+export { LoadStrategy, DEFAULT_LOAD_STRATEGY, loadsAtBootstrap } from './loadStrategy.js';
 // ── Model factory ─────────────────────────────────────────────────────────
 /**
- * Defines a model from a Zod shape, with optional relations and options. The row
- * type is inferred from the shape; fields built with the {@link field} builders
- * carry extra metadata, while plain Zod fields get metadata inferred from their Zod
- * type. The third argument sets options such as the {@link LoadStrategy}.
+ * Defines a model from a Zod shape and its options. The row type is inferred from
+ * the shape; fields built with the {@link field} builders carry extra metadata,
+ * while plain Zod fields get metadata inferred from their Zod type. Everything else
+ * about the model — its {@link ModelOptions.relations}, its {@link LoadStrategy},
+ * the table it maps to — lives in the second argument, so a model that needs one
+ * setting never has to name the settings it does not use.
  *
  * ```ts
  * import { z } from 'zod';
  * import { model, relation } from '@abloatai/ablo/schema';
  *
- * // Loaded at bootstrap (the default)
+ * // Fields alone
+ * const tags = model({ label: z.string() });
+ *
+ * // Loaded at bootstrap (the default), with an edge to its project
  * const tasks = model({
  *   title: z.string(),
  *   status: z.enum(['todo', 'doing', 'done']).default('todo'),
  *   projectId: z.string().optional(),
  * }, {
- *   project: relation.belongsTo('projects', 'projectId'),
+ *   relations: { project: relation.belongsTo('projects', 'projectId') },
  * });
  *
  * // Loaded on first access
- * const slideLayers = model({ slideId: z.string(), type: z.string() }, {
- *   slide: relation.belongsTo('slides', 'slideId'),
- * }, { load: 'lazy' });
- *
- * // Loaded only when explicitly requested
- * const auditLogs = model({ action: z.string() }, {}, { load: 'manual' });
+ * const blocks = model({ sectionId: z.string(), type: z.string() }, {
+ *   relations: { section: relation.belongsTo('sections', 'sectionId') },
+ *   load: 'lazy',
+ * });
  * ```
  */
-export function model(shape, relations, options) {
+export function model(shape, options) {
     // Build the fields metadata record by walking the Zod shape.
     // Fields built with `field.*()` have structured metadata; fields built
     // with raw Zod get a fallback derived from the Zod typeName.
@@ -75,8 +85,8 @@ export function model(shape, relations, options) {
         schema: z.object(shape),
         shape,
         fields,
-        relations: (relations ?? {}),
-        load: options?.load ?? 'instant',
+        relations: (options?.relations ?? {}),
+        load: options?.load ?? DEFAULT_LOAD_STRATEGY,
         bootstrapLimit: options?.bootstrapLimit,
         bootstrapOrderBy: options?.bootstrapOrderBy,
         typename: options?.typename,
@@ -102,7 +112,7 @@ export function model(shape, relations, options) {
 /**
  * Returns the sync-group kind a scope-root model produces, or `undefined` when the
  * model is not a scope root. `scope: true` derives the kind from the lowercased
- * typename (`SlideDeck` → `slidedeck`); `scope: 'deck'` sets it explicitly, which
+ * typename (`ReportSection` → `reportsection`); `scope: 'section'` sets it explicitly, which
  * you use when the wire kind must differ from the typename. This is the single place
  * that decides a record's own group, so every layer that reads it agrees.
  */

package/dist/transaction/schema/openapi.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Two OpenAPI 3.1 documents describing the same API, for two different readers.
+ *
+ * The server registers ONE parameterised route family — `/api/v1/models/:model`,
+ * `/:id`, `/:id/claim`, `/claim/heartbeat`, `/claim/reorder`, plus `/v1/commits`.
+ * Six routes, whatever a tenant's schema contains. Authentication is a single
+ * Bearer scheme, your API key.
+ *
+ * {@link abloOpenApi} publishes exactly those six. It takes no schema, so it
+ * cannot grow with one: identical for every caller, stable across every push,
+ * and the document a Python or Go client is generated from once.
+ *
+ * {@link schemaToOpenApi} expands the same six into one set per model, with
+ * payloads typed from each model's introspectable {@link FieldMeta}. Five paths
+ * per model, regenerated on every push — worth it when you want generated types
+ * for one schema, and the wrong thing to hand an agent.
+ *
+ * Both return a plain JSON-serializable object; feed either into codegen (for
+ * example `ablo openapi > openapi.json`) or serve it directly.
+ */
+import type { Schema, SchemaRecord } from './schema.js';
+/** Options for {@link schemaToOpenApi} — the metadata stamped into the generated spec. */
+export interface SchemaToOpenApiOptions {
+    /** Spec title. Default `"Ablo API"`. */
+    readonly title?: string;
+    /** Spec version. Default `"1.0.0"`. */
+    readonly version?: string;
+    /** API base URL. Default `"https://api.abloatai.com/api"`. */
+    readonly serverUrl?: string;
+}
+type Json = Record<string, unknown>;
+/**
+ * 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 declare function abloOpenApi(options?: SchemaToOpenApiOptions): Json;
+/**
+ * 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 declare function schemaToOpenApi<S extends SchemaRecord>(schema: Schema<S>, options?: SchemaToOpenApiOptions): Json;
+export {};