@abloatai/ablo 0.34.1 → 0.36.0

package/dist/sync/groupChange.js

@@ -9,7 +9,9 @@
  * Every handler takes a {@link GroupChangeContext}, the narrow facade through
  * which it reaches the client's local storage and connection lifecycle hooks.
  */
-import { getContext } from '../context.js';
+import { globalRuntime } from '../context.js';
+/** The context's runtime, falling back to the module-global bridge. */
+const runtimeOf = (ctx) => ctx.runtime ?? globalRuntime;
 /**
  * Marker returned when a group-change payload cannot be parsed, kept distinct
  * from a valid null or absent payload, which the handlers accept normally.
@@ -22,14 +24,14 @@ const MALFORMED_PAYLOAD = Symbol('malformed-group-change-payload');
  * would leave the delta pipeline after the watermark has already advanced. The
  * delta is never re-delivered, so the security clear it carried would be lost.
  */
-function parseGroupChangePayload(delta) {
+function parseGroupChangePayload(delta, runtime) {
     if (typeof delta.data !== 'string')
         return delta.data;
     try {
         return JSON.parse(delta.data);
     }
     catch (error) {
-        getContext().logger.debug('[BaseSyncedStore] Malformed group-change payload', {
+        runtime.logger.debug('[BaseSyncedStore] Malformed group-change payload', {
             syncId: delta.id,
             actionType: delta.actionType,
             error: error instanceof Error ? error.message : String(error),
@@ -44,7 +46,7 @@ function parseGroupChangePayload(delta) {
  * re-bootstrap from the server.
  */
 async function clearForUnknownGroupChange(ctx, delta, kind) {
-    getContext().logger.debug(`[BaseSyncedStore] Unreadable ${kind} payload — clearing cached data and re-bootstrapping`, { syncId: delta.id });
+    runtimeOf(ctx).logger.debug(`[BaseSyncedStore] Unreadable ${kind} payload — clearing cached data and re-bootstrapping`, { syncId: delta.id });
     // Revoked data must not persist if the device goes offline before the
     // re-bootstrap, the same reasoning as the explicit removed-groups path.
     await ctx.database.clear();
@@ -64,7 +66,7 @@ async function clearForUnknownGroupChange(ctx, delta, kind) {
  *   and refetch), clearing cached data first if any group was removed.
  */
 export async function handleSyncGroupChange(ctx, delta) {
-    const raw = parseGroupChangePayload(delta);
+    const raw = parseGroupChangePayload(delta, runtimeOf(ctx));
     if (raw === MALFORMED_PAYLOAD) {
         // The payload is unreadable, so we cannot tell which groups changed, and
         // this delta will never be re-delivered because the watermark has already
@@ -88,7 +90,7 @@ export async function handleSyncGroupChange(ctx, delta) {
         removedGroups: rawObj.removedGroups ?? [],
         addedGroups: rawObj.addedGroups ?? [],
     };
-    getContext().logger.info('[BaseSyncedStore] Sync group change received (legacy)', {
+    runtimeOf(ctx).logger.info('[BaseSyncedStore] Sync group change received (legacy)', {
         removedGroups: payload.removedGroups,
         addedGroups: payload.addedGroups,
         syncId: delta.id,
@@ -99,7 +101,7 @@ export async function handleSyncGroupChange(ctx, delta) {
     if (payload.removedGroups.length > 0) {
         await ctx.database.clear();
         ctx.objectPool.clear();
-        getContext().logger.info('[BaseSyncedStore] Cleared cached data due to revoked sync groups', {
+        runtimeOf(ctx).logger.info('[BaseSyncedStore] Cleared cached data due to revoked sync groups', {
             removedGroups: payload.removedGroups,
         });
     }
@@ -114,7 +116,7 @@ export async function handleSyncGroupChange(ctx, delta) {
  * through the normal insert path.
  */
 export async function handleGroupAdded(ctx, payload, syncId) {
-    getContext().logger.info('[BaseSyncedStore] Group added (incremental)', {
+    runtimeOf(ctx).logger.info('[BaseSyncedStore] Group added (incremental)', {
         group: payload.group,
         syncId,
     });
@@ -130,7 +132,7 @@ export async function handleGroupAdded(ctx, payload, syncId) {
  * local state and forces a re-bootstrap with the updated group list.
  */
 export async function handleGroupRemoved(ctx, delta) {
-    const raw = parseGroupChangePayload(delta);
+    const raw = parseGroupChangePayload(delta, runtimeOf(ctx));
     if (raw === MALFORMED_PAYLOAD) {
         // The payload is unreadable: access was revoked but we cannot tell which
         // group. Fall back to a full clear, the safe direction for an
@@ -141,12 +143,12 @@ export async function handleGroupRemoved(ctx, delta) {
     const rawObj = (raw ?? {});
     const groupKey = typeof rawObj.group === 'string' ? rawObj.group : undefined;
     if (!groupKey) {
-        getContext().logger.debug('[BaseSyncedStore] Group removed delta missing group key', {
+        runtimeOf(ctx).logger.debug('[BaseSyncedStore] Group removed delta missing group key', {
             syncId: delta.id,
         });
         return;
     }
-    getContext().logger.info('[BaseSyncedStore] Group removed', {
+    runtimeOf(ctx).logger.info('[BaseSyncedStore] Group removed', {
         group: groupKey,
         syncId: delta.id,
     });
@@ -181,7 +183,7 @@ export function computeUpdatedSyncGroups(ctx, payload) {
  */
 export function forceFullRebootstrap(ctx) {
     if (ctx.getBootstrapMode() === 'none') {
-        getContext().logger.info('[BaseSyncedStore] forceFullRebootstrap skipped (bootstrapMode=none)');
+        runtimeOf(ctx).logger.info('[BaseSyncedStore] forceFullRebootstrap skipped (bootstrapMode=none)');
         return;
     }
     ctx.database.markRequiresFullBootstrap();
@@ -219,7 +221,7 @@ export async function checkSyncGroupShrinkage(ctx) {
         const currentGroups = new Set(currentSyncGroups);
         const removedGroups = stored.filter((g) => !currentGroups.has(g));
         if (removedGroups.length > 0) {
-            getContext().logger.info('[BaseSyncedStore] Sync groups shrank — forcing full bootstrap', {
+            runtimeOf(ctx).logger.info('[BaseSyncedStore] Sync groups shrank — forcing full bootstrap', {
                 removedGroups,
                 storedCount: stored.length,
                 currentCount: currentGroups.size,
@@ -235,7 +237,7 @@ export async function checkSyncGroupShrinkage(ctx) {
         });
     }
     catch (error) {
-        getContext().logger.debug('[BaseSyncedStore] Failed to check sync group shrinkage', {
+        runtimeOf(ctx).logger.debug('[BaseSyncedStore] Failed to check sync group shrinkage', {
             error: error instanceof Error ? error.message : String(error),
         });
     }

package/dist/sync/participants.d.ts

@@ -1,6 +1,7 @@
+import type { JoinOptions } from '../transaction/resources/modelOperations.js';
 import type { SyncWebSocket } from './SyncWebSocket.js';
-import type { Schema } from '../schema/schema.js';
-import type { Claim, Activity, ClaimTarget, ClaimStream, Peer, PresenceStream, PresenceTarget } from '../types/streams.js';
+import type { Schema } from '../transaction/schema/schema.js';
+import type { Claim, Activity, ClaimTarget, ClaimStream, Peer, PresenceStream, PresenceTarget } from '../transaction/types/streams.js';
 import type { AttachableClaimStream } from './createClaimStream.js';
 /**
  * The scope a participant can be joined to. The usual form is an entity target
@@ -17,7 +18,13 @@ export interface EngineParticipant {
     readonly presence: PresenceStream;
     readonly claims: ClaimStream;
 }
-export interface ParticipantJoinOptions {
+/**
+ * The options for a participant join. It extends the public per-model
+ * {@link JoinOptions} rather than restating its members, so the lease dial is
+ * declared once, in the core, and this surface adds only what a lower-level
+ * join can additionally say.
+ */
+export interface ParticipantJoinOptions extends JoinOptions {
     /**
      * The initial focus target, named in your schema's vocabulary and optionally
      * narrowed to a path, field, or range. When `scope` is omitted, this target
@@ -34,7 +41,17 @@ export interface ParticipantJoinOptions {
     readonly scope?: ParticipantScope;
     /** Present a narrower capability for this logical participant. */
     readonly capabilityToken?: string;
-    /** How long the claim lives, in seconds or a compact duration string (`30s`, `5m`). */
+    /**
+     * @deprecated Use `ttl`. Removed in 0.37.0.
+     *
+     * One lease, spelled two ways, and the seconds spelling was the one that
+     * misled: it accepted a duration string, so `ablo.<model>.join(ids, { ttl:
+     * '5m' })` reached this surface as `ttlSeconds: '5m'` — a field whose name
+     * asserts a unit its value did not carry. `ttl` takes the same values and is
+     * the spelling every other lease in the SDK already uses (`claim`'s `ttl`,
+     * `ClaimLeaseOptions.ttl`). The wire is unchanged: it has always carried
+     * seconds, and still does.
+     */
     readonly ttlSeconds?: number | string | null;
     /**
      * The activity to announce as soon as the claim is acknowledged. Defaults to
@@ -64,7 +81,7 @@ export interface ScopedClaimOptions {
     /** Peer-visible description of the work. Defaults to `'editing'`. */
     readonly description?: string;
     /** How long the claim lives; the server expires it automatically after this. */
-    readonly ttl?: import('../types/streams.js').Duration;
+    readonly ttl?: import('../transaction/types/streams.js').Duration;
 }
 export interface ScopedClaims {
     readonly focus: ClaimTarget | null;
@@ -102,7 +119,8 @@ export interface ParticipantManager {
 }
 export interface ParticipantManagerConfig {
     readonly ready: () => Promise<void>;
-    readonly getTransport: () => SyncWebSocket | null;
+    /** The connection, host-built and stable for the client's lifetime. */
+    readonly transport: SyncWebSocket;
     readonly presence: PresenceStream;
     readonly claims: AttachableClaimStream;
     readonly schema?: Schema;

package/dist/sync/participants.js

@@ -1,5 +1,6 @@
-import { scopeKindOf } from '../schema/model.js';
-import { AbloConnectionError, AbloValidationError } from '../errors.js';
+import { scopeKindOf } from '../transaction/schema/model.js';
+import { AbloValidationError } from '../transaction/errors.js';
+import { subTarget, streamTarget, wireTarget, } from '../transaction/coordination/index.js';
 export function createParticipantManager(config) {
     return {
         async join(input, overrides) {
@@ -9,15 +10,16 @@ export function createParticipantManager(config) {
                 : null;
             const syncGroups = unique(resolveParticipantSyncGroups(options.scope ?? target ?? undefined, config.schema));
             await config.ready();
-            const transport = config.getTransport();
-            if (!transport) {
-                throw new AbloConnectionError('Ablo participant join failed: WebSocket is not connected', { code: 'ws_not_ready' });
-            }
+            // Not-connected joins surface through `sendClaim`'s diagnosed
+            // rejection below; a scopeless join needs no wire send at all.
+            const transport = config.transport;
             const claimId = createParticipantClaimId();
             if (syncGroups.length > 0) {
                 await transport.sendClaim(claimId, syncGroups, {
                     capabilityToken: options.capabilityToken,
-                    ttlSeconds: parseParticipantTtlSeconds(options.ttlSeconds),
+                    // `ttl` is the spelling; `ttlSeconds` is the deprecated one, read
+                    // second so a caller passing both gets the current name honored.
+                    ttlSeconds: parseParticipantTtlSeconds(options.ttl ?? options.ttlSeconds),
                 });
             }
             const participant = createJoinedParticipant({
@@ -74,15 +76,30 @@ export function resolveParticipantSyncGroups(scope, schema) {
     }
     return out;
 }
+/**
+ * The group kind for a model, in the wire dialect every plane shares: a
+ * declared scope root wins; otherwise the lowercased typename — the same
+ * token the commit plane and claim targets use (`wireModel`). Never the
+ * camelCase schema key: the server validates inbound subscription groups
+ * against a lowercase-only grammar, so a key like `reportBlocks` would be
+ * rejected as malformed on subscribe — and even a lowercase key would put
+ * this client in a different group than a peer who resolved the same row
+ * through an entity ref, so the two would never see each other's claims.
+ */
+function groupKindForModel(def, key) {
+    return scopeKindOf(def, key) ?? (def.typename ?? key).toLowerCase();
+}
 export function syncGroupFromEntityRef(ref, schema) {
     const match = findModelForEntityRef(ref, schema);
-    const kind = match ? scopeKindOf(match.def, match.key) : undefined;
-    return `${kind ?? ref.type.toLowerCase()}:${ref.id}`;
+    const kind = match
+        ? groupKindForModel(match.def, match.key)
+        : ref.type.toLowerCase();
+    return `${kind}:${ref.id}`;
 }
 function syncGroupFromSchemaKey(schemaKey, id, schema) {
     const def = schema?.models?.[schemaKey];
-    const kind = def ? scopeKindOf(def, schemaKey) : undefined;
-    return `${kind ?? schemaKey}:${id}`;
+    const kind = def ? groupKindForModel(def, schemaKey) : schemaKey.toLowerCase();
+    return `${kind}:${id}`;
 }
 function findModelForEntityRef(ref, schema) {
     if (!schema?.models)
@@ -296,12 +313,8 @@ function createJoinedParticipant(args) {
 }
 function activityFromTarget(target) {
     return {
-        entityType: target.type,
-        entityId: target.id,
-        path: target.path,
-        range: target.range,
-        field: target.field,
-        meta: target.meta,
+        ...wireTarget(target),
+        ...subTarget(target),
     };
 }
 function presenceMatchesParticipant(entry, target, syncGroups) {
@@ -310,12 +323,8 @@ function presenceMatchesParticipant(entry, target, syncGroups) {
     if (!target)
         return true;
     return targetsOverlap({
-        type: entry.activity.entityType,
-        id: entry.activity.entityId,
-        path: entry.activity.path,
-        range: entry.activity.range,
-        field: entry.activity.field,
-        meta: entry.activity.meta,
+        ...streamTarget(entry.activity),
+        ...subTarget(entry.activity),
     }, target);
 }
 function targetsOverlap(a, b) {

package/dist/sync/schemaDrift.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The semantic schema-drift classifier — the question that matters is not
+ * "did the schema change at all?" (one whole-schema hash answers that, and
+ * welds every client to every push) but "does THIS client use anything that
+ * changed?". This module compares only the models the client declares against
+ * the server's per-model surface (`GET /api/schema`), so:
+ *
+ *   - a purely additive server change (models this build never references) is
+ *     SILENCE — deployed clients don't care what they don't use;
+ *   - a model this build declares that the server doesn't have is named, with
+ *     the push as the fix;
+ *   - a shared model whose content differs is named, so "which field moved"
+ *     is one `ablo status` away instead of a hash-guessing game.
+ *
+ * Pure and transport-free; the BootstrapFetcher owns fetching the surface.
+ */
+/** One model as the server's schema read-back reports it. */
+export interface ServerSchemaModel {
+    readonly key: string;
+    /** Per-model content hash; absent on servers older than this check. */
+    readonly hash?: string;
+}
+export type SchemaDriftFinding = 
+/** Every model this client declares exists server-side with matching content
+ *  (the server may know more — that's an additive lead, not drift). */
+{
+    readonly kind: 'aligned';
+}
+/** Models this build declares that the server has no idea about — writes to
+ *  them will be declined until the schema is pushed. */
+ | {
+    readonly kind: 'unpushed';
+    readonly models: readonly string[];
+}
+/** Shared models whose content differs between this build and the server
+ *  (may also carry unpushed models found alongside). */
+ | {
+    readonly kind: 'changed';
+    readonly models: readonly string[];
+    readonly unpushed: readonly string[];
+}
+/** The server surface carries no per-model hashes (older server) — the
+ *  caller falls back to the whole-hash comparison. */
+ | {
+    readonly kind: 'unknown';
+};
+export declare function classifySchemaDrift(clientModels: Readonly<Record<string, string>>, serverModels: readonly ServerSchemaModel[]): SchemaDriftFinding;
+/**
+ * The warning for a real, named divergence. Calm and specific: which models,
+ * what that means for this client, and the one next step. Never speaks about
+ * hashes — the point of the semantic check is that nobody has to compare hex.
+ */
+export declare function describeSchemaDrift(finding: Extract<SchemaDriftFinding, {
+    kind: 'unpushed' | 'changed';
+}>, serverLabel: string): string;

package/dist/sync/schemaDrift.js

@@ -0,0 +1,53 @@
+/**
+ * The semantic schema-drift classifier — the question that matters is not
+ * "did the schema change at all?" (one whole-schema hash answers that, and
+ * welds every client to every push) but "does THIS client use anything that
+ * changed?". This module compares only the models the client declares against
+ * the server's per-model surface (`GET /api/schema`), so:
+ *
+ *   - a purely additive server change (models this build never references) is
+ *     SILENCE — deployed clients don't care what they don't use;
+ *   - a model this build declares that the server doesn't have is named, with
+ *     the push as the fix;
+ *   - a shared model whose content differs is named, so "which field moved"
+ *     is one `ablo status` away instead of a hash-guessing game.
+ *
+ * Pure and transport-free; the BootstrapFetcher owns fetching the surface.
+ */
+export function classifySchemaDrift(clientModels, serverModels) {
+    if (serverModels.length > 0 && serverModels.every((m) => !m.hash)) {
+        return { kind: 'unknown' };
+    }
+    const server = new Map(serverModels.map((m) => [m.key, m.hash]));
+    const unpushed = [];
+    const changed = [];
+    for (const [key, hash] of Object.entries(clientModels)) {
+        const serverHash = server.get(key);
+        if (serverHash === undefined)
+            unpushed.push(key);
+        else if (serverHash !== hash)
+            changed.push(key);
+    }
+    if (changed.length > 0)
+        return { kind: 'changed', models: changed, unpushed };
+    if (unpushed.length > 0)
+        return { kind: 'unpushed', models: unpushed };
+    return { kind: 'aligned' };
+}
+/**
+ * The warning for a real, named divergence. Calm and specific: which models,
+ * what that means for this client, and the one next step. Never speaks about
+ * hashes — the point of the semantic check is that nobody has to compare hex.
+ */
+export function describeSchemaDrift(finding, serverLabel) {
+    if (finding.kind === 'unpushed') {
+        return (`Ablo: This build declares models the server at ${serverLabel} doesn't have yet ` +
+            `(${finding.models.join(', ')}). Writes to them will be declined until the schema is ` +
+            `pushed — run \`ablo push\` (and \`ablo status\` to confirm it targets this server).`);
+    }
+    const alsoUnpushed = finding.unpushed.length > 0 ? ` (${finding.unpushed.join(', ')} not pushed yet)` : '';
+    return (`Ablo: These models differ between this build and the server at ${serverLabel}: ` +
+        `${finding.models.join(', ')}${alsoUnpushed}. Reads and writes touching what changed may be ` +
+        `declined — \`ablo status\` shows the deployed shape; pushing your schema or deploying a ` +
+        `current build aligns them.`);
+}

package/dist/sync/schemas.d.ts

@@ -2,22 +2,24 @@
  * Zod validation schemas for sync engine server responses.
  *
  * Validates data at the fetch boundary before it enters the sync engine.
- * Uses .passthrough() so the server can add fields without breaking clients.
+ * Unknown keys are kept, so a server that adds a field does not break a client
+ * that predates it.
  */
 import { z } from 'zod';
+import type { RuntimeContext } from "../RuntimeContext.js";
+/**
+ * A delta as it arrives in a bootstrap payload.
+ *
+ * The bootstrap routes return the same rows the broadcast path does, so the
+ * fields are taken from {@link syncDeltaWireCoreSchema} rather than restated
+ * here — a delta is one shape, and this is the reader for it, not a second
+ * definition of it. Unknown keys are kept, because the server sends its own
+ * wider projection (attribution, `projectId`) that later stages may read.
+ */
 export declare const ServerDeltaSchema: z.ZodObject<{
     id: z.ZodNumber;
-    operation: z.ZodOptional<z.ZodEnum<{
-        I: "I";
-        U: "U";
-        D: "D";
-        A: "A";
-        V: "V";
-        C: "C";
-        G: "G";
-        S: "S";
-    }>>;
-    action: z.ZodOptional<z.ZodEnum<{
+    data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
+    actionType: z.ZodEnum<{
         I: "I";
         U: "U";
         D: "D";
@@ -26,33 +28,22 @@ export declare const ServerDeltaSchema: z.ZodObject<{
         C: "C";
         G: "G";
         S: "S";
-    }>>;
+    }>;
     modelName: z.ZodString;
-    entityId: z.ZodOptional<z.ZodString>;
-    modelId: z.ZodOptional<z.ZodString>;
-    data: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    modelId: z.ZodString;
 }, z.core.$loose>;
 export type ValidatedServerDelta = z.infer<typeof ServerDeltaSchema>;
 export declare const BootstrapResponseSchema: z.ZodObject<{
     type: z.ZodEnum<{
-        partial: "partial";
         full: "full";
+        partial: "partial";
     }>;
     lastSyncId: z.ZodNumber;
     models: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodUnknown>, z.ZodString, z.ZodNull]>, z.ZodTransform<unknown[], string | unknown[] | null>>>>;
     deltas: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodNumber;
-        operation: z.ZodOptional<z.ZodEnum<{
-            I: "I";
-            U: "U";
-            D: "D";
-            A: "A";
-            V: "V";
-            C: "C";
-            G: "G";
-            S: "S";
-        }>>;
-        action: z.ZodOptional<z.ZodEnum<{
+        data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
+        actionType: z.ZodEnum<{
             I: "I";
             U: "U";
             D: "D";
@@ -61,16 +52,15 @@ export declare const BootstrapResponseSchema: z.ZodObject<{
             C: "C";
             G: "G";
             S: "S";
-        }>>;
+        }>;
         modelName: z.ZodString;
-        entityId: z.ZodOptional<z.ZodString>;
-        modelId: z.ZodOptional<z.ZodString>;
-        data: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        modelId: z.ZodString;
     }, z.core.$loose>>>;
     deltaCount: z.ZodOptional<z.ZodNumber>;
     failedModels: z.ZodOptional<z.ZodArray<z.ZodString>>;
     timestamp: z.ZodDefault<z.ZodNumber>;
     schemaHash: z.ZodOptional<z.ZodString>;
+    nextCursor: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 export type ValidatedBootstrapResponse = z.infer<typeof BootstrapResponseSchema>;
 /**
@@ -78,4 +68,4 @@ export type ValidatedBootstrapResponse = z.infer<typeof BootstrapResponseSchema>
  * result. On failure it records a diagnostic breadcrumb and throws an
  * {@link AbloValidationError} describing which fields were invalid.
  */
-export declare function parseBootstrapResponse(raw: unknown): ValidatedBootstrapResponse;
+export declare function parseBootstrapResponse(raw: unknown, runtime?: RuntimeContext): ValidatedBootstrapResponse;

package/dist/sync/schemas.js

@@ -2,27 +2,32 @@
  * Zod validation schemas for sync engine server responses.
  *
  * Validates data at the fetch boundary before it enters the sync engine.
- * Uses .passthrough() so the server can add fields without breaking clients.
+ * Unknown keys are kept, so a server that adds a field does not break a client
+ * that predates it.
  */
 import { z } from 'zod';
-import { getContext } from "../context.js";
-import { AbloValidationError } from "../errors.js";
-// ─── Sync Action Types ───────────────────────────────────────────────────────
-// The action codes a server delta can carry, matching the wire protocol's
-// action-type set.
-const SYNC_ACTION_VALUES = ['I', 'U', 'D', 'A', 'C', 'G', 'S', 'V'];
+import { globalRuntime } from "../context.js";
+import { AbloValidationError } from "../transaction/errors.js";
+import { syncDeltaWireCoreSchema } from '../transaction/wire/delta.js';
 // ─── Server Delta Schema ─────────────────────────────────────────────────────
-export const ServerDeltaSchema = z
-    .object({
-    id: z.number(),
-    operation: z.enum(SYNC_ACTION_VALUES).optional(),
-    action: z.enum(SYNC_ACTION_VALUES).optional(),
-    modelName: z.string(),
-    entityId: z.string().optional(),
-    modelId: z.string().optional(),
-    data: z.record(z.string(), z.unknown()).nullable().optional(),
+/**
+ * A delta as it arrives in a bootstrap payload.
+ *
+ * The bootstrap routes return the same rows the broadcast path does, so the
+ * fields are taken from {@link syncDeltaWireCoreSchema} rather than restated
+ * here — a delta is one shape, and this is the reader for it, not a second
+ * definition of it. Unknown keys are kept, because the server sends its own
+ * wider projection (attribution, `projectId`) that later stages may read.
+ */
+export const ServerDeltaSchema = syncDeltaWireCoreSchema
+    .pick({
+    id: true,
+    actionType: true,
+    modelName: true,
+    modelId: true,
+    data: true,
 })
-    .passthrough();
+    .loose();
 // ─── Model Value Schema ─────────────────────────────────────────────────────
 // A model's values can arrive in more than one shape depending on how the
 // server serialized them:
@@ -60,19 +65,23 @@ export const BootstrapResponseSchema = z
     // absent when the server predates this field or the tenant has never
     // pushed a schema.
     schemaHash: z.string().optional(),
+    // Present when a paged single-model request stopped at its row limit
+    // with rows remaining: pass it back as the next page's cursor. Absent
+    // on the final page, on unpaged responses, and from older servers.
+    nextCursor: z.string().optional(),
 })
-    .passthrough();
+    .loose();
 // ─── Parse Helpers ───────────────────────────────────────────────────────────
 /**
  * Validates a raw bootstrap response from the server and returns the typed
  * result. On failure it records a diagnostic breadcrumb and throws an
  * {@link AbloValidationError} describing which fields were invalid.
  */
-export function parseBootstrapResponse(raw) {
+export function parseBootstrapResponse(raw, runtime = globalRuntime) {
     const result = BootstrapResponseSchema.safeParse(raw);
     if (!result.success) {
         const issues = result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
-        getContext().observability.breadcrumb('Bootstrap response validation failed', 'sync.bootstrap', 'error', {
+        runtime.observability.breadcrumb('Bootstrap response validation failed', 'sync.bootstrap', 'error', {
             issues,
             rawType: typeof raw,
             rawKeys: raw && typeof raw === 'object' ? Object.keys(raw).join(',') : 'n/a',

package/dist/sync/syncPlan.d.ts

@@ -5,17 +5,17 @@
  * object pool, and the enrichment rules that attach related parents to
  * incoming rows. See {@link deriveSyncPlanFromSchema}.
  */
-import type { Schema } from '../schema/schema.js';
+import type { Schema } from '../transaction/schema/schema.js';
 /** A foreign-key index to register on the in-memory object pool when the store is constructed. */
 export interface ForeignKeyIndexSpec {
     /**
      * The name of the child model, where the foreign-key field lives, and the
      * name the object pool indexes by. Use the wire type-name casing (for
-     * example `'SlideLayer'`, not `'slideLayer'`), since that is the value
+     * example `'Block'`, not `'block'`), since that is the value
      * stamped onto reconstructed models and the key the pool looks up.
      */
     readonly modelName: string;
-    /** The foreign-key field name on the child model, for example `'slideId'`. */
+    /** The foreign-key field name on the child model, for example `'sectionId'`. */
     readonly fieldName: string;
 }
 /**