@dxos/plugin-debug 0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264 → 0.13.0

package/src/samples/tidepool/TidepoolSpace.test.ts

@@ -0,0 +1,61 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { buildArchive, histogram } from '@dxos/app-toolkit/testing';
+import * as EffectEx from '@dxos/effect/EffectEx';
+
+import * as TidepoolSpace from './TidepoolSpace.ts';
+
+/**
+ * The Tidepool template is built on demand rather than committed, so this asserts its shape in
+ * place of a fixture: if a schema it seeds changes incompatibly, the build fails here.
+ */
+describe('Tidepool template', () => {
+  test('builds an archive with the whole project graph', { timeout: 120_000 }, async ({ expect }) => {
+    const { json, objectCount } = await EffectEx.runPromise(buildArchive(TidepoolSpace.make()));
+    const counts = histogram(json);
+    const countOf = (typename: string) =>
+      Object.entries(counts)
+        .filter(([type]) => type.includes(typename))
+        .reduce((total, [, count]) => total + count, 0);
+
+    expect(objectCount).toBeGreaterThan(0);
+    expect(countOf('type.project')).toBe(1);
+    expect(countOf('type.repo')).toBe(1);
+    expect(countOf('type.taskSet')).toBe(1);
+    expect(countOf('type.milestone')).toBe(3);
+    expect(countOf('type.organization')).toBe(2);
+    expect(countOf('type.person')).toBe(6);
+    expect(countOf('type.document')).toBe(3);
+    expect(countOf('type.outline')).toBe(1);
+    // Six roots, eleven sub-tasks (three of them one level deeper).
+    expect(countOf('type.task:')).toBe(17);
+  });
+
+  // Same budget as above: this also boots a client and builds the whole space, which a shared CI
+  // runner with coverage instrumentation does not finish inside the 15s default.
+  test('files every sub-task under a parent, at two levels', { timeout: 120_000 }, async ({ expect }) => {
+    const { json } = await EffectEx.runPromise(buildArchive(TidepoolSpace.make()));
+    const objects: Array<{ '@type'?: string; 'id': string; 'title'?: string; 'subtasks'?: unknown }> =
+      JSON.parse(json).objects;
+    const tasks = objects.filter((object) => object['@type']?.includes('type.task:'));
+    // Refs serialize as an envelope, so a parent's `subtasks` are matched by id within it.
+    const childrenOf = (parent: (typeof tasks)[number] | undefined) => {
+      const listed = JSON.stringify(parent?.subtasks ?? []);
+      return tasks.filter((task) => listed.includes(task.id));
+    };
+    const children = tasks.flatMap((task) => childrenOf(task));
+
+    expect(tasks.filter((task) => !children.includes(task))).toHaveLength(6);
+    expect(children).toHaveLength(11);
+
+    // The migration sub-task has children of its own — the level Bramble's flat task set never
+    // exercised.
+    const migration = tasks.find((task) => task.title?.startsWith('Migrate notes written'));
+    expect(migration?.id).toBeDefined();
+    expect(childrenOf(migration)).toHaveLength(3);
+  });
+});

package/src/samples/tidepool/TidepoolSpace.ts

@@ -0,0 +1,65 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Effect from 'effect/Effect';
+
+import type * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+import { Ref } from '@dxos/echo';
+
+import { Docs } from './docs.ts';
+import { ProjectPhase } from './project.ts';
+import { Tasks } from './tasks.ts';
+import { People, Team } from './team.ts';
+import { REFERENCE } from './util.ts';
+
+const phases = {
+  team: Team,
+  people: People,
+  docs: Docs,
+  tasks: Tasks,
+  project: ProjectPhase,
+};
+
+/**
+ * A software-project template: one repository, one work-stream, a two-level task tree, and the
+ * documents a project accumulates — a `.mdl` spec with rule and QA-flow blocks, an architecture note
+ * carrying a mermaid diagram, and a decision log.
+ *
+ * The second `SpaceTemplate` definition, and the reason the phase machinery exists: nothing here is
+ * shared with the Bramble space except the builder itself — the seeds, the phases and the world are
+ * this space's own.
+ */
+export const make = (): SampleSpace.Definition<typeof phases, void> =>
+  SampleSpace.make({
+    space: { name: 'Tidepool — Offline sync v2', icon: 'flask', hue: 'cyan' },
+    reference: REFERENCE,
+    phases,
+    build: (phases) =>
+      Effect.gen(function* () {
+        const organizations = yield* phases.team();
+        const people = yield* phases.people(organizations);
+
+        const docs = yield* phases.docs();
+        const tasks = yield* phases.tasks(people);
+        yield* phases.project({ docs, tasks });
+
+        // The root holds collections only. Project/Repo/TaskSet/Task are not collection-item types,
+        // so they live directly in the space DB and surface through the project's own containers.
+        yield* SampleSpace.collection('Documents', [
+          Ref.make(docs.spec),
+          Ref.make(docs.architecture),
+          Ref.make(docs.decisions),
+        ]);
+      }),
+  });
+
+export const makeTemplate = (): AppCapabilities.SpaceTemplate =>
+  SampleSpace.makeTemplate({
+    id: 'org.dxos.plugin-debug.template.tidepool',
+    description: 'A work-stream with a two-level task tree, a .mdl spec, an architecture note and a decision log.',
+    definition: make(),
+  });

