Coldkeep v1.13.4 — Read-Side Dependency Direction and Result Ownership Review

[franchoy]

Coldkeep v1.13.4 — Read-Side Dependency Direction and Result Ownership Review

Coldkeep v1.13.4 reviews, documents, and guards the current ownership boundaries for the read-side surfaces introduced and stabilized across the v1.13.x line.

This release keeps the existing read-side behavior unchanged while making the current seams explicit and protected.

Reviewed surfaces:

• stats
• inspect
• snapshot show
• snapshot diff

What changed

Read-side ownership documentation

Added release documentation covering:

• read-side ownership inventory
• stats result ownership
• inspect dependency direction
• snapshot show ownership
• snapshot diff query/result ownership
• renderer and JSON assembly boundaries
• backend compatibility and package dependency direction
• final ownership summary
• v1.13.5 handoff

Guard tests

Added narrow CLI guard tests protecting the documented public-contract boundaries:

• stats / inspect success JSON remains in the renderer-envelope family
• snapshot show / snapshot diff success JSON remains in the CLI-envelope family
• read-side JSON error envelopes remain CLI-owned
• public output does not leak internal taxonomy helper names
• inspect public targets remain the documented set
• logical-file remains public
• physical-file remains internal-only

Backend compatibility review

Confirmed the current read-side ownership seams remain compatible with the v1.x backend posture:

• SQLite compatibility preserved
• PostgreSQL compatibility preserved
• no SQLite-only assumptions introduced
• PostgreSQL validation remains part of the release gate
• backend-sensitive paths remain behind existing catalog, snapshot, observability, and engine seams

Ownership decisions

stats

The current stats ownership remains unchanged.

• engine keeps the transitional StatsResult wrapper
• observability owns concrete aggregation
• renderer owns human and success JSON output
• CLI owns public error envelopes

inspect

The current direct CLI -> observability path remains unchanged.

• observability owns inspect logic and result shape
• CLI owns public target validation and error mapping
• renderer owns human and success JSON output
• EntityPhysicalFile remains internal-only

snapshot show

The current mixed ownership remains unchanged.

• metadata and stats/count paths remain engine-backed through CLI helpers
• file listing remains snapshot-package-backed
• CLI owns success JSON assembly
• renderer owns human output
• count fields remain stable

snapshot diff

The current split ownership remains unchanged.

• CLI owns validation, richer query parsing, summary selection, --filter post-processing, count projection, and success JSON assembly
• engine owns the provisional diff request/routing seam
• snapshot owns core detailed diff logic
• renderer owns human output
• summary/detailed behavior remains stable

Behavior impact

No public behavior changes are intended.

Preserved:

• CLI behavior
• human output
• JSON output
• JSON error envelopes
• exit codes
• command routing
• engine routing
• schema and migrations
• storage format
• repository format
• backend defaults
• SQLite compatibility
• PostgreSQL compatibility

Validation

The v1.13.4 release gate completed successfully after a local PostgreSQL reachability blocker was diagnosed, recorded, remediated, and rerun from the beginning.

Validated:

• formatting and static checks
• script checks
• golangci-lint
• go vet
• plain and AES-GCM race tests
• full Go test suite
• integration matrix
• long-run integration checks
• adversarial suite
• focused G14–G17 adversarial tests
• smoke tests
• benchmark matrix and regression thresholds
• legacy compatibility test
• local cross-platform approximation
• critical coverage report generation
• snapshot release gate
• PR CI
• main CI after merge

Notes

This release intentionally does not perform a broad read-side routing migration, result-type migration, JSON-envelope unification, or backend-default change.

The current seams are now documented transitional boundaries for v1.13.x and can be revisited later with stronger guardrails already in place.

---

This discussion was created from the release Coldkeep v1.13.4 — Read-Side Dependency Direction and Result Ownership Review.