@abloatai/ablo 0.35.0 → 0.36.0

package/dist/transaction/schema/openapi.js

@@ -6,9 +6,12 @@ import { ABLO_HOSTED_HTTP_BASE_URL } from '../auth/hostedEndpoints.js';
 // 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 { claimRequestSchema, claimHeartbeatRequestSchema, listQuerySchema, claimStateSchema, claimAcquiredResponseSchema, claimQueuedResponseSchema, claimHeartbeatReplySchema, claimHeartbeatBatchReplySchema, claimListQuerySchema, claimListResponseSchema, claimReorderRequestSchema, claimReorderReplySchema, claimReleaseReplySchema, } from '../wire/claims.js';
 import { modelReadResponseSchema, modelListResponseSchema } from '../wire/modelResponses.js';
-import { ephemeralKeyRequestSchema, capabilityRequestSchema } from '../wire/auth.js';
+import { modelMutationRequestSchema } from '../wire/modelMutations.js';
+import { logListResponseSchema, logQuerySchema } from '../wire/feedEvent.js';
+import { schemaReadResponseSchema } from '../wire/accountResponses.js';
+import { ephemeralKeyRequestSchema, capabilityRequestSchema, capabilityMintResponseSchema, } from '../wire/auth.js';
 import { EphemeralKeyResponseSchema } from '../auth/schemas.js';
 function fieldSchema(f) {
     switch (f.type) {
@@ -61,6 +64,16 @@ const modelParam = () => ({
     description: 'A model name from your pushed schema, e.g. `task`.',
 });
 const genericRow = () => ({ type: 'object', additionalProperties: true });
+/**
+ * The body of a model-scoped write, derived from the schema the server
+ * validates it against.
+ *
+ * It was `genericRow()` — "an object" — which described the record flat and
+ * omitted the envelope entirely. A client built from that document sent the
+ * row's fields at the top level, where the server looks for `data`, and every
+ * one of them went missing at once.
+ */
+const mutationBody = () => jsonBody(derive(modelMutationRequestSchema, 'input'));
 /**
  * Fill in `data` on a derived model-response schema.
  *
@@ -81,11 +94,30 @@ function withGenericRows(derived) {
             : 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 }));
+/**
+ * Query parameters derived from the schema the route reads them with.
+ *
+ * Taking the schema as an argument rather than closing over one is what lets the
+ * claim listing publish its filters too: `GET /v1/claims` accepts six, and a
+ * hand-written parameter list beside them would be the drifting copy this file
+ * exists to avoid.
+ */
+function queryParams(schema) {
+    const props = (derive(schema, 'input').properties ?? {});
+    return Object.entries(props).map(([name, s]) => ({ name, in: 'query', schema: s }));
 }
+/**
+ * Both release routes answer in one shape. `released` distinguishes "this call
+ * ended your lease" from "there was nothing of yours to end" — both success,
+ * and a retry after a lost response deserves to know which it got.
+ */
+const releaseResp = () => jsonResp('Released', derive(claimReleaseReplySchema, 'output'));
+const claimIdParam = () => ({
+    name: 'claimId',
+    in: 'path',
+    required: true,
+    schema: { type: 'string' },
+});
 /**
  * The `POST /v1/commits` body, derived from {@link commitRequestSchema} — the
  * same schema the server validates the request against.
@@ -115,15 +147,14 @@ function envelope(options, description, paths, schemas) {
     };
 }
 /**
- * The protocol reference: the five route templates the server actually serves,
- * plus `/v1/commits`.
+ * The protocol reference: the route templates the server actually serves.
  *
  * 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.
+ * parameterised route family (`/api/v1/models/:model/...`), so the surface is
+ * the same size 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
@@ -131,25 +162,46 @@ function envelope(options, description, paths, schemas) {
  */
 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()],
+                parameters: [modelParam(), ...queryParams(listQuerySchema)],
                 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() } },