package/src/samples/tidepool/docs.ts

@@ -0,0 +1,140 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+import { Database } from '@dxos/echo';
+import * as Markdown from '@dxos/plugin-markdown/Markdown';
+import { Outline } from '@dxos/types';
+
+//
+// The documents a software project accumulates: a spec, an architecture note, a decision log and
+// the scratch checklist.
+//
+
+/**
+ * A `.mdl` spec — the plugin-spec grammar this repo uses for its own plugins: prose under `##`
+ * headings, `rule` blocks the agentic review enforces, and `flow` blocks a QA run executes.
+ */
+const SPEC_MDL = `# Sync v2
+
+## Design
+
+A note is a CRDT sequence plus a plain-text title. The envelope carries a version byte so a client
+that speaks v1 is refused with a typed error instead of failing to parse.
+
+Reconciliation is one-way: the device offers its operations, the server replies with what it does
+not hold. Nothing is deleted on either side as part of a sync.
+
+## Rules
+
+\`\`\`rule no-lww-on-bodies
+A note body is never merged by timestamp. Any code path that picks a winner by \`updatedAt\` on
+\`note.body\` is a defect — bodies converge through the sequence CRDT.
+\`\`\`
+
+\`\`\`rule versioned-envelope
+Every payload written to the wire carries the envelope version. A writer that omits it is a defect;
+an unversioned payload on read is rejected, not guessed at.
+\`\`\`
+
+## QA
+
+\`\`\`flow QA-1 two devices, one paragraph
+1. Take device A and device B offline.
+2. On A, append a sentence to the second paragraph of "Tide pool survey — bay 3".
+3. On B, correct a word in the same paragraph.
+4. Bring both online.
+5. Both edits are present and the paragraph reads correctly. Neither edit is lost.
+\`\`\`
+
+\`\`\`flow QA-2 v1 note on first open
+1. Install the v1 client, write a note, uninstall.
+2. Install this build and open that note.
+3. The note opens, renders, and is converted in place exactly once.
+4. Re-open it. No second conversion is recorded.
+\`\`\`
+`;
+
+const ARCHITECTURE_MD = `# Architecture
+
+Three moving parts. The device owns the truth; the relay only holds what it has been handed.
+
+\`\`\`mermaid
+flowchart LR
+  subgraph Device
+    UI[Editor] --> Store[(Local store)]
+    Store --> Queue[Outbox]
+  end
+  Queue -->|offer ops| Relay
+  Relay -->|missing ops| Store
+  Relay --> Blobs[(Attachment store)]
+  Queue -->|content hash| Blobs
+\`\`\`
+
+## Why the outbox is separate from the store
+
+A field device is offline for weeks, so the store has to be readable and writable with no network at
+all. Sync is therefore a consumer of the store rather than a layer under it — which is what lets the
+editor be indifferent to connectivity.
+
+## Attachments
+
+Photos are content-addressed on capture. The device asks the relay which hashes it already holds and
+uploads only the remainder, so a reconnect after two weeks in the field does not re-send the trip.
+`;
+
+const DECISIONS_MD = `# Decisions
+
+## 2026-05-11 — Titles are last-writer-wins, bodies are not
+
+A title is one line, usually typed once. Running it through the sequence CRDT costs the same
+machinery as a body and buys a merge nobody asked for: two people renaming a note want to see one
+name win, not a splice of both.
+
+Bodies are different — paragraphs are edited concurrently and losing an edit is the bug we set out
+to fix. So: body through the CRDT, title by timestamp, and the rule against timestamp-merging
+bodies is written into SPEC.mdl so a future change has to argue with it.
+
+## 2026-05-04 — Version the envelope rather than sniffing it
+
+Sniffing works until a v1 payload happens to parse as v2. A version byte turns that into a refusal
+with a readable message, which is what a field team needs to hear.
+
+## 2026-04-28 — Convert v1 notes eagerly, in place
+
+The alternative — read v1 forever behind a shim — leaves two formats live indefinitely and every
+later change has to handle both. Converting on first open is a one-time cost and it has to be
+idempotent, which is a thing a test can state.
+`;
+
+const OUTLINE_MD = `- [x] Agree the envelope version byte
+- [x] Write SPEC.mdl and get Ravi to read it
+- [ ] Decide on conflicting titles
+  - [x] Write up the options
+  - [ ] Get Noa to sign off
+- [ ] Ask Sung-min what "saved" should look like on the device
+- [ ] Book the Northwind survey window
+`;
+
+export type DocsResult = {
+  spec: Markdown.Document;
+  architecture: Markdown.Document;
+  decisions: Markdown.Document;
+  outline: Outline.Outline;
+};
+
+/** The project's written artifacts, plus the outline that backs its scratch checklist. */
+export const Docs: SampleSpace.Phase<DocsResult> = SampleSpace.phase('docs', {
+  schemas: [Markdown.Document, Outline.Outline],
+  run: () =>
+    Effect.gen(function* () {
+      const spec = yield* Database.add(Markdown.make({ name: 'SPEC.mdl', content: SPEC_MDL }));
+      const architecture = yield* Database.add(Markdown.make({ name: 'ARCHITECTURE.md', content: ARCHITECTURE_MD }));
+      const decisions = yield* Database.add(Markdown.make({ name: 'DECISIONS.md', content: DECISIONS_MD }));
+      const outline = yield* Database.add(Outline.make({ name: 'Working notes', content: OUTLINE_MD }));
+      return { spec, architecture, decisions, outline };
+    }),
+});

