@dxos/echo 0.10.0 → 0.11.0

package/dist/lib/Feed.mjs

@@ -0,0 +1,338 @@
+import { t as __exportAll } from "./chunk-rolldown-runtime.mjs";
+import { c as getKeys, l as getMetaChecked, m as foreignKey, s as deleteKeys } from "./chunk-atom-snapshot.mjs";
+import { G as HiddenAnnotation, L as FormInputAnnotation, g as query$1, q as IconAnnotation, r as Service } from "./chunk-Database.mjs";
+import { h as change } from "./chunk-ref.mjs";
+import { makeObject } from "./Type.mjs";
+import { ID, getURI, make as make$1 } from "./Obj.mjs";
+import { is, select } from "./Query.mjs";
+import { feed } from "./Scope.mjs";
+import { KEY_QUEUE_POSITION } from "@dxos/echo-protocol";
+import { DXN, EID, EntityId } from "@dxos/keys";
+import * as Function from "effect/Function";
+import * as Schema from "effect/Schema";
+import { invariant } from "@dxos/invariant";
+import * as Effect from "effect/Effect";
+import * as Context from "effect/Context";
+import * as Layer from "effect/Layer";
+//#region src/Feed.ts
+var Feed_exports = /* @__PURE__ */ __exportAll({
+	ContextFeedService: () => ContextFeedService,
+	Feed: () => Feed,
+	PARENT_KEY: () => PARENT_KEY,
+	POSITION_KEY: () => POSITION_KEY,
+	append: () => append,
+	cursor: () => cursor,
+	getFeedUri: () => getFeedUri,
+	getParent: () => getParent,
+	getPosition: () => getPosition,
+	getSyncState: () => getSyncState,
+	history: () => history,
+	make: () => make,
+	next: () => next,
+	nextOption: () => nextOption,
+	query: () => query,
+	remove: () => remove,
+	setParent: () => setParent,
+	setRetention: () => setRetention,
+	sync: () => sync
+});
+var __dxlog_file = "/__w/dxos/dxos/packages/core/echo/echo/src/Feed.ts";
+/**
+* Runtime schema for a Feed object.
+*
+* @example
+* ```ts
+* const feed = Obj.make(Feed.Feed, { name: 'notifications', kind: 'org.dxos.plugin.notifications.v1' });
+* ```
+*/
+var Feed = class extends makeObject(DXN.make("org.dxos.type.feed", "0.1.0"))(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(FormInputAnnotation.set(false), Schema.optional),
+	/**
+	* Feed namespace.
+	* Controls how feed data is stored and replicated.
+	* - `data`: Data feed (default).
+	* - `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(ID.pipe(FormInputAnnotation.set(false)))
+}).pipe(HiddenAnnotation.set(true), IconAnnotation.set({
+	icon: "ph--rows--regular",
+	hue: "yellow"
+}))) {};
+/**
+* Effect service tag for injecting a Feed into effect operations.
+* Used to provide a specific feed to operations that operate on it without threading
+* the feed as an explicit parameter through every call site.
+*/
+var ContextFeedService = class ContextFeedService extends Context.Tag("@dxos/echo/Feed/ContextFeedService")() {
+	static layer = (feed) => Layer.succeed(ContextFeedService, { feed });
+};
+/**
+* Creates a new feed object.
+*
+* @example
+* ```ts
+* const feed = Feed.make({ name: 'notifications', kind: 'org.dxos.plugin.notifications.v1' });
+* ```
+*/
+var make = (props = {}) => make$1(Feed, props);
+/**
+* Returns the feed object's EID when the feed is stored in a space.
+*
+* 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.
+*/
+var getFeedUri = (feed) => EID.tryParse(getURI(feed));
+/**
+* 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 });
+* ```
+*/
+var append = (feed, items, options) => Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => {
+	if (options?.parent !== void 0 && items.length > 0) setParent(items[0], options.parent);
+	return db.appendToFeed(feed, items);
+}))).pipe(Effect.withSpan("Feed.append"));
+/**
+* Removes items from a feed.
+*
+* @example
+* ```ts
+* yield* Feed.remove(feed, [item]);
+* ```
+*/
+var remove = (feed, items) => Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.removeFeedItemsByIds(feed, items.map((item) => item.id))))).pipe(Effect.withSpan("Feed.remove"));
+/**
+* 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.
+*/
+var 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.
+*/
+var readParent = (item) => {
+	const id = getKeys(item, PARENT_KEY).at(0)?.id;
+	if (id === void 0) 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`.
+*/
+var 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);
+* ```
+*/
+var getPosition = (item) => {
+	const key = getKeys(item, KEY_QUEUE_POSITION).at(0)?.id;
+	const position = key !== void 0 ? Number(key) : 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.
+*/
+var getParent = (item) => 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.
+*/
+var setParent = (item, parent) => {
+	change(item, (mutable) => {
+		deleteKeys(mutable, PARENT_KEY);
+		if (parent !== void 0) {
+			const id = typeof parent === "string" ? parent : parent.id;
+			getMetaChecked(mutable).keys.push(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);
+* ```
+*/
+var history = (items, options) => {
+	const indexById = /* @__PURE__ */ new Map();
+	items.forEach((item, index) => indexById.set(item.id, index));
+	const head = options?.head;
+	const headIndex = head === void 0 ? items.length - 1 : indexById.get(typeof head === "string" ? head : head.id);
+	if (headIndex === void 0) return {
+		items: [],
+		shallow: true
+	};
+	let cursor = headIndex;
+	const reachable = [];
+	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 === void 0) {
+			shallow = true;
+			break;
+		}
+		const parentIndex = indexById.get(parent.id);
+		if (parentIndex === void 0 || parentIndex >= cursor) {
+			shallow = true;
+			break;
+		}
+		cursor = parentIndex;
+	}
+	return {
+		items: reachable.reverse(),
+		shallow
+	};
+};
+/**
+* Creates a reactive query over items in a feed.
+*
+* Returns a {@link QueryResult.QueryResultEffect}: yielding it produces a subscribable
+* `QueryResult`, while its `.run` / `.first` shorthands execute the query once. This mirrors
+* `Database.query` so feed and database queries chain identically.
+*
+* 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.getFeedUri(feed))))`.
+*
+* @example
+* ```ts
+* const result = yield* Feed.query(feed, Filter.type(Person));
+* result.subscribe(...);
+*
+* const objects = yield* Feed.query(feed, Filter.type(Person)).run;
+* const object = yield* Feed.query(feed, Filter.type(Person)).first;
+*
+* // Data-last (curried) form composes with `pipe`:
+* const objects = yield* pipe(feed, Feed.query(Filter.type(Person))).run;
+* ```
+*/
+var query = Function.dual(2, (feed$1, queryOrFilter) => {
+	const feedUri = getFeedUri(feed$1);
+	invariant(feedUri, "Feed must be stored in the database before accessing its contents", {
+		"~LogMeta": "~LogMeta",
+		F: __dxlog_file,
+		L: 432,
+		S: void 0,
+		A: ["feedUri", "'Feed must be stored in the database before accessing its contents'"]
+	});
+	return query$1((is(queryOrFilter) ? queryOrFilter : select(queryOrFilter)).from(feed(feedUri.toString())));
+});
+/**
+* Syncs the feed with the server.
+*
+* @example
+* ```ts
+* yield* Feed.sync(feed);
+* yield* Feed.sync(feed, { shouldPush: false });
+* ```
+*/
+var sync = (feed, options) => Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.syncFeed(feed, options)))).pipe(Effect.withSpan("Feed.sync"));
+/**
+* Returns the feed's replication backlog for its namespace.
+*
+* @example
+* ```ts
+* const { blocksToPull, blocksToPush } = yield* Feed.getSyncState(feed);
+* ```
+*/
+var getSyncState = (feed) => Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.getFeedSyncState(feed)))).pipe(Effect.withSpan("Feed.getSyncState"));
+/**
+* Creates a cursor for iterating over feed items.
+* Currently stubbed — cursor operations are not yet implemented.
+*
+* @example
+* ```ts
+* const cursor = yield* Feed.cursor<Person>(feed);
+* const item = yield* Feed.next(cursor);
+* ```
+*/
+var cursor = (_feed) => Effect.succeed({ _tag: "Cursor" });
+/**
+* Returns the next item from a feed cursor.
+* Currently stubbed — cursor operations are not yet implemented.
+*/
+var next = (_cursor) => Effect.die("Feed.next is not yet implemented");
+/**
+* Returns the next item from a feed cursor as an Option.
+* Currently stubbed — cursor operations are not yet implemented.
+*/
+var nextOption = (_cursor) => Effect.die("Feed.nextOption is not yet implemented");
+/**
+* Sets the local retention policy for a feed.
+* Currently stubbed — feeds do not yet support retention.
+*
+* @example
+* ```ts
+* yield* Feed.setRetention(feed, { count: 1000 });
+* ```
+*/
+var setRetention = (_feed, _options) => Effect.void;
+//#endregion
+export { ContextFeedService, Feed, PARENT_KEY, POSITION_KEY, append, cursor, getFeedUri, getParent, getPosition, getSyncState, history, make, next, nextOption, query, remove, setParent, setRetention, sync, Feed_exports as t };
+
+//# sourceMappingURL=Feed.mjs.map

