Module pins 

Pins — CORD-04 §7. A pin does not quote a message; it proves one.

One Pin List per Channel on the Control Plane (vsk 11, coordinate pins_locator(community_id, channel_id)), replaced entire per edit like the Banlist. Each entry carries the original kind-20013 seal verbatim plus the message’s disclosed NIP-44 keys, so any reader able to open the list’s form verifies author, words, Channel, and signed time — holding no history and no old keys. Compaction re-wraps the head across rotations, which is the whole point of the placement.

Wire format shared with Armada’s pins.ts — entry JSON, both content forms, and the caps are cross-client surface. Divergence silently breaks pin verification between clients.

Structs

EditedContent

PinEditBundle

An Edit’s proof bundle: the same disclosure, for the revision.

PinEntry

One wire entry. Optional fields are omitted when absent (matching the reference implementation’s JSON), and unknown fields are carried through extra so republishing an entry never strips what a newer client added.

ReadPinList

A read list: its entries, or the fact it stayed dark.

VerifiedPin

A pin that passed the full §7 verification — safe to render.

Enums

PinBuildFailure

Why a message could not be pinned — each cause needs a different answer.

Constants

PIN_MAX_CONTENT_BYTES

PIN_MAX_ENTRIES

Structural caps (CORD-04 §7 Limits) — a violating edition reads as EMPTY.

Functions

build_pin_edit_bundle

Build an Edit’s proof bundle from its opened stream — the same disclosure as an entry, for the revision (§7 Edits). Verification-mirrored like build_pin_entry: refuse to build what verify_edit_bundle would drop.

build_pin_entry

Build a pin entry from an opened chat message, with the reason attached on refusal. Requires the Channel’s stream conversation key at the message’s epoch — i.e. the pinner can read what they pin. A pinner told “that message is from an epoch you no longer hold” when the real cause is a non-encrypted seal would retry forever, so the caller gets the distinction.

pin_killed_by

Whether a kind-5 kills this pin: matched by the RECOMPUTED rumor id against the delete’s e tags, honored only when the delete’s author equals the pin’s proven author.

read_pin_list

Read a pin list edition’s content (§7 Limits): the byte cap judged on the exact carried bytes by every reader; the entry cap by whoever can open the form. A violating or unreadable-as-JSON edition reads as an EMPTY list — never refused from the fold.

serialize_public_pin_list

Serialize a pin list’s content for a PUBLIC Channel (plaintext — the plane’s wrap is the gate). Errors on a cap violation: a writer must never publish an edition every reader would read as empty.

serialize_sealed_pin_list

Serialize for a PRIVATE Channel: the entries sealed under the Channel’s group conversation key at epoch. Both caps are checked on the final carried bytes, the sealed envelope living INSIDE the byte cap.

verify_pin_entry

The §7 verification, holding nothing but the pin and the list’s Channel: seal kind + signature → MAC → decrypt → rumor checks (author equality, chat kind, channel binding) → recomputed id. None on ANY failure; a failed entry is dropped alone, its edition folds normally.

with_proven_edit

Attach the newest provable Edit to an entry (§7 Edits). Requires the Channel conversation key of the Edit’s own epoch — i.e. the curator can read it. Returns the entry unchanged when the Edit cannot be proven, so a refresh never downgrades a good pin into a broken one.