Lotus Family v0.2: trusted materializer and repository onboarding

[safal207]

Purpose

Move Lotus Family from auditing caller-supplied snapshots to producing a reproducible snapshot from a verified repository and exact commit, while keeping all results advisory and non-consequential.

This is the next slice after #230 / PR #231.

Problem

v0.1 proves which supplied bytes were evaluated, but it intentionally does not prove that those bytes came from the claimed remote repository, ref, or commit.

A v0.2 result must distinguish:

• caller_claim_only — repository/ref/SHA are supplied claims;
• trusted_materialization — the integration resolved and checked the repository, commit, tree, and clean snapshot;
• UNKNOWN — provenance could not be established.

First implementation scope

Pilot only in safal207/pythiaLabs before enabling CML, LS, or additional repositories.

Trusted materializer

• Accept an allowlisted repository identity and exact 40-character commit SHA.
• Resolve the remote repository without executing repository code.
• Verify that the commit exists and is reachable under the allowed repository.
• Record the resolved commit SHA and tree SHA.
• Materialize a clean read-only snapshot.
• Reject symlink escapes, submodule ambiguity, path traversal, dirty state, and identity mismatch.
• Hash the same bytes later consumed by the auditor.
• Emit deterministic materialization metadata.
• Never merge, deploy, approve, deliver, or execute repository-owned code.

Evidence record

The evidence bundle should include at minimum:

• repository identity;
• requested ref and commit;
• resolved commit and tree SHA;
• materializer version;
• materialization timestamp;
• checked paths and SHA-256 values;
• provenance assurance level;
• explicit limitations;
• authority boundary.

Repository onboarding contract

A repository may join Lotus Family only when it defines:

1. an allowlisted repository identity;
2. a canonical Lotus contract in English and Russian;
3. the exact regression test protecting that contract;
4. the CI workflow/job/step expected to execute the test;
5. required and forbidden authority terms;
6. adapter-owned paths and test commands;
7. a fail-closed outcome for inaccessible or ambiguous evidence;
8. a human owner for acceptance decisions.

Candidate scoring

Evaluate each candidate repository on:

• contract maturity;
• exact-head evidence maturity;
• CI determinism;
• parser/adapter complexity;
• exposure to untrusted code execution;
• usefulness to the wider family;
• maintenance ownership.

Recommended order:

Pythia pilot → CML → LS → one external candidate at a time.

Acceptance criteria

• A snapshot cannot receive provenance-backed PASS from caller claims alone.
• Repository identity mismatch returns UNKNOWN, never PASS.
• Missing/unreachable commit returns UNKNOWN, never fallback-to-branch behavior.
• The recorded tree and file hashes correspond to the exact bytes audited.
• Materialization does not execute hooks, build scripts, tests, workflows, or repository binaries.
• Dirty, incomplete, escaped, or ambiguous snapshots fail closed.
• Evidence explicitly states that PASS != APPROVED != MERGED.
• Existing v0.1 caller-supplied mode remains supported and clearly labeled.

Threat fixtures

• repository URL points to a different owner/project;
• ref resolves to a different commit than requested;
• commit does not exist;
• shallow history hides reachability;
• symlink escapes snapshot root;
• submodule points outside the allowlist;
• file changes between hashing and evaluation;
• malicious Git hook or smudge/filter configuration is present;
• snapshot contains untracked or modified files;
• network or permission failure occurs mid-materialization.

Safe sequence

specification → threat fixtures → read-only Pythia adapter → local deterministic materializer → same-byte audit binding → CI integration → exact-head review → staged CML/LS adoption → external repository pilot

Authority boundary

The materializer and auditor provide evidence and advisory judgments only. They grant no ownership, approval, execution, delivery, deployment, or merge authority.