@abloatai/ablo 0.3.0

package/dist/policy/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @ablo/sync-engine/policy — pluggable conflict resolution.
+ *
+ * The engine detects conflicts; the policy decides. Customer code
+ * implements `ConflictPolicy` and registers it at the sync-server.
+ *
+ * ```ts
+ * import { type ConflictPolicy, defaultPolicy } from '@ablo/sync-engine/policy';
+ *
+ * export const myPolicy: ConflictPolicy = (ctx) => {
+ *   if (ctx.committer.id.startsWith('linter:')) {
+ *     return { action: 'allow', note: 'cosmetic writer' };
+ *   }
+ *   return defaultPolicy(ctx);
+ * };
+ * ```
+ */
+export type { Conflict, ConflictDecision, ConflictKind, ConflictOperation, ConflictPolicy, StaleContextConflict, IntentHeldConflict, } from './types.js';
+export { defaultPolicy } from './types.js';

package/dist/policy/index.js

@@ -0,0 +1,18 @@
+/**
+ * @ablo/sync-engine/policy — pluggable conflict resolution.
+ *
+ * The engine detects conflicts; the policy decides. Customer code
+ * implements `ConflictPolicy` and registers it at the sync-server.
+ *
+ * ```ts
+ * import { type ConflictPolicy, defaultPolicy } from '@ablo/sync-engine/policy';
+ *
+ * export const myPolicy: ConflictPolicy = (ctx) => {
+ *   if (ctx.committer.id.startsWith('linter:')) {
+ *     return { action: 'allow', note: 'cosmetic writer' };
+ *   }
+ *   return defaultPolicy(ctx);
+ * };
+ * ```
+ */
+export { defaultPolicy } from './types.js';

package/dist/policy/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Conflict policy — the engine detects, the policy decides.
+ *
+ * Two conflict shapes today: `stale_context` (a write whose `readAt`
+ * is older than the latest delta on the target) and `intent_held`
+ * (a participant claims a target someone else is already claiming).
+ * Adding new shapes is additive on the discriminated union.
+ */
+import type { ParticipantRef } from '../types/streams.js';
+export type ConflictKind = 'stale_context' | 'intent_held';
+/** Fields shared by every conflict shape. */
+interface ConflictBase {
+    readonly committer: ParticipantRef;
+    readonly organizationId: string;
+    /** Human at the root of the committer's delegation chain (if any). */
+    readonly delegationChainRootUserId?: string | null;
+}
+/** The operation whose write conflicts. */
+export interface ConflictOperation {
+    readonly model: string;
+    readonly id: string;
+    readonly type: 'CREATE' | 'UPDATE' | 'DELETE' | 'ARCHIVE' | 'UNARCHIVE';
+    readonly input?: Readonly<Record<string, unknown>>;
+}
+export interface StaleContextConflict extends ConflictBase {
+    readonly kind: 'stale_context';
+    readonly operation: ConflictOperation;
+    /** Watermark the committer reasoned against. */
+    readonly readAt: number;
+    /** Most recent delta id on the target. */
+    readonly observedSyncId: number;
+}
+export interface IntentHeldConflict extends ConflictBase {
+    readonly kind: 'intent_held';
+    readonly heldBy: ParticipantRef;
+    readonly intentId: string;
+    readonly entityType: string;
+    readonly entityId: string;
+    /** Holder's intent expiry (ms since epoch). */
+    readonly expiresAt: number;
+}
+/**
+ * The discriminated union the policy receives. Switch on `.kind` to
+ * narrow to the variant.
+ */
+export type Conflict = StaleContextConflict | IntentHeldConflict;
+/** What the policy returns. */
+export type ConflictDecision = {
+    readonly action: 'reject';
+    readonly reason?: string;
+} | {
+    readonly action: 'allow';
+    readonly note?: string;
+};
+/**
+ * Pluggable decision function. Sync or async.
+ *
+ * ```ts
+ * const policy: ConflictPolicy = (conflict) => {
+ *   if (conflict.committer.id.startsWith('linter:')) {
+ *     return { action: 'allow', note: 'cosmetic writer' };
+ *   }
+ *   return defaultPolicy(conflict);
+ * };
+ * ```
+ */
+export type ConflictPolicy = (conflict: Conflict) => ConflictDecision | Promise<ConflictDecision>;
+/**
+ * Default: reject every conflict. Safe fallback when no custom policy
+ * is wired — the engine never silently allows a stale or
+ * intent-conflicting write through.
+ */
+export declare const defaultPolicy: ConflictPolicy;
+export {};

