@abloatai/ablo 0.6.0 → 0.7.0

package/dist/coordination/schema.d.ts

@@ -0,0 +1,329 @@
+import { z } from 'zod';
+/**
+ * Coordination wire schema — the ONE canonical source for the three layers
+ * that keep humans and agents from clobbering each other on a shared row.
+ * See `packages/sync-engine/docs/coordination.md` ("The model — three layers,
+ * one decision") for the conceptual model. The layers, outer-to-inner:
+ *
+ *   1. PRESENCE       (observation)    — who is working where; NEVER enforces.
+ *   2. PESSIMISTIC    (claims/leases)  — `intent_begin`/`intent_abandon`;
+ *                                        mutual exclusion between participants.
+ *   3. OPTIMISTIC     (stale-context)  — `readAt` + `onStale` write-guard;
+ *                                        last-writer-wins lost-update detection.
+ *
+ * Both the SDK (`types/streams.ts`) and the sync-server (`hub/types.ts`,
+ * `presence/*`) derive their TypeScript types from THESE schemas via
+ * `z.infer`, instead of re-declaring overlapping shapes. That collapses the
+ * field drift this surface accreted — e.g. the SDK's intent view dropping
+ * `status`/`error`, `onStale` declared 5×, `IntentStatus` declared 2× — into
+ * a single definition that the wire ingest can also validate at runtime.
+ */
+/** A line/column span within a text-bearing field (slide body, doc, cell). */
+export declare const targetRangeSchema: z.ZodObject<{
+    startLine: z.ZodNumber;
+    endLine: z.ZodNumber;
+    startColumn: z.ZodOptional<z.ZodNumber>;
+    endColumn: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type TargetRange = z.infer<typeof targetRangeSchema>;
+export declare const participantKindSchema: z.ZodEnum<{
+    user: "user";
+    agent: "agent";
+    system: "system";
+}>;
+export type ParticipantKind = z.infer<typeof participantKindSchema>;
+/**
+ * What a claim / intent / activity points at. The common locator shared by
+ * all three layers — an entity, optionally narrowed to a path, range, or
+ * field, with opaque app metadata.
+ */
+export declare const targetRefSchema: z.ZodObject<{
+    entityType: z.ZodString;
+    entityId: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    range: z.ZodOptional<z.ZodObject<{
+        startLine: z.ZodNumber;
+        endLine: z.ZodNumber;
+        startColumn: z.ZodOptional<z.ZodNumber>;
+        endColumn: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    field: z.ZodOptional<z.ZodString>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type TargetRef = z.infer<typeof targetRefSchema>;
+/**
+ * Mode applied when a write's snapshot watermark (`readAt`) is older than the
+ * target row's latest delta. `'reject'` is the default whenever `readAt` is
+ * present. `'flag'` and `'merge'` are reserved — the wire accepts them, the
+ * server does not yet enforce them.
+ */
+export declare const onStaleModeSchema: z.ZodEnum<{
+    reject: "reject";
+    force: "force";
+    flag: "flag";
+    merge: "merge";
+}>;
+export type OnStaleMode = z.infer<typeof onStaleModeSchema>;
+/**
+ * The optimistic guard carried on a commit operation. `readAt` is the
+ * snapshot watermark from `context.capture` (null/absent ⇒ unguarded write).
+ * `bypass` is the explicit, recorded override of a *foreign* pessimistic
+ * claim — see the claim layer below.
+ */
+export declare const writeGuardSchema: z.ZodObject<{
+    readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        reject: "reject";
+        force: "force";
+        flag: "flag";
+        merge: "merge";
+    }>>>;
+    bypass: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type WriteGuard = z.infer<typeof writeGuardSchema>;
+/**
+ * Lifecycle of an intent — the Stripe `PaymentIntent.status` shape. Absent on
+ * the wire ⇒ `'active'` (additive back-compat). The server stamps `'active'`
+ * on `intent_begin` and emits a single terminal frame (`committed` /
+ * `canceled` / `expired`) as the claim ends, so contenders learn *how* it
+ * resolved, not merely that it vanished.
+ */
+export declare const intentStatusSchema: z.ZodEnum<{
+    active: "active";
+    committed: "committed";
+    expired: "expired";
+    canceled: "canceled";
+}>;
+export type IntentStatus = z.infer<typeof intentStatusSchema>;
+/** Why a claim ended in a non-success terminal state. */
+export declare const intentErrorSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+    heldBy: z.ZodOptional<z.ZodString>;
+    heldByIntentId: z.ZodOptional<z.ZodString>;
+    heldByExpiresAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type IntentError = z.infer<typeof intentErrorSchema>;
+/**
+ * A declared pending-mutation intent — the unit broadcast in presence
+ * `activeIntents`. Clients supply the descriptive `targetRef` fields, an
+ * `action`, and a chosen `intentId`; the SERVER stamps `declaredAt` /
+ * `expiresAt` and may set `status` / `error`.
+ *
+ * `status` and `error` are OPTIONAL: this single shape serves both the
+ * server (which sets them) and the SDK view (which historically omitted
+ * them). The superset is structurally assignable wherever the leaner view
+ * was used, so the two prior copies collapse into this one without breaking
+ * SDK consumers.
+ */
+export declare const intentClaimSchema: z.ZodObject<{
+    entityType: z.ZodString;
+    entityId: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    range: z.ZodOptional<z.ZodObject<{
+        startLine: z.ZodNumber;
+        endLine: z.ZodNumber;
+        startColumn: z.ZodOptional<z.ZodNumber>;
+        endColumn: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    field: z.ZodOptional<z.ZodString>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    intentId: z.ZodString;
+    action: z.ZodString;
+    declaredAt: z.ZodNumber;
+    expiresAt: z.ZodNumber;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        committed: "committed";
+        expired: "expired";
+        canceled: "canceled";
+    }>>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodOptional<z.ZodString>;
+        heldBy: z.ZodOptional<z.ZodString>;
+        heldByIntentId: z.ZodOptional<z.ZodString>;
+        heldByExpiresAt: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type IntentClaim = z.infer<typeof intentClaimSchema>;
+/**
+ * `intent_begin` payload (client → server). The descriptive target + action,
+ * plus an optional duration hint and the opt-in fair-queue flag. The server
+ * stamps the lifecycle/timestamp fields, so they are NOT part of the inbound
+ * shape — this is exactly what the WS ingest validates.
+ */
+export declare const intentBeginPayloadSchema: z.ZodObject<{
+    entityType: z.ZodString;
+    entityId: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    range: z.ZodOptional<z.ZodObject<{
+        startLine: z.ZodNumber;
+        endLine: z.ZodNumber;
+        startColumn: z.ZodOptional<z.ZodNumber>;
+        endColumn: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    field: z.ZodOptional<z.ZodString>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    intentId: z.ZodString;
+    action: z.ZodString;
+    estimatedMs: z.ZodOptional<z.ZodNumber>;
+    queue: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type IntentBeginPayload = z.infer<typeof intentBeginPayloadSchema>;
+/**
+ * `intent_abandon` payload (client → server). `entityType`/`entityId` are
+ * carried so the server can DEQUEUE a still-*waiting* (not held) intent from
+ * the FIFO line — the held-intent path needs only `intentId`. (The previous
+ * wire type omitted these two even though the handler reads them; the schema
+ * documents what the code actually uses.)
+ */
+export declare const intentAbandonPayloadSchema: z.ZodObject<{
+    intentId: z.ZodString;
+    entityType: z.ZodOptional<z.ZodString>;
+    entityId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type IntentAbandonPayload = z.infer<typeof intentAbandonPayloadSchema>;
+/**
+ * `intent_reorder` payload (client → server). A privileged participant (e.g. a
+ * supervisor over its sub-agents) re-ranks the FIFO wait queue for an entity:
+ * `order` lists waiters by `heldBy`+`intentId` in the desired priority. Waiters
+ * not listed keep their relative order behind the listed ones. The server gates
+ * who may call this; an unauthorized sender is dropped. Unlike `intent_abandon`
+ * (acts on the caller's own entry), reorder acts on OTHER participants' queue
+ * positions — hence the authorization gate.
+ */
+export declare const intentReorderPayloadSchema: z.ZodObject<{
+    entityType: z.ZodString;
+    entityId: z.ZodString;
+    order: z.ZodArray<z.ZodObject<{
+        heldBy: z.ZodString;
+        intentId: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type IntentReorderPayload = z.infer<typeof intentReorderPayloadSchema>;
+export declare const commitOperationTypeSchema: z.ZodEnum<{
+    CREATE: "CREATE";
+    UPDATE: "UPDATE";
+    DELETE: "DELETE";
+    ARCHIVE: "ARCHIVE";
+    UNARCHIVE: "UNARCHIVE";
+}>;
+export type CommitOperationType = z.infer<typeof commitOperationTypeSchema>;
+/**
+ * A single mutation in a commit batch, as it arrives on the wire. Extends the
+ * optimistic `writeGuard` (`readAt`/`onStale`/`bypass`) — the structural link
+ * that makes "every write is stale-guarded" legible in the type, not just in
+ * prose.
+ */
+export declare const commitOperationSchema: z.ZodObject<{
+    readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        reject: "reject";
+        force: "force";
+        flag: "flag";
+        merge: "merge";
+    }>>>;
+    bypass: z.ZodOptional<z.ZodBoolean>;
+    type: z.ZodEnum<{
+        CREATE: "CREATE";
+        UPDATE: "UPDATE";
+        DELETE: "DELETE";
+        ARCHIVE: "ARCHIVE";
+        UNARCHIVE: "UNARCHIVE";
+    }>;
+    model: z.ZodString;
+    id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    input: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type CommitOperation = z.infer<typeof commitOperationSchema>;
+export declare const presenceKindSchema: z.ZodEnum<{
+    enter: "enter";
+    update: "update";
+    leave: "leave";
+}>;
+export type PresenceKind = z.infer<typeof presenceKindSchema>;
+/** What a participant is actively working on (agents fill this in). */
+export declare const presenceActivitySchema: z.ZodObject<{
+    entityType: z.ZodString;
+    entityId: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    range: z.ZodOptional<z.ZodObject<{
+        startLine: z.ZodNumber;
+        endLine: z.ZodNumber;
+        startColumn: z.ZodOptional<z.ZodNumber>;
+        endColumn: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    field: z.ZodOptional<z.ZodString>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    action: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PresenceActivity = z.infer<typeof presenceActivitySchema>;
+/**
+ * Full `presence_update` frame as the server broadcasts it. The activity +
+ * `activeIntents` are the observation surface for the other two layers —
+ * rendered, never acted on as enforcement.
+ */
+export declare const presenceUpdateFrameSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        enter: "enter";
+        update: "update";
+        leave: "leave";
+    }>;
+    userId: z.ZodOptional<z.ZodString>;
+    syncGroups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodString;
+    timezone: z.ZodOptional<z.ZodString>;
+    customStatus: z.ZodOptional<z.ZodString>;
+    activity: z.ZodOptional<z.ZodObject<{
+        entityType: z.ZodString;
+        entityId: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        range: z.ZodOptional<z.ZodObject<{
+            startLine: z.ZodNumber;
+            endLine: z.ZodNumber;
+            startColumn: z.ZodOptional<z.ZodNumber>;
+            endColumn: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        field: z.ZodOptional<z.ZodString>;
+        meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        action: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    isAgent: z.ZodOptional<z.ZodBoolean>;
+    activeIntents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        entityType: z.ZodString;
+        entityId: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        range: z.ZodOptional<z.ZodObject<{
+            startLine: z.ZodNumber;
+            endLine: z.ZodNumber;
+            startColumn: z.ZodOptional<z.ZodNumber>;
+            endColumn: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        field: z.ZodOptional<z.ZodString>;
+        meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        intentId: z.ZodString;
+        action: z.ZodString;
+        declaredAt: z.ZodNumber;
+        expiresAt: z.ZodNumber;
+        status: z.ZodOptional<z.ZodEnum<{
+            active: "active";
+            committed: "committed";
+            expired: "expired";
+            canceled: "canceled";
+        }>>;
+        error: z.ZodOptional<z.ZodObject<{
+            code: z.ZodString;
+            message: z.ZodOptional<z.ZodString>;
+            heldBy: z.ZodOptional<z.ZodString>;
+            heldByIntentId: z.ZodOptional<z.ZodString>;
+            heldByExpiresAt: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    delegatedFrom: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type PresenceUpdateFrame = z.infer<typeof presenceUpdateFrameSchema>;

package/dist/coordination/schema.js

@@ -0,0 +1,209 @@
+import { z } from 'zod';
+/**
+ * Coordination wire schema — the ONE canonical source for the three layers
+ * that keep humans and agents from clobbering each other on a shared row.
+ * See `packages/sync-engine/docs/coordination.md` ("The model — three layers,
+ * one decision") for the conceptual model. The layers, outer-to-inner:
+ *
+ *   1. PRESENCE       (observation)    — who is working where; NEVER enforces.
+ *   2. PESSIMISTIC    (claims/leases)  — `intent_begin`/`intent_abandon`;
+ *                                        mutual exclusion between participants.
+ *   3. OPTIMISTIC     (stale-context)  — `readAt` + `onStale` write-guard;
+ *                                        last-writer-wins lost-update detection.
+ *
+ * Both the SDK (`types/streams.ts`) and the sync-server (`hub/types.ts`,
+ * `presence/*`) derive their TypeScript types from THESE schemas via
+ * `z.infer`, instead of re-declaring overlapping shapes. That collapses the
+ * field drift this surface accreted — e.g. the SDK's intent view dropping
+ * `status`/`error`, `onStale` declared 5×, `IntentStatus` declared 2× — into
+ * a single definition that the wire ingest can also validate at runtime.
+ */
+// ─────────────────────────────────────────────────────────────────────────
+//  Shared primitives
+// ─────────────────────────────────────────────────────────────────────────
+/** A line/column span within a text-bearing field (slide body, doc, cell). */
+export const targetRangeSchema = z.object({
+    startLine: z.number(),
+    endLine: z.number(),
+    startColumn: z.number().optional(),
+    endColumn: z.number().optional(),
+});
+export const participantKindSchema = z.enum(['user', 'agent', 'system']);
+/**
+ * What a claim / intent / activity points at. The common locator shared by
+ * all three layers — an entity, optionally narrowed to a path, range, or
+ * field, with opaque app metadata.
+ */
+export const targetRefSchema = z.object({
+    entityType: z.string(),
+    entityId: z.string(),
+    path: z.string().optional(),
+    range: targetRangeSchema.optional(),
+    field: z.string().optional(),
+    meta: z.record(z.string(), z.unknown()).optional(),
+});
+// ─────────────────────────────────────────────────────────────────────────
+//  Layer 3 — OPTIMISTIC stale-context (the write-guard)
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Mode applied when a write's snapshot watermark (`readAt`) is older than the
+ * target row's latest delta. `'reject'` is the default whenever `readAt` is
+ * present. `'flag'` and `'merge'` are reserved — the wire accepts them, the
+ * server does not yet enforce them.
+ */
+export const onStaleModeSchema = z.enum(['reject', 'force', 'flag', 'merge']);
+/**
+ * The optimistic guard carried on a commit operation. `readAt` is the
+ * snapshot watermark from `context.capture` (null/absent ⇒ unguarded write).
+ * `bypass` is the explicit, recorded override of a *foreign* pessimistic
+ * claim — see the claim layer below.
+ */
+export const writeGuardSchema = z.object({
+    readAt: z.number().nullish(),
+    onStale: onStaleModeSchema.nullish(),
+    bypass: z.boolean().optional(),
+});
+// ─────────────────────────────────────────────────────────────────────────
+//  Layer 2 — PESSIMISTIC claim / intent-lease
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Lifecycle of an intent — the Stripe `PaymentIntent.status` shape. Absent on
+ * the wire ⇒ `'active'` (additive back-compat). The server stamps `'active'`
+ * on `intent_begin` and emits a single terminal frame (`committed` /
+ * `canceled` / `expired`) as the claim ends, so contenders learn *how* it
+ * resolved, not merely that it vanished.
+ */
+export const intentStatusSchema = z.enum([
+    'active',
+    'committed',
+    'expired',
+    'canceled',
+]);
+/** Why a claim ended in a non-success terminal state. */
+export const intentErrorSchema = z.object({
+    code: z.string(),
+    message: z.string().optional(),
+    /** Participant already holding the target (conflict rejections). */
+    heldBy: z.string().optional(),
+    heldByIntentId: z.string().optional(),
+    heldByExpiresAt: z.number().optional(),
+});
+/**
+ * A declared pending-mutation intent — the unit broadcast in presence
+ * `activeIntents`. Clients supply the descriptive `targetRef` fields, an
+ * `action`, and a chosen `intentId`; the SERVER stamps `declaredAt` /
+ * `expiresAt` and may set `status` / `error`.
+ *
+ * `status` and `error` are OPTIONAL: this single shape serves both the
+ * server (which sets them) and the SDK view (which historically omitted
+ * them). The superset is structurally assignable wherever the leaner view
+ * was used, so the two prior copies collapse into this one without breaking
+ * SDK consumers.
+ */
+export const intentClaimSchema = targetRefSchema.extend({
+    intentId: z.string(),
+    /** Verb the agent expects: 'update' | 'create' | 'editing' | 'reviewing' … */
+    action: z.string(),
+    /** Server-stamped declaration time (epoch ms). */
+    declaredAt: z.number(),
+    /** Server-computed TTL deadline (epoch ms). Readers treat as advisory. */
+    expiresAt: z.number(),
+    status: intentStatusSchema.optional(),
+    error: intentErrorSchema.optional(),
+});
+/**
+ * `intent_begin` payload (client → server). The descriptive target + action,
+ * plus an optional duration hint and the opt-in fair-queue flag. The server
+ * stamps the lifecycle/timestamp fields, so they are NOT part of the inbound
+ * shape — this is exactly what the WS ingest validates.
+ */
+export const intentBeginPayloadSchema = targetRefSchema.extend({
+    intentId: z.string(),
+    action: z.string(),
+    /** Hint for `expiresAt`; the server caps it. */
+    estimatedMs: z.number().optional(),
+    /**
+     * Opt into the fair wait queue: when the target is already held, the server
+     * enqueues this claim (FIFO) and replies `intent_queued` → later
+     * `intent_granted`, instead of `intent_rejected`. Clients that set this MUST
+     * handle the grant.
+     */
+    queue: z.boolean().optional(),
+});
+/**
+ * `intent_abandon` payload (client → server). `entityType`/`entityId` are
+ * carried so the server can DEQUEUE a still-*waiting* (not held) intent from
+ * the FIFO line — the held-intent path needs only `intentId`. (The previous
+ * wire type omitted these two even though the handler reads them; the schema
+ * documents what the code actually uses.)
+ */
+export const intentAbandonPayloadSchema = z.object({
+    intentId: z.string(),
+    entityType: z.string().optional(),
+    entityId: z.string().optional(),
+});
+/**
+ * `intent_reorder` payload (client → server). A privileged participant (e.g. a
+ * supervisor over its sub-agents) re-ranks the FIFO wait queue for an entity:
+ * `order` lists waiters by `heldBy`+`intentId` in the desired priority. Waiters
+ * not listed keep their relative order behind the listed ones. The server gates
+ * who may call this; an unauthorized sender is dropped. Unlike `intent_abandon`
+ * (acts on the caller's own entry), reorder acts on OTHER participants' queue
+ * positions — hence the authorization gate.
+ */
+export const intentReorderPayloadSchema = z.object({
+    entityType: z.string(),
+    entityId: z.string(),
+    order: z.array(z.object({ heldBy: z.string(), intentId: z.string() })),
+});
+// ─────────────────────────────────────────────────────────────────────────
+//  Commit operation — carries the optimistic write-guard (Layer 3)
+// ─────────────────────────────────────────────────────────────────────────
+export const commitOperationTypeSchema = z.enum([
+    'CREATE',
+    'UPDATE',
+    'DELETE',
+    'ARCHIVE',
+    'UNARCHIVE',
+]);
+/**
+ * A single mutation in a commit batch, as it arrives on the wire. Extends the
+ * optimistic `writeGuard` (`readAt`/`onStale`/`bypass`) — the structural link
+ * that makes "every write is stale-guarded" legible in the type, not just in
+ * prose.
+ */
+export const commitOperationSchema = writeGuardSchema.extend({
+    type: commitOperationTypeSchema,
+    model: z.string(),
+    id: z.string().nullish(),
+    input: z.record(z.string(), z.unknown()).nullish(),
+    /** Per-op client tx id, echoed on the broadcast delta. */
+    transactionId: z.string().nullish(),
+});
+// ─────────────────────────────────────────────────────────────────────────
+//  Layer 1 — PRESENCE (observation only; never enforces)
+// ─────────────────────────────────────────────────────────────────────────
+export const presenceKindSchema = z.enum(['enter', 'update', 'leave']);
+/** What a participant is actively working on (agents fill this in). */
+export const presenceActivitySchema = targetRefSchema.extend({
+    action: z.string(),
+    detail: z.string().optional(),
+});
+/**
+ * Full `presence_update` frame as the server broadcasts it. The activity +
+ * `activeIntents` are the observation surface for the other two layers —
+ * rendered, never acted on as enforcement.
+ */
+export const presenceUpdateFrameSchema = z.object({
+    kind: presenceKindSchema,
+    userId: z.string().optional(),
+    syncGroups: z.array(z.string()).optional(),
+    timestamp: z.number().optional(),
+    status: z.string(),
+    timezone: z.string().optional(),
+    customStatus: z.string().optional(),
+    activity: presenceActivitySchema.optional(),
+    isAgent: z.boolean().optional(),
+    activeIntents: z.array(intentClaimSchema).optional(),
+    delegatedFrom: z.string().nullish(),
+});

package/dist/core/QueryView.d.ts

@@ -20,7 +20,10 @@ export interface QueryViewOptions<T> {
     order?: 'asc' | 'desc';
     limit?: number;
     offset?: number;
-    scope?: ModelScope;
+    /** Lifecycle filter — `live` (default), `archived`, or `all`. Named `state`
+     *  (GitHub's open/closed/all precedent) so it doesn't collide with the
+     *  sync-group `scope`. */
+    state?: ModelScope;
 }
 export declare class QueryView<T extends Record<string, unknown>> implements IncrementalView {
     /** The full (unlimited) internal result set, kept sorted. */

package/dist/core/QueryView.js

@@ -50,7 +50,7 @@ export class QueryView {
         this.sortDir = options.order === 'desc' ? -1 : 1;
         this.limitN = options.limit;
         this.offsetN = options.offset ?? 0;
-        this.scope = options.scope ?? ModelScope.live;
+        this.scope = options.state ?? ModelScope.live;
         // Check for FK-index optimization: single-field where with an indexed FK
         this.fkField = null;
         this.fkValue = null;

package/dist/core/query-utils.d.ts

@@ -1,18 +1,15 @@
 /**
- * query-utils — Pure query helpers shared between QueryView (MobX) and
- * AgentQueryView (headless). One source of truth for sort, filter, and
- * binary insertion logic.
+ * query-utils — Pure query helpers for the MobX `QueryView`. One source of
+ * truth for sort, filter, and binary insertion logic.
  *
  * No MobX, no ObjectPool, no Model — just arrays and values.
  */
 /**
- * The incremental-update contract that both QueryView and
- * AgentQueryView satisfy. Their respective registries (ViewRegistry,
- * AgentViewRegistry) store views as this base type so they can
- * dispatch to many views with different `T` parameters from one Set
- * — `View<T>` is invariant in T, so without this shared base the
- * registries would have to widen via `unknown as View<Record<...>>`
- * at every register/unregister/notify call.
+ * The incremental-update contract a view satisfies. `ViewRegistry` stores views
+ * as this base type so it can dispatch to many views with different `T`
+ * parameters from one Set — `View<T>` is invariant in T, so without this shared
+ * base the registry would have to widen via `unknown as View<Record<...>>` at
+ * every register/unregister/notify call.
  */
 export interface IncrementalView {
     handleAdded(entity: Record<string, unknown>): void;

package/dist/core/query-utils.js

@@ -1,7 +1,6 @@
 /**
- * query-utils — Pure query helpers shared between QueryView (MobX) and
- * AgentQueryView (headless). One source of truth for sort, filter, and
- * binary insertion logic.
+ * query-utils — Pure query helpers for the MobX `QueryView`. One source of
+ * truth for sort, filter, and binary insertion logic.
  *
  * No MobX, no ObjectPool, no Model — just arrays and values.
  */