@dxos/echo 0.10.0 → 0.11.0

package/dist/types/src/Aggregate.d.ts

@@ -0,0 +1,86 @@
+import type * as EffectTypes from 'effect/Types';
+import type { QueryAST } from '@dxos/echo-protocol';
+import type * as Order from './Order';
+import type * as Query from './Query';
+/**
+ * The aggregate spec sans name; the name is supplied by the `Query.aggregate` record key. A tagged
+ * union per kind so `property`/`limit`/`order` are present exactly when the kind uses them (no
+ * unused optional fields to guard against at read sites).
+ */
+export type Spec = {
+    kind: 'group';
+    property: string;
+} | {
+    kind: 'max';
+    property: string;
+} | {
+    kind: 'min';
+    property: string;
+} | {
+    kind: 'items';
+    limit?: number;
+    order?: readonly QueryAST.Order[];
+} | {
+    kind: 'count';
+};
+export declare const AggregateTypeId: '~@dxos/echo/Aggregate';
+export type AggregateTypeId = typeof AggregateTypeId;
+/**
+ * A per-group aggregate declaration, materialised as a top-level field on the flat result record
+ * `Query.aggregate` produces and orderable via a following `orderBy(Order.property(name))`. Name it
+ * via the record passed to `Query.aggregate({ name: Aggregate.max('created') })`.
+ *
+ * `T` is the query's element type (so a reduced/grouped property is checked against it); `V` is the
+ * value the aggregate produces. {@link group} entries define the grouping keys; a record with no
+ * `group` entries aggregates the entire input into a single row.
+ */
+export interface Aggregate<T, V> {
+    readonly [AggregateTypeId]: {
+        element: T;
+        value: V;
+    };
+    spec: Spec;
+}
+export type Any = Aggregate<any, any>;
+/** Extracts the value type a {@link Aggregate} produces. */
+export type ValueOf<A> = A extends Aggregate<any, infer V> ? V : never;
+/** Computes the flat result type of `Query.aggregate(aggregates)` for a given aggregate record `A`. */
+export type AggregationResult<A extends Record<string, Any>> = EffectTypes.Simplify<Query.AggregateResult & {
+    readonly [N in keyof A]: ValueOf<A[N]>;
+}>;
+/**
+ * Group members by a scalar property. The record key names the result field carrying the coerced
+ * group-key value; multiple `group` entries form a composite key. Members whose property is missing,
+ * `null`, `undefined`, or non-scalar group under the `null` key, so the field value is `T[K] | null`.
+ */
+export declare const group: <T, K extends keyof T & string>(property: K) => Aggregate<T, T[K] | null>;
+/**
+ * Aggregate the maximum of a scalar property across the group's members.
+ * `T` is inferred from the `Query.aggregate` context, so `property` is checked against the query's
+ * element type (like {@link Order.property}).
+ */
+export declare const max: <T, K extends keyof T & string>(property: K) => Aggregate<T, T[K] | null>;
+/**
+ * Aggregate the minimum of a scalar property across the group's members.
+ */
+export declare const min: <T, K extends keyof T & string>(property: K) => Aggregate<T, T[K] | null>;
+/**
+ * Collect the group's members, optionally ordered by `order` and capped to `limit` per group.
+ * Opt-in — groups carry no members unless this aggregate is declared.
+ *
+ * `order` is this aggregate's own per-group ordering — independent of any `orderBy` elsewhere in
+ * the query, which orders the whole input stream (and, following `aggregate`, the resulting
+ * groups), not this aggregate's member selection. Without `order`, members keep whatever order
+ * they arrived in from a preceding `orderBy` (unspecified if there is none), so a per-group
+ * top-`limit` moved position in the chain would silently change; declaring `order` here makes the
+ * ordering explicit and local to this aggregate regardless of where it sits.
+ */
+export declare const items: <T>(options?: {
+    limit?: number;
+    order?: Order.Any[];
+}) => Aggregate<T, T[]>;
+/**
+ * Count the group's members. Opt-in — groups carry no count unless this aggregate is declared.
+ */
+export declare const count: <T>() => Aggregate<T, number>;
+//# sourceMappingURL=Aggregate.d.ts.map

