@dxos/echo 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/internal/Entity/model.ts

@@ -0,0 +1,119 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Schema from 'effect/Schema';
+
+import { type ForeignKey } from '@dxos/echo-protocol';
+import { invariant } from '@dxos/invariant';
+import { EID, EntityId, type URI } from '@dxos/keys';
+import { assumeType } from '@dxos/util';
+
+import type * as Database from '../../Database';
+import {
+  type ATTR_PARENT,
+  type ATTR_TYPE,
+  ATTR_DELETED,
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+  ATTR_SELF_URI,
+  ATTR_SELF_URI_LEGACY,
+  EntityKind,
+  KindId,
+  ObjectDatabaseId,
+  ObjectDeletedId,
+  ObjectVersionId,
+  type ParentId,
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+  type SchemaId,
+  SelfURIId,
+  TypeId,
+  type Version,
+} from '../common/types';
+import { type ATTR_META, type EntityMeta } from '../common/types/meta';
+import { type MetaId } from '../common/types/model-symbols';
+
+export {
+  ATTR_DELETED,
+  ATTR_SELF_URI,
+  ATTR_SELF_URI_LEGACY,
+  ObjectDatabaseId,
+  ObjectDeletedId,
+  ObjectVersionId,
+  SelfURIId,
+};
+
+/**
+ * Internal runtime representation of an object.
+ * The fields are accessed through getter functions.
+ */
+// NOTE: Each symbol has a jsdoc describing its purpose.
+export interface InternalObjectProps {
+  readonly id: EntityId;
+  readonly [SelfURIId]: EID.EID;
+  readonly [KindId]: EntityKind;
+  readonly [SchemaId]: Schema.Schema.AnyNoContext;
+  readonly [TypeId]: URI.URI;
+  readonly [MetaId]?: EntityMeta;
+  [ParentId]?: InternalObjectProps;
+  readonly [ObjectDatabaseId]?: Database.Database;
+  readonly [ObjectDeletedId]?: boolean;
+  readonly [ObjectVersionId]?: Version;
+  readonly [RelationSourceDXNId]?: EID.EID;
+  readonly [RelationTargetDXNId]?: EID.EID;
+  readonly [RelationSourceId]?: InternalObjectProps;
+  readonly [RelationTargetId]?: InternalObjectProps;
+}
+
+/**
+ * Entity metadata.
+ */
+export interface EntityMetaJSON {
+  keys: ForeignKey[];
+  tags?: string[];
+  key?: string;
+  version?: string;
+}
+
+/**
+ * JSON representation of an object or relation metadata.
+ */
+export interface ObjectJSON {
+  id: EntityId;
+  [ATTR_TYPE]?: URI.URI;
+  [ATTR_SELF_URI]?: EID.EID;
+  [ATTR_PARENT]?: EID.EID; // Encoded reference
+  [ATTR_DELETED]?: boolean;
+  [ATTR_META]?: EntityMetaJSON;
+  [ATTR_RELATION_SOURCE]?: EID.EID;
+  [ATTR_RELATION_TARGET]?: EID.EID;
+
+  /**
+   * Application-specific properties.
+   */
+  [key: string]: unknown;
+}
+
+/**
+ * NOTE: Keep as `function` to avoid type inference issues.
+ */
+export function assertObjectModel(obj: unknown): asserts obj is InternalObjectProps {
+  invariant(typeof obj === 'object' && obj !== null, 'Invalid object model: not an object');
+  assumeType<InternalObjectProps>(obj);
+  invariant(EntityId.isValid(obj.id), 'Invalid object model: invalid id');
+  invariant(obj[TypeId] === undefined || typeof obj[TypeId] === 'string', 'Invalid object model: invalid type');
+  invariant(
+    obj[KindId] === EntityKind.Object || obj[KindId] === EntityKind.Relation || obj[KindId] === EntityKind.Type,
+    'Invalid object model: invalid entity kind',
+  );
+
+  if (obj[KindId] === EntityKind.Relation) {
+    invariant(EID.isEID(obj[RelationSourceDXNId]), 'Invalid object model: invalid relation source');
+    invariant(EID.isEID(obj[RelationTargetDXNId]), 'Invalid object model: invalid relation target');
+    invariant(!EID.isEID(obj[RelationSourceId]), 'Invalid object model: source pointer is a DXN');
+    invariant(!EID.isEID(obj[RelationTargetId]), 'Invalid object model: target pointer is a DXN');
+  }
+}

