fix: prevent metadata entity ID collisions for repeated CIDs in one transaction

[Jay-Gould7]

Summary

Prevent IPFS metadata entity ID collisions when multiple events in one transaction reference the same CID.

The existing ID is transactionHash:cid, while each file data source carries an agent- or feedback-specific context. For example, two registrations for different agents in one transaction can create distinct file data sources that both write an immutable AgentRegistrationFile with the same ID. This can stop indexing with:

database constraint violated: duplicate key value violates unique constraint "agent_registration_file_id_key"

The feedback path uses the same ID construction and has the same collision risk. The observed deployment error specifically concerned registration files.

Changes

• Use transactionHash:logIndex:cid in handleAgentRegistered, handleUriUpdated, and handleNewFeedback.
• Pass the complete fileId through the file data source context; both file handlers consume it instead of independently rebuilding an ID.
• Keep chain entity links and file entity IDs consistent, retaining immutable file entities and independent agent/feedback ownership.
• Add eight focused regression tests and document the ID format, test limitations, and reindex requirement.
• Ignore generated Matchstick test binaries.

No registry addresses, network configuration, start blocks, reputation features, or analytics logic are changed. Agent and Feedback IDs and the existing data-URI file ID format are unchanged.

Validation

• Before the fix: eight new regression tests failed; the existing sanity test passed.
• After the fix: all nine tests passed using Matchstick 0.6.0 under WSL/Linux.
• npm run validate passed.
• npx --no-install graph codegen deployments/generated/erc-8004-eth-sepolia/subgraph.yaml passed.
• npx --no-install graph build deployments/generated/erc-8004-eth-sepolia/subgraph.yaml passed for all four mappings.
• git diff --check passed.

The regression cases cover registrations sharing a CID, repeated URI updates, registration plus URI update in one transaction, shared-CID feedback events, different transactions with the same log index, and both parsers consuming opaque context IDs.

Test limitations

Matchstick 0.6 cannot serialize the production analytics Int8/Timestamp values. These focused tests therefore use an unsupported mock network (chain ID 0), which skips the existing analytics branch without modifying production code. File contexts are supplied explicitly because Matchstick does not schedule IPFS templates. These are handler/parser tests, not PostgreSQL uniqueness, asynchronous file scheduling, or aggregation tests.

The tests reproduce the ID collision mechanism with synthetic events; they do not claim to reconstruct the exact historical transaction that triggered the deployment error.

Sepolia deployment observation

Our Studio deployment based on upstream 909a9d4518432c641e06fdb731b480fb0e9340dd stopped with the duplicate registration-file key error above. Its recorded fatal-error block was 10429684.

After deploying this fix as a new version and reindexing, the deployment passed that block and reached the chain head. On 2026-09-07, the indexer status API reported:

{
  "subgraph": "QmadC5SMGW53ucHqrDSgVLJPaSzDNnTZsFn3TodaUiVTYV",
  "synced": true,
  "health": "healthy",
  "fatalError": null,
  "latestBlock": "11654483",
  "chainHeadBlock": "11654483"
}

Queries for _meta, agents, and feedbacks also succeeded, with _meta.hasIndexingErrors = false.

This is evidence from our own deployment. We have not confirmed whether any official Agent0 deployment failure has the same cause.

Compatibility

IPFS AgentRegistrationFile.id and FeedbackFile.id change format. Deploy as a new version and reindex; existing indexed IDs are not migrated in place. Consumers that persist or construct file IDs must account for the new format. The Agent.registrationFile and Feedback.feedbackFile links continue to point to their corresponding file entities.