Build isolated preview artifacts for exact-source deployments (#13041)

## Thinking Path

> - Paperclip manages AI agents and their work.
> - Managed deployments need a cloud image and a database migration
package.
> - Branch commits can lack both artifacts until a normal release runs.
> - Operators need to test an exact commit without advancing release
aliases.
> - This pull request adds a preview build mode to the existing release
workflow.
> - Builds use an immutable source SHA and publish isolated, reusable
artifacts.

## Linked Issues or Issue Description

**Subsystem affected**

Release automation, cloud Docker images, and shared/database npm
packages.

**Problem or motivation**

An operator cannot deploy an unpublished branch with new migrations
using only
the normal release artifacts. Publishing it through a normal lane would
also
advance shared release aliases.

**Proposed solution**

Dispatch the trusted release workflow on master with a full source SHA
and a
request UUID. Build missing SHA images and, when needed, deterministic
preview
shared/DB packages. Publish packages under the preview dist-tag with
exact
workspace pins. Reuse matching artifacts on retries.

**Roadmap alignment**

This extends release tooling for operator validation. It does not add a
core
product feature or duplicate a planned product capability. Related PR
searches
found no duplicate preview deployment workflow.

## What Changed

- Add the preview channel, request correlation, artifact checks, and
result artifact.
- Compile source packages in a separate job from the npm publisher. The
publisher
  uses trusted master code and disables package lifecycle scripts.
- Publish only SHA cloud image tags. Preserve release aliases. Use
full-SHA tags and no shared build cache.
- Verify full source identity for reused packages and images. Both image
and npm publishers
use isolated jobs and the externally master-restricted npm-canary
environment. Fail on registry
  authentication errors, outages, or artifact identity mismatches.
- Let bundled-package preparation use patches from the requested source
checkout.
- Document publishing configuration, artifact contracts, and deployment
order.

## Verification

- Passed `pnpm -r typecheck` and `pnpm build`.
- Passed `pnpm test:release-registry`: 107 tests, including eight
preview tests.
- Passed `actionlint -shellcheck= .github/workflows/release.yml`.
- Built real shared and DB preview tarballs from an isolated exact-SHA
checkout.
Verified package source identity and all 244 SQL files and journal
entries.
- Verified the full revision behind an existing published SHA cloud
image.
- `pnpm test:run` exposed missing local embedded PostgreSQL library
symlinks.
The package's postinstall repair restored initdb; all 12 previously
affected
suites passed on rerun (95 tests). Additional local matrix reruns are in
progress.
The complete PR CI matrix is green, including general/serialized tests,
e2e,
typecheck, build, release registry, canary dry run, and the required
verify gate.
- Live preview publication and staging deployment require this workflow
on master
and the compatible control-plane backend. They have not run yet. No
production
  deployment was performed.

## Risks

Preview npm versions are immutable public artifacts. Both packages must
retain
their trusted publisher for release.yml in environment npm-canary.
Source builds
must remain separated from privileged npm publishing. The deploying
control plane
must verify source identity, integrity, and migration compatibility
before use.

Normal release jobs retain their existing conditions. Roll back by
stopping preview
dispatches and reverting the workflow/tooling. Published preview
versions remain
isolated from normal release tags.

## Model Used

OpenAI GPT-6 through Codex, with repository tools, code execution, and
test runs.
The session does not expose a more specific model version or
context-window size.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used with the available version and
capability details
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs
- [x] I have described the issue in-PR following the feature template
- [x] I have not referenced internal or instance-local issues or links
- [x] My branch name describes the change and contains no internal
ticket identifier
- [ ] I have run the full tests locally and they pass
- [x] I have added tests for the new behavior
- [x] I have updated relevant documentation
- [x] I have considered and documented risks
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open recommendations or follow-ups
- [x] I will address review comments before requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

doc/preview-release-artifacts.md

@@ -0,0 +1,93 @@
+# Preview deployment artifacts
+
+The `preview` channel in `.github/workflows/release.yml` builds deployment
+artifacts for one immutable source commit. It does not create a GitHub release,
+move a source branch, or advance any stable, beta, nightly, or canary alias.
+
+Dispatch `release.yml` on `master` with these inputs:
+
+| Input | Value |
+| --- | --- |
+| `channel` | `preview` |
+| `source_ref` | Full lowercase 40-character commit SHA in this repository |
+| `request_id` | UUID v4 identifying the operator's deployment request |
+| `preview_migrator` | `true` when exact-source DB/shared packages are needed |
+| `dry_run` | `false` |
+
+The workflow title is `Stack deploy <request_id> build`. Consumers must find a
+run by this identity, not by the latest run. Preview builds reject workflow
+definitions that do not run from `master`.
+
+## Outputs and reuse
+
+The image uses `ghcr.io/paperclipai/paperclip:sha-<FULL_SHA>-cloud`.
+Full-SHA tags keep separate commits with the same short prefix isolated. Normal
+release images retain their existing short-tag convention. Build arguments carry the full commit SHA.
+Preview builds do not import or overwrite the shared release cache or release
+aliases. Missing images are built for Linux amd64, matching managed deployments.
+
+When requested, both `@paperclipai/shared` and `@paperclipai/db` use
+`0.0.0-preview.g<FULL_SHA>`. Workspace dependencies are pinned to exact versions.
+Packages carry `gitHead` and `paperclipPreviewCommit` source identity. npm publishes
+them under the `preview` dist-tag only. Normal consumers of `latest` or `canary`
+continue to select normal releases.
+
+Registry 404 responses mean missing artifacts. Authentication errors, outages,
+or existing package identity mismatches fail the workflow. Retries reuse matching
+published artifacts, including a shared package published before a DB publish
+failure. Allow npm's visibility polling to finish before retrying.
+
+The final `stack-deploy-result` artifact contains `result.json` with contract
+version 1, request ID, SHA, stage `build`, and status `ready`. It expires after
+30 days. This confirms artifact availability; it does not certify a tenant deploy.
+
+## Publishing configuration and isolation
+
+Configure npm trusted publishing for **both packages** with repository
+`paperclipai/paperclip`, workflow `release.yml`, and environment `npm-canary`.
+The image publisher uses the same environment, whose deployment branch policy
+permits only master. Both publishers also check the workflow ref before running.
+This uses the existing publisher identity rather than requiring another workflow
+registration. The job uses npm with OIDC trusted publishing support and provenance.
+The environment's existing protections still apply.
+
+Package compilation runs in a separate job with read-only repository access and
+no npm, cloud-admin, or provider credentials. Trusted tooling from `master` packs
+the requested source checkout. The existing bundled-package helper takes patch
+configuration from that source checkout. Build artifacts contain only the two
+fixed package tarballs.
+
+Publishing runs on a fresh runner with trusted tooling, without a checkout of
+the requested branch. It checks package identity and exact dependencies, rejects
+archive path aliases, and publishes with lifecycle scripts disabled and an explicit
+registry and dist-tag. Image builds also run without registry write access and export a Docker archive.
+A separate trusted publisher loads that archive as data, verifies its full revision,
+platform, and image ID, then pushes only the SHA tag. It never runs the image.
+Dependency resolution disables scripts and pnpmfile hooks. Preview actions are
+pinned to full commit SHAs.
+
+The deploying control plane must independently verify package integrity, source
+identity, SQL and migration journal contents, and schema compatibility. Publish
+this workflow support before enabling an operator CLI that depends on it. Test
+normal release selection and a new migration-bearing branch in staging before
+allowing production use.
+
+## Local checks
+
+```sh
+node --test scripts/preview-artifacts.test.mjs
+pnpm test:release-registry
+pnpm -r typecheck
+pnpm test:run
+pnpm build
+```
+
+For a package build without publishing, install dependencies in a disposable
+checkout at an exact commit, then use the trusted helper:
+
+```sh
+node scripts/preview-artifacts.mjs pack /path/to/source /path/to/output FULL_SHA
+```
+
+This executes source build scripts. Keep output outside the repository and use an
+environment without publishing or cloud-admin credentials.