picopackage/notes.md

## Resolution rules

Two principles decide every case below:

1. **The checksum decides, never the timestamp.** mtime is unreliable (a raw
   file re-uploaded unchanged gets a new mtime; a gist mirrored elsewhere gets
   an arbitrary one) and it is not evidence about content. If the payload
   checksums agree, the payload is settled — there is nothing to resolve no
   matter what the timestamps say. This is why every `????` in the old table
   collapsed: all of those rows assumed equal checksums, so all of them are
   metadata questions, not content questions.

2. **Merge the payload, regenerate the metadata.** The metadata block is
   derived, not authored, so it never takes part in a merge — merging it would
   conflict on every single update. Three-way merges run on the payload alone
   and the block is rewritten afterwards.

### Terms

- **payload** — the file with its metadata block removed, then normalised.
- **bare** — a file with no metadata block. A hand-copied file, or an upstream
  that has never been packaged.
- **`payload_checksum`** — checksum of the payload as it sits in this file.
  Local edits break it, which is how modification is detected.
- **`base_checksum`** — checksum of the upstream payload this file was last
  reconciled with. Equal to `payload_checksum` on a clean install; they diverge
  after a merge or a local edit. This is the merge base pointer and the cache
  key.

### Same payload checksum

The content is identical, so the only question is which metadata to keep.

| Remote  | Local   | Action                                    | State       |
|---------|---------|-------------------------------------------|-------------|
| Bare    | missing | Write payload + generated metadata        | `installed` |
| Package | missing | Write payload + upstream metadata         | `installed` |
| Bare    | Bare    | Adopt: attach generated metadata           | `adopted`   |
| Package | Bare    | Adopt: attach upstream metadata            | `adopted`   |
| Bare    | Package | Nothing to do                             | `current`   |
| Package | Package | Rewrite only if the metadata itself changed | `current`   |

mtime appears nowhere in this table. That is the point of principle 1.

### Different payload checksum

| Local              | Modified | Base available | Action                              | State       |
|--------------------|----------|----------------|-------------------------------------|-------------|
| missing            | —        | —              | Write it                            | `installed` |
| Package            | no       | —              | Fast-forward to upstream            | `updated`   |
| Package            | yes      | yes            | Three-way merge, clean              | `merged`    |
| Package            | yes      | yes            | Three-way merge, conflicted         | `conflict`  |
| Package            | yes      | no             | Refuse — no ancestor to merge from  | `conflict`  |
| Bare               | n/a      | never          | Refuse — unrelated file, same name  | `conflict`  |
| any                | any      | any            | `--force` overwrites unconditionally | `updated`   |

A bare local file whose payload differs is not a modified picopackage — it is an
unrelated file that happens to share a name. There is no ancestor and no claim
that the two share a history, so merging would be guesswork. Refuse and say so.

### Conflicts are non-destructive

`git`/`diff3` conflict markers are written to `<file>.picopackage-merge`, beside
the original. The original is never touched. A package manager with no `reset`
and no index has no business writing conflict markers into a file the user may
not have committed.

## Merge base cache

Three-way merge needs the common ancestor — the payload exactly as upstream last
sent it. It is content-addressed under `$XDG_CACHE_HOME/picopackage/sha256/ab/cdef…`
and written on every save, so a file installed by `ppkg` carries the pointer to
its own ancestor in `base_checksum`.

Cache misses are expected and survivable: a file installed on another machine, a
cleared cache, a package predating this feature. The fallback is to refuse the
merge and say why, which is honest. A future `source_url` pinned to an immutable
revision would let us refetch the ancestor instead of refusing — see below.

## Update UX and signing (designed 2026-08-13, not implemented)

