If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/attic-labs/noms shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 5y ago

• 6 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 5y ago
• ⚠ Single-maintainer risk — top contributor 91% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live attic-labs/noms repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/attic-labs/noms.

What it runs against: a local clone of attic-labs/noms — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in attic-labs/noms | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1744 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of attic-labs/noms. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/attic-labs/noms.git
#   cd noms
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of attic-labs/noms and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "attic-labs/noms(\\.git)?\\b" \\
  && ok "origin remote is attic-labs/noms" \\
  || miss "origin remote is not attic-labs/noms (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "go/chunks/chunk_store.go" \\
  && ok "go/chunks/chunk_store.go" \\
  || miss "missing critical file: go/chunks/chunk_store.go"
test -f "go/datas/commit.go" \\
  && ok "go/datas/commit.go" \\
  || miss "missing critical file: go/datas/commit.go"
test -f "go/config/config.go" \\
  && ok "go/config/config.go" \\
  || miss "missing critical file: go/config/config.go"
test -f "cmd/noms/noms.go" \\
  && ok "cmd/noms/noms.go" \\
  || miss "missing critical file: cmd/noms/noms.go"
test -f "go/chunks/chunk_serializer.go" \\
  && ok "go/chunks/chunk_serializer.go" \\
  || miss "missing critical file: go/chunks/chunk_serializer.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1744 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1714d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/attic-labs/noms"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Noms is a decentralized, versioned, content-addressed database descended from Git that stores structured data with built-in support for concurrent synchronization across disconnected instances. It uses prolly-trees (probabilistic B-trees) for efficient indexing and provides atomic transactions with state persistence to filesystem or S3 via the NBS ChunkStore implementation. Monorepo with cmd/noms as the CLI entry point (Go), cmd/noms/splore as a React-based web UI for data exploration (JavaScript/Webpack), and core database logic distributed across Go packages (inferred from 3.7MB Go codebase). The noms CLI wraps database operations (blob, commit, diff, ds, json, list, log, map, merge, root, serve, set, show, stats, struct, sync, version commands in individual files).

Researchers and developers building distributed systems that need Git-like version control semantics applied to structured databases, plus teams needing efficient offline-first collaboration with automatic conflict reconciliation without manual merge resolution.

The project is archived and unmaintained as of the README warning — Aaron Boodman explicitly states 'Noms is not being maintained' and directs users to Dolt, an active fork. There is a comprehensive test suite (test files throughout cmd/noms/), CI via Travis CI (.travis.yml), and the codebase is well-structured, but no new development is happening.

Critical risk: The project is officially abandoned. No active maintenance, no recent commits expected, and the author explicitly recommends using Dolt instead. Any production use is unsupported. Dependencies are locked to legacy versions (babel 6, webpack 3, React 15, flow 0.45) that have known vulnerabilities and lack modern tooling support.

Nothing — the project is archived. The last activity was years ago. There are no active PRs, no ongoing development, and no planned features. The codebase is frozen in a stable but legacy state.

Clone and build using Go: git clone https://github.com/attic-labs/noms && cd noms && go build ./cmd/noms (requires Go 1.x). For the splore UI: cd cmd/noms/splore && npm install && npm run build (requires Node.js, uses webpack 3 + React 15). Note: This is for research/reference only — the project is not maintained.

Daily commands: CLI: go build ./cmd/noms && ./noms --help to see subcommands. Splore Web UI: cd cmd/noms/splore && npm run build generates out.js, then npm start runs webpack dev server with hot reload on :8080 (via webpack -w). Run npm run buildgo to embed UI into Go binary.

• go/chunks/chunk_store.go — Core interface defining how Noms persists and retrieves immutable chunks of data; foundational to the entire versioned database design
• go/datas/commit.go — Implements commit semantics for the versioned database; essential for understanding how version history is maintained
• go/config/config.go — Configures storage backends and resolves database URLs; every contributor must understand how storage is initialized
• cmd/noms/noms.go — CLI entry point orchestrating all subcommands; essential for understanding the public API and intended usage patterns
• go/chunks/chunk_serializer.go — Serializes/deserializes chunks to/from bytes; critical for data persistence and inter-node synchronization
• cmd/noms/splore/noms_splore.go — Web UI server for browsing Noms databases; demonstrates how the HTTP API surfaces the underlying data structures

