@dxos/echo 0.10.0 → 0.11.1

package/src/Feed.ts

@@ -11,17 +11,19 @@ import * as Layer from 'effect/Layer';
 import type * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 
-import { DXN, EID } from '@dxos/keys';
+import { KEY_QUEUE_POSITION } from '@dxos/echo-protocol';
+import { invariant } from '@dxos/invariant';
+import { DXN, EID, EntityId } from '@dxos/keys';
 
 import * as Annotation from './Annotation';
 import * as Database from './Database';
 import type * as Entity from './Entity';
 import type * as Filter from './Filter';
 import * as internal from './internal';
-import * as queryInternal from './internal/Query';
 import * as Obj from './Obj';
-import type * as Query from './Query';
+import * as Query from './Query';
 import type * as QueryResult from './QueryResult';
+import * as Scope from './Scope';
 import * as Type from './Type';
 
 /**
@@ -36,6 +38,7 @@ export class Feed extends Type.makeObject<Feed>(DXN.make('org.dxos.type.feed', '
   Schema.Struct({
     /** User-facing display name. */
     name: Schema.String.pipe(Schema.optional),
+
     /** Identifier for the feed's kind (e.g., plugin id). */
     kind: Schema.String.pipe(internal.FormInputAnnotation.set(false), Schema.optional),
 