package/src/internal/Entity/object.ts

@@ -0,0 +1,73 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { invariant } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+
+import { type TypeAnnotation, TypeAnnotationId } from '../Annotation/annotations';
+import { makeTypeJsonSchemaAnnotation } from '../Annotation/util';
+import { EntityKind } from '../common/types';
+import { toJsonSchema } from '../JsonSchema';
+import { type EchoTypeOptions, type EchoTypeSchema, makeEchoTypeSchema } from './entity';
+
+/**
+ * Object schema type with kind marker.
+ */
+export type EchoObjectSchema<
+  Self extends Schema.Schema.Any,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+> = EchoTypeSchema<Self, {}, EntityKind.Object, Fields>;
+
+/**
+ * Schema for Obj entity types.
+ * Pipeable function to add ECHO object annotations to a schema.
+ */
+export const EchoObjectSchema: {
+  (
+    dxn: DXN.DXN,
+    options?: EchoTypeOptions,
+  ): <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ) => EchoObjectSchema<Self, Fields>;
+} = (dxn, options) => {
+  const typename = DXN.getName(dxn);
+  const version = DXN.getVersion(dxn);
+  invariant(version, `Type.makeObject requires a versioned DXN: ${dxn}`);
+
+  return <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ): EchoObjectSchema<Self, Fields> => {
+    invariant(typeof TypeAnnotationId === 'symbol', 'Sanity.');
+    invariant(SchemaAST.isTypeLiteral(self.ast), 'Schema must be a TypeLiteral.');
+
+    // Extract fields from the schema if available (Struct schemas have .fields).
+    const fields = ((self as any).fields ?? {}) as Fields;
+
+    const schemaWithId = Schema.extend(self, Schema.Struct({ id: Schema.String }));
+    const ast = SchemaAST.annotations(schemaWithId.ast, {
+      // TODO(dmaretskyi): `extend` kills the annotations.
+      ...self.ast.annotations,
+      [TypeAnnotationId]: { kind: EntityKind.Object, typename, version } satisfies TypeAnnotation,
+      // TODO(dmaretskyi): TypeIdentifierAnnotationId?
+      [SchemaAST.JSONSchemaAnnotationId]: makeTypeJsonSchemaAnnotation({
+        kind: EntityKind.Object,
+        typename,
+        version,
+      }),
+    });
+
+    return makeEchoTypeSchema<Self, EntityKind.Object, Fields>(
+      fields,
+      ast,
+      typename,
+      version,
+      EntityKind.Object,
+      () => toJsonSchema(Schema.make(ast)),
+      options?.id,
+    );
+  };
+};

package/src/internal/Entity/relation.ts