package/src/samples/tidepool/project.ts

@@ -0,0 +1,57 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+import * as Project from '@dxos/compute/Project';
+import { Database, Ref } from '@dxos/echo';
+import { Repo } from '@dxos/types';
+
+import { type DocsResult } from './docs.ts';
+import { type TasksResult } from './tasks.ts';
+
+//
+// The repository and the project that ties everything else together.
+//
+
+export type ProjectInput = { docs: DocsResult; tasks: TasksResult };
+
+export type ProjectResult = { project: Project.Project; repo: Repo.Repo };
+
+/**
+ * The work-stream itself: it names the repository the work lands in, adopts the task set, and holds
+ * the written artifacts in order. `Project.make` would create its own empty task set, so the one
+ * built by the tasks phase is passed in explicitly.
+ */
+export const ProjectPhase: SampleSpace.Phase<ProjectResult, ProjectInput> = SampleSpace.phase('project', {
+  schemas: [Project.Project, Repo.Repo],
+  run: ({ docs, tasks }: ProjectInput) =>
+    Effect.gen(function* () {
+      const repo = yield* Database.add(
+        Repo.make({
+          name: 'tidepool',
+          owner: 'tidepool',
+          url: 'https://github.com/tidepool/tidepool',
+          description: 'Offline-first notes for field research.',
+          defaultBranch: 'main',
+        }),
+      );
+
+      const project = yield* Database.add(
+        Project.make({
+          name: 'Offline sync v2',
+          description:
+            'Make two field devices editing the same note converge without a manual step, in time for the Northwind survey.',
+          status: 'active',
+          repo: Ref.make(repo),
+          taskSet: Ref.make(tasks.taskSet),
+          outline: Ref.make(docs.outline),
+          artifacts: [Ref.make(docs.spec), Ref.make(docs.architecture), Ref.make(docs.decisions)],
+        }),
+      );
+
+      return { project, repo };
+    }),
+});

package/src/samples/tidepool/tasks.ts

