capability publish doesn't require/validate the contract's artifact field, so a real, human-mergeable PR can produce an unusable index entry

[enricopiovesan]

What's wrong

A capability's contract.json needs a top-level artifact: {digest, url} field for the capability to be usable at all -- traverse-framework/registry's own scripts/ci/build_index.py reads contract.get("artifact") or {} and copies digest/url straight into the published index record (verified directly: capabilities/<ns>/<id>/<ver>/contract.json -> index.json's digest/artifact_url fields). If a contract has no artifact field, the index entry silently gets digest: null, artifact_url: null -- a capability that appears in registry sync's output but has no way for any consumer to actually fetch its WASM binary.

traverse-cli capability publish doesn't require this field at all: parse_contract/validate_contract accept a contract with no artifact key (verified -- a real contract missing it passed --dry-run and a real publish with validation_status: "passed", traverse-framework/registry#89's first attempt). Registry's own scripts/ci/capability_validation.py also treats it as fully optional (artifact = contract.get("artifact"); if artifact is not None: ... -- the whole check is skipped when the field is absent). Nothing in the real, automated path stops a syntactically-valid, CI-green, human-mergeable PR from publishing a capability that's structurally unusable.

This isn't hypothetical -- it was hands-on reproduced this session authoring validation.validate-email: the contract validated and dry-ran cleanly with no artifact field, and the gap was only caught by separately reasoning through build_index.py's source (not by anything in the actual publish pipeline surfacing it).

Definition of Done

• capability publish requires an artifact.digest/artifact.url in the contract before allowing a non-dry-run publish (or, if there's a reason artifact-less contracts are meant to be valid for some other reason, that needs to be an explicit, documented decision -- not silence).
• If a real reason exists for the field staying schema-optional, capability_validation.py (registry-side) should fail loudly, not skip silently, when a contract lacks it -- matching the precedent already set for corrupt/unreadable contracts in build_index.py (registry decision-log entry 27: "a silently-dropped record is the same failure class... as an unverifiable record reaching a consumer").
• Whatever the fix, verify it actually blocks an artifact-less contract from reaching a green, mergeable PR -- not just that a unit test asserts the right error type.

Where this was found

traverse-framework/registry#89, first publish attempt of validation.validate-email -- the initial dry-run/publish succeeded with "validation_status": "passed" despite the contract having no artifact field. Fixed for that specific PR by manually adding the field before the real (non-dry-run) publish, but nothing in the tooling would have caught it if the author hadn't independently checked build_index.py's source.

[enricopiovesan]

Update: this is worse than originally described, and caused a real production incident

Confirmed by reading crates/traverse-contracts/src/lib.rs directly: CapabilityContract has no artifact or artifact_type fields at all. This isn't just "the field isn't validated" -- capability_publish_plan() deserializes the input contract into this struct and then re-serializes the struct itself (contract_json = serde_json::to_string_pretty(&normalized)) to produce the file that actually gets written to the registry. Any field not modeled by the struct -- including artifact, artifact_type, and likely others -- is silently dropped, even when the author correctly supplied it in their source contract. This isn't a missing-validation edge case; it is 100% reproducible on every capability publish call, always, regardless of what the author does right.

Real incident caused by this, this session: traverse-framework/registry#89 and #90 both published with correct, complete source contracts (verified: I read my own source file immediately before calling capability publish, artifact field present). Both came out the other end with the field stripped. build_index.py then copied contract.get("artifact") or {} into index.json, producing digest: null, artifact_url: null -- which fails Rust-side deserialization for any consumer running registry sync, not just for these two capabilities (the whole index fails to parse once it hits either null record). Fixed via traverse-framework/registry#92 (deprecate + republish both at 1.0.1 with the field manually restored) and #91 (caught before merge, same fix applied directly to the PR branch).

This will recur on every single future capability publish call until fixed -- not a corner case worth deprioritizing.

Revised Definition of Done

• CapabilityContract (or the publish path specifically) preserves artifact/artifact_type through the normalize-and-rewrite round trip -- either by adding these fields to the struct properly, or by having capability_publish_plan merge them back into the normalized JSON from the original input rather than relying on the struct to carry everything.
• Regression test: author a contract with artifact set, run it through capability_publish_plan, assert the resulting contract_json still has it. This exact case had zero test coverage, which is how it shipped.
• Once fixed, verify no other fields are silently dropped the same way -- artifact/artifact_type were caught by luck (a downstream consumer-side crash), not by anything in the publish path itself surfacing the loss.