---
id: capability.wiki.coordination-journal
name: Event-Sourced Coordination Journal
summary: An append-only, totally-ordered-per-space decision log (overlays, bindings, aliases, merges, forks) whose current state is a derived fold; git-addressable history.
owner: shard-wiki
status: draft
domain: helix_forge
tags: [wiki, event-sourcing, coordination, git, journal, shard-wiki]

maturity:
  discovery:
    current: D5
    target: D6
    confidence: high
    rationale: >
      Keystone resolved across two architecture reviews: coordination-canonical state
      as an append-only decision log with a per-space append authority; current state
      is a derived fold (derived = f(log)).
  availability:
    current: A2
    target: A4
    confidence: medium
    rationale: >
      In-memory DecisionLog + fold work as a source module; the git-backed store with a
      per-space lease (the production backing) is planned.

external_evidence:
  completeness:
    level: C2
    name: Partial
    confidence: medium
    basis: scope_vs_intent_and_consumer_expectations
    satisfied_expectations:
      - append-only, totally-ordered-per-space log with read-your-writes
      - derived fold to aliases + transitively-merged equivalence groups
    broken_expectations:
      - git-backed storage and per-space lease/append-authority not yet implemented
    out_of_scope_expectations:
      - general-purpose event bus
  reliability:
    level: R1
    confidence: low
    basis: consumer_quality_signals
    known_reliability_risks:
      - in-memory backing only; cross-process durability pending

discovery:
  intent: >
    Make coordination-canonical decisions durable and git-addressable as events, with the
    queryable current state always recomputable by replay.
  includes:
    - append-only decision log, totally ordered per information space
    - derived fold to current coordination state (aliases, equivalence groups, overlays)
    - per-space append authority (concurrency model)
  excludes:
    - storing derived/disposable union state
  use_cases:
    - "shard-wiki UseCaseCatalog UC-29, UC-33 (history, attribution, coordination journal)"

availability:
  current_level: A2
  target_level: A4
  current_artifacts:
    - "shard-wiki/src/shard_wiki/coordination/decision_log.py"
  target_artifacts:
    - git-backed log store with per-space lease
  consumption_modes:
    - source module

relations:
  supports:
    - capability.wiki.shard-orchestration
    - capability.wiki.overlay

evidence:
  documentation:
    - "shard-wiki/spec/CoreArchitectureBlueprint.md (Section 8.1)"
  tests:
    - "shard-wiki/tests/test_decision_log.py"

consumer_guidance:
  recommended_for:
    - durable, replayable, git-addressable coordination state for a federated space
  not_recommended_for:
    - high-frequency general event streaming
  known_limitations:
    - production git backing + lease are still on the roadmap (SHARD-WP-0009)
---

# Event-Sourced Coordination Journal

The keystone: coordination-canonical state (overlays, equivalence bindings, aliases, merges,
forks) is an append-only **decision log**, totally ordered per information space; the queryable
current state is a derived **fold** of the log (`derived = f(log)`). The log is git-addressable,
giving history/patch/review/backup for coordination decisions for free.

## Assessment notes

### Discovery
Resolved across the round-1/round-2 architecture reviews (CoreArchitectureBlueprint Section 8.1).

### Availability
`decision_log.py` ships an in-memory, totally-ordered log + fold; git+lease backing is planned.