@abloatai/transaction 0.55.0 → 0.57.0

package/dist/wire/modelMutations.js.map

@@ -1 +1 @@
-{"version":3,"file":"modelMutations.js","sourceRoot":"","sources":["../../src/wire/modelMutations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,2BAA2B,EAC3B,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AAEnC,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,gFAAgF;IAChF,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACjD;;;;;;;;;;;OAWG;IACH,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE;IACxB,gEAAgE;IAChE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE;IAC3B,2EAA2E;IAC3E,OAAO,EAAE,iBAAiB,CAAC,OAAO,EAAE;IACpC;;;;OAIG;IACH,MAAM,EAAE,sBAAsB,CAAC,OAAO,EAAE;IACxC,4EAA4E;IAC5E,KAAK,EAAE,wBAAwB,CAAC,OAAO,EAAE;IACzC,uEAAuE;IACvE,KAAK,EAAE,yBAAyB,CAAC,OAAO,EAAE;IAC1C;;;OAGG;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE;IAChC,wEAAwE;IACxE,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACtC,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,2BAA2B,CAAC,KAAK,CAAC,IAAI,oBAAoB,EAAE;IAC/E,IAAI,EAAE,CAAC,OAAO,CAAC;IACf,OAAO,EAAE,uCAAuC,oBAAoB,mBAAmB;CACxF,CAAC,CAAC"}
+{"version":3,"file":"modelMutations.js","sourceRoot":"","sources":["../../src/wire/modelMutations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,2BAA2B,EAC3B,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AAEnC,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,gFAAgF;IAChF,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACjD;;;;;;;;;;;OAWG;IACH,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE;IACxB,gEAAgE;IAChE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE;IAC3B,2EAA2E;IAC3E,OAAO,EAAE,iBAAiB,CAAC,OAAO,EAAE;IACpC;;;;OAIG;IACH,MAAM,EAAE,iBAAiB,CAAC,OAAO,EAAE;IACnC,4EAA4E;IAC5E,KAAK,EAAE,wBAAwB,CAAC,OAAO,EAAE;IACzC,uEAAuE;IACvE,KAAK,EAAE,yBAAyB,CAAC,OAAO,EAAE;IAC1C;;;OAGG;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE;IAChC,wEAAwE;IACxE,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACtC,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,2BAA2B,CAAC,KAAK,CAAC,IAAI,oBAAoB,EAAE;IAC/E,IAAI,EAAE,CAAC,OAAO,CAAC;IACf,OAAO,EAAE,uCAAuC,oBAAoB,mBAAmB;CACxF,CAAC,CAAC"}

package/dist/wire/rateLimit.d.ts

@@ -0,0 +1,82 @@
+/**
+ * How a rate limit is stated on the wire, so a caller can pace itself instead
+ * of discovering the ceiling by hitting it.
+ *
+ * Two fields, from "RateLimit header fields for HTTP"
+ * (draft-ietf-httpapi-ratelimit-headers), and they answer different questions:
+ *
+ *   - `RateLimit-Policy` is the STANDING allowance — the quota and the window
+ *     the server allocates. It does not move between responses, so it can be
+ *     stated on any response, including one that carried no credential. This is
+ *     the field an agent reads once and paces against.
+ *   - `RateLimit` is the LIVE position within that allowance — what is left and
+ *     when it refills. It is per caller, so it appears only once a request has
+ *     been attributed to a credential.
+ *
+ * Both are Structured Field Lists whose members are Strings naming the policy,
+ * carrying `q`/`w` (quota, window seconds) and `r`/`t` (remaining, seconds to
+ * reset) as parameters. Serializing them by hand is the reason this module
+ * exists: the field names and the parameter spellings were previously written
+ * out at each producer, so a change had to be made in every one of them and
+ * nothing failed when it was not.
+ *
+ * `Retry-After` is not defined here — it is plain HTTP (RFC 9110 § 10.2.3) and
+ * the value is a count of seconds. Its NAME lives here so a producer emitting
+ * the 429 triple names all three fields from one place.
+ */
+import { z } from 'zod';
+/** The standing-allowance field. Safe on any response; independent of caller. */
+export declare const RATE_LIMIT_POLICY_HEADER = "RateLimit-Policy";
+/** The live-position field. Per caller, so only on an attributed request. */
+export declare const RATE_LIMIT_HEADER = "RateLimit";
+/** Seconds to wait before retrying, on a 429 or a 503 (RFC 9110 § 10.2.3). */
+export declare const RETRY_AFTER_HEADER = "Retry-After";
+/**
+ * One allocation of server capacity: how much, over how long.
+ *
+ * `quotaUnit` is omitted for the default unit, requests. A limiter that meters
+ * something else — bytes, operations — names it, and a client that does not
+ * recognize the unit knows to leave the number alone rather than read it as a
+ * request count.
+ */
+export declare const quotaPolicySchema: z.ZodObject<{
+    name: z.ZodString;
+    quota: z.ZodNumber;
+    windowSeconds: z.ZodOptional<z.ZodNumber>;
+    quotaUnit: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type QuotaPolicy = Readonly<z.infer<typeof quotaPolicySchema>>;
+/** Where this caller currently stands against one {@link QuotaPolicy}. */
+export declare const serviceLimitSchema: z.ZodObject<{
+    policy: z.ZodString;
+    remaining: z.ZodNumber;
+    resetSeconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ServiceLimit = Readonly<z.infer<typeof serviceLimitSchema>>;
+/** Serialize {@link QuotaPolicy} values into a `RateLimit-Policy` field value. */
+export declare function rateLimitPolicyField(policies: readonly QuotaPolicy[]): string;
+/** Serialize {@link ServiceLimit} values into a `RateLimit` field value. */
+export declare function rateLimitField(limits: readonly ServiceLimit[]): string;
+/** What a producer knows about the limit at the moment it writes the response. */
+export declare const rateLimitSignalSchema: z.ZodObject<{
+    policies: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        quota: z.ZodNumber;
+        windowSeconds: z.ZodOptional<z.ZodNumber>;
+        quotaUnit: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    limits: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        policy: z.ZodString;
+        remaining: z.ZodNumber;
+        resetSeconds: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>>;
+    retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type RateLimitSignal = Readonly<z.infer<typeof rateLimitSignalSchema>>;
+/**
+ * The header map for one response. This is the single call every producer
+ * makes, so the three fields cannot be emitted in one place and forgotten in
+ * the next.
+ */
+export declare function rateLimitHeaders(signal: RateLimitSignal): Record<string, string>;
+//# sourceMappingURL=rateLimit.d.ts.map

package/dist/wire/rateLimit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimit.d.ts","sourceRoot":"","sources":["../../src/wire/rateLimit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,iFAAiF;AACjF,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAE3D,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAWhD;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB;;;;;iBAS5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC;AAEtE,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB;;;;iBAO7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC;AAoBxE,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAa7E;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAYtE;AAED,kFAAkF;AAClF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;iBAOhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC,CAAC;AAE9E;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWhF"}

package/dist/wire/rateLimit.js

@@ -0,0 +1,142 @@
+/**
+ * How a rate limit is stated on the wire, so a caller can pace itself instead
+ * of discovering the ceiling by hitting it.
+ *
+ * Two fields, from "RateLimit header fields for HTTP"
+ * (draft-ietf-httpapi-ratelimit-headers), and they answer different questions:
+ *
+ *   - `RateLimit-Policy` is the STANDING allowance — the quota and the window
+ *     the server allocates. It does not move between responses, so it can be
+ *     stated on any response, including one that carried no credential. This is
+ *     the field an agent reads once and paces against.
+ *   - `RateLimit` is the LIVE position within that allowance — what is left and
+ *     when it refills. It is per caller, so it appears only once a request has
+ *     been attributed to a credential.
+ *
+ * Both are Structured Field Lists whose members are Strings naming the policy,
+ * carrying `q`/`w` (quota, window seconds) and `r`/`t` (remaining, seconds to
+ * reset) as parameters. Serializing them by hand is the reason this module
+ * exists: the field names and the parameter spellings were previously written
+ * out at each producer, so a change had to be made in every one of them and
+ * nothing failed when it was not.
+ *
+ * `Retry-After` is not defined here — it is plain HTTP (RFC 9110 § 10.2.3) and
+ * the value is a count of seconds. Its NAME lives here so a producer emitting
+ * the 429 triple names all three fields from one place.
+ */
+import { z } from 'zod';
+/** The standing-allowance field. Safe on any response; independent of caller. */
+export const RATE_LIMIT_POLICY_HEADER = 'RateLimit-Policy';
+/** The live-position field. Per caller, so only on an attributed request. */
+export const RATE_LIMIT_HEADER = 'RateLimit';
+/** Seconds to wait before retrying, on a 429 or a 503 (RFC 9110 § 10.2.3). */
+export const RETRY_AFTER_HEADER = 'Retry-After';
+/**
+ * A policy name as it appears inside the fields. Constrained to characters that
+ * need no Structured-Fields escaping, which is what lets the serializers below
+ * be a template rather than a String encoder — and what makes an unquotable
+ * name a thrown error at the definition site rather than a malformed header on
+ * the wire.
+ */
+const POLICY_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+/**
+ * One allocation of server capacity: how much, over how long.
+ *
+ * `quotaUnit` is omitted for the default unit, requests. A limiter that meters
+ * something else — bytes, operations — names it, and a client that does not
+ * recognize the unit knows to leave the number alone rather than read it as a
+ * request count.
+ */
+export const quotaPolicySchema = z.object({
+    /** Identifier the matching {@link ServiceLimit} refers back to. */
+    name: z.string(),
+    /** `q` — the allocation, in `quotaUnit`. */
+    quota: z.number(),
+    /** `w` — the window the allocation applies over, in whole seconds. */
+    windowSeconds: z.number().optional(),
+    /** `qu` — the unit `quota` counts. Omit for the default, requests. */
+    quotaUnit: z.string().optional(),
+});
+/** Where this caller currently stands against one {@link QuotaPolicy}. */
+export const serviceLimitSchema = z.object({
+    /** The {@link QuotaPolicy} name this position is measured against. */
+    policy: z.string(),
+    /** `r` — units left in the current window. */
+    remaining: z.number(),
+    /** `t` — seconds until the allocation refills. */
+    resetSeconds: z.number().optional(),
+});
+function assertName(name, field) {
+    if (!POLICY_NAME.test(name)) {
+        throw new Error(`${field} policy name ${JSON.stringify(name)} must match ${String(POLICY_NAME)}`);
+    }
+}
+/**
+ * A non-negative whole number, which is what both fields' numeric parameters
+ * are. A fractional or negative value is a producer bug; clamping it here keeps
+ * one malformed reading from making the whole field unparseable for the client.
+ */
+function integer(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.floor(value));
+}
+/** Serialize {@link QuotaPolicy} values into a `RateLimit-Policy` field value. */
+export function rateLimitPolicyField(policies) {
+    if (policies.length === 0) {
+        throw new Error(`${RATE_LIMIT_POLICY_HEADER} must name at least one policy`);
+    }
+    return policies
+        .map((policy) => {
+        assertName(policy.name, RATE_LIMIT_POLICY_HEADER);
+        let item = `"${policy.name}";q=${integer(policy.quota)}`;
+        if (policy.quotaUnit !== undefined)
+            item += `;qu="${policy.quotaUnit}"`;
+        if (policy.windowSeconds !== undefined)
+            item += `;w=${integer(policy.windowSeconds)}`;
+        return item;
+    })
+        .join(', ');
+}
+/** Serialize {@link ServiceLimit} values into a `RateLimit` field value. */
+export function rateLimitField(limits) {
+    if (limits.length === 0) {
+        throw new Error(`${RATE_LIMIT_HEADER} must name at least one policy`);
+    }
+    return limits
+        .map((limit) => {
+        assertName(limit.policy, RATE_LIMIT_HEADER);
+        let item = `"${limit.policy}";r=${integer(limit.remaining)}`;
+        if (limit.resetSeconds !== undefined)
+            item += `;t=${integer(limit.resetSeconds)}`;
+        return item;
+    })
+        .join(', ');
+}
+/** What a producer knows about the limit at the moment it writes the response. */
+export const rateLimitSignalSchema = z.object({
+    /** The standing allowance. Always known; stated on every response. */
+    policies: z.array(quotaPolicySchema).readonly(),
+    /** This caller's position, once the request has been attributed to one. */
+    limits: z.array(serviceLimitSchema).readonly().optional(),
+    /** Present only on a rejection, and only when a wait is what resolves it. */
+    retryAfterSeconds: z.number().optional(),
+});
+/**
+ * The header map for one response. This is the single call every producer
+ * makes, so the three fields cannot be emitted in one place and forgotten in
+ * the next.
+ */
+export function rateLimitHeaders(signal) {
+    const headers = {
+        [RATE_LIMIT_POLICY_HEADER]: rateLimitPolicyField(signal.policies),
+    };
+    if (signal.limits && signal.limits.length > 0) {
+        headers[RATE_LIMIT_HEADER] = rateLimitField(signal.limits);
+    }
+    if (signal.retryAfterSeconds !== undefined) {
+        headers[RETRY_AFTER_HEADER] = String(Math.max(1, integer(signal.retryAfterSeconds)));
+    }
+    return headers;
+}
+//# sourceMappingURL=rateLimit.js.map

package/dist/wire/rateLimit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimit.js","sourceRoot":"","sources":["../../src/wire/rateLimit.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/transaction",
-  "version": "0.55.0",
+  "version": "0.57.0",
   "description": "The headless Ablo transaction client and canonical contracts for reads, commits, confirmation, claims, and durable observation.",
   "license": "Apache-2.0",
   "type": "module",

package/src/auth/hostedEndpoints.ts

@@ -1,10 +1,13 @@
 /**
- * The hosted Ablo Cloud endpoint constants, with no dependencies of their own.
+ * The hosted Ablo hosts, with no dependencies of their own.
  *
- * This is the single place the hosted API host is declared. URL resolution, the
- * CLI's default URL, the data-source connector's base, the generated OpenAPI
- * server entry, and the network probe's default all import from here, so
- * changing the API domain is a one-line edit.
+ * This is the single place each published Ablo domain is declared: the API the
+ * SDK calls, the documentation site every error link and descriptor points at,
+ * and the marketing site that carries signup and the legal pages. URL
+ * resolution, the CLI's default URL, the data-source connector's base, the
+ * generated OpenAPI server entry, the error registry's `doc_url`, and the
+ * published discovery descriptors all import from here, so changing a domain is
+ * a one-line edit.
  *
  * These constants are kept dependency-free deliberately: several low-level
  * modules consume them, and routing those modules through the auth layer would
@@ -22,3 +25,18 @@ export const ABLO_HOSTED_HTTP_BASE_URL = `https://${ABLO_HOSTED_API_DOMAIN}`;
  *  {@link ABLO_HOSTED_HTTP_BASE_URL}; kept as a distinct name because it is
  *  the documented client-options default. */
 export const ABLO_DEFAULT_BASE_URL = ABLO_HOSTED_HTTP_BASE_URL;
+
+/**
+ * The documentation site. Canonical target of every error `doc_url`, of the
+ * published OpenAPI document, and of the discovery descriptors under
+ * `/.well-known`, which is why it is declared beside the API host rather than
+ * retyped at each of those call sites.
+ */
+export const ABLO_DOCS_BASE_URL = 'https://docs.abloatai.com';
+
+/**
+ * The marketing site: signup, the CLI device-flow approval page, and the legal
+ * pages a machine-readable onboarding descriptor has to cite. The apex
+ * redirects here, so this is the form to publish.
+ */
+export const ABLO_SITE_BASE_URL = 'https://www.abloatai.com';

package/src/auth/index.ts

@@ -26,8 +26,10 @@ import type {
 } from './capability.js';
 export {
   ABLO_DEFAULT_BASE_URL,
+  ABLO_DOCS_BASE_URL,
   ABLO_HOSTED_API_DOMAIN,
   ABLO_HOSTED_HTTP_BASE_URL,
+  ABLO_SITE_BASE_URL,
 } from './hostedEndpoints.js';
 export { normalizeAbloBaseUrl } from './baseUrl.js';
 

package/src/coordination/index.ts

@@ -23,7 +23,6 @@ export {
   // Layer 3 — optimistic stale-context
   onStaleModeSchema,
   MAX_READ_SET_ENTRIES,
-  readSetWatermarkSchema,
   readSetRowTargetSchema,
   readSetGroupTargetSchema,
   commitReadSetTargetSchema,
@@ -117,7 +116,6 @@ export type {
   TargetRef,
   // Layer 3 — optimistic stale-context
   OnStaleMode,
-  ReadSetWatermark,
   ReadSetRowTarget,
   ReadSetGroupTarget,
   CommitReadSetTarget,

package/src/coordination/schema.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { logPositionSchema, type LogPosition } from '../syncLog/contract.js';
 import {
   syncGroupInputSchema,
   syncGroupRefSchema,
@@ -267,10 +268,6 @@ const streamTargetSchema = targetRefSchema
 export const onStaleModeSchema = z.enum(['reject', 'overwrite', 'notify']);
 export type OnStaleMode = z.infer<typeof onStaleModeSchema>;
 
-/** The exact authoritative position retained for one ReadSet entry. */
-export const readSetWatermarkSchema = z.number().int().nonnegative();
-export type ReadSetWatermark = z.infer<typeof readSetWatermarkSchema>;
-
 /** Maximum decision-input entries one logical commit may ask the server to scan. */
 export const MAX_READ_SET_ENTRIES = 500;
 
@@ -285,7 +282,7 @@ export type TrackOnStale = z.infer<typeof trackOnStaleSchema>;
  * claim — see the claim layer below.
  */
 export const writeGuardSchema = z.object({
-  readAt: readSetWatermarkSchema.nullish(),
+  readAt: logPositionSchema.nullish(),
   onStale: onStaleModeSchema.nullish(),
   bypass: z.boolean().optional(),
 });
@@ -489,7 +486,7 @@ export type PersistedReadSetTarget = z.infer<typeof persistedReadSetTargetSchema
 /** One exact input to the decision made by this commit. */
 export const commitReadSetEntrySchema = z.object({
   target: commitReadSetTargetSchema,
-  watermark: readSetWatermarkSchema,
+  watermark: logPositionSchema,
   lifetime: z.literal('commit'),
   onStale: onStaleModeSchema,
 });
@@ -498,7 +495,7 @@ export type CommitReadSetEntry = z.infer<typeof commitReadSetEntrySchema>;
 /** One exact input retained after the declaring commit settles. */
 export const persistedReadSetEntrySchema = z.object({
   target: persistedReadSetTargetSchema,
-  watermark: readSetWatermarkSchema,
+  watermark: logPositionSchema,
   lifetime: z.literal('persisted'),
   onStale: trackOnStaleSchema,
 });

package/src/errorCodes.ts

@@ -846,6 +846,12 @@ export const ERROR_CODES = {
     false,
     'The database rejected the write on a foreign-key constraint: a referenced row does not exist, or the row being deleted is still referenced by others. The error details name the constraint.'
   ),
+  entity_already_exists: wire(
+    'conflict',
+    409,
+    false,
+    'A row already exists with this id. CREATE is strict; use UPDATE for an existing row.'
+  ),
   unique_violation: wire(
     'conflict',
     409,

package/src/errors.ts

@@ -17,6 +17,9 @@
 
 import { z } from 'zod';
 import type { ErrorCode } from './errorCodes.js';
+// Dependency-free by design, so the error registry can name the docs host
+// without pulling the auth layer into this module's import graph.
+import { ABLO_DOCS_BASE_URL } from './auth/hostedEndpoints.js';
 import { errorCodeSpec, classifyRecovery } from './errorCodes.js';
 import {
   wireClaimSummarySchema,
@@ -156,7 +159,7 @@ export class AbloError extends Error {
  * a `doc_url` automatically.
  */
 export function docUrlForCode(code: ErrorCode): string {
-  return `https://docs.abloatai.com/errors#${code}`;
+  return `${ABLO_DOCS_BASE_URL}/errors#${code}`;
 }
 
 /** 401 — invalid/missing/expired credentials. */

package/src/readSetContext.ts

@@ -97,9 +97,15 @@ export function publishCommitRecord(
   registry.commitRecords.set(record.id, record);
   try {
     const observed = registry.onCommitRecord?.(record);
-    if (observed) void Promise.resolve(observed).catch(() => undefined);
-  } catch {
+    if (observed) {
+      void Promise.resolve(observed).catch((error) => {
+        // The observer is outside the transaction outcome by contract.
+        void error;
+      });
+    }
+  } catch (error) {
     // Observability must never change a commit's outcome.
+    void error;
   }
 }
 

package/src/resources/httpResources.ts

@@ -19,9 +19,12 @@ import type {
   CommitRecordList,
   CommitRecordListOptions,
   CommitRecordWhere,
+  CommitOperationBody,
+  ModelOperationAction,
 } from '../wire/commit.js';
 import type { LogListResponse, LogQuery } from '../wire/feedEvent.js';
 import type { ModelListEvidence } from '../wire/modelResponses.js';
+import { AbloValidationError } from '../errors.js';
 // Re-exported, not redeclared. `wire/commit.ts` owns the commit-status vocabulary
 // and derives the waitable subset from it; this module serves that name to SDK
 // consumers. Restating the subset here as its own union produced a type that
@@ -63,6 +66,7 @@ import type {
   AwaitedClaimMethod,
   ModelTrackParams,
   ModelTrackResult,
+  ModelCreateManyParams,
   ServerReadOptions,
 } from './modelOperations.js';
 
@@ -77,12 +81,7 @@ import type {
  *   `claim({ id })` — a durable claim handle for coordinated writes
  */
 
-export type ModelOperationAction =
-  | 'create'
-  | 'update'
-  | 'delete'
-  | 'archive'
-  | 'unarchive';
+export type { ModelOperationAction };
 
 
 /** @internal Transport envelope; the public typed client returns the row. */
@@ -130,20 +129,119 @@ export interface HttpTransportList<T = Record<string, unknown>> {
  * and a complete one the same value, so the caller with 500 matching rows got
  * 20 and no way to find out.
  */
-export type ModelList<T> = T[] & Pick<HttpTransportList<T>, 'hasMore' | 'nextCursor'>;
+export type ModelList<T> = T[] & Pick<HttpTransportList<T>, 'hasMore' | 'nextCursor'> &
+  AsyncIterable<T>;
 
 /**
- * Attach the page state to the rows. Non-enumerable so the result stays
- * indistinguishable from a plain array everywhere the properties aren't read.
+ * How far a `for await` over a list will walk before it gives up.
+ *
+ * A cursor that stops advancing would otherwise spin forever. The bound is
+ * high enough that no real collection reaches it and low enough that a broken
+ * server is a failed read rather than a hung process.
+ */
+const AUTO_PAGE_LIMIT = 10_000;
+const LIST_ALL_PAGE_LIMIT = 100;
+
+const nextPageFor = new WeakMap<object, (cursor: string) => Promise<ModelList<unknown>>>();
+
+export interface ModelListWalkOptions {
+  readonly maxPages?: number;
+  readonly signal?: AbortSignal;
+}
+
+async function* walkModelList<T>(
+  first: ModelList<T>,
+  options: ModelListWalkOptions = {},
+): AsyncGenerator<T> {
+  const maxPages = options.maxPages ?? AUTO_PAGE_LIMIT;
+  if (!Number.isInteger(maxPages) || maxPages < 1) {
+    throw new AbloValidationError('maxPages must be a positive integer.', {
+      code: 'invalid_options',
+      param: 'maxPages',
+    });
+  }
+
+  let current = first;
+  for (let visited = 0; visited < maxPages; visited += 1) {
+    options.signal?.throwIfAborted();
+    for (let i = 0; i < current.length; i += 1) {
+      options.signal?.throwIfAborted();
+      yield current[i] as T;
+    }
+    const cursor = current.nextCursor;
+    const fetchNext = nextPageFor.get(current) as
+      | ((nextCursor: string) => Promise<ModelList<T>>)
+      | undefined;
+    if (!current.hasMore || cursor === null || fetchNext === undefined) return;
+    const next = await fetchNext(cursor);
+    if (next.nextCursor === cursor) {
+      throw new AbloValidationError(
+        `Walking this list received the same continuation cursor twice (${JSON.stringify(cursor)}). ` +
+          'The collection may be incomplete, so traversal stopped with an error.',
+        { code: 'malformed_response', param: 'nextCursor' },
+      );
+    }
+    current = next;
+  }
+  throw new AbloValidationError(
+    `Walking this list passed ${maxPages} pages without reaching the end. ` +
+      `Narrow the read with \`where\` or raise \`maxPages\` deliberately.`,
+    { code: 'invalid_options', param: 'maxPages' },
+  );
+}
+
+/** Collect a complete list through the same guarded cursor loop as async iteration. */
+export async function collectModelList<T>(
+  first: ModelList<T>,
+  options: ModelListWalkOptions = {},
+): Promise<T[]> {
+  const rows: T[] = [];
+  for await (const row of walkModelList(first, {
+    maxPages: options.maxPages ?? LIST_ALL_PAGE_LIMIT,
+    signal: options.signal,
+  })) rows.push(row);
+  return rows;
+}
+
+/**
+ * Attach the page state to the rows, and make the list walk its own pages.
+ *
+ * `hasMore` and `nextCursor` are non-enumerable, so the result stays
+ * indistinguishable from a plain array everywhere they are not read: it maps,
+ * filters, spreads, and `JSON.stringify`s exactly as the rows always did.
+ *
+ * The async iterator is the answer to the question that shape raises. A list
+ * read is a page — the server applies a default size and caps the largest —
+ * and a page of 20 looks precisely like a complete answer of 20, so every
+ * caller either checked `hasMore` or, far more often, reasoned about a
+ * truncated set without knowing it. Hand-rolled page walkers were the common
+ * result, and each one re-derived the same cursor loop and the same
+ * non-advancing-cursor guard.
+ *
+ * So iterate the value to get the page, and `for await` it to get the
+ * collection:
+ *
+ * ```ts
+ * const page = await ablo.issue.list({ where: { teamId } });
+ * for (const issue of page) …            // the 20 rows that came back
+ * for await (const issue of page) …      // every issue, paged as it goes
+ * ```
  */
 export function modelList<T>(
   rows: readonly T[],
   page: Pick<HttpTransportList<unknown>, 'hasMore' | 'nextCursor'>,
+  /** Reads the page after `cursor`. Omitted where no transport can follow. */
+  fetchNext?: (cursor: string) => Promise<ModelList<T>>,
 ): ModelList<T> {
-  return Object.defineProperties([...rows], {
+  const list = Object.defineProperties([...rows], {
     hasMore: { value: page.hasMore, enumerable: false },
     nextCursor: { value: page.nextCursor, enumerable: false },
+    [Symbol.asyncIterator]: { value: () => walkModelList(list), enumerable: false },
   }) as ModelList<T>;
+  if (fetchNext) {
+    nextPageFor.set(list, fetchNext as (cursor: string) => Promise<ModelList<unknown>>);
+  }
+  return list;
 }
 
 export type IfClaimedPolicy = 'return' | 'fail';
@@ -206,21 +304,8 @@ export interface ClaimCreateOptions {
   readonly onStatus?: (event: ClaimAttemptEvent) => void;
 }
 
-export interface CommitOperationInput {
-  readonly action: ModelOperationAction;
-  /** The model name — matches `ablo.<model>` and the schema's `model()`. */
-  readonly model: string;
-  readonly id?: string | null;
-  readonly data?: Record<string, unknown> | null;
-  readonly where?: Record<string, unknown> | null;
-  readonly transactionId?: string | null;
-  /** Claim identity derived from a held claim; not an application id. */
-  readonly claimId?: string | null;
-  readonly readAt?: number | null;
-  readonly onStale?: OnStaleMode | null;
-  /** Fencing token (Option B) from the batch's claim handle; server-validated. */
-  readonly fenceToken?: number | null;
-}
+/** Public commit operation inferred from the canonical request-body schema. */
+export type CommitOperationInput = CommitOperationBody;
 
 export interface CommitCreateOptions {
   readonly idempotencyKey?: string | null;
@@ -402,6 +487,12 @@ export interface HttpTransportModel<
    * returned, not the input.
    */
   create(params: ModelMutationOptions & { readonly data: Record<string, unknown>; readonly id?: string | null }): Promise<T>;
+  /**
+   * Creates many rows as one atomic commit and returns them, in the caller's
+   * order. One rejected row declines the batch. The rows are the server's own,
+   * carried back on the commit rather than read again afterwards.
+   */
+  createMany(params: ModelCreateManyParams<Record<string, unknown>>): Promise<T[]>;
   update(params: ModelMutationOptions & { readonly id: string; readonly data: Record<string, unknown> }): Promise<CommitReceipt>;
   /**
    * Update under contention with a function of the latest state —