@dxos/echo-protocol 0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264 → 0.13.0

package/dist/lib/index.mjs

@@ -4,7 +4,7 @@ import { ComplexMap, compositeKey, visitValues } from "@dxos/util";
 import { subtleCrypto } from "@dxos/crypto/subtle";
 import { EdgeService, FeedProtocol } from "@dxos/protocols";
 import * as Schema from "effect/Schema";
-import { SchemaAST } from "@dxos/effect";
+import * as SchemaAST from "@dxos/effect/SchemaAST";
 import * as Match from "effect/Match";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
@@ -151,6 +151,15 @@ var EntityStructure = Object.freeze({
 	isDeleted: (object) => {
 		return object.system?.deleted ?? false;
 	},
+	getConvergenceKey: (object) => {
+		return object.meta?.convergenceKey;
+	},
+	getMergedInto: (object) => {
+		return object.system?.mergedInto;
+	},
+	getMergedFrom: (object) => {
+		return object.system?.mergedFrom ?? [];
+	},
 	getRelationSource: (object) => {
 		return object.system?.source;
 	},
@@ -224,25 +233,26 @@ var DATA_NAMESPACE = "data";
 //#endregion
 //#region src/edge-peer.ts
 /**
-* Returns true if the given peerId belongs to an EDGE replicator (Automerge or Subduction).
+* Returns true if the given peerId belongs to the EDGE Subduction replicator.
 *
 * When `spaceId` is provided, the match is scoped to that space (peerId must start with
 * `<service>:<spaceId>`). When omitted, only the leading service segment is checked
 * (peerId must start with `<service>:`), which is useful when the caller doesn't have a
-* spaceId on hand or wants to match any edge replicator regardless of space.
+* spaceId on hand or wants to match the edge replicator regardless of space.
 */
 var isEdgePeerId = (peerId, spaceId) => {
-	const automergePrefix = spaceId !== void 0 ? compositeKey(EdgeService.AUTOMERGE_REPLICATOR, spaceId) : `${EdgeService.AUTOMERGE_REPLICATOR}:`;
-	const subductionPrefix = spaceId !== void 0 ? compositeKey(EdgeService.SUBDUCTION_REPLICATOR, spaceId) : `${EdgeService.SUBDUCTION_REPLICATOR}:`;
-	return peerId.startsWith(automergePrefix) || peerId.startsWith(subductionPrefix);
+	const prefix = spaceId !== void 0 ? compositeKey(EdgeService.SUBDUCTION_REPLICATOR, spaceId) : `${EdgeService.SUBDUCTION_REPLICATOR}:`;
+	return peerId.startsWith(prefix);
 };
 //#endregion
 //#region src/echo-feed-codec.ts
 /** Property name for meta when object is serialized to JSON. Matches @dxos/echo/internal ATTR_META. */
 var ATTR_META = "@meta";
+/** Meta keys a store stamps on decode and strips on encode: they describe the block, not the object. */
+var FEED_KEY_SOURCES = [FeedProtocol.KEY_QUEUE_POSITION, FeedProtocol.KEY_FEED_BLOCK];
 /**
 * Codec for ECHO objects in feed block payload: JSON object ↔ UTF-8 bytes.
-* Encodes with queue position stripped; decodes with optional position injection.
+* Encodes with the block's own keys stripped; decodes with them stamped into `@meta`.
 */
 var EchoFeedCodec = class EchoFeedCodec {
 	static #encoder = new TextEncoder();
@@ -253,8 +263,7 @@ var EchoFeedCodec = class EchoFeedCodec {
 	* last-write-wins merge at the index (see EntityMetaIndex.update).
 	*/
 	static encode(value) {
-		const prepared = EchoFeedCodec.stripQueuePosition(value);
-		return EchoFeedCodec.#encoder.encode(JSON.stringify(prepared));
+		return EchoFeedCodec.#encoder.encode(JSON.stringify(EchoFeedCodec.stripFeedKeys(value)));
 	}
 	/**
 	* Decodes feed block bytes to a JSON value.
@@ -262,33 +271,77 @@ var EchoFeedCodec = class EchoFeedCodec {
 	*/
 	static decode(data, position) {
 		const decoded = JSON.parse(EchoFeedCodec.#decoder.decode(data));
-		if (position !== void 0 && typeof decoded === "object" && decoded !== null) EchoFeedCodec.#setQueuePosition(decoded, position);
+		if (position !== void 0 && typeof decoded === "object" && decoded !== null) EchoFeedCodec.#setKey(decoded, FeedProtocol.KEY_QUEUE_POSITION, position.toString());
 		return decoded;
 	}
 	/**
-	* Strips the queue-position foreign key from an object's metadata, producing a canonical form
-	* comparable across a local snapshot and an inbound feed block (positions differ per-append).
+	* Decodes a stored block, stamping its identity (and position, once it has one) into `@meta` so a
+	* reader can tell blocks apart and order them without comparing their content.
 	*/
-	static stripQueuePosition(value) {
-		if (typeof value !== "object" || value === null) return value;
-		const obj = structuredClone(value);
-		const meta = obj[ATTR_META];
-		if (meta?.keys?.some((key) => key.source === FeedProtocol.KEY_QUEUE_POSITION)) meta.keys = meta.keys.filter((key) => key.source !== FeedProtocol.KEY_QUEUE_POSITION);
-		return obj;
+	static decodeBlock(block) {
+		const decoded = EchoFeedCodec.decode(block.data, block.position ?? void 0);
+		if (typeof decoded === "object" && decoded !== null) EchoFeedCodec.#setKey(decoded, FeedProtocol.KEY_FEED_BLOCK, EchoFeedCodec.blockId(block.actorId, block.sequence));
+		return decoded;
 	}
-	static #setQueuePosition(obj, position) {
-		obj[ATTR_META] ??= { keys: [] };
-		obj[ATTR_META].keys ??= [];
-		const keys = obj[ATTR_META].keys;
-		for (let i = 0; i < keys.length; i++) if (keys[i].source === FeedProtocol.KEY_QUEUE_POSITION) {
-			keys.splice(i, 1);
-			i--;
-		}
-		keys.push({
-			source: FeedProtocol.KEY_QUEUE_POSITION,
-			id: position.toString()
-		});
+	/**
+	* The id stamped for a block. The sequence comes first: it is always digits, so the first separator
+	* splits the id even when the actor id contains one.
+	*/
+	static blockId(actorId, sequence) {
+		return `${sequence}@${actorId}`;
 	}
+	/** Reads the block reference {@link decodeBlock} (or {@link decode} with a position) stamped. */
+	static blockOf(value) {
+		return EchoFeedCodec.blockOfKeys(metaKeysOf(value));
+	}
+	/** Reads the block reference from an object's foreign keys. */
+	static blockOfKeys(keys) {
+		const ref = {};
+		for (const key of keys) if (key.source === FeedProtocol.KEY_QUEUE_POSITION) {
+			const position = Number(key.id);
+			if (Number.isFinite(position)) ref.position = position;
+		} else if (key.source === FeedProtocol.KEY_FEED_BLOCK) Object.assign(ref, parseBlockId(key.id));
+		return ref;
+	}
+	/**
+	* Returns `value` without the keys a store stamps on decode, so re-appending a decoded object does
+	* not carry its old block's identity into the new block. Copies only the containers it changes.
+	*/
+	static stripFeedKeys(value) {
+		const meta = value[ATTR_META];
+		const keys = metaKeysOf(value);
+		if (typeof meta !== "object" || meta === null || !keys.some((key) => FEED_KEY_SOURCES.includes(key.source))) return value;
+		return {
+			...value,
+			[ATTR_META]: {
+				...meta,
+				keys: keys.filter((key) => !FEED_KEY_SOURCES.includes(key.source))
+			}
+		};
+	}
+	static #setKey(obj, source, id) {
+		const meta = obj[ATTR_META];
+		obj[ATTR_META] = {
+			...typeof meta === "object" && meta !== null ? meta : {},
+			keys: [...metaKeysOf(obj).filter((key) => key.source !== source), {
+				source,
+				id
+			}]
+		};
+	}
+};
+var metaKeysOf = (value) => {
+	const meta = value[ATTR_META];
+	const keys = typeof meta === "object" && meta !== null && "keys" in meta ? meta.keys : void 0;
+	return Array.isArray(keys) ? keys : [];
+};
+var parseBlockId = (id) => {
+	const separator = id.indexOf("@");
+	const sequence = Number(id.slice(0, separator));
+	return separator > 0 && Number.isInteger(sequence) ? {
+		sequence,
+		actorId: id.slice(separator + 1)
+	} : {};
 };
 /**
 * Foreign-key source for the global position a feed block was assigned.
@@ -315,6 +368,8 @@ var ast_exports = /* @__PURE__ */ __exportAll({
 	FeedScope: () => FeedScope,
 	Filter: () => Filter,
 	FilterAnd: () => FilterAnd,
+	FilterAnnotation: () => FilterAnnotation,
+	FilterChanges: () => FilterChanges,
 	FilterChildOf: () => FilterChildOf,
 	FilterCompare: () => FilterCompare,
 	FilterContains: () => FilterContains,
@@ -322,6 +377,7 @@ var ast_exports = /* @__PURE__ */ __exportAll({
 	FilterHasParent: () => FilterHasParent,
 	FilterIn: () => FilterIn,
 	FilterInQuery: () => FilterInQuery,
+	FilterMnemonic: () => FilterMnemonic,
 	FilterNot: () => FilterNot,
 	FilterObject: () => FilterObject,
 	FilterOr: () => FilterOr,
@@ -354,6 +410,7 @@ var ast_exports = /* @__PURE__ */ __exportAll({
 	Scope: () => Scope,
 	SpaceScope: () => SpaceScope,
 	fold: () => fold,
+	isGroupKeyAggregate: () => isGroupKeyAggregate,
 	map: () => map,
 	visit: () => visit
 });
@@ -414,6 +471,15 @@ var FilterTag = Schema.Struct({
 	type: Schema.Literal("tag"),
 	tag: Schema.String
 });
+var FilterAnnotation = Schema.Struct({
+	type: Schema.Literal("annotation"),
+	key: Schema.String,
+	value: Schema.optional(Schema.Union([
+		Schema.String,
+		Schema.Number,
+		Schema.Boolean
+	]))
+});
 var FilterRange = Schema.Struct({
 	type: Schema.Literal("range"),
 	from: Schema.Any,
@@ -466,6 +532,15 @@ var FilterHasParent = Schema.Struct({
 	/** True matches objects with a parent; false matches unparented (root) objects. */
 	value: Schema.Boolean
 });
+var FilterMnemonic = Schema.Struct({
+	type: Schema.Literal("mnemonic"),
+	/** Normalized (uppercase) mnemonic. */
+	mnemonic: Schema.String
+});
+var FilterChanges = Schema.Struct({
+	type: Schema.Literal("changes"),
+	targets: Schema.optional(Schema.Array(EID.Schema))
+});
 /**
 * Union of filters.
 */
@@ -476,12 +551,15 @@ var Filter = Schema.Union([
 	FilterInQuery,
 	FilterContains,
 	FilterTag,
+	FilterAnnotation,
 	FilterRange,
 	FilterTimestamp,
 	FilterFeedCursor,
 	FilterTextSearch,
 	FilterChildOf,
 	FilterHasParent,
+	FilterMnemonic,
+	FilterChanges,
 	FilterNot,
 	FilterAnd,
 	FilterOr
@@ -607,6 +685,11 @@ var QuerySkipClause = Schema.Struct({
 *   ordering, independent of any `orderBy` clause elsewhere in the query (which orders the whole
 *   input stream / the resulting groups, not this aggregate's member selection).
 * - `count` yields the member count. Opt-in — a row carries no count otherwise.
+* - `type` partitions members by their type URI; the field carries the URI string.
+* - `timestamp` partitions members by the UTC hour or day a system timestamp falls in; the field
+*   carries the start of that interval in unix ms.
+* - `time` is `timestamp` over a unix-ms member `property` instead of a system timestamp.
+* - `sum` adds a numeric member `property`; non-numeric values count as 0.
 */
 var GroupAggregateGroup_ = Schema.Struct({
 	name: Schema.String,
@@ -639,13 +722,41 @@ var GroupAggregateCount_ = Schema.Struct({
 	name: Schema.String,
 	kind: Schema.Literal("count")
 });
-var GroupAggregate = Schema.Union([
+var GroupAggregateType_ = Schema.Struct({
+	name: Schema.String,
+	kind: Schema.Literal("type")
+});
+var GroupAggregateTimestamp_ = Schema.Struct({
+	name: Schema.String,
+	kind: Schema.Literal("timestamp"),
+	field: Schema.Literals(["createdAt", "updatedAt"]),
+	unit: Schema.Literals(["hour", "day"])
+});
+var GroupAggregateTime_ = Schema.Struct({
+	name: Schema.String,
+	kind: Schema.Literal("time"),
+	property: Schema.String,
+	unit: Schema.Literals(["hour", "day"])
+});
+var GroupAggregateSum_ = Schema.Struct({
+	name: Schema.String,
+	kind: Schema.Literal("sum"),
+	property: Schema.String
+});
+var GroupAggregate_ = Schema.Union([
 	GroupAggregateGroup_,
 	GroupAggregateMax_,
 	GroupAggregateMin_,
 	GroupAggregateItems_,
-	GroupAggregateCount_
+	GroupAggregateCount_,
+	GroupAggregateType_,
+	GroupAggregateTimestamp_,
+	GroupAggregateTime_,
+	GroupAggregateSum_
 ]);
+/** Aggregate kinds that contribute a component to the group key. */
+var isGroupKeyAggregate = (aggregate) => aggregate.kind === "group" || aggregate.kind === "type" || aggregate.kind === "timestamp" || aggregate.kind === "time";
+var GroupAggregate = GroupAggregate_;
 var QueryAggregateClause = Schema.Struct({
 	type: Schema.Literal("aggregate"),
 	query: Schema.suspend(() => Query),