Dotrain source subject is derived two ways: generate emits under keccak(cbor item map) while DotrainSourceV1::hash and the subject field docs say keccak(content)

[thedavidmeister]

Unit

CLI generate subcommand + metaboard emit tx-data (crates/cli/src/metaboard.rs, crates/cli/src/meta/types/dotrain/source_v1.rs) — AMT group g5-interpretercallermeta-v1.

Intent oracle

• DotrainSourceEmitData.subject doc comment (crates/cli/src/metaboard.rs): "Keccak256 hash of the content (hex-encoded with 0x prefix)".
• DotrainSourceV1::hash() doc comment (crates/cli/src/meta/types/dotrain/source_v1.rs): "Returns the hash of the dotrain source code" — implemented as keccak256(self.0.as_bytes()), i.e. hash of the raw content.
• IMetaV1_2 NatSpec (src/interface/unstable/IMetaV1_2.sol): subject "will often be a hash of some data/thing that this metadata is about" — interpretation is context specific, so the crate's own convention is the oracle for the dotrain-source context.

Observed behaviour

generate_dotrain_source_emit_tx_data derives subject as document.hash(false) = keccak256 of the CBOR-encoded meta item map (payload + magic + contentType + ...), NOT keccak256 of the raw source content.

So the same crate exposes two different subject derivations for the same dotrain source:

1. emit half (rain-metadata generate source / generate_dotrain_source_emit_tx_data): keccak256(cbor_encode(item))
2. fetch half (DotrainSourceV1::hash() + DotrainSourceV1::fetch_by_subject(subject, url)): the only hash the type itself offers is keccak256(content)

A consumer that computes DotrainSourceV1::hash(&source) and calls fetch_by_subject with it will never find a meta published via the generate flow, because that meta was emitted under the item-map hash.

Violated property

Content-addressable round-trip within one crate: subject(emit) == subject(fetch key) for the same source content; and doc/impl agreement for DotrainSourceEmitData.subject.

Verified repro

let content = "#main _ _: int-add(1 2) int-add(2 3)";
let tx = generate_dotrain_source_emit_tx_data(content).unwrap();
let content_hash = alloy::primitives::hex::encode_prefixed(DotrainSourceV1(content.to_string()).hash());
assert_ne!(tx.subject, content_hash); // passes today: the two subjects differ

Concrete values for content = "#main _ _: int-add(1 2) int-add(2 3)" (from the built CLI at bba50a7):

• generate flow subject (keccak of cbor item map): 0xaeb47b040e0c281065bdaed6a3c81284c6ad0be63eed471b3b75dd5672c1c68e
• DotrainSourceV1::hash / keccak256 of the raw content: 0x55d083bf6ee7d68b9f5f9138c1f0c7d42a906fd079efe2825fe6a4d80329e104

A fetch_by_subject(0x55d0…) lookup can never find the meta emitted under 0xaeb4….

Triage framing (neutral)

Either derivation may be the intended convention:

• If "subject = keccak256 of the raw content" (as the field doc and DotrainSourceV1::hash say) is intended, the generate flow emits under the wrong subject and DotrainSourceEmitData.subject's value is mislabeled.
• If "subject = keccak256 of the CBOR item map" (document.hash(false)) is intended, then the DotrainSourceEmitData.subject doc comment is wrong and DotrainSourceV1::hash() is a footgun as the natural-looking key for fetch_by_subject.

Not adjudicating which; flagging the inconsistency for triage. Existing tests only pin internal consistency (subject-in-calldata == subject field), not the cross-API convention.

[thedavidmeister]

Ruling: duplicate — resolved by #247

Verified against #247's actual head a8c66bbdd21fd522c2abb8fdf4d751442cec38df (branch
2026-08-25-issue-158), not its description. That head is the same defect filed from the
type side as #158, and its fix lands on the exact two files this issue names.

The change that resolves it

crates/cli/src/metaboard.rs in generate_dotrain_source_emit_tx_data:

-    // Hash before moving the document into the sequence to avoid cloning.
-    // Calculate subject hash
-    let subject_hash = document.hash(false)?;
+    let subject_hash = dotrain_source.hash();

DotrainSourceV1::hash() is keccak256(self.0.as_bytes()) — unchanged by #247. So the
emit subject on that head IS the raw-content digest, i.e. the same quantity the fetch half
keys on. The subject reaches both the calldata and the returned field from that one
binding (metaboard.rs:54, :65, :68), so subject-in-calldata == subject field still
holds.

Each claim in this issue against that head

• "generate flow derives document.hash(false), not keccak256(content)" — gone; it
  is now dotrain_source.hash().
• "two subject derivations for the same source in one crate" — one derivation left.
  fetch_by_subject(DotrainSourceV1::hash(&source), url) now addresses metas emitted by
  the generate flow.
• "DotrainSourceEmitData.subject's doc is mislabeled" — the doc at metaboard.rs:28
  is untouched and still reads "Keccak256 hash of the content (hex-encoded with 0x
  prefix)". It is now accurate against the value, so there is nothing left to fix on that
  half. This issue's own triage framing named the two mutually exclusive remedies; fix: emit dotrain source metas under the content hash, not the cbor item hash #247
  takes the first ("subject = keccak256 of the raw content"), which is the branch under
  which the doc needs no edit.
• "existing tests only pin internal consistency, not the cross-API convention" — fix: emit dotrain source metas under the content hash, not the cbor item hash #247
  adds metaboard::tests::test_emit_subject_is_the_fetch_by_subject_key, which asserts
  deployment.subject == hex::encode_prefixed(DotrainSourceV1(content).hash()) AND
  != document.hash(false) over three contents, so it pins both directions. Separately
  test_generate_dotrain_source_emit_tx_data_success's subject pin is rewritten to an
  inline keccak256(content.as_bytes()) that routes through neither hash helper
  (metaboard.rs:152).
• Verified repro — this issue's assert_ne!(tx.subject, content_hash) is exactly what
  the new test inverts to assert_eq!. This issue's recorded pair for
  "#main _ _: int-add(1 2) int-add(2 3)" — item-map 0xaeb47b04… vs content
  0x55d083bf… — is the same pair fix: emit dotrain source metas under the content hash, not the cbor item hash #247's rewritten pin now resolves to the content side.

CI on a8c66bb: rainix-rs / test / rs-test passes on ubuntu and macos, so both of those
tests pass in execution on that head, not only on paper.

Not acting further

No second PR on crates/cli/src/metaboard.rs; #247 owns that file. Two notes for whoever
merges it:

• fix: emit dotrain source metas under the content hash, not the cbor item hash #247 deliberately carries no closing keyword for this issue ("in case it is assigned
  elsewhere"), so this will not auto-close — close it on that merge.
• fix: emit dotrain source metas under the content hash, not the cbor item hash #247's red rainix-rs / static / rs-static is a rustfmt hook failing with "Failed to
  find targets", and the same check was already red on its base commit 6fe2e2b on main.
  Recent main runs are green, so it is a rebase/re-run away and is unrelated to this
  issue.

[thedavidmeister]

🤖 ai:vetter
Stranded flag cleared: the ai:close-candidate label was live with no trusted producer comment stating a claim. Nothing could judge it (there is no claim) and nothing could clear it, while the label kept the issue out of the producer's backlog. Removing the label returns the issue to the producer. NO ruling is made on the issue.

This discards whatever intent applied the label, which was never recorded. To park an issue durably, rule it: human-rule-issue <repo> <n> keep-open "…" or human-close <repo> <n> "…". Those are the human's namespace — sacred, and no AI actor clears them.