# v0.94.0 — Strict Transactional Graph Refresh

> **Status:** Planned
> **Scope:** Large
> **User promise:** *"Refresh a private graph atomically inside one transaction with exact boundaries."*
> **Blocked by:** [v0.93.0](v0.93.0.md)
> **Delivery plan:** Phase 2 of
> [Proposal: V1 Composable Refresh and Durable Delta Contracts](../plans/PROPOSAL_V1_COMPOSABLE_REFRESH_AND_DELTA_CONTRACTS.md)

## Theme

Complete Graph V1 with strict synchronous graph refresh. Validate and lock the
entire graph before execution, compute one immutable and complete source
boundary, refresh every member in topological order through the common
transactional finalizer, and return one structured result inside the caller's
outer PostgreSQL transaction.

Graph V1 remains disabled or experimental until this release's independent
acceptance gate passes. Delta V1 is not part of this gate.

## Items

### GV1-5: Strict graph-refresh context

Add `refresh_graph_strict()` over one structured internal graph-refresh
context. Reject duplicate roots, unsupported cycles or sources, temporary or
cross-database relations, `IMMEDIATE` members, non-`EXTERNAL` members, stale
contracts, and unauthorized members before the first node executes.

Acquire all member and admitted-source locks in canonical order before
execution. Busy work, lock timeout, concurrent lifecycle change, or contract
mismatch is a stable error, never a notice-and-skip success.

### GV1-6: Complete source-boundary proof

Compute one immutable source-boundary manifest after locks are held. Every
admitted source has a typed identity, capture mode, durable position, and proof
status. Unknown, partial, missing, or unverifiable boundaries abort the graph;
several incomparable source positions are never collapsed into a timestamp.

Bind graph refresh identifiers and manifests to the v0.92.0
database-instance identity so clones cannot reuse source-system evidence.

### GV1-7: Atomic graph execution and result

Execute the complete closure synchronously in canonical topological order.
Every member uses the same prepare, owner-execute, and transactional finalize
path as ordinary refresh. Return the requested and actual graph digests,
contract generations, graph refresh identifier, complete boundary manifest,
and exact or explicitly qualified per-node outcomes.

The function performs no commit. Stream-table contents, frontiers, cleanup,
history, graph metadata, and coordinator-owned writes commit or roll back with
the caller's transaction. No-data execution still validates contracts, locks,
and boundaries.

### GV1-8: Graph diagnostics and conformance

Expose graph status, health rows, history, stable error identifiers, and
metrics for strict refreshes, busy conflicts, contract failures, and boundary
failures. Publish operational documentation, transaction limits, source-class
admission, and capacity bounds.

## Exit criteria

- [ ] A conformance extension refreshes one-node, chain, shared-upstream, and
      diamond graphs against one complete source boundary
- [ ] It reads complete terminal tables and publishes coordinator-owned state
      before committing the same outer transaction
- [ ] Coordinator failure rolls back graph contents, frontiers, history, and
      coordinator state without a committed member subset
- [ ] Concurrent refresh, alter, repair, mode change, and drop tests prove the
      canonical lock order and strict busy behavior
- [ ] Source writers on both sides of the safe boundary produce no lost or
      double-consumed changes
- [ ] Every unadmitted or unverifiable source class fails before member
      execution
- [ ] Crash, restore, clone, and supported-upgrade tests preserve contracts and
      reject stale database-instance identity
- [ ] `external_graph_refresh` advertises stable major version 1 only after its
      transaction, concurrency, security, recovery, upgrade, and performance
      gates pass