@dxos/versioning 0.10.0

package/src/internal/model.ts

@@ -0,0 +1,189 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Text as EchoText, Obj, Ref } from '@dxos/echo';
+import { checkoutVersion } from '@dxos/echo-client';
+import { invariant } from '@dxos/invariant';
+import { Text } from '@dxos/schema';
+
+import { merge3 } from '../diff';
+import * as Versioning from './types';
+
+/** Any ECHO object that carries a versioning history (e.g. a markdown document). */
+export type VersionedObject = Obj.Unknown & { history?: Versioning.History | undefined };
+
+/** Initializes the history struct on first use so existing documents need no migration. */
+export const ensureHistory = (doc: VersionedObject): Versioning.History => {
+  if (!doc.history) {
+    Obj.update(doc, (doc) => {
+      doc.history = { branches: [], versions: [] };
+    });
+  }
+  const history = doc.history;
+  invariant(history, 'history not initialized');
+  return history;
+};
+
+const getHeads = (text: Text.Text): string[] => {
+  const version = Obj.version(text);
+  invariant(version.versioned && version.automergeHeads, 'text is not versioned (not persisted?)');
+  return [...version.automergeHeads];
+};
+
+/** @returns The Text content at the given automerge heads (read-only time travel). */
+export const contentAt = (text: Text.Text, heads: readonly string[]): string => {
+  // `checkoutVersion` returns `unknown` (raw historical data) — narrow via runtime checks.
+  const snapshot = checkoutVersion(text, [...heads]);
+  if (snapshot && typeof snapshot === 'object' && 'content' in snapshot) {
+    const { content } = snapshot;
+    return typeof content === 'string' ? content : '';
+  }
+  return '';
+};
+
+export type CreateCheckpointProps = { target: Text.Text; name: string; message?: string; creator?: string };
+
+/**
+ * Records a named checkpoint of the target Text's current automerge heads and appends it to
+ * the object's history. Zero-copy: only the heads are stored.
+ */
+export const createCheckpoint = (doc: VersionedObject, props: CreateCheckpointProps): Versioning.Version => {
+  const text = props.target;
+  const version = Versioning.makeVersion({
+    name: props.name,
+    target: Ref.make(text),
+    heads: getHeads(text),
+    ...(props.message !== undefined && { message: props.message }),
+    ...(props.creator !== undefined && { creator: props.creator }),
+  });
+  const history = ensureHistory(doc);
+  Obj.update(doc, () => {
+    history.versions.push(version);
+  });
+
+  // Return the stored record (the pushed plain object is detached from the database).
+  const stored = history.versions.find(({ id }) => id === version.id);
+  invariant(stored, 'checkpoint not stored');
+  return stored;
+};
+
+/** Display label for a checkpoint: its name, or the formatted creation time when unnamed. */
+export const versionLabel = (version: Versioning.Version): string =>
+  version.name || new Date(version.createdAt).toLocaleString();
+
+/** Display label for a branch: its name, or the formatted creation time when unnamed. */
+export const branchLabel = (branch: Versioning.Branch): string =>
+  branch.name || new Date(branch.createdAt).toLocaleString();
+
+/** Find the branch record owning a given Text (undefined for the root). */
+export const findBranch = (doc: VersionedObject, text: Text.Text): Versioning.Branch | undefined =>
+  doc.history?.branches.find((branch) => branch.content.target?.id === text.id);
+
+export type CreateBranchProps = {
+  name: string;
+  parent: Text.Text;
+  heads?: readonly string[];
+  creator?: string;
+};
+
+/**
+ * Forks a draft branch: a new Text seeded with the parent's content at the anchor heads
+ * (defaults to the parent's current heads), recorded in the object's history. The anchor is
+ * auto-checkpointed so the fork point stays addressable in the timeline.
+ */
+export const createBranch = (doc: VersionedObject, props: CreateBranchProps): Versioning.Branch => {
+  const parent = props.parent;
+  const anchor = props.heads ? [...props.heads] : getHeads(parent);
+  const baseContent = contentAt(parent, anchor);
+
+  const branchText = Text.make({ content: baseContent });
+  const db = Obj.getDatabase(doc);
+  invariant(db, 'document not in a database');
+  db.add(branchText);
+  Obj.setParent(branchText, doc);
+
+  const branch = Versioning.makeBranch({
+    name: props.name,
+    content: Ref.make(branchText),
+    parent: Ref.make(parent),
+    anchor,
+    ...(props.creator !== undefined && { creator: props.creator }),
+  });
+
+  const history = ensureHistory(doc);
+  Obj.update(doc, () => {
+    history.branches.push(branch);
+  });
+  // The anchor must stay addressable by name in the timeline.
+  if (!history.versions.some((version) => sameHeads(version.heads, anchor))) {
+    const version = Versioning.makeVersion({
+      name: `fork: ${branchLabel(branch)}`,
+      target: Ref.make(parent),
+      heads: anchor,
+    });
+    Obj.update(doc, () => {
+      history.versions.push(version);
+    });
+  }
+
+  // Return the stored record (the pushed plain object is detached from the database).
+  const stored = history.branches.find(({ id }) => id === branch.id);
+  invariant(stored, 'branch not stored');
+  return stored;
+};
+
+/** Applies the checkpoint's content to the tip as a new forward edit — history is never rewritten. */
+export const restore = (doc: VersionedObject, version: Versioning.Version): void => {
+  const text = version.target.target;
+  invariant(text, 'checkpoint target not loaded');
+  const historical = contentAt(text, version.heads);
+  Obj.update(text, () => {
+    EchoText.update(text, 'content', historical);
+  });
+};
+
+export type MergeResult = { conflicts: number };
+
+/**
+ * 3-way merge: base = parent@anchor, ours = parent tip, theirs = branch tip.
+ * Conflicting hunks are left in the document with git-style markers for manual cleanup.
+ */
+export const mergeBranch = (doc: VersionedObject, branch: Versioning.Branch): MergeResult => {
+  // Callers may hold a detached copy of the record — mutate the stored one.
+  const stored = resolveBranch(doc, branch);
+  invariant(stored.status === 'active', 'branch is not active');
+  const parent = stored.parent.target;
+  const branchText = stored.content.target;
+  invariant(parent && branchText, 'branch refs not loaded');
+
+  const base = contentAt(parent, stored.anchor);
+  const { text, conflicts } = merge3({ base, ours: parent.content, theirs: branchText.content });
+  Obj.update(parent, () => {
+    EchoText.update(parent, 'content', text);
+  });
+  Obj.update(doc, () => {
+    stored.status = 'merged';
+    stored.mergedAt = new Date().toISOString();
+  });
+
+  createCheckpoint(doc, { name: `merge: ${branchLabel(stored)}`, target: parent });
+  return { conflicts };
+};
+
+/** Archives the branch; its Text is retained for recovery. */
+export const discardBranch = (doc: VersionedObject, branch: Versioning.Branch): void => {
+  const stored = resolveBranch(doc, branch);
+  Obj.update(doc, () => {
+    stored.status = 'archived';
+  });
+};
+
+const resolveBranch = (doc: VersionedObject, branch: Versioning.Branch): Versioning.Branch => {
+  const stored = doc.history?.branches.find(({ id }) => id === branch.id);
+  invariant(stored, `branch not found: ${branch.id}`);
+  return stored;
+};
+
+const sameHeads = (a: readonly string[], b: readonly string[]) =>
+  a.length === b.length && a.every((head) => b.includes(head));