@@ -0,0 +1,252 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { EntityId } from '@dxos/echo/Key';
+import { Milestone, Task, TaskSet } from '@dxos/types';
+
+import { type PersonKey, type PersonMap } from './team.ts';
+import { daysAgo } from './util.ts';
+
+//
+// The task set, authored as a tree.
+//
+// The set lists its root tasks and each task lists its own sub-tasks (`Task.subtasks`), at unbounded
+// depth. The seeds are nested the same way, which keeps the shape of the work visible in the source
+// rather than reconstructable only by following refs.
+//
+
+type TaskSeed = {
+  readonly title: string;
+  readonly status: Task.Status;
+  readonly assignee?: PersonKey;
+  readonly description?: string;
+  readonly priority?: Task.Priority;
+  readonly estimate?: Task.Estimate;
+  /** Milestone key this task rolls up to; inherited by sub-tasks that do not name their own. */
+  readonly milestone?: MilestoneKey;
+  readonly subTasks?: ReadonlyArray<TaskSeed>;
+};
+
+type MilestoneKey = 'protocol' | 'merge' | 'field';
+
+const MILESTONE_SEEDS = [
+  {
+    key: 'protocol',
+    name: 'Sync protocol frozen',
+    description: 'Wire format agreed and versioned; no further breaking changes before launch.',
+  },
+  {
+    key: 'merge',
+    name: 'Conflict-free merge',
+    description: 'Two field devices editing the same note offline converge without a manual step.',
+  },
+  {
+    key: 'field',
+    name: 'Northwind field trial',
+    description: 'Two weeks offline on the Northwind survey, then a clean reconciliation.',
+  },
+] as const;
+
+const TASK_SEEDS: ReadonlyArray<TaskSeed> = [
+  {
+    title: 'Freeze the v2 sync wire format',
+    status: 'done',
+    assignee: 'ravi',
+    priority: 'urgent',
+    milestone: 'protocol',
+    description: 'Version the envelope so a v1 client is rejected with a readable error, not a parse failure.',
+    subTasks: [
+      { title: 'Add a version byte to the envelope', status: 'done', assignee: 'ravi', estimate: 's' },
+      { title: 'Reject v1 payloads with a typed error', status: 'done', assignee: 'ravi', estimate: 's' },
+      {
+        title: 'Write the format down in SPEC.mdl',
+        status: 'done',
+        assignee: 'noa',
+        estimate: 'xs',
+        description: 'The spec is the artifact reviewers read; the code is not.',
+      },
+    ],
+  },
+  {
+    title: 'Last-writer-wins is not good enough for notes',
+    status: 'started',
+    assignee: 'ravi',
+    priority: 'high',
+    milestone: 'merge',
+    estimate: 'l',
+    description: 'Two people editing the same paragraph offline lose one edit. Move the note body to a CRDT.',
+    subTasks: [
+      { title: 'Model the note body as a sequence CRDT', status: 'done', assignee: 'ravi', estimate: 'm' },
+      {
+        title: 'Decide what happens to conflicting titles',
+        status: 'review',
+        assignee: 'noa',
+        estimate: 's',
+        description: 'A title is one line; a CRDT there reads as noise. Written up in DECISIONS.md.',
+      },
+      {
+        title: 'Migrate notes written by the v1 client',
+        status: 'started',
+        assignee: 'imogen',
+        estimate: 'm',
+        subTasks: [
+          { title: 'Detect a v1 note on read', status: 'done', assignee: 'imogen', estimate: 's' },
+          { title: 'Convert in place, once, on first open', status: 'started', assignee: 'imogen', estimate: 's' },
+          { title: 'Prove the conversion is idempotent', status: 'todo', assignee: 'lena', estimate: 's' },
+        ],
+      },
+    ],
+  },
+  {
+    title: 'Attachment sync eats the battery',
+    status: 'todo',
+    assignee: 'imogen',
+    priority: 'high',
+    milestone: 'field',
+    estimate: 'm',
+    description: 'Photos re-upload on every reconnect. Content-address them and skip what the server already has.',
+    subTasks: [
+      { title: 'Hash attachments on capture', status: 'todo', assignee: 'imogen', estimate: 's' },
+      { title: 'Ask the server what it already holds', status: 'todo', assignee: 'ravi', estimate: 's' },
+    ],
+  },
+  {
+    title: 'Offline state has no affordance in the UI',
+    status: 'started',
+    assignee: 'theo',
+    priority: 'medium',
+    milestone: 'field',
+    estimate: 's',
+    description: 'Sung-min asked how anyone knows whether a note is saved. Nothing in the UI answers that.',
+  },
+  {
+    title: 'Two-week offline soak test',
+    status: 'blocked',
+    assignee: 'lena',
+    priority: 'high',
+    milestone: 'field',
+    estimate: 'l',
+    description: 'Blocked on the v1 migration: soaking a format we are about to change proves nothing.',
+  },
+  {
+    title: 'Cut 2.0-beta.1 for Northwind',
+    status: 'todo',
+    assignee: 'noa',
+    priority: 'medium',
+    milestone: 'field',
+    estimate: 's',
+  },
+];
+
+export type TasksResult = {
+  taskSet: TaskSet.TaskSet;
+  tasks: Task.Task[];
+  milestones: Milestone.Milestone[];
+};
+
+/**
+ * Depth-first flatten, resolving each seed against its parent's milestone and recording each task's
+ * children so they can be filed under it once stored.
+ */
+const buildTasks = (
+  seeds: ReadonlyArray<TaskSeed>,
+  people: PersonMap,
+  milestones: Record<MilestoneKey, Milestone.Milestone>,
+): { tasks: Task.Task[]; roots: Task.Task[]; children: Map<Task.Task, Task.Task[]> } => {
+  const tasks: Task.Task[] = [];
+  const roots: Task.Task[] = [];
+  const children = new Map<Task.Task, Task.Task[]>();
+  const visit = (seed: TaskSeed, parent: Task.Task | undefined, milestone: MilestoneKey | undefined) => {
+    const key = seed.milestone ?? milestone;
+    const task = Task.make({
+      title: seed.title,
+      status: seed.status,
+      description: seed.description,
+      priority: seed.priority,
+      estimate: seed.estimate,
+      assignee: seed.assignee ? { contact: Ref.make(people[seed.assignee]) } : undefined,
+      milestone: key ? Ref.make(milestones[key]) : undefined,
+      // Task carries no due date; its dates are activity-log lines, so that is where they go.
+      history: [
+        {
+          id: EntityId.random(),
+          date: daysAgo(21),
+          event: 'created' as const,
+          description: 'Filed against the sync v2 work-stream.',
+        },
+        ...(seed.status === 'done'
+          ? [
+              {
+                id: EntityId.random(),
+                date: daysAgo(9),
+                event: 'updated' as const,
+                description: 'Status changed to done.',
+              },
+            ]
+          : []),
+      ],
+    });
+    tasks.push(task);
+    if (parent) {
+      children.set(parent, [...(children.get(parent) ?? []), task]);
+    } else {
+      roots.push(task);
+    }
+    for (const child of seed.subTasks ?? []) {
+      visit(child, task, key);
+    }
+  };
+
+  for (const seed of seeds) {
+    visit(seed, undefined, undefined);
+  }
+  return { tasks, roots, children };
+};
+
+/**
+ * The project's work: three milestones and a two-level task tree. The set lists the roots and each
+ * parent lists its sub-tasks, both written through `SampleSpace.children`.
+ */
+export const Tasks: SampleSpace.Phase<TasksResult, PersonMap> = SampleSpace.phase('tasks', {
+  schemas: [TaskSet.TaskSet, Task.Task, Milestone.Milestone],
+  run: (people: PersonMap) =>
+    Effect.gen(function* () {
+      const taskSet = yield* Database.add(
+        TaskSet.make({ name: 'Offline sync v2', description: 'Everything that has to land before the field trial.' }),
+      );
+
+      const milestones = yield* SampleSpace.seed(MILESTONE_SEEDS, (seed) =>
+        Effect.succeed(Milestone.make({ name: seed.name, description: seed.description })),
+      );
+      yield* SampleSpace.children(taskSet, Object.values(milestones), (taskSet, refs) => {
+        taskSet.milestones = refs;
+      });
+
+      const { tasks, roots, children } = buildTasks(TASK_SEEDS, people, milestones);
+      yield* SampleSpace.children(taskSet, roots, (taskSet, refs) => {
+        taskSet.tasks = refs;
+      });
+      for (const [parent, subtasks] of children) {
+        yield* SampleSpace.children(parent, subtasks, (parent, refs) => {
+          parent.subtasks = refs;
+        });
+      }
+
+      // One execution dependency, so the blocked soak test reads as blocked for a stated reason
+      // rather than by status alone.
+      const soak = tasks.find((task) => task.title.startsWith('Two-week offline soak'));
+      const migration = tasks.find((task) => task.title.startsWith('Migrate notes written'));
+      if (soak && migration) {
+        Obj.update(soak, (soak) => {
+          soak.dependsOn = [Ref.make(migration)];
+        });
+      }
+
+      return { taskSet, tasks, milestones: Object.values(milestones) };
+    }),
+});

