Skip to content

architecture.adoc

Latest commit

 

History

History
129 lines (108 loc) · 5.98 KB

architecture.adoc

File metadata and controls

129 lines (108 loc) · 5.98 KB
Raw

Palimpsest Plasma — Architecture

1. Purpose

palimpsest-plasma is a deterministic, typed policy engine. It interprets machine-readable policies — deontic rules over repository state — and evaluates real repositories against them, producing findings and audit reports that are byte-for-byte reproducible.

Its role in the wider tooling picture is precision: when neural/LLM agents operate on code, plasma defines what "correct" means (policies) and verifies it afterwards (deterministic evaluation), providing the contract that forensic tooling (somethings-fishy) and claim verification (did-you-actually-do-that) consume.

2. Design Principles

  • Typed correctness — Rust’s type system enforces structural soundness at compile time; deontic operators (obligation, prohibition, permission) are first-class values in the AST.

  • Determinism as a feature — evaluation is a pure, total function of (policy, facts): no clocks, no randomness, no ambient state, BTree-ordered iteration. Identical inputs produce identical output.

  • Reject at load, never mid-run — any construct the evaluator cannot give exact semantics to fails schema validation up front; a policy that loads always evaluates.

  • Narrative alignment — rules and findings carry rationale and source fields tying machine decisions back to human-readable intent.

  • Composable surfaces — the engine is consumed by thin wrappers (CLI today; hooks and CI actions on the roadmap) that never embed policy logic.

3. Project Layout

palimpsest-plasma/
  Cargo.toml                        -- workspace: ".", plasma-parser, plasma-engine

  src/                              -- the `plasma` CLI binary
    main.rs                         -- clap surface: check/facts/policy/audit/init/badge/migrate
    check.rs                        -- plasma check (policy evaluation)
    facts_cmd.rs                    -- plasma facts (fact snapshot dump)
    policy_cmd.rs                   -- plasma policy validate
    audit.rs                        -- SPDX audit on plasma-parser's scan_repo
    init.rs / migrate.rs / badge.rs -- license adoption tooling (any SPDX id)

  plasma-engine/                    -- the policy engine (depends on plasma-parser)
    src/ast.rs                      -- Policy AST: subjects, resources, conditions,
                                       modalities, actions, overlays
    src/schema.rs                   -- versioned TOML/JSON loading; load-time rejection
    src/facts.rs                    -- fact collection (the only impure module)
    src/eval.rs                     -- pure, total evaluator (deontic matrix)
    src/finding.rs                  -- findings, severities, evaluation summary
    src/report/                     -- human + SARIF renderers
    policies/repo-hygiene.plasma.toml  -- bundled, self-applied policy

  plasma-parser/                    -- license/SPDX machinery
    src/spdx/                       -- lexer, recursive-descent parser, catalog
    src/family/                     -- license family types, registry, fallbacks
    src/zone/                       -- .plasma.toml zones, file→zone assignment
    src/audit/                      -- header extraction, scan_repo, content detection
    src/compat/                     -- license compatibility matrix
    src/report/                     -- RepoAudit JSON/SARIF

  tests/check_selftest.rs           -- the repo checks itself with its own policy
  docs/engine-v0-design.adoc        -- NORMATIVE semantics + Catala-readiness

4. Data Flow

 policy file (TOML/JSON)      repository tree
        │                            │
   schema.rs load              facts.rs collect        (impure boundary)
   + validation                (files, SPDX headers,
        │                       metadata, git HEAD)
        ▼                            ▼
        └────────► eval.rs evaluate ◄┘               (pure, total)
                       │
                       ▼
                  Evaluation
              (ordered findings + summary)
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
     human          JSON           SARIF 2.1.0
   (terminal)   (interchange)   (Code Scanning,
                                 sibling tools)

The action planner (findings → corrective actions, plasma fix) is roadmap v0.3 and will sit between Evaluation and a new apply/dry-run surface; see ROADMAP.adoc.

5. Schema Versioning

Every policy document carries a mandatory schema_version, checked before anything else. The engine implements exactly one schema version at a time (currently 0.1); documents written against other versions are refused with a distinct error rather than reinterpreted. Reserved constructs let the format grow without breaking loaders: they parse today, are rejected by validation, and gain semantics in the version that can honour them.

6. Related Projects

  • somethings-fishy (planned) — forensic investigation of bot-inflicted damage; consumes plasma findings and provenance.

  • did-you-actually-do-that (planned) — verifies agents did what they claimed; consumes plasma facts snapshots (diffable before/after) and pass-findings (positive evidence).

  • Palimpsest license (PMPL) — a separate future project. plasma-parser recognises its SPDX identifiers; nothing more.

7. Historical Note

Earlier revisions of this document described an OCaml implementation (src/core/*.ml) that was never built. The typed design survives — policy-ast-v0.1.adoc is its lineage — and the policy format is specified (engine-v0-design.adoc) so a future OCaml/Catala formal core can implement the same semantics and be verified against this engine.