feat(snapshot): add transactional publication receipts and ref CAS core

Author: Ivanbeethoven

.github/workflows/base.yml

@@ -312,3 +312,5 @@ jobs:
           cargo test -p jupiter --lib namespace_storage --locked -j 2
       - name: Snapshot contracts, PostgreSQL transactions and million-binding gate
         run: cargo test -p ceres --lib snapshot --locked -j 2 -- --include-ignored --nocapture
+      - name: Publication receipts, ref CAS, rollback and concurrency on both databases
+        run: cargo test -p jupiter --lib publication_storage --locked -j 2 -- --include-ignored --nocapture

ceres/src/application/snapshot/radix/database/postgres_tests.rs

@@ -22,9 +22,10 @@ async fn postgres_snapshot_nodes_scope_proofs_and_radix_transactions() {
         parsed.host_str(),
         Some("localhost" | "127.0.0.1" | "[::1]")
     ));
-    assert!(
-        parsed.path().trim_start_matches('/').ends_with("_test"),
-        "test database name must end in _test"
+    assert_eq!(
+        parsed.path(),
+        "/snapshot_test",
+        "use the explicit disposable test database"
     );
     let schema = format!("snapshot_test_{}", uuid::Uuid::new_v4().simple());
     let control = Database::connect(

docs/spec/namespace-publication-core.md

@@ -0,0 +1,103 @@
+# Namespace publication transaction core
+
+Status: implemented storage core, 2026-09-06; **not an enabled publisher API**.
+The application composer, all production writer integrations, release-policy
+enforcement, prepare/retention pins and authorization remain required before
+the namespace capability can be announced.
+
+## Ownership and ordering
+
+`PublicationStorage::begin(request, expected_head, writer_epoch)` owns one
+database transaction. Its first write reserves the unique
+`(actor_domain, operation_id)` row. A duplicate committed request returns its
+receipt before exposing any ref-writing handle. Reusing the same committed key
+with a different request digest or instance is a conflict. Failed/aborted
+transactions leave no operation reservation or success receipt.
+
+The request digest is supplied by a trusted application adapter and MUST cover
+the complete canonical mutation plan: fixed base/head, expected refs, binding
+policy/read set and prepared content identities. The storage facade cannot
+infer these fields from an opaque digest. The authenticated actor domain must
+not be accepted from untrusted request JSON. Receipt reads require current
+authorization independently of the operation key.
+
+A ready result owns `PublicationTransaction`. Writers can borrow its underlying
+transaction for conditional refs, prepared metadata, scope attestations and
+index nodes, but cannot obtain ownership and independently commit it. Explicit
+abort or dropping the owner rolls back. Publication's `finish` is the only
+commit path exposed by this wrapper.
+
+`finish` validates the prepared view identity/byte bound and same instance, then
+stages insert-only view bytes, conditional head update, publication history,
+operation result and outbox event. They commit together with the borrowed
+transaction's ref changes. A database error after head CAS still rolls back
+the head, view and refs. No notification is dispatched before COMMIT.
+
+## Compare-and-swap and receipts
+
+The head condition includes instance, expected sequence, expected view ID and
+writer epoch. Bootstrap is an insert-if-absent head, not an upsert. Sequences and
+epochs are positive SQL BIGINT values and sequence increment checks overflow.
+
+When the descriptor is unchanged, the operation may be a no-op for namespace
+publication: preserve sequence/view and do not insert publication/outbox rows.
+It STILL executes the head/epoch fence. For example, a non-selected branch may
+change without changing the default namespace view. Determining that the view
+really represents the complete post-write state belongs to the application;
+the storage facade must not be used to hide a selected-ref mutation.
+
+`GitDbStorage::update_ref_if_unchanged` adds one conditional SQL update on
+repo ID, fully qualified ref name and expected object ID, returning whether
+exactly one row changed. It accepts the publication transaction and does not
+silently rebase/retry. Existing legacy writers are not yet switched to this
+method. The caller must abort the whole publication if any required ref/read
+condition fails.
+
+A COMMIT error is reported as an uncertain outcome, not a proven rollback.
+Look up the original actor/operation/request digest on a new connection before
+retrying. Receipt replay never dispatches a second ref mutation or outbox
+event. Outbox rows have unique event IDs and pending/delivered state, but the
+delivery worker and external side effects are not implemented by this core.
+
+A writer_epoch column does not fence an old binary that never checks it.
+Maintenance cutover and an audit of every production writer remain G04/G05
+requirements; a passing storage test cannot establish those conditions.
+
+## Schema and reproduction
+
+The additive migration `m20260906_160000_namespace_publication` creates
+namespace_view, namespace_head, namespace_publication, snapshot_operation and
+namespace_outbox. It creates no initial head/catalog and enables no feature.
+Generated Callisto fields were produced with sea-orm-cli 2.0.2 from the actual
+SQLite migration schema; PostgreSQL tests verify the same runtime schema.
+
+View payloads are bounded to 16 KiB in SQL and checked against their SHA-256 ID.
+The application supplies the already validated namespace-manifest-v1 codec.
+An opaque-byte storage fixture is not proof that the manifest describes the
+actual native/import objects. No foreign-key cascade from a mutable ref or
+registry path deletes published metadata. Retention/GC and referential audits
+must be supplied by the full publisher before deployment.
+
+Use the explicit loopback disposable PostgreSQL URL described in
+[jupiter-migrate](../../jupiter-migrate/README.md), then run:
+
+```bash
+cargo test -p jupiter --lib publication_storage --locked -- --include-ignored --nocapture
+cargo test -p jupiter-migrate --lib snapshot --locked -- --include-ignored --nocapture
+```
+
+The six publication tests cover SQLite lifecycle, duplicate-key concurrency and
+expected-old competition, plus PostgreSQL lifecycle/reconnect, concurrent
+duplicates/expected-old writers and an independent-connection epoch change.
+Shared lifecycle checks also inject failure after head CAS, drop an uncommitted
+transaction, reject different-payload replay, preserve old views and verify
+no-op ref writes. They use the REAL import_refs and new publication tables.
+PostgreSQL tests create fresh random schemas, retain diagnostics and never
+refresh a supplied database. Tests do not cover a process/host power loss,
+external payload durability, notification delivery, source/path permissions or
+release-policy bypass through actual production routes.
+
+The CI focused snapshot job runs these PostgreSQL tests explicitly instead of
+silently skipping ignored tests. MG06/MG09/MG15 have additional storage-level
+evidence; the broader acceptance IDs remain incomplete until application and
+real-service integration are tested.

docs/spec/namespace-snapshot-spec.md

@@ -57,7 +57,7 @@ Mega 提供两个可独立验收的能力：
 
 ### 3.2 Scope 证明
 
-拟新增 `source_commit_scope`，唯一键 `(source_id, scope_path, algorithm, commit_oid)`，保存 root_tree_oid、证明类型和可审计来源（产生该对象的 ref mutation/父 scope 映射/已发布 root）。
+已添加 `source_commit_scope`，逻辑唯一键 `(source_id, scope_path, algorithm, commit_oid)`，保存 root_tree_oid、证明类型和可审计来源（产生该对象的 ref mutation/父 scope 映射/已发布 root）。实际数据库索引使用 scope 的 SHA-256 key 并核对完整路径，避免 PostgreSQL 长路径 btree 限制；所有生产创建/merge 入口的证明写入仍需接入。
 
 证明在原生 root/子 scope commit 创建、scope clone 派生、CL 接收、merge 生成路径 commits 时一起记录。已知 root commit 可沿已验证 root 历史建立 root-scope 关系；不能把任意存在于 `mega_commit` 的对象默认视为 `/`。
 
@@ -77,15 +77,17 @@ tag 解析返回 ref OID、必要的 annotated-tag peeling 链与最终 commit
 
 路径以组件匹配；`/rust` 不匹配 `/rust_v1`。v1 采用有效 UTF-8 路径组件，不做大小写折叠/Unicode 归一化；拒绝 NUL、`.`、`..`、重复分隔等非规范输入，非 UTF-8 名称明确返回 unsupported，不静默改名。Git 路径语义不套用 Windows 路径规则。路径编码规则进入 schema 版本。
 
-建议实现持久化压缩 byte-radix/Merkle trie：组件间使用禁止出现在名称中的 NUL 作为内部边界，内部节点最多 256 个分支，value 保存独立 binding digest。节点大小、最长路径、递归深度有硬上限；压缩长 label 必须仍受节点上限约束。
+已实现的 [索引基础](namespace-index-v1.md) 是持久化压缩 byte-radix/Merkle trie：组件间使用禁止出现在名称中的 NUL 作为内部边界，内部节点最多 256 个分支，value 保存独立 binding digest。节点大小、最长路径有硬上限，遍历不依赖递归；压缩长 label 仍受节点上限约束。公开分页 cursor、组合策略和保留遍历尚未由这层实现。
 
 仅说“重写祖先节点”还不够：根节点若内嵌百万 children，单次更新仍是 O(R)。首个索引 PR 必须证明节点 fanout/大小受限，更新 b 个 binding 的成本受变动 key 长度和受限节点数控制；持久化旧节点继续被旧 view 引用。
 
 按 prefix seek 和分页，不在每次 mount 或每页 readdir 扫描全 registry。cursor 绑定 view_id、prefix、最后排序 key、schema 与查询参数并防篡改；续页重新鉴权。ScorpioFS directory handle 绑定该 view，不能跨 view 使用 cookie。
 
 百万 binding 测试记录 node reads/writes、bytes、峰值内存和分页工作量，不只报告平均耗时。初始全量建索引允许 O(R)，在线单点发布和小工作集 mount 不允许。
 
-## 5. 元数据模型（拟新增，不是现有数据库表）
+## 5. 元数据模型（目标模型，部分已落地）
+
+当前 additive schema 已包含 source/scope、namespace_node、view/head/publication、operation 与 outbox；binding_head、pin 及完整业务发布策略尚未落地。表存在不代表已部署或启用完整 namespace capability。
 
 | 表/存储 | 关键字段与约束 | 用途 |
 | --- | --- | --- |
@@ -108,6 +110,8 @@ tag 解析返回 ref OID、必要的 annotated-tag peeling 链与最终 commit
 
 ## 6. 发布事务与并发约束
 
+已实现的 [publication storage core](namespace-publication-core.md) 包含操作预留/回执、head CAS、同事务 ref 条件写、view/publication/outbox 持久化与两个数据库的故障/并发测试。当前所有生产 writer 尚未接入，组合策略、prepare pin、对象保留与 HTTP 能力仍未完成；下面是完整应用协议，不把存储核心测试等同于全链路交付。
+
 统一应用服务接收 `PublishPlan {operation_id, expected_head, ref_read_set, binding_read_set, prepared_objects, native_change?, binding_changes}`，返回 `PublicationReceipt {seq, view_id, outcome}`。HTTP endpoint 名称不决定领域模型；Git 与网页编辑调用同一服务。
 
 ```text

jupiter-migrate/README.md

@@ -107,6 +107,31 @@ under an America/Los_Angeles session. The focused CI job also runs the ignored
 million-binding index test. These gates do not validate publication, leases, GC,
 writer fencing or the entire workspace; those remain separate acceptance work.
 
+## Publication metadata generation and tests
+
+The additive `m20260906_160000_namespace_publication` migration creates five more
+tables without initializing a head or enabling an API. Generate only its models
+from a new disposable schema (again use a fresh `<temp>` absolute directory):
+
+```bash
+cargo run -p jupiter-migrate --example snapshot_schema -- <temp>/publication.db
+sea-orm-cli generate entity -u sqlite://<temp>/publication.db -o <temp>/entities --tables namespace_view,namespace_head,namespace_publication,snapshot_operation,namespace_outbox --with-serde both --entity-format dense
+```
+
+Copy the five generated models, merge registries and preserve `entity_ext` as
+above. All counters use BIGINT and timestamps are timezone-aware. The snapshot
+migration roundtrip test now checks all nine snapshot tables. The UTC upgrade
+regression locates the UTC migration by name rather than assuming it is last.
+
+`cargo test -p jupiter --lib publication_storage --locked -- --include-ignored
+--nocapture` explicitly runs both SQLite and disposable PostgreSQL tests using
+the same guarded URL. They cover the real `import_refs` table participating in
+the publication transaction, operation replay, CAS, rollback after head update,
+concurrent duplicate/expected-old requests and reconnect receipt lookup. See
+[publication core](../docs/spec/namespace-publication-core.md) for the precise
+evidence boundary: all production writers, composition, pins, authorization and
+outbox delivery remain separate requirements.
+
 ## Library API reference
 
 ```rust

jupiter-migrate/src/migration/m20260906_160000_namespace_publication.rs

@@ -0,0 +1,133 @@
+//! Publication metadata only. No initial head, feature flag or historical
+//! catalog is synthesized. All fields use portable SQLite/PostgreSQL types.
+
+use sea_orm_migration::{prelude::*, schema::*};
+
+#[derive(DeriveMigrationName)]
+pub struct Migration;
+
+#[async_trait::async_trait]
+impl MigrationTrait for Migration {
+    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        manager
+            .create_table(
+                Table::create()
+                    .table(Meta::NamespaceView)
+                    .if_not_exists()
+                    .col(string(Meta::ViewId).primary_key())
+                    .col(string(Meta::InstanceId))
+                    .col(var_binary(Meta::CanonicalBytes, 16384))
+                    .col(timestamp_with_time_zone(Meta::CreatedAt))
+                    .check(Expr::cust("length(canonical_bytes) <= 16384"))
+                    .to_owned(),
+            )
+            .await?;
+        manager
+            .create_table(
+                Table::create()
+                    .table(Meta::NamespaceHead)
+                    .if_not_exists()
+                    .col(string(Meta::InstanceId).primary_key())
+                    .col(big_integer(Meta::PublicationSeq))
+                    .col(string(Meta::ViewId))
+                    .col(big_integer(Meta::WriterEpoch))
+                    .check(Expr::cust("publication_seq > 0 AND writer_epoch > 0"))
+                    .to_owned(),
+            )
+            .await?;
+        manager.create_table(Table::create()
+            .table(Meta::NamespacePublication).if_not_exists()
+            .col(string(Meta::InstanceId))
+            .col(big_integer(Meta::PublicationSeq))
+            .col(string(Meta::ViewId))
+            .col(ColumnDef::new(Meta::ParentSeq).big_integer().null())
+            .col(ColumnDef::new(Meta::ParentViewId).string().null())
+            .col(big_integer(Meta::WriterEpoch))
+            .col(string(Meta::ActorDomain))
+            .col(string(Meta::OperationId))
+            .col(string(Meta::Reason))
+            .col(timestamp_with_time_zone(Meta::CreatedAt))
+            .primary_key(Index::create().col(Meta::InstanceId).col(Meta::PublicationSeq))
+            .check(Expr::cust("publication_seq > 0 AND writer_epoch > 0"))
+            .check(Expr::cust("(parent_seq IS NULL AND parent_view_id IS NULL) OR (parent_seq IS NOT NULL AND parent_seq > 0 AND parent_view_id IS NOT NULL)"))
+            .to_owned()).await?;
+        manager.create_table(Table::create()
+            .table(Meta::SnapshotOperation).if_not_exists()
+            .col(string(Meta::ActorDomain))
+            .col(string(Meta::OperationId))
+            .col(string(Meta::InstanceId))
+            .col(string(Meta::RequestDigest))
+            .col(ColumnDef::new(Meta::PublicationSeq).big_integer().null())
+            .col(ColumnDef::new(Meta::ViewId).string().null())
+            .col(ColumnDef::new(Meta::Outcome).string().null())
+            .col(timestamp_with_time_zone(Meta::CreatedAt))
+            .primary_key(Index::create().col(Meta::ActorDomain).col(Meta::OperationId))
+            .check(Expr::cust("(publication_seq IS NULL AND view_id IS NULL AND outcome IS NULL) OR (publication_seq IS NOT NULL AND publication_seq > 0 AND view_id IS NOT NULL AND outcome IS NOT NULL AND outcome IN ('published', 'no_op'))"))
+            .to_owned()).await?;
+        manager
+            .create_table(
+                Table::create()
+                    .table(Meta::NamespaceOutbox)
+                    .if_not_exists()
+                    .col(string(Meta::EventId).primary_key())
+                    .col(string(Meta::InstanceId))
+                    .col(big_integer(Meta::PublicationSeq))
+                    .col(string(Meta::ViewId))
+                    .col(boolean(Meta::Delivered).default(false))
+                    .col(timestamp_with_time_zone(Meta::CreatedAt))
+                    .check(Expr::cust("publication_seq > 0"))
+                    .to_owned(),
+            )
+            .await?;
+        manager
+            .create_index(
+                Index::create()
+                    .name("namespace_outbox_pending")
+                    .table(Meta::NamespaceOutbox)
+                    .col(Meta::Delivered)
+                    .col(Meta::CreatedAt)
+                    .to_owned(),
+            )
+            .await
+    }
+
+    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        // Disposable-test DDL rollback only; application rollback retains history.
+        for table in [
+            Meta::NamespaceOutbox,
+            Meta::SnapshotOperation,
+            Meta::NamespacePublication,
+            Meta::NamespaceHead,
+            Meta::NamespaceView,
+        ] {
+            manager
+                .drop_table(Table::drop().table(table).to_owned())
+                .await?;
+        }
+        Ok(())
+    }
+}
+
+#[derive(DeriveIden)]
+enum Meta {
+    NamespaceView,
+    NamespaceHead,
+    NamespacePublication,
+    SnapshotOperation,
+    NamespaceOutbox,
+    ViewId,
+    InstanceId,
+    CanonicalBytes,
+    CreatedAt,
+    PublicationSeq,
+    WriterEpoch,
+    ParentSeq,
+    ParentViewId,
+    ActorDomain,
+    OperationId,
+    Reason,
+    RequestDigest,
+    Outcome,
+    EventId,
+    Delivered,
+}

jupiter-migrate/src/migration/mod.rs

@@ -107,6 +107,7 @@ mod m20260811_100000_create_campsite_member_identity;
 mod m20260906_120000_snapshot_source_identity;
 mod m20260906_140000_namespace_nodes;
 mod m20260906_145000_snapshot_utc_timestamps;
+mod m20260906_160000_namespace_publication;
 mod runner;
 #[cfg(test)]
 mod snapshot_tests;
@@ -203,6 +204,7 @@ impl MigratorTrait for Migrator {
             Box::new(m20260906_120000_snapshot_source_identity::Migration),
             Box::new(m20260906_140000_namespace_nodes::Migration),
             Box::new(m20260906_145000_snapshot_utc_timestamps::Migration),
+            Box::new(m20260906_160000_namespace_publication::Migration),
         ]
     }
 }