package/dist/types/src/Aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Aggregate.d.ts","sourceRoot":"","sources":["../../../src/Aggregate.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,KAAK,WAAW,MAAM,cAAc,CAAC;AAEjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,KAAK,KAAK,KAAK,MAAM,SAAS,CAAC;AACtC,OAAO,KAAK,KAAK,KAAK,MAAM,SAAS,CAAC;AAEtC;;;;GAIG;AACH,MAAM,MAAM,IAAI,GACZ;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,QAAQ,CAAC,KAAK,EAAE,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB,eAAO,MAAM,eAAe,EAAG,uBAAgC,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,EAAE,CAAC;IAC7B,QAAQ,CAAC,CAAC,eAAe,CAAC,EAAE;QAAE,OAAO,EAAE,CAAC,CAAC;QAAC,KAAK,EAAE,CAAC,CAAA;KAAE,CAAC;IAErD,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAEtC,4DAA4D;AAC5D,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEvE,uGAAuG;AACvG,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,WAAW,CAAC,QAAQ,CACjF,KAAK,CAAC,eAAe,GAAG;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CACnE,CAAC;AAcF;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,YAAY,CAAC,KAAG,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAC1C,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,GAAG,GAAI,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,YAAY,CAAC,KAAG,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAC1C,CAAC;AAEhD;;GAEG;AACH,eAAO,MAAM,GAAG,GAAI,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,YAAY,CAAC,KAAG,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAC1C,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,YAAY;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAC,GAAG,EAAE,CAAA;CAAE,KAAG,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CACmB,CAAC;AAEjH;;GAEG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,OAAK,SAAS,CAAC,CAAC,EAAE,MAAM,CAA0C,CAAC"}

package/dist/types/src/Blob.d.ts

