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
2 changes: 1 addition & 1 deletion docs/reference/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +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. |
| [crew-log/](crew-log/README.md) | **Named exception — local pages, no upstream.** API-style reference for the append-only crew log: 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
Original file line number Diff line number Diff line change
@@ -1,67 +1,67 @@
# Ledger reference
# Crew log 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
A crew log 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).
[`crew-log-core.md`](../../system-specs/modules/crew-log-core.md) and
[`crew-log-emitter.md`](../../system-specs/modules/crew-log-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. |
| [session-types.md](session-types.md) | Every session log entry type, one subsection each, with fields and an example. |
| [crew-types.md](crew-types.md) | The crew's log'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
**crew log** — the storage layer (`kiro_crew.crew_log`): 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.
thing; these pages say *crew log* throughout.

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

**kind** — which of the two unit types a ledger is: `crew` or `session`. A kind
**kind** — which of the two unit types a crew log 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,
**the session's log** — a `session`-kind crew log, 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 crew's log** — a `crew`-kind crew log. 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
**segment** — one physical file in a unit's crew log. 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
## What a crew log 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.
held. A crew log 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.
Expand All @@ -73,17 +73,17 @@ fact to both.

## The pointer model

An entry cites another ledger with `ref`. A session's header points back at the
An entry cites another crew log 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"]
subgraph crew["the crew's log — crews/<store name>/log.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"]
subgraph sess["the session's log — sessions/&lt;store name&gt;/log.jsonl"]
H["line 1 · header<br/>thread: {crew: qa, seq: 41}"]
S["seq 12 … seq 40<br/>the cited segment"]
end
Expand All @@ -95,7 +95,7 @@ flowchart LR
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
lines in the crew's log — 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.

Expand All @@ -113,7 +113,7 @@ from a cached counter. A second process that tries to append gets
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
**Crash closers are deterministic.** Opening a session's log 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).
Expand All @@ -139,13 +139,13 @@ 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
**Agent file tools cannot reach `crew-log/`.** 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
unit's history or forge a line into its own. The crew log'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
`KIROCREW_CREW_LOG` is truthy. With the flag unset no crew log directory is
created and no emit path reaches storage.

**The format is PRE-RELEASE.** Shapes may change while the flag is off by default.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,25 +1,25 @@
# Crew ledger entry types
# The crew's log entry types

**Local page, not a mirror.** Part of the [ledger reference](README.md), which is
**Local page, not a mirror.** Part of the [crew log 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
> [`crew-log-core.md`](../../system-specs/modules/crew-log-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
A crew's log uses the same file layout, the same header rules and the same eight
envelope fields as a session's log — [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
belongs to exactly one kind, and the kind of the crew log decides whether a type may
be written to it at all. Writing a crew-owned type into a session's log is refused
with [`event_type_not_owned`](errors.md#event_type_not_owned), and the reverse is
refused the same way.

Expand All @@ -46,14 +46,14 @@ A crew entry is written by one of:
| `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. |
| `crew:<name>` | A named crew, writing into its own crew log. |
| `app:<name>` | A named app, writing only its own `app:<name>/…` types, and only into a crew log. |

`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
crew-owned types into that crew's crew log; 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).
Expand All @@ -67,7 +67,7 @@ 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`. |
| messages | `message/received`, `message/sent` | The redacted body is in the crew log; 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. |
Expand Down Expand Up @@ -130,7 +130,7 @@ A dispatched party reported back on one work item.
**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
- **`ref` is required.** It cites the segment of the child's crew log 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.
Expand All @@ -144,6 +144,6 @@ appear several times for one dispatch; a terminal status appears once.
```

**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
statuses the resolution can answer with — the cited crew log may be gone or pruned
long after the report was written. See
[reading-and-writing.md](reading-and-writing.md#resolving-a-ref).
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
# Envelope

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

Everything here is kind-independent: it holds for a session ledger and a crew
ledger alike. What differs between the two kinds is which `type` domains and which
Everything here is kind-independent: it holds for a session's log and a crew's
log alike. What differs between the two kinds is which `type` domains and which
`src` values are allowed, which [session-types.md](session-types.md) and
[crew-types.md](crew-types.md) cover.

## File layout

```
<data home>/ledgers/crews/<store name>/ledger.jsonl
<data home>/ledgers/sessions/<store name>/ledger.jsonl
<data home>/crew-log/crews/<store name>/log.jsonl
<data home>/crew-log/sessions/<store name>/log.jsonl
```

`ledgers` is one shared root for both kinds, which is what lets a single fence
`crew-log` is one shared root for both kinds, which is what lets a single fence
entry cover every unit kind at once. Under it, `crews/` holds crew units and
`sessions/` holds session units.

Expand All @@ -29,14 +29,14 @@ Each unit directory holds:

| Path | What it is |
|---|---|
| `ledger.jsonl` | The segment whose first entry is `seq` 1. The only segment a writer creates. |
| `ledger.<first seq>.jsonl` | A later segment. The filename's middle is its first entry's `seq`, all digits and greater than 1. |
| `log.jsonl` | The segment whose first entry is `seq` 1. The only segment a writer creates. |
| `log.<first seq>.jsonl` | A later segment. The filename's middle is its first entry's `seq`, all digits and greater than 1. |
| `.lock` | The append lock. Held only for the duration of one append, and it is what makes `seq` assignment serial. |
| `.lease` | The write-ownership lease. Held for as long as a handle can still append. See [reading-and-writing.md](reading-and-writing.md#ownership). |

Line 1 of a segment is a header object. Every later line is an entry. **Every
segment repeats the header**, not just the first one, so a unit whose oldest
segment is gone is still a readable ledger. A reader validates each segment's
segment is gone is still a readable crew log. A reader validates each segment's
header against the unit it opened and checks that the filename's declared first
`seq` matches the segment's first readable entry.

Expand All @@ -56,7 +56,7 @@ Common to both kinds:
| `type` | string | required | The unit kind this file belongs to. | `crew`, `session` |
| `version` | int | required | Header schema version. A file declaring a version this build does not read is refused with [`unsupported_version`](errors.md#unsupported_version). | `1` |
| `id` | string | required | The raw unit id. Must match the id the reader opened. | |
| `createdAt` | int | required | Epoch milliseconds the unit's ledger was created. | |
| `createdAt` | int | required | Epoch milliseconds the unit's crew log was created. | |

A **crew** header carries nothing beyond those four: a crew's identity is its id,
and every fact about it is an entry rather than a header field.
Expand Down Expand Up @@ -98,12 +98,12 @@ present, then `data` last.

| Field | Type | Required | Meaning | Enum |
|---|---|---|---|---|
| `type` | string | required | `domain/action`, partitioned on the first slash. The action may not itself contain a slash, so a namespace is exactly one level deep. A guest form `app:<name>/<action>` exists for crew ledgers. | |
| `type` | string | required | `domain/action`, partitioned on the first slash. The action may not itself contain a slash, so a namespace is exactly one level deep. A guest form `app:<name>/<action>` exists for crew logs. | |
| `seq` | int ≥ 1 | required | Writer-assigned under the unit's lock, contiguous from 1 after the header. | |
| `time` | int | required | Writer-assigned epoch milliseconds. | |
| `src` | string | required | Which emitter wrote the line. | `gateway`, `acp`, `dashboard`, `patrol`, or `session:<id>` / `crew:<name>` / `app:<name>` |
| `thread` | int ≥ 1 | optional | The `seq` of an earlier entry in this same file, used as a grouping key. Refused if it names no earlier readable entry ([`bad_thread`](errors.md#bad_thread)). Session emitters never set it. | |
| `ref` | object | optional | A citation into another or the same ledger. | |
| `ref` | object | optional | A citation into another or the same crew log. | |
| `ignorable` | `true` | optional | The writer's promise that a reader may skip this line when it does not know the type. Only a literal `true` is written; the key is absent otherwise. | `true` |
| `data` | object | required | The type-specific payload. Must be a JSON object holding JSON-serializable values ([`bad_data`](errors.md#bad_data)). | |

Expand All @@ -130,7 +130,7 @@ written.

## `ref`

A `ref` is a citation, not a copy: the bytes stay in the ledger they were written
A `ref` is a citation, not a copy: the bytes stay in the crew log they were written
to, and a reader resolves the pointer when it wants them.

```json
Expand All @@ -139,7 +139,7 @@ to, and a reader resolves the pointer when it wants them.

| Field | Type | Required | Meaning | Enum |
|---|---|---|---|---|
| `unit` | string | required | The kind of ledger being cited. | `crew`, `session` |
| `unit` | string | required | The kind of crew log being cited. | `crew`, `session` |
| `id` | string | required | The cited unit's raw id. | |
| `from` | int ≥ 1 | required | First cited `seq`. | |
| `to` | int ≥ `from` | optional | Last cited `seq`. Absent cites the single line at `from`. | |
Expand All @@ -150,15 +150,15 @@ over-wide span — is [`bad_ref`](errors.md#bad_ref), raised when the ref is
constructed rather than when it is resolved.

Resolving a ref answers with a status rather than an exception, because a cited
ledger may legitimately be gone or pruned. The four statuses are on
crew log may legitimately be gone or pruned. The four statuses are on
[reading-and-writing.md](reading-and-writing.md#resolving-a-ref).

## `thread`

`thread` groups entries inside one file: it holds the `seq` of an earlier entry in
the same ledger, and a reader pages a group by that anchor. It is validated
the same crew log, and a reader pages a group by that anchor. It is validated
against the file at append time, so it can never name a line that does not exist
or one that comes later.

Session entries never carry it. It is the crew ledger's shape, where a report
Session entries never carry it. It is the crew's log's shape, where a report
threads onto the dispatch it answers.
Loading
Loading