Palimpsests

The project provides a clear upgrade path to newer versions rather than backporting to old ones, which is the appropriate model for a pre-1.0 project. SECURITY.md states the version policy explicitly: Palimpsests is pre-1.0 and evolving, security fixes land on main and in the latest published release, older 0.x releases are not maintained, and users should track the latest version. The upgrade path itself is simple — the package is installed and updated through pip in the standard way — and the changes that affect an upgrade are documented per release in CHANGELOG.md, which follows a Keep-a-Changelog structure with explicit Changed and Breaking sections and upgrade notes where behaviour shifts (for example, the changelog records that before v1.0 minor versions may include breaking changes, and calls out cases such as a first post-upgrade write being required before verify() reports fully). So where an upgrade is non-trivial, the interfaces that changed and the recommended steps are documented.

The project uses GitHub Issues as its issue-tracking system to track individual bugs, tasks, and enhancement requests. CONTRIBUTING.md directs contributors to open or link an issue when submitting work, and security-sensitive reports are routed separately through the private channel described in SECURITY.md. URL: https://github.com/Assault-Consulting/Palimpsests/issues

No externally reported vulnerabilities have been fixed in the last 12 months, so there is no reporter to credit — which makes this criterion not applicable for the current period. The project is nonetheless set up to credit reporters when the situation arises: SECURITY.md commits to crediting reporters in the release notes unless they ask to remain anonymous. When the first such report is fixed, the reporter will be credited there.

The project has a documented process for responding to vulnerability reports, published in SECURITY.md. It sets out how to report privately (GitHub private security advisories and a maintainer email, not a public issue), a response commitment (the maintainers will acknowledge a report within a few business days and agree on a disclosure timeline before any public disclosure), how reporters are credited (in the release notes, unless anonymity is requested), and which versions receive fixes (security fixes land on main and in the latest release; older 0.x releases are not maintained). This gives a reporter a clear, end-to-end path from private report to coordinated disclosure.
https://github.com/Assault-Consulting/Palimpsests/blob/main/SECURITY.md

The project identifies a specific coding style standard for its main language (Python) and requires contributions to comply with it. CONTRIBUTING.md has a "Code style" section naming the standard: ruff with the rule set ["E", "F", "I", "B", "UP"] (pycodestyle/PEP 8, Pyflakes, isort import ordering, flake8-bugbear, pyupgrade), a line length of 100, and target Python 3.11 — with the instruction to run ruff check . before pushing. This is not just documented but enforced: the ruleset is pinned in pyproject.toml ([tool.ruff] / [tool.ruff.lint]), and lint is a merge-blocking status check on main, so every contribution must generally conform before it can be merged.
https://github.com/Assault-Consulting/Palimpsests/blob/main/CONTRIBUTING.md

The project automatically enforces its chosen coding style. The style is defined as ruff with the rule set ["E", "F", "I", "B", "UP"], line length 100, target Python 3.11 (pyproject.toml, [tool.ruff] / [tool.ruff.lint]). ruff is an open-source style/lint tool for Python, and it is run automatically as a merge-blocking status check in CI on every push and pull request — a change that does not conform to the ruleset cannot be merged into main. Contributors also run ruff check . locally before pushing, per CONTRIBUTING.md. So enforcement is automated by an open-source tool for the project's main language, not left to manual review.

The project does not build native binaries, so compiler/linker environment variables (CC, CFLAGS, CXX, CXXFLAGS, LDFLAGS) do not apply. Palimpsests is pure Python, packaged with a PEP 517 build backend (hatchling); the build produces platform-independent wheels and an sdist, with no compilation step of its own. The one native component it can use — the llama.cpp C library — is not compiled by this project; it is consumed at runtime through the optional [native] extra as a separately built dependency. There is therefore no compiler or linker invocation in the project's build for these variables to be honored by.

