Served Content-Type is nondeterministic when multiple _attachment records share a fileId — make mimeType a property of the bytes

[cuibonobo]

Problem

Multiple _attachment@1 records per fileId is intentional and stays: different uploaders remember the same file under different names, and the metadata record is each uploader's perspective (the spec already leans into this — the download path serves the filename from the requester's own metadata record, spec §Attachments). This issue does not change that.

The defect is that one field in that record is not a perspective. filename is a memory aid for a human; mimeType is an instruction to the client about how to execute the bytes — text/html parses and runs a document on the serving origin, image/png renders pixels, application/octet-stream downloads inert. Two records disagreeing about filename is healthy pluralism; two records disagreeing about mimeType means someone is wrong, and today the server has no rule for who.

Mechanics: every putAttachment() creates a fresh metadata record with the uploader's declared type (packages/core/src/stack.ts:604–613), and content-addressing maps identical bytes to the same fileId (spec: "uploading identical bytes twice returns the same fileId") — so a second uploader doesn't create a second file, they attach a second, possibly contradictory, execution claim to the first uploader's bytes. The no-param download path then reads "the stored mimeType" (spec §Attachments) — which record is unspecified, so it varies with sort order and, since metadata records carry their own permissions, with who's asking.

Failure modes:

1. Nondeterminism among honest uploaders. The same file uploaded as text/markdown by one person and text/plain by another → which one a browser receives depends on record ordering; any HTTP cache in between pins one answer and serves it to everyone.
2. Escalation with one dishonest uploader. A requester with a create grant on _attachment@1 takes bytes someone else already stored (an image referenced from a shared record), uploads the identical bytes, declares text/html. No write access to any referencing record was needed — dedup attached the claim for them. Polyglot files (simultaneously valid PNG and valid HTML — a standard construction) make the payload real: if the server's arbitrary pick lands on the attacker's record, a stored "image" is served as an executable document on the stack's origin, scripts and all. Composes with the header-forcing gaps (companion issue, filed next).

Decided direction

Split the record's fields by what kind of fact they are:

1. mimeType is a property of the fileId: first-recorded wins for serving. The first _attachment@1 record created for a fileId fixes the served Content-Type. Later same-bytes uploads still create their own metadata records (filename, uploader attribution, size) — but a conflicting mimeType is rejected with StackValidationError (422) rather than stored-and-ignored: a contradictory execution claim shouldn't survive in the data to confuse the next reader. A matching type is fine.
2. Enforcement lives in record validation, not just the convenience method. The spec's upload flow creates metadata via plain POST /records (§Attachments, "Upload"), so the check must run wherever an _attachment@1 record is created or updated: look up existing metadata for the same content.fileId (exhaustive per Core code treats one query() page as the complete result set (grants, attachment metadata, uploader checks) #50) and compare mimeType. putAttachment() gets it via the same path.
3. filename stays per-perspective — the spec's requester's-own-record rule is affirmed as-is, falling back to the first record's filename.
4. Legitimate type choice survives via the existing explicit ?contentType parameter (subject to dangerous-type forcing) — determinism removes the arbitrary pick, not the requester's ability to ask.
5. First-recorded can still be a lie — deliberately out of scope here; the companion header-forcing issue is the backstop that makes a lie inert.

Work items

• Validation hook: _attachment@1 create/update rejects conflicting mimeType for an existing fileId (core + reaches the server via ordinary record validation; 422 per APIAdapter collapses the error taxonomy: Stack* errors never survive the wire round trip #53)
• Spec §Attachments: "first-recorded mimeType is served"; conflict-rejection rule; filename perspective rule affirmed
• Conformance fixture (PATCH contract mismatch: spec defines content-only merge patch, APIAdapter sends record-field envelopes #52): second upload with conflicting type → 422; with matching type → OK; served Content-Type stable regardless of requester
• Tests incl. the multi-uploader filename case (both requesters download under their own name; same Content-Type)

Refs #50 (exhaustive metadata lookup), #52 (fixtures), #53 (error round-trip), #51 (the create-grant threat actor this defends against), companion header-forcing issue (backstop).

[cuibonobo]

From the server-side sync review (haverstack/server#41): this issue protects one of the three physical-fact fields on _attachment@1 — mimeType — and leaves the other two, fileId and size, with no core-level protection.

Both are properties of the bytes in exactly this issue's sense, arguably more strictly than mimeType (size is derivable from the bytes; fileId is their identity). Mutating fileId severs the metadata record from its blob — download and delete both resolve through it; a wrong size corrupts the served Content-Length, which truncates or hangs HTTP clients. Today the only guard anywhere is a route-level check in haverstack/server (src/routes/records.ts:228-239, from haverstack/server#9) rejecting PATCHes to those fields — a per-server convention of precisely the kind the layering principle (#67, #68) says should be a core invariant written once.

Proposal: extend this issue's validation hook to reject any update that changes fileId or size on an _attachment@1 record (StackValidationError, 422 per #53), leaving filename as the only mutable — i.e. perspective — field. The server's route guard then gets deleted per the haverstack/server#41 cleanup, and adapter-local consumers inherit the protection they currently don't have.

---

Generated by Claude Code

[cuibonobo]

Adopted — this is the properties-vs-perspectives principle applied to the whole record rather than one field, and the server's route-level guard (haverstack/server src/routes/records.ts:228–239) is exactly the per-server-convention-that-should-be-a-core-invariant pattern #67 names. Folding into this issue's validation hook:

_attachment@1 update rule: filename is the only mutable field. fileId and size are immutable as proposed (StackValidationError, 422 per #53). And for symmetry, mimeType becomes immutable post-create too — its create-time value already had to match the established type per this issue's rule, so allowing a matching-only update is a no-op with extra steps, and allowing anything else contradicts first-recorded-wins. Genuine correction flow (everyone declared the wrong type): owner deleteAttachment + re-upload — identical bytes yield the same fileId, and the fresh first record establishes the corrected type.

The server's route guard gets deleted once this lands (per haverstack/server#41), and adapter-local consumers inherit protection they currently lack.

---

Generated by Claude Code