Skip to content

README.md

Latest commit

 

History

History
137 lines (108 loc) · 7.11 KB

README.md

File metadata and controls

137 lines (108 loc) · 7.11 KB
Raw

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 API reference · Operations
Architect / reviewer Brief Architecture · Philosophy · ADR-001
Operator / support Operations Troubleshooting · Glossary
Contributor / coding agent Contributing Agent guide · Architecture · API reference · ADR process
Auditor / security reviewer Boundaries Operations · Architecture · Claim register
Release owner Release notes Contributing · ADR index
IP / license reviewer Legal strategy IP record · Claim register · Defensive policy · Trademark policy

Document catalog

Concepts — why

Document Purpose
Brief One-page problem statement, solution, guarantees, and non-goals
Philosophy Design principles, explicit trade-offs, and rejected alternatives
Glossary Canonical terms for tables, WAL, CAS, checkpoints, and recovery

How it works — what happens

Document Purpose
Architecture Runtime layers, mutation flow, startup, checkpointing, rollback, and failure model
Operations Filesystem layout, lifecycle rules, backup/restore, integrity, and garbage collection

Reference — what to call

Document Purpose
API reference Public exports, typed tables, JSONSQL, query operators, indexes, aggregation, and events
Package README Install, minimal example, portability statement, and command index
Source entry point Export surface — the source of truth for package imports
Contracts Type-level API and serialized record contracts

Operations — how to run and debug

Document Purpose
Operations guide Start/stop, durability boundaries, backup, recovery, health, and CAS GC
Troubleshooting Symptom → likely cause → action runbooks
Release notes Supported release history and compatibility policy

Licensing and provenance

Document Purpose
Legal strategy License transition, threat model, enforcement boundaries, and counsel-required decisions
IP record Evidence discipline, invention disclosure, and defensive prior-art index
Claim register Bounded engineering claims, evidence status, limitations, and release packet
Defensive policy Apache patent posture, provenance preservation, and response playbook
Trademark policy Project-name and fork-branding guidance

Decisions — why the shape is stable

Document Purpose
ADR index Decision inventory and writing rules
ADR-001 Why BroccoliDB is a portable in-memory kernel with explicit file durability
ADR-002 Why future releases use Apache-2.0 with defensive IP and provenance controls
ADR-003 Why public claims are bounded by source evidence, tests, and legal-review gates
ADR-004 Why recovery fails closed and integrity-sensitive paths are constrained
ADR-005 Why BroccoliDB provides a bounded SQL-shaped subset over JSON tables
ADR-006 Why WAL compaction is separate from named rollback checkpoints

Documentation conventions

  1. Describe the current package. Distinguish the bounded JSONSQL subset from the removed SQLite implementation and from full SQLite/PostgreSQL compatibility.
  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/[email protected]
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
Query surfaces Typed table API + bounded embedded JSONSQL subset
License Apache-2.0 for 3.0.0+; MIT for historical 2.0.x

Quick links

# Build and test the implementation
npm test

# Validate docs and relative Markdown links
npm run docs:check

# Audit Apache metadata and evidence-bounded claims
npm run license:check
npm run ip:check

# Inspect the publishable artifact without creating it
npm pack --dry-run