@glw907/cairn-cms 0.62.2 → 0.76.0

package/src/lib/delivery/site-descriptors.ts

@@ -1,11 +1,16 @@
 // cairn-cms: the one-call descriptor helper. A delivery site needs the same per-concept descriptors
 // the admin runtime uses; this delegates to the shared resolveConcepts so the pairing is one path, not
-// tribal knowledge. The YAML URL policy stays the single source of truth.
+// tribal knowledge. Each concept declares its own routing and URL policy, the single source of truth.
 import { resolveConcepts } from '../content/concepts.js';
 import type { CairnAdapter, ConceptDescriptor } from '../content/types.js';
 import type { SiteConfig } from '../nav/site-config.js';
 
-/** Per-concept descriptors for a site, from its adapter content and its parsed site config. */
+/**
+ * Per-concept descriptors for a site, from its adapter content. The `siteConfig` parameter is retained
+ *  for API stability and the menus and site name it still carries; the URL policy now lives on each
+ *  concept, so it is not read here.
+ */
 export function siteDescriptors(adapter: CairnAdapter, siteConfig: SiteConfig): ConceptDescriptor[] {
-  return resolveConcepts(adapter.content, siteConfig);
+  void siteConfig;
+  return resolveConcepts(adapter.content);
 }

package/src/lib/delivery/site-indexes.ts

@@ -5,7 +5,7 @@
 // lower-level escape hatch. It imports only pure content and delivery code, so the delivery
 // bundle stays backend-free.
 import type { CairnAdapter, ConceptConfig } from '../content/types.js';
-import type { Infer } from '../content/schema.js';
+import type { InferFieldset } from '../content/fieldset.js';
 import type { SiteConfig } from '../nav/site-config.js';
 import { siteDescriptors } from './site-descriptors.js';
 import { createContentIndex, fromGlob } from './content-index.js';