package/src/samples/tidepool/team.ts

@@ -0,0 +1,87 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+import { Database, Ref } from '@dxos/echo';
+import { Organization, Person } from '@dxos/types';
+
+//
+// The company and the people who show up in tasks, reviews and decisions.
+//
+
+export type OrgKey = 'tidepool' | 'northwind';
+
+export type OrgMap = Record<OrgKey, Organization.Organization>;
+
+const ORG_SEEDS = [
+  {
+    key: 'tidepool',
+    name: 'Tidepool',
+    description: 'Six-person team building an offline-first notes app for field research.',
+    status: 'active',
+    website: 'https://tidepool.dev',
+  },
+  {
+    key: 'northwind',
+    name: 'Northwind Marine Lab',
+    description: 'Design partner. Their field teams work for weeks with no connectivity.',
+    status: 'active',
+    website: 'https://northwind-marine.org',
+  },
+] as const;
+
+export const Team: SampleSpace.Phase<OrgMap> = SampleSpace.phase('team', {
+  schemas: [Organization.Organization],
+  run: () =>
+    SampleSpace.seed(ORG_SEEDS, (seed) =>
+      Database.add(
+        Organization.make({
+          name: seed.name,
+          description: seed.description,
+          status: seed.status,
+          website: seed.website,
+        }),
+      ),
+    ),
+});
+
+export type PersonKey = 'noa' | 'ravi' | 'imogen' | 'theo' | 'lena' | 'sung';
+
+export type PersonMap = Record<PersonKey, Person.Person>;
+
+const PERSON_SEEDS = [
+  { key: 'noa', fullName: 'Noa Almeida', jobTitle: 'Engineering lead', orgKey: 'tidepool', email: 'noa@tidepool.dev' },
+  { key: 'ravi', fullName: 'Ravi Menon', jobTitle: 'Sync engineer', orgKey: 'tidepool', email: 'ravi@tidepool.dev' },
+  {
+    key: 'imogen',
+    fullName: 'Imogen Clarke',
+    jobTitle: 'Mobile engineer',
+    orgKey: 'tidepool',
+    email: 'imogen@tidepool.dev',
+  },
+  { key: 'theo', fullName: 'Theo Baptiste', jobTitle: 'Designer', orgKey: 'tidepool', email: 'theo@tidepool.dev' },
+  { key: 'lena', fullName: 'Lena Hofer', jobTitle: 'QA', orgKey: 'tidepool', email: 'lena@tidepool.dev' },
+  {
+    key: 'sung',
+    fullName: 'Sung-min Park',
+    jobTitle: 'Field research lead',
+    orgKey: 'northwind',
+    email: 'sungmin@northwind-marine.org',
+  },
+] as const;
+
+export const People: SampleSpace.Phase<PersonMap, OrgMap> = SampleSpace.phase('people', {
+  schemas: [Person.Person],
+  run: (organizations: OrgMap) =>
+    SampleSpace.seed(PERSON_SEEDS, (seed) =>
+      Database.add(
+        Person.make({
+          fullName: seed.fullName,
+          jobTitle: seed.jobTitle,
+          organization: Ref.make(organizations[seed.orgKey]),
+          emails: [{ label: 'Work', value: seed.email }],
+        }),
+      ),
+    ),
+});

package/src/samples/tidepool/util.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+
+/** Stable reference date so regenerations are reproducible. Override with NOW=2026-05-20 env. */
+export const REFERENCE = process.env.NOW ? new Date(process.env.NOW) : new Date('2026-05-20T15:00:00Z');
+
+/**
+ * Bound to the same reference the definition declares, so the pure content builders can date their
+ * objects without every one of them being an effect.
+ */
+export const clock = SampleSpace.makeClock(REFERENCE);
+
+export const daysAgo = clock.daysAgo;
+
+export const daysFromNow = clock.daysFromNow;