@@ -0,0 +1,188 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { raise } from '@dxos/debug';
+import { assertArgument, invariant } from '@dxos/invariant';
+import { DXN, type EntityId } from '@dxos/keys';
+
+// Type-only imports (erased at runtime — no import cycle); `internal` may depend
+// on the top-level `Obj` / `Type` API at the type level only.
+import type * as Obj from '../../Obj';
+import type * as Type from '../../Type';
+import {
+  type TypeAnnotation,
+  TypeAnnotationId,
+  getEntityKind,
+  getSchemaTypename,
+  getTypeIdentifierAnnotation,
+} from '../Annotation/annotations';
+import { makeTypeJsonSchemaAnnotation } from '../Annotation/util';
+import {
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+  EntityKind,
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+  type UnknownTypeSchema,
+  getStaticTypeSchema,
+} from '../common/types';
+
+export {
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+};
+
+import { toJsonSchema } from '../JsonSchema';
+import { type EchoTypeSchema, makeEchoTypeSchema } from './entity';
+
+/**
+ * Source and target props on relations.
+ */
+// TODO(burdon): any?
+export type RelationSourceTargetRefs<Source = any, Target = any> = {
+  /**
+   * Source ECHO live object.
+   */
+  [RelationSourceId]: Source;
+
+  /**
+   * Target ECHO live object.
+   */
+  [RelationTargetId]: Target;
+};
+
+export type RelationSource<R> = R extends RelationSourceTargetRefs<infer Source, infer _Target> ? Source : never;
+export type RelationTarget<R> = R extends RelationSourceTargetRefs<infer _Source, infer Target> ? Target : never;
+
+/**
+ * Accepted relation endpoint: an object-kind `Type.Type` entity (slot-backed)
+ * or the branded `Obj.Unknown` schema. Source/target are constrained to these
+ * — relations only connect object-kind entities.
+ */
+export type RelationEndpoint = Type.AnyObj | UnknownTypeSchema<any, EntityKind.Object>;
+
+/**
+ * Resolves a relation endpoint to the instance type it describes — the source /
+ * target instance recorded on the relation's `RelationSourceTargetRefs`.
+ */
+export type RelationEndpointInstance<S> =
+  S extends UnknownTypeSchema<infer A, any> ? A : S extends Type.AnyObj ? Type.InstanceType<S> : unknown;
+
+export type EchoRelationSchemaOptions<TSource extends RelationEndpoint, TTarget extends RelationEndpoint> = {
+  dxn: DXN.DXN;
+  source: TSource;
+  target: TTarget;
+  /**
+   * Override the entity id stamped on the in-memory `Type.Type` value.
+   *
+   * Defaults to `EntityId.deterministic(typename, version)` — stable across processes
+   * and workerd-safe (no `crypto.getRandomValues()` at module-evaluation time).
+   */
+  id?: EntityId;
+};
+
+/**
+ * Relation schema type with kind marker. `SourceInstance` / `TargetInstance`
+ * are the resolved endpoint instance types (see {@link RelationEndpointInstance}).
+ */
+export type EchoRelationSchema<
+  Self extends Schema.Schema.Any,
+  SourceInstance extends Obj.Unknown,
+  TargetInstance extends Obj.Unknown,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+> = EchoTypeSchema<Self, RelationSourceTargetRefs<SourceInstance, TargetInstance>, EntityKind.Relation, Fields>;
+
+/**
+ * Schema for Relation entity types.
+ */
+export const EchoRelationSchema = <Source extends RelationEndpoint, Target extends RelationEndpoint>({
+  dxn,
+  source,
+  target,
+  id: explicitId,
+}: EchoRelationSchemaOptions<Source, Target>) => {
+  // `source` / `target` are `Type.Type` entities (slot-backed) or the branded
+  // `Obj.Unknown` schema (used directly); resolve each to its Effect Schema for
+  // the schema-side machinery (DXN ref + entity-kind checks).
+  const sourceSchema = source != null ? (getStaticTypeSchema(source) ?? source) : source;
+  const targetSchema = target != null ? (getStaticTypeSchema(target) ?? target) : target;
+  assertArgument(Schema.isSchema(sourceSchema), 'source');
+  assertArgument(Schema.isSchema(targetSchema), 'target');
+  const typename = DXN.getName(dxn);
+  const version = DXN.getVersion(dxn);
+  invariant(version, `Type.makeRelation requires a versioned DXN: ${dxn}`);
+  const sourceDXN = getDXNForRelationSchemaRef(sourceSchema);
+  const targetDXN = getDXNForRelationSchemaRef(targetSchema);
+  if (getEntityKind(sourceSchema) !== EntityKind.Object) {
+    raise(new Error('Source schema must be an echo object schema.'));
+  }
+  if (getEntityKind(targetSchema) !== EntityKind.Object) {
+    raise(new Error('Target schema must be an echo object schema.'));
+  }
+
+  return <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ): EchoRelationSchema<Self, RelationEndpointInstance<Source>, RelationEndpointInstance<Target>, Fields> => {
+    invariant(SchemaAST.isTypeLiteral(self.ast), 'Schema must be a TypeLiteral.');
+
+    // Extract fields from the schema if available (Struct schemas have .fields).
+    const fields = ((self as any).fields ?? {}) as Fields;
+
+    const schemaWithId = Schema.extend(self, Schema.Struct({ id: Schema.String }));
+    const ast = SchemaAST.annotations(schemaWithId.ast, {
+      // TODO(dmaretskyi): `extend` kills the annotations.
+      ...self.ast.annotations,
+      [TypeAnnotationId]: {
+        kind: EntityKind.Relation,
+        typename,
+        version,
+        sourceSchema: sourceDXN,
+        targetSchema: targetDXN,
+      } satisfies TypeAnnotation,
+      // TODO(dmaretskyi): TypeIdentifierAnnotationId?
+
+      [SchemaAST.JSONSchemaAnnotationId]: makeTypeJsonSchemaAnnotation({
+        kind: EntityKind.Relation,
+        typename,
+        version,
+        relationSource: sourceDXN,
+        relationTarget: targetDXN,
+      }),
+    });
+
+    return makeEchoTypeSchema<Self, EntityKind.Relation, Fields>(
+      fields,
+      ast,
+      typename,
+      version,
+      EntityKind.Relation,
+      () => toJsonSchema(Schema.make(ast)),
+      explicitId,
+    );
+  };
+};
+
+export const getDXNForRelationSchemaRef = (schema: Schema.Schema.Any): DXN.DXN => {
+  assertArgument(Schema.isSchema(schema), 'schema');
+  const identifier = getTypeIdentifierAnnotation(schema);
+  if (identifier) {
+    return DXN.tryMake(identifier) ?? raise(new Error(`Invalid schema identifier: ${identifier}`));
+  }
+
+  const typename = getSchemaTypename(schema);
+  if (!typename) {
+    throw new Error('Schema must have a typename');
+  }
+
+  return DXN.make(typename);
+};

