Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/reference/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ writing both marks, not editing the page and leaving the rule to look broken.
|---|---|
| [kiro-cli/](kiro-cli/README.md) | The `kiro-cli` documentation, taken from the 2.x line. kiro-cli is Kiro Crew's required agent backend, so its ACP surface, agent-spec schema, and MCP config shape are load-bearing here. |
| [ledger-conductor-sequence.md](ledger-conductor-sequence.md) | **Named exception — local page, no upstream.** Kiro Crew's own end-to-end sequence for the work-ledger dispatch lifecycle. Preserve it across a re-fetch. |
| [ledger/](ledger/README.md) | **Named exception — local pages, no upstream.** API-style reference for the append-only ledger: envelope, session entry types, crew entry types, the reader and writer surface, and the error codes. Preserve it across a re-fetch. |

Where Kiro Crew's own behavior differs from a mirrored page, Kiro Crew's docs win:
this fork is KiroACP-only and does not use every capability the upstream CLI
Expand Down
153 changes: 153 additions & 0 deletions docs/reference/ledger/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
# Ledger reference

**Local page, not a mirror.** This directory is Kiro Crew's own documentation and
has no upstream source, so a re-fetch of the `kiro-cli/` mirror must leave it
alone. It is marked as a named exception in [the Reference index](../README.md).

A ledger is one append-only JSONL file per unit. A writer adds lines to the end
and never rewrites a line already there, so the file — not a context window, not
a summary — is the authority for what happened to that unit. Every line after the
first carries a writer-assigned `seq` that is contiguous from 1 within the file,
so a reader folds the lines in `seq` order and gets exactly one reading of the
unit's history.

These pages say WHAT the format is. For WHY it is shaped this way, read
[`ledger-core.md`](../../system-specs/modules/ledger-core.md) and
[`session-ledger-emitter.md`](../../system-specs/modules/session-ledger-emitter.md).

## Contents

| Page | What it covers |
|---|---|
| [envelope.md](envelope.md) | File layout, header fields, the eight common entry fields, `ref` and `thread`. Kind-independent. |
| [session-types.md](session-types.md) | Every session ledger entry type, one subsection each, with fields and an example. |
| [crew-types.md](crew-types.md) | The crew ledger's type families and the two dispatch contracts. |
| [reading-and-writing.md](reading-and-writing.md) | Reader API, writer rules, ownership, and the fail-soft emitter. |
| [errors.md](errors.md) | Every `LedgerError` code, its trigger, and what a caller does about it. |

## Glossary

**ledger** — the storage layer (`kiro_crew.ledger`): a file format, the rules for
who may write what, and the read-back paths. "Append-only log" names the same
thing; these pages say *ledger* throughout.

**unit** — the thing a ledger belongs to. One unit, one ledger.

**kind** — which of the two unit types a ledger is: `crew` or `session`. A kind
decides which `type` domains may be written to the file and which `src` values may
write them.

**session ledger** — a `session`-kind ledger, keyed by an ACP session id,
recording one session's turn lifecycle. [session-types.md](session-types.md)
covers it.

**crew ledger** — a `crew`-kind ledger. Same envelope, different type domains, and
the place `thread` and guest-namespaced types are used.
[crew-types.md](crew-types.md) covers it.

**entry** — one line after the header: an envelope plus a type-specific `data`
object.

**segment** — one physical file in a unit's ledger. A unit's history may span
several, read oldest first. Every segment repeats the header.

**opener / closer** — a pair of types where one records that something started and
the other that it ended. A closer is what makes an interrupted opener detectable.

## What a ledger is not

It is not the **SEL security audit log**, which records security-relevant
decisions for an auditor and answers a different question.

It is not a **session transcript**. Transcripts are message-grain, are rewritten
by rotation and compaction, and are a best-effort shadow of what a session slot
held. A ledger is operation-grain and append-only.

It is not the **per-turn usage row store**, which measures token and credit cost
per turn for reporting.

It is not a **global event stream**. A day-sharded stream of lifecycle events
joined by a correlation key is a different shape: it has no per-unit `seq`, so it
cannot be folded into one unit's authoritative history. No emitter writes the same
fact to both.

## The pointer model

An entry cites another ledger with `ref`. A session's header points back at the
crew row that dispatched it with `thread`. Neither copies bytes: both name a
location, and a reader that wants the content goes and reads it.

```mermaid
flowchart LR
subgraph crew["crew ledger — crews/<store name>/ledger.jsonl"]
D["seq 41 · crew/dispatch<br/>data.target → a session"]
R["seq 58 · crew/report<br/>thread: 41<br/>ref: {unit: session, id: s-7f3a, from: 12, to: 40}"]
end
subgraph sess["session ledger — sessions/&lt;store name&gt;/ledger.jsonl"]
H["line 1 · header<br/>thread: {crew: qa, seq: 41}"]
S["seq 12 … seq 40<br/>the cited segment"]
end
R -- "ref cites the work" --> S
H -- "thread names the dispatch" --> D
R -. "thread groups the reply<br/>onto the dispatch" .-> D
```

