@noorm/broccolidb 2.0.1

package/docs/OPERATIONS.md

@@ -0,0 +1,176 @@
+# Operations guide
+
+BroccoliDB is embedded in the host process. There is no daemon to start, but
+there is still an explicit lifecycle and a durable state directory to operate.
+
+## Lifecycle
+
+```ts
+const db = new BroccoliDatabaseKernel({
+  workspaceRoot: "/var/lib/my-app/state",
+  walDebounceMs: 20,
+})
+
+await db.start()
+try {
+  // register tables, read state, and perform mutations
+  await db.transaction(async () => {
+    // related writes share one process-local lock
+  })
+  await db.flush()
+} finally {
+  await db.stop()
+}
+```
+
+Rules:
+
+1. Start once before reading or writing.
+2. Keep one kernel owner per workspace root in a process.
+3. Use `transaction()` for related async mutations.
+4. Use `flush()` before reporting a durable handoff to another component.
+5. Use `checkpoint()` before long imports, migrations performed by the host, or
+   risky workflows.
+6. Always call `stop()` during normal shutdown.
+
+`start()` and `stop()` are idempotent at the service level. A process crash can
+still occur between an in-memory mutation and its asynchronous WAL append;
+choose an explicit flush or transaction boundary when that window matters.
+
+## Workspace selection
+
+`workspaceRoot` defaults to `process.cwd()`. For applications with multiple
+projects, use an explicit absolute or application-resolved path so state does
+not accidentally follow the launch directory.
+
+```ts
+const db = new BroccoliDatabaseKernel({
+  workspaceRoot: path.join(appDataDir, "broccolidb"),
+})
+```
+
+Do not point two independent processes at the same workspace unless the host
+provides an external single-writer or lease protocol. The built-in mutex only
+coordinates async work inside one Node.js process.
+
+## On-disk layout
+
+| Path | Purpose | Safe to edit manually? |
+|---|---|---|
+| `.broccolidb/wal.log` | Pending and historical mutation frames | No |
+| `.broccolidb/wal.log.old` | Previous WAL after checkpoint rotation | No |
+| `.broccolidb/checkpoint.db` | Latest base table snapshot | No |
+| `.broccolidb/checkpoints/<id>.json` | Named checkpoint history | No |
+| `.broccolidb/cas/blobs/<shard>/<hash>` | CAS payloads | No |
+| `.broccolidb/cas/corrupt/` | Quarantined payloads and manifest | Preserve for investigation |
+
+The directory is application state and should be included in the host's backup
+policy. It is ignored by the package repository's `.gitignore` because it is
+runtime data, not source.
+
+## Backup and restore
+
+### Consistent backup
+
+1. Stop the owning application, or quiesce all writes.
+2. Await `db.flush()` and preferably `db.checkpoint("backup-<label>")`.
+3. Copy the complete `.broccolidb/` directory to the backup target.
+4. Record the package version and Node.js version with the backup.
+5. Restart the application.
+
+Copying only `checkpoint.db` omits checkpoint history, WAL state, and CAS blobs.
+Copying only the CAS directory omits table records and references.
+
+### Restore
+
+1. Stop the application.
+2. Preserve the current state directory for forensic comparison.
+3. Restore the complete backup directory into the configured workspace root.
+4. Start the same or a compatible package version.
+5. Run `health()` and verify representative table and blob reads.
+
+Do not delete an invalid WAL before preserving it. A checksum failure is useful
+evidence about an interrupted write, manual mutation, or storage problem.
+
+## Checkpoints and rollback
+
+Use checkpoints as application-level restore points:
+
+```ts
+const beforeUpgrade = await db.checkpoint("before-upgrade")
+
+try {
+  await runHostUpgrade(db)
+} catch (error) {
+  const restored = await db.rollback(beforeUpgrade.checkpointId)
+  if (!restored) throw new Error("Upgrade failed and rollback was unavailable", { cause: error })
+}
+```
+
+`listCheckpoints()` reports records loaded or created in the current process.
+After a restart, history files are available to `rollback(id)` when the ID is
+known. Keep checkpoint IDs with the host's operation record if they are needed
+for later recovery.
+
+## Health and observability
+
+```ts
+const report = await db.health()
+
+if (report.status !== "HEALTHY") {
+  console.warn(report.actionableRecommendations)
+}
+```
+
+The report covers:
+
+- state-directory writability and estimated CAS disk usage;
+- CAS blob counts, quarantine counts, and reported compression savings;
+- WAL frame totals, buffered frame count, and last sync time;
+- table count, record count, and current index-parity status.
+
+The report is a fast operational probe. It does not replace a backup restore
+test, a full application invariant check, or cross-process coordination.
+
+## WAL maintenance
+
+The default WAL debounce is 20 ms. Increase it only when the host accepts a
+larger durability window; decrease it when write visibility matters more than
+batching. `checkpoint()` flushes before rotation and leaves a new checkpoint
+marker in the WAL.
+
+If WAL growth is persistent:
+
+1. Confirm the process is calling `flush()` or `stop()`.
+2. Inspect `health().pillars.walJournal`.
+3. Create a checkpoint after quiescing writes.
+4. Preserve `wal.log` and `wal.log.old` before manual intervention.
+
+## CAS maintenance
+
+Store a blob by retaining its returned hash in a record, conventionally as a
+string such as `CAS:<hash>`:
+
+```ts
+const hash = await db.storeBlob(Buffer.from(payload))
+table.put("document-1", { id: "document-1", blob: `CAS:${hash}` })
+const bytes = await db.readBlob(hash)
+```
+
+`gc()` scans current table values for `CAS:` references and removes all other
+blob files. Only call it when all durable references are represented in the
+currently loaded tables. External manifests, pending imports, and backups are
+not discovered automatically.
+
+When CAS verification fails, the payload is moved under `cas/corrupt/` and an
+entry is appended to `manifest.jsonl`. Preserve the quarantine directory before
+attempting a restore.
+
+## Security and data handling
+
+- Choose a state directory with permissions appropriate for the records stored.
+- Do not put secrets in natural-language queries, error messages, or checkpoint
+  labels; labels are persisted in checkpoint history.
+- Treat WAL, checkpoint, CAS, and quarantine files as sensitive application data.
+- Validate record content before persistence; BroccoliDB does not encrypt files.
+- Use an external lock/lease when more than one process can write the same root.

