Narada

A generalized, deterministic kernel for turning remote source deltas into locally materialized state and durable side-effect intents.

How to read this repo: Start with the kernel lawbook, then treat the Microsoft Graph/Exchange mailbox integration as the first vertical built on that kernel—not the essence of the system. Timer, webhook, filesystem, and process automations are first-class peers.

For a compact system diagram, see docs/system.md.

What this is

Narada is not a sync client, cache, or email tool. It is a deterministic state compiler from remote deltas into local canonical state, with a durable control plane for governed side-effects.

Narada instantiates Intelligence-Authority Separation: AI charter runners may contribute judgment, but they do not own truth, lifecycle, permission, effects, or confirmation. Intelligence supplies candidate meaning; Narada's control plane determines what counts, what may change, what may be done, and how consequence is confirmed.

The end-to-end boundary sequence is:

observe → normalize → fact → context → work → evaluation → decision → intent → execution → reconciliation → observation

Each boundary prevents a different collapse:

Boundary	Prevented collapse
observation → fact	world state becoming prompt memory
fact → context	unbounded reality becoming arbitrary model context
context → work	attention becoming informal task selection
work → evaluation	inference becoming mutation
evaluation → decision	model judgment becoming permission
decision → intent	approval becoming direct effect
intent → execution	execution inventing reasons
execution → reconciliation	API success becoming assumed truth
reconciliation → observation	hidden state becoming uninspectable consequence

• Generalized kernel — The core pipeline is vertical-agnostic.
• Mailbox as one vertical — The Exchange/Graph integration is the first Source implementation and the first set of charter policies. It is not privileged in the kernel.
• Peer verticals — TimerSource, WebhookSource, FilesystemSource, and process.run execute through the exact same control plane.

The Ops-Repo Model

Narada is designed around ops repos — private repositories that contain one or more operations, plus their knowledge, scenarios, and local configuration.

narada init-repo ~/src/my-ops
cd ~/src/my-ops
pnpm install

An ops repo is where you:

• Declare operations (want-mailbox, want-workflow) — tell Narada what you want to run
• Apply safety postures (want-posture) — set boundaries on what an operation can do
• Scaffold runtime directories (setup) — create the data and log paths each operation needs
• Verify readiness (preflight) — check credentials, connectivity, and policy before going live
• Understand behavior (explain) — see what an operation will do and why it might be blocked
• Activate (activate) — mark an operation as ready for the daemon to process
• Run (pnpm daemon) — start the control plane that compiles deltas and executes governed side-effects

Operations live in config/config.json. Logs, state, and backups live under the repo. The repo is yours — version it, branch it, share it within your team.

Installation

CLI (Recommended)

npm install -g @narada2/cli
# or
pnpm add -g @narada2/cli

The single narada CLI surfaces every command: runtime, backup, operation shaping, and repo bootstrapping.

Daemon

npm install -g @narada2/daemon
# or
pnpm add -g @narada2/daemon

The daemon is typically started from inside an ops repo via pnpm daemon.

Library

npm install @narada2/control-plane
# or
pnpm add @narada2/control-plane

First-Run Paths

Narada offers three entry paths, ordered from safest to live:

Path	Command	What it gives you
Show me	narada demo	Zero-setup taste with synthetic data. No credentials, no config, no files created.
Try safely	narada init-repo --demo ~/src/my-tryout	A non-live trial repo with a mock-backed operation. Explore the full shaping workflow without touching any external system.
Go live	narada init-repo ~/src/my-ops	A real ops repo. Declare a mailbox, add credentials, preflight, activate, and run.
Site bootstrap	narada sites init <id> --substrate <name>	Create a runtime Site on your local machine (Windows, macOS, or Linux). Composes with operation bootstrap.

See QUICKSTART.md for the full gold-path guide.

Choose Your Route

Narada can be consumed as runnable software, reference doctrine, or an agent reconstruction specification.

Reader	Route	Start Here
Runnable evaluator	You can install packages and run local commands.	narada demo, then narada init-repo --demo ~/src/my-tryout.
Live operator	You can provide credentials and run an operation.	narada init-repo ~/src/my-ops, then docs/product/bootstrap-contract.md.
Architect / doctrine reader	You cannot or do not want to run code yet.	docs/concepts/system.md, SEMANTICS.md, packages/layers/control-plane/docs/00-kernel.md.
Corporate or perimeter-blocked reader	You cannot install packages, access npm/GitHub freely, use Graph credentials, or execute arbitrary code.	Read the doctrine path and use docs/product/agent-reconstruction-specification.md.
Agent-assisted builder	You want an internal agent to rebuild a Narada-compatible local kernel inside your own environment.	Give the agent the prompt in docs/product/agent-reconstruction-specification.md.

If you cannot run this repo, do not treat package names or file layout as the essence of Narada. Preserve the invariants: governed crossings, zone authority, intelligence-authority separation, explicit admission, durable evidence, intent before execution, confirmation after execution, projections not authority, capability/secret separation, and Site factorization.

CLI Commands

Operation Shaping (ops-kit)

These commands shape what the daemon will do when it runs. They are safe to run at any time — they change configuration, not live state.