@@ -0,0 +1,153 @@
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import * as Database from './Database';
+import * as Err from './Err';
+import * as Obj from './Obj';
+import * as Type from './Type';
+/**
+ * Inline blob data: bytes stored directly on the ECHO object.
+ */
+export declare const InlineData: Schema.TaggedStruct<"inline", {
+    bytes: Schema.declare<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, readonly [], never>;
+}>;
+/**
+ * External blob data: bytes stored by a registered blob backend, addressed by `uri`.
+ */
+export declare const ExternalData: Schema.TaggedStruct<"external", {
+    /**
+     * URI locating the bytes. The scheme selects the backend at read time (e.g. `ni:///sha-256;…` for
+     * the edge backend — an RFC 6920 content digest, not a backend name — or `wnfs://…` for the
+     * plugin-wnfs extension), resolved via the scheme→backend map built from `registerBlobBackend`
+     * calls. Core code never parses or constructs backend-specific URIs beyond reading the scheme.
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc6920 RFC 6920} for the `ni:` URI format.
+     */
+    uri: typeof Schema.String;
+}>;
+export declare const BlobData: Schema.Union<[Schema.TaggedStruct<"inline", {
+    bytes: Schema.declare<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, readonly [], never>;
+}>, Schema.TaggedStruct<"external", {
+    /**
+     * URI locating the bytes. The scheme selects the backend at read time (e.g. `ni:///sha-256;…` for
+     * the edge backend — an RFC 6920 content digest, not a backend name — or `wnfs://…` for the
+     * plugin-wnfs extension), resolved via the scheme→backend map built from `registerBlobBackend`
+     * calls. Core code never parses or constructs backend-specific URIs beyond reading the scheme.
+     *
+     * @see {@link https://www.rfc-editor.org/rfc/rfc6920 RFC 6920} for the `ni:` URI format.
+     */
+    uri: typeof Schema.String;
+}>]>;
+export type BlobData = Schema.Schema.Type<typeof BlobData>;
+declare const Blob_base: Type.ObjClass<Blob, {
+    readonly type?: string | undefined;
+    readonly size: number;
+    readonly data: {
+        readonly _tag: "inline";
+        readonly bytes: Uint8Array<ArrayBufferLike>;
+    } | {
+        readonly _tag: "external";
+        readonly uri: string;
+    };
+}, {}>;
+/**
+ * Runtime schema for a Blob object.
+ *
+ * NOTE: This export shadows the DOM `Blob` global within modules that import it as a namespace.
+ * Code that needs the DOM class should use `globalThis.Blob` explicitly.
+ *
+ * @example
+ * ```ts
+ * const blob = yield* Blob.fromBytes(bytes, { type: 'image/png' });
+ * ```
+ */
+export declare class Blob extends Blob_base {
+}
+/**
+ * Storage backend names, selected at write time via {@link FromBytesOptions.storage}. Call sites
+ * always use these constants, never raw string literals. Extensions (e.g. plugin-wnfs) define
+ * their own storage names in their own package — core code knows nothing of them.
+ *
+ * Distinct from {@link Scheme}: a storage name picks *where* to write, a URI scheme describes
+ * *what the identifier is* at read time. They coincide for backends with no content-addressing
+ * (e.g. wnfs uses `'wnfs'` for both), but the edge backend's storage name (`'edge'`) differs from
+ * its URI scheme (`Scheme.ni`) because the identifier it produces is a content hash, not an
+ * edge-specific address.
+ */
+export declare const Storage: {
+    readonly inline: 'inline';
+    readonly edge: 'edge';
+};
+export type Storage = (typeof Storage)[keyof typeof Storage];
+/**
+ * URI schemes claimed by core backends (see `BlobBackend.schemes` in `@dxos/echo-protocol`).
+ *
+ * `ni` marks an {@link https://www.rfc-editor.org/rfc/rfc6920 RFC 6920} Named Information URI whose
+ * authority is empty and whose path carries a registered hash-algorithm name plus a base64url-encoded
+ * digest (e.g. `ni:///sha-256;UyaQNQIUxQKgg1jVMKMbg1Yr8Rrb2Y3RaOx2N0mVJhc`, produced by the edge
+ * backend). The scheme names *what the identifier is* — a content digest over the complete blob —
+ * not which backend wrote it, so any backend or cache that can resolve that digest may claim it.
+ * The URI is an identity claim, not a retrievability promise; transport is selected by the registered
+ * backend at read time.
+ *
+ * Extensions (e.g. plugin-wnfs) define their own schemes in their own package.
+ */
+export declare const Scheme: {
+    readonly ni: 'ni';
+};
+export type Scheme = (typeof Scheme)[keyof typeof Scheme];
+export declare const MAX_INLINE_SIZE: number;
+/**
+ * Creates a new blob object. Does not add it to the database — see {@link fromBytes}.
+ */
+export declare const make: (props: Obj.MakeProps<typeof Blob>) => Blob;
+/**
+ * Creates an inline {@link BlobData} variant that embeds raw bytes on the ECHO object.
+ */
+export declare const inlineData: (bytes: Uint8Array) => BlobData;
+/**
+ * Creates an external {@link BlobData} variant that references bytes held by a registered backend.
+ * @param uri - Backend-scoped URI, e.g. as returned by a `BlobBackend.put` call.
+ */
+export declare const externalData: (uri: string) => BlobData;
+export interface FromBytesOptions {
+    /** MIME type. */
+    type?: string;
+    /**
+     * Storage backend name. Defaults to the registry's configured default (initially `'inline'`;
+     * `@dxos/client` marks `'edge'` as the default when configured).
+     */
+    storage?: Storage | (string & {});
+}
+/**
+ * Hashes and uploads `bytes` via the chosen storage backend (a no-op for `inline`), returning an
+ * un-added Blob object. The caller is responsible for adding it to the database.
+ *
+ * @example
+ * ```ts
+ * const blob = yield* Blob.fromBytes(bytes, { type: 'image/png' });
+ * yield* Database.add(blob);
+ * ```
+ */
+export declare const fromBytes: (bytes: Uint8Array, options?: FromBytesOptions) => Effect.Effect<Blob, Err.BlobTooLargeError | Err.BlobWriteError, Database.Service>;
+/**
+ * Loads a blob's bytes. Inline: read directly off the object. External: dispatched to the
+ * registered backend for the URI's scheme.
+ *
+ * @example
+ * ```ts
+ * const bytes = yield* Blob.read(blob);
+ * ```
+ */
+export declare const read: (blob: Blob) => Effect.Effect<Uint8Array, Err.BlobNotAvailableError, Database.Service>;
+/**
+ * Checks whether a blob's bytes are currently available.
+ */
+export declare const exists: (blob: Blob) => Effect.Effect<boolean, never, Database.Service>;
+/**
+ * Returns a renderable URL for the blob: inline blobs resolve to a `data:` URL; external blobs
+ * are resolved by the registered backend's `getUrl`, if it implements one.
+ */
+export declare const url: (blob: Blob) => Effect.Effect<Option.Option<string>, never, Database.Service>;
+export {};
+//# sourceMappingURL=Blob.d.ts.map

