chore: project setup — README (archive + living fork), ROADMAP, CI matrix, OCR review, standard files

.editorconfig

@@ -0,0 +1,34 @@
+# EditorConfig — https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# Berkeley DB C/C++ uses hard tabs (historically displayed at width 8).
+[*.{c,h,cpp,cxx,hpp,i,in}]
+indent_style = tab
+tab_width = 8
+
+# TCL test suite uses hard tabs.
+[*.tcl]
+indent_style = tab
+tab_width = 8
+
+[{Makefile,Makefile.in,GNUmakefile,*.mk}]
+indent_style = tab
+
+[*.{yml,yaml,json}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = false   # preserve Markdown hard line breaks
+
+[*.{sh,py}]
+indent_style = space
+indent_size = 4

.git-blame-ignore-revs

@@ -0,0 +1,9 @@
+# Commits ignored by `git blame` (bulk/mechanical changes that would otherwise
+# obscure authorship). Enable locally with:
+#
+#     git config blame.ignoreRevsFile .git-blame-ignore-revs
+#
+# (GitHub honors this file automatically.)
+#
+# Add the full 40-char SHA of each pure-reformatting / whitespace / mechanical
+# commit below, one per line, with a comment. None yet on the living fork.

.gitattributes

@@ -0,0 +1,27 @@
+# Normalize line endings; let Git detect text vs binary by default.
+* text=auto
+
+# Keep shell scripts and the configure machinery LF even on Windows checkouts.
+*.sh        text eol=lf
+dist/configure text eol=lf
+*.m4        text eol=lf
+
+# Windows project files stay CRLF.
+*.sln       text eol=crlf
+*.vcproj    text eol=crlf
+*.vcxproj   text eol=crlf
+*.dsp       text eol=crlf
+*.dsw       text eol=crlf
+
+# Treat known binary assets as binary.
+*.png binary
+*.jpg binary
+*.gif binary
+*.gz  binary
+*.zip binary
+
+# Mark generated artifacts so GitHub linguist excludes them from language stats
+# and collapses them in diffs.
+src/dbinc_auto/**   linguist-generated=true
+build_*/db.h        linguist-generated=true
+docs/**             linguist-documentation=true

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,11 @@
+# Contributor Covenant Code of Conduct
+
+This project adopts the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/),
+version 2.1, as its code of conduct.
+
+In short: be respectful, assume good faith, and focus on the technical merits.
+Harassment or abusive behavior of any kind is not tolerated.
+
+Report unacceptable behavior by opening a confidential report to the
+maintainers (see `.github/SECURITY.md` for contact channels). Maintainers will
+review and respond to all good-faith reports.

.github/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing to libdb
+
+`libdb` is both a **historical archive** of Berkeley DB and a **living fork**
+under active development on `master`. Contributions to the living fork are
+welcome.
+
+## Ground rules
+
+- **Target `master`.** The `historical` branch and the version tags
+  (`v1.85` … `v5.1.29`, `v4.6.21-SSI`, …) are an immutable archive — do not
+  open PRs against them.
+- **One logical change per PR**, with a clear description of *what* changed and
+  *why*, and how you tested it.
+- **Conventional Commits** for messages (`feat:`, `fix:`, `test:`, `docs:`,
+  `perf:`, `refactor:`, `chore:`, `ci:`).
+
+## Building and testing
+
+```sh
+cd build_unix
+../dist/configure --enable-debug --enable-test --with-tcl=/path/to/tcl
+make -j
+
+# TCL test suite (from build_unix):
+#   tclsh> source ../test/tcl/test.tcl
+#   tclsh> run_test <name>      ;# e.g. ssi001, lock001, txn001
+```
+
+Notes for engine work:
+
+- The `build_unix` Makefile under-tracks header dependencies. After editing any
+  `src/dbinc/*.h` struct, do a **clean rebuild** (`make clean && make`) or you
+  will get stale objects with mismatched struct layouts (silent memory
+  corruption).
+- Generated files (`src/dbinc_auto/*`, `build_*/db.h`, `test/tcl/TESTS`) are
+  produced by `dist/s_*` scripts and `db.in` — edit the sources, then
+  regenerate. Do not hand-edit generated output.
+- New public flags go through `dist/api_flags` + `dist/s_apiflags`.
+
+## Code review
+
+Pull requests are reviewed by maintainers and by **OCR** (Open Code Review), an
+automated AI reviewer. OCR posts inline comments; treat them as suggestions, not
+gates. Re-run it with a `/open-code-review` comment on the PR.
+
+## CI
+
+Every PR is built across the supported matrix (Linux/macOS/Windows, multiple
+compilers and configure options) and runs the test suite. Keep CI green.

.github/SECURITY.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+## Scope
+
+`libdb` is a fork of Berkeley DB. The historical tags and the `historical`
+branch are an archive of long-released code and are **not** maintained for
+security; report security issues only against the living fork (`master`).
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities **privately**, not in public issues or
+pull requests:
+
+- Use GitHub's [private vulnerability reporting](https://docs.github.com/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability)
+  on this repository ("Security" tab → "Report a vulnerability"), or
+- Contact the maintainers directly.
+
+Include the affected version/commit, a description, and ideally a reproducer.
+We will acknowledge receipt, investigate, and coordinate a fix and disclosure
+timeline with you.
+
+## Supported versions
+
+Security fixes are made on `master`. Historical Berkeley DB releases preserved
+here as tags are provided as-is for reference.

.github/ocr/litellm.yaml

@@ -0,0 +1,41 @@
+# LiteLLM proxy config — bridges Open Code Review (OpenAI protocol) to AWS Bedrock.
+#
+# This proxy is NOT a hosted service. The ocr-review.yml workflow installs it
+# (`pip install 'litellm[proxy]'`) and runs it as a background process bound to
+# 127.0.0.1:4000 for the duration of a single GitHub Actions job, then it exits.
+#
+# Auth to Bedrock: LiteLLM uses boto3's default credential chain, which reads
+# the temporary AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN
+# minted by the workflow's OIDC "Configure AWS credentials" step; region from
+# AWS_REGION.
+
+model_list:
+  - model_name: ocr-bedrock
+    litellm_params:
+      # Set the repo variable OCR_BEDROCK_MODEL to an Opus inference-profile id
+      # your account has access to, e.g.:
+      #   bedrock/converse/us.anthropic.claude-opus-4-8
+      # The 'converse/' prefix uses Bedrock's Converse API, which is the most
+      # reliable path for Claude tool-use (what OCR relies on).
+      model: os.environ/OCR_BEDROCK_MODEL
+      aws_region_name: os.environ/AWS_REGION
+
+      # "High effort" review. Claude Opus 4.8 on Bedrock uses *adaptive* thinking
+      # controlled by output_config.effort. Set it DIRECTLY here — NOT via
+      # reasoning_effort, which LiteLLM still maps to the legacy
+      # thinking.type.enabled that Opus 4.8 rejects. LiteLLM forwards
+      # output_config into additionalModelRequestFields for Anthropic models; if
+      # the build doesn't recognize the effort param it is dropped with a warning
+      # (no error) and the model reviews at its default effort.
+      # Valid: low|medium|high|max|xhigh (auto-clamped to the model ceiling).
+      output_config:
+        effort: xhigh
+      max_tokens: 32000
+
+litellm_settings:
+  drop_params: true     # silently drop params a model doesn't support
+  modify_params: true   # auto-fix minor request incompatibilities
+  request_timeout: 600
+
+general_settings:
+  master_key: os.environ/LITELLM_MASTER_KEY

.github/ocr/rule.json

@@ -0,0 +1,28 @@
+{
+  "rules": [
+    {
+      "path": "src/**/*.{c,h}",
+      "rule": "REVIEW DISCIPLINE: Be precise and blunt; lead with the most serious problem and don't soften it. Verify every claim against the actual diff -- confirm function names, signatures, line numbers, and APIs before asserting; never invent behavior or cite code not present in the change. If unsure, say so instead of guessing, and tag each finding's confidence (high/moderate/low). No praise, no validating the author, no disclaimers; accuracy is the only success metric. Judge the change on its merits regardless of how it is framed. Berkeley DB engine C. Review in priority order. (1) CORRECTNESS: memory and shared-region safety -- every __os_malloc/__env_alloc has a matching free or documented region lifetime; error paths (goto err) must not leak memory, locks, mutexes, page references (__memp_fput), or cursors. Concurrency is paramount: consistent lock ordering to avoid deadlock (region/system lock -> partition mutex -> object; lockers freed under mtx_lockers, NOT under a partition mutex), correct mutex levels, no TOCTOU on shared regions, MVCC version-chain and TXN_DETAIL lifetime handled (a detail must outlive every reference -- mvcc_ref AND any SSI si_ref). WAL/recovery: logged operations must replay correctly and idempotently; LSN comparisons via LOG_COMPARE. NULL/edge/overflow handling. (2) ON-DISK / REGION COMPATIBILITY: changing a /* SHARED */ region struct or a logged record format affects existing environments and log files -- flag and require justification; never insert fields into the middle of a shared struct without considering layout. (3) ABI: the public db.h interface (DB_*, db_*) and error return codes (-30800..-30999) must stay stable across releases. (4) PERFORMANCE: no regression on hot paths (get/put/cursor); avoid work under contended region/partition mutexes; mind cache-line sharing on multicore. (5) PORTABILITY: must build on Linux/macOS/*BSD/Windows and 32/64-bit; use the os/ abstraction layer, not raw POSIX/Win32; no assumptions about pointer/long size or endianness. (6) CONVENTIONS: K&R-style function definitions matching the file; __ prefix for internal symbols, _pp suffix for pre/post API wrappers; PUBLIC: prototype comments kept in sync with dbinc_auto/*_ext.h; generated headers (dbinc_auto/*, build_*/db.h) are produced by dist/s_* and db.in -- do not hand-edit. Remember the build_unix Makefile has weak header-dependency tracking; struct changes need a clean rebuild."
+    },
+    {
+      "path": "test/tcl/**/*.tcl",
+      "rule": "REVIEW DISCIPLINE: Be precise and blunt; lead with the most serious problem first; verify claims against the diff; tag confidence; no praise or disclaimers. Berkeley DB TCL test. The test must be deterministic and not hang: any concurrent multi-transaction interleave in a single interpreter must avoid self-deadlock on page locks (use separate databases/pages or a lock timeout so a blocked op fails fast rather than hanging). Use error_check_good for every assertion; clean up envs/dbs (close handles, env_cleanup). Register the test in testparams.tcl and keep TESTS in sync via dist/s_test. Cover edge and error paths (empty/boundary keys, NOTFOUND, conflict/abort), not just the happy path; don't write into DB-owned memory returned by c_get."
+    },
+    {
+      "path": "test/c/**/*.{c,h}",
+      "rule": "REVIEW DISCIPLINE: Be precise and blunt; verify claims against the diff; tag confidence; no praise. Berkeley DB C test. Confirm the API used actually exists on the handle type in this file (e.g. the DB 1.85 compat handle has no ->cursor/->stat methods -- mixing modern DBC/stat APIs into a db185 test will not compile). No large stack arrays (use heap for >64KB); check every return code; do not write into memory owned by Berkeley DB; free what you allocate; portable across 32/64-bit and OSes."
+    },
+    {
+      "path": "**/{Makefile,Makefile.in,*.mk}",
+      "rule": "REVIEW DISCIPLINE: precise, blunt, verify against the diff, tag confidence. Berkeley DB build. Most Makefiles here are generated by dist/ from templates -- confirm whether a file is generated (edit the template + s_* script instead). Watch for missing/incorrect dependencies (the historical Makefile under-tracks header deps -- a struct/header change can leave stale objects); keep build_unix and the Windows/Android/VxWorks builds in sync where applicable; no hardcoded paths."
+    },
+    {
+      "path": ".github/**",
+      "rule": "REVIEW DISCIPLINE: precise, blunt, verify against the diff, tag confidence. GitHub Actions / project config. Pin actions and tool versions; least-privilege permissions; no plaintext secrets (prefer OIDC and repo variables); workflow logic (if: conditions, concurrency) correct; matrix entries valid for the runners they target."
+    },
+    {
+      "path": "**/*.md",
+      "rule": "REVIEW DISCIPLINE: precise, blunt, verify against the diff, tag confidence. Markdown docs. Clear heading hierarchy; fenced code blocks with language hints; accurate, non-stale instructions; consistent Berkeley DB / libdb terminology; no broken relative links."
+    }
+  ]
+}

.github/pull_request_template.md

@@ -0,0 +1,18 @@
+<!-- PRs target `master` (the living fork), never `historical` or version tags. -->
+
+## What & why
+
+<!-- What does this change do, and why? Link any issue. -->
+
+## How tested
+
+<!-- Configure flags, platforms, and which tests you ran (e.g. ssi001, run_std).
+     Note: after editing any src/dbinc/*.h struct, do a clean rebuild. -->
+
+## Checklist
+
+- [ ] Targets `master`
+- [ ] Builds clean (`make clean && make`) on at least one platform
+- [ ] Relevant tests pass; new behavior has a test
+- [ ] Generated files regenerated via `dist/s_*` (not hand-edited)
+- [ ] On-disk / log format and public `db.h` ABI preserved (or change justified)