feat(calibration): attestation-evidence envelope schema, validator, and report-data binder

[michiot05]

Summary

• Closes calibration: attestation-evidence envelope — schema, pure structural validator, and report-data binding helper #8541 (attested-evaluation epic): adds the pure typed evidence seam packages/loopover-engine/src/calibration/attestation-envelope.ts — a schema type, a deterministic report-data binder, and a never-throwing structural validator — so a later runner can attach "this run executed inside an attested TEE" evidence to a persisted backtest run without inventing an ad-hoc shape. Pure structural code only: no cryptographic verification, no IO, no new dependency, no src/** change, no change to any existing calibration module.
• type AttestationEnvelope (+ the AttestationVerification discriminated union) with every field constraint the issue specifies: schemaVersion: 1 literal, teeTechnology "sev-snp" | "tdx", non-empty runtimeClass ≤128, 32–128-hex measurement, exactly-64-hex reportData, non-empty base64 attestationReport ≤65536, and a verification union of unverified / verified / failed.
• buildAttestationReportData({corpusChecksum, headSha, baseSha}) → lowercase-hex sha256 of ${corpusChecksum}:${headSha}:${baseSha} via node:crypto, mirroring backtest-split.ts's existing sha256 usage (no new dependency).
• validateAttestationEnvelope(value: unknown) → {valid,envelope} | {valid,errors} — structural validation of every field/constraint; never throws for any input (null, primitives, arrays, objects with extra keys — extra keys are rejected, naming the key); errors accumulates every failing field path in one pass. ISO-8601 verifiedAt is checked by shape (regex) and real-calendar validity (Date.parse), so a well-shaped but impossible datetime is still rejected.
• One barrel line in packages/loopover-engine/src/index.ts (export * from "./calibration/attestation-envelope.js";), matching the existing calibration export lines.

Tests

Two suites, per the epic's "engine blind-spot rule" the issue cites (#8438):

• packages/loopover-engine/test/attestation-envelope.test.ts — the node:test suite gating the engine workspace's own npm run test (all 719 engine tests pass).
• test/unit/attestation-envelope-engine.test.ts — the root vitest mirror importing the engine src path directly, which provides codecov/patch coverage (the engine's node:test output isn't harvested to Codecov). Exercises both arms of every rule — 63/64/65-char reportData, 31/32/128/129 measurement boundaries, hex-vs-non-hex-vs-non-string, empty/too-long/non-base64 attestationReport, each union variant valid + each with a missing/invalid member (incl. a regex-valid-but-unparseable datetime), valid-then-extra-key, and the never-throws guarantee on non-object inputs — plus buildAttestationReportData pinned against a precomputed vector. 100% of new lines and branches, verified locally via lcov (34/34 lines, 0 missed branches).

Scope

• Conventional Commit title; focused; follows CONTRIBUTING.md; no site//CNAME.
• Linked a currently open issue (Closes #8541).

Validation

• git diff --check
• npm run typecheck
• npm run test:coverage locally (100% patch coverage on the new file, verified via lcov)
• @loopover/engine build + its 719-test node:test suite
• npm run test:engine-parity, npm run engine-parity:drift-check, npm run docs:drift-check

If any required check was skipped, explain why:

• This change is exactly one pure, self-contained new engine file, one additive barrel-export line, and two test files. It touches no API/OpenAPI, migration, generated artifact, command, setting, UI, worker, or dependency, so the remaining test:ci steps cannot be affected by it. Engine was rebuilt (a stale dist otherwise breaks whole-repo typecheck), typecheck is clean, and engine build/tests + engine-parity + drift checks + the unsharded coverage run all pass.

Safety

• No secrets, wallets, hotkeys, trust scores, or reward values anywhere.
• No cryptographic verification implemented (structural only, per the issue boundary); the attestationReport blob is treated as opaque.
• API/OpenAPI/MCP behavior unchanged.

UI Evidence

Not applicable — a pure calibration-engine module with no visible UI, frontend, docs, or extension change.

Notes

• Foundation-only, per the issue boundary: no consumer wired yet, no crypto verification, no src/** change. validateAttestationEnvelope collects all field errors rather than short-circuiting, so a caller sees every problem at once.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

❌ 3 Tests Failed:

Tests completed	Failed	Passed	Skipped
21471	3	21468	21

View the top 3 failed test(s) by shortest run time

test/unit/rag-index.test.ts > indexRepo: MAX_CHUNKS_PER_REPO cap holds > still indexes package.json (and other root manifest/config files) on a repo whose file count exceeds the cap (regression: manifestPriority)

Stack Traces | 37.7s run time

Error: Test timed out in 15000ms.
If this is a long-running test, pass a timeout value as the last argument or configure it globally with "testTimeout".
 ❯ test/unit/rag-index.test.ts:530:3

test/unit/rag-index.test.ts > indexRepo: MAX_CHUNKS_PER_REPO cap holds > stops upserting once the per-repo cap is reached

Stack Traces | 40.3s run time

Error: Test timed out in 15000ms.
If this is a long-running test, pass a timeout value as the last argument or configure it globally with "testTimeout".
 ❯ test/unit/rag-index.test.ts:511:3

test/unit/rag-index.test.ts > reindexChangedPaths: delete + re-upsert only the changed paths > caps incremental reindex upserts at MAX_CHUNKS_PER_REPO

Stack Traces | 46.7s run time

Error: Test timed out in 15000ms.
If this is a long-running test, pass a timeout value as the last argument or configure it globally with "testTimeout".
 ❯ test/unit/rag-index.test.ts:735:3

To view more test analytics, go to the Test Analytics Dashboard
_{📋 Got 3 mins? Take this short survey to help us improve Test Analytics.}

[loopover-orb]

Caution

🛑 LoopOver review result - fixes required

_{Review updated: 2026-07-24 20:14:28 UTC}

4 files · no blockers · CI failing · blocked

🛑 Suggested Action - Fix Blockers

• AI review already in progress for this PR head: Another LoopOver pass is already running the AI review for this exact PR head. This pass is skipping to avoid a duplicate LLM call.

Review summary
AI review is already running for this PR head in another LoopOver pass. LoopOver is holding this PR for manual review until that pass completes.

Nits — 1 non-blocking

• AI review already in progress for this PR head — The gate is held for a human reviewer rather than passed automatically; it re-evaluates once the in-flight review completes or on the next update.

CI checks failing

• validate
• validate-tests

Decision drivers

• ✅ Code review — No blockers (No AI review summary)
• ⚠️ Gate result — Not blocking (Advisory; not blocking this PR.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#8541
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 35 registered-repo PR(s), 18 merged, 5 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	michiot05; Gittensor profile; 35 PR(s), 5 issue(s).
Improvement	✅ Minor	risk: clean · value: minor

Linked issue satisfaction

Addressed
The PR adds exactly the three required exports in the new attestation-envelope.ts file with all specified field constraints, adds the single barrel line in index.ts, and includes both a node:test suite and a vitest mirror (following the #8438 precedent) that exercise boundary cases, union variants, extra-key rejection, never-throw behavior, and a pinned buildAttestationReportData vector.

Review context

• Author: michiot05
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Rust
• Official Gittensor activity: 35 PR(s), 5 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[loopover-orb]

LoopOver is closing this pull request on the maintainer's behalf (CI is failing (validate, validate-tests)). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.