feat(engine): add the attestation-evidence envelope seam

[RealDiligent]

Summary

Adds the typed evidence seam the attested-evaluation epic needs before any TEE infrastructure exists, so the later runner work attaches evidence to backtest runs instead of inventing an ad-hoc object at the call site.

New file packages/loopover-engine/src/calibration/attestation-envelope.ts exporting exactly three things:

• AttestationEnvelope — schemaVersion: 1 (literal), teeTechnology: "sev-snp" | "tdx", runtimeClass (non-empty, ≤128), measurement (lowercase hex, 32–128), reportData (lowercase hex, exactly 64), attestationReport (base64, non-empty, ≤65536), and a discriminated verification union (unverified / verified / failed).
• buildAttestationReportData(binding) — lowercase-hex sha256 of `${corpusChecksum}:${headSha}:${baseSha}` via node:crypto, mirroring backtest-split.ts's existing createHash usage. No new dependency.
• validateAttestationEnvelope(value) — structural validation returning { valid: true, envelope } or { valid: false, errors }, naming each failing field path. Never throws for any input — null, primitives, arrays, Symbol, BigInt, and objects with extra keys all return a result. Extra keys are rejected by name rather than ignored, since this is persisted evidence and silently dropping an unrecognized field would lose data a future schemaVersion may depend on.

Plus one barrel line in packages/loopover-engine/src/index.ts, matching the existing calibration exports.

Scope held exactly to the issue's boundary: structural validation only — no cryptographic verification of the attestation report, no src/** wiring, no new dependencies, and no changes to any existing calibration module. Verifying a TEE vendor's signature chain / measurement allow-list / report freshness is later maintainer work in the parent epic; implementing any of it here would bake a verification policy into what is meant to be a transport shape.

Coverage

100% of the new module — lines, statements, functions, and branches (vitest json-summary, the authoritative reporter):

metric	result
lines	100% (54/54)
statements	100% (60/60)
functions	100% (4/4)
branches	100% (62/62)

Every rule is exercised on both arms as the issue requires — accept at the boundary, reject just past it: runtimeClass 128 vs 129; measurement 32/128 vs 31/129, plus uppercase-hex and non-hex; reportData 64 vs 63/65; attestationReport at the 65536 cap vs 65537, empty, and non-base64; each verification variant valid, and each with a missing/empty/invalid member; a valid envelope plus an extra key. buildAttestationReportData is pinned against a precomputed vector (sha256("abc123:head456:base789")) so a change to the binding format — which would silently invalidate every previously-attested run — fails here rather than shipping.

Coverage is Codecov-visible via the root-vitest mirror (test/unit/attestation-envelope-engine.test.ts) importing the engine source path directly — the same seam #8438 used for signal-tracking.ts, since the engine's own node:test suite runs against dist/ and is invisible to Codecov. The companion packages/loopover-engine/test/attestation-envelope.test.ts gates the engine workspace's own npm run test against the built barrel.

Closes #8541

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked a currently open issue this PR resolves (e.g. Closes #123) — a linked open issue is required for every contributor PR.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally; codecov/patch requires ≥99% coverage of the lines AND branches you changed (aim for 100% on your diff so CI variance does not fail near the threshold). Global coverage is a non-blocking trend with a loose 90% backstop, not the gate.
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

If any required check was skipped, explain why:

• One new engine module + one barrel line + two test files. No workflow, MCP, UI, worker, or dependency surface is touched, so actionlint, build:mcp/test:mcp-pack, ui:*, test:workers, and npm audit are not exercised by it.
• Verified locally: root tsc --noEmit clean, engine tsc -p packages/loopover-engine/tsconfig.json clean, the root vitest mirror passes (17 tests), the engine node --test twin passes (4 tests) against a fresh npm run build --workspace @loopover/engine, and git diff --check is clean.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks.
• Visible UI changes include a UI Evidence section below with JPG/JPEG or PNG screenshots arranged as organized, captioned, clickable thumbnails. SVG screenshots are not used as review evidence. Review-only screenshots or recordings are not committed to the repository.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

UI Evidence

Not applicable — a pure engine module and its tests; no visible UI, frontend, docs, or extension change.

Notes

• verifiedAt is validated by shape and parseability: Date.parse alone accepts a bare "2026-07-25" and other implementation-defined forms, while the ISO regex alone would accept "2026-13-45T99:99:99Z". Both operands are covered by tests.
• The envelope is a transport shape only: nothing in this PR reads, writes, or persists it, so there is no behavior change to any existing run.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.51%. Comparing base (ec6f6e6) to head (92a9093).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #8551   +/-   ##
=======================================
  Coverage   92.51%   92.51%           
=======================================
  Files         794      795    +1     
  Lines       79551    79607   +56     
  Branches    24036    24055   +19     
=======================================
+ Hits        73593    73645   +52     
  Misses       4800     4800           
- Partials     1158     1162    +4     

Flag	Coverage Δ
backend	93.67% <100.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...ver-engine/src/calibration/attestation-envelope.ts	100.00% <100.00%> (ø)

... and 1 file with indirect coverage changes

[superagent-security]

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

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

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

4 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds a pure, well-scoped structural validation module for a TEE attestation envelope shape, plus a hash-binding helper mirroring an existing pattern (backtest-split.ts's createHash usage). The validator never throws, names every failing field path, rejects unrecognized keys by design, and is exercised by two thorough test suites (a vitest src-path mirror for codecov, and a node:test barrel check against dist) covering boundary conditions on every bounded field and both arms of the verification union. The module is not wired into any src/** call site yet, matching its stated 'seam before infrastructure' scope, and the barrel export is a single additive line consistent with the existing calibration exports.

Nits — 5 non-blocking

• The ISO_DATETIME regex plus Date.parse double-check in validateVerification (attestation-envelope.ts:~93-95) is a bit dense — a short comment already explains the rationale, but consider extracting a small `isIsoDatetime` helper for readability.
• MEASUREMENT_MIN_HEX (32) and the issue reference embedded in a comment (Research: is TEE hardware attestation necessary, or does a reproducible-backtest checksum approach cover the real threat? #8136) are magic/contextual values with no named constant beyond the existing MEASUREMENT_MIN_HEX — the numeric bound is fine as named already, this is a very minor readability nit.
• validateVerification's status-narrowing branch (attestation-envelope.ts:~82-99) reaches moderate nesting depth; could flatten slightly by returning early per status, though current structure is still readable.
• The CI FAILED checks (validate, validate-tests) have no detail provided; given this branch is 1 commit behind the default branch, this is plausibly caused by a base-branch drift rather than a defect in this diff — worth confirming with a rebase rather than assuming a content issue.
• Consider extracting the ISO datetime shape+range double-check into a small named helper for reuse if more datetime fields are added later.

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

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: 370 registered-repo PR(s), 154 merged, 37 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	RealDiligent; Gittensor profile; 370 PR(s), 37 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: moderate

Linked issue satisfaction

Addressed
The diff adds exactly the three required exports in attestation-envelope.ts (AttestationEnvelope type, buildAttestationReportData, validateAttestationEnvelope) with all specified field constraints, adds the single barrel line in index.ts, and includes both a package-native test and a root-vitest mirror (following the #8438 pattern) that exercise boundary cases, union variants, extra-key rejection,

Review context

• Author: RealDiligent
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, Ruby, TypeScript, Svelte, Cuda, JavaScript, Markdown, MDX
• Official Gittensor activity: 370 PR(s), 37 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 approves — the gate is satisfied and CI is green.