# @qmilab/lodestar-event-log

> Append-only NDJSON event log writer and reader for the Lodestar epistemic chain. Part of Lodestar, the trust layer for AI agents.

Latest version **0.5.0** (published 2026-07-01) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @qmilab/lodestar-event-log
pnpm add @qmilab/lodestar-event-log
yarn add @qmilab/lodestar-event-log
bun add @qmilab/lodestar-event-log
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.5.0 |
| Published | 2026-07-01 |
| First published | 2026-05-25 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 52.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 3 |
| Author | QMI Lab |
| Maintainers | cybernandan |
| Keywords | ai-agents, trust, lodestar, event-log, audit-trail, ndjson, append-only, replay |

## Links

- npm: https://www.npmjs.com/package/@qmilab/lodestar-event-log
- Repository: https://github.com/qmilab/lodestar
- Homepage: https://qmilab.com/lodestar
- Issues: https://github.com/qmilab/lodestar/issues
- npm.io page: https://npm.io/package/@qmilab/lodestar-event-log

## Dependencies (2)

- [zod](https://npm.io/package/zod.md) ^3.23.8
- [@qmilab/lodestar-core](https://npm.io/package/@qmilab/lodestar-core.md) 0.5.0

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.5.0 (latest) — 2026-07-01
- 0.4.0 — 2026-06-20
- 0.3.0 — 2026-06-12
- 0.2.0 — 2026-06-08
- 0.1.5 — 2026-05-25
- 0.1.4 — 2026-05-25
- 0.1.1 — 2026-05-25

## README

# @qmilab/lodestar-event-log

Append-only NDJSON event log for the Lodestar epistemic chain. Part of
[Lodestar](https://qmilab.com/lodestar) — the trust layer for AI agents.

Every governance event in Lodestar (observation, claim, belief
adoption, firewall transition, action proposal, action outcome,
revision) flows through this log. The log is the source of truth that
`@qmilab/lodestar-trace` reads to produce trust reports, and the
substrate replay-grade audit is built on.

## Install

```sh
npm install @qmilab/lodestar-event-log @qmilab/lodestar-core
# or
bun add @qmilab/lodestar-event-log @qmilab/lodestar-core
```

## Usage

### Writing

```ts
import { EventLogWriter, canonicalHash } from "@qmilab/lodestar-event-log"

const writer = new EventLogWriter(".lodestar/events")

await writer.append({
  id: crypto.randomUUID(),
  type: "observation.recorded",
  schema_version: "0.1.0",
  project_id: "my-project",
  session_id: "session-1",
  actor_id: "agent-1",
  timestamp: new Date().toISOString(),
  causal_parent_ids: [],
  payload: { what: "an example observation" },
  payload_hash: canonicalHash({ what: "an example observation" }),
  versions: { schema_registry_version: "0.1.0" },
})
```

The writer assigns each event a monotonic per-project `seq` and a
per-session `logical_clock`. Both are stored in the envelope so
downstream readers can reconstruct ordering and causality without
re-deriving them.

### Reading

```ts
import { EventLogReader } from "@qmilab/lodestar-event-log"

const reader = new EventLogReader(".lodestar/events")

// All events for a project, in seq order:
const all = await reader.readAll("my-project")

// Just the events for one session, in logical-clock order:
const session = await reader.readSession("my-project", "session-1")
```

`projectChain` and `renderReport` from `@qmilab/lodestar-trace`
consume the reader's output to produce the trust reports that the
`lodestar report` CLI emits.

## File layout

One NDJSON file per `(project_id, day)` under
`<root>/<project_id>/<YYYY-MM-DD>.ndjson`. Each line is a single JSON
event envelope. The writer validates every envelope against the
`EventEnvelopeSchema` from `@qmilab/lodestar-core` before writing —
malformed envelopes never reach disk.

## Concurrency

The writer maintains process-wide partition state (per `rootDir` ×
`project_id`) so multiple `EventLogWriter` instances in the same
process — for example, two concurrent `guard.runGuarded` sessions for
the same project — share allocation of `seq` and `logical_clock`.

Cross-process safety (file locking) is a v0.2+ concern that lands with
the MCP proxy. For now, run one writer process per project at a time.

## Vocabulary note

The architecture memo refers to this subsystem as the **Ephemeris** —
"a table of positions over time; the Lodestar event log records the
position of the agent's epistemic state over time." That naming is
documented in
[`docs/architecture/v02-delta.md`](https://github.com/qmilab/lodestar/blob/main/docs/architecture/v02-delta.md).
The package name on npm stays `@qmilab/lodestar-event-log`.

## License

[Apache 2.0](./LICENSE).

---
_Source: https://npm.io/package/@qmilab/lodestar-event-log · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._