package/dist/policy/types.js

@@ -0,0 +1,17 @@
+/**
+ * Conflict policy — the engine detects, the policy decides.
+ *
+ * Two conflict shapes today: `stale_context` (a write whose `readAt`
+ * is older than the latest delta on the target) and `intent_held`
+ * (a participant claims a target someone else is already claiming).
+ * Adding new shapes is additive on the discriminated union.
+ */
+/**
+ * Default: reject every conflict. Safe fallback when no custom policy
+ * is wired — the engine never silently allows a stale or
+ * intent-conflicting write through.
+ */
+export const defaultPolicy = (conflict) => ({
+    action: 'reject',
+    reason: conflict.kind === 'stale_context' ? 'stale_context' : 'intent_conflict',
+});

package/dist/principal.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Principal constructors — a thin typed façade over the raw
+ * `SessionRef` / `AgentRef` shapes so call sites don't have to memorize
+ * the discriminated-union tags.
+ *
+ * ```ts
+ * import Ablo, { session } from '@ablo/sync-engine';
+ *
+ * const ablo = Ablo({ schema, apiKey });
+ * const participant = await ablo.participants.join({
+ *   type: 'Matter',
+ *   id: 'deal-1',
+ * });
+ * ```
+ *
+ * Browser-human flows use `session(...)`. Agent-spawn-agent flows use
+ * `agent(...)`, but those rarely appear in customer code because the
+ * participant layer handles attenuation.
+ *
+ * These are pure — no I/O, no hidden state. If the shape ever grows a
+ * required field (say, a Biscuit scope hint), the helper is the one
+ * place to flag migrations.
+ */
+import type { AgentRef, SessionRef } from './types/streams.js';
+/**
+ * Build a `SessionRef` from the identifiers your auth system already
+ * holds. Typical inputs: the Better Auth session id, the user id, and
+ * the organization the session is scoped to.
+ */
+export declare function session(params: {
+    id: string;
+    userId: string;
+    organizationId: string;
+}): SessionRef;
+/**
+ * Build an `AgentRef` from an agent id + the capability token that
+ * authenticates it. Rare in application code — the common path is
+ * `participant.join(child)` where the parent's token is attenuated
+ * automatically.
+ */
+export declare function agent(params: {
+    id: string;
+    capabilityToken: string;
+}): AgentRef;

package/dist/principal.js

@@ -0,0 +1,49 @@
+/**
+ * Principal constructors — a thin typed façade over the raw
+ * `SessionRef` / `AgentRef` shapes so call sites don't have to memorize
+ * the discriminated-union tags.
+ *
+ * ```ts
+ * import Ablo, { session } from '@ablo/sync-engine';
+ *
+ * const ablo = Ablo({ schema, apiKey });
+ * const participant = await ablo.participants.join({
+ *   type: 'Matter',
+ *   id: 'deal-1',
+ * });
+ * ```
+ *
+ * Browser-human flows use `session(...)`. Agent-spawn-agent flows use
+ * `agent(...)`, but those rarely appear in customer code because the
+ * participant layer handles attenuation.
+ *
+ * These are pure — no I/O, no hidden state. If the shape ever grows a
+ * required field (say, a Biscuit scope hint), the helper is the one
+ * place to flag migrations.
+ */
+/**
+ * Build a `SessionRef` from the identifiers your auth system already
+ * holds. Typical inputs: the Better Auth session id, the user id, and
+ * the organization the session is scoped to.
+ */
+export function session(params) {
+    return {
+        kind: 'session',
+        id: params.id,
+        userId: params.userId,
+        organizationId: params.organizationId,
+    };
+}
+/**
+ * Build an `AgentRef` from an agent id + the capability token that
+ * authenticates it. Rare in application code — the common path is
+ * `participant.join(child)` where the parent's token is attenuated
+ * automatically.
+ */
+export function agent(params) {
+    return {
+        kind: 'agent',
+        id: params.id,
+        capabilityToken: params.capabilityToken,
+    };
+}

package/dist/query/client.d.ts

