v0.7.27: deep debt — coordinated shutdown, zero-copy phase 3, type safety

Coordinated graceful shutdown via tokio::sync::watch for HTTP/tarpc/UDS.
Zero-copy Phase 3: BraidMetadata title/description/tags to Arc<str>.
JsonLdVersion replaces f32 for content-addressed precision. get_batch
surfaces store errors. RegistryRpc structured errors. Discoverable vocab
URIs. AttributionNotice Display single source of truth.

1,128 tests, 90.23% line coverage, 0 clippy, 0 unsafe, 0 TODOs.

Made-with: Cursor

Author: ecoPrimals

CHANGELOG.md

@@ -7,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.27] - 2026-03-24
+
+### Deep Debt: Coordinated Shutdown, Zero-Copy Phase 3, Type Safety, Structured Errors
+
+Comprehensive debt resolution across 11 audit items: coordinated graceful
+shutdown, zero-copy BraidMetadata, JSON-LD version type safety, structured
+registry errors, discoverable vocab URIs, and store error surfacing.
+
+### Added
+
+- **Coordinated shutdown** — `tokio::sync::watch` channel coordinates HTTP,
+  tarpc, and UDS graceful shutdown; spawned servers drain in-flight requests
+  before process exit (was fire-and-forget)
+- **`JsonLdVersion` type** — replaces `f32` for `BraidContext.version`;
+  always serializes to `1.1`, validates on deserialization (eliminates float
+  precision drift in content-addressed hashing)
+- **`RegistryError` enum** — structured error type for `RegistryRpc` tarpc
+  service (`NotFound`, `RegistrationFailed`, `Internal`); replaces `String`
+- **Discoverable vocab URIs** — `ecop_vocab_uri()` / `ecop_base_uri()`
+  resolve from `ECOP_VOCAB_URI` / `ECOP_BASE_URI` env vars with fallback
+  defaults; `BraidContext::default()` uses discoverable functions
+- **`Display` impl for `AttributionNotice`** — single source of truth for
+  notice text generation (removed `notice_text` field to prevent drift)
+
+### Changed
+
+- **Zero-copy Phase 3: `BraidMetadata`** — `title: Option<String>` →
+  `Option<Arc<str>>`, `description` → `Option<Arc<str>>`, `tags: Vec<String>`
+  → `Vec<Arc<str>>`; cross-crate migration across all 10 crates + 4 store
+  backends + tests
+- **Tag index evolved** — `HashMap<String, HashSet<BraidId>>` →
+  `HashMap<Arc<str>, HashSet<BraidId>>` in memory store (zero-copy tags)
+- **`get_batch` returns errors** — changed from `Vec<Option<Braid>>` to
+  `(Vec<Option<Braid>>, Vec<StoreError>)` matching `put_batch` pattern;
+  store errors are now visible instead of silently swallowed as "not found"
+- **`CachedDiscovery.find_one`** — sorts by `last_seen` (most recent first)
+  before selecting; deterministic instead of hash-map iteration order
+- **Health check parsing** — replaced fragile `response.contains("200 OK")`
+  with numeric status code parsing; accepts any 2xx response
+- **`println!` → `tracing::info!`** — 2 chaos test diagnostics migrated
+- **`RewardShare` documented** — `share`/`amount` fields documented as
+  informational ratios with evolution path to integer basis points
+
+### Verified
+
+- `cargo fmt` — 0 diffs
+- `cargo clippy` (pedantic + nursery, `-D warnings`) — 0 warnings
+- `cargo doc` — 0 warnings
+- `cargo test` — 1,128 tests, 0 failures
+- `cargo llvm-cov` — **90.23% line coverage**
+- 0 TODOs, 0 unsafe, 0 production unwraps, all files under 1000 LOC
+
+## [0.7.26] - 2026-03-23
+
+### Ecosystem Absorption: scyBorg License, Sled Deprecation, Lint Evolution
+
+See ROADMAP.md for full details.
+
 ## [0.7.25] - 2026-03-23
 
 ### Coverage Push and Test Hygiene

CONTEXT.md

@@ -28,7 +28,7 @@ attribution before distributing rewards.
 - **Communication:** JSON-RPC 2.0 (required) + tarpc (optional high-perf) + REST + UDS
 - **License:** scyBorg Triple-Copyleft (AGPL-3.0 + ORC-1.0 + CC-BY-SA-4.0)
 - **Tests:** 1,128 passing
-- **Coverage:** ~90% line coverage (testable code, excluding Postgres which needs runtime)
+- **Coverage:** 90.23% line coverage (llvm-cov, excluding Postgres which needs runtime)
 - **MSRV:** 1.87 (Edition 2024)
 - **Crate count:** 10 workspace crates
 - **Unsafe code:** 0 blocks (`#![forbid(unsafe_code)]` on all crates)

Cargo.toml

@@ -16,7 +16,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.7.26"
+version = "0.7.27"
 edition = "2024"
 rust-version = "1.87"
 license = "AGPL-3.0-only"

