@camox/api-contract 0.76.0 → 0.76.1

package/dist/router.d.ts

@@ -7,8 +7,6 @@ import { WebSockets } from "agents/websockets";
 import "@earendil-works/pi-ai";
 import "@earendil-works/pi-ai/models";
 import "@earendil-works/pi-durable/tools";
-import { FileErrorCode } from "@earendil-works/pi-durable/env";
-import "camox/_internal/sdkBundleName";
 import "@camox/ai-tools";
 import { AgentEvent } from "@earendil-works/pi-durable";
 import "effect";
@@ -18,6 +16,8 @@ import "drizzle-orm";
 import "drizzle-orm/sqlite-core";
 import { SpecialistId } from "@camox/api-contract/specialists";
 import { DrizzleD1Database } from "drizzle-orm/d1";
+import { FileErrorCode } from "@earendil-works/pi-durable/env";
+import { SdkBundleNames } from "camox/_internal/sdkBundleName";
 import { CIWorkflow, CiContext, CiParams, CloudflareArtifacts } from "@cloudflare/ci";
 import { CiBindings } from "@cloudflare/ci/worker";
 import { ProjectRoomMessage } from "@camox/api-contract/query-keys";
@@ -233,34 +233,6 @@ type Attachment = typeof attachments.$inferSelect;
  */
 type MessageAttachment = Pick<Attachment, "id" | "filename" | "mimeType" | "url" | "blobKey">;
 //#endregion
-//#region ../../apps/api/src/domains/code/remote-env.d.ts
-/** The operations sent as they are: every argument but the context is plain data. */
-declare const SENT: ["absolutePath", "joinPath", "readTextFile", "readTextLines", "readBinaryFile", "writeFile", "appendFile", "truncateFile", "flushFile", "renameFile", "fileInfo", "listDir", "canonicalPath", "exists", "createDir", "remove"];
-/** What a remote environment asks of the one it reaches. */
-type EnvCall = {
-  operation: (typeof SENT)[number];
-  args: unknown[];
-} |
-/** Opens a binary reader there and reads the whole file it opened. */
-{
-  operation: "openBinaryReader";
-  args: [path: string, options?: {
-    noFollow?: boolean;
-  }];
-};
-/** An operation's result as it crosses: its value, or its error as plain data. */
-type EnvAnswer = {
-  ok: true;
-  value: unknown;
-} | {
-  ok: false;
-  error: {
-    code: FileErrorCode;
-    message: string;
-    path?: string;
-  };
-};
-//#endregion
 //#region ../../apps/api/src/domains/revisions/result.d.ts
 /** A revision's ID: a UUIDv7. */
 type RevisionId = string;
@@ -301,347 +273,19 @@ type BuildResult = {
   };
 };
 //#endregion