@@ -0,0 +1,43 @@
+/**
+ * HTTP client for the generic /sync/query endpoint.
+ *
+ * Thin wrapper over fetch() that:
+ *   - POSTs a QueryBatch as JSON
+ *   - Handles auth via `credentials: 'include'` (session cookie)
+ *   - Throws on non-2xx responses
+ *   - Parses the response into a typed QueryBatchResult
+ *
+ * The higher-level BootstrapHelper methods (fetchDeckSlideLayers,
+ * fetchChatMessages, etc.) use this to issue structured queries
+ * without duplicating the fetch boilerplate.
+ */
+import type { QueryBatch, QueryBatchResult } from './types.js';
+export interface PostQueryOptions {
+    /**
+     * Full base URL of the sync server including the `/api` prefix.
+     * The query endpoint is appended as `/sync/query`, so the final
+     * request hits `${baseUrl}/sync/query`.
+     */
+    baseUrl: string;
+    /** Timeout in ms for the fetch request. Default: 30000. */
+    fetchTimeout?: number;
+    /**
+     * Capability token (Biscuit) to attach as `Authorization: Bearer <token>`.
+     * Required for Node consumers (agent-worker, server-side tests) that
+     * have no session cookie to ride. Browser consumers can omit this and
+     * fall back to `credentials: 'include'`. When both are present the
+     * server prefers the Bearer header (see `agentTokenProvider` in
+     * `apps/sync-server/src/auth`), so passing the token in browser code
+     * is harmless.
+     */
+    capabilityToken?: string;
+}
+/**
+ * POST a batch of queries to /sync/query. Returns the parsed
+ * QueryBatchResult. Throws a descriptive error on HTTP failure.
+ *
+ * The server guarantees results[i] corresponds to queries[i] in the
+ * request — callers can rely on index alignment to extract typed
+ * results from a multi-query batch.
+ */
+export declare function postQuery(options: PostQueryOptions, batch: QueryBatch): Promise<QueryBatchResult>;

package/dist/query/client.js

