@abloatai/ablo 0.34.1 → 0.35.0

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,23 @@
  * 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';
+/**
+ * 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 +27,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 +51,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>;
 /**

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 { 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,8 +65,12 @@ 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

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;
 }
 /**

package/dist/sync/wsFrameHandlers.d.ts

@@ -1,116 +1,8 @@
 /**
- * Routes each inbound frame from the sync WebSocket to the handler for its
- * type. Handlers work against a minimal {@link WsSession} interface — only
- * the members they actually touch, rather than the transport object itself,
- * which keeps this module free of an import cycle. Reading a message off the
- * socket, parsing its JSON, and tracking heartbeats all happen before this
- * point; every parsed frame then passes through {@link dispatchWsFrame}.
+ * Moved to the settlement core with the duplex transport (ADR 0016): the
+ * inbound frame dispatch is the receiving half of the wire protocol, and the
+ * handlers already worked against the minimal `WsSession` port rather than
+ * the transport object. This path re-exports it so existing importers stay
+ * unchanged.
  */
-import { type CommitAck } from './commitFrames.js';
-/**
- * In-flight `commit` request record, keyed by clientTxId in the session.
- * Resolved when a matching `mutation_result` frame arrives from the
- * server, or rejected on timeout / disconnect.
- */
-export interface PendingCommit {
-    resolve: (value: CommitAck) => void;
-    reject: (err: Error) => void;
-    timeout: ReturnType<typeof setTimeout>;
-}
-/**
- * In-flight `claim` request record, keyed by claimId. Resolved when the
- * matching `claim_ack` arrives, or rejected on timeout/disconnect.
- */
-export interface PendingClaim {
-    resolve: (value: {
-        syncGroups: string[];
-        ttlSeconds?: number;
-    }) => void;
-    reject: (err: Error) => void;
-    timeout: ReturnType<typeof setTimeout>;
-}
-/**
- * An in-flight `update_subscription` request awaiting its
- * `subscription_ack`. The wire carries no correlation id, so requests are
- * matched to their acknowledgements in first-in, first-out order, the same
- * order the server applies them.
- */
-export interface PendingSubscription {
-    resolve: (value: {
-        syncGroups: string[];
-    }) => void;
-    reject: (err: Error) => void;
-    timeout: ReturnType<typeof setTimeout>;
-}
-/**
- * A parsed inbound wire frame, straight from `JSON.parse`. The data is
- * untrusted: every payload is loosely typed, and each handler narrows it
- * defensively before use.
- */
-export interface WsInboundFrame {
-    type?: string;
-    payload?: unknown;
-    /** Some delta frames carry their delta fields at the top level rather than under `payload`. */
-    actionType?: unknown;
-    modelName?: unknown;
-    [key: string]: unknown;
-}
-/** Narrow arbitrary wire data to a plain string-keyed record. */
-export declare function isRecord(value: unknown): value is Record<string, unknown>;
-/**
- * A type guard for the parsed result of an inbound message. A frame is any
- * plain object whose `type`, when present, is a string. Validating the
- * payload itself is left to each handler; delta payloads, for example, are
- * checked against the canonical delta schema before they are applied.
- */
-export declare function isWsInboundFrame(value: unknown): value is WsInboundFrame;
-/**
- * The subset of the sync WebSocket that the frame handlers need. The
- * transport builds a single object exposing these members over its own
- * private state. Handlers read the fields live rather than capturing them,
- * so resetting a field elsewhere — such as clearing pending subscriptions
- * on close — never leaves a handler holding a stale value.
- */
-export interface WsSession {
-    /** EventEmitter surface — handlers emit the typed transport events. */
-    emit(event: string, ...args: unknown[]): boolean;
-    /** In-flight commit acks keyed by clientTxId. */
-    pendingMutations: Map<string, PendingCommit>;
-    /** In-flight claim acks keyed by claimId. */
-    pendingClaims: Map<string, PendingClaim>;
-    /** Removes and returns the oldest in-flight `update_subscription` request. */
-    shiftPendingSubscription(): PendingSubscription | undefined;
-    /** Connection options subset the handlers write back (acked sync groups). */
-    options: {
-        syncGroups: string[];
-    };
-    /** Registered collaboration event keys (colon format). */
-    collaborationEventTypes: ReadonlySet<string>;
-    /**
-     * Processes one inbound delta. The argument is untrusted wire data; the
-     * transport validates it against the canonical delta schema and drops
-     * anything malformed, so handlers here never cast.
-     */
-    handleDelta(delta: unknown): void;
-    handleSyncResponse(payload: unknown): void;
-    handleBootstrapResponse(payload: unknown): void;
-    handlePresenceUpdate(message: {
-        payload?: unknown;
-        [k: string]: unknown;
-    }): void;
-}
-export type WsFrameHandler = (session: WsSession, message: WsInboundFrame) => void;
-/**
- * Maps each frame type to its handler. Every named server frame this
- * package understands is dispatched from this table; anything else falls
- * through to the collaboration-event and unknown-type path in
- * {@link dispatchWsFrame}.
- */
-export declare const wsFrameHandlers: Record<string, WsFrameHandler>;
-/**
- * Routes one parsed inbound frame to its handler. Keepalive frames are
- * ignored, a missing `type` is treated as a bare delta, and any unknown
- * type falls through to the collaboration-event map, whose wire names use
- * underscores and whose event keys use colons.
- */
-export declare function dispatchWsFrame(session: WsSession, message: WsInboundFrame): void;
+export { isRecord, readWsInboundFrame, wsFrameHandlers, dispatchWsFrame, type PendingCommit, type PendingClaim, type PendingSubscription, type WsInboundFrame, type WsSession, type WsFrameHandler, } from '../transaction/transport/wsFrameHandlers.js';