feat(cloud): publish content-addressed review snapshots

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 0.7.2 - Unreleased
 
+- Require every Gitcrawl cloud publisher manifest to opt into snapshot staging so `--stage-only` and normal publish-then-cutover runs cannot activate serving state through the legacy compatibility path.
+- Update CrawlKit to v0.14.2 and bind publisher resume plus post-cutover verification to the exact snapshot ID, so a newer concurrently staged candidate cannot be mistaken for the snapshot this publisher owns.
+- Fail cloud publication before any remote mutation when local enrichment coverage is incomplete unless operators explicitly pass `--allow-incomplete`.
+
 ## 0.7.1 - 2026-07-09
 
 - Add local, fail-closed packaging and independent verification for official macOS archives signed as `org.openclaw.gitcrawl` by `Developer ID Application: OpenClaw Foundation (FWJYW4S8P8)`, while keeping CI and cross-platform snapshots credential-free and non-publishing.

README.md

@@ -67,7 +67,34 @@ gitcrawl tui owner/repo
 The remote service is deployed separately from gitcrawl in `openclaw/crawl-remote` with Wrangler. gitcrawl only stores the Worker endpoint/archive in config and calls that service.
 `gitcrawl remote login` starts the Worker GitHub OAuth flow, verifies org/team membership server-side, and stores the signed bearer token in the OS keyring.
 Use `gitcrawl remote login --github-token-env GITHUB_TOKEN` for non-browser bootstrap; the Worker verifies that GitHub token against the same org/team policy and stores only the returned remote session token locally.
-`gitcrawl cloud publish` sends the local SQLite repositories and thread rows to a Worker archive through the role-gated ingest endpoint.
+`gitcrawl cloud publish` freezes and sanitizes one local SQLite image, uses its
+SHA-256 as the snapshot identity, exports repositories, threads, revisions,
+fingerprints, summaries, durable clusters, and PR detail/file rows from that
+same image, negotiates the remote snapshot-provenance contract before touching
+R2, uploads its digest-scoped bundle, and completes staged D1 coverage through
+row- and encoded-byte-bounded ingest requests.
+Publishing moves unpinned reads to the complete snapshot by default, preserving
+the existing reader-refresh behavior. The remote must advertise
+`gitcrawl.snapshot.staging.v1`; `--stage-only` keeps the immutable snapshot
+staged without changing serving state. A later publish verifies the
+candidate through the publisher-only status projection, skips repeated ingest
+when its digest, source sync, schema, resolved publication profile, persisted
+generation timestamp, and coverage match, then cuts it over. Cutover requires
+the remote contract to advertise reader-authenticated `GET /sqlite`; Gitcrawl
+validates the cutover acknowledgement, retries the scoped reader projection
+until its digest, profile, generation, and dataset coverage are exact, rechecks
+the exact publisher metadata, and hashes the downloaded bound SQLite image
+before reporting success. Before any upload or ingest, Gitcrawl verifies
+the configured credential through the advertised `/v1/whoami` route and
+requires both publisher and reader roles, including for stage-only publication.
+Incomplete local enrichment fails before any remote mutation;
+`--allow-incomplete` is an explicit escape hatch, and `--observation-order`
+publishes durable fetch ordering after the remote operator fence is enabled.
+Digest-scoped SQLite bundles can contain private issue and pull-request text.
+Gitcrawl intentionally exposes no remote deletion command: operators must only
+enable publication against a remote deployment with bounded lifecycle rules for
+failed, superseded, and uncut staged bundles. `--stage-only` does not transfer
+that retention responsibility back to the client.
 `gitcrawl clusters-report` writes a Markdown report for the top clusters using the same display view, with an at-a-glance table, per-cluster metadata, member tables, and key snippets. Use `--json` for the hydrated report payload.
 `gitcrawl cluster` and `gitcrawl refresh` build ghcrawl-shaped durable clusters by default (`--threshold 0.80`, `--min-size 1`, `--max-cluster-size 40`, `--k 16`, `--cross-kind-threshold 0.93`): every active vector-backed thread is represented, singleton rows use `singleton_orphan`, multi-member rows use `duplicate_candidate`, and stable IDs are derived from the representative thread. They also add deterministic GitHub reference evidence for direct issue/PR links such as `#123`, `issues/123`, and `pull/123`. Weak embedding edges need concrete title-token overlap unless their similarity is already high, which keeps generic low-confidence bridges from forming unrelated clusters.
 `gitcrawl tui` infers the most recently updated local repository when `owner/repo` is omitted. `serve` is intentionally not part of `gitcrawl`.

go.mod

@@ -9,7 +9,7 @@ require (
 	github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834
 	github.com/charmbracelet/x/ansi v0.11.7
 	github.com/mattn/go-isatty v0.0.22
-	github.com/openclaw/crawlkit v0.13.4
+	github.com/openclaw/crawlkit v0.14.2
 	github.com/zalando/go-keyring v0.2.8
 	golang.org/x/sys v0.46.0
 	modernc.org/sqlite v1.53.0

go.sum

@@ -64,8 +64,8 @@ github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc
 github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
 github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
 github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
-github.com/openclaw/crawlkit v0.13.4 h1:6KZaIzs5BQxBjCeOwg1u2XPLNbsOkrRPQGPtTkxZaYE=
-github.com/openclaw/crawlkit v0.13.4/go.mod h1:u5oK8v0gtLzIXtj6gehF0JV2cGX1D/xiogZGCJwONGs=
+github.com/openclaw/crawlkit v0.14.2 h1:NA0+fDlyYnQjrI6krkhajHDKMTOt9q8JTlMFsGH37pg=
+github.com/openclaw/crawlkit v0.14.2/go.mod h1:u5oK8v0gtLzIXtj6gehF0JV2cGX1D/xiogZGCJwONGs=
 github.com/pelletier/go-toml/v2 v2.4.3 h1:GTRvJQutkOSftxIFD5xw9aepkYNuPWmVJpffdDPYVpY=
 github.com/pelletier/go-toml/v2 v2.4.3/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=

internal/cli/app.go

@@ -4770,7 +4770,7 @@ Usage:
 	"cloud": `gitcrawl cloud manages Worker-backed remote archives.
 
 Usage:
-  gitcrawl cloud publish --remote URL --archive id [--json]
+  gitcrawl cloud publish --remote URL --archive id [--allow-incomplete] [--observation-order] [--stage-only] [--json]
 `,
 	"whoami": `gitcrawl whoami prints the configured remote archive identity.