• ChunkStore interface (Go interfaces, hash-based storage) — Abstraction for reading/writing immutable chunks; implementations can be memory, disk, or remote
  • Failure mode: Storage unavailable → all operations fail; chunk loss → data corruption
• Chunk Serializer (Binary encoding, type reflection) — Converts between Go data structures and byte sequences; preserves type information
  • Failure mode: Serialization bug → data corruption; incompatible version → deserialization fails
• Commit Graph (Go structs, hash pointers) — Represents version history as DAG; enables diff, merge, and sync operations
  • Failure mode: Corrupted graph → merge/sync fails; circular references → infinite loops
• Config Resolver (URL parsing, factory pattern) — Parses database URLs and instantiates appropriate chunk store backend
  • Failure mode: Unknown scheme → database cannot be opened; misconfiguration → wrong storage used
• CLI Command Router (Kingpin CLI framework, Go functions) — Dispatches user input to appropriate subcommand handlers

Add a new CLI subcommand

1. Create a new file cmd/noms/noms_<command>.go implementing the operation logic (cmd/noms/noms_newfeature.go)
2. Register the command handler in the main dispatcher (cmd/noms/noms.go)
3. Add corresponding test file with test cases (cmd/noms/noms_newfeature_test.go)
4. Update README.md with usage documentation (cmd/noms/README.md)

Add a new storage backend

1. Create a new chunk store implementation implementing the ChunkStore interface (go/chunks/mynewstore.go)
2. Register the URL scheme handler in the resolver (go/config/resolver.go)
3. Add configuration handling in config module (go/config/config.go)
4. Write test suite using the common test utilities (go/chunks/mynewstore_test.go)

Add a new feature to Splore UI

1. Create a new React component in the splore src/ directory (cmd/noms/splore/src/newcomponent.js)
2. Import and integrate into the main UI component (cmd/noms/splore/src/main.js)
3. Build the JavaScript bundle and regenerate Go bindings (cmd/noms/splore/package.json)
4. Update the Go splore server if new HTTP endpoints are needed (cmd/noms/splore/noms_splore.go)

• Go — Efficient concurrency for chunk management, fast binary serialization, and cross-platform CLI compilation; aligns with Git-inspired design of immutable objects
• React + Webpack (Splore) — Interactive browsing UI for complex nested data structures; Webpack bundling allows embedding the UI in the Go binary
• Content-addressable chunks (hash-based) — Enables deduplication, efficient synchronization, and Git-like version control semantics; chunks with same content have same identity
• HTTP remote protocol — Allows Noms databases to sync and share data over networks without tight coupling to storage implementation

• All commits are immutable; new commits always created rather than in-place updates

  • Why: Enables version history preservation and fork-friendly design; required for decentralized sync
  • Consequence: Higher memory/disk usage over time as all versions retained; garbage collection of orphaned commits not automatic

• Chunk store is pluggable and abstract; no single built-in file format

  • Why: Flexibility to use different backends (memory, LevelDB, remote HTTP, etc.)
  • Consequence: Storage format depends on resolver configuration; data portability requires explicit sync operations

• Three-way merge implemented for conflict resolution, similar to Git

  • Why: Handles concurrent edits in decentralized scenarios
  • Consequence: Complex merge logic; not all conflicts automatically resolvable; user must handle merge conflicts manually

• Real-time multi-user locking or ACID transactions on individual values
• Automatic garbage collection of unreachable commits (explicit pruning only)
• SQL query language or relational schema enforcement
• Sharding or horizontal scaling across multiple machines

