Content pins

Two mechanisms fix which bytes a node’s interfaces are generated from, and they answer different questions: what an author requires, and what a launch decides.

Author pins: what a manifest may state

Every place a manifest references a contract or pairing document by name:tag accepts an optional sha256, the fingerprint of the exact document file the author wrote the node against:

depends_on: {
  contracts: [
    { link_id: "cam", name: "rgb_camera", tag: "v1",
      sha256: "3f9c0e21ab7e5f6d8a4b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f" }
  ],
}

An unpinned reference resolves to whatever the repository caches hold for that name:tag; a pinned one resolves only to the exact stated content. When the caches hold different bytes, node add and node sync name each cached copy of that name:tag, with its fingerprint and where it was read, and advise running peppy repo refresh, then changing the pin or registering the repository that serves those bytes; a launch refuses the resolution naming both fingerprints. Pin when a node’s correctness depends on a specific revision of a document that a tag alone does not identify; leave unpinned to follow the document as its repository evolves.

An author pin is a statement about authorship: it travels with the manifest, so every machine that ever adds the node enforces it.

A node uses one content for each document that its manifest names. Two references to one name:tag of a contract, or of a pairing, with two different sha256 values make the manifest invalid, so node sync and node add refuse it and name both values. A reference without a sha256 resolves when the node is added: an add whose references resolve to two contents of one document is refused, naming both fingerprints.

The contract references of an MCP exposure take the same optional sha256 with the same meaning: a launch serving the exposure resolves the contract through the pin, and refuses naming both fingerprints when the caches hold other bytes.

Launch pins: what a launch decides

A launch pins everything, whether the manifests do or not. The machine the launch is submitted to resolves every node, every transitive dependency, and every contract and pairing document once, and every machine in the launch runs exactly the content it resolved; see Federation. A launch pin exists for the duration of one launch and is minted from whatever the submitting machine’s caches held at that moment.

The two compose rather than compete. Where a manifest carries an author pin, the launch resolves the reference through it, so the launch pin and the author pin name the same bytes. A launch whose closure would need one document at two different contents is refused up front, naming both fingerprints, because a single launch runs a single answer for each identity.