package/dist/lib/Feed.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Feed.mjs","names":[],"sources":["../../src/Feed.ts"],"sourcesContent":["//\n// Copyright 2025 DXOS.org\n//\n\n// @import-as-namespace\n\nimport * as Context from 'effect/Context';\nimport * as Effect from 'effect/Effect';\nimport * as Function from 'effect/Function';\nimport * as Layer from 'effect/Layer';\nimport type * as Option from 'effect/Option';\nimport * as Schema from 'effect/Schema';\n\nimport { KEY_QUEUE_POSITION } from '@dxos/echo-protocol';\nimport { invariant } from '@dxos/invariant';\nimport { DXN, EID, EntityId } from '@dxos/keys';\n\nimport * as Annotation from './Annotation';\nimport * as Database from './Database';\nimport type * as Entity from './Entity';\nimport type * as Filter from './Filter';\nimport * as internal from './internal';\nimport * as Obj from './Obj';\nimport * as Query from './Query';\nimport type * as QueryResult from './QueryResult';\nimport * as Scope from './Scope';\nimport * as Type from './Type';\n\n/**\n * Runtime schema for a Feed object.\n *\n * @example\n * ```ts\n * const feed = Obj.make(Feed.Feed, { name: 'notifications', kind: 'org.dxos.plugin.notifications.v1' });\n * ```\n */\nexport class Feed extends Type.makeObject<Feed>(DXN.make('org.dxos.type.feed', '0.1.0'))(\n  Schema.Struct({\n    /** User-facing display name. */\n    name: Schema.String.pipe(Schema.optional),\n\n    /** Identifier for the feed's kind (e.g., plugin id). */\n    kind: Schema.String.pipe(internal.FormInputAnnotation.set(false), Schema.optional),\n\n    /**\n     * Feed namespace.\n     * Controls how feed data is stored and replicated.\n     * - `data`: Data feed (default).\n     * - `trace`: Trace feed.\n     */\n    namespace: Schema.optional(Schema.Literal('data', 'trace')),\n\n    /**\n     * Earliest item a pending rewind discards — set when a soft fork is decided but not yet expressed,\n     * because the writer may be a different process than the one that decided it.\n     *\n     * Stored as the first *discarded* item rather than the new parent so that rewinding to the very\n     * first item needs no sentinel: nothing precedes it, so the continuation simply starts a new line.\n     * Readers show what precedes it; the next append parents to that and clears this.\n     *\n     * Transient intent, never a source of truth for history. The fork itself lives in item lineage\n     * (see {@link PARENT_KEY}), which is what {@link history} walks and what replicates in a defined\n     * order relative to the blocks.\n     */\n    rewindFrom: Schema.optional(Obj.ID.pipe(internal.FormInputAnnotation.set(false))),\n  }).pipe(\n    internal.HiddenAnnotation.set(true),\n    Annotation.IconAnnotation.set({ icon: 'ph--rows--regular', hue: 'yellow' }),\n  ),\n) {}\n\n//\n// Types\n//\n\n/**\n * Opaque cursor for iterating over feed items.\n */\n// TODO(dmaretskyi): T needs to be referenced in the type structure for typescript to respect it during inference and type-checking.\nexport interface Cursor<T = Obj.Snapshot> {\n  readonly _tag: 'Cursor';\n}\n\n/**\n * Retention options for a feed.\n *\n * Live feed objects persist every `Obj.update` as a whole-object re-append reusing the object's id\n * (see `EchoFeedCodec.encode`), so superseded blocks accumulate indefinitely — retention/compaction\n * of those superseded blocks (driven by these options, once implemented) is the reclaim mechanism.\n * TODO(wittjosiah): Implement when feed retention is supported (see `setRetention` below and\n * `FeedStore.appendLocal`).\n */\nexport interface RetentionOptions {\n  /** Retain items after this cursor position. */\n  // TODO(wittjosiah): Use FeedCursor from @dxos/feed?\n  cursor?: string;\n}\n\n/**\n * Options for {@link append}.\n */\nexport interface AppendOptions {\n  /**\n   * Explicit lineage parent for the appended items — the soft-fork point.\n   * Applies to the first item only; the rest of the batch chain implicitly in append order.\n   */\n  parent?: Entity.Unknown | Entity.Snapshot | EntityId;\n}\n\n/**\n * Options for {@link history}.\n */\nexport interface HistoryOptions {\n  /**\n   * Item to walk the history from, as git's `HEAD` selects which commits are reachable.\n   * Defaults to the last item, so the most recently appended line of items wins.\n   */\n  head?: Entity.Unknown | Entity.Snapshot | EntityId;\n}\n\n/**\n * The items reachable from a head by following lineage — a feed's equivalent of\n * `git log --first-parent`.\n */\nexport interface History<T> {\n  /** The reachable items, in append order. */\n  items: T[];\n  /**\n   * A parent was referenced but could not be resolved, so the walk stopped at a boundary and\n   * earlier history is missing — the same condition as a git shallow clone.\n   */\n  shallow: boolean;\n}\n\n/**\n * Sync options for a feed.\n */\nexport interface SyncOptions {\n  /** Push local changes to the server. Defaults to true. */\n  shouldPush?: boolean;\n  /** Pull remote changes from the server. Defaults to true. */\n  shouldPull?: boolean;\n}\n\n/**\n * Queue replication backlog for a feed namespace.\n * `0` / `0` means caught up on pull and push.\n */\nexport interface SyncState {\n  /** Blocks still to pull from remote. */\n  blocksToPull: number;\n  /** Unpositioned blocks still to push to remote. */\n  blocksToPush: number;\n  /** Total blocks stored locally for the feed namespace. */\n  totalBlocks: number;\n}\n\n/**\n * Effect service tag for injecting a Feed into effect operations.\n * Used to provide a specific feed to operations that operate on it without threading\n * the feed as an explicit parameter through every call site.\n */\nexport class ContextFeedService extends Context.Tag('@dxos/echo/Feed/ContextFeedService')<\n  ContextFeedService,\n  {\n    readonly feed: Feed;\n  }\n>() {\n  static layer = (feed: Feed) => Layer.succeed(ContextFeedService, { feed });\n}\n\n//\n// Factory\n//\n\n/**\n * Creates a new feed object.\n *\n * @example\n * ```ts\n * const feed = Feed.make({ name: 'notifications', kind: 'org.dxos.plugin.notifications.v1' });\n * ```\n */\n// TODO(wittjosiah): How to control the feed namespace (data/trace)? Why do feeds have namespaces?\nexport const make = (props: Obj.MakeProps<typeof Feed> = {}): Feed => Obj.make(Feed, props);\n\n/**\n * Returns the feed object's EID when the feed is stored in a space.\n *\n * Private-ish and on track to be removed — prefer resolving feed scopes via higher-level APIs\n * (e.g. `Feed.query`) rather than threading the raw queue URI. Used internally by the feed service\n * layer.\n */\n// TODO(dmaretskyi): Remove — private-ish, prefer higher-level feed-scope APIs.\nexport const getFeedUri = (feed: Feed): EID.EID | undefined => EID.tryParse(Obj.getURI(feed));\n\n//\n// Operations\n//\n\n/**\n * Appends items to a feed.\n *\n * Pass `options.parent` to soft-fork the feed: the first appended item continues from that item\n * rather than from the feed's tip, so everything appended between the two becomes unreachable from\n * {@link history}. Nothing is removed from the log.\n *\n * @example\n * ```ts\n * yield* Feed.append(feed, [Obj.make(Notification, { title: 'Hello' })]);\n *\n * // Continue from an earlier item, leaving what followed it unreachable.\n * yield* Feed.append(feed, [Obj.make(Notification, { title: 'Take two' })], { parent: earlier });\n * ```\n */\nexport const append = (\n  feed: Feed,\n  items: Entity.Unknown[],\n  options?: AppendOptions,\n): Effect.Effect<void, never, Database.Service> =>\n  Database.Service.pipe(\n    Effect.flatMap(({ db }) =>\n      Effect.promise(() => {\n        if (options?.parent !== undefined && items.length > 0) {\n          setParent(items[0], options.parent);\n        }\n        return db.appendToFeed(feed, items);\n      }),\n    ),\n  ).pipe(Effect.withSpan('Feed.append'));\n\n/**\n * Removes items from a feed.\n *\n * @example\n * ```ts\n * yield* Feed.remove(feed, [item]);\n * ```\n */\n// TODO(dmaretskyi): Should we allow snapshots here? - what does it mean to remove a snapshot?\nexport const remove = (\n  feed: Feed,\n  items: (Entity.Unknown | Obj.Snapshot)[],\n): Effect.Effect<void, never, Database.Service> =>\n  Database.Service.pipe(\n    Effect.flatMap(({ db }) =>\n      Effect.promise(() =>\n        db.removeFeedItemsByIds(\n          feed,\n          items.map((item) => item.id),\n        ),\n      ),\n    ),\n  ).pipe(Effect.withSpan('Feed.remove'));\n\n//\n// Lineage (soft fork)\n//\n\n/**\n * Foreign-key source for an item's explicit lineage parent within a feed.\n *\n * Lineage is carried in item `@meta` because feed items are arbitrary ECHO objects that the feed\n * does not own and cannot extend; `KEY_QUEUE_POSITION` rides along with feed blocks the same way.\n */\nexport const PARENT_KEY = 'org.dxos.key.feed-parent';\n\n/**\n * Tri-state read of the lineage key, distinguishing an absent key from a present but malformed one.\n * A replicated id that does not parse must not read as \"no parent\" — that would resolve a fork as\n * an implicit continuation and silently expose the items it abandoned.\n */\nconst readParent = (item: Entity.Unknown | Entity.Snapshot): { present: boolean; id?: EntityId } => {\n  const id = internal.getKeys(item, PARENT_KEY).at(0)?.id;\n  if (id === undefined) {\n    return { present: false };\n  }\n  return EntityId.isValid(id) ? { present: true, id } : { present: true };\n};\n\n/**\n * Foreign-key source for the global position a position authority assigned a feed item.\n * Exposed alongside {@link getPosition} so callers can stamp or inspect it without reaching for\n * `@dxos/protocols`.\n */\nexport const POSITION_KEY = KEY_QUEUE_POSITION;\n\n/**\n * The global position a feed item was assigned, or `+Infinity` when it has none — a block written\n * locally and not yet acknowledged, which sorts last because it is the newest.\n *\n * Use this to put items into append order before calling {@link history}: a query returns an unordered\n * set, and `created` is a wall clock that peers do not agree on.\n *\n * @example\n * ```ts\n * const inAppendOrder = Array.sort(messages, Order.mapInput(Order.number, Feed.getPosition));\n * const { items } = Feed.history(inAppendOrder);\n * ```\n */\nexport const getPosition = (item: Entity.Unknown | Entity.Snapshot): number => {\n  const key = internal.getKeys(item, KEY_QUEUE_POSITION).at(0)?.id;\n  const position = key !== undefined ? Number(key) : Number.NaN;\n  return Number.isNaN(position) ? Number.POSITIVE_INFINITY : position;\n};\n\n/**\n * Returns an item's explicit lineage parent, or `undefined` when it continues from the item that\n * precedes it in append order (the default for every feed).\n *\n * Also `undefined` for a malformed stored id; {@link history} tells the two apart and reports\n * a malformed parent as truncation.\n */\nexport const getParent = (item: Entity.Unknown | Entity.Snapshot): EntityId | undefined => readParent(item).id;\n\n/**\n * Sets (or, with `undefined`, clears) an item's explicit lineage parent.\n * Call before appending the item; {@link append}'s `parent` option does this for you.\n */\nexport const setParent = (\n  item: Entity.Unknown,\n  parent: Entity.Unknown | Entity.Snapshot | EntityId | undefined,\n): void => {\n  internal.change(item, (mutable) => {\n    internal.deleteKeys(mutable, PARENT_KEY);\n    if (parent !== undefined) {\n      const id = typeof parent === 'string' ? parent : parent.id;\n      internal.getMetaChecked(mutable).keys.push(internal.foreignKey(PARENT_KEY, id));\n    }\n  });\n};\n\n/**\n * Returns the items reachable from a head by following lineage — a feed's `git log --first-parent`.\n *\n * Walks backwards from the head: an item with an explicit lineage parent jumps to that item, leaving\n * everything appended in between unreachable; an item without one steps to its predecessor. So a\n * feed appended as `M1, M2, M3, M4, M5(M3)` yields `M1, M2, M3, M5`, with `M4` unreachable but still\n * present in the log — the log is the object store, this function is what HEAD reaches.\n *\n * `items` must be in **append order** — the walk is positional, and pre-sorting by a wall-clock\n * field such as `created` would corrupt it. Lineage is resolved over exactly the list passed in, so\n * a parent excluded by the caller's filter reads as absent (`shallow`), same as one that has not\n * replicated yet or whose stored id does not parse.\n *\n * @example\n * ```ts\n * const messages = yield* Feed.query(feed, Filter.type(Message.Message)).run;\n * const { items, shallow } = Feed.history(messages);\n * ```\n */\nexport const history = <T extends Entity.Unknown | Entity.Snapshot>(\n  items: readonly T[],\n  options?: HistoryOptions,\n): History<T> => {\n  const indexById = new Map<EntityId, number>();\n  items.forEach((item, index) => indexById.set(item.id, index));\n\n  const head = options?.head;\n  const headIndex = head === undefined ? items.length - 1 : indexById.get(typeof head === 'string' ? head : head.id);\n  if (headIndex === undefined) {\n    return { items: [], shallow: true };\n  }\n\n  let cursor = headIndex;\n  const reachable: T[] = [];\n  let shallow = false;\n  while (cursor >= 0) {\n    const item = items[cursor];\n    reachable.push(item);\n\n    const parent = readParent(item);\n    if (!parent.present) {\n      cursor -= 1;\n      continue;\n    }\n    if (parent.id === undefined) {\n      // Key present but unparseable — a fork whose target cannot be identified, so stop rather than\n      // fall through to the predecessor and make what this item superseded reachable again.\n      shallow = true;\n      break;\n    }\n\n    // A parent at or after its child is a cycle or a forward reference (possible with arbitrary\n    // multi-writer data); requiring the cursor to strictly decrease also guarantees termination.\n    const parentIndex = indexById.get(parent.id);\n    if (parentIndex === undefined || parentIndex >= cursor) {\n      shallow = true;\n      break;\n    }\n    cursor = parentIndex;\n  }\n\n  return { items: reachable.reverse(), shallow };\n};\n\n/**\n * Creates a reactive query over items in a feed.\n *\n * Returns a {@link QueryResult.QueryResultEffect}: yielding it produces a subscribable\n * `QueryResult`, while its `.run` / `.first` shorthands execute the query once. This mirrors\n * `Database.query` so feed and database queries chain identically.\n *\n * Supports both data-first and data-last (curried) forms; the latter composes with `pipe`.\n *\n * In non-Effect code, query a feed directly through the database with a feed scope:\n * `db.query(Query.select(filter).from(Scope.feed(Feed.getFeedUri(feed))))`.\n *\n * @example\n * ```ts\n * const result = yield* Feed.query(feed, Filter.type(Person));\n * result.subscribe(...);\n *\n * const objects = yield* Feed.query(feed, Filter.type(Person)).run;\n * const object = yield* Feed.query(feed, Filter.type(Person)).first;\n *\n * // Data-last (curried) form composes with `pipe`:\n * const objects = yield* pipe(feed, Feed.query(Filter.type(Person))).run;\n * ```\n */\nexport const query: {\n  <Q extends Query.Any>(feed: Feed, query: Q): QueryResult.QueryResultEffect<Query.Type<Q>, never, Database.Service>;\n  <F extends Filter.Any>(feed: Feed, filter: F): QueryResult.QueryResultEffect<Filter.Type<F>, never, Database.Service>;\n  <Q extends Query.Any>(\n    query: Q,\n  ): (feed: Feed) => QueryResult.QueryResultEffect<Query.Type<Q>, never, Database.Service>;\n  <F extends Filter.Any>(\n    filter: F,\n  ): (feed: Feed) => QueryResult.QueryResultEffect<Filter.Type<F>, never, Database.Service>;\n} = Function.dual(2, (feed: Feed, queryOrFilter: Query.Any | Filter.Any) => {\n  const feedUri = getFeedUri(feed);\n  invariant(feedUri, 'Feed must be stored in the database before accessing its contents');\n  const query = Query.is(queryOrFilter) ? queryOrFilter : Query.select(queryOrFilter);\n  return Database.query(query.from(Scope.feed(feedUri.toString())));\n});\n\n/**\n * Syncs the feed with the server.\n *\n * @example\n * ```ts\n * yield* Feed.sync(feed);\n * yield* Feed.sync(feed, { shouldPush: false });\n * ```\n */\nexport const sync = (feed: Feed, options?: SyncOptions): Effect.Effect<void, never, Database.Service> =>\n  Database.Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.syncFeed(feed, options)))).pipe(\n    Effect.withSpan('Feed.sync'),\n  );\n\n/**\n * Returns the feed's replication backlog for its namespace.\n *\n * @example\n * ```ts\n * const { blocksToPull, blocksToPush } = yield* Feed.getSyncState(feed);\n * ```\n */\nexport const getSyncState = (feed: Feed): Effect.Effect<SyncState, never, Database.Service> =>\n  Database.Service.pipe(Effect.flatMap(({ db }) => Effect.promise(() => db.getFeedSyncState(feed)))).pipe(\n    Effect.withSpan('Feed.getSyncState'),\n  );\n\n/**\n * Creates a cursor for iterating over feed items.\n * Currently stubbed — cursor operations are not yet implemented.\n *\n * @example\n * ```ts\n * const cursor = yield* Feed.cursor<Person>(feed);\n * const item = yield* Feed.next(cursor);\n * ```\n */\n// TODO(wittjosiah): Implement cursor operations. Use Effect streams?\nexport const cursor = <T = Obj.Snapshot>(_feed: Feed): Effect.Effect<Cursor<T>, never, Database.Service> =>\n  Effect.succeed({ _tag: 'Cursor' } as Cursor<T>);\n\n/**\n * Returns the next item from a feed cursor.\n * Currently stubbed — cursor operations are not yet implemented.\n */\nexport const next = <T = Obj.Snapshot>(_cursor: Cursor<T>): Effect.Effect<T, never, Database.Service> =>\n  Effect.die('Feed.next is not yet implemented');\n\n/**\n * Returns the next item from a feed cursor as an Option.\n * Currently stubbed — cursor operations are not yet implemented.\n */\nexport const nextOption = <T = Obj.Snapshot>(\n  _cursor: Cursor<T>,\n): Effect.Effect<Option.Option<T>, never, Database.Service> => Effect.die('Feed.nextOption is not yet implemented');\n\n/**\n * Sets the local retention policy for a feed.\n * Currently stubbed — feeds do not yet support retention.\n *\n * @example\n * ```ts\n * yield* Feed.setRetention(feed, { count: 1000 });\n * ```\n */\n// TODO(dmaretskyi): Implement when feed retention is supported.\nexport const setRetention = (_feed: Feed, _options: RetentionOptions): Effect.Effect<void, never, Database.Service> =>\n  Effect.void;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,IAAa,OAAb,cAA0B,WAAsB,IAAI,KAAK,sBAAsB,OAAO,CAAC,CAAC,CACtF,OAAO,OAAO;;CAEZ,MAAM,OAAO,OAAO,KAAK,OAAO,QAAQ;;CAGxC,MAAM,OAAO,OAAO,KAAA,oBAAkC,IAAI,KAAK,GAAG,OAAO,QAAQ;;;;;;;CAQjF,WAAW,OAAO,SAAS,OAAO,QAAQ,QAAQ,OAAO,CAAC;;;;;;;;;;;;;CAc1D,YAAY,OAAO,SAAA,GAAgB,KAAA,oBAAkC,IAAI,KAAK,CAAC,CAAC;AAClF,CAAC,CAAC,CAAC,KAAA,iBACyB,IAAI,IAAI,GAAA,eACR,IAAI;CAAE,MAAM;CAAqB,KAAK;AAAS,CAAC,CAC5E,CACF,CAAC,CAAC,CAAC;;;;;;AA6FH,IAAa,qBAAb,MAAa,2BAA2B,QAAQ,IAAI,oCAAoC,CAAC,CAKvF,CAAC,CAAC;CACF,OAAO,SAAS,SAAe,MAAM,QAAQ,oBAAoB,EAAE,KAAK,CAAC;AAC3E;;;;;;;;;AAeA,IAAa,QAAQ,QAAoC,CAAC,MAAY,OAAS,MAAM,KAAK;;;;;;;;AAU1F,IAAa,cAAc,SAAoC,IAAI,SAAS,OAAW,IAAI,CAAC;;;;;;;;;;;;;;;;AAqB5F,IAAa,UACX,MACA,OACA,YAAA,QAEiB,KACf,OAAO,SAAS,EAAE,SAChB,OAAO,cAAc;CACnB,IAAI,SAAS,WAAW,KAAA,KAAa,MAAM,SAAS,GAClD,UAAU,MAAM,IAAI,QAAQ,MAAM;CAEpC,OAAO,GAAG,aAAa,MAAM,KAAK;AACpC,CAAC,CACH,CACF,CAAC,CAAC,KAAK,OAAO,SAAS,aAAa,CAAC;;;;;;;;;AAWvC,IAAa,UACX,MACA,UAAA,QAEiB,KACf,OAAO,SAAS,EAAE,SAChB,OAAO,cACL,GAAG,qBACD,MACA,MAAM,KAAK,SAAS,KAAK,EAAE,CAC7B,CACF,CACF,CACF,CAAC,CAAC,KAAK,OAAO,SAAS,aAAa,CAAC;;;;;;;AAYvC,IAAa,aAAa;;;;;;AAO1B,IAAM,cAAc,SAAgF;CAClG,MAAM,KAAK,QAAiB,MAAM,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE;CACrD,IAAI,OAAO,KAAA,GACT,OAAO,EAAE,SAAS,MAAM;CAE1B,OAAO,SAAS,QAAQ,EAAE,IAAI;EAAE,SAAS;EAAM;CAAG,IAAI,EAAE,SAAS,KAAK;AACxE;;;;;;AAOA,IAAa,eAAe;;;;;;;;;;;;;;AAe5B,IAAa,eAAe,SAAmD;CAC7E,MAAM,MAAM,QAAiB,MAAM,kBAAkB,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE;CAC9D,MAAM,WAAW,QAAQ,KAAA,IAAY,OAAO,GAAG,IAAI;CACnD,OAAO,OAAO,MAAM,QAAQ,IAAI,OAAO,oBAAoB;AAC7D;;;;;;;;AASA,IAAa,aAAa,SAAiE,WAAW,IAAI,CAAC,CAAC;;;;;AAM5G,IAAa,aACX,MACA,WACS;CACT,OAAgB,OAAO,YAAY;EACjC,WAAoB,SAAS,UAAU;EACvC,IAAI,WAAW,KAAA,GAAW;GACxB,MAAM,KAAK,OAAO,WAAW,WAAW,SAAS,OAAO;GACxD,eAAwB,OAAO,CAAC,CAAC,KAAK,KAAK,WAAoB,YAAY,EAAE,CAAC;EAChF;CACF,CAAC;AACH;;;;;;;;;;;;;;;;;;;;AAqBA,IAAa,WACX,OACA,YACe;CACf,MAAM,4BAAY,IAAI,IAAsB;CAC5C,MAAM,SAAS,MAAM,UAAU,UAAU,IAAI,KAAK,IAAI,KAAK,CAAC;CAE5D,MAAM,OAAO,SAAS;CACtB,MAAM,YAAY,SAAS,KAAA,IAAY,MAAM,SAAS,IAAI,UAAU,IAAI,OAAO,SAAS,WAAW,OAAO,KAAK,EAAE;CACjH,IAAI,cAAc,KAAA,GAChB,OAAO;EAAE,OAAO,CAAC;EAAG,SAAS;CAAK;CAGpC,IAAI,SAAS;CACb,MAAM,YAAiB,CAAC;CACxB,IAAI,UAAU;CACd,OAAO,UAAU,GAAG;EAClB,MAAM,OAAO,MAAM;EACnB,UAAU,KAAK,IAAI;EAEnB,MAAM,SAAS,WAAW,IAAI;EAC9B,IAAI,CAAC,OAAO,SAAS;GACnB,UAAU;GACV;EACF;EACA,IAAI,OAAO,OAAO,KAAA,GAAW;GAG3B,UAAU;GACV;EACF;EAIA,MAAM,cAAc,UAAU,IAAI,OAAO,EAAE;EAC3C,IAAI,gBAAgB,KAAA,KAAa,eAAe,QAAQ;GACtD,UAAU;GACV;EACF;EACA,SAAS;CACX;CAEA,OAAO;EAAE,OAAO,UAAU,QAAQ;EAAG;CAAQ;AAC/C;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,IAAa,QAST,SAAS,KAAK,IAAI,QAAY,kBAA0C;CAC1E,MAAM,UAAU,WAAW,MAAI;CAC/B,UAAU,SAAS,qEAAkE;EAAA,YAAA;EAAA,GAAA;EAAA,GAAA;EAAA,GAAA,KAAA;EAAA,GAAA,CAAA,WAAA,qEAAA;CAAA,CAAC;CAEtF,OAAO,SADO,GAAS,aAAa,IAAI,gBAAgB,OAAa,aAAa,EAC5D,CAAM,KAAK,KAAW,QAAQ,SAAS,CAAC,CAAC,CAAC;AAClE,CAAC;;;;;;;;;;AAWD,IAAa,QAAQ,MAAY,YAAA,QACd,KAAK,OAAO,SAAS,EAAE,SAAS,OAAO,cAAc,GAAG,SAAS,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,KAClG,OAAO,SAAS,WAAW,CAC7B;;;;;;;;;AAUF,IAAa,gBAAgB,SAAA,QACV,KAAK,OAAO,SAAS,EAAE,SAAS,OAAO,cAAc,GAAG,iBAAiB,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KACjG,OAAO,SAAS,mBAAmB,CACrC;;;;;;;;;;;AAaF,IAAa,UAA4B,UACvC,OAAO,QAAQ,EAAE,MAAM,SAAS,CAAc;;;;;AAMhD,IAAa,QAA0B,YACrC,OAAO,IAAI,kCAAkC;;;;;AAM/C,IAAa,cACX,YAC6D,OAAO,IAAI,wCAAwC;;;;;;;;;;AAYlH,IAAa,gBAAgB,OAAa,aACxC,OAAO"}