Abandoned codebase: Do not expect bug fixes or compatibility updates. Legacy dependencies: splore requires Node.js compatible with Babel 6, Webpack 3, React 15, and Flow 0.45 — modern Node versions (16+) may have compatibility issues. Python 2 assumption: js2go.py (cmd/noms/splore/js2go.py) is likely Python 2; may fail on Python 3 without updates. No version pinning in Go: go.mod likely uses loose constraints or is absent entirely (pre-modules era). Splore's out.js embedding: The js2go.py step is required before pushing changes to the CLI; forgetting it will silently use stale UI.

• Content-Addressing (Content Hash) — Noms' core principle — every piece of data is identified by its hash, enabling deduplication, efficient diffing, and automatic conflict detection across forks
• Prolly-Trees (Probabilistic B-Trees) — Noms' custom tree structure for indexing; uses randomization to achieve balanced trees without rebalancing, key to efficient range queries and minimal diff sizes
• CRDT-like Synchronization — Noms allows disconnected instances to sync changes without a central authority, automatically merging non-conflicting updates similar to CRDT semantics
• ChunkStore (Pluggable Storage Backend) — Abstract storage layer in Noms allowing multiple backends (filesystem NBS, S3 NBS) without changing core logic — critical for cloud deployment and scalability
• Immutable Data Structures — All Noms data is immutable; versioning is achieved by creating new root pointers rather than mutating in-place, enabling efficient branching and merging
• Type System for Structured Data — Unlike SQL or document stores, Noms enforces a first-class type system (structs, lists, maps, blobs) known at write time, enabling safe schema evolution and efficient serialization
• Atomic Transactions with CP Semantics — Single-instance Noms provides strict Consistency and Partition tolerance; when backed by S3, becomes effectively CA per Spanner whitepaper, critical for understanding correctness guarantees

• dolthub/dolt — Active fork of Noms that continues development with SQL support, better CI/CD, and production-ready maintenance
• google/gvisor — Another Google-era Go project using content-addressed storage and version control primitives for system design (related conceptual approach)
• ipfs/go-ipfs — Decentralized, content-addressed storage system using similar merkle-tree versioning principles as Noms, though for file systems not databases
• ChainCodeLabs/bitcoin — Bitcoin's blockchain is a versioned, decentralized append-only ledger sharing Noms' immutability and synchronization challenges
• apache/cassandra — Distributed database with eventual consistency and version tracking patterns relevant to understanding Noms' production deployment model

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add missing unit tests for noms_blob_put.go and noms_blob_get.go

The blob operations are core functionality but noms_blob_put.go has no corresponding test file, while noms_blob_get.go only has noms_blob_get_test.go. Complete test coverage for blob put operations would catch regressions in data persistence and is critical for a versioned database.

• [ ] Create cmd/noms/noms_blob_put_test.go with test cases for blob upload functionality
• [ ] Add tests for error handling (invalid blobs, storage failures)
• [ ] Add tests for edge cases (empty blobs, very large blobs)
• [ ] Run go test ./cmd/noms to verify tests pass

Migrate noms_splore webpack build from deprecated Babel 6 to Babel 7

The splore UI (cmd/noms/splore/) uses outdated Babel 6 dependencies (babel-cli@^6.24.1, babel-core@^6.25.0) which are no longer maintained and have known security vulnerabilities. Upgrading to Babel 7 would modernize the build pipeline and improve security.

• [ ] Update cmd/noms/splore/package.json: replace babel-cli/babel-core with @babel/cli/@babel/core@^7.x
• [ ] Replace babel-preset-stage-3 with appropriate @babel/preset-* equivalents
• [ ] Update cmd/noms/splore/.babelrc to new Babel 7 format
• [ ] Test webpack build: npm run build and npm run buildgo in cmd/noms/splore/
• [ ] Verify prettier and eslint still work with updated transpilation

Add integration tests for noms_sync.go end-to-end synchronization

While noms_sync_test.go exists, the sync functionality is complex and critical for a versioned, syncable database. Current tests may not cover all replication edge cases (concurrent syncs, partial failures, conflict resolution). Enhanced integration tests would improve reliability.

