Journal 3 User-Visible Operation Contract
Purpose
Journal 3 is persistence/synchronization infrastructure. Ordinary callers continue to see IncrementalGraph operations rather than raw Journal IDs, contexts, authority clocks, or writer coordinates.
Ordinary graph APIs
pull()
A successful pull has the existing IncrementalGraph result. Any persisted graph transition and its replay-complete Journal history become durable together.
Fresh no-op, first materialization, changed recomputation, Unchanged, and cache revalidation remain ordinary graph behavior.
invalidate()
Explicit invalidation runs no target computor. It records genuine node invalidation and the actual persistent fresh->stale propagation while retaining cached values which remain safe as oldValue.
Inspection
Inspection reads current materialized projection. It does not execute computors or author semantic history merely because data was read.
Synchronization
synchronizeFrom(source)
requires an established writable receiver.
Success means:
- version/schema compatibility came from the same immutable source snapshot as imported history;
- imported foreign records kept exact identity/body;
- causal/reference rules were validated;
- required receiver normalization committed;
- active graph equals active Journal replay;
- no computor ran; and
- repeating the same incorporated source without intervening changes is a semantic no-op.
Keep versus delete under merged dependency state
- If a selected cached node loses a required materialized input, synchronization explicitly deletes that dependent closure. The node cannot remain materialized under IncrementalGraph structural semantics.
- If every required input remains present, disagreement between current input ValueIds and the dependent's certificate does not by itself delete the cached value. The cache remains a legitimate
oldValue; replay expresses hard/soft stale state through proof/freshness.
So mixed input histories affect validity/freshness, not cache existence, unless structural dependency closure itself fails.
Persistent propagated stale state
Synchronization persistent-stale marker authoring is owned by incremental-graph-journal-sync.md §Phase 2 using selfProofReady(K) from incremental-graph-journal-replay.md §Persistent propagated staleness, including its no-duplicate rule. The user-visible consequence is that later upstream Unchanged cannot erase required sync-persisted staleness.
Synchronization can reveal unsupported local rollback
The user-visible result for the established-writer rollback condition is JournalWriterBehindError; the condition is defined in database-lifecycle.md §5 and synchronization behavior in incremental-graph-journal-sync.md §Receiver-local writer ahead in the source is unsupported state.
Release recovery
Journal 3 release recovery is forward-only as accepted by $id-5083197642258146. Restoring an existing database from an earlier checkpoint or rewinding its remote publication is not a supported rollback path; the lifecycle classification is owned by database-lifecycle.md §14.
A corrected release moves state forward through supported operations and, when needed, a canonical Journal-aware migration. If a known-good source remains version/schema compatible, resetTo() may restore its observable projection while retaining the receiver's already-observed history.
Absent-installation startup
A machine whose local database is completely absent queries an installation recovery source before generating a fresh fingerprint.
- continuation-safe synchronized state exists -> restore that writer/history/projection/allocator state;
- definite absence -> fresh identity may be created;
- read/query/continuation-safety uncertainty -> fail, no fresh fallback.
Continuation safety is defined in database-lifecycle.md §4.1.
The recovery source abstraction does not require one server, one branch, one authority, or one storage topology. Transport locators such as hostnames or branch names remain outside IncrementalGraph-owned persisted state and semantic recovery APIs.
Absent restoration does not apply when a local database still exists but has been partially rolled back, truncated, mixed with older storage, or otherwise externally damaged. Those states are outside the supported lifecycle model.
Initial Journal bootstrap
Pre-Journal replicas which will later synchronize use one frozen canonical bootstrap cut as the shared ValueId basis for occurrences equal to that cut.
The cohort source yields exactly:
Exists(CanonicalBootstrapSnapshot)
DefinitelyAbsent
IndeterminateOrError
Indeterminate/error does not authorize competing canonical creation.
DefinitelyAbsent authorizes only staging a candidate. The cohort winner is selected by conditional publishCanonicalBootstrapIfAbsent: exactly one distinct candidate may be published, a losing creator adopts the returned existing artifact, and an indeterminate publication outcome leaves the legacy database active until re-query resolves the winner. This is the arbitration required by $id-1847369205416728.
The artifact contains exactly the original bootstrap frontier/version/schema, not later cohort history.
Bootstrap is semantic identity
Bootstrap journals the already-persisted supported legacy graph. Before Journal identity exists it does not run ordinary semantic migration decisions such as create/invalidate/delete, synthesize new timestamps/identifiers, or perform a schema-semantic migration.
If such a migration is required, the automatic bootstrap transition is incompatible. Actual graph/schema/representation migration happens before entering the supported legacy source state or afterward as Journal-aware migration.
Creator resume
If the canonical artifact belongs to the still-pre-Journal local fingerprint, startup resumes the interrupted creator transition: direct persisted legacy state must equal artifact projection. On equality install exactly the artifact and reconstruct writer state; on disagreement fail JournalBootstrapForkError. No migration callback reruns and no duplicate bootstrap history is authored.
Exact shared occurrence
Exact-shared bootstrap identity/proof/freshness semantics are defined normatively by incremental-graph-journal-migrations.md §7.3. This user contract relies on that result and does not maintain a second merge formula.
Divergent values and legacy absence
A different/local-only legacy occurrence becomes historical concurrent bootstrap evidence with authority seeded from persisted legacy modifiedAt, not upgrade time.
Canonical-present/local-absent does not manufacture a deletion. Two independent late joiners may assign different ValueIds to the same non-canonical legacy occurrence; $id-1635227135166767 accepts the resulting possible downstream recomputation.
Locally-authored dependent proof keeps legacy provenance
For a locally-authored joining occurrence K, bootstrap records each legacy-valid input edge against the input occurrence that the joining host actually had, not whichever input occurrence wins the later conflict merge.
For an input D, that proof ValueId is:
- the canonical ValueId when the joining D occurrence was exactly canonical-equal; otherwise
- the joining writer's historical bootstrap ValueId for its own D occurrence, even when that D occurrence loses conflict selection.
Therefore a mixed-winner merge cannot manufacture a never-observed combination such as canonical D0 -> joining K1. If K1 was historically validated against joining D1 but D0 wins selection, K1's basis still names D1; replay sees the mismatch and K1 is hard stale until revalidated/recomputed.
Recursive bootstrap staleness
Bootstrap recursive-stale marker authoring is owned by incremental-graph-journal-migrations.md §7.4 using selfProofReady(K) from incremental-graph-journal-replay.md §Persistent propagated staleness. The user-visible consequence is that later upstream Unchanged cannot erase bootstrap-persisted recursive staleness.
A validation authored after the frozen canonical cut but unseen by the late join is concurrent with late-join negative proof/stale evidence and therefore does not erase it until a causally later validation observes/re-proves that evidence. $id-4465456703882268 accepts the resulting conservative revalidation/recomputation cost.
Journal-aware migration
Migration has two distinct parts:
- deterministic whole-history format rewrite;
- semantic target repair.
Representation rewrite
Each directed database-version transition uses the JournalFormatCodec defined normatively by incremental-graph-journal-migrations.md §9a. Its totality, determinism, capability restrictions, target re-canonicalization, and global NodeKey-injectivity requirements are owned there and are not restated in this user contract.
Semantic repair is then evaluated in the codec-transported target NodeKey space. Thus a representation-only Ks -> Kt rename with keep preserves the same selected ValueId instead of looking like a deletion of Ks plus creation of Kt.
When ValueEvent payload representation changes, this codec is the sole source of target bytes across all replicas and all selected/historical occurrences. A selected semantic occurrence whose meaning survives uses keep.
Supported Journal version upgrades follow the canonical version chain in incremental-graph-journal-migrations.md §9b. Skipping an application release does not skip its canonical Journal transition; this keeps pre-existing shared record bodies byte-identical when replicas later meet at the same target version.
Semantic occurrence identity
Occurrence-preserving decisions (keep, invalidate, proof/freshness/schema-only changes, representation-only format rewrite) preserve the ValueId. For keep, source proof/freshness survives only under the occurrence-provenance rule in incremental-graph-journal-migrations.md §11a: a preserved value is never certified against a newly created/replaced input occurrence it did not observe. A new ValueEvent is reserved for actual create/replace occurrence changes.
Independent genuine replacement migrations may create different replacement ValueIds; later synchronization selects normally and may stale dependents naming a losing replacement. This is accepted.
Proof weakening
True migration invalidate(K) remains node-scoped.
If maintenance merely removes incoming validity while preserving V, it first considers every effective edge of every eligible retained certificate for V. For each such edge absent from the target it authors one:
Invalidate(K, scope=proof(V,D), reason=migration)
for every non-target edge D -> K that any eligible retained certificate for the preserved ValueId could expose.
A proof-edge barrier removes only that edge from certificates targeting V until causally re-proved. Concurrent barriers compose by subtracting the union of named edges; they do not destroy unrelated proof or affect V2.
Persistent target stale state
Migration persistent-stale marker authoring is owned by incremental-graph-journal-migrations.md §17 using selfProofReady(K) from incremental-graph-journal-replay.md §Persistent propagated staleness, including its no-duplicate rule. The user-visible consequence is that later upstream Unchanged does not erase required migration-persisted staleness.
Reset
resetTo(source)
requires an established writable receiver and one held compatible source snapshot.
The reset result reports changed = false only when the receiver already retained the entire source snapshot frontier and reset authored no repair records. Missing source history makes the reset a persistent change even if the observable graph projection was already equal to the target.
If the reset source is ahead for the receiver's own writer, the user-visible failure follows incremental-graph-journal-reset.md §Preconditions and the lifecycle boundary in database-lifecycle.md §5.
Reset retains history and establishes the source projection relative to all history it observed. A compatible receiver/source union may be temporarily non-projectable because Value/Delete winners mix across replicas; reset uses raw deterministic head selection for its first occurrence/presence repair rather than sync-normalizing or rejecting that staging union.
- raw-union selected occurrence already matches target immutable occurrence state -> preserve that raw-union selected ValueId, even if the source projection names a different ValueId;
- actual occurrence difference -> new reset ValueEvent;
- every
D in eligibleEffectiveProofUnion(K) - TargetValid(K)for preserved V ->proof(V,D)barrier; - exact target proof -> validation as needed;
- persistent target-stale marker handling ->
incremental-graph-journal-reset.md§Pass 3 usingselfProofReady(K)fromincremental-graph-journal-replay.md§Persistent propagated staleness; - target absence while union selects value -> one DeleteEvent;
- already-selected absence -> no redundant delete.
Reset repairs intentionally causally follow observed history. That causal-later semantics is not used for pre-Journal bootstrap conflicts.
Projection rebuild
Administrative rebuild reconstructs graph/index state from authoritative current-format Journal history. Valid history rebuild is semantically invisible. Malformed authoritative history causes failure rather than rewriting Journal to match graph bytes.
History retention
Journal 3 has no destructive replay-history compaction obligation. Derived indexes/checkpoints may be added independently, but retained Journal history remains semantic authority.