@voltro/cms 0.86.0 → 0.87.0

package/README.md

@@ -20,7 +20,145 @@ Installation, guides, the full API reference, and examples all live in the
 **[Voltro documentation](https://docs.voltro.dev/docs/intro/getting-started)** — the single source of truth. This README is
 deliberately short so there is nothing here to drift out of date.
 
+Private build consumers use the server entry `@voltro/cms/build`.
+`copyStaticPathManifest`, `staticPathHash` and `verifyStaticPathPage` reuse the
+framework's captured path-set integrity checks, including the empty first page
+of a zero-route set. The consumer still binds the authenticated response to its
+authorized snapshot/application; these helpers grant no publication authority.
+
 ## License
 
 Proprietary. © 2026 Voltro UG. Your use is governed by the
 [Terms of Service](https://voltro.cloud/legal/terms). See the bundled `LICENSE`.
+
+### Publication stream consistency
+
+Register `cmsChangesTable` and `cmsChangeHeadsTable` for every publication,
+including types without `changeFeed: true`. The flag controls event emission;
+all publication transitions share the scoped lock and advance an independent
+generation. Named releases also activate a generation when they have no items.
+Content writes allocate commit-ordered positions in the caller's transaction;
+`readChanges` requires an explicit tenant/site/environment scope. Event IDs
+remain opaque cursors. Unknown cursors and incomplete upgrades fail with
+`ChangeFeedUnavailable` instead of silently returning no changes.
+
+Archiving a visible published copy appends one take-down; repeating the archive
+or archiving only a draft adds none. With writers stopped, apply schema and
+initialize positions, then run `reconcileArchivedPublications(tx, types, scope)`
+as an Effect in a maintenance transaction to repair older missing take-downs.
+It uses bounded batches and appends at the current tail, without rewriting old
+cursors or fabricating archival dates. The repair is scoped and repeatable.
+Publication, release, scheduler, environment-copy, promotion, blueprint and duplicate-retirement
+Effects preserve `ChangeFeedUnavailable` as typed; procedure descriptors must
+declare it so a refusal rolls back rather than becoming an undeclared error.
+
+For existing history, stop writers, apply schema, then call the Effect
+`initializeChangeFeed(tx, scope)` inside a maintenance transaction for each
+stream. It preserves event IDs and uses bounded batches. Do not reset the
+internal sequence head. See the CMS guide and the shipped 0.86.0 upgrade note.
+
+`readChangeCheckpoint` captures the latest committed event ID. Pass it as
+`readChanges(..., { through, settleMs: 0 })` to bound a paginated catch-up scan
+despite later publishes or skewed writer clocks. The event range is pinned,
+not subsequent content reads. `readRecentChanges` supplies bounded history in
+descending commit order within the same explicit scope.
+
+### Atomic environment aliases
+
+Register `cmsEnvironmentAliasesTable` and `cmsEnvironmentAliasRevisionsTable`
+to route a stable tenant/site alias to a configured physical environment.
+`swapEnvironmentAlias` compares the observed revision under the caller's
+transaction; `rollbackEnvironmentAlias` appends a new revision targeting a
+previous one. Resolve once per request and retain the physical target. Unknown
+aliases never fall back. Procedure descriptors declare `EnvironmentAliasUnavailable`
+from `@voltro/cms/web`; authorization and the trusted environment registry belong
+to the application. See the CMS guide for the complete transaction contract.
+
+### Shared site delivery definition
+
+`defineSiteDelivery` and `compileSiteDelivery` are browser-safe exports from
+`@voltro/cms/web` (also available from the main entry). One frozen, versioned
+plain-data graph separates stable locale IDs, approved language tags and stored
+variant keys. API and frontend derive enabled locales, independent source/default
+locales, fallback chains and URL prefixes from it. Invalid graphs refuse with
+`SiteDeliveryUnavailable`; no tag inference, registry lookup or database write
+occurs. See the CMS guide for the contract and paired-template upgrade. Route
+creation, source migration and editorial locale lifecycle remain application work.
+
+### Explicit site content bindings
+
+Register `cmsSiteBindingsTable` and `cmsSiteBindingRevisionsTable` alongside the
+change-stream tables. `siteContentBinding` reads a named document identity in an
+explicit tenant/site/physical-environment scope. `bindSiteContent` compares an
+observed revision and requires a published target; it never chooses by timestamp.
+`siteContentBindingRevision` reads scoped history; `rollbackSiteContentBinding`
+appends a new revision. Changed bindings share the caller's publication transaction,
+advance its generation and clear the active release. Bind before release activation.
+The application owns authorization and delivery cache invalidation; no synthetic
+content event is emitted. Declare `SiteBindingUnavailable` and `ChangeFeedUnavailable`
+from `@voltro/cms/web` in mutation descriptors. Existing API CMS installations must
+explicitly select their published site document for the `chrome` binding before
+switching readers; the starter only binds a site it newly creates.
+
+### Scoped domain changes
+
+Register `cmsSiteDomainsTable` and `cmsSiteStateHeadsTable`. All domain functions
+receive `CmsSiteScope` (`tenantId`, `site`); ID-based operations take it before
+the domain ID. Domain writers use the caller transaction and the same site
+barrier, including first-host creation. Concurrent primary changes serialize;
+rollback restores the complete mapping. Unique host claims return `taken` to
+the losing site without exposing its owner's record. Preserve
+`SiteStateUnavailable` in the procedure error schema (`@voltro/cms/web`). Stop
+writers, apply the coordination table and update scoped calls before upgrading.
+
+### Redirect publication boundary
+
+`addRedirect` and `removeRedirect` require the trusted tenant as their final
+argument. Register `cmsChangeHeadsTable` with path/redirect tables and use one
+caller transaction. Changed manual redirects and standalone `recordPaths`
+advance publication generation and clear the active release without inventing
+a content-feed event. Same-target adds and absent removals are no-ops. Declare
+`ChangeFeedUnavailable` in caller/import descriptors. Review duplicate stored
+history before upgrade; see the CMS guide and manual 0.87.0/11 checklist.
+Read APIs still require their scoped store or explicit tenant filter. Application
+cache/rebuild coordination and the full Route Registry remain separate work.
+
+### Shared content locations
+
+Declare `locations` on a content type with stable mapping IDs and `segments`:
+literal text, `{ field: 'slug' }`, or `{ tree: true }`. Share the detached/frozen
+`defineContentLocations` definition with `resolveContentLocation` in API and
+frontend code; both are browser-safe `/web` exports. Descriptor validation checks
+string fields and tree availability. The resolver takes decoded values, an
+explicit locale prefix and optional tree path, produces bounded encoded paths,
+and refuses invalid inputs with `ContentLocationUnavailable`. It performs no
+route reservation, release-graph validation, authorization or frontend codegen.
+Handle incomplete draft addresses before using public delivery links.
+
+Server coordinators can use `createSnapshotDocumentAssembly` from
+`@voltro/cms/build` to retain bounded immutable document-pin batches in their
+private output provider. Each operation freshly admits the signed path sets and
+same build identity. `cmsBuildOutput(directory).composeDocuments` verifies actual
+renderer receipts and bytes; final assembly requires complete routes and public
+consent classes, current media rights and fresh grant admission. Only the two
+journal IDs are durable state; credentials remain private. This grants no
+activation or serving authority. See the build-snapshot documentation for bounds
+and explicit grant coordination.
+
+Trusted output providers may implement `readAssets` to verify an existing assets
+role against the original retained app and complete renderer inventory. The CLI
+provider uses its configured archive, checks physical bytes through EOF and
+reconstructs the expected manifest without a stage or build. This filesystem
+port mounts no transport; the CMS caller still owns fresh grant, signed-path
+and current-media-rights admission around each read.
+
+`createSnapshotRoleTransfer` and `cmsSnapshotRoleTransferRest` expose private
+manifest/file/chunk/batch reads for `assets`, `deny`, `redirects`, `sitemap` and `robots`.
+Each read reconstructs the exact selected role against the original admitted
+app/documents and current safety, route history or SEO state. The server fixes
+custody, byte bounds and the redirect declaration; fresh authorization brackets
+all physical operations. Chunks and batches are at most 64 KiB. A batch contains
+at most 200 complete files, each independently verified through EOF and SHA-256;
+the complete result is withheld until the final semantic admission succeeds.
+These operations create no
+stage, renew no credential and grant no activation or serving authority.