@@ -0,0 +1,84 @@
+/**
+ * HTTP client for the generic /sync/query endpoint.
+ *
+ * Thin wrapper over fetch() that:
+ *   - POSTs a QueryBatch as JSON
+ *   - Handles auth via `credentials: 'include'` (session cookie)
+ *   - Throws on non-2xx responses
+ *   - Parses the response into a typed QueryBatchResult
+ *
+ * The higher-level BootstrapHelper methods (fetchDeckSlideLayers,
+ * fetchChatMessages, etc.) use this to issue structured queries
+ * without duplicating the fetch boilerplate.
+ */
+import { z } from 'zod';
+// ── Response validation ─────────────────────────────────────────────────
+//
+// Each result slot is an array of rows (or an object for bundled
+// responses). Server-side per-query failures surface here as `[]`, but
+// the server logs them via `console.error('[query.error] ...')` — alert
+// on that prefix, not on emptiness. Parsing through Zod normalizes
+// `null` slots into empty arrays so downstream callers never see raw
+// null.
+const QueryResultSchema = z
+    .union([z.array(z.unknown()), z.record(z.string(), z.unknown()), z.null()])
+    .transform((val) => {
+    if (val === null)
+        return [];
+    return val;
+});
+const QueryBatchResultSchema = z
+    .object({
+    results: z.array(QueryResultSchema),
+})
+    .passthrough();
+/**
+ * POST a batch of queries to /sync/query. Returns the parsed
+ * QueryBatchResult. Throws a descriptive error on HTTP failure.
+ *
+ * The server guarantees results[i] corresponds to queries[i] in the
+ * request — callers can rely on index alignment to extract typed
+ * results from a multi-query batch.
+ */
+export async function postQuery(options, batch) {
+    const url = `${options.baseUrl}/sync/query`;
+    const timeout = options.fetchTimeout ?? 30_000;
+    // Race the fetch against a timeout so hung requests don't block
+    // the calling helper indefinitely.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+        const headers = { 'Content-Type': 'application/json' };
+        if (options.capabilityToken) {
+            headers.Authorization = `Bearer ${options.capabilityToken}`;
+        }
+        const response = await fetch(url, {
+            method: 'POST',
+            headers,
+            credentials: 'include',
+            body: JSON.stringify(batch),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            // Direct console.error is INTENTIONAL — operators alert on the
+            // `[postQuery.error]` prefix in browser console. Routing through
+            // an injected logger here would require a coordinated change to
+            // the alerting pipeline. Tracked as future work; the dual-channel
+            // alternative (logger + observability.captureException) is the
+            // production target. Never throw — fire-and-forget callers would
+            // kill Next.js router on unhandled rejection.
+            console.error(`[postQuery.error] ${response.status} ${response.statusText} for ${batch.queries.map((q) => q.model).join(',')}`);
+            return { results: batch.queries.map(() => []) };
+        }
+        const raw = await response.json();
+        const parsed = QueryBatchResultSchema.safeParse(raw);
+        if (!parsed.success) {
+            console.error('[postQuery.error] malformed response:', parsed.error.issues);
+            return { results: batch.queries.map(() => []) };
+        }
+        return parsed.data;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/query/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Query module barrel — re-exports the public surface for convenience.
+ * See types.ts and client.ts for the actual definitions.
+ */
+export type { Query, QueryBatch, QueryBatchResult } from './types.js';
+export { postQuery, type PostQueryOptions } from './client.js';

package/dist/query/index.js

@@ -0,0 +1,5 @@
+/**
+ * Query module barrel — re-exports the public surface for convenience.
+ * See types.ts and client.ts for the actual definitions.
+ */
+export { postQuery } from './client.js';

package/dist/query/types.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Structured query types for the generic /sync/query endpoint.
+ *
+ * Zero-shaped ZQL-ish wire format: `where` is a flat list of `[col, op, val]`
+ * tuples (AND'd together), and `related` is a list of schema-declared
+ * relation names to traverse. The server compiler reads the schema's
+ * relation metadata to turn `related: ['layers']` into the right JOIN.
+ *
+ * # Why this shape
+ *
+ * An earlier revision used equality-only `where: Record<string, unknown>`
+ * plus a PK-only `ids: string[]` batch field. That worked for simple cases
+ * but collapsed on two real workloads:
+ *
+ *   1. "Fetch all layers for these slide IDs" — the IDs are foreign keys
+ *      (`SlideLayer.slideId`), not primary keys. The old `ids` field
+ *      filtered on `id`, silently returning empty.
+ *
+ *   2. "Fetch all layers for this deck" — needs a JOIN through
+ *      `slides.deck_id → slide_layers.slide_id`. Equality-only `where` had
+ *      no way to express it, so the Go server hardcoded a dispatch case.
+ *
+ * Both are generic patterns ("batch by FK column", "filter via relation")
+ * that should be first-class in the protocol, not model-specific escape
+ * hatches on the server. This shape matches Zero's ZQL:
+ *
+ *   - `where('slideId', 'IN', ids)` → `['slideId', 'IN', ids]`
+ *   - `.related('layers')` → `related: ['layers']`
+ *
+ * The server's compiler stays schema-driven: given a model name, it reads
+ * the schema's declared relations to emit JOIN SQL, and given a `[col, op,
+ * val]` tuple it emits a WHERE fragment — never a switch on specific model
+ * names. Adding a new model or relation is a schema change, not a server
+ * change.
+ */
+/** Primitive operand types allowed in a where clause. */
+export type WherePrimitive = string | number | boolean | null;
+/**
+ * Comparison operators. Mirrors Zero's ZQL set so client authors can
+ * lean on familiar semantics and server compilers that already target
+ * ZQL stay portable.
+ */
+export type WhereOp = '=' | '!=' | '<' | '<=' | '>' | '>=' | 'IN' | 'NOT IN' | 'IS' | 'IS NOT' | 'LIKE' | 'NOT LIKE' | 'ILIKE' | 'NOT ILIKE';
+/**
+ * A single condition. Two supported shapes:
+ *
+ *   - `[col, value]` — shortcut for `[col, '=', value]`
+ *   - `[col, op, value]` — explicit operator
+ *
+ * The value is a single primitive for scalar operators and an array of
+ * primitives for IN/NOT IN.
+ */
+export type WhereClause = readonly [col: string, value: WherePrimitive] | readonly [col: string, op: WhereOp, value: WherePrimitive | readonly WherePrimitive[]];
+/**
+ * Client-facing where shape for `load({where})` and `deleteMany({where})`.
+ *
+ * Two shapes accepted, both AND-combined:
+ *
+ *   - Object form: `{ name: 'foo', orgId: '1' }` — each entry is an `=`
+ *     clause; array values become `IN`. Ergonomic for the common case.
+ *   - Tuple form: `[['name', 'ILIKE', '%Goldman%'], ['orgId', '1']]` —
+ *     explicit operators (LIKE/ILIKE/<=/etc.). Matches the wire
+ *     `WhereClause[]` 1:1, so no translation layer.
+ *
+ * The two forms compose: pass tuple form when you need an operator,
+ * object form otherwise. For OR semantics, run two `load()` calls and
+ * union client-side — keeps the protocol AND-only.
+ */
+export type LoadWhere<T> = Partial<T> | {
+    [K in keyof T]?: T[K] | readonly T[K][];
+} | readonly WhereClause[];
+/** A single structured fetch request. */
+export interface Query {
+    /**
+     * Client-facing model name (e.g. "File", "SlideLayer", "Message").
+     * The server's adapter maps this to the actual database table.
+     */
+    model: string;
+    /**
+     * List of where clauses AND'd together. Empty or omitted means "no
+     * filter" (still subject to server-side org scoping).
+     *
+     * Use `['col', 'IN', values]` to batch by any column — the old
+     * primary-key-only `ids` field is subsumed by this form.
+     */
+    where?: readonly WhereClause[];
+    /**
+     * Relation names declared in the schema for this model. The server's
+     * compiler resolves each name via the schema's relation metadata
+     * (`relation.hasMany` / `relation.belongsTo`) and emits the JOIN
+     * SQL — no model-specific dispatch on the server.
+     *
+     * Results come back as nested objects under the relation key:
+     *
+     *   { __typename: 'Slide', id: '…', layers: [{ __typename: 'SlideLayer', … }] }
+     */
+    related?: readonly string[];
+    /**
+     * Row limit. Applied after where + JOIN, before related nesting.
+     * Omit for no limit.
+     */
+    limit?: number;
+    /**
+     * Column to order by. For stable pagination. Omit for unordered.
+     */
+    orderBy?: string;
+    /** Order direction. Defaults to `'asc'`. */
+    order?: 'asc' | 'desc';
+}
+/** Request body for POST /sync/query. */
+export interface QueryBatch {
+    /**
+     * Batch of queries to execute in one round trip. Results are
+     * returned in request order at the same indices. Keep batches
+     * small — the server caps at 16 queries per batch by default.
+     */
+    queries: Query[];
+}
+/** Response body from POST /sync/query. */
+export interface QueryBatchResult {
+    /**
+     * Per-query results in request order. `results[i]` corresponds to
+     * `queries[i]`. Each element is an array of rows for array-shaped
+     * queries, or a bundled object for providers that return multiple
+     * collections under named keys.
+     *
+     * Each row carries `__typename` for client-side model dispatch, plus
+     * any `related` keys nested under the row.
+     *
+     * Failed queries surface as empty arrays. The server logs them via
+     * `console.error('[query.error] ...')` — alert on that prefix rather
+     * than trying to infer failure from empty results. A tagged-union
+     * wire shape that forces caller acknowledgement is the right next
+     * step once every `postQuery` consumer is updated at once.
+     */
+    results: unknown[];
+    /**
+     * Server watermark observed after the batch ran. Public resource reads
+     * expose this as `stamp` and callers thread it into `commits.create({
+     * readAt })` to reject stale writes.
+     */
+    lastSyncId?: number;
+}

package/dist/query/types.js

@@ -0,0 +1,36 @@
+/**
+ * Structured query types for the generic /sync/query endpoint.
+ *
+ * Zero-shaped ZQL-ish wire format: `where` is a flat list of `[col, op, val]`
+ * tuples (AND'd together), and `related` is a list of schema-declared
+ * relation names to traverse. The server compiler reads the schema's
+ * relation metadata to turn `related: ['layers']` into the right JOIN.
+ *
+ * # Why this shape
+ *
+ * An earlier revision used equality-only `where: Record<string, unknown>`
+ * plus a PK-only `ids: string[]` batch field. That worked for simple cases
+ * but collapsed on two real workloads:
+ *
+ *   1. "Fetch all layers for these slide IDs" — the IDs are foreign keys
+ *      (`SlideLayer.slideId`), not primary keys. The old `ids` field
+ *      filtered on `id`, silently returning empty.
+ *
+ *   2. "Fetch all layers for this deck" — needs a JOIN through
+ *      `slides.deck_id → slide_layers.slide_id`. Equality-only `where` had
+ *      no way to express it, so the Go server hardcoded a dispatch case.
+ *
+ * Both are generic patterns ("batch by FK column", "filter via relation")
+ * that should be first-class in the protocol, not model-specific escape
+ * hatches on the server. This shape matches Zero's ZQL:
+ *
+ *   - `where('slideId', 'IN', ids)` → `['slideId', 'IN', ids]`
+ *   - `.related('layers')` → `related: ['layers']`
+ *
+ * The server's compiler stays schema-driven: given a model name, it reads
+ * the schema's declared relations to emit JOIN SQL, and given a `[col, op,
+ * val]` tuple it emits a WHERE fragment — never a switch on specific model
+ * names. Adding a new model or relation is a schema change, not a server
+ * change.
+ */
+export {};