@@ -24,7 +24,7 @@ export type SiteGlobs<A extends CairnAdapter> = {
  */
 export type SiteIndexes<A extends CairnAdapter> = {
   [K in keyof A['content']]: ContentIndex<
-    NonNullable<A['content'][K]> extends ConceptConfig<infer S> ? Infer<S> : Record<string, unknown>
+    NonNullable<A['content'][K]> extends ConceptConfig<infer S> ? InferFieldset<S> : Record<string, unknown>
   >;
 } & { readonly site: SiteResolver };
 

package/src/lib/delivery/site-resolver.ts

@@ -6,6 +6,7 @@
 import type { ConceptDescriptor } from '../content/types.js';
 import type { ContentEntry, ContentIndex, ContentSummary } from './content-index.js';
 import type { LinkResolve } from '../content/links.js';
+import { extractReferenceEdges, type ReferenceEdge } from '../content/references.js';
 
 /** One concept's descriptor paired with its built index. */
 export interface ConceptIndex {
@@ -93,6 +94,69 @@ export function createSiteResolver(concepts: ConceptIndex[], opts: { validate?:
   };
 }
 
+/**
+ * A reference edge resolved to its target's identity, for a public route to render a linked target.
+ *  It reuses the target entry's own summary fields rather than re-deriving them, so a linked author
+ *  card reads the same title and permalink the target's own page does. `summary` is the target's
+ *  excerpt when present.
+ */
+export interface ResolvedReference {
+  id: string;
+  concept: string;
+  title: string;
+  permalink: string;
+  summary?: string;
+}
+
+/** Project a resolved target entry into the identity a public route renders for a reference. */
+function projectReference(edge: ReferenceEdge, target: ContentSummary): ResolvedReference {
+  const resolved: ResolvedReference = {
+    id: edge.id,
+    concept: edge.concept,
+    title: target.title,
+    permalink: target.permalink,
+  };
+  if (target.excerpt) resolved.summary = target.excerpt;
+  return resolved;
+}
+
+/**
+ * Resolve a concept's `reference` and `array(reference)` frontmatter edges to their target identities,
+ * keyed by the field name, so a public route renders a reference as a link to its target's page. The
+ * resolution lives here because only the cross-concept resolver reaches a different concept's entries:
+ * a posts entry's `author` edge targets a pages entry, which the posts index alone cannot read. A
+ * single `reference` field resolves to one `ResolvedReference`, an `array(reference)` to a
+ * `ResolvedReference[]` in edge order. An id with no live target is dropped rather than thrown: the
+ * build's `verifyReferences` gate already fails a true dangling edge, so an unresolved id at request
+ * time is a mid-flight or draft target, not a hard error. Resolve per call, since the target entries
+ * exist only after every per-concept index is unioned into the resolver.
+ */
+export function resolveReferences(
+  site: SiteResolver,
+  descriptor: ConceptDescriptor,
+  frontmatter: Record<string, unknown>,
+): Record<string, ResolvedReference | ResolvedReference[]> {
+  const edges = extractReferenceEdges(frontmatter, descriptor.fields);
+  const resolved: Record<string, ResolvedReference | ResolvedReference[]> = {};
+  for (const field of descriptor.fields) {
+    const isSingle = field.type === 'reference';
+    const isArray = field.type === 'array' && field.item.type === 'reference';
+    if (!isSingle && !isArray) continue;
+    const fieldEdges = edges.filter((edge) => edge.field === field.name);
+    const hits: ResolvedReference[] = [];
+    for (const edge of fieldEdges) {
+      const target = site.concept(edge.concept)?.byId(edge.id);
+      if (target) hits.push(projectReference(edge, target));
+    }
+    if (isSingle) {
+      if (hits.length > 0) resolved[field.name] = hits[0];
+    } else {
+      resolved[field.name] = hits;
+    }
+  }
+  return resolved;
+}
+
 /**
  * A resolver backed by the site resolver, for the build. A miss throws, so a dangling cairn: token
  *  fails the prerender (the build backstop). The preview uses manifestLinkResolver, which marks.

package/src/lib/doctor/checks-local.ts

@@ -5,11 +5,8 @@ import { fail, pass, skip } from './types.js';
 import type { CheckResult, DoctorCheck, DoctorContext } from './types.js';
 import { readWranglerConfig } from './wrangler-config.js';
 import { requireOrigin } from '../env.js';
-import { parseSiteConfig, urlPolicyFrom } from '../nav/site-config.js';
+import { parseSiteConfig } from '../nav/site-config.js';
 import type { SiteConfig } from '../nav/site-config.js';
-import { normalizeConcepts } from '../content/concepts.js';
-import { defineFields } from '../content/schema.js';
-import type { ConceptConfig } from '../content/types.js';
 
 const NO_WRANGLER: CheckResult = skip('no wrangler.jsonc or wrangler.toml found');
 
@@ -156,16 +153,11 @@ export const configSiteConfig: DoctorCheck = {
 		const text = await readSiteConfigText(ctx);
 		if (text === null) return skip(`no site.config.yaml found (looked in ${SITE_CONFIG_PATHS.join(', ')})`);
 		try {
-			const policy = urlPolicyFrom(parseSiteConfig(text));
-			// Run the engine's own URL-policy validation by declaring a synthetic empty concept
-			// per policy key. Routing is concept-fixed in the engine (CONCEPT_ROUTING, never the
-			// adapter), so the dated rules apply faithfully here. What a CLI cannot check without
-			// evaluating the adapter is whether each policy key names a concept the site declares.
-			const synthetic = Object.fromEntries(
-				Object.keys(policy).map((id): [string, ConceptConfig] => [id, { dir: '', schema: defineFields([]) }])
-			);
-			normalizeConcepts(synthetic, policy);
-			return pass('parsed and URL policy validated (the adapter concept set is not checkable from the CLI)');
+			// Parse-only. parseSiteConfig validates the root shape and, since Contract v2, hard-errors on a
+			// stale per-concept `content:` block (URL policy moved onto defineConcept). The per-concept URL
+			// policy is now validated at the concept declaration, which a CLI cannot reach without the adapter.
+			parseSiteConfig(text);
+			return pass('parsed (per-concept URL policy lives on the adapter concepts, not checkable from the CLI)');
 		} catch (err) {
 			return fail(err instanceof Error ? err.message : String(err));
 		}

package/src/lib/github/backend.ts

@@ -0,0 +1,161 @@
+// cairn-cms: the Backend seam. A Backend is read, commit, and branch operations over files,
+// never a query(): that line is the constraint that keeps a store swappable and a database out.
+// The adapter holds a BackendProvider from githubApp(...); the engine resolves one live Backend
+// per request via connect(env), with the GitHub App installation token minted and cached behind
+// the seam. makeGithubBackend takes an injectable token getter so a test wires a literal token and
+// the in-memory fetch double intercepts the same GitHub URLs the production getter would reach.
+import { readRaw, listMarkdown, commitFiles } from './repo.js';
+import type { FileChange } from './repo.js';
+import { branchHeadSha, createBranch as createBranchRef, deleteBranch, listBranches } from './branches.js';
+import { appCredentials } from './credentials.js';
+import type { BackendEnv } from './credentials.js';
+import { cachedInstallationToken } from './signing.js';
+import { CommitConflictError } from './types.js';
+import type { CommitAuthor, RepoFile } from './types.js';
+
+// One BackendEnv declaration lives in credentials.js (the secret-channel owner). Re-export it here so
+// the seam and connect() name the same type the public root surfaces, with no duplicate declaration.
+export type { BackendEnv };
+
+/**
+ * A live, connected content store pinned to a default branch. The GitHub implementation already
+ * holds a minted token behind it; the engine resolves one per request. Read, commit, and branch
+ * over files only: this interface never grows a query() method.
+ */
+export interface Backend {
+  /** The site's default branch, for example "main". Callers reading published state pass it as the ref. */
+  readonly defaultBranch: string;
+
+  /** Raw file contents at a ref, or null when the path does not exist. */
+  readFile(path: string, ref: string): Promise<string | null>;
+
+  /** The markdown entries directly in a concept directory at a ref, newest id first. */
+  readEntries(dir: string, ref: string): Promise<RepoFile[]>;
+
+  /** A branch's head commit sha, or null when the branch does not exist. */
+  branchHead(branch: string): Promise<string | null>;
+
+  /** Branch names under a prefix, sorted. */
+  listBranches(prefix: string): Promise<string[]>;
+
+  /**
+   * Commit a set of path changes atomically on a branch; returns the new commit sha. When
+   * `expectedHead` is given the commit is fail-closed: it makes one attempt and throws
+   * CommitConflictError if the branch head is not `expectedHead`. Omitting it keeps the head-merge
+   * retry the entry and publish paths rely on.
+   */
+  commit(
+    branch: string,
+    changes: FileChange[],
+    author: CommitAuthor,
+    message: string,
+    expectedHead?: string,
+  ): Promise<string>;
+
+  /** Create a branch at another branch's current head. */
+  createBranch(name: string, fromBranch: string): Promise<void>;
+
+  /** Delete a branch; a missing branch is success. */
+  deleteBranch(name: string): Promise<void>;
+}
+
+/** The adapter's backend value: a provider that connect()s to a live Backend given the Worker env. */
+export interface BackendProvider {
+  /** A stable tag for the implementation, for example "github-app". The non-request readers narrow on it. */
+  readonly kind: string;
+  /** The default branch, surfaced before connect() so compose-time code can read it. */
+  readonly branch: string;
+  /** Connect to a live Backend; the GitHub implementation mints and caches its token lazily. */
+  connect(env: BackendEnv): Backend;
+}
+
+/** What githubApp() returns: the generic provider plus the GitHub App's non-secret identity facts. */
+export interface GithubAppProvider extends BackendProvider {
+  readonly kind: 'github-app';
+  readonly owner: string;
+  readonly repo: string;
+  readonly appId: string;
+  readonly installationId: string;
+}
+
+/**
+ * Narrow a provider to the GitHub App provider on its `kind` tag. The non-request readers (the
+ * health self-test, the build-time facts) call this before reading the GitHub-specific identity,
+ * since `BackendProvider.kind` is a bare string the compiler cannot narrow on its own.
+ */
+export function isGithubApp(provider: BackendProvider): provider is GithubAppProvider {
+  return provider.kind === 'github-app';
+}
+
+/** The non-secret GitHub App identity an adapter carries in source; the private key stays a Worker secret. */
+interface GithubAppConfig {
+  owner: string;
+  repo: string;
+  branch: string;
+  appId: string;
+  installationId: string;
+}
+
+/**
+ * The live GitHub Backend over the existing repo.ts and branches.ts transports. The token getter
+ * is injected rather than the env: connect() wires the production getter that mints and caches the
+ * installation token, and a unit test wires a literal so the in-memory fetch double intercepts the
+ * same GitHub URLs. Not barrel-exported; it is the internal test seam imported by path.
+ */
+export function makeGithubBackend(config: GithubAppConfig, getToken: () => string | Promise<string>): Backend {
+  return {
+    defaultBranch: config.branch,
+    async readFile(path, ref) {
+      return readRaw({ ...config, branch: ref }, path, await getToken());
+    },
+    async readEntries(dir, ref) {
+      return listMarkdown({ ...config, branch: ref }, dir, await getToken());
+    },
+    async branchHead(branch) {
+      return branchHeadSha(config, branch, await getToken());
+    },
+    async listBranches(prefix) {
+      return listBranches(config, prefix, await getToken());
+    },
+    async commit(branch, changes, author, message, expectedHead) {
+      return commitFiles({ ...config, branch }, changes, { message, author }, await getToken(), expectedHead);
+    },
+    async createBranch(name, fromBranch) {
+      const tok = await getToken();
+      const head = await branchHeadSha(config, fromBranch, tok);
+      // A null head means the source branch is gone or unreadable. Throw a defined, catchable
+      // error the save path maps to its 500 rather than letting the createBranchRef POST fail raw.
+      if (head === null) throw new CommitConflictError(`${fromBranch} (unreadable source)`);
+      await createBranchRef(config, name, head, tok);
+    },
+    async deleteBranch(name) {
+      await deleteBranch(config, name, await getToken());
+    },
+  };
+}
+
+/**
+ * The default content backend: a GitHub App over a repo branch. Returns a provider carrying the
+ * App's non-secret identity (so the build-time, health, and doctor readers narrow on kind and read
+ * it) whose connect(env) mints and caches the installation token from the Worker's private-key
+ * secret. The missing-secret CairnError stays on first token use, inside connect.
+ */
+export function githubApp(config: {
+  owner: string;
+  repo: string;
+  branch: string;
+  appId: string;
+  installationId: string;
+}): GithubAppProvider {
+  return {
+    kind: 'github-app',
+    branch: config.branch,
+    owner: config.owner,
+    repo: config.repo,
+    appId: config.appId,
+    installationId: config.installationId,
+    connect(env) {
+      return makeGithubBackend(config, () => cachedInstallationToken(appCredentials(config, env)));
+    },
+  };
+}

package/src/lib/github/credentials.ts

@@ -3,22 +3,25 @@
 // save action (Plan 05) stays thin and a misconfigured Worker fails by name, not with a deep
 // TypeError. Mirrors requireDb/requireOrigin in env.ts.
 import { CairnError } from '../diagnostics/index.js';
-import type { BackendConfig } from '../content/types.js';
 import type { AppCredentials } from './types.js';
 
-/** The Worker secret holding the GitHub App private key: base64 of the PEM, single line. */
-export interface GithubKeyEnv {
+/**
+ * The Worker secret carrier `Backend.connect` reads: the GitHub App private key as base64 of the
+ * PEM, single line. A consumer's `App.Platform.env` block names it. Aliased as the engine's
+ * `BackendEnv` since the backend seam owns the secret channel.
+ */
+export interface BackendEnv {
   GITHUB_APP_PRIVATE_KEY_B64?: string;
 }
 
 /**
- * Assemble the `AppCredentials` the signer needs from the adapter's `backend` (app id,
+ * Assemble the `AppCredentials` the signer needs from the GitHub App's identity (app id,
  * installation) and the Worker's private-key secret. Throws a CairnError naming
  * `github.app-unreachable` when the secret is unset, since the App cannot authenticate without it.
  */
 export function appCredentials(
-  backend: Pick<BackendConfig, 'appId' | 'installationId'>,
-  env: GithubKeyEnv,
+  identity: { appId: string; installationId: string },
+  env: BackendEnv,
 ): AppCredentials {
   const privateKeyB64 = env.GITHUB_APP_PRIVATE_KEY_B64;
   if (!privateKeyB64) {
@@ -26,5 +29,5 @@ export function appCredentials(
       message: 'GITHUB_APP_PRIVATE_KEY_B64 is not configured',
     });
   }
-  return { appId: backend.appId, installationId: backend.installationId, privateKeyB64 };
+  return { appId: identity.appId, installationId: identity.installationId, privateKeyB64 };
 }

package/src/lib/github/repo.ts

@@ -86,56 +86,6 @@ export async function readRaw(repo: RepoRef, path: string, token?: string): Prom
   return res.text();
 }
 
-/** Standard (padded) base64 of UTF-8 text, the form the contents API expects. */
-function toBase64(text: string): string {
-  return btoa(Array.from(new TextEncoder().encode(text), (b) => String.fromCharCode(b)).join(''));
-}
-
-/** The current blob sha for a path, or null if the file does not yet exist. */
-export async function fileSha(repo: RepoRef, path: string, token: string): Promise<string | null> {
-  const res = await fetch(contentsUrl(repo, path), { headers: ghHeaders('application/vnd.github+json', token) });
-  if (res.status === 404) return null;
-  if (!res.ok) throw new Error(`GitHub stat ${path} failed: ${res.status}`);
-  return ((await res.json()) as { sha: string }).sha;
-}
-
-/**
- * Commit `content` to `path` on the configured branch through the contents API. The author is
- * the editor; the committer is omitted, so GitHub attributes it to the App (`cairn-cms[bot]`).
- * Updates the file in place when it exists (passing its sha), creates it otherwise. Returns the
- * commit sha. A stale-sha 409 (someone committed in between) becomes a `CommitConflictError`,
- * so the save fails safe: re-fetch and ask the editor to reapply, never a merge.
- *
- * Caller preconditions this layer cannot enforce, and the save action (Plan 05) must:
- * `path` is confined to the concept's configured directory (the App token can write anywhere
- * in the repo, so an unvalidated path could overwrite CI config or source), and `author` is
- * derived from the verified server-side session, never from request input.
- */
-export async function commitFile(
-  repo: RepoRef,
-  path: string,
-  content: string,
-  opts: { message: string; author: CommitAuthor },
-  token: string,
-): Promise<string> {
-  const sha = await fileSha(repo, path, token);
-  const url = `${API}/repos/${repo.owner}/${repo.repo}/contents/${path.replace(/^\/+|\/+$/g, '')}`;
-  const res = await fetch(url, {
-    method: 'PUT',
-    headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      message: opts.message,
-      content: toBase64(content),
-      branch: repo.branch,
-      author: opts.author,
-      ...(sha ? { sha } : {}),
-    }),
-  });
-  if (res.status === 409) throw new CommitConflictError(path);
-  if (!res.ok) throw new Error(`GitHub commit ${path} failed: ${res.status} ${await res.text()}`);
-  return ((await res.json()) as { commit: { sha: string } }).commit.sha;
-}
-
 /** A path change for an atomic commit: write `content`, or delete the path when `content` is null. */
 export interface FileChange {
   path: string;
@@ -186,6 +136,69 @@ function treeChanges(changes: FileChange[]): TreeChange[] {
 /** Retries after the initial attempt when the branch moves under an atomic commit. */
 const COMMIT_RETRIES = 3;
 
+/**
+ * Build a tree on `parent`'s tree, create the commit, and PATCH the branch ref to it. Returns the
+ * new commit sha, or null when the ref PATCH is a non-fast-forward (the head moved). A tree-create
+ * 422 (an unprocessable delete) becomes a `CommitConflictError`, and any other non-fast-forward
+ * detail is left to the caller to map.
+ */
+async function commitOnTree(
+  repo: RepoRef,
+  parent: string,
+  tree: TreeChange[],
+  opts: { message: string; author: CommitAuthor },
+  token: string,
+): Promise<{ sha: string } | { conflict: true }> {
+  const baseTree = await commitTreeSha(repo, parent, token);
+
+  const treeRes = await fetch(gitUrl(repo, 'trees'), {
+    method: 'POST',
+    headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ base_tree: baseTree, tree }),
+  });
+  if (!treeRes.ok) {
+    // A 422 means an entry is unprocessable against the base tree, which a delete of an
+    // already-removed path produces (a concurrent delete or rename got there first). Treat it as
+    // the same non-fast-forward conflict the ref PATCH surfaces, so the caller fails safe with the
+    // reload-and-retry path instead of a raw 500.
+    if (treeRes.status === 422) throw new CommitConflictError(`${repo.branch} (tree create)`);
+    throw new Error(`GitHub tree create failed: ${treeRes.status} ${await treeRes.text()}`);
+  }
+  const newTree = ((await treeRes.json()) as { sha: string }).sha;
+
+  const commitRes = await fetch(gitUrl(repo, 'commits'), {
+    method: 'POST',
+    headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ message: opts.message, tree: newTree, parents: [parent], author: opts.author }),
+  });
+  if (!commitRes.ok) throw new Error(`GitHub commit create failed: ${commitRes.status} ${await commitRes.text()}`);
+  const newCommit = ((await commitRes.json()) as { sha: string }).sha;
+
+  const refRes = await fetch(gitUrl(repo, `refs/heads/${encodeURIComponent(repo.branch)}`), {
+    method: 'PATCH',
+    headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ sha: newCommit, force: false }),
+  });
+  if (refRes.ok) return { sha: newCommit };
+  // A non-fast-forward means the branch moved; the caller decides whether to retry or fail closed.
+  // Any other failure is not a race, so surface it.
+  if (refRes.status !== 422) throw new Error(`GitHub ref update failed: ${refRes.status} ${await refRes.text()}`);
+  return { conflict: true };
+}
+
+/** Fail-closed commit on a known head: a non-fast-forward becomes a `CommitConflictError`. */
+async function commitOnHead(
+  repo: RepoRef,
+  head: string,
+  tree: TreeChange[],
+  opts: { message: string; author: CommitAuthor },
+  token: string,
+): Promise<string> {
+  const result = await commitOnTree(repo, head, tree, opts, token);
+  if ('conflict' in result) throw new CommitConflictError(`${repo.branch} (head moved)`);
+  return result.sha;
+}
+
 /**
  * Commit several path changes in one commit over the Git Data API. The author is the editor; the
  * committer is omitted, so GitHub attributes the commit to the App. Returns the new commit sha.
@@ -197,51 +210,34 @@ const COMMIT_RETRIES = 3;
  *
  * An empty change set is rejected, since it would otherwise push an empty commit that triggers a
  * site redeploy for no content change.
+ *
+ * When `expectedHead` is supplied the commit is fail-closed: it makes a single attempt with no
+ * retry, throws a `CommitConflictError` when the branch head is not `expectedHead` (a concurrent
+ * commit landed), and otherwise commits onto that head. The nav and settings writes, which land on
+ * the default branch and trigger a deploy, pass it so a same-branch race surfaces the editor's
+ * reload-and-reapply prompt rather than a silent last-writer-wins. Omitting it keeps the
+ * head-merge retry the entry and publish paths rely on.
  */
 export async function commitFiles(
   repo: RepoRef,
   changes: FileChange[],
   opts: { message: string; author: CommitAuthor },
   token: string,
+  expectedHead?: string,
 ): Promise<string> {
   if (changes.length === 0) throw new Error('commitFiles: no changes to commit');
   const tree = treeChanges(changes);
+  if (expectedHead !== undefined) {
+    const head = await headCommitSha(repo, token);
+    if (head !== expectedHead) throw new CommitConflictError(`${repo.branch} (head moved)`);
+    return commitOnHead(repo, head, tree, opts, token);
+  }
   for (let attempt = 0; attempt <= COMMIT_RETRIES; attempt++) {
     const parent = await headCommitSha(repo, token);
-    const baseTree = await commitTreeSha(repo, parent, token);
-
-    const treeRes = await fetch(gitUrl(repo, 'trees'), {
-      method: 'POST',
-      headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
-      body: JSON.stringify({ base_tree: baseTree, tree }),
-    });
-    if (!treeRes.ok) {
-      // A 422 means an entry is unprocessable against the base tree, which a delete of an
-      // already-removed path produces (a concurrent delete or rename got there first). Treat it as
-      // the same non-fast-forward conflict the ref PATCH surfaces, so the caller fails safe with the
-      // reload-and-retry path instead of a raw 500.
-      if (treeRes.status === 422) throw new CommitConflictError(`${repo.branch} (tree create)`);
-      throw new Error(`GitHub tree create failed: ${treeRes.status} ${await treeRes.text()}`);
-    }
-    const newTree = ((await treeRes.json()) as { sha: string }).sha;
-
-    const commitRes = await fetch(gitUrl(repo, 'commits'), {
-      method: 'POST',
-      headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
-      body: JSON.stringify({ message: opts.message, tree: newTree, parents: [parent], author: opts.author }),
-    });
-    if (!commitRes.ok) throw new Error(`GitHub commit create failed: ${commitRes.status} ${await commitRes.text()}`);
-    const newCommit = ((await commitRes.json()) as { sha: string }).sha;
-
-    const refRes = await fetch(gitUrl(repo, `refs/heads/${encodeURIComponent(repo.branch)}`), {
-      method: 'PATCH',
-      headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
-      body: JSON.stringify({ sha: newCommit, force: false }),
-    });
-    if (refRes.ok) return newCommit;
+    const result = await commitOnTree(repo, parent, tree, opts, token);
     // A non-fast-forward means the branch moved; retry on the new head so a concurrent commit
-    // is preserved. Any other failure is not a race, so surface it.
-    if (refRes.status !== 422) throw new Error(`GitHub ref update failed: ${refRes.status} ${await refRes.text()}`);
+    // is preserved.
+    if ('sha' in result) return result.sha;
   }
   throw new CommitConflictError(`${repo.branch} (atomic commit)`);
 }

package/src/lib/github/types.ts

@@ -1,9 +1,9 @@
-// cairn-cms: the GitHub backend's plain data types and its one typed error. The backend
-// reads repo coordinates from the adapter's `BackendConfig` (spec §8); `RepoRef` is the
-// `{ owner, repo, branch }` subset, so `backend` is assignable wherever a `RepoRef` is
-// wanted with no conversion.
+// cairn-cms: the GitHub backend's plain data types and its one typed error. The GitHub App
+// provider config (`githubApp`'s input) carries these repo coordinates; `RepoRef` is the
+// `{ owner, repo, branch }` subset the read and commit transports take, so the provider config
+// is assignable wherever a `RepoRef` is wanted with no conversion.
 
-/** Repo coordinates pinned to a branch: the structural subset of `BackendConfig` the read and commit paths need. */
+/** Repo coordinates pinned to a branch: the `{ owner, repo, branch }` subset the read and commit paths need. */
 export interface RepoRef {
   owner: string;
   repo: string;