# @qmilab/lodestar-core

> Schemas and types 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-core
pnpm add @qmilab/lodestar-core
yarn add @qmilab/lodestar-core
bun add @qmilab/lodestar-core
```

## 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 | 1 |
| Unpacked size | 692.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 3 |
| Author | QMI Lab |
| Maintainers | cybernandan |
| Keywords | ai-agents, trust, epistemic, audit, agent-governance, lodestar, schemas, types |

## Links

- npm: https://www.npmjs.com/package/@qmilab/lodestar-core
- 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-core

## Dependencies (1)

- [zod](https://npm.io/package/zod.md) ^3.23.8

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K 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
- 0.1.0 — 2026-05-25

## README

# @qmilab/lodestar-core

Schemas and types for the Lodestar epistemic chain. Part of
[Lodestar](https://qmilab.com/lodestar) — the trust layer for AI agents.

Every other Lodestar package depends on this one. If you're building
directly on Lodestar's primitives (claims, evidence, beliefs,
decisions, actions, outcomes, revisions, the event envelope), this is
the package you import from.

## Install

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

## Usage

Every schema and type is re-exported from the package root. Import
from `@qmilab/lodestar-core` directly — there are no subpath imports.

```ts
import { ClaimSchema, type Claim, registry } from "@qmilab/lodestar-core"

// Validate a candidate Claim against the schema. Zod's parse throws
// on invalid input; safeParse returns a Result. Lodestar uses safeParse
// at every package boundary.
const candidate: unknown = {
  id: crypto.randomUUID(),
  statement: "Current branch is 'main'",
  source_observation_ids: ["obs-1"],
  extraction_method: "tool",
  extracted_by: "agent-1",
  status: "extracted",
  scope: { level: "project", identifier: "my-project" },
  sensitivity: "internal",
  authors: ["agent-1"],
  created_at: new Date().toISOString(),
}

const parsed = ClaimSchema.safeParse(candidate)
if (!parsed.success) {
  throw new Error(`invalid claim: ${parsed.error.message}`)
}
const claim: Claim = parsed.data

// The observation-schema registry: register your tool's output schema
// once at module load, then the Action Kernel validates tool outputs
// against it before they enter cognition.
//
// registry.register("my.tool@1", MyOutputSchema)
```

## What's in here

- `Observation`, `Claim`, `EvidenceSet`, `Belief`, `Decision`,
  `Action`, `Outcome`, `Revision`, `Explanation` — the eight links of
  the epistemic chain plus the rationale type that binds them.
- `ContextPolicy`, `ActionContract`, `Sensitivity`, `ResourceScope`,
  and the four orthogonal belief lifecycle axes (truth, retrieval,
  security, freshness).
- `EventEnvelope` — the append-only NDJSON event-log envelope every
  Lodestar event is wrapped in.
- A schema registry (`registry`) for tool output schemas.

Each type has both a Zod schema (e.g. `ClaimSchema`) and a TypeScript
type alias derived via `z.infer` (e.g. `Claim`). The Zod schemas are
the source of truth; the types are derived.

## What's not in here

No runtime behaviour. This package is pure types + schemas. The
governance components live in their own packages:

- `@qmilab/lodestar-event-log` — append-only event log writer / reader
- `@qmilab/lodestar-action-kernel` — tool registry + two-phase action execution
- `@qmilab/lodestar-memory-firewall` — claim/belief lifecycle gates
- `@qmilab/lodestar-cognitive-core` — claim extraction + belief adoption
- `@qmilab/lodestar-guard` — the `wrap()` helper that ties it all
  together for an agent loop
- `@qmilab/lodestar-trace` — `lodestar report <session-id>` from the log

## License

[Apache 2.0](./LICENSE).

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