package/docs/PHILOSOPHY.md

@@ -0,0 +1,91 @@
+# Design philosophy
+
+BroccoliDB is intentionally smaller than a general-purpose database. Its design
+optimizes for an embeddable application boundary where the owner can see the
+tables, choose the workspace path, decide when to flush, and recover from
+ordinary files.
+
+## Principles
+
+### 1. Memory is the hot path; durability is explicit
+
+Table reads and indexes stay in memory. The WAL, checkpoint, and CAS layers are
+explicit durability mechanisms rather than hidden database behavior. Callers
+should know which boundary they have crossed:
+
+| Boundary | Meaning |
+|---|---|
+| `put()`/`delete()` returned | The in-memory table changed; the WAL append was scheduled |
+| `await db.flush()` | Buffered WAL frames were written |
+| `await db.transaction(fn)` returned | The callback completed and the kernel flushed its WAL buffer |
+| `await db.checkpoint()` returned | A base snapshot and checkpoint history were written and the WAL was rotated |
+| `await db.stop()` returned | Kernel subsystems were flushed and stopped |
+
+### 2. Files should be boring
+
+The durable format uses JSON, JSONL, SHA-256, temporary files, and rename. This
+makes state inspectable and transferable without a native reader. The trade-off
+is that applications should not expect SQL joins, page-level indexes, or a
+server-grade transaction log.
+
+### 3. Integrity belongs at the boundary
+
+WAL frames carry checksums and previous-frame metadata. CAS payloads are verified
+against their requested SHA-256 address on read. Checkpoint snapshots include a
+hash. Corrupt data should fail visibly or be quarantined; it should not silently
+be treated as valid state.
+
+### 4. Contracts are more stable than implementation details
+
+Consumers program against `IDbTable`, `IBroccoliDatabaseKernel`, query types,
+aggregate types, and change events. Internal index maps and file helpers may
+change, but public signatures and documented lifecycle semantics require review.
+
+### 5. Portability beats incidental compatibility
+
+BroccoliDB does not preserve the removed SQLite package's SQL or driver API. The
+supported path is the standalone `@noorm/broccolidb` package. Adapters should
+translate application queries into the typed table/query contracts instead of
+reintroducing a private compatibility layer.
+
+### 6. Operational behavior must be legible
+
+Health reports, checkpoint records, WAL metrics, CAS stats, and explicit error
+types are preferable to opaque magic. The health report is a diagnostic probe,
+not a substitute for an application-specific audit or backup test.
+
+## Rejected alternatives
+
+### Native SQLite binding as the package core
+
+Rejected for this package because it adds native installation and ABI concerns.
+Applications that need SQL should choose a dedicated SQL database; BroccoliDB is
+the portable table substrate.
+
+### A remote database service
+
+Rejected because the package is designed for local, offline, process-owned state
+and should not introduce networking, credentials, or service discovery.
+
+### Implicit persistence on every mutation
+
+Rejected because it couples latency and correctness decisions to an invisible
+policy. Micro-batching plus explicit `flush()`, `transaction()`, and
+`checkpoint()` calls make the boundary visible to the caller.
+
+### Treating token estimates as billing truth
+
+Rejected in `TokenCompressionService`. The four-characters-per-token estimate is
+a fast budget signal; provider usage accounting remains the provider's concern.
+
+## Boundaries
+
+- The async mutex is process-local and re-entrant through async context.
+- The kernel does not coordinate independent Node processes writing the same
+  workspace.
+- WAL replay validates frame checksums and reconstructs table mutations; it is
+  not a general migration engine.
+- CAS garbage collection is only safe when the referenced-hash set accurately
+  reflects application records.
+- Health probes report the implementation's current checks; they are not a
+  full filesystem scrub or cross-process consistency protocol.