DEVELOPMENT.md

@@ -1,7 +1,7 @@
 # 🌾 SweetGrass — Development Guide
 
 **Last Updated**: March 23, 2026  
-**Version**: v0.7.26
+**Version**: v0.7.27
 
 ---
 

README.md

@@ -2,7 +2,7 @@
 
 **Semantic Provenance and Attribution Layer for ecoPrimals**
 
-v0.7.26 | 1,128 tests | Edition 2024 | scyBorg Triple-Copyleft | Pure Rust | ecoBin compliant | Sovereign types
+v0.7.27 | 1,128 tests | Edition 2024 | scyBorg Triple-Copyleft | Pure Rust | ecoBin compliant | Sovereign types
 
 ---
 
@@ -180,7 +180,7 @@ See [DEVELOPMENT.md](./DEVELOPMENT.md) for all options.
 
 | Metric | Value |
 |--------|-------|
-| Version | v0.7.26 |
+| Version | v0.7.27 |
 | Tests | 1,128 passing |
 | Coverage | ~90% lines (llvm-cov, excluding Postgres runtime tests) |
 | Edition | 2024 (MSRV 1.87) |
@@ -211,7 +211,7 @@ See [DEVELOPMENT.md](./DEVELOPMENT.md) for all options.
 
 ### Zero-Copy
 
-`ContentHash`, `BraidId`, `Did`, `ActivityId`, `Braid.mime_type`, `EcoPrimalsAttributes.source_primal`, `EcoPrimalsAttributes.niche`, `LoamCommitRef.spine_id`, `BraidFactory.source_primal`, and `CompressionEngine.source_primal` use `Arc<str>` internally — `.clone()` is O(1) atomic refcount increment. MIME type indexes (`MemoryStore`, `AgentContributions`) share the same `Arc<str>`, eliminating per-query allocations on hot paths. `BraidSignature` fields use `Cow<'static, str>` for zero-allocation static values. `BraidContext.imports` uses `IndexMap` for deterministic serialization.
+`ContentHash`, `BraidId`, `Did`, `ActivityId`, `Braid.mime_type`, `BraidMetadata.title`, `BraidMetadata.description`, `BraidMetadata.tags`, `EcoPrimalsAttributes.source_primal`, `EcoPrimalsAttributes.niche`, `LoamCommitRef.spine_id`, `BraidFactory.source_primal`, and `CompressionEngine.source_primal` use `Arc<str>` internally — `.clone()` is O(1) atomic refcount increment. MIME type and tag indexes (`MemoryStore`, `AgentContributions`) share the same `Arc<str>`, eliminating per-query allocations on hot paths. `BraidSignature` fields use `Cow<'static, str>` for zero-allocation static values. `BraidContext.imports` uses `IndexMap` for deterministic serialization.
 
 ### Configuration
 

ROADMAP.md

@@ -1,11 +1,27 @@
 # SweetGrass Roadmap
 
-**Current Version**: v0.7.26 (March 2026)
+**Current Version**: v0.7.27 (March 2026)
 
 ---
 
 ## Completed
 
+### v0.7.27 — Deep Debt: Coordinated Shutdown, Zero-Copy Phase 3, Type Safety (March 2026)
+
+- [x] **Coordinated graceful shutdown** — `tokio::sync::watch` channel coordinates HTTP, tarpc, and UDS; spawned servers drain in-flight requests before process exit (was fire-and-forget `tokio::spawn`)
+- [x] **Zero-copy Phase 3: `BraidMetadata`** — `title`, `description` → `Option<Arc<str>>`, `tags` → `Vec<Arc<str>>`; cross-crate migration across all 10 crates + 4 store backends
+- [x] **`JsonLdVersion` type** — replaces `f32` for `BraidContext.@version`; zero-size type always serializes to `1.1`, validates on deserialization (eliminates float precision drift)
+- [x] **`get_batch` error surfacing** — returns `(Vec<Option<Braid>>, Vec<StoreError>)` matching `put_batch` pattern; store errors now visible instead of silently swallowed
+- [x] **`RegistryRpc` structured errors** — `Result<T, String>` → `Result<T, RegistryError>` with `NotFound`/`RegistrationFailed`/`Internal` variants
+- [x] **Discoverable vocab URIs** — `ecop_vocab_uri()` / `ecop_base_uri()` resolve from env vars with fallback defaults; `BraidContext::default()` uses discoverable functions
+- [x] **`AttributionNotice` single source of truth** — removed `notice_text` field; `Display` impl generates text from structured data
+- [x] **`CachedDiscovery.find_one` stable ordering** — sorts by `last_seen` (newest first) for deterministic selection
+- [x] **Health check parsing** — numeric status code extraction replaces fragile string matching
+- [x] **Tag index zero-copy** — `HashMap<String, ...>` → `HashMap<Arc<str>, ...>` in memory store
+- [x] **`println!` → `tracing`** in chaos tests
+- [x] **`RewardShare` f64 documented** — informational ratios with evolution path to integer basis points (sunCloud v0.9.0+)
+- [x] 1,128 tests passing, 90.23% line coverage (llvm-cov), 0 clippy warnings, 0 doc warnings, 0 unsafe, 0 fmt issues
+
 ### v0.7.26 — Ecosystem Absorption: scyBorg License, Sled Deprecation, Lint Evolution (March 2026)
 
 - [x] **scyBorg Triple-Copyleft LICENSE** — adopted rhizoCrypt v0.13.0 format (AGPL + ORC + CC-BY-SA with Reserved Material section)