@@ -46,6 +49,20 @@ export class Feed extends Type.makeObject<Feed>(DXN.make('org.dxos.type.feed', '
      * - `trace`: Trace feed.
      */
     namespace: Schema.optional(Schema.Literal('data', 'trace')),
+
+    /**
+     * Earliest item a pending rewind discards — set when a soft fork is decided but not yet expressed,
+     * because the writer may be a different process than the one that decided it.
+     *
+     * Stored as the first *discarded* item rather than the new parent so that rewinding to the very
+     * first item needs no sentinel: nothing precedes it, so the continuation simply starts a new line.
+     * Readers show what precedes it; the next append parents to that and clears this.
+     *
+     * Transient intent, never a source of truth for history. The fork itself lives in item lineage
+     * (see {@link PARENT_KEY}), which is what {@link history} walks and what replicates in a defined
+     * order relative to the blocks.
+     */
+    rewindFrom: Schema.optional(Obj.ID.pipe(internal.FormInputAnnotation.set(false))),
   }).pipe(
     internal.HiddenAnnotation.set(true),
     Annotation.IconAnnotation.set({ icon: 'ph--rows--regular', hue: 'yellow' }),
@@ -66,6 +83,12 @@ export interface Cursor<T = Obj.Snapshot> {
 
 /**
  * Retention options for a feed.
+ *
+ * Live feed objects persist every `Obj.update` as a whole-object re-append reusing the object's id
+ * (see `EchoFeedCodec.encode`), so superseded blocks accumulate indefinitely — retention/compaction
+ * of those superseded blocks (driven by these options, once implemented) is the reclaim mechanism.
+ * TODO(wittjosiah): Implement when feed retention is supported (see `setRetention` below and
+ * `FeedStore.appendLocal`).
  */
 export interface RetentionOptions {
   /** Retain items after this cursor position. */
@@ -73,6 +96,42 @@ export interface RetentionOptions {
   cursor?: string;
 }
 
+/**
+ * Options for {@link append}.
+ */
+export interface AppendOptions {
+  /**
+   * Explicit lineage parent for the appended items — the soft-fork point.
+   * Applies to the first item only; the rest of the batch chain implicitly in append order.
+   */
+  parent?: Entity.Unknown | Entity.Snapshot | EntityId;
+}
+
+/**
+ * Options for {@link history}.
+ */
+export interface HistoryOptions {
+  /**
+   * Item to walk the history from, as git's `HEAD` selects which commits are reachable.
+   * Defaults to the last item, so the most recently appended line of items wins.
+   */
+  head?: Entity.Unknown | Entity.Snapshot | EntityId;
+}
+
+/**
+ * The items reachable from a head by following lineage — a feed's equivalent of
+ * `git log --first-parent`.
+ */
+export interface History<T> {
+  /** The reachable items, in append order. */
+  items: T[];
+  /**
+   * A parent was referenced but could not be resolved, so the walk stopped at a boundary and
+   * earlier history is missing — the same condition as a git shallow clone.
+   */
+  shallow: boolean;
+}
+
 /**
  * Sync options for a feed.
  */
@@ -110,50 +169,6 @@ export class ContextFeedService extends Context.Tag('@dxos/echo/Feed/ContextFeed
   static layer = (feed: Feed) => Layer.succeed(ContextFeedService, { feed });
 }
 
-//
-// Service
-//
-
-/**
- * Effect service for feed operations.
- * @deprecated Use `Database.Service` instead — feed operations now run directly on the database.
- */
-export class FeedService extends Context.Tag('@dxos/echo/Feed/FeedService')<
-  FeedService,
-  {
-    append(feed: Feed, items: Entity.Unknown[]): Promise<void>;
-    remove(feed: Feed, ids: string[]): Promise<void>;
-    query: {
-      <Q extends Query.Any>(feed: Feed, query: Q): QueryResult.QueryResult<Query.Type<Q>>;
-      <F extends Filter.Any>(feed: Feed, filter: F): QueryResult.QueryResult<Filter.Type<F>>;
-    };
-    sync(feed: Feed, options?: SyncOptions): Promise<void>;
-    getSyncState(feed: Feed): Promise<SyncState>;
-  }
->() {}
-
-/**
- * Layer that provides a `FeedService` that throws when accessed.
- * @deprecated Use `Database.layer(db)` instead.
- */
-export const notAvailable: Layer.Layer<FeedService> = Layer.succeed(FeedService, {
-  append: () => {
-    throw new Error('Feed.FeedService not available');
-  },
-  remove: () => {
-    throw new Error('Feed.FeedService not available');
-  },
-  query: () => {
-    throw new Error('Feed.FeedService not available') as never;
-  },
-  sync: () => {
-    throw new Error('Feed.FeedService not available');
-  },
-  getSyncState: () => {
-    throw new Error('Feed.FeedService not available');
-  },
-} as Context.Tag.Service<FeedService>);
-
 //
 // Factory
 //
@@ -172,9 +187,12 @@ export const make = (props: Obj.MakeProps<typeof Feed> = {}): Feed => Obj.make(F
 /**
  * Returns the feed object's EID when the feed is stored in a space.
  *
- * Used internally by the feed service layer.
+ * Private-ish and on track to be removed — prefer resolving feed scopes via higher-level APIs
+ * (e.g. `Feed.query`) rather than threading the raw queue URI. Used internally by the feed service
+ * layer.
  */
-export const getQueueUri = (feed: Feed): EID.EID | undefined => EID.tryParse(Obj.getURI(feed));
+// TODO(dmaretskyi): Remove — private-ish, prefer higher-level feed-scope APIs.
+export const getFeedUri = (feed: Feed): EID.EID | undefined => EID.tryParse(Obj.getURI(feed));
 
 //
 // Operations
@@ -183,15 +201,33 @@ export const getQueueUri = (feed: Feed): EID.EID | undefined => EID.tryParse(Obj
 /**
  * Appends items to a feed.
  *
+ * Pass `options.parent` to soft-fork the feed: the first appended item continues from that item
+ * rather than from the feed's tip, so everything appended between the two becomes unreachable from
+ * {@link history}. Nothing is removed from the log.
+ *
  * @example
  * ```ts
  * yield* Feed.append(feed, [Obj.make(Notification, { title: 'Hello' })]);
+ *
+ * // Continue from an earlier item, leaving what followed it unreachable.
+ * yield* Feed.append(feed, [Obj.make(Notification, { title: 'Take two' })], { parent: earlier });
  * ```
  */
-export const append = (feed: Feed, items: Entity.Unknown[]): Effect.Effect<void, never, Database.Service> =>
-  Database.Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.appendToFeed(feed, items)))).pipe(
-    Effect.withSpan('Feed.append'),
-  );
+export const append = (
+  feed: Feed,
+  items: Entity.Unknown[],
+  options?: AppendOptions,
+): Effect.Effect<void, never, Database.Service> =>
+  Database.Service.pipe(
+    Effect.flatMap(({ db }) =>
+      Effect.promise(() => {
+        if (options?.parent !== undefined && items.length > 0) {
+          setParent(items[0], options.parent);
+        }
+        return db.appendToFeed(feed, items);
+      }),
+    ),
+  ).pipe(Effect.withSpan('Feed.append'));
 
 /**
  * Removes items from a feed.
@@ -217,6 +253,147 @@ export const remove = (
     ),
   ).pipe(Effect.withSpan('Feed.remove'));
 
+//
+// Lineage (soft fork)
+//
+
+/**
+ * Foreign-key source for an item's explicit lineage parent within a feed.
+ *
+ * Lineage is carried in item `@meta` because feed items are arbitrary ECHO objects that the feed
+ * does not own and cannot extend; `KEY_QUEUE_POSITION` rides along with feed blocks the same way.
+ */
+export const PARENT_KEY = 'org.dxos.key.feed-parent';
+
+/**
+ * Tri-state read of the lineage key, distinguishing an absent key from a present but malformed one.
+ * A replicated id that does not parse must not read as "no parent" — that would resolve a fork as
+ * an implicit continuation and silently expose the items it abandoned.
+ */
+const readParent = (item: Entity.Unknown | Entity.Snapshot): { present: boolean; id?: EntityId } => {
+  const id = internal.getKeys(item, PARENT_KEY).at(0)?.id;
+  if (id === undefined) {
+    return { present: false };
+  }
+  return EntityId.isValid(id) ? { present: true, id } : { present: true };
+};
+
+/**
+ * Foreign-key source for the global position a position authority assigned a feed item.
+ * Exposed alongside {@link getPosition} so callers can stamp or inspect it without reaching for
+ * `@dxos/protocols`.
+ */
+export const POSITION_KEY = KEY_QUEUE_POSITION;
+
+/**
+ * The global position a feed item was assigned, or `+Infinity` when it has none — a block written
+ * locally and not yet acknowledged, which sorts last because it is the newest.
+ *
+ * Use this to put items into append order before calling {@link history}: a query returns an unordered
+ * set, and `created` is a wall clock that peers do not agree on.
+ *
+ * @example
+ * ```ts
+ * const inAppendOrder = Array.sort(messages, Order.mapInput(Order.number, Feed.getPosition));
+ * const { items } = Feed.history(inAppendOrder);
+ * ```
+ */
+export const getPosition = (item: Entity.Unknown | Entity.Snapshot): number => {
+  const key = internal.getKeys(item, KEY_QUEUE_POSITION).at(0)?.id;
+  const position = key !== undefined ? Number(key) : Number.NaN;
+  return Number.isNaN(position) ? Number.POSITIVE_INFINITY : position;
+};
+
+/**
+ * Returns an item's explicit lineage parent, or `undefined` when it continues from the item that
+ * precedes it in append order (the default for every feed).
+ *
+ * Also `undefined` for a malformed stored id; {@link history} tells the two apart and reports
+ * a malformed parent as truncation.
+ */
+export const getParent = (item: Entity.Unknown | Entity.Snapshot): EntityId | undefined => readParent(item).id;
+
+/**
+ * Sets (or, with `undefined`, clears) an item's explicit lineage parent.
+ * Call before appending the item; {@link append}'s `parent` option does this for you.
+ */
+export const setParent = (
+  item: Entity.Unknown,
+  parent: Entity.Unknown | Entity.Snapshot | EntityId | undefined,
+): void => {
+  internal.change(item, (mutable) => {
+    internal.deleteKeys(mutable, PARENT_KEY);
+    if (parent !== undefined) {
+      const id = typeof parent === 'string' ? parent : parent.id;
+      internal.getMetaChecked(mutable).keys.push(internal.foreignKey(PARENT_KEY, id));
+    }
+  });
+};
+
+/**
+ * Returns the items reachable from a head by following lineage — a feed's `git log --first-parent`.
+ *
+ * Walks backwards from the head: an item with an explicit lineage parent jumps to that item, leaving
+ * everything appended in between unreachable; an item without one steps to its predecessor. So a
+ * feed appended as `M1, M2, M3, M4, M5(M3)` yields `M1, M2, M3, M5`, with `M4` unreachable but still
+ * present in the log — the log is the object store, this function is what HEAD reaches.
+ *
+ * `items` must be in **append order** — the walk is positional, and pre-sorting by a wall-clock
+ * field such as `created` would corrupt it. Lineage is resolved over exactly the list passed in, so
+ * a parent excluded by the caller's filter reads as absent (`shallow`), same as one that has not
+ * replicated yet or whose stored id does not parse.
+ *
+ * @example
+ * ```ts
+ * const messages = yield* Feed.query(feed, Filter.type(Message.Message)).run;
+ * const { items, shallow } = Feed.history(messages);
+ * ```
+ */
+export const history = <T extends Entity.Unknown | Entity.Snapshot>(
+  items: readonly T[],
+  options?: HistoryOptions,
+): History<T> => {
+  const indexById = new Map<EntityId, number>();
+  items.forEach((item, index) => indexById.set(item.id, index));
+
+  const head = options?.head;
+  const headIndex = head === undefined ? items.length - 1 : indexById.get(typeof head === 'string' ? head : head.id);
+  if (headIndex === undefined) {
+    return { items: [], shallow: true };
+  }
+
+  let cursor = headIndex;
+  const reachable: T[] = [];
+  let shallow = false;
+  while (cursor >= 0) {
+    const item = items[cursor];
+    reachable.push(item);
+
+    const parent = readParent(item);
+    if (!parent.present) {
+      cursor -= 1;
+      continue;
+    }
+    if (parent.id === undefined) {
+      // Key present but unparseable — a fork whose target cannot be identified, so stop rather than
+      // fall through to the predecessor and make what this item superseded reachable again.
+      shallow = true;
+      break;
+    }
+
+    // A parent at or after its child is a cycle or a forward reference (possible with arbitrary
+    // multi-writer data); requiring the cursor to strictly decrease also guarantees termination.
+    const parentIndex = indexById.get(parent.id);
+    if (parentIndex === undefined || parentIndex >= cursor) {
+      shallow = true;
+      break;
+    }
+    cursor = parentIndex;
+  }
+
+  return { items: reachable.reverse(), shallow };
+};
+
 /**
  * Creates a reactive query over items in a feed.
  *
@@ -227,7 +404,7 @@ export const remove = (
  * Supports both data-first and data-last (curried) forms; the latter composes with `pipe`.
  *
  * In non-Effect code, query a feed directly through the database with a feed scope:
- * `db.query(Query.select(filter).from(Scope.feed(Feed.getQueueUri(feed))))`.
+ * `db.query(Query.select(filter).from(Scope.feed(Feed.getFeedUri(feed))))`.
  *
  * @example
  * ```ts
@@ -250,13 +427,12 @@ export const query: {
   <F extends Filter.Any>(
     filter: F,
   ): (feed: Feed) => QueryResult.QueryResultEffect<Filter.Type<F>, never, Database.Service>;
-} = Function.dual(2, (feed: Feed, queryOrFilter: Query.Any | Filter.Any) =>
-  Database.Service.pipe(
-    Effect.map(({ db }) => db.queryFeed(feed, queryOrFilter)),
-    Effect.withSpan('Feed.query'),
-    queryInternal.makeQueryResultEffect,
-  ),
-);
+} = Function.dual(2, (feed: Feed, queryOrFilter: Query.Any | Filter.Any) => {
+  const feedUri = getFeedUri(feed);
+  invariant(feedUri, 'Feed must be stored in the database before accessing its contents');
+  const query = Query.is(queryOrFilter) ? queryOrFilter : Query.select(queryOrFilter);
+  return Database.query(query.from(Scope.feed(feedUri.toString())));
+});
 
 /**
  * Syncs the feed with the server.
@@ -273,7 +449,7 @@ export const sync = (feed: Feed, options?: SyncOptions): Effect.Effect<void, nev
   );
 
 /**
- * Returns queue replication backlog for the feed's namespace.
+ * Returns the feed's replication backlog for its namespace.
  *
  * @example
  * ```ts

package/src/Filter.ts

@@ -20,11 +20,15 @@ import type * as Obj from './Obj';
 import * as Ref from './Ref';
 // eslint-disable-next-line @dxos/rules/import-as-namespace
 import type * as Type$ from './Type';
+
+export const FilterTypeId = '~@dxos/echo/Filter' as const;
+export type FilterTypeId = typeof FilterTypeId;
+
 export interface Filter<T> {
   // TODO(dmaretskyi): See new effect-schema approach to variance.
-  '~Filter': { value: Types.Covariant<T> };
+  readonly [FilterTypeId]: { value: Types.Covariant<T> };
 
-  'ast': QueryAST.Filter;
+  ast: QueryAST.Filter;
 }
 
 export type Props<T> = {
@@ -37,15 +41,15 @@ export type Any = Filter<any>;
 export type Type<F extends Any> = F extends Filter<infer T> ? T : never;
 
 class FilterClass implements Any {
-  private static 'variance': Any['~Filter'] = {} as Any['~Filter'];
+  private static 'variance': Any[FilterTypeId] = {} as Any[FilterTypeId];
 
-  'constructor'(public readonly ast: QueryAST.Filter) {}
+  constructor(public readonly ast: QueryAST.Filter) {}
 
-  '~Filter' = FilterClass.variance;
+  [FilterTypeId] = FilterClass.variance;
 }
 
 export const is = (value: unknown): value is Any => {
-  return typeof value === 'object' && value !== null && '~Filter' in value;
+  return typeof value === 'object' && value !== null && FilterTypeId in value;
 };
 
 /** Construct a filter from an ast. */
@@ -307,13 +311,27 @@ export const lte = <T>(value: T): Filter<T | undefined> => {
 };
 
 /**
- * Predicate for property to be in the provided array.
- * @param values - Values to check against.
+ * Predicate for property to be in the provided array, or in the set of values projected
+ * from a subquery's results (an uncorrelated `col IN (SELECT property FROM ...)` semi-join —
+ * see `Query.project`). The subquery may target a different scope than the parent query; it
+ * is resolved once at execution time.
+ * @param values - Values to check against, or a single subquery projection.
  */
-const in$ = <T>(...values: T[]): Filter<T> => {
+const in$: {
+  <T>(projection: internal.Projection<T>): Filter<T>;
+  <T>(...values: T[]): Filter<T>;
+} = <T>(...args: [internal.Projection<T>] | T[]): Filter<T> => {
+  if (args.length === 1 && internal.isProjection(args[0])) {
+    const projection = args[0];
+    return new FilterClass({
+      type: 'in-query',
+      subquery: projection.query,
+      property: projection.property,
+    });
+  }
   return new FilterClass({
     type: 'in',
-    values,
+    values: args,
   });
 };
 export { in$ as in };

package/src/Hypergraph.ts

@@ -2,6 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
+import { type CleanupFn } from '@dxos/async';
+import { type BlobBackend } from '@dxos/echo-protocol';
 import { type URI } from '@dxos/keys';
 
 import type * as Database from './Database';
@@ -72,4 +74,20 @@ export interface Hypergraph extends Database.Queryable {
    * @returns The database for the given space ID, or undefined if not found.
    */
   getDatabase(spaceId: Key.SpaceId): Database.Database | undefined;
+
+  /**
+   * Registers a pluggable blob storage backend under `name`, claiming its declared URI schemes.
+   * Registering a scheme already claimed by another backend is an error.
+   *
+   * @param options.default - When true, `name` becomes the storage used when
+   *   `Blob.fromBytes`'s `storage` option is omitted.
+   * @returns A cleanup function that unregisters the backend.
+   */
+  registerBlobBackend(name: string, backend: BlobBackend, options?: { default?: boolean }): CleanupFn;
+
+  /**
+   * Storage name `Blob.fromBytes` uses when its `storage` option is omitted. Starts as `'inline'`;
+   * reflects the most recent `registerBlobBackend(name, backend, { default: true })` call.
+   */
+  get defaultBlobStorage(): string;
 }

package/src/Json.ts

@@ -47,6 +47,7 @@ const toJson = (obj: Obj.Any): unknown => (typeof (obj as any).toJSON === 'funct
  * Note: ECHO objects' `toJSON` runs before the replacer is invoked, so by the time we see a
  * value refs are already encoded as `{ "/": "dxn:..." }`.
  */
+// TODO(dmaretskyi): is this used anywhere?
 export const createRefReplacer = ({ db, depth = 1 }: CreateRefReplacerOptions): JsonReplacer => {
   // Per-object hop count. Set when we return an object (via ref resolution or pass-through) so
   // the child callbacks (which carry that object as `this`) can read it.

package/src/Obj.test.ts

@@ -123,10 +123,10 @@ describe('Obj', () => {
       expect(EID.isEID(uri)).toBe(true);
     });
 
-    test("prefer: 'relative' returns local EID echo:/<id>", ({ expect }) => {
+    test("prefer: 'relative' returns local EID echo:///<id>", ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'Alice' });
       const uri = Obj.getURI(obj, { prefer: 'relative' });
-      expect(uri).toMatch(/^echo:\/[^/]/);
+      expect(uri).toMatch(/^echo:\/\/\/[^/]/);
       expect(EID.isLocal(EID.parse(uri))).toBe(true);
     });
 

package/src/Obj.ts

@@ -380,8 +380,9 @@ export type Mutable<T> = internal.Mutable<T>;
  *
  * Note: Only accepts objects. Use `Relation.update` for relations.
  */
-export const update = <T extends Unknown>(obj: T, callback: internal.ChangeCallback<T>): void => {
+export const update = <T extends Unknown>(obj: T, callback: internal.ChangeCallback<T>): T => {
   internal.change(obj, callback);
+  return obj;
 };
 
 /**
@@ -576,6 +577,24 @@ export const getTypename = (entity: Unknown | Snapshot): string | undefined => i
 export const getDatabase = (entity: Entity.Unknown | Entity.Snapshot): Database.Database | undefined =>
   internal.getDatabase(entity);
 
+/**
+ * Get the branch this object instance is bound to: `'main'` for the canonical object, or the branch of
+ * a `db.branch()` independent instance. The branch is a property of the instance — two instances of the
+ * same object id on different branches each report their own branch.
+ */
+export const getBranch = (obj: Unknown): string => internal.getBranch(obj);
+
+/**
+ * Get an immutable snapshot of the object at the given historical heads — a detached instance, not a
+ * pin on the live object. Only the surface that asks for it sees the historical value; the live
+ * object and every other surface are unaffected. The functional alternative to a read-time-travel pin.
+ */
+export const getVersion = <T extends Unknown>(obj: T, heads: readonly string[]): Snapshot<T> => {
+  const db = getDatabase(obj);
+  invariant(db, 'object is not bound to a database');
+  return db.getVersion(obj, heads);
+};
+
 //
 // Meta
 //
@@ -897,6 +916,7 @@ export const toJSON = (entity: Unknown | Snapshot): JSON => objInternal.objectTo
  * @param options.refResolver - Resolver for references. Produces hydrated references that can be resolved.
  * @param options.uri - Override object URI. Changes the result of `Obj.getURI`.
  * @param options.database - Database to associate with the object.
+ * @param options.parent - Parent entity to associate with the object (used when the JSON has no `@parent`). Changes the result of `Obj.getParent`.
  */
 export const fromJSON: (
   json: unknown,

package/src/Order.ts

@@ -6,28 +6,35 @@
 
 import { type QueryAST } from '@dxos/echo-protocol';
 
+export const OrderTypeId = '~@dxos/echo/Order' as const;
+export type OrderTypeId = typeof OrderTypeId;
+
 export interface Order<T> {
-  // TODO(dmaretskyi): See new effect-schema approach to variance.
-  '~Order': { value: T };
+  readonly [OrderTypeId]: { value: T };
 
-  'ast': QueryAST.Order;
+  ast: QueryAST.Order;
 }
 
 export type Any = Order<any>;
 
 class OrderClass implements Order<any> {
-  private static 'variance': Order<any>['~Order'] = {} as Order<any>['~Order'];
+  private static 'variance': Order<any>[OrderTypeId] = {} as Order<any>[OrderTypeId];
 
-  static 'is'(value: unknown): value is Order<any> {
-    return typeof value === 'object' && value !== null && '~Order' in value;
+  static is(value: unknown): value is Any {
+    return typeof value === 'object' && value !== null && OrderTypeId in value;
   }
 
-  'constructor'(public readonly ast: QueryAST.Order) {}
+  constructor(public readonly ast: QueryAST.Order) {}
 
-  '~Order' = OrderClass.variance;
+  [OrderTypeId] = OrderClass.variance;
 }
 
-export const natural: Order<any> = new OrderClass({ kind: 'natural' });
+/**
+ * Order by the database's default order. For non-feed sources this is by id; for feed sources
+ * this is insertion order, so `desc` reads newest-first. Defaults to `asc`.
+ */
+export const natural = (direction: QueryAST.OrderDirection = 'asc'): Order<any> =>
+  new OrderClass({ kind: 'natural', direction });
 export const property = <T>(property: keyof T & string, direction: QueryAST.OrderDirection): Order<T> =>
   new OrderClass({
     kind: 'property',