+            post: {
+                tags,
+                summary: 'Create a row',
+                description: 'The record travels in `data`; `id` is yours to choose — see the ' +
+                    'field for the derivation that makes a retry idempotent.',
+                parameters: [modelParam()],
+                requestBody: mutationBody(),
+                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() } },
+            patch: {
+                tags,
+                summary: 'Update a row',
+                description: 'Pass `claim` and `readAt` together: the lease says nobody else is ' +
+                    'writing, the watermark says the row has not moved since you read it.',
+                parameters: [modelParam(), idParam()],
+                requestBody: mutationBody(),
+                responses: { '200': commitReceipt() },
+            },
+            delete: {
+                tags,
+                summary: 'Delete a row',
+                parameters: [modelParam(), idParam()],
+                requestBody: { ...mutationBody(), required: false },
+                responses: { '200': commitReceipt() },
+            },
         },
         '/v1/models/{model}/{id}/claim': {
             post: {
@@ -165,7 +217,12 @@ export function abloOpenApi(options = {}) {
                         '`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' }) } },
+            delete: {
+                tags: ['claims'],
+                summary: 'Release a claim',
+                parameters: [modelParam(), idParam()],
+                responses: { '200': releaseResp() },
+            },
         },
         '/v1/models/{model}/{id}/claim/heartbeat': {
             post: {
@@ -179,7 +236,17 @@ export function abloOpenApi(options = {}) {
             },
         },
         '/v1/models/{model}/{id}/claim/reorder': {
-            post: { tags: ['claims'], summary: 'Reorder the wait-line (privileged)', parameters: [modelParam(), idParam()], responses: { '200': jsonResp('Reordered', { type: 'object' }) } },
+            post: {
+                tags: ['claims'],
+                summary: 'Reorder the wait-line (privileged)',
+                description: 'Name the waiters you want at the front, in the order you want them. ' +
+                    'Waiters you leave out keep their relative places behind them.',
+                parameters: [modelParam(), idParam()],
+                requestBody: optionalJsonBody(derive(claimReorderRequestSchema, 'input')),
+                responses: {
+                    '200': jsonResp('Reordered', derive(claimReorderReplySchema, 'output')),
+                },
+            },
         },
         '/v1/ephemeral_keys': {
             post: {
@@ -194,6 +261,44 @@ export function abloOpenApi(options = {}) {
                 responses: { '200': jsonResp('The minted credential', derive(EphemeralKeyResponseSchema, 'output')) },
             },
         },
+        '/v1/claims': {
+            get: {
+                tags: ['claims'],
+                summary: 'List who holds what, and who waits',
+                description: 'The coordination view: scope to a row with `model` and `id`, to a ' +
+                    'participant with `actorId`, `actorKind`, `onBehalfOfId` or ' +
+                    '`capabilityId`, or combine them. `queue` is populated only when the ' +
+                    'request names both `model` and `id` — a wait line belongs to one row.',
+                parameters: queryParams(claimListQuerySchema),
+                responses: {
+                    '200': jsonResp('Live claims, and the wait line behind the named row.', derive(claimListResponseSchema, 'output')),
+                },
+            },
+            post: {
+                tags: ['claims'],
+                summary: 'Claim a row named in the body',
+                description: 'The same operation as `POST /v1/models/{model}/{id}/claim`, with the ' +
+                    'row in `target` instead of the URL. Answers identically.',
+                requestBody: jsonBody(derive(claimRequestSchema, 'input')),
+                responses: {
+                    '201': jsonResp('The lease is yours.', derive(claimAcquiredResponseSchema, 'output')),
+                    '202': jsonResp('Already held, and you asked to queue. You are in line at `position`.', derive(claimQueuedResponseSchema, 'output')),
+                },
+            },
+        },
+        '/v1/claims/heartbeat': {
+            post: {
+                tags: ['claims'],
+                summary: 'Heartbeat every lease you hold, in one request',
+                description: 'One round trip per cadence for a worker holding many rows, instead of ' +
+                    'one per row. Takes only `ttl`; the leases are whichever ones your ' +
+                    'credential holds on this plane.',
+                requestBody: optionalJsonBody(derive(claimHeartbeatRequestSchema, 'input')),
+                responses: {
+                    '200': jsonResp('One ack per lease extended.', derive(claimHeartbeatBatchReplySchema, 'output')),
+                },
+            },
+        },
         '/v1/claims/{claimId}': {
             get: {
                 tags: ['claims'],
@@ -201,7 +306,7 @@ export function abloOpenApi(options = {}) {
                 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' } }],
+                parameters: [claimIdParam()],
                 responses: { '200': jsonResp('The claim state', derive(claimStateSchema, 'output')) },
             },
             delete: {
@@ -210,8 +315,24 @@ export function abloOpenApi(options = {}) {
                 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' }) },
+                parameters: [claimIdParam()],
+                responses: { '200': releaseResp() },
+            },
+        },
+        '/v1/claims/{claimId}/heartbeat': {
+            post: {
+                tags: ['claims'],
+                summary: 'Heartbeat a claim by id — held or queued',
+                description: 'The beat a waiter needs: a queued caller holds nothing but the ' +
+                    '`claimId` it was handed at enqueue, and an entry that stops beating ' +
+                    'drops out of the line on TTL. The reply doubles as the wait poll — ' +
+                    '`queued` means still in line, `held` means the grant landed, at which ' +
+                    'point `GET /v1/claims/{claimId}` carries the fence token.',
+                parameters: [claimIdParam()],
+                requestBody: optionalJsonBody(derive(claimHeartbeatRequestSchema, 'input')),
+                responses: {
+                    '200': jsonResp('Lease extended, or queued slot refreshed.', derive(claimHeartbeatReplySchema, 'output')),
+                },
             },
         },
         '/v1/capabilities': {
@@ -221,7 +342,14 @@ export function abloOpenApi(options = {}) {
                 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' }) },
+                responses: {
+                    // 201, not 200. The reference said 200 while the route has always
+                    // answered 201, so a generated client checking the documented code
+                    // failed on every successful mint.
+                    '201': jsonResp('The minted capability. `token` is the credential — carry it as the ' +
+                        'Bearer token on every other call. `scope` is what was minted, ' +
+                        'which is not always what was asked for.', derive(capabilityMintResponseSchema, 'output')),
+                },
             },
         },
         '/v1/capabilities/{id}': {
@@ -246,6 +374,39 @@ export function abloOpenApi(options = {}) {
                 responses: { '200': jsonResp('The rotated capability', { type: 'object' }) },
             },
         },
+        '/v1/schema': {
+            get: {
+                tags: ['schema'],
+                summary: 'What the models look like',
+                description: "The schema deployed on your credential's plane: every model with its " +
+                    'fields, their types, and its relations. Read this when you have no ' +
+                    'local schema declaration to read types from — it is what makes a ' +
+                    'field typo a local check rather than a rejected write. Each model ' +
+                    'carries a content `hash` that moves only when its shape does, so read ' +
+                    'the shape once and poll the hashes after: a refetch only ever answers ' +
+                    'a push.',
+                responses: {
+                    '200': jsonResp('The deployed schema, or `active: false` when nothing is pushed.', derive(schemaReadResponseSchema, 'output')),
+                },
+            },
+        },
+        '/v1/logs': {
+            get: {
+                tags: ['logs'],
+                summary: 'Tail what changed',
+                description: 'How a caller without a socket learns what its peers did. Omit ' +
+                    '`after` for the most recent entries, then copy each page\'s ' +
+                    '`next_cursor` back as `after` to walk forward. Scope is taken from ' +
+                    'your key — organization, plane and sync groups — so a caller cannot ' +
+                    'widen what it sees by asking.',
+                parameters: queryParams(logQuerySchema),
+                responses: {
+                    '200': jsonResp('A page of the feed, oldest first. Entries are discriminated on ' +
+                        '`object`, so a reader that meets an entry kind it does not know ' +
+                        'can skip it and keep paging.', derive(logListResponseSchema, 'output')),
+                },
+            },
+        },
         '/v1/commits': {
             post: {
                 tags: ['commits'],
@@ -290,7 +451,7 @@ export function schemaToOpenApi(schema, options = {}) {
             get: {
                 tags: [key],
                 summary: `List ${key}`,
-                parameters: listQueryParams(),
+                parameters: queryParams(listQuerySchema),
                 responses: {
                     '200': jsonResp('List of rows', {
                         type: 'object',

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

@@ -96,7 +96,13 @@ export interface BelongsToOptions {
 declare const __relationType: unique symbol;
 declare const __relationTarget: unique symbol;
 declare const __relationField: unique symbol;
-export type RelationType = 'belongsTo' | 'hasMany' | 'hasOne';
+/**
+ * The three edges the engine resolves. Inferred from `wire/modelShape.ts`
+ * rather than restated: the set is reported to callers by `GET /api/schema`,
+ * so it is protocol, and protocol has one definition.
+ */
+export type { RelationType } from '../wire/modelShape.js';
+import type { RelationType } from '../wire/modelShape.js';
 /**
  * A relation definition, carrying its type information at both the type and
  * runtime level.
@@ -196,4 +202,3 @@ export declare const relation: {
      */
     readonly hasOne: <Target extends string, Field extends string>(target: Target, foreignKey: Field) => RelationDef<"hasOne", Target, Field>;
 };
-export {};

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

@@ -23,6 +23,7 @@ import { z } from 'zod';
 import type { ModelDef, RelationRecord } from './model.js';
 import type { RelationDef } from './relation.js';
 import type { IdentityRole } from './roles.js';
+import { type FieldRef } from './fieldRef.js';
 export { type IdentityRole, type IdentityRoleSource, type IdentityContext, type EntityRole, type EntityRoleSource, type EntityContext, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, composeIdentitySyncGroups, composeEntitySyncGroups, intersectRequestedWithAllowed, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, } from './roles.js';
 /** The set of built-in casing conventions supported by `defineSchema`. */
 export type CasingConvention = 'snake_case' | 'camelCase';
@@ -150,6 +151,23 @@ export interface BaseModelMethods {
 export interface Schema<S extends SchemaRecord = SchemaRecord> {
     /** The raw model definitions */
     readonly models: S;
+    /**
+     * Every declared field as a {@link FieldRef} — the field as a value rather
+     * than a quoted name: `schema.fields.tasks.status`.
+     *
+     * A surface that names a field takes one of these instead of a string, so a
+     * name that does not exist stops compiling and a rename is a compile error at
+     * every use. Claims are the first caller; anything else that has to say
+     * "which field" should take a reference for the same reason.
+     *
+     * Base fields (`id`, `createdAt`, …) are not here: the schema does not
+     * declare them, and a caller naming one means the row, not a part of it.
+     */
+    readonly fields: {
+        readonly [K in keyof S]: S[K] extends ModelDef<infer Shape> ? {
+            readonly [F in Extract<keyof Shape, string>]: FieldRef;
+        } : never;
+    };
     /** Zod schemas with base fields merged in */
     readonly validators: {
         readonly [K in keyof S]: S[K] extends ModelDef<infer Shape> ? z.ZodObject<Shape & typeof baseFieldsSchema.shape> : never;
@@ -321,4 +339,13 @@ export type UpdateValue<S extends Schema, ModelName extends keyof S['models']> =
 export interface DeleteId<S extends Schema, ModelName extends keyof S['models']> {
     id: string;
 }
+/**
+ * One {@link FieldRef} per declared field, keyed by model then field.
+ *
+ * Every construction of a {@link Schema} goes through here — `defineSchema`,
+ * the `selectModels`/`omitModels` projections, and the deserializer — so a
+ * projection carries references for exactly the models it kept and a schema
+ * rebuilt from JSON carries them at all.
+ */
+export declare function buildFieldRefs(models: Record<string, ModelDef>): Record<string, Record<string, FieldRef>>;
 export declare function defineSchema<const S extends SchemaRecord>(models: S, options?: DefineSchemaOptions): Schema<S>;

package/dist/transaction/schema/schema.js

@@ -21,6 +21,7 @@
  */
 import { z } from 'zod';
 import { AbloValidationError } from '../errors.js';
+import { fieldRef } from './fieldRef.js';
 import { scopeSchema, grantsRefSchema } from './roles.js';
 // Sync-group roles (identity and entity) are defined in `./roles.js` and
 // re-exported here so they can also be imported from this module. See
@@ -153,6 +154,24 @@ function assertRoundTrippableCamelCase(modelName, fieldName) {
         }
     }
 }
+/**
+ * One {@link FieldRef} per declared field, keyed by model then field.
+ *
+ * Every construction of a {@link Schema} goes through here — `defineSchema`,
+ * the `selectModels`/`omitModels` projections, and the deserializer — so a
+ * projection carries references for exactly the models it kept and a schema
+ * rebuilt from JSON carries them at all.
+ */
+export function buildFieldRefs(models) {
+    const refs = {};
+    for (const [model, def] of Object.entries(models)) {
+        const perField = {};
+        for (const field of Object.keys(def.shape))
+            perField[field] = fieldRef(model, field);
+        refs[model] = perField;
+    }
+    return refs;
+}
 export function defineSchema(models, options) {
     // Build validators with base fields merged in, and resolve defaults for
     // `typename` and `persist.store` so downstream code (the loader and the
@@ -228,6 +247,7 @@ export function defineSchema(models, options) {
         // already part of ModelDef, so the shape is structurally unchanged.
         models: resolvedModels,
         validators: validators,
+        fields: buildFieldRefs(resolvedModels),
         identityRoles: options?.identityRoles ?? [],
         sessionSettings: options?.sessionSettings ?? {},
     };

package/dist/transaction/transactions/settlement/commitEnvelope.d.ts

@@ -111,8 +111,8 @@ export declare const durableCommitEnvelopeSchema: z.ZodObject<{
             }>>;
         }, z.core.$strip>]>>>>;
         track: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-            model: z.ZodString;
             id: z.ZodString;
+            model: z.ZodString;
             readAt: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>, z.ZodObject<{
             group: z.ZodString;

package/dist/transaction/transactions/settlement/pendingWrite.d.ts

@@ -67,8 +67,8 @@ export declare const pendingWriteSchema: z.ZodUnion<readonly [z.ZodObject<{
             }>>;
         }, z.core.$strip>]>>>>;
         track: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-            model: z.ZodString;
             id: z.ZodString;
+            model: z.ZodString;
             readAt: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>, z.ZodObject<{
             group: z.ZodString;

package/dist/transaction/transport/httpClient.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClientConfig } from './httpOptions.js';
-import type { CommitResource, HttpClaimApi, ModelReadOptions, CreateSessionParams, AbloSession } from '../resources/httpResources.js';
+import type { CommitResource, HttpClaimApi, HttpClaimsResource, ModelReadOptions, CreateSessionParams, AbloSession } from '../resources/httpResources.js';
 import type { ModelCreateParams, ModelDeleteParams, ServerReadOptions, ModelRetrieveParams, ModelTrackParams, ModelTrackResult, ModelUpdateParams } from '../resources/modelOperations.js';
 import type { Schema, SchemaRecord, InferModel, InferCreate } from '../schema/schema.js';
 import type { ModelUpdater, ContentionOptions } from '../resources/functionalUpdate.js';
@@ -108,6 +108,14 @@ export type AbloHttpClient<S extends SchemaRecord> = {
     /** Replays every pending durable HTTP write in seal order and waits for settlement. */
     waitForFlush(): Promise<void>;
     readonly commits: CommitResource;
+    /**
+     * Claim-ticket operations keyed by `claimId`: `retrieve` polls a queued
+     * ticket to its grant, `heartbeat` keeps one lease (held or queued) alive,
+     * `heartbeatAll` beats every lease this identity holds in one round trip.
+     * The id comes from `AbloClaimedError('claim_queued')`, which carries it on
+     * `error.claims`.
+     */
+    readonly claims: HttpClaimsResource;
     dispose(): Promise<void>;
     /** Resolves the bearer credential this client authenticates with, or `null` if none is set. */
     getAuthToken(): Promise<string | null>;

package/dist/transaction/transport/httpClient.js

@@ -29,6 +29,7 @@ const PROTOCOL_MEMBERS = new Set([
     'waitForFlush',
     'dispose',
     'commits',
+    'claims',
     'getAuthToken',
     'sessions',
 ]);