Command	Description
init-repo <path>	Bootstrap a private ops repo
init-repo --demo <path>	Bootstrap a non-live trial repo
want-mailbox <id>	Declare a mailbox operation
want-workflow <id>	Declare a timer workflow operation
want-posture <target> <preset>	Apply a safety posture to an operation (observe-only, draft-only, review-required, autonomous)
setup [target]	Scaffold directories for configured operations
preflight <operation>	Verify operation readiness (credentials, connectivity, policy)
inspect <operation>	Show operation configuration
explain <operation>	Explain what an operation will do and why it may be blocked
activate <operation>	Mark an operation as live for daemon processing

Site Management

Command	Description
sites init <id> --substrate <name>	Initialize a new Site (windows-native, windows-wsl, macos, linux-user, linux-system)
sites enable <id>	Generate supervisor configuration for a Site
sites list	List discovered Sites with health status
sites show <id>	Show Site metadata and last-known health
sites discover	Scan filesystem and refresh registry
sites remove <id>	Remove a Site from the registry (does NOT delete files)
cycle --site <id>	Run a single Cycle for a Site
status --site <id>	Show health and last trace for a Site
doctor --site <id>	Diagnose a Site by ID

Runtime & Data

These commands operate on live state and data.

Command	Description
sync	Run a single synchronization cycle
status	Show sync status and health
integrity	Check data integrity
rebuild-views	Rebuild all derived views
init	Create a new configuration file
cleanup	Run data lifecycle cleanup operations
demo	Zero-setup taste with synthetic data

Backup & Restore

Command	Description
backup -o <path>	Create a backup of sync data
restore -i <path>	Restore data from backup
backup-verify -i <path>	Verify backup integrity without extracting
backup-ls -i <path>	List backup contents

Global Options

These options are available on every command:

-f, --format <format>       Output format: json, human, or auto (default: auto)
--log-level <level>         Log level: debug, info, warn, error (default: info)
--log-format <format>       Log format: pretty, json, or auto (default: auto)
--metrics-output <file>     Write metrics to file on exit

Most runtime and data commands also accept:

-c, --config <path>         Config file path (default: ./config.json)
-v, --verbose               Enable verbose output

The init command uses -o, --output <path> instead of -c, --config. The demo command does not accept -c, --config.

Architecture

The system is organized in five layers above six deterministic compiler layers:

1. Inbound Compiler — packages/layers/control-plane compiles remote source deltas into locally materialized state. It knows nothing of agents, charters, or control decisions.
2. Control Plane — Manages first-class work objects (work_item, execution_attempt, intent) above the compiler. The daemon schedules work; the foreman decides it.
3. Charter Runtime — Vertical-specific policy definitions (packages/domains/charters) that guide bounded agent evaluation inside frozen capability envelopes.
4. Tool Runner — Executes validated tool calls with timeout enforcement and durable tool_call_records logging.
5. Effect Workers — Durable execution pipelines for each vertical: outbound worker for mail mutations, ProcessExecutor for subprocesses, and future workers for API automations.

Verification Ladder

After making changes, verify using the appropriate level:

Command	What it does	When to use
pnpm verify	Typecheck + build + fast packages (~15 sec)	Default — reliable baseline without heavy suites
pnpm test:focused "<cmd>"	Run one specific test file with telemetry	When you know exactly which file to test
pnpm test:unit	Unit tests across all packages	When you want tests without integration overhead
pnpm test:integration	Integration tests only	When you changed durable-state or I/O logic
pnpm test:control-plane	Control-plane tests only (~60+ sec)	When you changed control-plane internals
pnpm test:daemon	Daemon tests only (~90 sec)	When you changed daemon or integration surface
ALLOW_FULL_TESTS=1 pnpm test:full	Full recursive suite (~2 min)	Explicit full verification (CI, release prep)

Root pnpm test is disabled to prevent accidental full-suite runs. Use pnpm verify for the fast default, or pnpm test:focused for targeted single-file verification. Multi-file or package-level focused runs require explicit overrides.

Documentation

• 00-kernel.md — The canonical, vertical-agnostic kernel lawbook
• 02-architecture.md — Component layers and data flow
• QUICKSTART.md — Gold-path first-run guide
• SEMANTICS.md — Canonical ontology and vocabulary (single source of truth for all terms)
• TERMINOLOGY.md — User-facing words for talking about Narada
• AGENTS.md — Navigation hub for contributors and agents
• RELEASE.md — Local and CI publishing flow for @narada2/* packages
• .ai/do-not-open/tasks/ — Design tasks and specifications

Review Checklist for Future Architecture Changes

When proposing changes that touch public types, docs, or package surfaces, verify:

• Kernel-first framing: Docs and comments describe the generalized behavior first, vertical specifics second.
• No mailbox-default types: Generic interfaces use scope_id / context_id, not mailbox_id / conversation_id.
• Vertical parity: New features for one vertical have a plausible path for peers (timer, webhook, filesystem, process).
• Authority boundaries preserved: No new write paths bypass ForemanFacade, Scheduler, IntentHandoff, or OutboundHandoff.
• Observation remains read-only: No UI-facing code mutates durable state directly.
• Control-plane lint passes: pnpm control-plane-lint reports zero violations.

License

MIT