Palimpsest Plasma

Table of Contents

• Overview
• What it is
• What it is not
• Sibling projects
• Quickstart
• Writing a policy
• Workspace layout
• Architecture
• Static site
• License
• Author

Overview

palimpsest-plasma is a deterministic, typed policy engine for the agentic era. You write policies as machine-readable, deontic rules — obligations, prohibitions, permissions over repository state — and plasma check evaluates a repository against them exactly: same policy, same repository, same findings, byte for byte, every time.

That precision is the point. When neural/LLM tooling operates on a codebase, something deterministic has to define what "correct" means and verify it afterwards. Plasma is that something.

What it is

• A policy engine: typed rules in TOML or JSON, evaluated by a pure, total function over a collected fact snapshot. No clocks, no randomness, no ambient state. See engine-v0-design.adoc for the normative semantics.

• A license/SPDX toolkit: plasma audit checks SPDX headers against a zone-aware license map (.plasma.toml), powered by a real SPDX expression parser; plasma init, migrate, and badge handle license adoption for any SPDX license.

• A fact source for agent verification: plasma facts emits the exact JSON snapshot the evaluator sees; plasma check --format sarif emits SARIF 2.1.0 with stable plasma/<rule-id> rule identifiers.

What it is not

• Not the PMPL governance engine. The Palimpsest license (PMPL) is a separate, future project. This repo’s parser recognises Palimpsest-family SPDX identifiers, but the project itself is licensed plainly: code under MPL-2.0, documentation under CC-BY-SA-4.0.

• Not an OCaml system. Earlier documentation described an OCaml core that was never built. The engine is Rust, implementing the design in policy-ast-v0.1.adoc, and its policy format is specified so a future formal core (OCaml/Catala) can generate or verify the same policies.

Sibling projects

Plasma is the policy-definition and compliance-evaluation member of a planned trio for keeping automated agents honest:

• somethings-fishy — forensic investigation of bot-inflicted damage

• did-you-actually-do-that — verification that agents did what they claimed

The integration contract is plasma’s deterministic output: JSON findings, SARIF results, and plasma facts snapshots (diffable before/after an agent run).

Quickstart

cargo build --release
./target/release/plasma check .            # evaluate against the bundled repo-hygiene policy
./target/release/plasma check . --format json
./target/release/plasma facts .            # the fact snapshot the evaluator sees
./target/release/plasma policy validate plasma-engine/policies/repo-hygiene.plasma.toml
./target/release/plasma audit .            # SPDX header audit (MPL-2.0 default)

plasma check exits 0 when no violation at or above the severity threshold exists (default: error), 1 otherwise — ready for CI and git hooks.

Writing a policy

schema_version = { major = 0, minor = 1 }
id = "my-policy"
version = { major = 1, minor = 0 }

[[rules]]
id = "license-file-present"
modality = "obligation"
severity = "error"
subject = { type = "repo" }
resource = { type = "file", path = "LICENSE*" }
action = { type = "present" }
rationale = "Every repository must carry its license text."

Rules bind a deontic modality (obligation, prohibition, permission) to a subject, resource, optional condition, and action. Subjects expand over the repository (file-pattern matches globs); conditions compose with all/any/not. The full vocabulary and its exact semantics are in engine-v0-design.adoc.

Workspace layout

Crate	Purpose
plasma-parser	SPDX expression lexer/parser (including Palimpsest-family identifiers), license family types, zone auditing (.plasma.toml), compatibility matrix, JSON/SARIF reports.
plasma-engine	Policy AST, versioned schema loading, fact collection, the pure evaluator, and finding/report rendering. Depends on plasma-parser.
root (plasma binary)	The CLI: check, facts, policy, audit, init, badge, migrate.

Architecture

See docs/architecture.adoc for the engine design, docs/policy-ast-v0.1.adoc for the original typed-AST design, docs/engine-v0-design.adoc for the normative v0 semantics and Catala-readiness guarantees, and TOPOLOGY.md for the project map and honest completion dashboard.

Static site

Compliance guidance builds through a local Elixir mix project at site/. Run mix site.build from that folder to regenerate site/_site. The GitHub Actions workflow in .github/workflows/nimble-site.yml deploys the pages.

License

Code is licensed under the Mozilla Public License 2.0 (see LICENSE). Documentation is licensed under CC-BY-SA-4.0 (see LICENSES/CC-BY-SA-4.0.txt). Every file carries an SPDX header; NOTICE has the details.

Author

Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>