Layer 1 — Magpie, the substrate

In plain language

Magpie is the foundation everything runs on. It is not a product and it has no screens. It is the set of guarantees that stay the same across every multi-tenant, audit-first AI system: events, an append-only ledger, a tenant boundary, deterministic AI execution, exactly-once operations, a knowledge store with provenance, and a release process that is enforced by machinery rather than by memory.

It is shipped as 34 packages under one version number (currently the 0.7.x line, every package moving in lockstep), distributed from a private registry, and consumed by the layers above it exactly as an outside party would consume it.

What it owns

• the event spine, the append-only audit ledger and the tenant boundary;
• the AI runtime — prompt engine, model gateway, workflow kernel, evaluations, observability;
• the execution primitives — idempotency, jobs, scheduler, webhooks, reconciliation, blob storage, runtime control plane;
• the knowledge substrate — document records, extraction, chunking, embeddings, tenant-isolated vector storage, citation-ready retrieval, drift reconciliation;
• the transactional substrate — a cross-package atomic-write coordinator and a typed row store, with a forward-only migration runner;
• relationship memory — a governed record system for what a relationship has learned over time;
• release governance — mechanically enforced.

What it deliberately is not

It does not deploy anything, render any UI, or hold any per-consumer value (operator email, tenant identity, copy). Everything that varies between consumers lives in the consumer repository. Magpie is the answer to "what stays the same".

The seven groups

The packages are described here in seven groups. Each page states what the group owns, the guarantees it makes, and the design notes (ADRs) that shaped it.

1. Event spine and audit ledger
2. Tenancy, records and the transactional substrate
3. The AI runtime
4. Execution primitives
5. The knowledge substrate
6. Relationship memory
7. Release governance

Dependency direction, enforced

Consumer application
    │
    ▼
modules  +  runtime libraries        (module-inquiry, module-ai-workflow;
    │                                 prompt-engine, model-gateway, evals, observability)
    ▼
@magpie/core  (façade)
    │
    ├── core primitives              events, ledger, tenancy, observability, control-plane
    ├── execution primitives         idempotency, blob, jobs, webhooks, scheduler, reconciliation
    ├── knowledge primitives         knowledge, text-extraction, chunking, embeddings,
    │                                vector-store, retrieval, knowledge-reconciliation
    └── transactional primitives     unit-of-work, records, records-migrate

Imports flow downward only. Modules cannot import each other (cross-module communication is event-only, ADR-0007). Every package's AWS SDK adapters live in a /server subpath, isolated from the pure-logic public API, so the main entry of every package is AWS-free and testable without cloud credentials. Deep imports into a package's internals are forbidden; consumers use only the declared exports. All of this is enforced by lint in continuous integration.

By the numbers

• 34 packages, one coordinated version (0.7.x line).
• 30 architecture decision records (ADR-0007 … ADR-0039), each with a status, a decider and a date.
• 181 unit-test files, roughly three thousand test cases, all framework-pure (no Lambda handler, no Amplify, no app-shell coupling).

Sources

• magpie/README.md — package inventory, boundary rules, wave history.
• magpie/docs/architecture-constitution.md — substrate invariants.
• magpie/docs/adr/ — ADR-0007 … ADR-0039.
• magpie/tests/unit/ — the test suite.