package/docs/README.md

@@ -0,0 +1,116 @@
+# BroccoliDB documentation
+
+This is the documentation map for the standalone `@noorm/broccolidb` package.
+The package docs follow a layered structure used by mature storage systems:
+
+**Concepts → How it works → Reference → Operations → Decisions**
+
+The implementation and tests are authoritative when documentation disagrees.
+This map explains where a claim belongs and gives each reader a shortest useful
+path through the package.
+
+## Reading paths by role
+
+| Role | Start here | Then read |
+|---|---|---|
+| **Application developer** | [Quick start](../README.md#quick-start) | [API reference](API.md) · [Operations](OPERATIONS.md) |
+| **Architect / reviewer** | [Brief](BRIEF.md) | [Architecture](ARCHITECTURE.md) · [Philosophy](PHILOSOPHY.md) · [ADR-001](adr/ADR-001-portable-inmemory-kernel.md) |
+| **Operator / support** | [Operations](OPERATIONS.md) | [Troubleshooting](TROUBLESHOOTING.md) · [Glossary](GLOSSARY.md) |
+| **Contributor** | [Contributing](CONTRIBUTING.md) | [Architecture](ARCHITECTURE.md) · [API reference](API.md) · [ADR process](adr/README.md) |
+| **Auditor / security reviewer** | [Boundaries](PHILOSOPHY.md#boundaries) | [Operations](OPERATIONS.md#integrity-and-recovery) · [Architecture](ARCHITECTURE.md#failure-model) |
+| **Release owner** | [Release notes](RELEASE_NOTES.md) | [Contributing](CONTRIBUTING.md#release-checklist) · [ADR index](adr/README.md) |
+
+## Document catalog
+
+### Concepts — why
+
+| Document | Purpose |
+|---|---|
+| [Brief](BRIEF.md) | One-page problem statement, solution, guarantees, and non-goals |
+| [Philosophy](PHILOSOPHY.md) | Design principles, explicit trade-offs, and rejected alternatives |
+| [Glossary](GLOSSARY.md) | Canonical terms for tables, WAL, CAS, checkpoints, and recovery |
+
+### How it works — what happens
+
+| Document | Purpose |
+|---|---|
+| [Architecture](ARCHITECTURE.md) | Runtime layers, mutation flow, startup, checkpointing, rollback, and failure model |
+| [Operations](OPERATIONS.md) | Filesystem layout, lifecycle rules, backup/restore, integrity, and garbage collection |
+
+### Reference — what to call
+
+| Document | Purpose |
+|---|---|
+| [API reference](API.md) | Public exports, kernel/table methods, query operators, indexes, aggregation, and events |
+| [Package README](../README.md) | Install, minimal example, portability statement, and command index |
+| [Source entry point](../src/index.ts) | Export surface — the source of truth for package imports |
+| [Contracts](../src/broccolidb.contracts.ts) | Type-level API and serialized record contracts |
+
+### Operations — how to run and debug
+
+| Document | Purpose |
+|---|---|
+| [Operations guide](OPERATIONS.md) | Start/stop, durability boundaries, backup, recovery, health, and CAS GC |
+| [Troubleshooting](TROUBLESHOOTING.md) | Symptom → likely cause → action runbooks |
+| [Release notes](RELEASE_NOTES.md) | Supported release history and compatibility policy |
+
+### Decisions — why the shape is stable
+
+| Document | Purpose |
+|---|---|
+| [ADR index](adr/README.md) | Decision inventory and writing rules |
+| [ADR-001](adr/ADR-001-portable-inmemory-kernel.md) | Why BroccoliDB is a portable in-memory kernel with explicit file durability |
+
+## Documentation conventions
+
+1. **Describe the current package.** Do not document the removed in-repository
+   SQLite implementation or imply that it remains supported.
+2. **Use contract language.** Distinguish what is guaranteed after an in-memory
+   mutation, after `flush()`, after `checkpoint()`, and after `stop()`.
+3. **Name the source of truth.** Public exports live in `src/index.ts`; type
+   contracts live in `src/broccolidb.contracts.ts`; behavior is verified by
+   `test/`.
+4. **Keep examples executable.** Examples should use the public package import,
+   explicit lifecycle calls, and a temporary or application-owned workspace.
+5. **Document failure boundaries.** Say what is process-local, what is on disk,
+   what is recoverable, and what requires an external coordination system.
+6. **Prefer stable vocabulary.** Say table, record, WAL frame, checkpoint, CAS
+   blob, replay, rollback, flush, and health report consistently.
+7. **Update docs with contracts.** Export changes, file-format changes, and
+   durability changes require API/operations updates plus an ADR or release note.
+
+## Source-of-truth matrix
+
+| Question | Source of truth |
+|---|---|
+| What can consumers import? | `src/index.ts` and generated `dist/index.d.ts` |
+| What does a method accept/return? | `src/broccolidb.contracts.ts` and class signatures |
+| How does a write reach disk? | `src/broccolidb-kernel.ts` and `src/broccolidb-wal.ts` |
+| How are blobs addressed and verified? | `src/broccolidb-cas.ts` |
+| What behavior is protected? | `test/*.test.ts` |
+| Is the package publishable? | `package.json`, `npm pack --dry-run`, and `npm run docs:check` |
+
+## Status
+
+| Metric | Current value |
+|---|---|
+| Package | `@noorm/broccolidb@2.0.1` |
+| API status | Standalone supported package; modern ESM surface |
+| Runtime dependencies | 0 |
+| Node.js | `>=18` |
+| Public entry point | `src/index.ts` / `dist/index.js` |
+| Persistence | In-memory tables + optional filesystem WAL/checkpoints/CAS |
+| License | MIT |
+
+## Quick links
+
+```bash
+# Build and test the implementation
+npm test
+
+# Validate docs and relative Markdown links
+npm run docs:check
+
+# Inspect the publishable artifact without creating it
+npm pack --dry-run
+```

package/docs/RELEASE_NOTES.md

@@ -0,0 +1,34 @@
+# Release notes
+
+## 2.0.1 — first npm publication
+
+This patch release publishes the standalone package under a new version because
+the previously unused `2.0.0` version had already been unpublished on npm and
+cannot be reused by the registry.
+
+The package contents and supported API are unchanged from the standalone
+release described below.
+
+## 2.0.0 — standalone portable package
+
+This release is the supported standalone BroccoliDB package.
+
+### Included
+
+- in-memory typed tables with equality, sorted, composite, and prefix indexes;
+- operator filters, boolean query clauses, fluent queries, aggregation, CDC,
+  TTL expiration, and deterministic natural-language parsing;
+- checksum-linked micro-batched WAL and restart replay;
+- atomic JSON checkpoints, named history, and rollback;
+- SHA-256 CAS storage with optional Brotli compression and corruption quarantine;
+- re-entrant async mutex and kernel transaction boundary;
+- dependency-free runtime package for Node.js `>=18`.
+
+### Compatibility policy
+
+The standalone package is the supported implementation. The removed SQLite
+implementation is not a supported compatibility target, and this package does
+not promise SQL, Kysely, or `better-sqlite3` API compatibility.
+
+Changes to exported contracts or durable file formats require a release-note
+entry and an architecture decision record.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,145 @@
+# Troubleshooting
+
+Use the symptom → likely cause → action flow below. Preserve `.broccolidb/`
+before destructive recovery work.
+
+## Startup and recovery
+
+### `start()` throws `WalIntegrityError`
+
+**Likely causes:** a truncated JSONL write, hand-edited WAL, filesystem
+corruption, or a package/version mismatch that changed frame serialization.
+
+**Action:** stop all writers, copy the entire `.broccolidb/` directory, inspect
+the failing line and checksum message, and restore the last known-good backup if
+the WAL cannot be repaired. Do not delete the WAL as a first response.
+
+### Data is missing after a process crash
+
+**Likely cause:** a mutation changed memory but its asynchronous WAL append had
+not been flushed before termination.
+
+**Action:** use `transaction()`, `flush()`, or `checkpoint()` at the host's
+durability boundary. BroccoliDB cannot recover a frame that never reached the
+WAL.
+
+### Startup is slow
+
+**Likely causes:** a large WAL tail, a large checkpoint, or too many records
+being rebuilt into indexes.
+
+**Action:** measure startup with the same workload, inspect WAL metrics, quiesce
+writes, and create a checkpoint. Keep tables bounded or partition application
+state when a single in-memory table becomes too large.
+
+## Tables and queries
+
+### A query is correct but slower than expected
+
+**Likely cause:** no matching index exists or the predicate cannot use the
+available index shape.
+
+**Action:** call `select().where(...).explain()`, inspect `scanStrategy`, and add
+an equality, sorted, composite, or prefix index that matches the hot predicate.
+Do not assume an index changes semantics; it changes candidate selection.
+
+### An index appears stale
+
+**Likely causes:** records were restored with a custom snapshot, a host kept a
+second table reference, or application code mutated an object after passing it
+to the table.
+
+**Action:** treat records as immutable application values, use table mutation
+methods, and rebuild the table/indexes through a controlled restore if needed.
+
+### TTL behavior is surprising
+
+**Likely cause:** TTL timers are process-local and depend on the process staying
+alive; an expired record is not a durable scheduler job.
+
+**Action:** use TTL for local cache-like expiration. For business deadlines,
+persist an explicit expiration field and run a host-owned reconciliation pass.
+
+## Checkpoints and rollback
+
+### `rollback(id)` returns `false`
+
+**Likely causes:** the ID is unknown, history was not copied with the backup, or
+the checkpoint file is unreadable.
+
+**Action:** call `listCheckpoints()`, verify
+`.broccolidb/checkpoints/<id>.json`, and restore the complete state directory if
+the file is missing.
+
+### Rollback did not remove a table created later
+
+**Likely cause:** rollback rebuilds tables represented by the checkpoint; it is
+not a schema registry that automatically deletes every table absent from a
+historical snapshot.
+
+**Action:** explicitly clear or recreate application tables as part of the
+rollback procedure, then checkpoint the resulting state.
+
+## CAS
+
+### `readBlob(hash)` returns `null`
+
+**Likely cause:** the hash is absent from the configured workspace or the host
+opened a different `workspaceRoot`.
+
+**Action:** log the resolved root, compare `cas.getBaseDir()`, and restore the
+CAS directory from the matching backup.
+
+### `StorageIntegrityError` is raised
+
+**Likely cause:** a payload failed Brotli decompression or SHA-256 verification.
+
+**Action:** preserve `cas/corrupt/manifest.jsonl`, inspect the quarantined blob,
+and restore a known-good backup. Do not overwrite the quarantine entry before
+capturing it.
+
+### `gc()` deleted data needed by the application
+
+**Likely cause:** the reference was not stored in a currently loaded table as a
+`CAS:<hash>` string.
+
+**Action:** restore from backup and make references explicit before rerunning GC.
+`gc()` is conservative only with respect to the references it can see.
+
+## Locking and concurrency
+
+### `DeadlockTimeoutError`
+
+**Likely causes:** a callback awaited a long-running operation while holding the
+lock, nested operations are waiting on another resource, or two application
+components use locks in inconsistent order.
+
+**Action:** keep transaction callbacks short, avoid external network calls while
+holding the kernel lock, and review lock ordering. The mutex is re-entrant for
+the same async context, but it is not a general deadlock solver.
+
+### Two processes see divergent state
+
+**Likely cause:** both processes wrote the same `.broccolidb/` directory. The
+package does not provide cross-process fencing.
+
+**Action:** assign one writer, put an external lease around the workspace, or
+choose a database designed for multi-process coordination.
+
+## Packaging and imports
+
+### `ERR_MODULE_NOT_FOUND` for internal imports
+
+**Likely cause:** the package was copied without building `dist/`, or a consumer
+is bypassing the package export and importing source files incorrectly.
+
+**Action:** run `npm run build`, import from `@noorm/broccolidb`, and inspect the
+`files` list with `npm pack --dry-run`.
+
+### A native SQLite package appears in the dependency tree
+
+**Likely cause:** the host application installed an unrelated database package
+or a stale lockfile was copied into the package.
+
+**Action:** run `npm ls --omit=dev --depth=0`, inspect the host's dependency
+graph, and keep BroccoliDB's runtime `dependencies` object empty.

package/docs/adr/ADR-001-portable-inmemory-kernel.md

@@ -0,0 +1,74 @@
+# ADR-001: Portable in-memory kernel with explicit filesystem durability
+
+- **Status:** Accepted
+- **Date:** 2026-09-20
+- **Owners:** BroccoliDB maintainers
+- **Scope:** package architecture, runtime dependencies, and persistence boundary
+
+## Context
+
+BroccoliDB is embedded in applications that need fast local tables, indexes, and
+recoverable state. The previous SQLite-oriented implementation introduced a
+native database dependency and a portability burden for consumers that only
+needed table operations and local durability.
+
+The standalone package must work across supported Node.js environments without a
+native compiler, Electron ABI rebuild, database server, or SQL-specific adapter.
+
+## Decision
+
+Use an in-memory table kernel as the supported implementation and compose
+durability from ordinary filesystem primitives:
+
+- typed `Map`-backed tables and secondary indexes for the hot path;
+- a micro-batched JSONL WAL with checksum metadata for mutation replay;
+- atomic JSON checkpoints and named checkpoint history for restore points;
+- SHA-256 content-addressable files with optional Brotli compression for blobs;
+- a process-local re-entrant async mutex for kernel transactions;
+- zero production dependencies and an ESM Node.js `>=18` package surface.
+
+The public contract is the package export from `src/index.ts` and the interfaces
+in `src/broccolidb.contracts.ts`. The removed SQLite implementation is not a
+compatibility target.
+
+## Alternatives considered
+
+### Keep `better-sqlite3` in the package
+
+Rejected. It creates native installation/ABI coupling and makes a small embedded
+table substrate harder to transfer between environments.
+
+### Use Kysely over a database driver
+
+Rejected. A query builder does not remove the underlying driver and would force
+the package to preserve SQL/dialect semantics it does not need.
+
+### Use an external service
+
+Rejected. The package is intended for offline, process-owned local state and
+should not add networking, credentials, deployment, or service availability
+requirements.
+
+## Consequences
+
+### Positive
+
+- Consumers install and run without native database builds.
+- State is inspectable and transferable as ordinary files.
+- The hot path is simple and fast for bounded local tables.
+- Recovery behavior is explicit and testable.
+- The package can be vendored or published without LUMI-specific aliases.
+
+### Trade-offs
+
+- Tables must fit in process memory.
+- There is no SQL compatibility, migration engine, or relational join planner.
+- The built-in mutex does not coordinate independent processes.
+- Durability is explicit; an unflushed process crash can lose the latest buffer.
+- Applications own backup policy, schema evolution, and record validation.
+
+## Compatibility impact
+
+Changing the WAL frame shape, checkpoint structure, CAS encoding, export surface,
+or lifecycle semantics is a compatibility change. Such changes require tests,
+operations documentation, release notes, and a new or updated ADR.

package/docs/adr/README.md

@@ -0,0 +1,38 @@
+# Architecture decision records
+
+Architecture Decision Records (ADRs) capture decisions that affect the public
+API, durable formats, portability boundary, or recovery behavior. They are
+shorter than a whitepaper and more durable than a changelog entry.
+
+## Index
+
+| ID | Decision | Status |
+|---|---|---|
+| [ADR-001](ADR-001-portable-inmemory-kernel.md) | Use a portable in-memory table kernel with explicit filesystem durability | Accepted |
+
+## When to write an ADR
+
+Write or update an ADR when a change:
+
+- adds/removes a public export;
+- changes WAL, checkpoint, CAS, or recovery semantics;
+- changes the runtime dependency or native-module policy;
+- changes concurrency or cross-process assumptions;
+- introduces a new persistence format or compatibility decision.
+
+Do not use an ADR for a typo, a local refactor, or a test-only fixture change.
+
+## Lifecycle
+
+1. Create the next numbered file from [the template](TEMPLATE.md).
+2. State context, decision, alternatives, consequences, and compatibility impact.
+3. Link it from this index and the affected reference/operations documents.
+4. Mark it `Accepted`, `Superseded`, or `Rejected`; do not silently rewrite the
+   historical decision.
+
+## Status vocabulary
+
+- **Proposed** — under review and not yet a supported contract.
+- **Accepted** — current supported decision.
+- **Superseded** — replaced by a later ADR; retain for history.
+- **Rejected** — considered and declined; retain the reasoning.