package/src/internal/types.ts

@@ -0,0 +1,76 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Key, Ref } from '@dxos/echo';
+import { Text } from '@dxos/schema';
+
+/**
+ * Named checkpoint: a pointer to the automerge heads of a Text's backing document.
+ * Heads are content-addressed change hashes, stable across peers, so a checkpoint is zero-copy.
+ * Generic over any object holding a `history` field (see model.ts).
+ */
+export const Version = Schema.mutable(
+  Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    target: Ref.Ref(Text.Text),
+    heads: Schema.mutable(Schema.Array(Schema.String)),
+    createdAt: Schema.String,
+    creator: Schema.optional(Schema.String),
+    message: Schema.optional(Schema.String),
+  }),
+);
+export interface Version extends Schema.Schema.Type<typeof Version> {}
+
+export const BranchStatus = Schema.Literal('active', 'merged', 'archived');
+export type BranchStatus = Schema.Schema.Type<typeof BranchStatus>;
+
+/**
+ * A draft Text forked from a parent Text at a specific revision (anchor heads).
+ * The branch tree is formed by `parent` references; the root is Document.content.
+ */
+export const Branch = Schema.mutable(
+  Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    content: Ref.Ref(Text.Text),
+    parent: Ref.Ref(Text.Text),
+    anchor: Schema.mutable(Schema.Array(Schema.String)),
+    status: BranchStatus,
+    createdAt: Schema.String,
+    creator: Schema.optional(Schema.String),
+    mergedAt: Schema.optional(Schema.String),
+  }),
+);
+export interface Branch extends Schema.Schema.Type<typeof Branch> {}
+
+export const History = Schema.mutable(
+  Schema.Struct({
+    branches: Schema.mutable(Schema.Array(Branch)),
+    versions: Schema.mutable(Schema.Array(Version)),
+  }),
+);
+export interface History extends Schema.Schema.Type<typeof History> {}
+
+export type MakeVersionProps = Pick<Version, 'target' | 'heads' | 'name'> &
+  Partial<Pick<Version, 'creator' | 'message'>>;
+
+/** Constructs a Version checkpoint record with a generated id and creation timestamp. */
+export const makeVersion = (props: MakeVersionProps): Version => ({
+  id: Key.EntityId.random(),
+  createdAt: new Date().toISOString(),
+  ...props,
+});
+
+export type MakeBranchProps = Pick<Branch, 'content' | 'parent' | 'anchor' | 'name'> & Partial<Pick<Branch, 'creator'>>;
+
+/** Constructs an active Branch record with a generated id and creation timestamp. */
+export const makeBranch = (props: MakeBranchProps): Branch => ({
+  id: Key.EntityId.random(),
+  status: 'active',
+  createdAt: new Date().toISOString(),
+  ...props,
+});