There is no compilation or install step in this project that could strip debug information. Palimpsests is pure Python, built with a PEP 517 backend (hatchling) into platform-independent wheels — there are no compiled artifacts and no install -s-style stripping to avoid. Python source is shipped as-is and remains fully inspectable/debuggable; nothing in the build or install removes debug information. (The one native component, llama.cpp, is a separately built runtime dependency behind the optional [native] extra, not something this project's build or install produces.) This criterion therefore does not apply.

This criterion concerns recursive Make-style builds over subdirectories that have cross-dependencies (the classic "recursive make considered harmful" problem). It does not apply here: Palimpsests is pure Python with a PEP 517 build backend (hatchling), which builds the package as a single unit into wheels and an sdist — there is no recursive per-subdirectory build and therefore no opportunity for a recursive build to mishandle cross-directory dependencies. There is no Makefile or equivalent recursive build system in the project.

Palimpsests is a pure-Python project: the source is used directly rather than compiled into a different form. There is no compilation step whose output would need to be reproduced bit-for-bit — the .py files that run are the same source files kept in the repository, and packaging (a PEP 517 wheel/sdist via hatchling) simply archives that same source with metadata, it does not transform it. The criterion's own escape clause applies here — "scripting languages where source is used directly rather than compiled" — so this is not applicable.

Installation and removal use the standard, conventional mechanism for Python: pip. The software is published on PyPI and installed with pip install palimpsests (with optional extras — e.g. [native] — enabling the higher execution levels). It is a PEP 517/518 package built with hatchling, so it installs cleanly into any environment via the normal Python packaging path, and it is removed just as conventionally with pip uninstall palimpsests. No custom installer, build-from-source step, or manual file placement is required — the common practice for the language is exactly what the project uses.
https://pypi.org/project/palimpsests/

The project has no custom end-user installation system that writes compiled files to system locations, so conventions like DESTDIR do not apply. Installation is handled entirely by pip installing a PEP 517 wheel — pip already places files according to the active Python environment's standard scheme (site-packages / the environment prefix, honoring virtualenv/--prefix/--target as pip defines them), and the project neither overrides that placement nor ships a Makefile-style install target that would need to honor DESTDIR. There are also no compiled files of the project's own to place (pure Python). The criterion's escape clause — no separate install system of the project's own — therefore applies.

The project lets a potential developer set up the full change-making environment quickly, using common Python practice. CONTRIBUTING.md gives the steps: clone the repository, then python -m pip install -e ".[dev]" — an editable install of the project plus the [dev] extra, which pulls in the developer and test tooling (ruff pinned, pytest, pytest-httpx, numpy). After that, ruff check . runs the linter and python -m pytest runs the full test suite. So one standard editable-install command brings in the software, the supporting tools, and the test environment together, and tests are run with the standard Python invocation — no bespoke bootstrap script or manual dependency wrangling.

External dependencies are declared in a computer-processable format in pyproject.toml — the standard machine-readable manifest for a PEP 621 Python project. Runtime dependencies are listed under [project.dependencies], and the optional feature sets (e.g. [native] for the level-3 backend, [dev] for the developer/test tooling) under [project.optional-dependencies], each with version constraints (lower bounds; the lint tool pinned). Any standard tool — pip, build back-ends, dependency scanners, Dependabot — parses this file directly, and Dependabot is enabled on the repository to monitor those dependencies.
https://github.com/Assault-Consulting/Palimpsests/blob/main/pyproject.toml

The project monitors its external dependencies for known vulnerabilities on an ongoing basis. Dependabot is enabled on the repository, which continuously watches the dependencies declared in pyproject.toml against vulnerability databases and opens alerts/update pull requests when a known-vulnerable dependency is identified. The project also runs OpenSSF Scorecard, whose checks include dependency-update and vulnerability signals (badge shown on the repository front page). When an alert surfaces, it is handled through the normal pull-request process — updating the dependency, or confirming non-exploitability — under the response practice documented in SECURITY.md. There are currently no known unaddressed vulnerable dependencies.

Reused external components are easy to identify and update. The project does not vendor or copy third-party code into the tree; every externally maintained component is a normal, versioned dependency declared in pyproject.toml ([project.dependencies] and the optional-dependency groups), resolved from PyPI. Because they are standard packaged dependencies rather than embedded copies, updating one when a vulnerability is found is a routine version bump — pip resolves it, Dependabot proposes the update automatically, and no in-tree fork has to be patched by hand. The project also favors standard, widely used components delivered by the platform (e.g. SQLCipher/keyring for at-rest encryption and credential storage, httpx for transport) rather than bespoke implementations, so fixes flow from upstream maintenance.

The project avoids deprecated or obsolete functions and APIs where supported open-source alternatives exist. It targets current, actively supported Python (3.11+), and modern-Python usage is enforced automatically: the ruff ruleset includes UP (pyupgrade), which flags legacy idioms and pushes code to current language constructs, and lint is a merge-blocking gate — so deprecated patterns do not accumulate. Dependencies are kept current through Dependabot rather than pinned to end-of-life versions, and the components chosen are current, maintained ones (httpx for HTTP, SQLCipher/keyring, hatchling/PEP 517 packaging, Sigstore for signing) rather than deprecated predecessors. There are no known uses of obsolete APIs for which a readily available alternative is being ignored.

An automated test suite runs on every change to the shared repository. GitHub Actions CI is triggered on push and on pull request against main (.github/workflows/ci.yml) and executes the full pytest suite across a matrix of three operating systems and Python 3.11/3.12. It produces a clear pass/fail report: the run's success or failure is reported back as a required status check on the commit/PR (and gates merge into main), and the CI status is shown as a live badge on the repository front page. So each change gets an automated suite with an explicit success-or-failure result, not a manual or best-effort check.

Regression tests are added for well over 50% of bugs fixed — it is the project's standing policy, enforced in review. CONTRIBUTING.md mandates that tests ship with every behavioral change, and a bug fix is a behavioral change, so fixes land with a test that exercises the corrected behavior; because the test suite is a merge-blocking gate, a fix without its covering test does not get merged. Recent fixes demonstrate the practice: for example, a defect in the audit-format test vectors (an anchor-completeness inconsistency) was fixed together with regression tests that assert the exact diagnosis — tests/test_pala_codec.py and tests/test_pala_cli.py verify that a lagging anchor is reported as an unanchored tail with the correct lag count — and earlier subsystem fixes (e.g. in the state validator and the native scheduler) each landed with their own tests/ additions. The per-PR history shows the test-with-fix pattern throughout.

The project's automated test suite achieves statement coverage above the 80% threshold, measured by a FLOSS tool. Coverage is measured in CI with pytest-cov / coverage.py (both open source), and the CI coverage job is gated: the build fails if statement coverage drops below 80%. Current statement coverage is ~87% across the codebase. The one module that sits low is the hardware-only ctypes backend (llamacpp_backend.py), which requires a real GGUF model and GPU and is validated on hardware per benchmarks/RUNBOOK.md rather than in CI; excluding that hardware-gated path, the pure-software surface is well covered, and the overall figure still clears 80% comfortably.

The project has a formal written policy requiring tests for new significant functionality to be added to the automated test suite. CONTRIBUTING.md states, as a ground rule for contributions, that tests ship with every behavioral change — so adding new functionality obliges adding the tests that cover it, in the same pull request. The policy is not advisory: the automated suite is a merge-blocking status check on main, so a change introducing new functionality without its covering tests cannot be merged. The requirement is documented in writing, applied to every contributor, and enforced automatically.

The policy of adding tests for new functionality is documented in the contribution guidelines. CONTRIBUTING.md states, under its Tests section, "Every behavioral change ships with tests in the same PR," and additionally requires security-sensitive code to test escape and denial paths explicitly. This places the policy directly in the instructions contributors read before submitting changes. URL: https://github.com/Assault-Consulting/Palimpsests/blob/main/CONTRIBUTING.md

The project enforces a curated, deliberately-chosen strict rule set that is practical for the codebase: ruff with ["E","F","I","B","UP"] — pycodestyle/pyflakes correctness rules, import ordering, flake8-bugbear (which catches likely bugs and unsafe patterns), and pyupgrade. The linter is pinned to a fixed version and enforced as a required, merge-blocking CI check on every push and pull request, so the strictness is applied consistently rather than advisory. The rule set was chosen for signal over noise rather than enabling every available rule, which is the practical maximum for this project. URL: https://github.com/Assault-Consulting/Palimpsests/blob/main/pyproject.toml

The project implements secure-design principles concretely, not just documents them:
Fail-safe / secure defaults. TLS verification is on by default and no insecure transport is enabled by default; in the audit format, an unknown time source (time_trust = UNKNOWN) is required to carry a zero timestamp — the design refuses a confident-but-unjustified value rather than guessing.
Least privilege. The release workflow grants only the scopes it needs (id-token for OIDC publish, contents for the release), and publishing uses short-lived OIDC identity rather than a broad stored token.
Minimize / separate the attack surface. Header-only chain verification needs no key and touches no bodies, so a verifier sees no sensitive data; the audit codec is stdlib-only; and the one memory-unsafe boundary (the llama.cpp C library) is isolated behind an optional extra rather than in the core.
Defense in depth. Untrusted persisted state is bounds-checked by a validator and fuzzed; changes must pass branch protection, non-author review, green tests, coverage, SAST, and signed provenance — layered, not a single control.
Separation of privilege / keys apart from data. Encryption keys live outside the log (addressed by key_id, in an OS keychain or injected), so the data, its keys, config, and logs are separated; the audit path observes safety events rather than controlling them.
Open design (no security through obscurity). The audit format is fully specified and independently verifiable — its guarantees rely on the published mechanism, not on secrecy, to the point that a third party can verify a log with their own tool.
SECURITY.md maps vulnerability classes to these implemented mitigations, and docs/THREAT_MODEL.md and docs/ASSURANCE-CASE.md carry the design reasoning.