package/src/internal/Entity/type-kind.ts

@@ -0,0 +1,75 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { invariant } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+
+import { type TypeAnnotation, TypeAnnotationId } from '../Annotation/annotations';
+import { makeTypeJsonSchemaAnnotation } from '../Annotation/util';
+import { EntityKind } from '../common/types';
+import { toJsonSchema } from '../JsonSchema';
+import { type EchoTypeOptions, type EchoTypeSchema, makeEchoTypeSchema } from './entity';
+
+/**
+ * Type-kind schema marker — produced by {@link EchoTypeKindSchema}.
+ *
+ * Distinguishes meta-schemas (entities of `EntityKind.Type`, such as the
+ * built-in `Type.Type` TypeSchema) from object and relation types.
+ */
+export type EchoTypeKindSchema<
+  Self extends Schema.Schema.Any,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+> = EchoTypeSchema<Self, {}, EntityKind.Type, Fields>;
+
+/**
+ * Pipeable that brands a schema as a type-kind ECHO entity. Mirrors
+ * {@link EchoObjectSchema} / {@link EchoRelationSchema}, but stamps the
+ * resulting entity with `[SchemaKindId]: EntityKind.Type` and a matching
+ * `TypeAnnotation.kind = 'type'` so meta-schemas surface uniformly through
+ * `Type.isTypeKind`, `Filter.type`, etc.
+ */
+export const EchoTypeKindSchema: {
+  (
+    dxn: DXN.DXN,
+    options?: EchoTypeOptions,
+  ): <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ) => EchoTypeKindSchema<Self, Fields>;
+} = (dxn, options) => {
+  const typename = DXN.getName(dxn);
+  const version = DXN.getVersion(dxn);
+  invariant(version, `Type-kind schemas require a versioned DXN: ${dxn}`);
+
+  return <Self extends Schema.Schema.Any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>(
+    self: Self & { fields?: Fields },
+  ): EchoTypeKindSchema<Self, Fields> => {
+    invariant(SchemaAST.isTypeLiteral(self.ast), 'Schema must be a TypeLiteral.');
+
+    const fields = ((self as any).fields ?? {}) as Fields;
+
+    const schemaWithId = Schema.extend(self, Schema.Struct({ id: Schema.String }));
+    const ast = SchemaAST.annotations(schemaWithId.ast, {
+      ...self.ast.annotations,
+      [TypeAnnotationId]: { kind: EntityKind.Type, typename, version } satisfies TypeAnnotation,
+      [SchemaAST.JSONSchemaAnnotationId]: makeTypeJsonSchemaAnnotation({
+        kind: EntityKind.Type,
+        typename,
+        version,
+      }),
+    });
+
+    return makeEchoTypeSchema<Self, EntityKind.Type, Fields>(
+      fields,
+      ast,
+      typename,
+      version,
+      EntityKind.Type,
+      () => toJsonSchema(Schema.make(ast)),
+      options?.id,
+    );
+  };
+};

