Skip to content

Commit 5adcad7

Browse files
radroidclaude
andcommitted
docs(coil): re-baseline the seam ledger and correct the runbooks (#71)
The ledger asked that a second displacement "argue for itself in this file the way that one did", so it does. 47 upstream-owned files, +2074/-933 — seven new rows and two grown deletion counts, all of them the app rename, each listed with what moves and why it could not be an insertion. Renaming the app is not expressible as an append: `T3 Code` has to stop being the name, and every one of those literals already exists in an upstream file. Five of the nine rows are tests, which is the cheap half — a fixture upstream also edits conflicts loudly and resolves by reading two lines. The four source rows are one string literal each, which is the floor for a rename, and is why `T3 Coil (Alpha)` was chosen over an unsuffixed `T3 Coil`: dropping the stage label would have meant restructuring resolveDesktopAppBranding instead of replacing a constant. Also records what was declined — 31 more upstream files carry `T3 Code` in body copy, and renaming them would nearly double the ledger to buy prose consistency. The mac-signing runbook carried a "`productName` stays `T3 Code (Alpha)`" note that this issue invalidates. Replaced rather than deleted: the hazard it described is real, it was accepted rather than avoided, and the note now says so and points at the one-time manual install. Its #71 entry moves from a warning to the sequence that was actually followed. The two `codesign` transcripts that still show the old name are historical output and stay as they are. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 0856197 commit 5adcad7

4 files changed

Lines changed: 80 additions & 32 deletions

File tree

‎docs/coil/SEAMS.md‎

Lines changed: 43 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,17 @@
1-
# t3x seam ledger
1+
# coil seam ledger
22

33
**The authoritative list of every upstream-owned file this fork edits.**
44

5-
Measured, not asserted: **40 upstream-owned files, +2197 / -1047 lines**, against merge-base
6-
`78f462c4e` (upstream v0.0.33, the 2026-08-10 sync). The only deletion added since the
7-
2026-08-10 baseline is `scripts/build-desktop-artifact.ts` (row 38) — one line for #70, deliberately shaped as
8-
an env escape hatch so upstream's default and its tests survive it. Rows 39 and 40 (`README.md`,
9-
`docs/user/install.md`, #72) are pure insertions above upstream's own text. The −134 that #58 added
10-
on 2026-08-11 are **all** `pnpm-lock.yaml`, the one row the additive invariant below has never
11-
covered because it is regenerated rather than merged. Everything else the fork adds lives in new
5+
Measured, not asserted: **PLACEHOLDER_FILES upstream-owned files, +PLACEHOLDER_ADD / -PLACEHOLDER_DEL lines**, against merge-base
6+
`78f462c4e` (upstream v0.0.33, the 2026-08-10 sync). Everything else the fork adds lives in new
127
files upstream has never seen and cannot conflict.
138

9+
> **Re-baselined 2026-08-12 for #71**, which renamed the fork's identity from `t3x` to `coil` and
10+
> the app from `T3 Code (Alpha)` to `T3 Coil (Alpha)`. The directory and symbol renames cost
11+
> nothing here — they move fork-owned files, and the fork-added lines inside upstream files change
12+
> content without changing count. The app rename is what moved these numbers: **7 new rows and 2
13+
> grown deletion counts**, argued for below.
14+
1415
> **Corrected 2026-08-11 (#40).** The header read +1968 while the regeneration recipe below returned
1516
> +1981 against the same `origin/main` — a 13-line drift in the `pnpm-lock.yaml` row (see its own
1617
> note). The drift is persistent, not new: it was +1957 against a recipe run of +1970 before #70 landed,
@@ -30,6 +31,33 @@ files upstream has never seen and cannot conflict.
3031
> file, and the invariant above weakens from "no deletions anywhere" to "one known deletion, at a known
3132
> line". Keep it that way. The additive rule is what makes a clean rebase evidence of anything, so a
3233
> second displacement should have to argue for itself in this file the way that one did.
34+
>
35+
> **2026-08-12 (#71): the argument for the second set.** Renaming the app is not expressible as an
36+
> insertion. `T3 Code` has to stop being the name, and every one of these is a literal that already
37+
> exists in an upstream file, so each is a replacement:
38+
>
39+
> | File | | What moves |
40+
> | --- | --- | --- |
41+
> | `apps/desktop/src/app/DesktopEnvironment.ts` | +9/-1 | `APP_BASE_NAME`. The only one that really matters — `displayName` is derived from it and reaches `app.setName()`, the About panel, window titles, the Linux `.desktop` entry, and the whole web UI through `getAppBranding()`. The other 8 lines are a comment explaining why `legacyUserDataDirName` two lines below must NOT follow it |
42+
> | `apps/desktop/package.json` | -1 → -2 | `productName`, the `.app` bundle name |
43+
> | `apps/desktop/scripts/electron-launcher.mjs` | +1/-1 | the dev-mode display name |
44+
> | `apps/web/src/branding.ts` | +1/-1 | the browser-only fallback, used when no desktop branding is injected |
45+
> | `apps/web/index.html` | -0 → -1 | the boot `<title>` |
46+
> | `apps/desktop/src/app/DesktopAppIdentity.test.ts` | +5/-2 | asserts the new name AND keeps the legacy-userData assertions on the old one |
47+
> | `apps/web/src/branding.test.ts` | +14/-11 | fixtures, minus the injected-branding case which deliberately keeps `T3 Code` |
48+
> | `apps/desktop/src/app/DesktopLinuxUrlHandler.test.ts` | +1/-1 | fixture |
49+
> | `scripts/build-desktop-artifact.test.ts` | +4/-1 | asserts `resolveDesktopProductName` returns the fork's name |
50+
>
51+
> Five of the nine are tests, which is the cheap half: a test fixture that upstream also edits
52+
> conflicts loudly and is resolved by reading two lines. The four source rows are each a single
53+
> string literal, which is the smallest displacement a rename admits. `T3 Coil (Alpha)` was chosen
54+
> over an unsuffixed `T3 Coil` precisely to keep it that way — dropping the stage label would have
55+
> meant restructuring `resolveDesktopAppBranding` rather than replacing a constant.
56+
>
57+
> **What was NOT taken.** 31 further upstream files carry `T3 Code` in body copy ("T3 Code needs the
58+
> relay client…"). Renaming those would nearly double this ledger to buy prose consistency, and is
59+
> deliberately declined. The app's own name is computed, not hardcoded, in every surface that
60+
> matters; the leftovers are sentences.
3361
3462
> **Read the two dependency rows with their note, not their number.** `pnpm-lock.yaml` sits at
3563
> +490 / -871 and so at risk **77577**, still the top row by a wide margin. That figure is the
@@ -81,7 +109,7 @@ files upstream has never seen and cannot conflict.
81109
82110
> **Update delivery adds no NEW rows.** Almost all of the feature
83111
> (`docs/superpowers/specs/2026-08-03-update-delivery-design.md`) is new fork-owned files —
84-
> `infra/coil-update-relay/`, `.github/workflows/t3x-release.yml`, `scripts/coil/`,
112+
> `infra/coil-update-relay/`, `.github/workflows/coil-release.yml`, `scripts/coil/`,
85113
> `apps/desktop/src/coil/updateDelivery/`, `apps/desktop/src/ipc/methods/coilUpdate.ts`,
86114
> `packages/contracts/src/coil/`, `apps/web/src/components/coil/` — plus the `pnpm-lock.yaml`
87115
> row below. Two things that would each have cost a row were solved at the workflow level instead:
@@ -113,14 +141,14 @@ files upstream has never seen and cannot conflict.
113141
> consults the flag **only when no identity was named** — `findIdentity()` reads
114142
> `qualifier || process.env.CSC_NAME` first and, when non-empty, goes straight to
115143
> `security find-identity`. So the signing half is entirely fork-owned (`CSC_NAME` exported by
116-
> `.github/workflows/t3x-release.yml` and `scripts/coil/auto-build-desktop.sh`), at zero rows.
144+
> `.github/workflows/coil-release.yml` and `scripts/coil/auto-build-desktop.sh`), at zero rows.
117145
>
118146
> The row is spent on the **second** cause instead, which no environment variable existed for: macOS
119147
> stores one TCC permission row per `(service, bundle id)`, and the fork shared
120148
> `com.t3tools.t3code` with upstream's nightly — so whichever app launched last owned the grants and
121149
> the other was re-prompted, however well either was signed. `DESKTOP_APP_ID` is now
122150
> `process.env.T3X_DESKTOP_APP_ID?.trim() || "com.t3tools.t3code"`, and the fork sets that variable to
123-
> `dev.curlycloud.coil`.
151+
> `dev.curlycloud.t3coil`.
124152
>
125153
> **The shape of the edit is the point.** A changed literal would have been +1/-1 and would have
126154
> broken three upstream assertions in `build-desktop-artifact.test.ts`, adding a second row on a
@@ -272,8 +300,8 @@ Sorted by risk, worst first.
272300

273301
- `packages/contracts/src/settings.test.ts` — the fork's `notifyOnNeedsInput` block sat at the same
274302
`describe` anchor upstream keeps appending to, producing the add/add conflict in issue #29. Moved
275-
to `packages/contracts/src/coil/settings.t3x.test.ts`; the upstream file is byte-identical again.
276-
**This is the pattern to copy:** fork test cases belong in a `t3x/` sibling, never appended to an
303+
to `packages/contracts/src/coil/settings.coil.test.ts`; the upstream file is byte-identical again.
304+
**This is the pattern to copy:** fork test cases belong in a `coil/` sibling, never appended to an
277305
upstream spec.
278306

279307
## Logic mirrors (semantic dependencies, not code seams)
@@ -323,7 +351,7 @@ immediate-send branch only, and the fork's queue branch returns _before_ it.
323351
- `apps/server/src/coil/**`, `apps/web/src/coil/**`, `packages/contracts/src/coil/**` — feature code
324352
and the `CoilLayerLive` aggregator.
325353
- `scripts/coil/**` — fork setup, upstream sync, desktop auto-build (incl. opt-in git hooks).
326-
- `.github/workflows/t3x-*.yml` — `coil-upstream-sync.yml`, `coil-weekly-verify.yml`,
354+
- `.github/workflows/coil-*.yml` — `coil-upstream-sync.yml`, `coil-weekly-verify.yml`,
327355
`coil-sync-resolve.yml`, `coil-ci.yml` (the fork's PR/main gate; upstream's `ci.yml` needs
328356
blacksmith runners the fork cannot use).
329357
- `docs/coil/**`, `docs/superpowers/specs/**` — including `docs/coil/agents/**` (issue tracker, triage
@@ -332,7 +360,7 @@ immediate-send branch only, and the fork's queue branch returns _before_ it.
332360
`docs/adr/` precisely because those three are paths upstream could plausibly create.
333361

334362
Note that a fork-created file is only conflict-free if upstream never creates a file at the same
335-
path. Roughly half of the fork's new files sit outside the four `t3x`-named namespaces above, so
363+
path. Roughly half of the fork's new files sit outside the four `coil`-named namespaces above, so
336364
that guarantee is weaker than it looks.
337365

338366
### Desktop auto-build (`scripts/coil/auto-build-desktop.sh`)

‎docs/coil/auto-build-runbook.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -35,13 +35,13 @@ The name is **not** a flag — it is derived from the version in
3535

3636
| Version | Channel | `.app` produced |
3737
| ---------------------- | -------- | ----------------------- |
38-
| plain (e.g. `0.0.28`) | `latest` | `T3 Code (Alpha).app` |
38+
| plain (e.g. `0.0.28`) | `latest` | `T3 Coil (Alpha).app` |
3939
| `…-nightly.YYYYMMDD.N` | nightly | `T3 Code (Nightly).app` |
4040

41-
The `latest` name comes from `"productName": "T3 Code (Alpha)"` in
41+
The `latest` name comes from `"productName": "T3 Coil (Alpha)"` in
4242
`apps/desktop/package.json` — **not** the `"T3 Code"` fallback, which only
4343
applies if that field is ever removed upstream. So a default local build
44-
replaces **`T3 Code (Alpha).app`**, the app most fork users already run.
44+
replaces **`T3 Coil (Alpha).app`**, the app most fork users already run.
4545

4646
Don't trust the table — ask the script. `--dry-run` mounts the built `.dmg`
4747
read-only and reports the **real** name, falling back to the prediction above
@@ -58,8 +58,8 @@ last build" before it reaches the install step.)
5858
It prints one of:
5959

6060
```
61-
DRY-RUN install: read 'T3 Code (Alpha).app' from …/release/T3-Code-0.0.28-arm64.dmg
62-
DRY-RUN: '/Applications/T3 Code (Alpha).app' exists and WOULD be replaced
61+
DRY-RUN install: read 'T3 Coil (Alpha).app' from …/release/T3-Code-0.0.28-arm64.dmg
62+
DRY-RUN: '/Applications/T3 Coil (Alpha).app' exists and WOULD be replaced
6363
```
6464

6565
```

‎docs/coil/mac-signing-runbook.md‎

Lines changed: 16 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -160,13 +160,17 @@ through `T3X_DESKTOP_APP_ID`, which is the one upstream-owned line this whole ch
160160
so upstream's own assertions on that constant still pass and an unset environment builds exactly what
161161
upstream builds. See `SEAMS.md`.
162162

163-
Two deliberate non-changes:
163+
One deliberate non-change, and one that has since changed:
164164

165-
- **`productName` stays `T3 Code (Alpha)`.** The updater refuses an install when the `.app` name inside
166-
the dmg differs from the installed one (`resolveMacInstallTarget`), so renaming the app would break
167-
the update path this is meant to make quiet. The rename stops at the bundle id (#71).
168165
- **User data does not move.** `~/Library/Application Support/t3code` comes from a hardcoded
169-
`userDataDirName`, not from the bundle id — threads, settings and sessions are untouched.
166+
`userDataDirName`, not from the bundle id or the app name — threads, settings and sessions are
167+
untouched. This held through #70 and again through #71.
168+
- **`productName` no longer stays `T3 Code (Alpha)`.** It became `T3 Coil (Alpha)` in #71, along
169+
with the bundle id (`dev.curlycloud.t3coil`) and the certificate (`T3 Coil Code Signing`). The
170+
hazard this note used to warn about is real and was accepted rather than avoided: the updater
171+
refuses an install when the `.app` name in the dmg differs from the installed one, so the first
172+
renamed build has to be installed by hand, once. `describeRefusal` says exactly that now instead
173+
of reading like a fault.
170174

171175
Since it lands in the same release as the signing change, the two identity changes cost **one**
172176
round of prompts between them, not two. `scripts/coil/mac-signature.test.ts` asserts every build path
@@ -228,12 +232,13 @@ so a rotation that forgets them fails the next release instead of quietly re-pro
228232

229233
## Related
230234

231-
- **Issue #71 — renaming the fork to `coil`.** Read the notes on that issue before renaming anything
232-
here. Two things it has to respect: renaming the signing certificate (`T3 Coil Code Signing`, which a
233-
sweep of `T3X` will find) changes the designated requirement and costs another round of prompts,
234-
and renaming `productName` makes the updater refuse the first renamed build by design
235-
(`resolveMacInstallTarget`, "would create a second app"). Renaming the _visible app_ is otherwise
236-
free in permission terms — grants are keyed to the bundle id and the certificate, not the name.
235+
- **Issue #71 — renaming the fork to `coil`.** Done. It moved all three identities at once — bundle
236+
id, certificate and visible name — deliberately, so the permission reset is paid once rather than
237+
once per change. The certificate rename is the half that is not a code change: a new common name
238+
is a new certificate, so `--rotate` has to run and `designated-requirement.txt` has to be
239+
re-recorded from it before the release can sign anything. Renaming the visible app is free in TCC
240+
terms — grants key on the designated requirement, which names the bundle id and the certificate,
241+
not `productName`.
237242
- `docs/coil/auto-build-runbook.md` — the local build/install loop, which signs the same way.
238243
- Issue #41 — the autobuild relaunch race. Unrelated, adjacent.
239244
- Issue #72 / PR #78 (still open, branch `t3x/install-instructions`) — the first-launch install copy,

‎infra/coil-update-relay/tsconfig.json‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,22 @@
33
"compilerOptions": {
44
"target": "ES2023",
55
"lib": ["ES2023", "WebWorker"],
6-
"types": ["@cloudflare/workers-types"]
6+
"types": ["@cloudflare/workers-types"],
7+
"plugins": [
8+
{
9+
"name": "@effect/language-service",
10+
// Deep-merged with tsconfig.base.json; only the Worker-specific override belongs here.
11+
//
12+
// `globalFetch` steers application code towards `HttpClient` from `effect/unstable/http`,
13+
// which is right almost everywhere. It is not right inside a Cloudflare Worker: `fetch` is
14+
// the runtime's own API — it is how a Worker calls another origin, and how a Durable Object
15+
// stub is invoked — and there is no Effect runtime in the request path here to carry an
16+
// `HttpClient` requirement. apps/web disables it for the same reason.
17+
"diagnosticSeverity": {
18+
"globalFetch": "off"
19+
}
20+
}
21+
]
722
},
823
"include": ["src/**/*.ts"]
924
}

0 commit comments

Comments
 (0)