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)

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; no event references a node or edge that never existed. 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.
• 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.
• 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.