• [ ] Examine existing cmd/noms/noms_sync_test.go to identify gaps in coverage
• [ ] Add test cases for concurrent sync operations between multiple datasets
• [ ] Add test cases for partial sync failures and recovery scenarios
• [ ] Add test cases for syncing with different database chunks/structures
• [ ] Document sync test scenarios in cmd/noms/README.md if not already present

• Add missing tests for cmd/noms/noms_blob.go, cmd/noms/noms_root.go, and cmd/noms/noms_struct.go — these files have no corresponding _test.go companions while most other subcommands have tests
• Document the content-addressing and prolly-tree implementation in HACKING.md with code examples — the README links to doc/intro.md but there is no concrete code walkthrough for how chunks are hashed and indexed
• Create a quick-start example in cmd/noms/README.md showing how to initialize a Noms database, add structured data (map/list/struct), commit it, and sync between two instances — currently only CLI help is available

This codebase presents significant security concerns primarily due to severely outdated dependencies (from 2017) with known CVEs, unspecified Docker base images creating non-deterministic builds, and an exposed service port without documented security controls. The project is officially unmaintained, making it unsuitable for production use. Critical actions needed: update all npm dependencies, pin Docker base images to specific versions, and document/implement authentication and encryption for the exposed service. Users should migrate to Dolt, the actively maintained fork.

• High · Outdated and Vulnerable Dependencies — cmd/noms/splore/package.json. The package.json contains multiple dependencies from 2017 with known security vulnerabilities. Babel (^6.24.1), ESLint (^3.5.0), Webpack (^3.5.3), and other packages are severely outdated. These versions have known CVEs including prototype pollution, arbitrary code execution, and denial of service vulnerabilities. Fix: Update all dependencies to the latest stable versions. Specifically: upgrade Babel to 7.x, ESLint to latest, Webpack to 5.x+, and all other packages to current versions. Run 'npm audit' and address all vulnerabilities.
• High · Unspecified Go Base Image — Dockerfile (line 1). The Dockerfile uses 'golang:latest' which pins to the latest golang version without specifying a specific version. This creates non-deterministic builds and may introduce breaking changes or vulnerabilities unexpectedly. Fix: Pin to a specific Go version, e.g., 'golang:1.21-alpine' instead of 'golang:latest'. This ensures reproducible builds and allows for controlled updates.
• Medium · Debugging Webpack Configuration — cmd/noms/splore/package.json (build script). The build script uses 'webpack -d' flag which enables source maps in production bundles. This exposes internal code structure and may facilitate reverse engineering of the frontend logic. Fix: Remove the '-d' flag from production builds. Source maps should only be generated for development environments or not included in deployed artifacts.
• Medium · Exposed Service Port — Dockerfile (line 14: EXPOSE 8000). The Dockerfile exposes port 8000 without any documented authentication or encryption mechanism. The noms_serve command serves data directly on this port, potentially exposing the database to unauthorized access. Fix: Document authentication requirements, implement TLS/HTTPS, and restrict network access through firewall rules. Consider running behind a reverse proxy with authentication.
• Medium · Insecure Alpine Base Image — Dockerfile (line 16). The final stage uses 'alpine:latest' without a pinned version, leading to non-deterministic builds similar to the golang image issue. Fix: Use a specific Alpine version, e.g., 'alpine:3.18' instead of 'alpine:latest' for reproducible and secure deployments.
• Low · Missing Security Headers Documentation — cmd/noms/noms_serve.go (inferred from file structure). No documentation or configuration visible for security headers (CORS, CSP, X-Frame-Options, etc.) for the exposed HTTP service on port 8000. Fix: Document and implement appropriate security headers in the serve command. Review the noms_serve.go implementation to ensure proper CORS and security header configuration.
• Low · Project Maintenance Status — README.md. The README explicitly states 'This project is not active' and 'not being maintained.' Security vulnerabilities will not receive timely patches. Fix: This project should not be used in production. Users are directed to use Dolt (https://github.com/dolthub/dolt) instead, which is actively maintained.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.