Spec: Journal & Events

Status: Implemented (Format Level 2, see bundle-format.md) — the event vocabulary, JSONL sidecar IO, cross-checks, and projections live in packages/schema/src/journal*.ts and projections.ts; the app dual-writes via lib/data/emit-events.ts, and the CLI reads/writes the sidecar (arkaik log, arkaik release). This document remains the normative contract. The key words MUST, MUST NOT, SHOULD, and MAY are to be interpreted as in RFC 2119.

Purpose

The journal turns status from a mutable field that forgets into a tracked evolution. It is an append-only log of typed events recording how the product graph changed: status transitions, releases, ideas, requests, reference updates. From it, consumers derive the features a static snapshot cannot offer — per-node timelines, changelogs, release notes, and a backlog of ideas and requests.

Storage Shapes

Canonical (repo): JSONL sidecar

In a repository (Kommit mode), the journal is a sidecar file next to the snapshot — never inside it. The snapshot stays small and the history cannot corrupt it.

docs/arkaik/
  bundle.json                     # snapshot (Levels 0–2)
  journal.jsonl                   # append-only, one event per line
  journal/
    archive-1.3.0.jsonl           # compacted history per release (optional)
  assets/                         # repo-hosted asset files

arkaik init configures .gitattributes:

docs/arkaik/journal.jsonl merge=union

JSONL is the one shape where git's union merge is sound: one line = one self-contained event, concurrent appends merge automatically, and order is recoverable from the events themselves. A malformed line invalidates exactly one event — the validator reports the line number — and can never damage existing history or the snapshot. This is the property that makes agent writes safe: appending is structurally incapable of the corrupt-the-whole-JSON failure that whole-file regeneration invites.

Interchange: embedded journal[]

When a single file is needed (drag-in import to the app, Publik, LLM output), arkaik pack embeds the journal as the bundle's optional journal array. This is a projection for transport, not a storage recommendation. Publik publishes without the journal by default — history stays private unless explicitly included.

Event Envelope

One event is one JSON object:

interface JournalEvent {
  id: string;      // ULID — sortable, collision-free without coordination
  ts: string;      // ISO 8601 timestamp
  actor?: string;  // who/what wrote it: "alexis", "claude-code", "arkaik-sync", "ci"
  type: string;    // vocabulary below
  // ...type-specific payload fields, flat on the object
}

Event Vocabulary (v1)

The five quality.* types are Kritik's (docs/rfcs/kritik.md § 3.2). They follow the same rule as every other event — facts, not state: current quality is a projection (deriveQualityMatrix), the latest audit plus opened-minus-resolved-or-accepted findings. Writers SHOULD set actor on them so human, agent, and CI scores stay tellable apart; validateBundle warns when one does not, and never blocks. A trip written from CI against a hosted project carries the commit it observed and, by convention, its run URL in detail — the one writer that always knows both, and pays nothing to say so (issue #406).

Authority & Consistency Model

The journal is not event sourcing, and v1 makes no replay promises. The rules:

1. The snapshot is authoritative for current state. The journal is authoritative for history.
2. Writers (the skill, the CLI, later the app) dual-write: patch the snapshot and append the matching event in the same change.
3. The validator cross-checks the two by value, never by timestamp (per-node timestamps don't exist and clocks lie): the last node.status_changed.to for a node must equal its current status; every node has a node.created or is named by a journal.baseline; no event references a node or edge that never existed (a baselined id counts as having existed). The baseline is what makes adoption possible: a journal that starts life after the graph does would otherwise be flagged for every pre-existing node the moment its first event lands, so a writer MUST emit one covering the uncovered nodes before its first append, and MUST NOT backfill node.created events instead. Any mismatch is a validation error naming both sides. The same rule extends to decisions: the last decision.status_changed.to for a node must equal its current metadata.decision_status (absent reads as proposed). A node with at least one decision.status_changed event but no longer present in the snapshot (legitimately deleted after its last transition) is not cross-checked.
4. Divergence is repaired explicitly: arkaik doctor appends corrective events to make history consistent with the snapshot (the snapshot wins). Consumers MUST NOT silently re-project the snapshot from the journal — that would launder drift instead of surfacing it.

Releases, Compaction & Growth

• release.tagged events are the version markers. The changelog between two versions is the ordered slice of events between their markers; a release note is that slice summarized (by template or by an agent), filtered to the platforms of the affected nodes when platform is used.
• Deliverables sit between events and releases: a deliverable.shipped records a unit of shipped work (typically one merged PR) with a summary note, a url, and the touched node_ids. A deliverable belongs to release V when its first occurrence falls inside V's changelog slice; the first occurrence anchors when it shipped, and later re-appends with the same deliverable_id edit content (latest occurrence wins) without moving it between releases. A first occurrence after the last marker is unreleased. There is no deliverables[] list on release.tagged — the slice is the grouping. A deliverable born from a merged PR's Lab Note carries the full note under lab_note (en required, fr/suggested/ nodes optional) — the bilingual half exists so downstream projections (the pollen feed) keep both languages. A note's nodes are the ids the author declared; they are checked against the snapshot and unioned with the acceptances the pull request mentions to form node_ids, so the event's own list never names a node the graph does not hold.
• arkaik release tags the version, generates the release-note draft, and MAY compact: move the released slice from journal.jsonl to journal/archive-{version}.jsonl. Archives are part of history (projections may read them); the working journal stays small. Compaction differs from the changesets tool's model deliberately — changeset files are consumed at release, journal history is kept.
• Because compaction relocates history rather than dropping it, validators MUST fold journal/archive-*.jsonl in alongside journal.jsonl when a bundle carries no embedded journal: the archives are the journal. Reading only the working file makes an ordinary release look like data loss — the first release archives every node.created, and any later one can archive a node's newest transition and strand an older one as the apparent "last" — so the cross-check would fail a perfectly healthy project. A malformed archive line is the same hard error as a malformed sidecar line, reported with its file and line number. An embedded journal array still wins outright; the packed interchange form carries its own history.
• The hosted app stores journals under a separate storage key from the snapshot store, so history growth never inflates every snapshot write. App-side event emission is gated on the IndexedDB migration for the same reason (see the roadmap in vision.md).

Projections

Projections are pure functions over (snapshot, journal) — the same pattern as the existing status rollups in lib/utils/platform-status.ts. Planned module: lib/utils/journal.ts.

A bundle without a journal simply renders none of these — the empty state, not an error. That is the whole backward-compatibility story.