From 414bb13a6bdaf4695ea90541c48a4d46690ed200 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Przemys=C5=82aw=20Galarowicz?= Date: Tue, 17 Nov 2026 13:55:13 +0100 Subject: [PATCH] docs(limits,threat-model): true statements about what pharn deletes (C4.2, CORE-175) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit LIMITS.md §1d: a renamed file's old copy stays on disk as an orphan; `update` deletes only the directory of a capability it drops (deleteCapabilityDir), never a file inside one it keeps. The unrelated src/commands/update.ts:452 citation is gone, and the backstop no longer says `update` reports nothing: the ORPHANED note names it. THREAT-MODEL.md: outside the project pharn deletes only the temporary download directory it created itself, not "nothing". Both link docs/reference/deletes.md. Co-Authored-By: Claude Opus 5.5 --- LIMITS.md | 10 ++++++---- THREAT-MODEL.md | 5 +++-- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/LIMITS.md b/LIMITS.md index 989a0324..2708396c 100644 --- a/LIMITS.md +++ b/LIMITS.md @@ -74,8 +74,10 @@ install's channel offers NOW — the newest verified release for an install that a config recorded at the `flat` layout, removed in v0.21.0, is refused at load). An upstream **rename** lands at two levels: a renamed **capability** surfaces in `update`'s membership report as `dropped-gone` / `added` (`mergeCapabilities`, `src/lib/merge-capabilities.ts`), while a renamed **file inside** a -capability is restored at its new path and the old copy is left on disk — `update` never deletes -(`src/commands/update.ts:452`). +capability is restored at its new path and the old copy is left on disk as an orphan — `update` +deletes only the directory of a capability it drops (`deleteCapabilityDir`, +`src/lib/capability-dir.ts`), never a file inside one it keeps (every delete: +`docs/reference/deletes.md`). - **Struck claim:** "`remove`/`update` always know exactly what the pinned version installed." - **True statement:** `update`/`status` reconstruct from the **current** upstream, so a capability @@ -84,8 +86,8 @@ capability is restored at its new path and the old copy is left on disk — `upd (`deleteCapabilityDir`, `src/lib/capability-dir.ts`) and pruning that capability's entries from `pharn.records.json` (`pruneCapabilityRecords`, `src/commands/remove.ts`). - **Backstop:** every one of those paths is `safeJoin`-contained. Two residuals remain named: a file - **orphaned by an upstream rename** — `update` restores the new path, leaves the old one, and reports - nothing, bounded to the install subtree and visible to `pharn status`; and `remove`'s delete takes the + **orphaned by an upstream rename** — `update` restores the new path, leaves the old one, and names it + in its `ORPHANED` note (as `pharn status` does), bounded to the install subtree; and `remove`'s delete takes the **whole directory** at that address, including files you added inside it. --- diff --git a/THREAT-MODEL.md b/THREAT-MODEL.md index 7e0be992..503e2e8a 100644 --- a/THREAT-MODEL.md +++ b/THREAT-MODEL.md @@ -148,8 +148,9 @@ a test. the resolved SHA _as_ the ref, so every fetch wrote a self-mapped `"": ""` entry under a new key, the previous hash was always `undefined`, and the delete branch could never run. One ~2.4 MB tarball per distinct upstream commit, retained forever, each one an entry reusable by - filename. Caches already on disk are inert but **not** removed — pharn deletes nothing outside the - user's project; `docs/troubleshooting.md` says where they live and how to size them. + filename. Caches already on disk are inert but **not** removed — outside the user's project pharn + deletes only the temporary download directory it created itself (`docs/reference/deletes.md`); + `docs/troubleshooting.md` says where the caches live and how to size them. - **No proxy support of pharn's own, stated as a limit.** Node's global `fetch` reads **no** proxy environment variable by default. Every Node at or above pharn's floor (24.2.0, `engines.node`) reads them once the user opts in (`NODE_USE_ENV_PROXY=1`, or `--use-env-proxy` on 24.5+), and then