canopycms 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -5,9 +5,9 @@ packages release together, at one version.
 
 ## This build
 
-Version `0.8.0`, built from [`f47713d`](https://github.com/safeinsights/canopycms/tree/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a).
+Version `0.8.1`, built from [`67d7e59`](https://github.com/safeinsights/canopycms/tree/67d7e59ebd472b09175d09c620d8e2d06d333496).
 
-Its entries are [0.8.0](#080), under **Released**.
+Its entries are [0.8.1](#081), under **Released**.
 
 If you upgraded from a build on another branch, compare the `<!-- changeset: … -->` slugs in your previous build's `CHANGELOG.md` (`npm pack canopycms@<old>` fetches it) with this one's: entries whose slug your old file lacks are new to you.
 
@@ -24,7 +24,7 @@ Each entry has up to three parts:
 `node_modules/canopycms/CHANGELOG.md`, assembled for that build: its **This build** section lists
 what is new since the previous int on the same branch, or on a stable release links its entries, and its links point at the commit the build
 came from. The copy in the repository holds released history and the entries from before changesets;
-every entry written since is a file in [`.changeset/`](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/.changeset/README.md) until a stable release
+every entry written since is a file in [`.changeset/`](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/.changeset/README.md) until a stable release
 moves it here.
 
 **Find your starting point.** From a stable pin, start at the first version under **Released**
@@ -62,6 +62,16 @@ entries under **Released**.
 
 ## Released
 
+### 0.8.1
+
+#### Content reads stop re-reading and re-parsing the schema cache
+
+<!-- changeset: schema-cache-read-once -->
+
+_First in 0.8.1._
+
+**What changed.** An adopter's request measured every `read()` and `readByUrlPath()` reading and parsing the branch's whole schema cache file, up to five times per page. Each process now keeps the schema it parsed and reuses it while the file is unchanged, still checking its freshness on every read. `readByUrlPath()` resolves the branch's schema once for both of the paths it tries. A build resolves the schema once per process instead of on every read. The cache file is written without indentation, under half its former size.
+
 ### 0.8.0
 
 <!-- changeset: merge-main-0-7-1-into-int-e -->
@@ -251,7 +261,7 @@ _First in 0.7.0._
 
 **What changed.** The pull request a submit opens now lists the branch's unresolved editor comment threads: where each one is, the first line of its first comment (80 characters at most) and a link to it in the editor. Once every thread is resolved, it says so. The list is updated whenever a comment is added, replied to or resolved, as well as on submit. Comment excerpts are visible to everyone who can read the pull request, which on a public repository means everyone. Open threads do not block the merge or keep the pull request in draft. A pull request opened before this release shows no list until its branch is next submitted.
 
-**To adopt.** Nothing, if your deploy replaces the worker along with the CMS, as `cdk deploy` of the canopycms-cdk stack does with the default `workerCode`. A worker on an earlier release fails each update of the list and marks the branch's sync failed until a later task succeeds, so a pipeline that leaves the worker behind must roll it no later than the CMS: see [Rolling the worker from CI](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#rolling-the-worker-from-ci).
+**To adopt.** Nothing, if your deploy replaces the worker along with the CMS, as `cdk deploy` of the canopycms-cdk stack does with the default `workerCode`. A worker on an earlier release fails each update of the list and marks the branch's sync failed until a later task succeeds, so a pipeline that leaves the worker behind must roll it no later than the CMS: see [Rolling the worker from CI](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#rolling-the-worker-from-ci).
 
 #### Pull request bodies link back to the editor
 
@@ -261,7 +271,7 @@ _First in 0.7.0._
 
 **What changed.** The pull request a submit opens links to the branch in the editor, and each changed entry to that entry. A notice tells reviewers that comments on the pull request do not reach the editor, so the author will not see them. The links use the editor's URL from the submit, accepted only when its host is the one the request was addressed to (`X-Forwarded-Host`, else `Host`), which holds behind `canopycms-cdk`'s CloudFront distribution as it stands.
 
-**To adopt.** Nothing, unless a proxy in front of the CMS sets neither header to the editor's public host: then set `editorUrl` in your Canopy config to the editor page's URL, e.g. `editorUrl: 'https://cms.example.org/edit'`. See [the config reference](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#definecanopyconfig-options).
+**To adopt.** Nothing, unless a proxy in front of the CMS sets neither header to the editor's public host: then set `editorUrl` in your Canopy config to the editor page's URL, e.g. `editorUrl: 'https://cms.example.org/edit'`. See [the config reference](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#definecanopyconfig-options).
 
 #### CloudFront origin read timeout accepted up to 120 s; the editor waits 135 s
 
@@ -347,7 +357,7 @@ _First in 0.6.0._
 
 **What changed.** `CanopyCmsService` takes `clerkOrganizationsAsGroups` (default `true`, unchanged), which the worker honours; in a deployment it, not the plugin's `useOrganizationsAsGroups`, decides the groups. When Clerk refuses the organization list with a 403 (Organizations disabled), the refresh now writes users with no groups and logs a warning, instead of failing whole; any other failure still keeps the last snapshot. Memberships are fetched instance-wide rather than per user. The scaffolds write `false` explicitly: `useOrganizationsAsGroups` in `canopycms init`'s `canopy.ts`, and `clerkOrganizationsAsGroups` in `canopycms init-deploy aws`'s CDK stack.
 
-**To adopt.** On a Clerk instance without Organizations, set `clerkOrganizationsAsGroups: false` on `CanopyCmsService` and `useOrganizationsAsGroups: false` in `createClerkAuthPlugin`. See [Deploying to AWS](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md).
+**To adopt.** On a Clerk instance without Organizations, set `clerkOrganizationsAsGroups: false` on `CanopyCmsService` and `useOrganizationsAsGroups: false` in `createClerkAuthPlugin`. See [Deploying to AWS](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md).
 
 ### 0.5.0
 
@@ -359,7 +369,7 @@ _First in 0.5.0._
 
 **What changed.** A `type: 'reference', list: true` field now edits as rows in stored order, like an `object` list: drag a row or use its "…" menu to move or remove it, open a row to swap its entry in place, and pick from Add under the rows to append. Neither control offers an entry the list already holds. Any `list: true` field, and any `block` field, takes `maxItems`. The editor stops adding at the cap and says why, a save over it is refused, and a production build fails on an entry over it, naming the entry, field, count and cap. Adding `maxItems` to a list that already holds more therefore fails the build until an editor removes the extra items. `maxItems` on a field that holds no items is refused when the entry schema registry is created.
 
-**To adopt.** Set `maxItems: 3` on the list field in its entry schema. See [Field Types](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#field-types).
+**To adopt.** Set `maxItems: 3` on the list field in its entry schema. See [Field Types](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#field-types).
 
 #### SEO field location moves into config; reference pickers mark hidden entries and take a sort order — **breaking: `createNextCanopyContext({ seo })` and `AIContentConfig.seo` are removed**
 
@@ -369,7 +379,7 @@ _First in 0.5.0._
 
 **What changed.** `defineCanopyConfig` takes `seo: { group?, fields? }`, the one place every surface reads an entry's `noindex` flag: the sitemap and `entryToMetadata` that `createNextCanopyContext` returns, AI content and the editor's reference picker. A per-call `seo`/`group`/`fields` still overrides it. The free `generateContentSitemap` takes `seo` as an argument and refuses to run without it when the config sets one; `createNextCanopyContext` and the AI content config refuse a leftover `seo`. A reference picker now badges an entry hidden from search as "Hidden from search", and picking one adds a note naming the setting on that entry's form, since a page listing only indexed entries won't show it. A reference field takes `optionSort`: `'label'` (the default), `'collection'`, or `{ field, direction }`. Point `field` at an ISO date, since strings compare as text.
 
-**To adopt.** Move `seo` from `createNextCanopyContext({ seo })` and from `defineAIContentConfig({ seo })` into `defineCanopyConfig({ seo })`. See [Sitemap and SEO Metadata](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#sitemap-and-seo-metadata) and [How References Work in the Editor](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#how-references-work-in-the-editor).
+**To adopt.** Move `seo` from `createNextCanopyContext({ seo })` and from `defineAIContentConfig({ seo })` into `defineCanopyConfig({ seo })`. See [Sitemap and SEO Metadata](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#sitemap-and-seo-metadata) and [How References Work in the Editor](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#how-references-work-in-the-editor).
 
 **Now deletable.** A shared `seo` constant passed separately to the Next context and the AI content config.
 
@@ -397,7 +407,7 @@ resolved without it.
 **To adopt.** Where a reference renders its target's prose, set `includeBody: true` on that
 reference field. Code that reads the body from a link-only reference's resolved type now sees
 `string | undefined`; either set `includeBody: true` or handle the missing value. See
-[Resolving References in a Listing](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#resolving-references-in-a-listing).
+[Resolving References in a Listing](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#resolving-references-in-a-listing).
 
 ### 0.3.3
 
@@ -814,7 +824,7 @@ URL.
 2. For a branch preview: wrap views with `withCanopyPreview` in a `'use client'` module, add
    `app/preview/[[...path]]/page.server.tsx`, set `editor.previewPrefix: '/preview'`, and serve that
    route with `frame-ancestors 'self'`, not `X-Frame-Options: DENY` (see
-   [Live Preview](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#live-preview)).
+   [Live Preview](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#live-preview)).
 3. A test reading view content from the route's server HTML must load the page in a browser.
    Server output rendered during a preview request carries the signed-in asset prefix; keep it out
    of cross-request caches (`unstable_cache`, module memos).
@@ -829,7 +839,7 @@ kept site styles ahead of Mantine's in the preview.
 server components. A string path marks the form's spelling (`'a.0.b'` marks `a[0].b`), and an empty
 path marks nothing. The editor counts and logs marks naming no field. `createEntrySchemaRegistry`
 refuses a field name that is empty, all digits or contains `.`, `[` or `]`. See
-[Live Preview](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#live-preview).
+[Live Preview](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#live-preview).
 
 **To adopt.** Fix each path that stops compiling; the error lists valid ones. Rewrite computed paths
 as literal segments, or type that component's prop as plain `FieldProps`. Pass `fieldProps` as
@@ -911,7 +921,7 @@ or a failed render) renders as its plain text, with no URL; any other form of th
 fields are nested or renamed, pass the AI config's `seo` the same object you pass
 `createNextCanopyContext({ seo })`, so the sitemap and AI content read the flag from the same
 place. A field that links to a hidden section by plain URL needs a field transform; the README
-shows [the recipe](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#ai-content-configuration).
+shows [the recipe](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#ai-content-configuration).
 
 **Now deletable.** An `exclude.where` that re-read the `noindex` flag by hand.
 
@@ -933,7 +943,7 @@ A `markdown` field with `renderAs: 'mdx'` is checked as MDX, and `mdxAllow` narr
 field or site-wide. New: field options `renderAs`, `mdxAllow`; config key `mdxAllow`; type
 `MdxAllowlist`. (int.110) A component prop allowance can be `'string'` (or
 `{ type: 'string', maxLength }`): a quoted value only, never bare or `{…}`. See
-[MDX content cannot run code](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#mdx-content-cannot-run-code).
+[MDX content cannot run code](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#mdx-content-cannot-run-code).
 
 **To adopt.** Set `renderAs: 'mdx'` on each `markdown` field your site compiles as MDX, and
 `mdxAllow` to what your renderer takes. Set `executable: true` only on a field whose editors you
@@ -1070,7 +1080,7 @@ a format check.
 
 - (int.93) Submit commits gain an `Edited-by: Name (id)` trailer; PR bodies gain a section that
   re-submits replace, keeping human text. Options: `gitEditedByTrailers`, `gitCoAuthoredByTrailers`
-  ([reference](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#definecanopyconfig-options)).
+  ([reference](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#definecanopyconfig-options)).
 - (int.110) Submit-commit trailers name every user who saved since the last submit commit, and
   the PR-body section every user who edited the branch, not only the submitter; settings commits
   (permissions, groups) carry the acting user's trailer.
@@ -1094,7 +1104,7 @@ saves only push the branch, and no failing PR task lands in System health.
 that entry type goes unavailable: the editor says so, and its entries answer 503 with
 `code: 'SCHEMA_UNAVAILABLE'`. Builds, static deploys and `generate-ai-content` still fail. The
 worker holds the base branch for up to 30 minutes while that lasts; see
-[New schemas wait for the editor deploy](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#new-schemas-wait-for-the-editor-deploy).
+[New schemas wait for the editor deploy](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#new-schemas-wait-for-the-editor-deploy).
 Public types gain optional `unavailable` on `EntryTypeConfig` and `FlatSchemaItem`, optional
 `ApiResponse.code`, and a required `SchemaResolutionResult.issues`.
 
@@ -1132,7 +1142,7 @@ hang until the drain heartbeat lets termination continue. Its in-flight task is
 new stack needs no steps.
 
 **What changed.** (int.109) Detailed in
-[The worker instance](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#the-worker-instance): IMDSv2 with a hop limit of 1; the
+[The worker instance](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#the-worker-instance): IMDSv2 with a hop limit of 1; the
 bundle is one file whose sha256 user data checks, readable as that one object; a file-system policy
 refusing clients without TLS or IAM, replacing the worker's
 `AmazonElasticFileSystemClientReadWriteAccess`; an encrypted gp3 root volume; a boot-time upgrade to
@@ -1186,10 +1196,10 @@ failure and exits non-zero on `selfStopped`, with a code outside `RestartPrevent
   with its hash, as `worker/dist/index.js` and `index.js.sha256`. The default, `'asset'`, is
   unchanged.
 - `CanopyCmsService` alarms when the worker logs no git sync for 30 minutes. See
-  [Worker-down alarm](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#worker-down-alarm).
+  [Worker-down alarm](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#worker-down-alarm).
 
 **To adopt.** Optional. For parameter-only change sets, see
-[Rolling the worker from CI](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#rolling-the-worker-from-ci). For the alarm, pass
+[Rolling the worker from CI](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#rolling-the-worker-from-ci). For the alarm, pass
 `alarmTopic`.
 
 **Now deletable.** A manual `cdk deploy` after each canopycms bump whose only purpose is moving the
@@ -1200,7 +1210,7 @@ worker, and a hand-built alarm on the worker log group.
 **What changed.** (int.112) The boot's `dnf upgrade` could be OOM-killed on every retry. A 1 GiB
 swap file now goes on first; an upgrade that still fails starts the worker unpatched and notifies
 `alarmTopic` if set; a retried step names itself when it gives up. See
-[The worker instance](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#the-worker-instance).
+[The worker instance](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#the-worker-instance).
 
 **To adopt.** Deploy, which replaces the worker instance. The bundle needs none of this, so it is
 not Template first and the worker contract stays at 1.
@@ -1266,7 +1276,7 @@ and operations may reuse GitHub fetches under 30 seconds old.
 
 **To adopt.** Nothing. Seeding `remote.git` stages a copy of the repository beside the gateway's
 mirror, so the root volume needs room for two
-([details](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#the-worker-instance)).
+([details](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#the-worker-instance)).
 
 #### The worker follows a rebased or deleted GitHub branch
 
@@ -1288,7 +1298,7 @@ changes the template too (the fallback bundle's key and hash), so only the contr
 bundle-only roll is safe.
 
 **To adopt.** Parameter mode: gate bundle-only rolls on the contract
-([recipe](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#rolling-the-worker-from-ci)). The gate refuses a stack without the
+([recipe](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#rolling-the-worker-from-ci)). The gate refuses a stack without the
 `WorkerContract` output, so `cdk deploy` the template once, which adds it. A hand-installed unit
 copies its `Environment=CANOPYCMS_WORKER_CONTRACT=` line from `worker/canopy-worker.service`.
 
@@ -1305,8 +1315,8 @@ units from the bundle's contract: 2 gets the split, an older bundle the single u
 template, then roll the bundle; on an older template it stops with `template too old for this
 bundle`. Inspect EFS only through `sudo /opt/canopy-worker/canopy-inspect <command>`, never from a root shell. A hand install
 takes `worker/`'s three units and `gateway.env.example`
-([steps](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#installing-the-units-by-hand)). After the first deploy, run the
-[checklist](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#first-deploy-checklist).
+([steps](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#installing-the-units-by-hand)). After the first deploy, run the
+[checklist](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#first-deploy-checklist).
 
 #### `canopycms-cdk`: `CanopyCmsService.attachTo`, and editor response headers — **behaviour change if you frame the CMS**
 
@@ -1317,7 +1327,7 @@ response headers policy. `CanopyCmsDistribution` sends the same headers: `frame-
 `X-Frame-Options: SAMEORIGIN`, `nosniff`, HSTS and `X-Robots-Tag: noindex`. Unless your app sends
 its own framing headers, no other origin can frame the editor or any page the CMS domain serves. Every such page is
 marked `noindex`. The editor's default preview is same-origin and unaffected. See
-[Serving the editor from a distribution you already own](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#serving-the-editor-from-a-distribution-you-already-own).
+[Serving the editor from a distribution you already own](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#serving-the-editor-from-a-distribution-you-already-own).
 
 **To adopt.** If you wired the Function URL into your own distribution by hand, delete those
 behaviors and call `attachTo`, passing your CMS build's `assetPrefix` as `editorAssetPrefix` and a
@@ -1493,7 +1503,7 @@ one the exclusions leave out. A throw or any other return is logged and treated
 **To adopt.** If your site's routes, sitemap or bylines decide that some entries have no page,
 apply the same rule here, for example `referenceLink: (target, { body }) =>
 !body?.trim() ? false : undefined` in `defineAIContentConfig` from `canopycms/ai`. See
-[AI Content Configuration](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#ai-content-configuration).
+[AI Content Configuration](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#ai-content-configuration).
 
 **Now deletable.** A `fieldTransforms` entry that re-renders a reference field only to drop or
 change its link.
@@ -1568,7 +1578,7 @@ _First in int.115._
 entry the base branch also changed, the "updated on the base branch" notice and the branch's
 conflict count now stay until the branch merges, so a reviewer still sees which entries replaced a
 base change. They used to clear on the next sync, about five minutes later. README's new [Drafts
-and Unpublishing](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#drafts-and-unpublishing) section covers long-lived branches and
+and Unpublishing](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#drafts-and-unpublishing) section covers long-lived branches and
 unpublishing.
 
 #### The editor calls the content drawer "All content"
@@ -1880,7 +1890,7 @@ editor carries an unsaved draft of a stamped entry onto its stamped version.
 The flag is refused off a top-level `datetime`, on `list: true`, and with `required: true`.
 
 **To adopt.** Add `stampOnPublish: true` to the date field your site sorts or labels by, such as
-`{ name: 'publishedAt', type: 'datetime', stampOnPublish: true }`. See [Stamping a publication date](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#stamping-a-publication-date).
+`{ name: 'publishedAt', type: 'datetime', stampOnPublish: true }`. See [Stamping a publication date](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#stamping-a-publication-date).
 
 **Now deletable.** A build step or hook that writes a missing publication date into new entries.
 
@@ -1927,7 +1937,7 @@ preview/form divider is now keyboard-resizable within the same 15–85% the spli
 stored at, and `react-split-pane` is no longer a dependency.
 `EditorPanes`, `EditorPanesProps`, the `PaneLayout` type and the `SPLIT_PERCENT_*` and `DEFAULT_*_SPLIT_PERCENT` constants are
 no longer exported from `canopycms/client`. See
-[Your root layout](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#editor-customization).
+[Your root layout](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#editor-customization).
 
 **To adopt.** Nothing, unless you import `EditorPanes` or those constants: render `CanopyEditor`
 instead, which lays out its own panes. Hiding your site chrome on the editor route is now
@@ -2038,7 +2048,7 @@ never ended. `canopycms-auth-clerk` skips it while the editor is mounted, and ex
 **To adopt.** Nothing for the editor, if your edit page uses `useClerkAuthConfig()` or
 `ClerkSignIn`. If your CMS build renders `<SignIn>`, `UserButton` or `OrganizationSwitcher` on your
 own pages, mount the hook as in
-[Clerk components on your own pages](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/packages/canopycms-auth-clerk/README.md#clerk-components-on-your-own-pages).
+[Clerk components on your own pages](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/packages/canopycms-auth-clerk/README.md#clerk-components-on-your-own-pages).
 Your own Server Actions in the CMS build still 403 behind OAC.
 
 **Now deletable.** Any local patch of `window.__internal_onBeforeSetActive` (or 6.x's
@@ -2079,12 +2089,12 @@ fast naming the ARN, the field and the keys present, never a value.
 **To adopt.** Nothing, unless one of those secrets holds a JSON document: then set the matching
 prop. The scaffolded stack fills them from the repository _variables_
 `CANOPY_GITHUB_TOKEN_SECRET_JSON_FIELD` and `CLERK_SECRET_KEY_SECRET_JSON_FIELD`
-([why the prefix](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#repository-secrets-and-variables)); a stack scaffolded earlier
+([why the prefix](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#repository-secrets-and-variables)); a stack scaffolded earlier
 adds the props to `infrastructure/bin/app.ts` and `infrastructure/lib/cms-stack.ts` and the two `env`
 lines to `.github/workflows/deploy-cms.yml`, or re-runs the generator and diffs. `cdk synth` refuses a `…JsonField` prop without its `…SecretArn`, and an ARN carrying the ECS `:KEY::` suffix
 (also in `secretsArns`). Don't use CDK's `secretValueFromJson`: it resolves the plaintext into the deployed
 resource's configuration, readable by anyone who can describe it. Only `CLERK_SECRET_KEY` goes through Secrets Manager; `CLERK_JWT_KEY` and the publishable
-key are public material ([Security Model](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#security-model)).
+key are public material ([Security Model](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#security-model)).
 
 **Now deletable.** A wrapper that fetches the secret, parses it and re-exports one field into the
 worker's environment, such as a `jq` step in user data or a wrapper entrypoint around
@@ -2096,7 +2106,7 @@ worker's environment, such as a `jq` step in user data or a wrapper entrypoint a
 `githubToken` is not deprecated and stays the documented default; `canopycms` neither depends on
 nor imports `@octokit/auth-app`. Register one App per site, not one shared across repositories:
 anyone holding an App's key can mint a token for any of its installations
-([why](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/ARCHITECTURE.md#why-one-github-app-per-site-not-one-shared-across-an-organisation)).
+([why](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/ARCHITECTURE.md#why-one-github-app-per-site-not-one-shared-across-an-organisation)).
 
 **To adopt with `canopycms-cdk`** (existing stacks need no edit). `CanopyCmsServiceProps` takes
 `githubAppId`, `githubAppInstallationId`, `githubAppPrivateKeySecretArn` and
@@ -2109,7 +2119,7 @@ anyone holding an App's key can mint a token for any of its installations
    `verify` checks an existing installation's permissions: run it, since an App missing a
    permission only shows up later, as `sync-failed`. `create` needs an interactive terminal and
    never edits an existing JSON secret (create one and point the JSON-field prop at it)
-   ([details](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#register-it-with-canopycms-init-github-app)).
+   ([details](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#register-it-with-canopycms-init-github-app)).
 2. Set the three props and **remove `githubTokenSecretArn`** (with its JSON field). A partial set
    of the three is refused at synth, and so is an App alongside a token.
 3. In the generated workflow, store them as `CANOPY_GITHUB_APP_ID`,
@@ -2120,7 +2130,7 @@ anyone holding an App's key can mint a token for any of its installations
 
 The private key is ARN-only; passing the key itself is refused at synth. Its ARN joins the worker's
 IAM policy automatically, so you need not add it to `secretsArns`. See
-[Authenticating as a GitHub App](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#authenticating-as-a-github-app).
+[Authenticating as a GitHub App](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#authenticating-as-a-github-app).
 
 ```bash
 canopycms init-github-app create -- \
@@ -2168,7 +2178,7 @@ downloads the `.pem` from the App's settings page.
 
 **What changed.** The worker re-reads a Secrets Manager secret (the GitHub token or the Clerk secret
 key) when the operation using it fails. Timings, costs and the store-before-revoke order are in
-[Rotating a secret](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#rotating-a-secret).
+[Rotating a secret](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#rotating-a-secret).
 
 **To adopt.** Nothing for credentials from `*_SECRET_ARN`, which is every scaffolded deployment. A
 GitHub App private key is still read only at boot: store the new key, replace the instance, and
@@ -2222,12 +2232,12 @@ also check the bucket policy for its grant.
 5. `withCanopy()` adds sharp's libvips to Next's file tracing (not for a static export) and, on
    Next 16 and later, sets `turbopack: {}` when your config has neither `turbopack` nor your own
    `webpack` and it can read your Next version. A webpack build still fails its image transforms
-   ([Dual Build Support](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#dual-build-support)).
+   ([Dual Build Support](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#dual-build-support)).
 
 **Breaking:** a stack setting `platform` on `fromImageAsset` without `architecture` gets an arm64
 function while `platform` still decides the image, so `Platform.LINUX_AMD64` builds an image the
 function cannot run. A stack setting neither moves to arm64 with a matching image, built under QEMU
-on an x86 host ([Where the image is built](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#where-the-image-is-built)).
+on an x86 host ([Where the image is built](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#where-the-image-is-built)).
 
 **To adopt.**
 
@@ -2256,7 +2266,7 @@ reason; `platform` on `fromImageAsset`; and, with `withCanopy()`, a hand-written
 
 **What changed.** `media.uploadUrl` (s3 adapter; an absolute http(s) URL or a site-relative path)
 replaces the `url` that `beginUpload()` returns, leaving the presign's `fields` untouched, so
-uploads can be same-origin. See [Media Configuration](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#media-configuration) for the
+uploads can be same-origin. See [Media Configuration](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#media-configuration) for the
 CloudFront behavior it expects.
 
 **To adopt.** Optional. Set it from an environment variable: a site-relative value works only where
@@ -2281,7 +2291,7 @@ needs `lazyPublicTransforms: true`) let you pass a deterministically named role,
 bucket's stack computes `arn:aws:iam::<account>:role/<name>` from literals instead of a
 `Fn::GetStackOutput` reference only the CDK CLI resolves. The constructs re-attach
 `AWSLambdaBasicExecutionRole` (and the VPC policy) that `lambda.Function` drops from a role you
-pass. See [Cross-account asset bucket](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#cross-account-asset-bucket).
+pass. See [Cross-account asset bucket](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#cross-account-asset-bucket).
 
 **To adopt.** Optional:
 
@@ -2391,7 +2401,7 @@ public JWKS PEM, used only to verify signatures.
 to variables (Settings → Secrets and variables → Actions → Variables); `bin/app.ts` refuses the
 deploy at synth while it is unset. Check that `bin/app.ts` passes `CLERK_SECRET_KEY` as
 `clerkSecretKeySecretArn` (read by the worker), never in the Lambda's `environment`, unless you keep
-`clerkMiddleware` ([Security Model](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/docs/deploying-to-aws.md#security-model)).
+`clerkMiddleware` ([Security Model](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/docs/deploying-to-aws.md#security-model)).
 
 #### `readByUrlPath` answers only where `listEntries` publishes — **breaking (routing)**
 
@@ -2490,7 +2500,7 @@ basePath: process.env.NEXT_PUBLIC_BASE_PATH,
 Then pass `baseUrl` to `assetUrl` only if Next serves `/assets` (local adapter, `next dev`, S3 with
 no distribution): `assetUrl(image, { width: 960, baseUrl: BASE_PATH })`. Assets on CloudFront via
 `AssetSupport` stay at the distribution root; pass no `baseUrl` (mount table under "Where `/assets`
-is mounted" in [Media Configuration](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#media-configuration)). Two traps:
+is mounted" in [Media Configuration](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#media-configuration)). Two traps:
 
 - Don't pass a deployment `basePath` to `contentStaticParams({ basePath })`; that option filters by
   a nested route prefix and emits zero params, building green.
@@ -2649,7 +2659,7 @@ Under `exactOptionalPropertyTypes: true`, omit keys instead of assigning `undefi
 `withTrailingSlash` and `isAbsoluteUrl` from `canopycms/server`; `defineSeoFieldGroup()` from
 `canopycms`; `generateContentSitemap` and `entryToMetadata` from `canopycms-next`, bound on
 `createNextCanopyContext`'s result. See
-[Sitemap and SEO Metadata](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#sitemap-and-seo-metadata). Every routable entry type is in
+[Sitemap and SEO Metadata](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#sitemap-and-seo-metadata). Every routable entry type is in
 the sitemap unless `exclude`d or `noindex`; one `noindex` predicate drives both robots metadata and
 sitemap exclusion. `trailingSlash` is never inferred. `lastModified` defaults to `updatedAt`, a
 filesystem mtime. An empty SEO field counts as unset. `siteUrl` must be absolute, colliding URLs are
@@ -2706,7 +2716,7 @@ underscore-prefixed files are skipped.
 
 **What changed.** New scaffolds write `defaultBranchAccess: 'deny'` and
 `defaultPathAccess: { read: 'allow' }`
-([Public read on server deployments](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#public-read-on-server-deployments)).
+([Public read on server deployments](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#public-read-on-server-deployments)).
 
 **To adopt.** An older scaffold's `defaultBranchAccess: 'allow'` is wider than recommended;
 consider `'deny'`. If you deleted `defaultPathAccess: { read: 'allow' }`, anonymous visitors get no content until you
@@ -2759,7 +2769,7 @@ re-checked an entry's type (a `switch` on `meta.entryType` can merge them into o
 **What changed.** `BlockComponentRegistry<Blocks>` (types only, from `canopycms`; `BlockValueOf<Blocks, 'hero'>`
 gives one template's value type) requires exactly
 one component per block template name when written as an object literal. See
-[Block Component Registries](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#block-component-registries) and
+[Block Component Registries](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#block-component-registries) and
 `apps/example1/app/components/PostView.tsx`.
 
 ```ts
@@ -2781,7 +2791,7 @@ templates against the schema.
 
 **What changed.** Spreading a `const` field array into several schemas, and nesting
 `defineInlineFieldGroup()` inside a block template, are documented
-([Reusable Field Fragments](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#reusable-field-fragments)); `defineFieldFragment()` is an
+([Reusable Field Fragments](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#reusable-field-fragments)); `defineFieldFragment()` is an
 identity helper for them.
 
 ```ts
@@ -2800,7 +2810,7 @@ field by composing from the same `const` field object.
 A block template holding a `reference` field is a shared block; `read()`/`readByUrlPath()` resolve
 it, and listings do with
 [`resolveReferences`](#listings-resolve-references-and-a-resolved-reference-carries-urlpath-and-optionally-its-body-16--breaking-type-level)
-(0.0.64). See [Shared / Referenced Blocks](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#shared--referenced-blocks).
+(0.0.64). See [Shared / Referenced Blocks](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#shared--referenced-blocks).
 
 **Now deletable.** A second `read()` in page code to unwrap a shared block's reference.
 
@@ -2822,7 +2832,7 @@ Not retro-documented, apart from these:
 
 #### The registry is keyed by entry-type name (0.0.42)
 
-**What changed.** `createEntrySchemaRegistry` keys are the entry-type names that `.collection.json` files name in `entry.schema`, and `EntryTypesFromRegistry` derives the typed entry-type map from them. Schema-variable keys (`{ postSchema }`) still work but derive nothing; [README's registry convention](https://github.com/safeinsights/canopycms/blob/f47713db8d2e5c0dbb3b7ef77ea4b03c1939595a/README.md#convention-why-key-the-registry-by-entry-type-name) says when to keep them.
+**What changed.** `createEntrySchemaRegistry` keys are the entry-type names that `.collection.json` files name in `entry.schema`, and `EntryTypesFromRegistry` derives the typed entry-type map from them. Schema-variable keys (`{ postSchema }`) still work but derive nothing; [README's registry convention](https://github.com/safeinsights/canopycms/blob/67d7e59ebd472b09175d09c620d8e2d06d333496/README.md#convention-why-key-the-registry-by-entry-type-name) says when to keep them.
 
 **To adopt.**
 

package/dist/branch-schema-cache.d.ts

@@ -33,8 +33,15 @@ export interface ResolvedBranchSchema {
     issues: SchemaIssue[];
 }
 /**
- * Per-branch schema cache: one file in {@link schemaCacheDir} with no in-memory
- * layer, so it stays coherent across Lambda invocations.
+ * Per-branch schema cache: one file in {@link schemaCacheDir}, the only state
+ * shared across processes. Each process keeps the entries it parsed or wrote,
+ * keyed by the file's identity, so it parses an unchanged file once while the
+ * entry stays in its size-bounded memo. Every call still opens the file and
+ * runs every freshness check below on the entry, and the file is only ever
+ * replaced by rename (see {@link fileIdentity}), so a process is as fresh as if
+ * it re-read the file. The identity is fstat'ed on an open handle because NFS
+ * revalidates attributes on open (close-to-open), while a bare stat() may
+ * answer from its attribute cache.
  *
  * Freshness follows the generation-marker protocol owned by
  * resource-generation.ts, and this is one of that protocol's durable-snapshot
@@ -58,6 +65,16 @@ export interface ResolvedBranchSchema {
 export declare class BranchSchemaCache {
     /** Tracks when we last checked mtimes per contentRoot, to debounce rapid requests */
     private lastMtimeCheck;
+    /** Parsed cache files, by absolute path; see the class doc. */
+    private readonly snapshots;
+    /**
+     * In-flight resolves of the checkout during a build, by content root and registry. A build
+     * reads a checkout that does not change under it, so those two are its whole input and the
+     * result needs no revalidation. Only {@link isBuildMode}: `CANOPY_BUILD_MODE` is a build and
+     * script switch, and a long-lived process setting it would see a schema edit only on
+     * restart. A rejected resolve is dropped, so a strict-mode failure fails every read.
+     */
+    private readonly buildResolves;
     private readonly devMode;
     constructor(mode?: OperatingMode);
     /**
@@ -79,6 +96,9 @@ export declare class BranchSchemaCache {
      */
     protected resolveFresh(contentRoot: string, entrySchemaRegistry: EntrySchemaRegistry, unknownSchema: UnknownSchemaPolicy): Promise<SchemaResolutionResult>;
     private loadFromCacheOrResolve;
+    private resolveForBuild;
+    /** The parsed cache file, or null when it is absent or unreadable. */
+    private readSnapshot;
     /**
      * Resolve the schema fresh from disk and persist it (subject to the
      * skip-persist rule below), UNCONDITIONALLY -- never through the cache-read

package/dist/branch-schema-cache.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { LRUCache } from 'lru-cache';
 import { resolveSchema, isValidSchema } from './schema/resolver.js';
 import { registryFingerprint } from './schema/registry-fingerprint.js';
 import { flattenSchema } from './config/flatten.js';
@@ -13,6 +14,8 @@ import { canopyLogWarn } from './utils/logger.js';
 const SCHEMA_CACHE_VERSION = 4;
 /** Minimum interval between mtime staleness checks (ms) */
 const MTIME_CHECK_DEBOUNCE_MS = 1000;
+/** Cap on the parsed snapshots one process keeps, counted in bytes of their files. */
+const SNAPSHOT_MEMO_MAX_BYTES = 64 * 1024 * 1024;
 /** File name of the schema cache inside {@link schemaCacheDir}. */
 export const SCHEMA_CACHE_FILE = 'schema-cache.json';
 /** resource-generation.ts resource key for the schema cache's marker. */
@@ -65,6 +68,13 @@ async function isStaleByMtime(dir, cachedAt) {
     }
     return false;
 }
+/**
+ * Names one version of a file. Every write of the schema cache renames a new temp file into
+ * place, so a rewrite always changes the inode, whatever token or content it carries.
+ */
+function fileIdentity(stat) {
+    return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}`;
+}
 /**
  * Directory holding a branch's schema cache: `{branchRoot}/.git/canopycms` when
  * the branch root is a full clone (every canopycms branch workspace is), else
@@ -80,8 +90,15 @@ async function schemaCacheDir(branchRoot) {
     return isClone ? path.join(gitDir, 'canopycms') : path.join(branchRoot, CANOPY_META_DIR);
 }
 /**
- * Per-branch schema cache: one file in {@link schemaCacheDir} with no in-memory
- * layer, so it stays coherent across Lambda invocations.
+ * Per-branch schema cache: one file in {@link schemaCacheDir}, the only state
+ * shared across processes. Each process keeps the entries it parsed or wrote,
+ * keyed by the file's identity, so it parses an unchanged file once while the
+ * entry stays in its size-bounded memo. Every call still opens the file and
+ * runs every freshness check below on the entry, and the file is only ever
+ * replaced by rename (see {@link fileIdentity}), so a process is as fresh as if
+ * it re-read the file. The identity is fstat'ed on an open handle because NFS
+ * revalidates attributes on open (close-to-open), while a bare stat() may
+ * answer from its attribute cache.
  *
  * Freshness follows the generation-marker protocol owned by
  * resource-generation.ts, and this is one of that protocol's durable-snapshot
@@ -106,6 +123,19 @@ export class BranchSchemaCache {
     constructor(mode = 'prod') {
         /** Tracks when we last checked mtimes per contentRoot, to debounce rapid requests */
         this.lastMtimeCheck = new Map();
+        /** Parsed cache files, by absolute path; see the class doc. */
+        this.snapshots = new LRUCache({
+            maxSize: SNAPSHOT_MEMO_MAX_BYTES,
+            sizeCalculation: (snapshot) => Math.max(1, snapshot.bytes),
+        });
+        /**
+         * In-flight resolves of the checkout during a build, by content root and registry. A build
+         * reads a checkout that does not change under it, so those two are its whole input and the
+         * result needs no revalidation. Only {@link isBuildMode}: `CANOPY_BUILD_MODE` is a build and
+         * script switch, and a long-lived process setting it would see a schema edit only on
+         * restart. A rejected resolve is dropped, so a strict-mode failure fails every read.
+         */
+        this.buildResolves = new Map();
         this.devMode = mode === 'dev';
     }
     /**
@@ -135,17 +165,12 @@ export class BranchSchemaCache {
     async loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName) {
         const contentRoot = path.join(branchRoot, contentRootName);
         const fromCheckout = this.readsCheckout(branchRoot);
+        if (fromCheckout && isBuildMode()) {
+            return this.resolveForBuild(branchRoot, entrySchemaRegistry, contentRootName);
+        }
         if (!fromCheckout) {
             const cachePath = path.join(await schemaCacheDir(branchRoot), SCHEMA_CACHE_FILE);
-            let cacheData = null;
-            try {
-                const cacheContent = await fs.readFile(cachePath, 'utf-8');
-                cacheData = JSON.parse(cacheContent);
-            }
-            catch {
-                // Cache doesn't exist or can't be read
-                cacheData = null;
-            }
+            let cacheData = await this.readSnapshot(cachePath);
             // Strict version check, not truthiness: a snapshot from an older version
             // left on EFS by a rolling deploy has no `generation` field, and an
             // `undefined` token breaks the freshness comparison below.
@@ -187,6 +212,44 @@ export class BranchSchemaCache {
             fromCheckout,
         });
     }
+    resolveForBuild(branchRoot, entrySchemaRegistry, contentRootName) {
+        const key = `${path.resolve(branchRoot, contentRootName)}\0${registryFingerprint(entrySchemaRegistry)}`;
+        let pending = this.buildResolves.get(key);
+        if (!pending) {
+            pending = this.resolveFreshAndPersist(branchRoot, entrySchemaRegistry, contentRootName, {
+                fromCheckout: true,
+            });
+            this.buildResolves.set(key, pending);
+            pending.catch(() => this.buildResolves.delete(key));
+        }
+        return pending;
+    }
+    /** The parsed cache file, or null when it is absent or unreadable. */
+    async readSnapshot(cachePath) {
+        let handle;
+        try {
+            handle = await fs.open(cachePath, 'r');
+        }
+        catch {
+            return null;
+        }
+        try {
+            const stat = await handle.stat({ bigint: true });
+            const identity = fileIdentity(stat);
+            const memo = this.snapshots.get(cachePath);
+            if (memo?.identity === identity)
+                return memo.entry;
+            const entry = JSON.parse(await fs.readFile(handle, 'utf-8'));
+            this.snapshots.set(cachePath, { identity, entry, bytes: Number(stat.size) });
+            return entry;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            await handle.close().catch(() => { });
+        }
+    }
     /**
      * Resolve the schema fresh from disk and persist it (subject to the
      * skip-persist rule below), UNCONDITIONALLY -- never through the cache-read
@@ -241,16 +304,29 @@ export class BranchSchemaCache {
                 };
                 // Temp file then rename, with the temp file unlinked on a failed
                 // rename so a transient error leaves no stray `.tmp` beside the cache.
+                // The memo is seeded from the temp file's own identity, which the
+                // rename keeps: stat'ing cachePath afterwards could see a concurrent
+                // writer's file and pair it with this entry. It holds the parsed body,
+                // as every reader does, not the resolver's objects, which alias the
+                // registry and keep values JSON changes or drops.
                 await fs.mkdir(cacheDir, { recursive: true });
                 const tmpPath = path.join(cacheDir, `schema-cache.tmp.${Date.now()}.${Math.random()}.json`);
-                await fs.writeFile(tmpPath, JSON.stringify(newCache, null, 2), 'utf-8');
+                const body = JSON.stringify(newCache);
+                let identity;
                 try {
+                    await fs.writeFile(tmpPath, body, 'utf-8');
+                    identity = fileIdentity(await fs.stat(tmpPath, { bigint: true }));
                     await fs.rename(tmpPath, cachePath);
                 }
                 catch (err) {
                     await fs.unlink(tmpPath).catch(() => { });
                     throw err;
                 }
+                this.snapshots.set(cachePath, {
+                    identity,
+                    entry: JSON.parse(body),
+                    bytes: Buffer.byteLength(body),
+                });
             }
             // else: the marker read failed for a reason other than "never bumped",
             // so no token can be attributed to this resolve, and a snapshot stamped

package/dist/cli/cli.js

@@ -3405,6 +3405,7 @@ import path72 from "node:path";
 import { randomUUID as randomUUID2 } from "node:crypto";
 import fs72 from "node:fs/promises";
 import path82 from "node:path";
+import { LRUCache } from "lru-cache";
 import { promises as fs62 } from "fs";
 import { join } from "pathe";
 import { z as z7 } from "zod";
@@ -5706,6 +5707,9 @@ async function isStaleByMtime(dir, cachedAt) {
   }
   return false;
 }
+function fileIdentity(stat) {
+  return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}`;
+}
 async function schemaCacheDir(branchRoot) {
   const gitDir = path82.join(branchRoot, ".git");
   const isClone = await fs72.stat(gitDir).then((stat) => stat.isDirectory(), () => false);
@@ -8432,7 +8436,7 @@ async function generateAIContentCLI(options) {
   console.log(`  Output: ${result.outputDir}
 `);
 }
-var __defProp3, __getOwnPropNames3, __esm3, __export3, init_error3, init_atomic_write2, init_field_traversal, ITEM_KEY, ITEM_KEY_PATTERN, isItemKey, BASE58, isListField, init_item_keys, active2, init_logger2, SENTINEL_BASE2, DOT_SEGMENT2, init_sanitize_href2, init_normalize, RESERVED_SETTINGS_BRANCH_PREFIX2, init_branch_name, BASE58_PATTERN2, CONTENT_ID_PATTERN2, PHYSICAL_SEGMENT_PATTERN2, MAX_BRANCH_NAME_LENGTH2, init_validation, ROOT_COLLECTION_ID, init_types2, normalizePathValue, flattenSchema, init_flatten, scalarFieldTypes2, markdownFieldTypes2, primitiveFieldTypes2, fieldTypes2, init_types22, SAFE_HTML_TAGS2, COMPONENT_NAME2, MDX_BINDINGS2, FORBIDDEN_ATTRIBUTES2, init_mdx_allowlist2, fieldBaseSchema2, selectOptionSchema2, referenceOptionSchema2, primitiveFieldSchema2, mdxPropAllowSchema2, mdxAllowlistSchema2, markdownFieldSchema2, ASPECT_RATIO_RE2, imageFieldSchema2, selectFieldSchema2, referenceSortFieldSchema2, referenceFieldSchema2, fieldHolder2, blockSchema2, blockFieldSchema2, objectFieldSchema2, inlineGroupFieldSchema2, customFieldSchema2, knownFieldSchema2, fieldSchema2, init_field2, relativePathSchema2, entryTypeSchema2, collectionSchema2, init_collection2, uploadTargetUrlSchema2, previewPrefixSchema2, editorUrlSchema2, init_url2, mediaSchema2, init_media2, defaultBranchAccessSchema2, defaultPathAccessLevelSchema2, defaultPathAccessLevelsSchema2, defaultPathAccessSchema2, defaultBaseBranchSchema2, defaultRemoteNameSchema2, defaultRemoteUrlSchema2, gitBotAuthorNameSchema2, gitBotAuthorEmailSchema2, githubTokenEnvVarSchema2, operatingModeSchema2, deployedAsSchema2, contentRootSchema2, sourceRootSchema2, basePathSchema2, deploymentNameSchema2, devContentSyncSchema2, devConfigSchema2, editorConfigSchema2, seoFieldNameSchema2, seoSchema2, CanopyConfigSchema2, DEFAULT_PROD_WORKSPACE2, init_config3, SERVER_MODE_ENV_VAR, BROWSER_MODE_ENV_VAR, warned22, init_mode_env, forEachReferenceField, init_validation2, ProdClientSafeStrategy2, DevClientSafeStrategy2, clientStrategyCache, init_client_safe_strategy, warned3, VALID_DEPLOYMENT_NAME2, isValidDeploymentName2, init_deployment_name, warned4, DEPLOYMENT_PLACEHOLDER2, DEFAULT_BRANCH_NAMESPACE_TEMPLATE2, BRANCH_NAMESPACE_ENV2, init_branch_namespace, init_config22, ProdStrategy2, DevStrategy2, strategyCache2, init_client_unsafe_strategy, operating_mode_exports, init_operating_mode, task_queue_config_exports2, init_task_queue_config2, worker_status_exports, WORKER_STATUS_FILE, init_worker_status, BLOCK_DISCRIMINATOR_KEYS, BLOCK_STRUCTURAL_KEYS, envFlag2, LOG_LEVELS2, DebugLogger2, testLogger2, MARKDOWN_EXPORT_OPTIONS, BULLETS, DELIMITERS, EMPHASIS, STRONG, RULE, WORD_CHAR, GAP, Restyler, END, FRESH, LINE_WIDTH, MIN_LINE_WIDTH, SourceSplicer, log2, MAX_LCS_CELLS, Splicer, log22, EVIDENCE_MAX_DEPTH, log3, locks, PROVISIONING_LOCK_STALE_MS, sleep, META_DIR, CONTENT_WRITE_LOCK_NAME, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, ContentWriteLockBusyError, sleep2, CONTENT_WRITE_LOCK_STALE_MS, heldRoots, getFormatExtension, isDataOnlyFormat, asRecord, DEFAULT_SEO_FIELD_NAMES, asRecord2, asText, asFlag, asImageUrl, asOgType, asTwitterCard, RESTRICTED_REFERENCE_MARKER, SEO_GROUP_FIELDS, MAX_WARNED, warned5, SchemaUnavailableError, isValidId, parseTypedFilename, EMPTY_LOGICAL_PATH, ENTRY_EXTENSIONS, ContentIdIndex, CONTENT_EXTENSIONS, registry, finalization, log4, META_DIR2, entryTypeMetaSchema, collectionMetaSchema, rootCollectionMetaSchema, fingerprints, editDistance, closestName, forEachEntryType, collectEntryTypeNames, validateReferenceEntryTypes, isDeployedStatic, isBuildMode, readsFromCheckout, STATIC_DEPLOY_USER, storage, log5, BaseBranchUnresolvedError, NETWORK_SCHEME_PATTERN, TRANSPORT_HELPER_PATTERN, LEADING_OPTION_PATTERN, WINDOWS_DRIVE_PATTERN, COLON_BEFORE_SLASH_PATTERN, MISSING_REMOTE_REF_REASONS, CANOPY_META_DIR, SCHEMA_CACHE_VERSION, MTIME_CHECK_DEBOUNCE_MS, SCHEMA_CACHE_FILE, SCHEMA_GENERATION_RESOURCE, reportedIssues, BranchSchemaCache, RESOURCE, BranchPathError, resolveContentBranchesRoot, ContentStoreError, ContentConflictError, EntryGoneError, BranchSyncingError, DuplicateContentIdError, UrlPathConflictError, isEmptyFieldValue, DEFAULT_INDEX_FRESHNESS_INTERVAL_MS, FORCED_REFRESH_MIN_INTERVAL_MS, STALE_LOOKUP, isMissingReference, createReferenceResolveCache, ContentStore, ATTR_CONTENT, BLOCK_PREFIX, BLOCK_SUFFIX, BLOCK_RESTORE_RE, INLINE_PREFIX, INLINE_SUFFIX, INLINE_RESTORE_RE, DEFAULT_REFERENCE_RENDERING, FLAT_CELL_TYPES, log6, BASE58_CHAR, ENTRY_LINK_PATTERN, INLINE_LINK_TARGET, BranchMetadataCorruptError, BRANCH_META_DIR, BRANCH_META_FILE, branchMetadataFilePath, UNKNOWN_TIME, enumOf, branchMetadataShape, branchMetadataSchema, branchMetadataFileSchema, log7, REGISTRY_FILE, REGISTRY_STALE_FILE, REGISTRY_TEMP_FILE, REGISTRY_VERSION, RESOURCE2, GET_MISS_REFRESH_MIN_INTERVAL_MS, snapshotSchema, reportedUnreadable, BranchRegistry, log8, OccWriteConflictError, CURRENT_SCHEMA_VERSION, BranchMetadataConflictError, BranchMetadataFileManager, loadBranchContext, GitProcessError, STDERR_CAP_BYTES, KILL_GRACE_MS, log9, GIT_ENV_PASSTHROUGH, FORCE_C_LOCALE, GIT_NETWORK_ENV_PASSTHROUGH, NO_AUTO_GC_CONFIG, HASH_INACTIVITY_TIMEOUT_MS, MAX_HASH_RUNS, LS_REMOTE_INACTIVITY_TIMEOUT_MS, symlinkBlobSha, REMOTE_GIT_CONFIG, REMOTE_GIT_MAX_LOOSE_OBJECTS, REMOTE_GIT_MAX_PACKS, PARALLEL_CHECKOUT_ARGS, remoteInitLocks, GITHUB_TRACKING_REF_PREFIX, BaseBranchMissingError, GitConflictError, GitRemoteRefMissingError, RemoteNotReadyError, SettingsRemoteUnreadableError, SettingsBranchDivergedError, SETTINGS_BRANCH_FILES, SettingsBranchHasContentHistoryError, GitManager, PUBLISH_LOCK_WAIT_MS, CREATE_RESIDUE_MIN_QUIET_MS, STAGING_MAX_AGE_MS, REPAIR_MAX_AGE_MS, DELETING_MAX_AGE_MS, SETTINGS_TRASH_MAX_AGE_MS, BranchProvisioningBusyError, BranchDirOccupiedError, STAGING_PREFIX, REPAIR_PREFIX, TRASH_PREFIX, stagingDirName, NO_GIT, RENAME_BLOCKED, SPARSE_CONE_RECORD, defaultSink, sink, ProvisionLog, testHooks, provisionsInFlight, BranchWorkspaceManager, log10, normalizePath, parseEntryParts, parseEntryData, readEntryData, createReferenceResolver, withoutUnavailableEntries, resolveCollectionItemReferences, looksLikeMalformedEntry, listCollectionEntries, MAX_INPUT_PIXELS, CROP_PRECISION, KNOWN_FIELD_TYPES, STRING_FIELD_TYPES, selectOptionValues, GENERATED_RECORD_FILENAME, SAFE_BUILD_ID, BUILD_ID_RULE, jiti;
+var __defProp3, __getOwnPropNames3, __esm3, __export3, init_error3, init_atomic_write2, init_field_traversal, ITEM_KEY, ITEM_KEY_PATTERN, isItemKey, BASE58, isListField, init_item_keys, active2, init_logger2, SENTINEL_BASE2, DOT_SEGMENT2, init_sanitize_href2, init_normalize, RESERVED_SETTINGS_BRANCH_PREFIX2, init_branch_name, BASE58_PATTERN2, CONTENT_ID_PATTERN2, PHYSICAL_SEGMENT_PATTERN2, MAX_BRANCH_NAME_LENGTH2, init_validation, ROOT_COLLECTION_ID, init_types2, normalizePathValue, flattenSchema, init_flatten, scalarFieldTypes2, markdownFieldTypes2, primitiveFieldTypes2, fieldTypes2, init_types22, SAFE_HTML_TAGS2, COMPONENT_NAME2, MDX_BINDINGS2, FORBIDDEN_ATTRIBUTES2, init_mdx_allowlist2, fieldBaseSchema2, selectOptionSchema2, referenceOptionSchema2, primitiveFieldSchema2, mdxPropAllowSchema2, mdxAllowlistSchema2, markdownFieldSchema2, ASPECT_RATIO_RE2, imageFieldSchema2, selectFieldSchema2, referenceSortFieldSchema2, referenceFieldSchema2, fieldHolder2, blockSchema2, blockFieldSchema2, objectFieldSchema2, inlineGroupFieldSchema2, customFieldSchema2, knownFieldSchema2, fieldSchema2, init_field2, relativePathSchema2, entryTypeSchema2, collectionSchema2, init_collection2, uploadTargetUrlSchema2, previewPrefixSchema2, editorUrlSchema2, init_url2, mediaSchema2, init_media2, defaultBranchAccessSchema2, defaultPathAccessLevelSchema2, defaultPathAccessLevelsSchema2, defaultPathAccessSchema2, defaultBaseBranchSchema2, defaultRemoteNameSchema2, defaultRemoteUrlSchema2, gitBotAuthorNameSchema2, gitBotAuthorEmailSchema2, githubTokenEnvVarSchema2, operatingModeSchema2, deployedAsSchema2, contentRootSchema2, sourceRootSchema2, basePathSchema2, deploymentNameSchema2, devContentSyncSchema2, devConfigSchema2, editorConfigSchema2, seoFieldNameSchema2, seoSchema2, CanopyConfigSchema2, DEFAULT_PROD_WORKSPACE2, init_config3, SERVER_MODE_ENV_VAR, BROWSER_MODE_ENV_VAR, warned22, init_mode_env, forEachReferenceField, init_validation2, ProdClientSafeStrategy2, DevClientSafeStrategy2, clientStrategyCache, init_client_safe_strategy, warned3, VALID_DEPLOYMENT_NAME2, isValidDeploymentName2, init_deployment_name, warned4, DEPLOYMENT_PLACEHOLDER2, DEFAULT_BRANCH_NAMESPACE_TEMPLATE2, BRANCH_NAMESPACE_ENV2, init_branch_namespace, init_config22, ProdStrategy2, DevStrategy2, strategyCache2, init_client_unsafe_strategy, operating_mode_exports, init_operating_mode, task_queue_config_exports2, init_task_queue_config2, worker_status_exports, WORKER_STATUS_FILE, init_worker_status, BLOCK_DISCRIMINATOR_KEYS, BLOCK_STRUCTURAL_KEYS, envFlag2, LOG_LEVELS2, DebugLogger2, testLogger2, MARKDOWN_EXPORT_OPTIONS, BULLETS, DELIMITERS, EMPHASIS, STRONG, RULE, WORD_CHAR, GAP, Restyler, END, FRESH, LINE_WIDTH, MIN_LINE_WIDTH, SourceSplicer, log2, MAX_LCS_CELLS, Splicer, log22, EVIDENCE_MAX_DEPTH, log3, locks, PROVISIONING_LOCK_STALE_MS, sleep, META_DIR, CONTENT_WRITE_LOCK_NAME, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, ContentWriteLockBusyError, sleep2, CONTENT_WRITE_LOCK_STALE_MS, heldRoots, getFormatExtension, isDataOnlyFormat, asRecord, DEFAULT_SEO_FIELD_NAMES, asRecord2, asText, asFlag, asImageUrl, asOgType, asTwitterCard, RESTRICTED_REFERENCE_MARKER, SEO_GROUP_FIELDS, MAX_WARNED, warned5, SchemaUnavailableError, isValidId, parseTypedFilename, EMPTY_LOGICAL_PATH, ENTRY_EXTENSIONS, ContentIdIndex, CONTENT_EXTENSIONS, registry, finalization, log4, META_DIR2, entryTypeMetaSchema, collectionMetaSchema, rootCollectionMetaSchema, fingerprints, editDistance, closestName, forEachEntryType, collectEntryTypeNames, validateReferenceEntryTypes, isDeployedStatic, isBuildMode, readsFromCheckout, STATIC_DEPLOY_USER, storage, log5, BaseBranchUnresolvedError, NETWORK_SCHEME_PATTERN, TRANSPORT_HELPER_PATTERN, LEADING_OPTION_PATTERN, WINDOWS_DRIVE_PATTERN, COLON_BEFORE_SLASH_PATTERN, MISSING_REMOTE_REF_REASONS, CANOPY_META_DIR, SCHEMA_CACHE_VERSION, MTIME_CHECK_DEBOUNCE_MS, SNAPSHOT_MEMO_MAX_BYTES, SCHEMA_CACHE_FILE, SCHEMA_GENERATION_RESOURCE, reportedIssues, BranchSchemaCache, RESOURCE, BranchPathError, resolveContentBranchesRoot, ContentStoreError, ContentConflictError, EntryGoneError, BranchSyncingError, DuplicateContentIdError, UrlPathConflictError, isEmptyFieldValue, DEFAULT_INDEX_FRESHNESS_INTERVAL_MS, FORCED_REFRESH_MIN_INTERVAL_MS, STALE_LOOKUP, isMissingReference, createReferenceResolveCache, ContentStore, ATTR_CONTENT, BLOCK_PREFIX, BLOCK_SUFFIX, BLOCK_RESTORE_RE, INLINE_PREFIX, INLINE_SUFFIX, INLINE_RESTORE_RE, DEFAULT_REFERENCE_RENDERING, FLAT_CELL_TYPES, log6, BASE58_CHAR, ENTRY_LINK_PATTERN, INLINE_LINK_TARGET, BranchMetadataCorruptError, BRANCH_META_DIR, BRANCH_META_FILE, branchMetadataFilePath, UNKNOWN_TIME, enumOf, branchMetadataShape, branchMetadataSchema, branchMetadataFileSchema, log7, REGISTRY_FILE, REGISTRY_STALE_FILE, REGISTRY_TEMP_FILE, REGISTRY_VERSION, RESOURCE2, GET_MISS_REFRESH_MIN_INTERVAL_MS, snapshotSchema, reportedUnreadable, BranchRegistry, log8, OccWriteConflictError, CURRENT_SCHEMA_VERSION, BranchMetadataConflictError, BranchMetadataFileManager, loadBranchContext, GitProcessError, STDERR_CAP_BYTES, KILL_GRACE_MS, log9, GIT_ENV_PASSTHROUGH, FORCE_C_LOCALE, GIT_NETWORK_ENV_PASSTHROUGH, NO_AUTO_GC_CONFIG, HASH_INACTIVITY_TIMEOUT_MS, MAX_HASH_RUNS, LS_REMOTE_INACTIVITY_TIMEOUT_MS, symlinkBlobSha, REMOTE_GIT_CONFIG, REMOTE_GIT_MAX_LOOSE_OBJECTS, REMOTE_GIT_MAX_PACKS, PARALLEL_CHECKOUT_ARGS, remoteInitLocks, GITHUB_TRACKING_REF_PREFIX, BaseBranchMissingError, GitConflictError, GitRemoteRefMissingError, RemoteNotReadyError, SettingsRemoteUnreadableError, SettingsBranchDivergedError, SETTINGS_BRANCH_FILES, SettingsBranchHasContentHistoryError, GitManager, PUBLISH_LOCK_WAIT_MS, CREATE_RESIDUE_MIN_QUIET_MS, STAGING_MAX_AGE_MS, REPAIR_MAX_AGE_MS, DELETING_MAX_AGE_MS, SETTINGS_TRASH_MAX_AGE_MS, BranchProvisioningBusyError, BranchDirOccupiedError, STAGING_PREFIX, REPAIR_PREFIX, TRASH_PREFIX, stagingDirName, NO_GIT, RENAME_BLOCKED, SPARSE_CONE_RECORD, defaultSink, sink, ProvisionLog, testHooks, provisionsInFlight, BranchWorkspaceManager, log10, normalizePath, parseEntryParts, parseEntryData, readEntryData, createReferenceResolver, withoutUnavailableEntries, resolveCollectionItemReferences, looksLikeMalformedEntry, listCollectionEntries, MAX_INPUT_PIXELS, CROP_PRECISION, KNOWN_FIELD_TYPES, STRING_FIELD_TYPES, selectOptionValues, GENERATED_RECORD_FILENAME, SAFE_BUILD_ID, BUILD_ID_RULE, jiti;
 var init_generate_ai_content = __esm({
   "dist/cli/generate-ai-content.js"() {
     "use strict";
@@ -10878,12 +10882,18 @@ var init_generate_ai_content = __esm({
     init_logger2();
     SCHEMA_CACHE_VERSION = 4;
     MTIME_CHECK_DEBOUNCE_MS = 1e3;
+    SNAPSHOT_MEMO_MAX_BYTES = 64 * 1024 * 1024;
     SCHEMA_CACHE_FILE = "schema-cache.json";
     SCHEMA_GENERATION_RESOURCE = "schema";
     reportedIssues = /* @__PURE__ */ new Set();
     BranchSchemaCache = class {
       constructor(mode = "prod") {
         this.lastMtimeCheck = /* @__PURE__ */ new Map();
+        this.snapshots = new LRUCache({
+          maxSize: SNAPSHOT_MEMO_MAX_BYTES,
+          sizeCalculation: (snapshot) => Math.max(1, snapshot.bytes)
+        });
+        this.buildResolves = /* @__PURE__ */ new Map();
         this.devMode = mode === "dev";
       }
       /**
@@ -10913,15 +10923,12 @@ var init_generate_ai_content = __esm({
       async loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName) {
         const contentRoot = path82.join(branchRoot, contentRootName);
         const fromCheckout = this.readsCheckout(branchRoot);
+        if (fromCheckout && isBuildMode()) {
+          return this.resolveForBuild(branchRoot, entrySchemaRegistry, contentRootName);
+        }
         if (!fromCheckout) {
           const cachePath = path82.join(await schemaCacheDir(branchRoot), SCHEMA_CACHE_FILE);
-          let cacheData = null;
-          try {
-            const cacheContent = await fs72.readFile(cachePath, "utf-8");
-            cacheData = JSON.parse(cacheContent);
-          } catch {
-            cacheData = null;
-          }
+          let cacheData = await this.readSnapshot(cachePath);
           if (cacheData && cacheData.version === SCHEMA_CACHE_VERSION && cacheData.registryFingerprint === registryFingerprint(entrySchemaRegistry)) {
             const read = await readResourceGeneration(branchRoot, SCHEMA_GENERATION_RESOURCE);
             if (isGenerationCurrent(cacheData.generation, read)) {
@@ -10951,6 +10958,42 @@ var init_generate_ai_content = __esm({
           fromCheckout
         });
       }
+      resolveForBuild(branchRoot, entrySchemaRegistry, contentRootName) {
+        const key = `${path82.resolve(branchRoot, contentRootName)}\0${registryFingerprint(entrySchemaRegistry)}`;
+        let pending = this.buildResolves.get(key);
+        if (!pending) {
+          pending = this.resolveFreshAndPersist(branchRoot, entrySchemaRegistry, contentRootName, {
+            fromCheckout: true
+          });
+          this.buildResolves.set(key, pending);
+          pending.catch(() => this.buildResolves.delete(key));
+        }
+        return pending;
+      }
+      /** The parsed cache file, or null when it is absent or unreadable. */
+      async readSnapshot(cachePath) {
+        let handle;
+        try {
+          handle = await fs72.open(cachePath, "r");
+        } catch {
+          return null;
+        }
+        try {
+          const stat = await handle.stat({ bigint: true });
+          const identity = fileIdentity(stat);
+          const memo = this.snapshots.get(cachePath);
+          if (memo?.identity === identity)
+            return memo.entry;
+          const entry = JSON.parse(await fs72.readFile(handle, "utf-8"));
+          this.snapshots.set(cachePath, { identity, entry, bytes: Number(stat.size) });
+          return entry;
+        } catch {
+          return null;
+        } finally {
+          await handle.close().catch(() => {
+          });
+        }
+      }
       /**
        * Resolve the schema fresh from disk and persist it (subject to the
        * skip-persist rule below), UNCONDITIONALLY -- never through the cache-read
@@ -10992,14 +11035,22 @@ var init_generate_ai_content = __esm({
             };
             await fs72.mkdir(cacheDir, { recursive: true });
             const tmpPath = path82.join(cacheDir, `schema-cache.tmp.${Date.now()}.${Math.random()}.json`);
-            await fs72.writeFile(tmpPath, JSON.stringify(newCache, null, 2), "utf-8");
+            const body = JSON.stringify(newCache);
+            let identity;
             try {
+              await fs72.writeFile(tmpPath, body, "utf-8");
+              identity = fileIdentity(await fs72.stat(tmpPath, { bigint: true }));
               await fs72.rename(tmpPath, cachePath);
             } catch (err2) {
               await fs72.unlink(tmpPath).catch(() => {
               });
               throw err2;
             }
+            this.snapshots.set(cachePath, {
+              identity,
+              entry: JSON.parse(body),
+              bytes: Buffer.byteLength(body)
+            });
           }
         }
         reportSchemaIssues(issues);
@@ -18064,10 +18115,12 @@ var init_meta_loader = __esm({
 });
 
 // dist/branch-schema-cache.js
-var SCHEMA_GENERATION_RESOURCE2;
+import { LRUCache as LRUCache2 } from "lru-cache";
+var SNAPSHOT_MEMO_MAX_BYTES2, SCHEMA_GENERATION_RESOURCE2;
 var init_branch_schema_cache = __esm({
   "dist/branch-schema-cache.js"() {
     "use strict";
+    SNAPSHOT_MEMO_MAX_BYTES2 = 64 * 1024 * 1024;
     SCHEMA_GENERATION_RESOURCE2 = "schema";
   }
 });

package/dist/cli/generate-ai-content.js

@@ -4443,6 +4443,7 @@ function isGenerationCurrent(snapshotToken, read) {
 // dist/branch-schema-cache.js
 import fs7 from "node:fs/promises";
 import path8 from "node:path";
+import { LRUCache } from "lru-cache";
 
 // dist/schema/meta-loader.js
 import { promises as fs6 } from "fs";
@@ -4902,6 +4903,7 @@ async function resolveBaseBranch(options) {
 init_logger();
 var SCHEMA_CACHE_VERSION = 4;
 var MTIME_CHECK_DEBOUNCE_MS = 1e3;
+var SNAPSHOT_MEMO_MAX_BYTES = 64 * 1024 * 1024;
 var SCHEMA_CACHE_FILE = "schema-cache.json";
 var SCHEMA_GENERATION_RESOURCE = "schema";
 var reportedIssues = /* @__PURE__ */ new Set();
@@ -4935,6 +4937,9 @@ async function isStaleByMtime(dir, cachedAt) {
   }
   return false;
 }
+function fileIdentity(stat) {
+  return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}`;
+}
 async function schemaCacheDir(branchRoot) {
   const gitDir = path8.join(branchRoot, ".git");
   const isClone = await fs7.stat(gitDir).then((stat) => stat.isDirectory(), () => false);
@@ -4943,6 +4948,11 @@ async function schemaCacheDir(branchRoot) {
 var BranchSchemaCache = class {
   constructor(mode = "prod") {
     this.lastMtimeCheck = /* @__PURE__ */ new Map();
+    this.snapshots = new LRUCache({
+      maxSize: SNAPSHOT_MEMO_MAX_BYTES,
+      sizeCalculation: (snapshot) => Math.max(1, snapshot.bytes)
+    });
+    this.buildResolves = /* @__PURE__ */ new Map();
     this.devMode = mode === "dev";
   }
   /**
@@ -4972,15 +4982,12 @@ var BranchSchemaCache = class {
   async loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName) {
     const contentRoot = path8.join(branchRoot, contentRootName);
     const fromCheckout = this.readsCheckout(branchRoot);
+    if (fromCheckout && isBuildMode()) {
+      return this.resolveForBuild(branchRoot, entrySchemaRegistry, contentRootName);
+    }
     if (!fromCheckout) {
       const cachePath = path8.join(await schemaCacheDir(branchRoot), SCHEMA_CACHE_FILE);
-      let cacheData = null;
-      try {
-        const cacheContent = await fs7.readFile(cachePath, "utf-8");
-        cacheData = JSON.parse(cacheContent);
-      } catch {
-        cacheData = null;
-      }
+      let cacheData = await this.readSnapshot(cachePath);
       if (cacheData && cacheData.version === SCHEMA_CACHE_VERSION && cacheData.registryFingerprint === registryFingerprint(entrySchemaRegistry)) {
         const read = await readResourceGeneration(branchRoot, SCHEMA_GENERATION_RESOURCE);
         if (isGenerationCurrent(cacheData.generation, read)) {
@@ -5010,6 +5017,42 @@ var BranchSchemaCache = class {
       fromCheckout
     });
   }
+  resolveForBuild(branchRoot, entrySchemaRegistry, contentRootName) {
+    const key = `${path8.resolve(branchRoot, contentRootName)}\0${registryFingerprint(entrySchemaRegistry)}`;
+    let pending = this.buildResolves.get(key);
+    if (!pending) {
+      pending = this.resolveFreshAndPersist(branchRoot, entrySchemaRegistry, contentRootName, {
+        fromCheckout: true
+      });
+      this.buildResolves.set(key, pending);
+      pending.catch(() => this.buildResolves.delete(key));
+    }
+    return pending;
+  }
+  /** The parsed cache file, or null when it is absent or unreadable. */
+  async readSnapshot(cachePath) {
+    let handle;
+    try {
+      handle = await fs7.open(cachePath, "r");
+    } catch {
+      return null;
+    }
+    try {
+      const stat = await handle.stat({ bigint: true });
+      const identity = fileIdentity(stat);
+      const memo = this.snapshots.get(cachePath);
+      if (memo?.identity === identity)
+        return memo.entry;
+      const entry = JSON.parse(await fs7.readFile(handle, "utf-8"));
+      this.snapshots.set(cachePath, { identity, entry, bytes: Number(stat.size) });
+      return entry;
+    } catch {
+      return null;
+    } finally {
+      await handle.close().catch(() => {
+      });
+    }
+  }
   /**
    * Resolve the schema fresh from disk and persist it (subject to the
    * skip-persist rule below), UNCONDITIONALLY -- never through the cache-read
@@ -5051,14 +5094,22 @@ var BranchSchemaCache = class {
         };
         await fs7.mkdir(cacheDir, { recursive: true });
         const tmpPath = path8.join(cacheDir, `schema-cache.tmp.${Date.now()}.${Math.random()}.json`);
-        await fs7.writeFile(tmpPath, JSON.stringify(newCache, null, 2), "utf-8");
+        const body = JSON.stringify(newCache);
+        let identity;
         try {
+          await fs7.writeFile(tmpPath, body, "utf-8");
+          identity = fileIdentity(await fs7.stat(tmpPath, { bigint: true }));
           await fs7.rename(tmpPath, cachePath);
         } catch (err) {
           await fs7.unlink(tmpPath).catch(() => {
           });
           throw err;
         }
+        this.snapshots.set(cachePath, {
+          identity,
+          entry: JSON.parse(body),
+          bytes: Buffer.byteLength(body)
+        });
       }
     }
     reportSchemaIssues(issues);

package/dist/content-reader.d.ts

@@ -89,20 +89,34 @@ export interface ContentReadMeta {
     /** The entry's URL path with no query, by the rule `listEntries` uses. */
     urlPath: string;
 }
+/** What a content read resolves to. */
+export interface ContentReadResult<T = unknown> {
+    data: T;
+    /**
+     * The requested `entryPath` and slug as a percent-encoded URL path, plus `?branch=<name>`.
+     * Through an entry-type `entryPath` it is not the entry's URL. Compare entries by
+     * `meta.urlPath`.
+     */
+    path: string;
+    meta: ContentReadMeta;
+}
 export interface ContentReader {
-    read: <T = unknown>(input: ReadContentInput, message?: string) => Promise<{
-        data: T;
-        /**
-         * The requested `entryPath` and slug as a percent-encoded URL path, plus `?branch=<name>`.
-         * Through an entry-type `entryPath` it is not the entry's URL. Compare entries by
-         * `meta.urlPath`.
-         */
-        path: string;
-        meta: ContentReadMeta;
-    }>;
+    read: <T = unknown>(input: ReadContentInput, message?: string) => Promise<ContentReadResult<T>>;
+}
+/** @internal The reader `CanopyContext` (context.ts) builds on. */
+export interface ContentReaderInternal extends ContentReader {
+    /**
+     * Read the first of `inputs` that resolves, against one store resolved once for their branch,
+     * so a lookup trying several paths resolves the branch and its schema once. Every input must
+     * name the same branch and user. An error `isMiss` accepts moves on to the next input; null
+     * when every input misses, or when resolving the branch itself throws a miss.
+     */
+    readFirst: <T = unknown>(inputs: readonly ReadContentInput[], isMiss: (err: unknown, input: ReadContentInput) => boolean) => Promise<ContentReadResult<T> | null>;
 }
 /**
  * Server-side helper to read content directly from a branch workspace. A branch with no workspace
  * reads as NOT_FOUND unless `allowCreateBranch` or a `getBranchContext` resolver says otherwise.
  */
 export declare const createContentReader: (options: ContentReaderOptions) => ContentReader;
+/** @internal {@link createContentReader} plus `readFirst`, for context.ts. */
+export declare const createContentReaderInternal: (options: ContentReaderOptions) => ContentReaderInternal;

package/dist/content-reader.js

@@ -16,6 +16,11 @@ import { CONTENT_READER_USER_ID } from './system-users.js';
  * reads as NOT_FOUND unless `allowCreateBranch` or a `getBranchContext` resolver says otherwise.
  */
 export const createContentReader = (options) => {
+    const { read } = createContentReaderInternal(options);
+    return { read };
+};
+/** @internal {@link createContentReader} plus `readFirst`, for context.ts. */
+export const createContentReaderInternal = (options) => {
     const services = options.services;
     const operatingMode = services.config.mode;
     const basePathOverride = options.basePathOverride;
@@ -127,9 +132,9 @@ export const createContentReader = (options) => {
         const url = encodedSlug ? `${trimmed}/${encodedSlug}` : trimmed || '/';
         return appendBranch(url);
     };
-    const readDocument = async (input) => {
-        const { entryPath, slug, branchName, user } = resolveTarget(input);
-        const { context, branchRoot, store } = await resolveStore(branchName);
+    const readDocument = async (input, resolved) => {
+        const { entryPath, slug, user } = resolveTarget(input);
+        const { context, branchRoot, store } = resolved;
         // Rule 1 of urlAddressableOnly (see ReadContentInput): a published URL's non-slug segments
         // are collection names, so a candidate landing on an entry-TYPE item can only ever produce a
         // URL enumeration never emits. NO_SCHEMA_ITEM is what assertCollection raises for exactly
@@ -216,9 +221,9 @@ export const createContentReader = (options) => {
             throw err;
         }
     };
-    const read = async (input, message) => {
+    const readResolved = async (input, resolved, message) => {
         const { entryPath, slug, branchName } = resolveTarget(input);
-        const result = await readDocument(input);
+        const result = await readDocument(input, resolved);
         if (!result || typeof result.doc !== 'object' || !('data' in result.doc)) {
             const defaultMessage = `Content not found for ${entryPath}${slug ? `/${slug}` : ''} on branch ${branchName}`;
             throw new ContentStoreError(message ?? defaultMessage, 'NOT_FOUND');
@@ -242,5 +247,37 @@ export const createContentReader = (options) => {
         });
         return { data, path, meta: { physicalPath, entryType, entryId, slug: entrySlug, urlPath } };
     };
-    return { read };
+    const read = async (input, message) => {
+        const { branchName } = resolveTarget(input);
+        return readResolved(input, await resolveStore(branchName), message);
+    };
+    const readFirst = async (inputs, isMiss) => {
+        const [first] = inputs;
+        if (!first)
+            return null;
+        if (inputs.some((input) => input.branch !== first.branch || input.user !== first.user)) {
+            throw new Error('readFirst: every input must name the same branch and user');
+        }
+        let resolved;
+        try {
+            resolved = await resolveStore(resolveTarget(first).branchName);
+        }
+        catch (err) {
+            if (isMiss(err, first))
+                return null;
+            throw err;
+        }
+        for (const input of inputs) {
+            try {
+                return await readResolved(input, resolved);
+            }
+            catch (err) {
+                if (isMiss(err, input))
+                    continue;
+                throw err;
+            }
+        }
+        return null;
+    };
+    return { read, readFirst };
 };

package/dist/context.js

@@ -1,5 +1,5 @@
 import { isDeployedStatic, isBuildMode, readsFromCheckout, STATIC_DEPLOY_USER } from './build-mode.js';
-import { createContentReader } from './content-reader.js';
+import { createContentReaderInternal } from './content-reader.js';
 import { ContentStoreError } from './content-store.js';
 import { createLogicalPath, namesNoWorkspace, parseSlug, resolveBranchPaths, } from './paths/index.js';
 import { resolveUrlPathCandidates } from './url-path-resolver.js';
@@ -129,7 +129,7 @@ export function createCanopyContext(options) {
         };
         // The reader resolves every branch through resolveBranch; a null reads as
         // NOT_FOUND. Reads from the checkout bypass the resolver inside the reader.
-        const baseReader = createContentReader({
+        const baseReader = createContentReaderInternal({
             services,
             defaultBranch: activeBranch,
             getBranchContext: (branchName) => resolveBranch(otherBranch(branchName)),
@@ -140,7 +140,7 @@ export function createCanopyContext(options) {
         // function rather than an optional second parameter on the
         // `CanopyContext['read']`-typed closure, so the two call sites stay visible
         // and nobody widens the public API by accident.
-        const readWithOptions = async (input, extra) => {
+        const toReadInput = (input, extra) => {
             const entryPath = createLogicalPath(input.entryPath);
             let slug;
             if (input.slug) {
@@ -161,53 +161,55 @@ export function createCanopyContext(options) {
                 resolveReferences: input.resolveReferences ?? true,
                 ...extra,
             };
-            return baseReader.read(readInput);
+            return readInput;
         };
-        const read = (input) => readWithOptions(input);
+        const read = async (input) => baseReader.read(toReadInput(input));
         const readByUrlPath = async (urlPath, options) => {
             const contentRoot = services.config.contentRoot || 'content';
             const candidates = resolveUrlPathCandidates(urlPath, contentRoot);
             if (candidates.length === 0)
                 return null;
             const { branch, resolveReferences } = options ?? {};
-            for (const candidate of candidates) {
-                // Skip a candidate whose slug isn't valid (/favicon.ico, Next internals
-                // the [...slug] route catches). None can match an entry, so treat it as
-                // a miss rather than let read() throw "Invalid slug".
-                if (!parseSlug(candidate.slug).ok)
-                    continue;
-                try {
-                    return await readWithOptions({
-                        entryPath: candidate.entryPath,
-                        slug: candidate.slug,
-                        branch,
-                        resolveReferences,
-                    }, 
-                    // A read BY PUBLISHED URL accepts only what listEntries publishes.
-                    // See ReadContentInput.urlAddressableOnly for the two rules, and
-                    // why they live in the reader (which holds the branch-correct
-                    // schema) rather than the candidate builder (pure and schema-free).
-                    { urlAddressableOnly: true });
-                }
-                catch (err) {
-                    // Swallow a candidate path's "not found", and FORBIDDEN so a denied
-                    // or anonymous read renders as the adopter's 404 rather than an
-                    // unhandled 500. Real errors (validation, corruption, anything not a
-                    // ContentStoreError) rethrow.
-                    if (err instanceof ContentStoreError && isPageSwallowable(err)) {
-                        if (err.code === 'FORBIDDEN') {
-                            log.debug('readByUrlPath', 'Read denied, treating as not-found: ' + err.message, {
-                                urlPath,
-                                entryPath: candidate.entryPath,
-                                slug: candidate.slug,
-                            });
-                        }
-                        continue;
-                    }
-                    throw err;
+            // Swallow a candidate path's "not found", and FORBIDDEN so a denied or
+            // anonymous read renders as the adopter's 404 rather than an unhandled
+            // 500. Real errors (validation, corruption, anything not a
+            // ContentStoreError) rethrow.
+            const isMiss = (err, input) => {
+                if (!(err instanceof ContentStoreError && isPageSwallowable(err)))
+                    return false;
+                if (err.code === 'FORBIDDEN') {
+                    log.debug('readByUrlPath', 'Read denied, treating as not-found: ' + err.message, {
+                        urlPath,
+                        entryPath: input?.entryPath,
+                        slug: input?.slug,
+                    });
                 }
+                return true;
+            };
+            // Converting every candidate up front throws nothing a candidate-by-candidate
+            // loop would not: a valid slug holds no `..`, so the index candidate's path
+            // fails createLogicalPath only when the entry candidate's does.
+            let inputs;
+            try {
+                inputs = candidates
+                    // Skip a candidate whose slug isn't valid (/favicon.ico, Next internals
+                    // the [...slug] route catches). None can match an entry, so treat it as
+                    // a miss rather than let read() throw "Invalid slug".
+                    .filter((candidate) => parseSlug(candidate.slug).ok)
+                    .map((candidate) => toReadInput({ entryPath: candidate.entryPath, slug: candidate.slug, branch, resolveReferences }, 
+                // A read BY PUBLISHED URL accepts only what listEntries publishes.
+                // See ReadContentInput.urlAddressableOnly for the two rules, and
+                // why they live in the reader (which holds the branch-correct
+                // schema) rather than the candidate builder (pure and schema-free).
+                { urlAddressableOnly: true }));
             }
-            return null;
+            catch (err) {
+                if (isMiss(err))
+                    return null;
+                throw err;
+            }
+            // One branch and schema resolve for every candidate.
+            return baseReader.readFirst(inputs, isMiss);
         };
         /**
          * What a batch read (listEntries / buildContentTree) lists from: the branch's

package/dist/server.d.ts

@@ -1,4 +1,9 @@
-export * from './content-reader.js';
+/**
+ * The lower-level reader under `CanopyContext.read`: reads one entry from a branch as a user
+ * the caller passes explicitly, checking that user's read access first except in a static
+ * deployment or a build. See README.md, "Advanced: Using createContentReader Directly".
+ */
+export { createContentReader, type ContentReader, type ContentReaderOptions, type ContentReadMeta, type ContentReadResult, type ReadContentInput, } from './content-reader.js';
 export * from './services.js';
 export * from './build-mode.js';
 export * from './context.js';

package/dist/server.js

@@ -2,7 +2,12 @@
 // TypeScript's propagation through `export { X } from './module.js'` is inconsistent across LSP
 // versions and module-resolution modes and adopters would otherwise get no hover text. Follow the
 // pattern for new top-level public re-exports (see DEVELOPING.md).
-export * from './content-reader.js';
+/**
+ * The lower-level reader under `CanopyContext.read`: reads one entry from a branch as a user
+ * the caller passes explicitly, checking that user's read access first except in a static
+ * deployment or a build. See README.md, "Advanced: Using createContentReader Directly".
+ */
+export { createContentReader, } from './content-reader.js';
 export * from './services.js';
 export * from './build-mode.js';
 export * from './context.js';

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CANOPYCMS_VERSION = "0.8.0";
+export declare const CANOPYCMS_VERSION = "0.8.1";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/bump-version.mjs, its only writer. The package builds with plain
 // tsc (rootDir: src), so src/ cannot import ../package.json; version.test.ts keeps the two equal.
-export const CANOPYCMS_VERSION = '0.8.0';
+export const CANOPYCMS_VERSION = '0.8.1';

package/dist/worker/github-gateway-wire.d.ts

@@ -424,14 +424,14 @@ declare const errorEnvelope: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
     message: string;
     reason: "settings" | "protected" | "invalid" | "other-settings" | "outside-namespace" | "not-a-commit" | "too-long";
     kind: "refusal";
-    operation: "push" | "pull-request" | "delete";
+    operation: "push" | "delete" | "pull-request";
 }, {
     branch: string;
     push: boolean;
     message: string;
     reason: "settings" | "protected" | "invalid" | "other-settings" | "outside-namespace" | "not-a-commit" | "too-long";
     kind: "refusal";
-    operation: "push" | "pull-request" | "delete";
+    operation: "push" | "delete" | "pull-request";
 }>, z.ZodObject<{
     kind: z.ZodLiteral<"push">;
     pushKind: z.ZodEnum<["rejected", "rejected-after-stale-lease"]>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@codemirror/language, @lezer/highlight: workaround — @mdxeditor/editor uses cm6-theme-basic-light which peer-requires these but mdxeditor doesn't declare them as dependencies",
   "name": "canopycms",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "CanopyCMS core package: schema-driven content, branch-aware editing, and editor UI for Next.js.",
   "license": "MIT",
   "repository": {