package/src/model.test.ts

@@ -0,0 +1,182 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { afterEach, beforeEach, describe, test } from 'vitest';
+
+import { DXN, Obj, Ref, Type } from '@dxos/echo';
+import { EchoTestBuilder } from '@dxos/echo-client/testing';
+import { Text } from '@dxos/schema';
+
+import * as Branch from './Branch';
+import * as History from './History';
+import * as Version from './Version';
+
+/** Minimal versioned host: a document-like object holding a root Text and a history. */
+const TestDoc = Type.makeObject(DXN.make('org.dxos.test.versioning.Doc', '0.1.0'))(
+  Schema.Struct({
+    name: Schema.optional(Schema.String),
+    content: Ref.Ref(Text.Text),
+    history: History.History.pipe(Schema.optional),
+  }),
+);
+
+describe('versioning model', () => {
+  let builder: EchoTestBuilder;
+
+  beforeEach(async () => {
+    builder = await new EchoTestBuilder().open();
+  });
+
+  afterEach(async () => {
+    await builder.close();
+  });
+
+  const setup = async (content: string) => {
+    const { db } = await builder.createDatabase({ types: [TestDoc, Text.Text] });
+    const doc = db.add(Obj.make(TestDoc, { content: Ref.make(Text.make({ content })) }));
+    await db.flush();
+    const root = await doc.content.load();
+    return { db, doc, root };
+  };
+
+  test('ensureHistory initializes once', async ({ expect }) => {
+    const { doc } = await setup('one');
+    const history = History.ensure(doc);
+    expect(history.versions).toEqual([]);
+    expect(History.ensure(doc)).toBe(doc.history);
+  });
+
+  test('checkpoint records current heads; contentAt returns historical content', async ({ expect }) => {
+    const { doc, root } = await setup('one');
+
+    const checkpoint = Version.create(doc, { name: 'v1', target: root });
+    expect(checkpoint.heads.length).toBeGreaterThan(0);
+    expect(doc.history?.versions).toHaveLength(1);
+
+    Obj.update(root, (root) => {
+      root.content = 'one two';
+    });
+
+    expect(Version.contentAt(root, checkpoint.heads)).toBe('one');
+    expect(root.content).toBe('one two');
+  });
+
+  test('branch forks content at anchor; edits stay isolated', async ({ expect }) => {
+    const { doc, root } = await setup('one two three');
+
+    const branch = Branch.create(doc, { name: 'draft', parent: root });
+    const branchText = await branch.content.load();
+    expect(branchText.content).toBe('one two three');
+    // Fork point auto-checkpointed on the parent.
+    expect(doc.history?.versions.some((version) => version.name === 'fork: draft')).toBe(true);
+
+    Obj.update(branchText, (branchText) => {
+      branchText.content = 'one two three four';
+    });
+    expect(root.content).toBe('one two three');
+  });
+
+  test('branch at a historical checkpoint seeds historical content', async ({ expect }) => {
+    const { doc, root } = await setup('first');
+    const checkpoint = Version.create(doc, { name: 'v1', target: root });
+
+    Obj.update(root, (root) => {
+      root.content = 'second';
+    });
+
+    const branch = Branch.create(doc, { name: 'from-v1', parent: root, heads: checkpoint.heads });
+    const branchText = await branch.content.load();
+    expect(branchText.content).toBe('first');
+  });
+
+  test('merge applies branch changes to parent as one edit', async ({ expect }) => {
+    const { doc, root } = await setup('alpha\nbravo\n');
+
+    const branch = Branch.create(doc, { name: 'draft', parent: root });
+    const branchText = await branch.content.load();
+    Obj.update(branchText, (branchText) => {
+      branchText.content = 'alpha\nbravo\ncharlie\n';
+    });
+    // Concurrent parent edit after the fork.
+    Obj.update(root, (root) => {
+      root.content = 'alpha edited\nbravo\n';
+    });
+
+    const result = Branch.merge(doc, branch);
+    expect(result.conflicts).toBe(0);
+    expect(root.content).toBe('alpha edited\nbravo\ncharlie\n');
+    expect(branch.status).toBe('merged');
+    expect(doc.history?.versions.some((version) => version.name === 'merge: draft')).toBe(true);
+  });
+
+  test('merge leaves conflict markers when both sides edit the same line', async ({ expect }) => {
+    const { doc, root } = await setup('alpha\nbravo\n');
+
+    const branch = Branch.create(doc, { name: 'draft', parent: root });
+    const branchText = await branch.content.load();
+    Obj.update(branchText, (branchText) => {
+      branchText.content = 'alpha theirs\nbravo\n';
+    });
+    Obj.update(root, (root) => {
+      root.content = 'alpha ours\nbravo\n';
+    });
+
+    const result = Branch.merge(doc, branch);
+    expect(result.conflicts).toBe(1);
+    expect(root.content).toContain('<<<<<<< branch');
+    expect(root.content).toContain('alpha theirs');
+    expect(root.content).toContain('alpha ours');
+    expect(branch.status).toBe('merged');
+  });
+
+  test('branch of a branch forks from and merges into its parent branch', async ({ expect }) => {
+    const { doc, root } = await setup('alpha\n');
+
+    const parentBranch = Branch.create(doc, { name: 'draft', parent: root });
+    const parentText = await parentBranch.content.load();
+    Obj.update(parentText, (parentText) => {
+      parentText.content = 'alpha\nbravo\n';
+    });
+
+    const childBranch = Branch.create(doc, { name: 'nested', parent: parentText });
+    const childText = await childBranch.content.load();
+    expect(childText.content).toBe('alpha\nbravo\n');
+
+    Obj.update(childText, (childText) => {
+      childText.content = 'alpha\nbravo\ncharlie\n';
+    });
+
+    // Merging the child lands on the parent BRANCH, not the root.
+    const result = Branch.merge(doc, childBranch);
+    expect(result.conflicts).toBe(0);
+    expect(parentText.content).toBe('alpha\nbravo\ncharlie\n');
+    expect(root.content).toBe('alpha\n');
+  });
+
+  test('restore applies historical content as a new forward edit', async ({ expect }) => {
+    const { doc, root } = await setup('first');
+    const checkpoint = Version.create(doc, { name: 'v1', target: root });
+
+    Obj.update(root, (root) => {
+      root.content = 'second';
+    });
+
+    Version.restore(doc, checkpoint);
+    expect(root.content).toBe('first');
+    // History retained: heads advanced, not rewound.
+    expect(Obj.version(root).automergeHeads).not.toEqual(checkpoint.heads);
+  });
+
+  test('discard archives without touching parent', async ({ expect }) => {
+    const { doc, root } = await setup('one');
+
+    const branch = Branch.create(doc, { name: 'draft', parent: root });
+    await branch.content.load();
+    Branch.discard(doc, branch);
+
+    expect(branch.status).toBe('archived');
+    expect(root.content).toBe('one');
+  });
+});