package/dist/types/src/Blob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Blob.d.ts","sourceRoot":"","sources":["../../../src/Blob.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAKxC,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAE7B,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAE/B;;GAEG;AACH,eAAO,MAAM,UAAU;;EAErB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY;IACvB;;;;;;;OAOG;;EAEH,CAAC;AAEH,eAAO,MAAM,QAAQ;;;IAXnB;;;;;;;OAOG;;IAIyD,CAAC;AAC/D,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,QAAQ,CAAC,CAAC;;;;;;;;;;;;AAE3D;;;;;;;;;;GAUG;AACH,qBAAa,IAAK,SAAQ,SAUzB;CAAG;AAMJ;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO;aAAK,MAAM,EAAE,QAAQ;aAAE,IAAI,EAAE,MAAM;CAAW,CAAC;AACnE,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,OAAO,OAAO,CAAC,CAAC;AAE7D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM;aAAK,EAAE,EAAE,IAAI;CAAW,CAAC;AAC5C,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;AAM1D,eAAO,MAAM,eAAe,QAAkB,CAAC;AAE/C;;GAEG;AACH,eAAO,MAAM,IAAI,UAAW,GAAG,CAAC,SAAS,CAAC,OAAO,IAAI,CAAC,KAAG,IAA6B,CAAC;AAEvF;;GAEG;AACH,eAAO,MAAM,UAAU,UAAW,UAAU,KAAG,QAAuC,CAAC;AAEvF;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAS,MAAM,KAAG,QAAuC,CAAC;AAEnF,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;CACnC;AAMD;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,UACb,UAAU,YACP,gBAAgB,KACzB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,iBAAiB,GAAG,GAAG,CAAC,cAAc,EAAE,QAAQ,CAAC,OAAO,CAWxC,CAAC;AAE5C;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI,SAAU,IAAI,KAAG,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,GAAG,CAAC,qBAAqB,EAAE,QAAQ,CAAC,OAAO,CAcjE,CAAC;AAEvC;;GAEG;AACH,eAAO,MAAM,MAAM,SAAU,IAAI,KAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,CAAC,OAAO,CAG/E,CAAC;AAEJ;;;GAGG;AACH,eAAO,MAAM,GAAG,SAAU,IAAI,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,OAAO,CAIxD,CAAC"}

package/dist/types/src/Blob.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Blob.test.d.ts.map

package/dist/types/src/Blob.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Blob.test.d.ts","sourceRoot":"","sources":["../../../src/Blob.test.ts"],"names":[],"mappings":""}

package/dist/types/src/Database.d.ts