Two things are worth reading off that diagram. The `ref` is the one deliberate
cross-kind pointer: a crew entry cites a span of a session's file. The `thread` is
always within-file — `crew/report` threads onto `crew/dispatch` because both are
lines in the crew ledger — except on the session *header*, where `thread` is a
back-pointer naming a row in another unit and is spelled `{crew, seq}` rather than
a bare int.

## Guarantees

Each guarantee names the error a caller gets when it is enforced against them.

**Append-only.** A writer adds lines. Nothing already written is rewritten in
place, so a reader that has folded up to `seq` N never has to re-read below N.

**`seq` is contiguous from 1, and one writer owns a file.** Seq is assigned under
the unit's lock as `last_seq + 1`, read back from the file's own tail rather than
from a cached counter. A second process that tries to append gets
[`already_owned`](errors.md#already_owned) and appends nothing. A gap between two
segments mid-chain is damage, not a pruned log:
[`segment_gap`](errors.md#segment_gap).

**Crash closers are deterministic.** Opening a session ledger with repair on
truncates a torn tail, drops a trailing orphan chunk run, and writes one closer
per still-open opener with a fixed value per type. The same file always repairs to
the same bytes. See [reading-and-writing.md](reading-and-writing.md#crash-repair).

**An oversize entry is refused, never truncated.** The serialized line ceiling is
64 KiB (`MAX_ENTRY_BYTES`). A line over it raises
[`entry_too_large`](errors.md#entry_too_large) before any byte is written, so a
reader never meets a half-recorded fact. An oversize *body* is split into
`message/chunk` entries by the emitter instead of being clipped.

**A `ref` spans at most 500 lines** (`MAX_REF_SPAN`). A citation is a pointer, not
a bulk export; a wider span raises [`bad_ref`](errors.md#bad_ref).

**A reader is never handed an entry it cannot interpret.** A reader that declares
the types it knows gets [`unknown_entry_type`](errors.md#unknown_entry_type) on an
unknown entry, unless the writer marked that entry `ignorable`. Reconstruction
stops rather than silently skipping a line that may change the meaning of every
line after it.

**Every file identifies its own unit.** Line 1 names the kind and the id, and each
segment repeats it. A header that names a different unit, or a version this build
does not read, is refused: [`bad_header`](errors.md#bad_header),
[`bad_segment`](errors.md#bad_segment),
[`unsupported_version`](errors.md#unsupported_version).

**Agent file tools cannot reach `ledgers/`.** The whole root is a fenced leaf in
the shared sensitive-path floor, so a prompt-injected agent cannot read another
unit's history or forge a line into its own. The ledger's own code opens the files
directly and is unaffected.

**Session emission is off by default.** The session emitter is inert unless
`KIROCREW_SESSION_LEDGER` is truthy. With the flag unset no ledger directory is
created and no emit path reaches storage.

**The format is PRE-RELEASE.** Shapes may change while the flag is off by default.
Do not build a stored artifact that assumes a field will keep its name or its
presence rule until the flag ships on.
149 changes: 149 additions & 0 deletions docs/reference/ledger/crew-types.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
# Crew ledger entry types

**Local page, not a mirror.** Part of the [ledger reference](README.md), which is
marked as a named exception in [the Reference index](../README.md).

> **No crew emitter exists.** The families and the two contracts on this page are
> the specified shape a crew writer must produce. The `crew/dispatch` and
> `crew/report` contracts are defined here and in
> [`ledger-core.md`](../../system-specs/modules/ledger-core.md); a validator that
> refuses a malformed one is pending. Treat every field rule below as the
> agreement, not as something the code enforces today.

A crew ledger uses the same file layout, the same header rules and the same eight
envelope fields as a session ledger — [envelope.md](envelope.md) covers all of
that. Three things differ: which `type` domains may be written, which `src` values
may write them, and the fact that `thread` and `ref` are actually used.

## The layering rule

There is one base envelope, then two disjoint sets of types on top of it. A type
belongs to exactly one kind, and the kind of the ledger decides whether a type may
be written to it at all. Writing a crew-owned type into a session ledger is refused
with [`event_type_not_owned`](errors.md#event_type_not_owned), and the reverse is
refused the same way.

The crew kind owns eight `type` domains: `member`, `activity`, `slot`, `patrol`,
`message`, `crew`, `item`, `memory`.

Two overlaps between the kinds are deliberate rather than accidental. The
`message` domain exists in **both** kinds, carrying different `data` in each:
ownership answers "does this kind have such events", and a crew and a session both
do. And `ref` **crosses** kinds — a crew entry citing a span of a session's file is
the one intended cross-kind pointer.

A type name never carries the writer's identity. Who wrote a line is `src`, not
part of `type`, so a dispatch written by one crew and a dispatch written by another
are the same type and a reader folds them together. The `app:<name>/<action>` guest
form is reserved for facts an app defines that no built-in domain covers.

## Allowed `src`

A crew entry is written by one of:

| `src` | Who it is |
|---|---|
| `dashboard` | The dashboard, acting for the person using it. |
| `patrol` | A patrol pass. |
| `gateway` | The gateway itself. |
| `crew:<name>` | A named crew, writing into its own crew ledger. |
| `app:<name>` | A named app, writing only its own `app:<name>/…` types, and only into a crew ledger. |

`dashboard` and `patrol` are crew-side values: a session entry is written with
`gateway` or `acp` and nothing else.

A guest's own name is its write permission. A `crew:<name>` writer may write
crew-owned types into that crew's ledger; an `app:<name>` writer is confined to its
own namespace. Writing outside it is
[`namespace_violation`](errors.md#namespace_violation), and an unparseable `src` is
[`bad_src`](errors.md#bad_src).

## Families

From the RFC's event-family model. Each row names the shape of a family rather than
an exhaustive type list, because a new action under an owned domain needs no
registry change.

| Family | Types | What it points at |
|---|---|---|
| shipped | `member/*`, `activity/record`, `slot/*`, `patrol/*` | `slot/*` cites the session it shipped. |
| messages | `message/received`, `message/sent` | The redacted body is in the ledger; a permalink reply cites its anchor with `ref`. |
| tree | `crew/child-attached`, `crew/parent-attached`, and their `-detached` counterparts | — |
| dispatch | `crew/dispatch`, `crew/report` | A report cites the child's segment. |
| topics | `crew/topic-*`, `crew/forwarded`, `crew/run-state` | A topic cites its work session. |
| items | `item/phase`, `item/next`, `item/probe`, `item/verdict`, `crew/round-*` | A probe and a verdict cite their evidence. |
| knowledge | `crew/finding`, `crew/summary`, `crew/note-*`, `crew/link` | The segment covered. |
| memory | `memory/bound`, `memory/copied`, `memory/forgotten`, `memory/restored` | — |

The chat surface is a fold over the `messages` family rather than a separate store.
A direct message is the entries with no `thread`; a thread page is the entries whose
`thread` is that anchor; a reply that quotes a line is a `message/sent` whose `ref`
names it.

## `crew/dispatch`

A crew handed one work item to a target.

**Kind and `src`** — `crew`; written by the dispatching party, so `src` is
`dashboard`, `patrol`, `gateway` or `crew:<name>`.

**Pairing** — Opener. Answered by one or more [`crew/report`](#crewreport) entries
that thread onto its `seq`.

| Field | Type | Required | Meaning | Enum |
|---|---|---|---|---|
| `item` | string | required | The work item's id. | |
| `target` | object | required | Who the item went to. **A dispatch without a target is invalid.** | |
| `target.kind` | string | required | Which sort of target. | `session`, `crew` |
| `target.slot` | string | conditional | The slot key, required when `target.kind` is `session`. | |
| `target.name` | string | conditional | The crew name, required when `target.kind` is `crew`. | |
| `brief` | string | optional | The brief handed over. | |

**Invariants** — `target` is required and its `kind` decides which of `slot` or
`name` must be present. The two forms are exclusive: a target names a session slot
or a crew, never both.

```json
{"type":"crew/dispatch","seq":41,"time":1789000003000,"src":"crew:qa","data":{"item":"WI-4","target":{"kind":"session","slot":"dashboard:7"},"brief":"write the reference pages"}}
```

**Reader hint** — Group a work item's history by `item`, then order it by `seq`. The
dispatch is the anchor every report threads onto.

## `crew/report`

A dispatched party reported back on one work item.

**Kind and `src`** — `crew`; written by the reporting party, so `src` is
`crew:<name>` for a crew and `gateway` for a session's own report.

**Pairing** — Closer in practice, though a `progress` status leaves the item open.
`thread` is the dispatch's `seq`.

| Field | Type | Required | Meaning | Enum |
|---|---|---|---|---|
| `item` | string | required | The work item's id, matching the dispatch. | |
| `status` | string | required | Where the item stands. | `done`, `blocked`, `failed`, `progress` |
| `credits` | number | optional | What the work cost. | |
| `summary` | string | optional | What was done. | |

**Envelope requirements** — Unlike every other type documented here, `crew/report`
constrains the envelope as well as `data`:

- **`ref` is required.** It cites the segment of the child's ledger holding the
work, so a report is never a claim without evidence. The span cap of 500 lines
(`MAX_REF_SPAN`) applies, so a long run is cited by its relevant span rather than
in full.
- **`thread`** is the `seq` of the `crew/dispatch` being answered.

**Invariants** — A report without a `ref` is invalid. `status: "progress"` may
appear several times for one dispatch; a terminal status appears once.

```json
{"type":"crew/report","seq":58,"time":1789000004000,"src":"crew:qa","thread":41,"ref":{"unit":"session","id":"s-7f3a","from":12,"to":40},"data":{"item":"WI-4","status":"done","credits":1.42,"summary":"six pages and a test"}}
```

**Reader hint** — Resolve the `ref` to read the work itself, and handle all four
statuses the resolution can answer with — the cited ledger may be gone or pruned
long after the report was written. See
[reading-and-writing.md](reading-and-writing.md#resolving-a-ref).
Loading
Loading