-//#region ../../apps/api/src/lib/timing.d.ts
-/** What a span's line says beside its name and duration. Undefined fields are left out. */
-type SpanFields = Record<string, string | number | boolean | null | undefined>;
-//#endregion
-//#region ../../apps/api/src/durable-objects/draft-code.d.ts
-/** A revision of the draft whose build goes up as its publish script. */
-type PublishUpload = {
-  /** The project's Project ID. */
-  project: string;
-  revision: string;
-  /** Its build in `REVISION_BUILDS`. */
-  archiveKey: string;
-};
-/** A commit `prepareCommit` made, not on the branch yet. */
-type PreparedCommit = {
-  commit: string;
-  tree: string;
-  /** The tree's files, as a tar archive. */
-  files: Uint8Array;
-  /** The tree's `pnpm-lock.yaml`, if it has one. */
-  lockfile: string | null;
-};
-/**
- * A merge of `main` that doesn't land as a revision as it is: it conflicts, or its tree doesn't
- * build or type check. Recorded for Camox's reconcile turn, which tries once for each move of
- * `main`, until code holding that `main` builds without errors (`settleClash`): the draft has
- * the "doesn't merge with Live's" blocker until then.
- */
-type MergeClash = {
-  /** The commit of `main` that clashed. */
-  main: string;
-  /** The files both sides changed in ways that don't merge, for a merge that conflicts. */
-  conflicts?: string[];
-  /** The merged tree's build, for a merge that doesn't build or type check. */
-  result?: BuildResult;
-};
-/** What merging `main` into the working copy found. */
-type MergeOutcome =
-/** The draft holds the current `main` already. */
-{
-  outcome: "upToDate";
-} |
-/** The working copy has changes no revision holds yet: the merge waits for them. */
-{
-  outcome: "unsettled";
-} |
-/** This move of `main` clashed already, and isn't merged again until `main` moves again. */
-{
-  outcome: "clashedBefore";
-  main: string;
-} | {
-  outcome: "conflicts";
-  main: string;
-  conflicts: string[];
-} |
-/** A merge commit of `main`, not on the branch yet, for a build to commit. */
-{
-  outcome: "merged";
-  main: string;
-  prepared: PreparedCommit;
+//#region ../../apps/api/src/domains/layouts/schema.d.ts
+/** Which collection a layout's record pages render, and the field they're found by. */
+type RecordPages = {
+  collectionId: string;
+  field: string;
 };
+//#endregion
+//#region ../../apps/api/src/domains/pages/schema.d.ts
 /**
- * The working copy of one draft with code, addressed by the draft's ID (`getByName`): a depth-1
- * clone of the draft's branch, held in memory, which the agent's code tools read and write over
- * RPC, through the write line. Every change is saved to its SQLite as it's made, Git's own
- * directory included, so an eviction restores it without cloning again. The skills of its `camox`
- * version are mounted beside the files and never saved, nor committed.
- *
- * It stores nothing until `start` made it, and nothing once `delete` deleted it.
- */
-declare class DraftCode extends DurableObject<Bindings> {
-  #private;
-  /** Whether the draft has code: its branch was made, and not deleted since. */
-  held(): Promise<boolean>;
-  /**
-   * The commit of `main` the draft's code holds: the one its branch last merged, or forked from,
-   * once it has code.
-   */
-  mergedMain(): Promise<string | undefined>;
-  /**
-   * Where the draft's merges of `main` stand: the branch's head, the `main` it holds, and the
-   * last merge that clashed, read at once, as a commit moves them together.
-   */
-  merges(): Promise<{
-    head: string;
-    mergedMain: string;
-    clash: MergeClash | undefined;
-  }>;
-  /** The last merge of `main` that clashed, until a merge of `main` lands. */
-  clash(): Promise<MergeClash | undefined>;
-  /**
-   * Records that the merge of `main` at `clash.main` clashed (see `MergeClash`), for Camox's
-   * reconcile turn. A merge that didn't land is left in the files, uncommitted, conflict markers
-   * included, and the next revision is its merge commit: see `merging`.
-   */
-  recordClash(clash: MergeClash): Promise<void>;
-  /**
-   * The commit of `main` whose merge the files hold, uncommitted, if they do: Camox's reconcile
-   * turn fixes it, and its build commits the merge commit.
-   */
-  merging(): Promise<string | undefined>;
-  /**
-   * Forgets the clash, once the draft's code built without errors and holds the `main` that
-   * clashed: unless the files still hold a merge no commit landed.
-   */
-  settleClash(): Promise<void>;
-  /**
-   * Uploads the build of the draft's revision `revision` as the draft's publish script, ahead of
-   * its publish, unless the script holds it already: its publish then only checks it's there
-   * (`uploadForPublish`). Nothing once a publish took the script, until that publish ends, nor
-   * once the draft ended. A draft that ended during the upload, deleted, loses the script.
-   */
-  prepareUpload(toUpload: PublishUpload): Promise<void>;
-  /**
-   * The draft's publish script holding the build of `revision`, which the publish `instanceId`
-   * ships, taking it: no upload ahead replaces it until that publish ends. Uploads it unless the
-   * script holds it already, as the upload ahead left it. Returns its name, and whether this
-   * uploaded it.
-   */
-  uploadForPublish(toUpload: PublishUpload, instanceId: string, span?: SpanFields): Promise<{
-    script: string;
-    uploaded: boolean;
-  }>;
-  /** The publish of the draft going now, if any: its Workflow instance. */
-  publishGoing(): Promise<string | null>;
-  /**
-   * Records that a member's push landed during the publish `instanceId`: the revision it waits
-   * for a build to leave changed under it, so it goes back to the review (ADR 0043).
-   */
-  notePushDuring(instanceId: string): Promise<void>;
-  /** Whether a member's push landed during the publish `instanceId`. */
-  pushedDuring(instanceId: string): Promise<boolean>;
-  /** Records that a build of the draft's code started, or ended. */
-  markBuilding(building: boolean): Promise<void>;
-  /**
-   * Whether a build of the draft's code is going (see `BUILD_GOING_FOR_AT_MOST_MS`), or owed:
-   * Camox's infrastructure failed the last one, and Camox retries it. A type check, going or
-   * owed, isn't building (ADR 0043).
-   */
-  building(): Promise<boolean>;
-  /**
-   * Records that the thread `threadId` couldn't build the draft's code because of Camox's own
-   * infrastructure, or with `typesOnly`, only check the types of a revision that built, and has
-   * it retry later (`alarm`), each retry waiting longer.
-   */
-  oweBuild({ threadId, typesOnly }: {
-    threadId: string;
-    typesOnly?: boolean;
-  }): Promise<void>;
-  /** Forgets the build Camox owed the draft, once one ended without Camox's failing. */
-  settleOwedBuild(): Promise<void>;
-  /** Retries the build Camox owes the draft, in its thread's build queue, until one lands. */
-  alarm(): Promise<void>;
-  /**
-   * Makes the draft's branch and working copy, from `commit` of `main` in the project's repo
-   * `repo`, unless they were made already. Returns the commit the branch forked from.
-   */
-  start({ repo, commit }: {
-    repo: string;
-    commit: string;
-  }): Promise<string>;
-  /**
-   * Makes the branch and working copy of a draft reverting a Publication, unless they were made
-   * already: forked from `commit`, the Publication's commit on `main`, with one commit on top,
-   * `message`, putting back the tree `main` had before it. Merging the current `main` then
-   * applies that undo to Live's latest code, as a merge of `main` into any draft (`mergeMain`):
-   * code a later publish changed since clashes as merges do. Returns whether `main` moved since
-   * `commit`, which a merge then brings in, or null, making nothing, when `commit` is `main`'s
-   * first: there's no code before it to put back.
-   */
-  startReverting({ repo, commit, message }: {
-    repo: string;
-    commit: string;
-    message: string;
-  }): Promise<{
-    mainMoved: boolean;
-  } | null>;
-  /** Runs one operation of the agent's environment on the working copy, and saves what it changed. */
-  call(call: EnvCall): Promise<EnvAnswer>;
-  /**
-   * The files that have merge conflict markers, as a merge of `main` that conflicts leaves them:
-   * only files the branch's head doesn't hold as they are, since no commit holds markers.
-   */
-  conflicts(): Promise<string[]>;
-  /**
-   * The paths of the working copy's files that differ from the commit `since`, added or changed
-   * since, without those deleted: since the branch's head when the working copy doesn't hold it,
-   * or without `since`.
-   */
-  changedFiles({ since }?: {
-    since?: string;
-  }): Promise<string[]>;
-  /**
-   * The working copy's files that installing its dependencies reads, as a tar archive, with its
-   * lockfile: what its sandbox needs to install ahead of a build, which `prepareCommit` would
-   * give only once it staged and committed every change.
-   */
-  installFiles(): Promise<Pick<PreparedCommit, "files" | "lockfile">>;
-  /**
-   * Stages the working copy's every change and makes, without moving the branch, the commit it
-   * would be: `message` on top of the branch's head. Returns the commit and its tree, with the
-   * tree's files as a tar archive, which a build streams into its sandbox, and the lockfile.
-   * Neither Git's directory nor the references mounted beside the files are in the tree.
-   */
-  prepareCommit({ message }: {
-    message: string;
-  }): Promise<PreparedCommit>;
-  /**
-   * Adds a member's pushed commits to the working copy, without moving the branch: the objects of
-   * `pack`, a bundle's packfile, which may build on the objects of `prerequisites`, commits of
-   * `main` fetched for it when the working copy doesn't hold them. A build then commits the
-   * pushed head (`commit`, with `checkout`).
-   */
-  receive({ pack, prerequisites }: {
-    pack: Uint8Array;
-    prerequisites: string[];
-  }): Promise<void>;
-  /**
-   * Moves the draft's branch to `commit`, which `prepareCommit` made, or a member pushed on top
-   * of the branch's head, and pushes it. A commit of the tree the branch's head already has, such
-   * as one prepared again after the push of the first, leaves the head as it is. With
-   * `checkout`, for a commit made beside the files, the files take its tree. A member's pushed
-   * head names `mergedMain`, the newest commit of `main` it holds, which the draft's next merge of
-   * `main` merges from. Returns the branch's head and its parents.
-   */
-  commit({ commit, checkout, mergedMain }: {
-    commit: string;
-    checkout?: boolean;
-    mergedMain?: string;
-  }): Promise<{
-    commit: string;
-    parents: string[];
-  }>;
-  /** Whether `commit` is the branch's head or one of its descendants: it includes the head. */
-  includesHead(commit: string): Promise<boolean>;
-  /**
-   * Pushes the draft's code to `main` as one squashed commit, as a publish lands: the tree of
-   * `commit`, a revision on the branch, with the current tip of `main` as its only parent. A
-   * `main` that already has that tree, as after a retried push that landed, is left as it is.
-   * Returns the commit `main` points to.
-   */
-  publishToMain({ commit, message }: {
-    commit: string;
-    message: string;
-  }): Promise<string>;
-  /**
-   * Merges the current `main` into the branch, without moving it: fetches `main` shallowly, its
-   * history down to the `main` commit the branch last merged or forked from, which is then the
-   * merge base, and merges it into the branch's head. A clean merge is returned as a merge commit
-   * whose parents are the head and `main`, for a build to commit (`commit`): the files stay as
-   * they are until then. A merge that conflicts changes nothing either.
-   *
-   * It waits while the files have changes no commit holds, and doesn't merge again a move of
-   * `main` that clashed. Files holding the merge of an earlier `main` that Camox's reconcile
-   * turn didn't fix (`merging`) are put back to the branch's head first, to merge this one.
-   */
-  mergeMain(): Promise<MergeOutcome>;
-  /** Deletes the draft's branch and everything the working copy stored, as the draft ends. */
-  delete(): Promise<void>;
-}
-//#endregion
-//#region ../../apps/api/src/domains/code-pushes/checks.d.ts
-/** Why a push was refused: each reason is a stable code the CLI and its users can rely on. */
-type PushRefusalReason =
-/** What was sent isn't a Git bundle of one branch's commits. */
-"invalidBundle" |
-/** The pushed tree changes a platform-owned file, which only Upgrades change. */
-"platformFile" |
-/** The pushed tree adds or changes a file under `src/` that isn't TypeScript or CSS. */
-"notCode" |
-/** `main` changed a platform-owned file since the branch last merged it. */
-"mergeMainFirst" |
-/** The branch starts from a commit that was never on `main`. */
-"baseNotOnMain" |
-/** The branch doesn't merge cleanly with the current `main`. */
-"conflictsWithMain" |
-/** The pushed head doesn't build. */
-"doesNotBuild" |
-/** The pushed head doesn't include the draft's current head. */
-"pullDraftFirst" |
-/** The draft the push names was published or deleted. */
-"draftEnded";
-type PushRefusal = {
-  reason: PushRefusalReason;
-  message: string;
-  data?: Record<string, unknown>;
-};
-/** A push that passed the checks: its head, as a commit to build, and what landing it needs. */
-type CheckedPush = {
-  /** The pushed head, as a commit to build. */
-  prepared: PreparedCommit;
-  /**
-   * The commits of `main` or of the draft's branch the pushed commits build on: the bundle's
-   * prerequisites.
-   */
-  prerequisites: string[];
-  /** The newest commit of `main` the pushed head holds, which a draft it opens forks from. */
-  base: string;
-  pack: Uint8Array;
-  /** The subject of each pushed commit, oldest first. */
-  subjects: string[];
-};
-//#endregion
-//#region ../../apps/api/src/domains/code-pushes/land.d.ts
-/** A push that passed its checks, as the draft it lands on receives it. */
-type CheckedLanding = CheckedPush & {
-  /** The project's Project ID, which names its repo. */
-  repo: string;
-};
-/** Whether the push landed, with its head's build, or why it was refused. */
-type Landing = {
-  refused: PushRefusal;
-} | {
-  result: BuildResult;
-};
-//#endregion
-//#region ../../apps/api/src/domains/revisions/merge.d.ts
-/** How a merge of `main` into a draft ended. */
-type MergeEnd =
-/** The draft holds the current `main`, or will once its changes are committed. */
-"upToDate" |
-/** A merge revision landed, built, and the draft previews it. */
-"merged" |
-/** The merge clashed: it's left for Camox's reconcile turn (`DraftCode.clash`), to start. */
-"clashed" |
-/** This move of `main` clashed already: Camox's reconcile turn had its one try. */
-"clashedBefore";
-//#endregion
-//#region ../../apps/api/src/domains/layouts/schema.d.ts
-/** Which collection a layout's record pages render, and the field they're found by. */
-type RecordPages = {
-  collectionId: string;
-  field: string;
-};
-//#endregion
-//#region ../../apps/api/src/domains/pages/schema.d.ts
-/**
- * A page. Live and every draft store pages side by side (ADR 0005), like blocks: a Live row has
- * no draft, a draft row is the draft's copy of a page, a page the draft created, or a tombstone.
- * An id is unique within each locale of Live and of each draft (ADR 0015). Read and write pages
- * through the draft overlay.
+ * A page. Live and every draft store pages side by side (ADR 0005), like blocks: a Live row has
+ * no draft, a draft row is the draft's copy of a page, a page the draft created, or a tombstone.
+ * An id is unique within each locale of Live and of each draft (ADR 0015). Read and write pages
+ * through the draft overlay.
  */
 declare const pages: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
   name: "pages";
@@ -1994,6 +1638,14 @@ type DraftRequest = {
 declare const ENTITY_KINDS: readonly ["locale", "page", "block", "sharedContent", "repeatableItem", "file", "record", "exclusion"];
 type EntityKind = (typeof ENTITY_KINDS)[number];
 //#endregion
+//#region ../../apps/api/src/domains/revisions/schema.d.ts
+/**
+ * What left a revision: the agent's `build`, the end of its turn, a merge of `main`, a
+ * member's `push` from their own checkout (ADR 0026), or the undo of a Publication's code
+ * starting the draft reverting it (ADR 0045).
+ */
+type RevisionSource = "build" | "turn" | "merge" | "push" | "revert";
+//#endregion
 //#region ../../apps/api/src/db.d.ts
 declare const schema: {
   projects: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
@@ -6831,7 +6483,14 @@ declare const schema: {
     dialect: 'sqlite';
   }>;
 };
-declare function createDb(d1: D1Database): DrizzleD1Database<typeof schema> & {
+/**
+ * A database on `d1` whose reads issued together share one round trip (`coalescingReads`). A
+ * database kept beyond one request must not: a batch would answer each request's reads from
+ * another's I/O. Pass `coalesce: false` for it.
+ */
+declare function createDb(d1: D1Database, { coalesce }?: {
+  coalesce?: boolean;
+}): DrizzleD1Database<typeof schema> & {
   $client: D1Database;
 };
 type Database = ReturnType<typeof createDb>;
@@ -10015,22 +9674,6 @@ declare class Thread extends DurableObject<Bindings> {
   readonly harness: UntilStartedPiHarness;
   readonly webSockets: WebSockets;
   readonly lifecycle: Lifecycle<object, object>;
-  /**
-   * Builds the code of the draft `draftId`, the thread's, in its build queue, as a publish of a
-   * head revision whose build is gone asks: the head's tree finds its revision, built again.
-   */
-  buildForPublish(draftId: string): Promise<BuildResult | null>;
-  /**
-   * Lands a member's checked push `push` on the thread's draft, in its build queue, as `pusher`
-   * pushed it (ADR 0026): once the agent's turn going, if any, made its last commit, and before
-   * the next message. Starts the thread, if nobody messaged it yet, so Camox's merges of `main`
-   * reach the draft. `waiting` hears that the push waits for the turn. A push that landed adds
-   * its entry to the thread: the agent reads it, and doesn't answer it.
-   */
-  landPush(push: CheckedLanding & {
-    identity: ThreadIdentity;
-    pusher: ThreadSender;
-  }, waiting?: () => Promise<void> | void): Promise<Landing>;
   /**
    * Adds the entry of a member's push that landed on the thread's draft, starting the thread if
    * nobody messaged it yet: who pushed, their commits, and how the pushed head built. The model
@@ -10043,31 +9686,10 @@ declare class Thread extends DurableObject<Bindings> {
     result: BuildResult;
   }): Promise<void>;
   /**
-   * Merges the current `main` into the thread's draft, when it has code, as a push to `main`
-   * asks: right away when the agent is idle, or else right after its turn's last commit, before
-   * the next message (`#onYield`). Nothing of it shows in the thread.
-   */
-  mergeMain(): Promise<MergeEnd | "afterTheTurn" | "noCode">;
-  /**
-   * Lands the undo of a Publication's code on the thread's draft, which reverts it (ADR 0045),
-   * starting the thread: the draft's branch, made by `DraftCode.startReverting`, holds the undo
-   * on top of the Publication's commit. When `main` moved since, its merge applies the undo to
-   * Live's latest code, a clash starting Camox's reconcile turn, as any merge of `main` does
-   * (ADR 0020). Otherwise the undo is built as the draft's revision. Either goes on in the
-   * background: the draft shows it's building, or not holding Live's code, until it lands.
-   */
-  revertCode({ identity, mainMoved }: {
-    identity: ThreadIdentity;
-    mainMoved: boolean;
-  }): Promise<void>;
-  /**
-   * Builds the code of the thread's draft, as the end of a turn would on its last try, when
-   * Camox's infrastructure failed the last build: changes that don't build are committed as a
-   * revision that isn't built, which blocks publishing. Nothing of it shows in the thread. A
-   * failure on Camox's side again owes the next retry. `busy` while the agent's turn runs: its
-   * end builds.
+   * Starts Camox's reconcile turn in the thread of the draft `identity` names, as a merge of
+   * `main` into its code clashed, starting the thread if nobody messaged it yet.
    */
-  retryBuild(): Promise<"built" | "failed" | "busy" | "noCode">;
+  reconcile(identity: ThreadIdentity): Promise<void>;
   /**
    * Lifecycle's alarm, which wakes Pi's runs, unless the thread ended: an alarm already on its
    * way when it did would look for the jobs its storage no longer has. A published draft's
@@ -10202,6 +9824,602 @@ declare class ProjectCode extends DurableObject<Bindings> {
   snapshot(known?: string): Promise<MainSnapshot>;
 }
 //#endregion
+//#region ../../apps/api/src/lib/timing.d.ts
+/** What a span's line says beside its name and duration. Undefined fields are left out. */
+type SpanFields = Record<string, string | number | boolean | null | undefined>;
+//#endregion
+//#region ../../apps/api/src/domains/revisions/sandbox.d.ts
+/** A type check's outcome, with what it printed: its errors when it failed. */
+type SandboxTypeCheck = {
+  ok: boolean;
+  output: string;
+};
+/**
+ * A build's outcome: its output as one gzipped tar archive, with the SDK Bundle it names (null
+ * for a whole-app build) and the type check of the same tree, which may still be running, or the
+ * log of its failure. Either way, `lint` has the findings of the lint that ran beside it: null
+ * when it was asked for none, or Camox couldn't lint.
+ */
+type SandboxBuild = {
+  lint: Promise<LintError[] | null>;
+} & ({
+  ok: true;
+  archive: Uint8Array;
+  sdkBundle: SdkBundleNames | null;
+  typeCheck: Promise<SandboxTypeCheck>;
+} | {
+  ok: false;
+  log: string;
+});
+//#endregion
+//#region ../../apps/api/src/domains/code-pushes/checks.d.ts
+/** Why a push was refused: each reason is a stable code the CLI and its users can rely on. */
+type PushRefusalReason =
+/** What was sent isn't a Git bundle of one branch's commits. */
+"invalidBundle" |
+/** The pushed tree changes a platform-owned file, which only Upgrades change. */
+"platformFile" |
+/** The pushed tree adds or changes a file under `src/` that isn't TypeScript or CSS. */
+"notCode" |
+/** `main` changed a platform-owned file since the branch last merged it. */
+"mergeMainFirst" |
+/** The branch starts from a commit that was never on `main`. */
+"baseNotOnMain" |
+/** The branch doesn't merge cleanly with the current `main`. */
+"conflictsWithMain" |
+/** The pushed head doesn't build. */
+"doesNotBuild" |
+/** The pushed head doesn't include the draft's current head. */
+"pullDraftFirst" |
+/** The draft the push names was published or deleted. */
+"draftEnded";
+type PushRefusal = {
+  reason: PushRefusalReason;
+  message: string;
+  data?: Record<string, unknown>;
+};
+/** A push that passed the checks: its head, as a commit to build, and what landing it needs. */
+type CheckedPush = {
+  /** The pushed head, as a commit to build. */
+  prepared: PreparedCommit;
+  /**
+   * The commits of `main` or of the draft's branch the pushed commits build on: the bundle's
+   * prerequisites.
+   */
+  prerequisites: string[];
+  /** The newest commit of `main` the pushed head holds, which a draft it opens forks from. */
+  base: string;
+  pack: Uint8Array;
+  /** The subject of each pushed commit, oldest first. */
+  subjects: string[];
+};
+//#endregion
+//#region ../../apps/api/src/domains/code-pushes/land.d.ts
+/** A push that passed its checks, as the draft it lands on receives it. */
+type CheckedLanding = CheckedPush & {
+  /** The project's Project ID, which names its repo. */
+  repo: string;
+};
+/** Whether the push landed, with its head's build, or why it was refused. */
+type Landing = {
+  refused: PushRefusal;
+} | {
+  result: BuildResult;
+};
+//#endregion
+//#region ../../apps/api/src/domains/code/remote-env.d.ts
+/** The operations sent as they are: every argument but the context is plain data. */
+declare const SENT: ["absolutePath", "joinPath", "readTextFile", "readTextLines", "readBinaryFile", "writeFile", "appendFile", "truncateFile", "flushFile", "renameFile", "fileInfo", "listDir", "canonicalPath", "exists", "createDir", "remove"];
+/** What a remote environment asks of the one it reaches. */
+type EnvCall = {
+  operation: (typeof SENT)[number];
+  args: unknown[];
+} |
+/** Opens a binary reader there and reads the whole file it opened. */
+{
+  operation: "openBinaryReader";
+  args: [path: string, options?: {
+    noFollow?: boolean;
+  }];
+};
+/** An operation's result as it crosses: its value, or its error as plain data. */
+type EnvAnswer = {
+  ok: true;
+  value: unknown;
+} | {
+  ok: false;
+  error: {
+    code: FileErrorCode;
+    message: string;
+    path?: string;
+  };
+};
+//#endregion
+//#region ../../apps/api/src/domains/revisions/build.d.ts
+/** What left a revision, and the thread run that did, if one did. */
+type RevisionOrigin = {
+  leftBy: RevisionSource;
+  run?: {
+    threadId: string;
+    runId: string;
+  };
+  /**
+   * The commit to build, made beside the working copy's files, such as a merge of `main`
+   * (`DraftCode.prepareMerge`) or a member's pushed head (`DraftCode.receive`). Without it, the
+   * build is of the files.
+   */
+  prepared?: PreparedCommit;
+  /**
+   * The build of `prepared` made already, which a push's checks make before anything is
+   * written: it's committed as it is rather than built again.
+   */
+  built?: Extract<SandboxBuild, {
+    ok: true;
+  }>;
+  /** For a member's pushed head, the newest commit of `main` it holds. */
+  mergedMain?: string;
+  /**
+   * The files whose lint findings the result lists, linted beside the build. A lint Camox can't
+   * run finds nothing: it never fails the build.
+   */
+  lint?: string[];
+};
+//#endregion
+//#region ../../apps/api/src/domains/revisions/end-of-turn.d.ts
+/** What the end of a turn did about the code the turn changed. */
+type TurnBuild =
+/** The turn's code already is a revision: nothing changed since the last one. */
+{
+  outcome: "unchanged";
+} | {
+  outcome: "built";
+  result: BuildResult;
+} |
+/**
+ * The turn's code builds, but lint found problems in the files it changed: the agent is handed
+ * `result` to fix them. Once it had them too often, the turn ends `built`, with them.
+ */
+{
+  outcome: "linted";
+  result: BuildResult;
+} |
+/** The build failed: the agent is handed `result` to fix it. */
+{
+  outcome: "failed";
+  result: BuildResult;
+} |
+/** The build failed once too often: the changes are committed anyway, as a revision not built. */
+{
+  outcome: "committedUnbuilt";
+  result: BuildResult;
+} |
+/**
+ * The changes built, committed, but had errors once too often: type errors, or definitions the
+ * draft can't use. They stay as they are.
+ */
+{
+  outcome: "keptErrors";
+  result: BuildResult;
+} |
+/**
+ * The build failed once too often, but its changes can't be committed as they are: the files
+ * hold a merge of Live's code that Camox's reconcile turn didn't fix, or conflict markers.
+ * Nothing is committed: `merging` says whether the files hold a merge.
+ */
+{
+  outcome: "uncommitted";
+  result: BuildResult;
+  merging: boolean;
+};
+/**
+ * Builds what a turn changed in the code of the draft `draftId`, which has code, as the turn
+ * ends: whatever changed since its last revision, nothing when the agent's last `build` already
+ * covered it without errors. A passing build leaves a revision, even with type errors. A build
+ * fails when it, its type check or its definitions have errors. `failedInARow` is how many
+ * end-of-turn builds of this turn failed before this one: once this one makes
+ * `END_OF_TURN_BUILD_FAILURES`, changes that didn't build are committed anyway, as a revision
+ * that isn't built, and ones that did stay with their errors. `building` runs before a build
+ * starts.
+ *
+ * The files the turn changed since `base`, the commit its code was at as it started, are linted
+ * too, beside the build, or alone when the agent's builds covered its changes: findings in code
+ * that builds hand the agent a `linted` result, and count as a failure, and the findings of a
+ * build that fails come with its errors. Lint never fails a build, and the turn ends with
+ * findings it had once too often.
+ */
+declare function buildAtEndOfTurn(env: Bindings, draftId: string, { run, failedInARow, building, base }: {
+  run?: RevisionOrigin["run"];
+  failedInARow: number;
+  building: () => Promise<void>;
+  base?: string;
+}): Promise<TurnBuild>;
+//#endregion
+//#region ../../apps/api/src/domains/revisions/merge.d.ts
+/** How a merge of `main` into a draft ended. */
+type MergeEnd =
+/** The draft holds the current `main`, or will once its changes are committed. */
+"upToDate" |
+/** A merge revision landed, built, and the draft previews it. */
+"merged" |
+/** The merge clashed: it's left for Camox's reconcile turn (`DraftCode.clash`), to start. */
+"clashed" |
+/** This move of `main` clashed already: Camox's reconcile turn had its one try. */
+"clashedBefore";
+//#endregion
+//#region ../../apps/api/src/domains/revisions/code-queue.d.ts
+/** What the code queue asks of the draft's thread. */
+type DraftThread = {
+  /** Whether the agent is mid-turn in the draft's thread. */
+  turnGoing(): Promise<boolean>;
+  /** Starts Camox's turn reconciling the draft's code with Live's, whose merge clashed. */
+  reconcile(): Promise<void>;
+};
+/** What the code queue needs of the `DraftCode` holding it. */
+type CodeQueueHost = {
+  env: Bindings;
+  storage: DurableObjectStorage;
+  draftId: () => string;
+  /** Whether the draft has code. */
+  held: () => boolean;
+  /** The files its sandbox installs from, ahead of a build (`DraftCode.installFiles`). */
+  installFiles: () => Promise<Pick<PreparedCommit, "files" | "lockfile">>;
+  thread: () => DraftThread;
+  waitUntil: (promise: Promise<unknown>) => void;
+};
+/** The draft's code queue (see above), for its `DraftCode` to answer with. */
+declare class CodeQueue {
+  #private;
+  constructor(host: CodeQueueHost);
+  /** Builds the files as a revision, as the agent's `build` or a publish asks. None without code. */
+  build({ run }?: {
+    run?: RevisionOrigin["run"];
+  }): Promise<BuildResult | null>;
+  /**
+   * Builds what the agent's turn changed, as it ends (`buildAtEndOfTurn`). A build Camox's
+   * infrastructure failed is owed, and retried later: the turn ends on it.
+   */
+  buildAtTurnEnd(turn: Omit<Parameters<typeof buildAtEndOfTurn>[2], "building"> & {
+    building: () => Promise<void> | void;
+  }): Promise<TurnBuild | {
+    outcome: "owed";
+  }>;
+  /**
+   * Starts the draft's sandbox and installs its dependencies, in the queue, so the next build
+   * finds them. Doesn't count as building.
+   */
+  warmSandbox(span: SpanFields): Promise<void>;
+  /**
+   * Merges the current `main` into the draft, as a push to `main` asks: right away unless the
+   * agent is mid-turn, or else once its turn ended (`turnEnded`).
+   */
+  mergeMain(): Promise<MergeEnd | "afterTheTurn" | "noCode">;
+  /**
+   * Lands the member's checked push `push`, once the agent's turn going, if any, made its last
+   * commit. `waiting` hears that it waits for the turn.
+   */
+  landPush(push: CheckedLanding, waiting?: () => Promise<void> | void): Promise<Landing>;
+  /**
+   * Lands what waited for the agent's turn, as it ends: the merge of the `main` that moved
+   * during it, then the members' pushes, one after the other.
+   */
+  turnEnded(): Promise<void>;
+  /**
+   * Lands the undo of a Publication's code, which `DraftCode.startReverting` put on the
+   * draft's branch, in the background: merged with Live's latest code when `main` moved since,
+   * or else built as the draft's revision. The draft shows it's building from now, so a publish
+   * asked meanwhile waits for it.
+   */
+  landRevert({ mainMoved }: {
+    mainMoved: boolean;
+  }): void;
+  /** Waits for the merge of `main` or the member's push landing now, if any: it lands beside the files. */
+  untilLanded(): Promise<void>;
+  /**
+   * Whether a build of the draft's code is going (see `BUILD_GOING_FOR_AT_MOST_MS`), or owed:
+   * Camox's infrastructure failed the last one, and Camox retries it. A type check, going or
+   * owed, isn't building (ADR 0043).
+   */
+  building(): boolean;
+  /**
+   * Records that the build going ended, or is previewed, its type check going on: the draft no
+   * longer shows it's building, and a publish waiting for it ships what it left.
+   */
+  buildEnded(): Promise<void>;
+  /**
+   * Retries the build Camox owes the draft, as the end of a turn would on its last try: changes
+   * that don't build are committed as a revision that isn't built. A turn going builds at its
+   * end, so the retry waits for the next one.
+   */
+  retryOwed(): Promise<void>;
+}
+//#endregion
+//#region ../../apps/api/src/durable-objects/draft-code.d.ts
+/** A revision of the draft whose build goes up as its publish script. */
+type PublishUpload = {
+  /** The project's Project ID. */
+  project: string;
+  revision: string;
+  /** Its build in `REVISION_BUILDS`. */
+  archiveKey: string;
+};
+/** A commit `prepareCommit` made, not on the branch yet. */
+type PreparedCommit = {
+  commit: string;
+  tree: string;
+  /** The tree's files, as a tar archive. */
+  files: Uint8Array;
+  /** The tree's `pnpm-lock.yaml`, if it has one. */
+  lockfile: string | null;
+};
+/**
+ * A merge of `main` that doesn't land as a revision as it is: it conflicts, or its tree doesn't
+ * build or type check. Recorded for Camox's reconcile turn, which tries once for each move of
+ * `main`, until code holding that `main` builds without errors (`settleClash`): the draft has
+ * the "doesn't merge with Live's" blocker until then.
+ */
+type MergeClash = {
+  /** The commit of `main` that clashed. */
+  main: string;
+  /** The files both sides changed in ways that don't merge, for a merge that conflicts. */
+  conflicts?: string[];
+  /** The merged tree's build, for a merge that doesn't build or type check. */
+  result?: BuildResult;
+};
+/** What merging `main` into the working copy found. */
+type MergeOutcome =
+/** The draft holds the current `main` already. */
+{
+  outcome: "upToDate";
+} |
+/** The working copy has changes no revision holds yet: the merge waits for them. */
+{
+  outcome: "unsettled";
+} |
+/** This move of `main` clashed already, and isn't merged again until `main` moves again. */
+{
+  outcome: "clashedBefore";
+  main: string;
+} | {
+  outcome: "conflicts";
+  main: string;
+  conflicts: string[];
+} |
+/** A merge commit of `main`, not on the branch yet, for a build to commit. */
+{
+  outcome: "merged";
+  main: string;
+  prepared: PreparedCommit;
+};
+/**
+ * The working copy of one draft with code, addressed by the draft's ID (`getByName`): a depth-1
+ * clone of the draft's branch, held in memory, which the agent's code tools read and write over
+ * RPC, through the write line. Every change is saved to its SQLite as it's made, Git's own
+ * directory included, so an eviction restores it without cloning again. The skills of its `camox`
+ * version are mounted beside the files and never saved, nor committed.
+ *
+ * It stores nothing until `start` made it, and nothing once `delete` deleted it.
+ */
+declare class DraftCode extends DurableObject<Bindings> {
+  #private;
+  /** Whether the draft has code: its branch was made, and not deleted since. */
+  held(): Promise<boolean>;
+  /**
+   * The commit of `main` the draft's code holds: the one its branch last merged, or forked from,
+   * once it has code.
+   */
+  mergedMain(): Promise<string | undefined>;
+  /**
+   * Where the draft's merges of `main` stand: the branch's head, the `main` it holds, and the
+   * last merge that clashed, read at once, as a commit moves them together.
+   */
+  merges(): Promise<{
+    head: string;
+    mergedMain: string;
+    clash: MergeClash | undefined;
+  }>;
+  /** The last merge of `main` that clashed, until a merge of `main` lands. */
+  clash(): Promise<MergeClash | undefined>;
+  /**
+   * Records that the merge of `main` at `clash.main` clashed (see `MergeClash`), for Camox's
+   * reconcile turn. A merge that didn't land is left in the files, uncommitted, conflict markers
+   * included, and the next revision is its merge commit: see `merging`.
+   */
+  recordClash(clash: MergeClash): Promise<void>;
+  /**
+   * The commit of `main` whose merge the files hold, uncommitted, if they do: Camox's reconcile
+   * turn fixes it, and its build commits the merge commit.
+   */
+  merging(): Promise<string | undefined>;
+  /**
+   * Forgets the clash, once the draft's code built without errors and holds the `main` that
+   * clashed: unless the files still hold a merge no commit landed.
+   */
+  settleClash(): Promise<void>;
+  /**
+   * Uploads the build of the draft's revision `revision` as the draft's publish script, ahead of
+   * its publish, unless the script holds it already: its publish then only checks it's there
+   * (`uploadForPublish`). Nothing once a publish took the script, until that publish ends, nor
+   * once the draft ended. A draft that ended during the upload, deleted, loses the script.
+   */
+  prepareUpload(toUpload: PublishUpload): Promise<void>;
+  /**
+   * The draft's publish script holding the build of `revision`, which the publish `instanceId`
+   * ships, taking it: no upload ahead replaces it until that publish ends. Uploads it unless the
+   * script holds it already, as the upload ahead left it. Returns its name, and whether this
+   * uploaded it.
+   */
+  uploadForPublish(toUpload: PublishUpload, instanceId: string, span?: SpanFields): Promise<{
+    script: string;
+    uploaded: boolean;
+  }>;
+  /** The publish of the draft going now, if any: its Workflow instance. */
+  publishGoing(): Promise<string | null>;
+  /**
+   * Records that a member's push landed during the publish `instanceId`: the revision it waits
+   * for a build to leave changed under it, so it goes back to the review (ADR 0043).
+   */
+  notePushDuring(instanceId: string): Promise<void>;
+  /** Whether a member's push landed during the publish `instanceId`. */
+  pushedDuring(instanceId: string): Promise<boolean>;
+  /**
+   * The draft's thread, as its code queue asks it whether a turn is going: the one the draft's
+   * row names. Tests put a fake in its place.
+   */
+  draftThread: DraftThread;
+  /** Builds the files as a revision, as the agent's `build` or a publish asks. None without code. */
+  build(options?: Parameters<CodeQueue["build"]>[0]): Promise<BuildResult | null>;
+  /**
+   * Builds what the agent's turn changed, as it ends: `building` runs before a build starts. A
+   * build Camox's infrastructure failed is owed, and retried later: the turn ends on it.
+   */
+  buildAtTurnEnd(turn: Parameters<CodeQueue["buildAtTurnEnd"]>[0]): Promise<TurnBuild | {
+    outcome: "owed";
+  }>;
+  /** Starts the draft's sandbox ahead of its next build, in the queue. */
+  warmSandbox(span: SpanFields): Promise<void>;
+  /**
+   * Merges the current `main` into the draft, as a push to `main` asks: right away unless the
+   * agent is mid-turn, or else once its turn ended (`turnEnded`). Nothing of it shows in the
+   * thread, unless it clashes: Camox's reconcile turn then starts there.
+   */
+  mergeMain(): Promise<MergeEnd | "afterTheTurn" | "noCode">;
+  /**
+   * Lands a member's checked push on the draft (ADR 0026), once the agent's turn going, if any,
+   * made its last commit. `waiting` hears that the push waits for the turn. A draft without
+   * code gets its branch from the push.
+   */
+  landPush(push: CheckedLanding, waiting?: () => Promise<void> | void): Promise<Landing>;
+  /** Lands what waited for the agent's turn, as it ends: a merge of `main`, then pushes. */
+  turnEnded(): Promise<void>;
+  /**
+   * Lands the undo of a Publication's code, which `startReverting` made, in the background
+   * (ADR 0045). The draft shows it's building from now, so its publish waits for it.
+   */
+  landRevert({ mainMoved }: {
+    mainMoved: boolean;
+  }): Promise<void>;
+  /** Waits for the merge of `main` or the push landing now, if any: code writes wait for it. */
+  untilLanded(): Promise<void>;
+  /**
+   * Whether a build of the draft's code is going, or owed: Camox's infrastructure failed the
+   * last one, and Camox retries it. A type check, going or owed, isn't building (ADR 0043).
+   */
+  building(): Promise<boolean>;
+  /**
+   * Records that the build going is previewed: the draft no longer shows it's building, though
+   * its type check goes on.
+   */
+  buildPreviewed(): Promise<void>;
+  /** Retries the build Camox owes the draft, until one lands. */
+  alarm(): Promise<void>;
+  /**
+   * Makes the draft's branch and working copy, from `commit` of `main` in the project's repo
+   * `repo`, unless they were made already. Returns the commit the branch forked from.
+   */
+  start({ repo, commit }: {
+    repo: string;
+    commit: string;
+  }): Promise<string>;
+  /**
+   * Makes the branch and working copy of a draft reverting a Publication, unless they were made
+   * already: forked from `commit`, the Publication's commit on `main`, with one commit on top,
+   * `message`, putting back the tree `main` had before it. Merging the current `main` then
+   * applies that undo to Live's latest code, as a merge of `main` into any draft (`prepareMerge`):
+   * code a later publish changed since clashes as merges do. Returns whether `main` moved since
+   * `commit`, which a merge then brings in, or null, making nothing, when `commit` is `main`'s
+   * first: there's no code before it to put back.
+   */
+  startReverting({ repo, commit, message }: {
+    repo: string;
+    commit: string;
+    message: string;
+  }): Promise<{
+    mainMoved: boolean;
+  } | null>;
+  /** Runs one operation of the agent's environment on the working copy, and saves what it changed. */
+  call(call: EnvCall): Promise<EnvAnswer>;
+  /**
+   * The files that have merge conflict markers, as a merge of `main` that conflicts leaves them:
+   * only files the branch's head doesn't hold as they are, since no commit holds markers.
+   */
+  conflicts(): Promise<string[]>;
+  /**
+   * The paths of the working copy's files that differ from the commit `since`, added or changed
+   * since, without those deleted: since the branch's head when the working copy doesn't hold it,
+   * or without `since`.
+   */
+  changedFiles({ since }?: {
+    since?: string;
+  }): Promise<string[]>;
+  /**
+   * The working copy's files that installing its dependencies reads, as a tar archive, with its
+   * lockfile: what its sandbox needs to install ahead of a build, which `prepareCommit` would
+   * give only once it staged and committed every change.
+   */
+  installFiles(): Promise<Pick<PreparedCommit, "files" | "lockfile">>;
+  /**
+   * Stages the working copy's every change and makes, without moving the branch, the commit it
+   * would be: `message` on top of the branch's head. Returns the commit and its tree, with the
+   * tree's files as a tar archive, which a build streams into its sandbox, and the lockfile.
+   * Neither Git's directory nor the references mounted beside the files are in the tree.
+   */
+  prepareCommit({ message }: {
+    message: string;
+  }): Promise<PreparedCommit>;
+  /**
+   * Adds a member's pushed commits to the working copy, without moving the branch: the objects of
+   * `pack`, a bundle's packfile, which may build on the objects of `prerequisites`, commits of
+   * `main` fetched for it when the working copy doesn't hold them. A build then commits the
+   * pushed head (`commit`, with `checkout`).
+   */
+  receive({ pack, prerequisites }: {
+    pack: Uint8Array;
+    prerequisites: string[];
+  }): Promise<void>;
+  /**
+   * Moves the draft's branch to `commit`, which `prepareCommit` made, or a member pushed on top
+   * of the branch's head, and pushes it. A commit of the tree the branch's head already has, such
+   * as one prepared again after the push of the first, leaves the head as it is. With
+   * `checkout`, for a commit made beside the files, the files take its tree. A member's pushed
+   * head names `mergedMain`, the newest commit of `main` it holds, which the draft's next merge of
+   * `main` merges from. Returns the branch's head and its parents.
+   */
+  commit({ commit, checkout, mergedMain }: {
+    commit: string;
+    checkout?: boolean;
+    mergedMain?: string;
+  }): Promise<{
+    commit: string;
+    parents: string[];
+  }>;
+  /** Whether `commit` is the branch's head or one of its descendants: it includes the head. */
+  includesHead(commit: string): Promise<boolean>;
+  /**
+   * Pushes the draft's code to `main` as one squashed commit, as a publish lands: the tree of
+   * `commit`, a revision on the branch, with the current tip of `main` as its only parent. A
+   * `main` that already has that tree, as after a retried push that landed, is left as it is.
+   * Returns the commit `main` points to.
+   */
+  publishToMain({ commit, message }: {
+    commit: string;
+    message: string;
+  }): Promise<string>;
+  /**
+   * Merges the current `main` into the branch, without moving it: fetches `main` shallowly, its
+   * history down to the `main` commit the branch last merged or forked from, which is then the
+   * merge base, and merges it into the branch's head. A clean merge is returned as a merge commit
+   * whose parents are the head and `main`, for a build to commit (`commit`): the files stay as
+   * they are until then. A merge that conflicts changes nothing either.
+   *
+   * It waits while the files have changes no commit holds, and doesn't merge again a move of
+   * `main` that clashed. Files holding the merge of an earlier `main` that Camox's reconcile
+   * turn didn't fix (`merging`) are put back to the branch's head first, to merge this one.
+   */
+  prepareMerge(): Promise<MergeOutcome>;
+  /** Deletes the draft's branch and everything the working copy stored, as the draft ends. */
+  delete(): Promise<void>;
+}
+//#endregion
 //#region ../../apps/api/src/domains/project-creation/workflow.d.ts
 type ProjectCreationParams = {
   /** The new project's Project ID, which names its repo. */
@@ -10388,7 +10606,7 @@ type Dispatch = {
    * `archive` when the API sends it, as it does while it stores it, or else from R2:
    * dispatch serves its client assets from then on, and has loaded and rendered it once. Returns
    * its Definition Set (JSON, not yet checked), with what each part took, for the API's timing
-   * logs.
+   * logs. Fails as `REVISION_CODE_THREW` says when the revision's own code throws.
    */
   prepare(revision: RevisionToLoad, archive?: Uint8Array): Promise<PreparedRevision>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camox/api-contract",
-  "version": "0.76.0",
+  "version": "0.76.1",
   "license": "MIT",
   "files": [
     "src",