@@ -2,7 +2,10 @@ import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import * as Schema from 'effect/Schema';
+import * as Stream from 'effect/Stream';
+import type { CleanupFn } from '@dxos/async';
 import { type SpaceId, type URI } from '@dxos/keys';
+import type * as Blob from './Blob';
 import type * as Entity from './Entity';
 import * as Err from './Err';
 import type * as Feed from './Feed';
@@ -42,6 +45,13 @@ export type AddOptions = {
      * @default 'linked-doc'
      */
     placeIn?: ObjectPlacement;
+    /**
+     * Append the object to this feed instead of the automerge-backed space database. The object is
+     * returned synchronously (a live feed object) and persisted in the background — confirm the write
+     * completed with {@link Database.flush}. Synchronous alternative to the async
+     * {@link Database.appendToFeed}; `placeIn` is ignored when set.
+     */
+    to?: Feed.Feed;
 };
 /**
  * Rejects Type entities from {@link Database.add} at compile time via their `[KindId]` brand. Used
@@ -71,6 +81,17 @@ export type FlushOptions = {
      */
     updates?: boolean;
 };
+/**
+ * A caller-owned, writable **independent instance** of one object bound to one branch: a distinct
+ * object instance (not a UI surface), separate from the device-global canonical object.
+ * @see Database.branch
+ */
+export type BranchBinding<T extends Obj.Unknown = Obj.Unknown> = {
+    /** Live object bound to the branch document (`'main'` -> the canonical live object). */
+    readonly object: T;
+    /** Release the binding (drops the doc-handle listener; never deletes the branch document). */
+    dispose(): void;
+};
 /**
  * Identifier denoting an ECHO Database.
  */