@@ -464,7 +480,8 @@
 
 | Version | Target | Focus |
 |---------|--------|-------|
-| v0.7.26 | **March 2026** | Ecosystem Absorption: scyBorg License, Sled Deprecation, Lint Evolution (DONE) |
+| v0.7.27 | **March 2026** | Deep Debt: Coordinated Shutdown, Zero-Copy Phase 3, Type Safety (DONE) |
+| v0.7.26 | March 2026 | Ecosystem Absorption: scyBorg License, Sled Deprecation, Lint Evolution (DONE) |
 | v0.7.25 | March 2026 | Coverage Push, Test Hygiene, PUBLIC_SURFACE_STANDARD Compliance (DONE) |
 | v0.7.24 | March 2026 | Deep Debt: Zero-Copy Phase 2, Public Surface, Audit (DONE) |
 | v0.7.23 | March 2026 | Ecosystem Absorption: MCP Tool Exposure, Canonical Capabilities (DONE) |

config/capability_registry.toml

@@ -7,7 +7,7 @@
 
 [primal]
 name = "sweetgrass"
-version = "0.7.26"
+version = "0.7.27"
 description = "Semantic provenance and attribution layer"
 license = "AGPL-3.0-only"
 protocol = "jsonrpc-2.0"

crates/sweet-grass-compression/src/engine/mod.rs

@@ -236,11 +236,14 @@ impl CompressionEngine {
 
         // Build metadata
         let metadata = BraidMetadata {
-            title: Some(format!("Session {}", session.id)),
-            description: Some(format!(
-                "Compressed from {} vertices ({} committed)",
-                analysis.vertex_count, analysis.committed_count
-            )),
+            title: Some(format!("Session {}", session.id).into()),
+            description: Some(
+                format!(
+                    "Compressed from {} vertices ({} committed)",
+                    analysis.vertex_count, analysis.committed_count
+                )
+                .into(),
+            ),
             ..Default::default()
         };
 

crates/sweet-grass-core/src/braid/mod.rs

@@ -23,8 +23,9 @@ pub mod types;
 pub use builder::BraidBuilder;
 pub use types::{
     BraidContext, BraidId, BraidMetadata, BraidSignature, BraidType, CompressionMeta, ContentHash,
-    ECOP_BASE_URI, ECOP_VOCAB_URI, EcoPrimalsAttributes, LoamAnchor, LoamCommitRef, PROV_VOCAB_URI,
-    SCHEMA_VOCAB_URI, SummaryType, Timestamp, XSD_VOCAB_URI, current_timestamp_nanos,
+    DEFAULT_ECOP_BASE_URI, DEFAULT_ECOP_VOCAB_URI, EcoPrimalsAttributes, JsonLdVersion, LoamAnchor,
+    LoamCommitRef, PROV_VOCAB_URI, SCHEMA_VOCAB_URI, SummaryType, Timestamp, XSD_VOCAB_URI,
+    current_timestamp_nanos, ecop_base_uri, ecop_vocab_uri,
 };
 
 /// A `SweetGrass` Braid (provenance record).

crates/sweet-grass-core/src/braid/tests.rs

@@ -86,7 +86,8 @@ mod unit_tests {
     #[test]
     fn test_braid_context_default() {
         let ctx = BraidContext::default();
-        assert!((ctx.version - 1.1).abs() < f32::EPSILON);
+        let version_json = serde_json::to_value(ctx.version).unwrap();
+        assert!((version_json.as_f64().unwrap() - 1.1).abs() < f64::EPSILON);
         assert!(ctx.imports.contains_key("prov"));
         assert!(ctx.imports.contains_key("ecop"));
     }
@@ -366,7 +367,7 @@ mod proptests {
     fn test_braid_builder_metadata() {
         let did = Did::new("did:key:z6MkBuilderMeta");
         let meta = BraidMetadata {
-            tags: vec!["important".to_string()],
+            tags: vec!["important".into()],
             ..BraidMetadata::default()
         };
         let braid = Braid::builder()
@@ -378,7 +379,8 @@ mod proptests {
             .build()
             .expect("should build");
 
-        assert_eq!(braid.metadata.tags, vec!["important"]);
+        let expected: Vec<std::sync::Arc<str>> = vec!["important".into()];
+        assert_eq!(braid.metadata.tags, expected);
     }
 
     #[test]