@fungi.computer/bonsai 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# @fungi.computer/bonsai
+
+## 0.1.0
+
+### Minor Changes
+
+- Changes since 0.0.1:
+
+  - fix(agar): keep the result-row decoder out of Apps that do not present
+  - refactor(caps): one status bead, the gooey one, everywhere
+  - feat(shed): one Ghostty terminal for the light and full shells
+  - test(bonsai): cheaper real-git tests and a real-git vitest project
+  - feat(apps): describe finished Prints, Inkcap, Shed and Bonsai calls
+  - feat(oyster): public release 0.1.0
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+  - @fungi.computer/agar@0.2.0
+  - @fungi.computer/caps@0.1.0
+  - @fungi.computer/gills@0.1.0
+  - @fungi.computer/oyster@0.2.0
+  - @fungi.computer/puffball@0.1.0
+
+## 0.0.1
+
+### Patch Changes
+
+- Initial public release of @fungi.computer/bonsai.
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+  - @fungi.computer/agar@0.1.0
+  - @fungi.computer/caps@0.0.2
+  - @fungi.computer/issues@0.0.1
+  - @fungi.computer/oyster@0.1.0
+  - @fungi.computer/puffball@0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,197 @@
-# Temporary Holding Version
+# Bonsai (`@fungi.computer/bonsai`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Bonsai is a git platform for many agents working on one codebase at once. Each
+agent gets its own fork, pushes with ordinary `git`, and shows up live.
+
+![Bonsai: the network graph of reed-pond-2 with one lane per agent fork, the live activity feed, and cards for koi-pond, tide-pool and the other repositories](docs/media/overview.png)
+
+Bonsai is one of the starter Apps of
+[Oyster](https://github.com/fungi-computer/oyster), the open App host that runs
+on your own Cloudflare account. Its repositories live in Cloudflare Artifacts,
+so a repository per agent is cheap. Try it at
+<https://oyster.shiit.app/apps/bonsai/>: that installation is public and
+read-only, so you can browse repositories, the graph, Changes and issues with no
+sign-in.
+
+## What you can do
+
+- **Give every agent its own fork.** `repos.fork` makes one in a single call,
+  and the agent clones it through Oyster's git door with its own key. It never
+  sees a provider credential.
+- **See who did what.** The network graph draws each fork as a lane and colours
+  every commit by the key that pushed it, not by the commit's author field.
+  Merges fold back into `main`.
+- **Review Changes.** Every fork is already a Change, measured against `main` on
+  each push: commits ahead and behind, and the diff it would bring in. Merge
+  with one click; Bonsai always writes a merge commit.
+- **Hand conflicts back.** When `main` has moved, Bonsai records the conflict
+  and its paths. The agent pulls `main`, resolves it, pushes, and the merge goes
+  through.
+- **Keep issues in the repository.** Markdown files under `issues/`, with
+  `status`, `priority` and `blocked_by` in their frontmatter. Unblocked work is
+  listed first, and agents read and update them with `git`.
+- **Watch the Overview.** Network, Live, Changes, README, contributors, agents
+  versus people, code age, file churn and a contribution calendar, as tiles you
+  arrange and save.
+- **React to events.** Every push, fork, merge and conflict is an event, sent as
+  a signed webhook or picked up by a
+  [Trellis](https://github.com/fungi-computer/trellis) workflow trigger.
+
+![Bonsai's Overview of koi-pond in the light theme: Network, Live, Changes, Agents and people, Contributors, README and the contribution calendar](docs/media/bonsai-insights.png)
+
+<img alt="Bonsai on a phone in the light theme: the network graph above the live feed" src="docs/media/overview-phone.png" width="300">
+
+## Get it
+
+Bonsai installs with the other starter Apps. On a deployed Oyster (see the
+[Oyster quick start](https://github.com/fungi-computer/oyster#quick-start-deploy-your-own-oyster)),
+run:
+
+```sh
+export OYSTER_URL=https://oyster.<your-subdomain>.workers.dev
+export OYSTER_OWNER_KEY=<your owner key>
+npx oyster install-apps
+```
+
+The installer clones this repository and the six others, seeds each on your
+Oyster with `git push`, builds them on your Computer and installs them. Sign in
+at `$OYSTER_URL/login` with the owner key and open Bonsai from the Tourtois
+desktop. Run `install-apps` again to update; each App keeps its data.
+
+To let anyone browse your Bonsai read-only, as the live demo does:
+
+```sh
+curl -X PUT -H "Authorization: Bearer $OYSTER_OWNER_KEY" -H 'content-type: application/json' \
+  -d '{"visibility":"public"}' $OYSTER_URL/api/installations/bonsai/visibility
+```
+
+## Put agents to work
+
+Create a key for each agent. Oyster shows it once; its `name` is also its id, so
+a fork is always `<repo>--<name>`. These grants let the key use every App on
+this Oyster, including ones installed later, as the owner would:
+
+```sh
+curl -X POST -H "Authorization: Bearer $OYSTER_OWNER_KEY" -H 'content-type: application/json' \
+  -d '{"name":"morel","grants":[{"capability":"apps.use","targets":{"kind":"all"}}]}' \
+  $OYSTER_URL/api/keys
+```
+
+The reply's `plaintext` key, starting `oyk_`, works for App methods and for
+`git`. Revoke it with `POST $OYSTER_URL/api/keys/revoke` and
+`{"keyId":"morel","requestId":"<any id>"}`; it stops working immediately. Fork a
+repository and clone the fork:
+
+```sh
+curl -X POST -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
+  -d '{"repo":"koi-pond"}' $OYSTER_URL/apps/bonsai/methods/repos.fork
+git -c http.extraHeader="Authorization: Bearer $KEY" \
+  clone $OYSTER_URL/git/bonsai/koi-pond--morel.git
+```
+
+`scripts/agent.sh <name> <repo> "<task>"` does all of that and starts a coding
+agent in the clone. It uses Codex by default; set `AGENT_CMD` to use another.
+
+## Webhooks
+
+```sh
+curl -X POST -H "Authorization: Bearer $OYSTER_OWNER_KEY" -H 'content-type: application/json' \
+  -d '{"installationId":"bonsai","url":"https://example.com/hook","types":["git.push","change.merged"]}' \
+  $OYSTER_URL/api/webhooks
+```
+
+The reply carries a `whsec_` secret, shown once. Each delivery is a Standard
+Webhooks payload, `{type, timestamp, data}`, signed with `webhook-id`,
+`webhook-timestamp` and `webhook-signature` and with `X-Hub-Signature-256`. The
+event types are `git.push`, `git.fork`, `change.opened`, `change.merged`,
+`change.conflicted` and `repo.created`. A delivery that does not get a 2xx is
+retried after 10 s, 1 min, 5 min, 30 min and 2 h;
+`GET /api/webhooks/<id>/deliveries` lists the attempts.
+
+## Build and install Apps
+
+Bonsai also edits the other Apps on your Oyster. `apps.fork` copies an installed
+App's source into a new Bonsai repository you own. Push your changes to it, then
+open the repository's **Settings** and use **Build & install**: Oyster builds
+that exact commit on your Computer and installs the Release, or switches a live
+installation onto it while keeping its data. To fork Bonsai itself:
+
+```sh
+curl -X POST -H "Authorization: Bearer $OYSTER_OWNER_KEY" -H 'content-type: application/json' \
+  -d '{"appId":"app_bonsai","name":"my-bonsai"}' \
+  $OYSTER_URL/apps/bonsai/methods/apps.fork
+git -c http.extraHeader="Authorization: Bearer $OYSTER_OWNER_KEY" \
+  clone $OYSTER_URL/git/bonsai/my-bonsai.git
+```
+
+To work from GitHub instead, fork this repository and point the installer at
+your forks with `--repositories <base URL>` and `--ref <branch or tag>`. The
+installer reads all seven starter Apps from that base, so fork them under one
+account.
+
+## Agent tools
+
+Every method is `POST $OYSTER_URL/apps/bonsai/methods/<name>` with a JSON body
+and a key, and the same methods reach agents through Oyster's MCP endpoint; see
+[Git, keys and MCP](https://github.com/fungi-computer/oyster#git-keys-and-mcp).
+Bonsai's own UI uses the same API.
+
+| Area         | Methods                                                                                                    |
+| ------------ | ---------------------------------------------------------------------------------------------------------- |
+| Repositories | `repos.list`, `repos.get`, `repos.create`, `repos.fork`, `repos.delete`, `branches.options`                |
+| Files        | `files.tree`, `files.list`, `files.read`, `files.save`, `files.sync`, `files.discard`, `issues.read`       |
+| History      | `commits.list`, `commits.get`, `graph.get`, `activity.list`, `actors.list`                                 |
+| Changes      | `changes.list`, `changes.get`, `changes.open`, `changes.approve`, `changes.merge`, `changes.close`, `sync` |
+| Checks       | `checks.request`, `checks.report`                                                                          |
+| Insights     | `insights.code`, `insights.layout.get`, `insights.layout.save`                                             |
+| Apps (owner) | `apps.fork`, `apps.build`, `apps.buildStatus`, `apps.install`                                              |
+
+## How it is built
+
+Bonsai is an App on Oyster. Oyster serves its UI in a sandboxed frame, runs its
+backend as a Durable Object with its own SQLite, and grants it only the two
+bindings it declares:
+
+- **`GIT`**: create, fork, log, read trees and blobs, and merge on Cloudflare
+  Artifacts, scoped to Bonsai's installation. Oyster holds every token.
+- **`EVENTS`**: `emit(type, payload, eventId)`, delivered as signed webhooks.
+
+When a client pushes, Oyster's git door asks Bonsai whether that key may push to
+that repository, forwards the push to Artifacts, and reports the accepted refs
+back to Bonsai. Bonsai keeps saved copies of repository pages in SQLite, so
+browsing a repository makes no Git calls once its copies are warm.
+
+| Piece       | Where                | Owns                                                   |
+| ----------- | -------------------- | ------------------------------------------------------ |
+| App methods | `backend/methods.ts` | The one API, for agents, hosts and Bonsai's own UI     |
+| Operations  | `backend/service.ts` | What each method does                                  |
+| State       | `backend/state.ts`   | Repository registry, activity, who pushed which commit |
+| Facet       | `backend/index.ts`   | The App's Durable Object; push consent and push facts  |
+| Contracts   | `shared/`            | Response shapes and the event envelope (`verifyHook`)  |
+| UI          | `web/`               | React; the network graph is `web/network-graph.tsx`    |
+
+## Build and check
+
+```sh
+pnpm install
+pnpm build
+pnpm typecheck
+pnpm test
+```
+
+`seed:demo` replays the `koi-pond` story against an Oyster through its public
+API: three agents (morel, chanterelle and enoki) fork the repository and push
+real changes with ordinary `git`; one Change is checked and merged, one stays
+open and one conflicts. Keep the owner key in a private file; the script never
+prints it:
+
+```sh
+pnpm seed:demo --origin $OYSTER_URL \
+  --work /private/bonsai-demo --owner-key-file /private/oyster-owner-key
+```
+
+A completed rerun checks the three outcomes without making new commits.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/backend/background.ts

@@ -0,0 +1,259 @@
+/** One actor-lane Watchdog dispatcher; feature modules own cargo and row settlement. */
+import {
+  Watchdog,
+  type ConcurrentWatchdogRuntime,
+  type WatchdogQueueProjector,
+  type WatchdogSqliteOwner,
+  type WatchdogRunningJob,
+  type WatchdogSettledJob,
+  type WatchdogExecutionDecision,
+  type WatchdogTransactionalProjection,
+} from "@fungi.computer/watchdog";
+import {
+  actorLane,
+  backgroundSyncRefusalSchema,
+  type BackgroundSyncRefusal,
+  type BackgroundBinding,
+} from "@fungi.computer/puffball/background-replay";
+import type { AppMethodCallContext } from "@fungi.computer/puffball/app-method-runtime";
+import {
+  executeQueuedFileEdit,
+  cleanupSettledFileEdit,
+  projectQueuedFileEdit,
+} from "./file-edits.js";
+import type { Bonsai } from "./service.js";
+import {
+  executeQueuedMerge,
+  cleanupQueuedMerge,
+  mergeJobSchema,
+  projectQueuedMerge,
+} from "./merge.js";
+import { readCopyFrame } from "./git.js";
+import { AppError } from "@fungi.computer/agar/errors";
+
+const invocations = new WeakMap<
+  WatchdogSqliteOwner,
+  WeakMap<AppMethodCallContext, Promise<ConcurrentWatchdogRuntime>>
+>();
+const projectors = new WeakMap<
+  WatchdogSqliteOwner,
+  Map<"file-edit" | "merge", WatchdogQueueProjector>
+>();
+// Different caller runtimes share one live-claim view of the durable owner.
+const activeJobs = new WeakMap<WatchdogSqliteOwner, Set<string>>();
+// Covers the claim-to-execute window before a job enters activeJobs.
+const ticksInFlight = new WeakMap<WatchdogSqliteOwner, Map<string, number>>();
+
+/** Replace a feature's synchronous row projection without opening another runner. */
+export function registerBackgroundProjector(
+  bonsai: Bonsai,
+  feature: "file-edit" | "merge",
+  project: WatchdogQueueProjector,
+): void {
+  const owner = bonsai.state.backgroundOwner;
+  let registered = projectors.get(owner);
+  if (registered === undefined) {
+    registered = new Map();
+    projectors.set(owner, registered);
+  }
+  registered.set(feature, project);
+}
+
+/**
+ * Share one runner within this trusted call context. A fresh replay context opens
+ * a fresh runtime over the same durable owner; it never retains old authority.
+ * Hosts own frame-close wakes and abort the old facet before a click can enter.
+ */
+export function backgroundRuntime(
+  bonsai: Bonsai,
+  caller: AppMethodCallContext,
+  signal: AbortSignal = new AbortController().signal,
+  background?: BackgroundBinding,
+): Promise<ConcurrentWatchdogRuntime> {
+  registerBackgroundProjector(bonsai, "file-edit", (transition) => {
+    projectQueuedFileEdit(bonsai, transition);
+  });
+  registerBackgroundProjector(bonsai, "merge", (transition) => {
+    projectQueuedMerge(bonsai, transition);
+  });
+  const owner = bonsai.state.backgroundOwner;
+  let calls = invocations.get(owner);
+  if (calls === undefined) {
+    calls = new WeakMap();
+    invocations.set(owner, calls);
+  }
+  const existing = calls.get(caller);
+  if (existing !== undefined) return existing;
+  const created = openLaneRuntime(
+    bonsai,
+    actorLane(caller.actor),
+    async (job, enqueue) => {
+      if (background === undefined)
+        return { kind: "failed", reason: "access_changed" };
+      if (mergeJobSchema.safeParse(job.payload).success)
+        return executeQueuedMerge(
+          bonsai,
+          caller,
+          job,
+          enqueue,
+          signal,
+          background,
+        );
+      return executeQueuedFileEdit(
+        bonsai,
+        caller,
+        job,
+        enqueue,
+        background,
+        signal,
+      );
+    },
+  );
+  calls.set(caller, created);
+  return created;
+}
+
+/** This is the sole runner factory for admitted execution and zero-grant refusal. */
+function openLaneRuntime(
+  bonsai: Bonsai,
+  lane: string,
+  execute: (
+    job: WatchdogRunningJob,
+    enqueue: WatchdogTransactionalProjection["enqueueAcceptedJob"],
+  ) => Promise<WatchdogExecutionDecision>,
+  settled?: WatchdogSettledJob[],
+): Promise<ConcurrentWatchdogRuntime> {
+  const owner = bonsai.state.backgroundOwner;
+  let active = activeJobs.get(owner);
+  if (active === undefined) {
+    active = new Set();
+    activeJobs.set(owner, active);
+  }
+  let runtime: ConcurrentWatchdogRuntime;
+  return Watchdog.make({
+    owner,
+    concurrentLane: lane,
+    project: (transition) => {
+      for (const project of projectors.get(owner)?.values() ?? [])
+        project(transition);
+      if (transition.settled !== undefined) settled?.push(transition.settled);
+    },
+    isAlive: (job) =>
+      Promise.resolve(
+        active.has(job.jobId) || (ticksInFlight.get(owner)?.get(lane) ?? 0) > 1,
+      ),
+    wake: { recompute: () => Promise.resolve() },
+    execute: async (job) => {
+      active.add(job.jobId);
+      try {
+        return await execute(job, (successor) => {
+          runtime.transactional.enqueueAcceptedJob(successor);
+        });
+      } finally {
+        active.delete(job.jobId);
+      }
+    },
+  }).then((opened) => {
+    runtime = opened;
+    return opened;
+  });
+}
+
+/** An available facet settles the refused lane without inventing a caller or binding authority. */
+export async function refuseBackground(
+  bonsai: Bonsai,
+  raw: BackgroundSyncRefusal,
+): Promise<void> {
+  const refusal = backgroundSyncRefusalSchema.parse(raw);
+  // Unavailable installations are host dead letters, never guest settlement.
+  if (refusal.code !== "access_changed") return;
+  registerBackgroundProjector(bonsai, "merge", (transition) => {
+    projectQueuedMerge(bonsai, transition);
+  });
+  registerBackgroundProjector(bonsai, "file-edit", (transition) => {
+    projectQueuedFileEdit(bonsai, transition);
+  });
+  const settled: WatchdogSettledJob[] = [];
+  const runtime = await openLaneRuntime(
+    bonsai,
+    refusal.lane,
+    () => Promise.resolve({ kind: "failed", reason: "access_changed" }),
+    settled,
+  );
+  let result;
+  do {
+    result = await runtime.failLane({
+      lane: refusal.lane,
+      reason: "access_changed",
+    });
+  } while (result.more);
+  // Refused jobs may hold step material with the member's file bytes.
+  for (const job of settled) {
+    await cleanupQueuedMerge(bonsai, job);
+    await cleanupSettledFileEdit(bonsai, job);
+  }
+}
+
+/** An ordinary fresh member call drains only its own lane, with one frame budget. */
+export async function syncBackground(
+  bonsai: Bonsai,
+  caller: AppMethodCallContext,
+  background?: BackgroundBinding,
+): Promise<{ more: boolean }> {
+  if (
+    background === undefined ||
+    caller.actor.kind !== "member" ||
+    caller.workflow !== undefined
+  )
+    return { more: false };
+  const lane = actorLane(caller.actor);
+  await readCopyFrame(bonsai.store, async (store, signal) => {
+    const runtime = await backgroundRuntime(
+      { ...bonsai, store },
+      caller,
+      signal,
+      background,
+    );
+    const owner = bonsai.state.backgroundOwner;
+    let ticks = ticksInFlight.get(owner);
+    if (ticks === undefined) {
+      ticks = new Map();
+      ticksInFlight.set(owner, ticks);
+    }
+    ticks.set(lane, (ticks.get(lane) ?? 0) + 1);
+    let tick;
+    try {
+      tick = await runtime.tickConcurrent();
+    } finally {
+      const remaining = (ticks.get(lane) ?? 1) - 1;
+      if (remaining === 0) ticks.delete(lane);
+      else ticks.set(lane, remaining);
+      if (ticks.size === 0) ticksInFlight.delete(owner);
+    }
+    if (
+      tick.status === "settled" &&
+      tick.job.outcome === "failed" &&
+      tick.job.failureReason === "sync_retry"
+    )
+      throw new AppError(
+        "Git sync is temporarily unavailable. Your changes remain saved.",
+        { code: "HOST_FAILURE", retryable: true },
+      );
+    if (tick.status === "settled") {
+      await cleanupQueuedMerge(bonsai, tick.job);
+      await cleanupSettledFileEdit(bonsai, tick.job);
+    }
+  });
+  return {
+    more:
+      bonsai.state.fileEdits.hasPending(lane) ||
+      bonsai.state
+        .changes(null)
+        .some(
+          (row) =>
+            row.state === "merging" &&
+            row.lease !== null &&
+            actorLane({ kind: "member", memberId: row.lease.by }) === lane,
+        ),
+  };
+}

package/backend/change-copy.ts

@@ -0,0 +1,99 @@
+/** Saved Change facts and immutable detail objects, independent of lifecycle commands. */
+import type { ChangeRecord } from "../shared/contract.js";
+import { AppMethodRefusal } from "@fungi.computer/agar/backend";
+import { treeDiff } from "./diff.js";
+import {
+  changeCopyKey,
+  changeObjectsSchema,
+  changeCopySchema,
+} from "./state.js";
+import {
+  compareChange,
+  projectionStore,
+  type ChangeHistory,
+} from "./history.js";
+import type { Bonsai } from "./service.js";
+import { gitStore } from "./git.js";
+
+async function buildChangeCopy(
+  runtime: Bonsai,
+  row: ChangeRecord,
+  history?: ChangeHistory,
+) {
+  const bonsai = { ...runtime, store: projectionStore(runtime) };
+  const compared =
+    history ??
+    (await compareChange(
+      bonsai.store,
+      row.repo,
+      row.sourceRepo,
+      row.head,
+      row.target,
+    ));
+  if (compared === null)
+    throw new AppMethodRefusal("not_found", "The proposed head is missing");
+  const origins = bonsai.state.origins(compared.aheadHashes);
+  const [base, head] = await Promise.all([
+    compared.base === null
+      ? null
+      : bonsai.store.commit(row.sourceRepo, compared.base),
+    bonsai.store.commit(row.sourceRepo, row.head),
+  ]);
+  if (head === null)
+    throw new AppMethodRefusal("not_found", "The proposed head is missing");
+  const objects = changeObjectsSchema.parse({
+    commits: compared.ahead.map((commit) => ({
+      commit,
+      agent: origins.get(commit.hash)?.agent ?? null,
+    })),
+    diff: await treeDiff(
+      bonsai.store,
+      row.sourceRepo,
+      base?.treeHash ?? null,
+      head.treeHash,
+    ),
+  });
+  const bytes = new TextEncoder().encode(JSON.stringify(objects));
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+  const detailHash = `sha256:${Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+  bonsai.state.copies.putBlob(detailHash, bytes);
+  return changeCopySchema.parse({
+    target: row.target,
+    base: compared.base,
+    ahead: compared.ahead,
+    aheadHashes: compared.aheadHashes,
+    behind: compared.behind,
+    headAuthors: [
+      ...new Set([...origins.values()].map((origin) => origin.agent)),
+    ],
+    detailHash,
+  });
+}
+
+export async function loadChangeCopy(
+  bonsai: Bonsai,
+  row: ChangeRecord,
+  signal: AbortSignal,
+) {
+  const result = await bonsai.state.changeCopies.load(changeCopyKey(row), {
+    git: bonsai.store.binding,
+    signal,
+    rebuild: async (git) => ({
+      head: row.head,
+      value: await buildChangeCopy({ ...bonsai, store: gitStore(git) }, row),
+    }),
+  });
+  if (result.kind !== "ready")
+    throw new AppMethodRefusal("unavailable", "Change copy is rebuilding.");
+  return result.value;
+}
+
+/** Prepare immutable objects and actor-independent facts in a write/push frame. */
+export async function refreshChangeCopy(
+  bonsai: Bonsai,
+  row: ChangeRecord,
+  history?: ChangeHistory,
+): Promise<void> {
+  const value = await buildChangeCopy(bonsai, row, history);
+  bonsai.state.changeCopies.write(changeCopyKey(row), row.head, value);
+}