@@ -113,6 +134,8 @@ export interface Database extends Queryable {
      *
      * Only Object and Relation entities are accepted. To persist a Type definition use
      * {@link addType} — passing a Type entity is rejected at compile time (and at runtime).
+     *
+     * Pass `{ to: feed }` to append to a feed instead (synchronous; confirm with {@link flush}).
      */
     add<T extends Entity.Unknown = Entity.Unknown>(obj: T & RejectTypeEntity<T>, opts?: AddOptions): T;
     /**
@@ -144,13 +167,48 @@ export interface Database extends Queryable {
      */
     flush(opts?: FlushOptions): Promise<void>;
     /**
-     * Removes feed items by ID.
+     * The device-global current branch for an object id (`'main'` by default).
+     * @deprecated Prefer `Obj.getBranch(obj)` — it takes the object and reports the branch of that
+     * specific instance (including `db.branch()` independent instances), not just the device selection.
      */
-    removeFeedItemsByIds(feed: Feed.Feed, ids: string[]): Promise<void>;
+    getCurrentBranch(objectId: string): string;
+    /**
+     * An immutable snapshot of the object at the given historical heads — a detached instance, not a
+     * pin on the live object. Prefer `Obj.getVersion(obj, heads)`.
+     */
+    getVersion<T extends Obj.Unknown>(obj: T, heads: readonly string[]): Obj.Snapshot<T>;
+    /** All branch names available for an object, including the implicit `'main'` (always first). */
+    listBranches(objectId: string): string[];
+    /**
+     * Fork the object and its referenced subtree into a new branch (does not switch to it).
+     * @param opts.fromHeads Fork from a historical frontier instead of the tip (a bare heads array
+     *   applies to the root only; a map forks each member from its own frontier).
+     */
+    createBranch(rootObjectId: string, name: string, opts?: {
+        fromHeads?: readonly string[] | Record<string, readonly string[]>;
+    }): Promise<void>;
+    /** Switch the object's subtree to a branch (or back to `'main'`). Device-local; cascades to children. */
+    switchBranch(rootObjectId: string, name: string): Promise<void>;
+    /** Merge a branch back into main across the subtree, then switch back to main. */
+    mergeBranch(rootObjectId: string, name: string, opts?: {
+        deleteAfter?: boolean;
+    }): Promise<void>;
+    /** Fold main's changes into a branch across the subtree (the reverse of {@link mergeBranch}). */
+    syncBranch(rootObjectId: string, name: string): Promise<void>;
+    /** Delete a branch (its documents lose their sync reference). Cannot delete `'main'`. */
+    deleteBranch(rootObjectId: string, name: string): void;
+    /**
+     * Create a caller-owned, writable binding to one branch of one object — a live object whose reads
+     * resolve the branch document and whose writes land on the branch document only. Multiple bindings
+     * to different branches of the same object may coexist; the device-global current branch and other
+     * bindings are unaffected. Binding to `'main'` returns the canonical live object. Bindings are
+     * ephemeral and never persisted — the caller must `dispose()`.
+     */
+    branch<T extends Obj.Unknown>(obj: T, name: string): Promise<BranchBinding<T>>;
     /**
-     * Queries items in a feed associated with this database.
+     * Removes feed items by ID.
      */
-    queryFeed(feed: Feed.Feed, queryOrFilter: Query.Any | Filter.Any): QueryResult.QueryResult<any>;
+    removeFeedItemsByIds(feed: Feed.Feed, ids: string[]): Promise<void>;
     /**
      * Syncs a feed with the server.
      */
@@ -159,6 +217,45 @@ export interface Database extends Queryable {
      * Returns queue replication backlog for the feed's namespace.
      */
     getFeedSyncState(feed: Feed.Feed): Promise<Feed.SyncState>;
+    /**
+     * Disposes and drops the in-memory handle (live working-set / core cache) for a feed, so the next
+     * access re-reads it cold. Advanced cache-control; primarily used by tests to model a spawned
+     * process reading the feed with an empty in-memory cache. Public (not `_`-prefixed) so it survives
+     * declaration stripping for cross-package test use.
+     */
+    evictFeedHandle(feed: Feed.Feed): Promise<void>;
+    /**
+     * Hashes and uploads `bytes` via the chosen storage backend, returning an un-added Blob object.
+     * Rejects with `Err.BlobTooLargeError` (over inline storage's fixed cap, or the backend's own
+     * `maxSize`), `Err.BlobWriteError` (backend upload failure), or `Err.BlobNotAvailableError`
+     * (`reason: 'backend-not-registered'` — the requested storage name has no registered backend).
+     */
+    createBlob(bytes: Uint8Array, options?: {
+        type?: string;
+        storage?: string;
+    }): Promise<Blob.Blob>;
+    /**
+     * Loads a blob's bytes. Rejects with `Err.BlobNotAvailableError` if the backend for the blob's
+     * storage scheme is not registered, offline, or cannot find the bytes.
+     */
+    readBlob(blob: Blob.Blob): Promise<Uint8Array>;
+    /**
+     * Checks whether a blob's bytes are currently available.
+     */
+    blobExists(blob: Blob.Blob): Promise<boolean>;
+    /**
+     * Returns a renderable URL for the blob, if one can be produced.
+     */
+    getBlobUrl(blob: Blob.Blob): Promise<string | undefined>;
+    /**
+     * Get the current combined (automerge documents + feed blocks) sync state, reported against a
+     * single remote peer.
+     */
+    getSyncState(options?: GetSyncStateOptions): Promise<SyncState>;
+    /**
+     * Subscribe to combined sync state changes.
+     */
+    subscribeToSyncState(cb: (state: SyncState) => void, options?: GetSyncStateOptions): CleanupFn;
 }
 export declare const isDatabase: (obj: unknown) => obj is Database;
 export declare const Database: Schema.Schema<Database>;
@@ -242,5 +339,57 @@ export declare const query: {
     <Q extends Query.Any>(query: Q): QueryResult.QueryResultEffect<Query.Type<Q>, never, Service>;
     <F extends Filter.Any>(filter: F): QueryResult.QueryResultEffect<Filter.Type<F>, never, Service>;
 };
+/**
+ * Sync state of the database in relation to EDGE.
+ */
+export interface SyncState {
+    /**
+     * Total number of documents locally.
+     */
+    readonly localDocumentCount: number;
+    /**
+     * Total number of documents on the remote peer.
+     */
+    readonly remoteDocumentCount: number;
+    /**
+     * Total number of documents across this peer and the remote peer.
+     */
+    readonly totalDocumentCount: number;
+    /**
+     * Total number of documents that are not synced.
+     * Includes documents that are present only locally, only on the remote peer, or whether the peers have different versions.
+     */
+    readonly unsyncedDocumentCount: number;
+    /**
+     * Blocks still to pull from remote. 0 when caught up.
+     */
+    readonly blocksToPull: string;
+    /**
+     * Unpositioned blocks still to push to remote. 0 when caught up.
+     */
+    readonly blocksToPush: string;
+    /**
+     * Total blocks stored locally for this namespace in the space.
+     */
+    readonly totalBlocks: string;
+}
+/**
+ * Options for reading combined sync state.
+ */
+export interface GetSyncStateOptions {
+    /**
+     * Peer to report the automerge document backlog against. Defaults to the EDGE peer.
+     * Provide explicitly in local/test topologies where there is no EDGE peer.
+     */
+    readonly peerId?: string;
+}
+/**
+ * Get the current sync state.
+ */
+export declare const getSyncState: (options?: GetSyncStateOptions) => Effect.Effect<SyncState, never, Service>;
+/**
+ * Subscribe to sync state changes.
+ */
+export declare const subscribeToSyncState: (options?: GetSyncStateOptions) => Stream.Stream<SyncState, never, Service>;
 export {};
 //# sourceMappingURL=Database.d.ts.map

package/dist/types/src/Database.d.ts.map

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

package/dist/types/src/Err.d.ts

@@ -127,6 +127,122 @@ declare const TextEditNotFoundError_base: {
 export declare class TextEditNotFoundError extends TextEditNotFoundError_base {
     constructor(oldString: string, options?: BaseErrorOptions);
 }
+declare const BlobTooLargeError_base: {
+    new (options?: BaseErrorOptions): {
+        cause?: unknown;
+        stack?: string;
+        name: "BlobTooLargeError";
+        context: Record<string, unknown>;
+        readonly message: string;
+        readonly _tag: "BlobTooLargeError";
+    };
+    isError(error: unknown): error is Error;
+    name: "BlobTooLargeError";
+    is(error: unknown): error is BaseError;
+    wrap(options?: Omit<BaseErrorOptions, 'cause'> & {
+        ifTypeDiffers?: boolean;
+    }): (error: unknown) => {
+        cause?: unknown;
+        stack?: string;
+        name: "BlobTooLargeError";
+        context: Record<string, unknown>;
+        readonly message: string;
+        readonly _tag: "BlobTooLargeError";
+    };
+    extend<Name extends string = string>(name: Name, message?: string): any;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};
+/**
+ * Thrown when a blob's bytes exceed the size limit of the storage backend writing them (inline
+ * storage's fixed cap, or a registered backend's own `maxSize`).
+ */
+export declare class BlobTooLargeError extends BlobTooLargeError_base {
+    constructor(context: {
+        size: number;
+        limit: number;
+    }, options?: BaseErrorOptions);
+}
+/**
+ * Reason why a blob's bytes could not be read.
+ * - `offline`: The backend's transport failed (e.g. network unavailable).
+ * - `not-found`: The backend could not locate the bytes for the given URI.
+ * - `backend-not-registered`: No backend is registered for the URI's scheme.
+ */
+export type BlobNotAvailableReason = 'offline' | 'not-found' | 'backend-not-registered';
+declare const BlobNotAvailableError_base: {
+    new (options?: BaseErrorOptions): {
+        cause?: unknown;
+        stack?: string;
+        name: "BlobNotAvailableError";
+        context: Record<string, unknown>;
+        readonly message: string;
+        readonly _tag: "BlobNotAvailableError";
+    };
+    isError(error: unknown): error is Error;
+    name: "BlobNotAvailableError";
+    is(error: unknown): error is BaseError;
+    wrap(options?: Omit<BaseErrorOptions, 'cause'> & {
+        ifTypeDiffers?: boolean;
+    }): (error: unknown) => {
+        cause?: unknown;
+        stack?: string;
+        name: "BlobNotAvailableError";
+        context: Record<string, unknown>;
+        readonly message: string;
+        readonly _tag: "BlobNotAvailableError";
+    };
+    extend<Name extends string = string>(name: Name, message?: string): any;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};
+/**
+ * Thrown when a blob's bytes cannot be read from its backend.
+ */
+export declare class BlobNotAvailableError extends BlobNotAvailableError_base {
+    constructor(context: {
+        backend: string;
+        key: string;
+        reason: BlobNotAvailableReason;
+    }, options?: BaseErrorOptions);
+}
+declare const BlobWriteError_base: {
+    new (options?: BaseErrorOptions): {
+        cause?: unknown;
+        stack?: string;
+        name: "BlobWriteError";
+        context: Record<string, unknown>;
+        readonly message: string;
+        readonly _tag: "BlobWriteError";
+    };
+    isError(error: unknown): error is Error;
+    name: "BlobWriteError";
+    is(error: unknown): error is BaseError;
+    wrap(options?: Omit<BaseErrorOptions, 'cause'> & {
+        ifTypeDiffers?: boolean;
+    }): (error: unknown) => {
+        cause?: unknown;
+        stack?: string;
+        name: "BlobWriteError";
+        context: Record<string, unknown>;
+        readonly message: string;
+        readonly _tag: "BlobWriteError";
+    };
+    extend<Name extends string = string>(name: Name, message?: string): any;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};
+/**
+ * Thrown when a blob's bytes fail to upload to its backend.
+ */
+export declare class BlobWriteError extends BlobWriteError_base {
+    constructor(context: {
+        backend: string;
+    }, options?: BaseErrorOptions);
+}
 /**
  * Reason why getting a reactive object from a snapshot failed.
  * - `no-database`: The snapshot is not associated with a database.

package/dist/types/src/Err.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Err.d.ts","sourceRoot":"","sources":["../../../src/Err.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEtC,qBAAa,mBAAoB,SAAQ,wBAA2D;IAClG,YAAY,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,EAErD;CACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAED,qBAAa,mBAAoB,SAAQ,wBAA2D;IAClG,YAAY,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,gBAAgB,EAEnD;CACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,0BAG1C;IACC,YAAY,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,EAExD;CACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,0BAAgE;IACzG,YAAY,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,EAExD;CACF;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,aAAa,GAAG,kBAAkB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAExE;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,qBAGrC;IACC,YAAY,OAAO,EAAE;QAAE,MAAM,EAAE,sBAAsB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,gBAAgB,EAE9F;CACF"}
+{"version":3,"file":"Err.d.ts","sourceRoot":"","sources":["../../../src/Err.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEtC,qBAAa,mBAAoB,SAAQ,wBAA2D;IAClG,YAAY,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,EAErD;CACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAED,qBAAa,mBAAoB,SAAQ,wBAA2D;IAClG,YAAY,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,gBAAgB,EAEnD;CACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,0BAG1C;IACC,YAAY,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,EAExD;CACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,0BAAgE;IACzG,YAAY,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,EAExD;CACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,sBAA0E;IAC/G,YAAY,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,EAE/E;CACF;AAED;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,WAAW,GAAG,wBAAwB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAExF;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,0BAAkE;IAC3G,YAAY,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,sBAAsB,CAAA;KAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,EAEhH;CACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,mBAA0D;IAC5F,YAAY,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,EAEnE;CACF;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,aAAa,GAAG,kBAAkB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAExE;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,qBAGrC;IACC,YAAY,OAAO,EAAE;QAAE,MAAM,EAAE,sBAAsB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,gBAAgB,EAE9F;CACF"}