The security question splits in three, and today's answers are: **first
install** — pure trust in the URL, same as copy+paste, mitigated by "it's one
file and you can read it"; **update** — worse than copy+paste, because `ppkg
update` fetches whatever the mutable url serves and writes it with less
friction than a human re-pasting; **transport** — plain `http` is currently
allowed. The checksum contributes nothing adversarial: it lives inside the
file it hashes and is regenerated on every write, so it is integrity against
yourself, not against an attacker. The design below closes the update gap.

### Diff by default

`ppkg update` shows the diff and asks before writing. The diff shown is
**ancestor → upstream** — the untrusted delta. Local edits are not news to the
user, and the Resolver already holds all three payloads at that point, so this
is nearly free. We are not a diff tool: shell out (`git diff --no-index`, else
`diff -u`), respect `$PAGER` — the same philosophy as merge.rb. `-y`/`--yes`
skips the prompt for scripts; it never covers an identity change (below).

### Identity: SSH signatures, TOFU-pinned

SSH rather than Sigstore. A full Sigstore bundle is 4–10KB of JSON — routinely
larger than the payload it certifies — and drags a dependency tree into a
zero-dependency gem. An armored ed25519 ssh signature is ~0.5KB, embeds in the
metadata block, and the authors this format serves (gists, blogs) already hold
ssh keys, with `github.com/<user>.keys` as a verification channel separate
from the file itself. What Sigstore would add — identity that survives key
loss, a transparency log — is real but not a different security class at this
scale. It stays a possible opt-in upgrade, not the price of entry.

- The signature covers the **normalized payload + the claims** (url, filename,
  payload_version). Signing the payload alone leaves `url` unsigned, so a
  tampered first install could silently redirect every future update. The
  claims/records split in provider.rb is the seam: sign the claims, keep
  deriving the records.
- TOFU: the key fingerprint is pinned at install, or the first time a
  signature appears on an already-installed file. Unsigned packages keep
  working; signing is opt-in per file.

### Key changes are a hard stop

The known_hosts model: banner, refuse, distinct exit code — not a y/n prompt
someone can fat-finger through. The only door is `--accept-key <fingerprint>`;
making the human transcribe the new fingerprint is what proves they looked.

Routine updates and identity changes are different signals and get different
ceremonies. "Upstream changed, here's the diff" is routine: default-proceed,
informational. "The signing identity changed" is how account compromise
presents: default-refuse. Flattening both into one always-maximum-caution
ceremony is how alarm fatigue happens.

### No rotation chains

Old-key-signs-new-key succession (signify/TUF style) was considered and
dropped. If every key change is loud and manual anyway, a valid rotation proof
can only *downgrade* the alarm — and a stolen key holds everything needed to
mint that proof, so chains sharpen theft (a thief can rotate the author out of
their own package) while buying convenience only for planned rotation. At this
scale, "key changed, human reads the diff carefully, re-pins" *is* the
rotation ceremony, and it covers loss and theft with the same motion.

### Exit codes are the contract

Callers — scripts and reviewing agents — build policy on exit codes, not on
prose. An agent's policy may auto-accept a clean diff under a continuous key;
an identity change must be unrepresentable in that path — no flag an agent
routinely passes gets through it.

| Code | Meaning                                                    |
|------|------------------------------------------------------------|
| 0    | written (installed/adopted/updated/merged) or already current |
| 1    | conflict — original untouched, as ever                     |
| 2    | declined — user said no to the diff                        |
| 3    | identity change — signing key differs from the pin         |

### Review is the content check; the signature is the identity check

A signature answers "same author?" and says nothing about whether the code is
safe. Review answers "does this change look sane?" and says nothing about who
made it. They are complements, and single files invert the economics that make
library review hopeless: the whole unit — old file, new file, three-way diff,
the project it lives in — fits in one reading (or one context window), and
with no install hooks, build steps, or dependencies, what you review is
exactly what runs.

The gem's job is to surface facts, not to judge: emit the diff plus the
machine-readable facts (`--json` — key changed, size delta, e.g. "adds
net/http") and exit accordingly. Any LLM stays out of the gem. Note for
whoever builds the reviewing agent: the payload is adversarial input —
prompt injection in comments, aimed at the reviewer, is an expected attack.

### Order of work

1. Refuse plain `http`, including via redirect — cheap, orthogonal.
2. `source_url` pinning (see open question below) — makes the update diff a
   pointer change and recovers merge bases on cache miss.
3. Diff-by-default + the exit-code contract.
4. SSH signing and pinning.

## Open questions

- **Immutable source pinning.** `url` is mutable ("whatever is at this address
  today"), which means builds aren't reproducible and "upstream improved" is
  indistinguishable from "upstream was compromised". Wants splitting into a
  pinned `source_url` (gist revision SHA, commit SHA) and a mutable `update_url`
  used only for checking. This also recovers merge bases on a cache miss.
- **Multi-file packages.** `Jmap::Client` + `Jmap::Http` are one unit of reuse
  across two files. Either the spec grows a flat file-set, or single-file
  packages accept that they define several classes in one file and lose Zeitwerk
  file-per-class layout. Unresolved, and the first real consumer hits it.
- **Comment styles.** `#` covers Ruby/Python/shell/YAML/Perl. Needs a table for
  `//`, `--`, `<!-- -->`, `/* */`, `;` before the format is honestly
  language-agnostic.
- **Unknown metadata keys** are preserved verbatim on rewrite (see
  `Metadata#extra`), so optional spec fields survive a tool that predates them.
- **Snippet-hosting providers.** `Provider::PROVIDERS` covers GitHub Gist and
  OpenGist; GitLab and Gitea snippets have no provider, so they fall through to
  `DefaultProvider` and only work if the pasted URL already points at raw
  content. Gitea matters now that picopackage itself is hosted on one. A Gitea
  snippet is `https://<host>/snippets/<id>` → `…/snippets/<id>/raw`; GitLab is
  `https://gitlab.com/(-/)?snippets/<id>` → `…/snippets/<id>/raw`. They sit on
  opposite sides of the `handles_url?` contract: GitLab is a fixed host, so it
  can answer `true` by pattern like `GithubGistProvider`, while a self-hosted
  Gitea can be any domain and has to answer `:maybe` and prove itself by
  fetching, like `OpenGistProvider`.
- **`test_method`.** `test_url` is carried in `Metadata`; `test_method` (the
  name of a test defined inside the payload itself) was in the original spec and
  never implemented. It only earns its place if `ppkg` can actually run it,
  which means executing upstream code — so it's blocked behind the signing work
  above, not just unimplemented.
- **Is a picopackage necessarily code?** The spec repo answered this and the
  answer never made it here: “a scheme for sharing text content, often source
  code… to track a single file of text”, packaging “code or configuration or
  data”. So the scope is text, not code. Nothing in the tool assumes otherwise,
  but nothing states it either, and it decides two things downstream: the
  comment-style table above, and `test_url`/`test_method`, which only mean
  anything for the code case.
- **`source_url` is an overloaded name.** The pinning proposal above wants
  `source_url` for an immutable revision pointer. The spec repo already used
  that name for something else — there, `url` was the human-readable page and
  `source_url` the optional direct/raw link “if `url` isn’t parsable”, which is
  the job `Provider` now does by resolution rather than by metadata. If pinning
  is implemented under that name, it is a third meaning for the same key; worth
  picking a fresh one (`pinned_url`, `revision_url`) instead.