attest manifest: the integration facts, derived not transcribed

[mgoldey]

Why

agentmarkit consumes attestation as a first-class dependency of its academic-research-assistant starter, and had to hand-copy ~40 facts about it into its own repo — lab/docs/01-attestation-runtime-map.md in prose, plus lab/presets/research-attestation/preset.yaml. Entry points, the seven skill names, resolve_db_path's ladder, env var names including the legacy RSS_DB, and which capabilities survive without a model.

Hand-copied facts rot. Two are already wrong: their pin sits 81 commits stale, and HERMES_HOME is absent from the map entirely because it postdates the transcription by a day.

What

attest manifest prints JSON that attestation derives from itself:

{
  "schema": "attestation/manifest/1",
  "version": "0.2.0",
  "console_scripts": {"attest": "...", "attestation": "...", "attest-mcp": "..."},
  "mcp_servers": [{"name": "attest-mcp", "transport": "stdio", "verify": "attest install --check"}],
  "surfaces": {"feed": {...}, "provenance": {...}, "knowledge": {...}, "symbolic": {...}},
  "skills": ["attestation-annotate", "... 7 total"],
  "env": {"HERMES_HOME": {...}, "ATTEST_DB": {"legacy_alias": "RSS_DB"}, ...},
  "db_path_precedence": ["explicit --db", "ATTEST_DB, or RSS_DB", "...", "./hermes.db"],
  "degrades_without_model": {"still_works": [...], "unavailable": [...]}
}

Derived, never typed. Version and requires-python from installed metadata, console scripts from entry points, skills from the shipped directory, surfaces from AGENT_SURFACES. An eighth skill or a fifth surface needs no edit here — which is the point. emit.py's docstring already says it: "two copies of one fact with no check between them is the whole problem."

No credentials, by construction. agentmarkit's preset schema bans url/token/api_key/secret from an MCP declaration, on the rule that "a package declares that a server should exist; only the instance holds its address and its credential." That rule is right independently of who reads it, so the manifest says attest-mcp exists and how to verify it — never where it lives. test_manifest_declares_no_credentials asserts it.

Deliberately not a preset

Their schema needs 15 required keys and most are genuinely theirs — agent37 template digests, teardown_steps, profile_distribution, pricing-adjacent status. This feeds about six of them; a human writes the rest. attestation shouldn't know those keys exist.

Verified

• From an installed wheel, with no pyproject.toml and cwd outside the checkout — the actual packager case, where the importlib.metadata fallbacks carry version, scripts and the skill list. 7 skills, 4 surfaces, correct version.
• test_db_precedence_matches_resolve_db_path drives the real function rather than reading the tuple back, so the documented ladder cannot silently diverge from the code.
• 11 new tests. All eight gates pass.

One flake worth noting: test_every_output_block_of_an_offline_path_is_real[flows] failed once under full-suite load and passes in isolation both with and without this change — I checked against clean main before concluding it wasn't mine.

Note on timing

Nothing reads a source-published manifest today — export_starters.py reads only in-repo YAML, and sync_sources.py never opens a file inside a checkout. This is a producer ahead of its consumer. It is small and fully tested, but its value turns on agentmarkit reading it; the natural join point is sync_sources.py, where a pinned checkout already exists.

🤖 Generated with Claude Code