package/src/internal/Entity/type-uri.ts

@@ -0,0 +1,92 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { raise } from '@dxos/debug';
+import { assertArgument } from '@dxos/invariant';
+import { DXN, EID, URI } from '@dxos/keys';
+
+import { getSchemaURI, getTypename } from '../Annotation/annotations';
+import { type AnyEntity, InstancePhantomId, KindId, TypeId, getStaticTypeSchema } from '../common/types';
+import { getUri as getUriFromEntity } from './api';
+
+/**
+ * @param input schema, `Type.Type` entity, or a type URI (an `echo:` EID or a `dxn:` DXN).
+ * @return type identifier URI — see {@link getSchemaURI}. A URI is returned verbatim. For a
+ * `Type.Type` entity, the URI of the schema it declares, symmetric with what
+ * `Obj.make(typeEntity, ...)` stamps on `system.type`: a static declaration resolves to its
+ * typename DXN, a persisted entity to its local `echo:/<objectId>`.
+ */
+export const getTypeURIFromSpecifier = (input: Schema.Schema.All | AnyEntity | URI.URI): URI.URI => {
+  if (Schema.isSchema(input)) {
+    return getSchemaURI(input) ?? raise(new TypeError('Schema has no URI'));
+  }
+  if (typeof input === 'object' && input !== null && KindId in input) {
+    // `Type.Type` entity. Both in-memory and persisted forms expose the schema
+    // they declare via `StaticTypeSchemaSlot`, whose URI is exactly what
+    // `Obj.make` stamps on `system.type` — a static declaration carries
+    // `TypeAnnotation` (→ typename DXN), a persisted entity's rebuilt schema
+    // carries `TypeIdentifierAnnotation` (→ local `echo:/<objectId>`).
+    const schema = getStaticTypeSchema(input);
+    if (schema != null) {
+      // Static types carry TypeAnnotation → DXN; persisted db types carry
+      // TypeIdentifierAnnotation → echo EID. In-memory makeObjectFromJsonSchema
+      // entities have neither (plain JSON Schema), so fall through to the EID path.
+      const uri = getSchemaURI(schema);
+      if (uri != null) {
+        return uri;
+      }
+    }
+    return getUriFromEntity(input as AnyEntity);
+  }
+  // A string specifier is already a branded URI — an `echo:` EID or a `dxn:` DXN.
+  assertArgument(EID.isEID(input) || DXN.isDXN(input), 'input', 'expected a type URI (EID or DXN)');
+  return input;
+};
+
+/**
+ * Checks if the object is an instance of the schema.
+ * Only typename is compared, the schema version is ignored.
+ *
+ * The following cases are considered to mean that the object is an instance of the schema:
+ *  - Object was created with this exact schema.
+ *  - Object was created with a different version of this schema.
+ *  - Object was created with a different schema (maybe dynamic) that has the same typename.
+ */
+// TODO(burdon): Can we use `Schema.is`?
+export const isInstanceOf = <S>(
+  schemaOrType: S extends Schema.Schema.AnyNoContext ? S : Schema.Schema.AnyNoContext | AnyEntity,
+  object: any,
+): object is S extends Schema.Schema.AnyNoContext
+  ? Schema.Schema.Type<S>
+  : S extends { readonly [InstancePhantomId]?: infer A }
+    ? A
+    : unknown => {
+  if (object == null) {
+    return false;
+  }
+
+  const schemaURI = getTypeURIFromSpecifier(schemaOrType);
+
+  // `object` is arbitrary input — read TypeId directly (it may be missing on
+  // non-entities) rather than via `getTypeURI` which asserts the URI is set.
+  const type = (object as any)[TypeId];
+  if (URI.isURI(type) && type === schemaURI) {
+    return true;
+  }
+
+  const typename = getTypename(object);
+  if (!typename) {
+    return false;
+  }
+
+  if (!DXN.isDXN(schemaURI)) {
+    // EID-based schema URI — no typename match possible.
+    return false;
+  }
+
+  const parsed = DXN.tryMake(schemaURI);
+  return parsed != null && DXN.getName(parsed) === typename;
+};

package/src/internal/Entity/util.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { assertArgument, invariant } from '@dxos/invariant';
+import { EID, EntityId } from '@dxos/keys';
+import { assumeType } from '@dxos/util';
+
+import { type InternalObjectProps, SelfURIId } from './model';
+
+/**
+ * Returns the EID of an object.
+ *
+ * @internal
+ */
+export const getObjectEchoUri = (object: any): EID.EID | undefined => {
+  invariant(!Schema.isSchema(object), 'schema not allowed in this function');
+  assertArgument(typeof object === 'object' && object != null, 'object', 'expected object');
+  assumeType<InternalObjectProps>(object);
+
+  if (object[SelfURIId]) {
+    invariant(EID.isEID(object[SelfURIId]), 'Invalid object model: invalid self dxn');
+    return EID.parse(object[SelfURIId]);
+  }
+
+  if (!EntityId.isValid(object.id)) {
+    throw new TypeError('Object id is not valid.');
+  }
+
+  return EID.make({ entityId: object.id });
+};

package/src/internal/Entity/version.ts

@@ -0,0 +1,96 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { assertArgument } from '@dxos/invariant';
+
+import { type AnyEntity, VersionTypeId } from '../common/types';
+import { ObjectVersionId } from './model';
+
+/**
+ * Represent entity version.
+ * May be backed by Automerge.
+ * Entities with no history are not versioned.
+ * Named EntityVersion to avoid conflict with types/version.ts.
+ */
+export interface EntityVersion {
+  [VersionTypeId]: {};
+
+  /**
+   * Whether the entity is versioned.
+   */
+  versioned: boolean;
+
+  /**
+   * Automerge heads.
+   */
+  automergeHeads?: string[];
+}
+
+const unversioned: EntityVersion = {
+  [VersionTypeId]: {},
+  versioned: false,
+};
+
+/**
+ * Checks that `obj` is a version object.
+ */
+export const isVersion = (entity: unknown): entity is EntityVersion => {
+  return entity != null && typeof entity === 'object' && VersionTypeId in entity;
+};
+
+/**
+ * Returns the version of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const version = (entity: AnyEntity): EntityVersion => {
+  const ver = (entity as any)[ObjectVersionId];
+  if (ver === undefined) {
+    return unversioned;
+  }
+  return ver;
+};
+
+/**
+ * Checks that `version` is a valid version object.
+ */
+export const versionValid = (ver: EntityVersion): boolean => {
+  assertArgument(isVersion(ver), 'version', 'Invalid version object');
+  return !!ver.versioned;
+};
+
+export type VersionCompareResult = 'unversioned' | 'equal' | 'different';
+
+/**
+ * Compares two versions.
+ * @param version1
+ * @param version2
+ * @returns 'unversioned' if either entity is unversioned, 'equal' if the versions are equal, 'different' if the versions are different.
+ */
+export const compareVersions = (version1: EntityVersion, version2: EntityVersion): VersionCompareResult => {
+  assertArgument(isVersion(version1), 'version1', 'Invalid version object');
+  assertArgument(isVersion(version2), 'version2', 'Invalid version object');
+
+  if (!versionValid(version1) || !versionValid(version2)) {
+    return 'unversioned';
+  }
+
+  if (version1.automergeHeads?.length !== version2.automergeHeads?.length) {
+    return 'different';
+  }
+  if (version1.automergeHeads?.some((head) => !version2.automergeHeads?.includes(head))) {
+    return 'different';
+  }
+
+  return 'equal';
+};
+
+export const encodeVersion = (ver: EntityVersion): string => {
+  return JSON.stringify(ver);
+};
+
+export const decodeVersion = (ver: string): EntityVersion => {
+  const parsed = JSON.parse(ver);
+  parsed[VersionTypeId] = {};
+  return parsed;
+};