[immakermatty]

Why

The client side of the product update (src/update/, #5 and #7) can check, download, stage and activate — but nothing can publish what it consumes, the client has no built-in idea where the repository is or whom to trust, and executables have nowhere to live. This slice adds the publishing side of the contract in docs/update.md ("Publishing"), modelled on T3 Code's tag-driven release, and closes the client's remaining "explicit options only" gap.

What changes

Publisher core — src/publish/ (pure planning + a filesystem adapter, no network). Every operation reads the published tree and returns a plan of files to add, timestamp last. applyPlan decides for the whole plan, before the first byte is written, that no existing immutable path would receive other bytes; it then creates files exclusively and replaces only metadata/timestamp.json. Nothing is ever deleted, so a cached older timestamp always describes a complete repository.

• add-release (artifacts + identities + notes + channel document; repeatable, refuses an equal/lower version, other bytes under a reached version, the same artifact under another URL, a dropped target, and any identity the client would refuse)
• promote (exact version required; stable names the same artifact paths preview offers — never a rebuild; pre-releases refused)
• The tree is storage, not authority. Before anything is planned, the published timestamp, snapshot and targets must verify under the published root, and numbered metadata above what the timestamp references is refused. An independent review of this branch found that the first version re-signed whatever the branch held — someone with write access to gh-pages could have had a planted artifact entry signed by the real targets key on the next approved run. That is fixed and reproduced as a test.
• refresh (targets / snapshot / timestamp, no target change), status (remaining validity per role, non-zero below a margin), root installation (verified chain link; re-signs exactly the roles whose key changed)
• Lifetimes default to root 365 / targets 90 / snapshot 30 / timestamp 7 days (docs/release-cycle.md), configurable.
• The loopback fixture (scripts/update-fixture.ts) now builds every signed byte with the publisher's builders instead of its own copy, so the format the client tests prove is the format the publisher writes.

Artifact location. The TUF target path stays artifacts/<sha256>/lazurio; the GitHub Release asset URL goes into the signed target's custom.url. The client downloads from that signed URL and verifies signed length + digest exactly as before; without a URL it falls back to <targetBase>/<consistent-snapshot name> (fixture, mirrors). identity.json and release notes are small and live in the static tree.

Compiled-in defaults — src/update/defaults.ts. Repository https://releases.lazurio.io/{metadata,targets}/ (a domain the project controls, CNAME to GitHub Pages — it is baked into every client for good), default channel stable, the artifact origin allowlist, and the root metadata embedded at build time from release/root.json. That file does not exist until the key ceremony: a build then embeds no root, and lazurio install / lazurio update answer trust-missing — creating nothing — unless --bootstrap-root is given. install, update and update --check resolve repository, origins and root in one place; flags only override. The compiled-in root is the supplied root of the activation branch's seeding rule: it seeds empty trust, is otherwise ignored unless it is the verified direct successor of the trusted root, and is never a conflict. Naming another repository replaces the compiled-in origins entirely.

update/config.json is one owned, tolerant (member by member), schema-versioned file: {schemaVersion, channel, service, folder}, one reader/writer module. lazurio update channel keeps the recorded service and Folder; lazurio install keeps a channel chosen before it and records the channel it verified against. Switching never downgrades.

origin-refused (not retryable; its number lives only in the table below): a signed location or a redirect to an origin outside the list is refused at once instead of network-unavailable after backoff.

Minimum version. The signed minimumVersion of stable changes only through the explicit --minimum-version of a promotion (workflow input minimum_version): never from preview, never derived, only upwards, never above the promoted version; re-promoting the current version with a higher value raises it between releases.

Qualification bundle. scripts/update-fixture-server.ts now serves a repository produced by the publisher (add-release → promote per release) as static files; the control interface and qualify-update-linux.sh are unchanged. Smoke-tested on macOS against the CLI from source; not run on a Linux Machine.

Key tooling. scripts/release-keys.ts (generate, init-root, rotate-root; Ed25519, private key files 0600, refuses to write inside a Git repository or over an existing file, never prints key material) and docs/release-keys.md — the Principal's one-time ceremony, custody per role, rotation, compromise handling and the expiry calendar.

Workflows (release.yml, update-metadata-refresh.yml) and scripts/update-tree.sh (append-only gh-pages plumbing, tested against a local bare repository). See "Not in this push" below.

Redirect-origin finding

https://github.com/<owner>/<repo>/releases/download/<tag>/<asset> answers 302 to https://release-assets.githubusercontent.com/... (observed 2026-09-19 on a public repository). GitHub documents that storage only as the wildcard *.githubusercontent.com (GET /meta, domains.website); the transport matches exact origins, so the list names https://github.com, https://release-assets.githubusercontent.com and the predecessor host https://objects.githubusercontent.com. A test proves a redirect to an unlisted origin is refused. The release workflow downloads every new asset through the same list before publishing, so a host GitHub introduces later stops a release, not installed Machines.

What the Principal must set up on GitHub (nothing here creates it)

1. Key ceremony per docs/release-keys.md, then commit release/root.json through a reviewed PR.
2. Published origin https://releases.lazurio.io: DNS CNAME releases.lazurio.io → lazurio.github.io; verify lazurio.io for Pages at the Organization level; repository Pages: deploy from branch gh-pages, folder /, custom domain releases.lazurio.io, enforce HTTPS. The first release creates the branch (with the CNAME file); its "wait until the origin serves it" step only passes once DNS and the certificate are live — run publish-tag again afterwards (a no-op for the tree).
3. Environment release with a required reviewer, deployment branches/tags limited to main and v*, and environment secret LAZURIO_TUF_TARGETS_KEY.
4. Repository secrets LAZURIO_TUF_SNAPSHOT_KEY, LAZURIO_TUF_TIMESTAMP_KEY.
5. Ruleset for tags v* (a tag starts a release) and protection of gh-pages (no force push, no deletion).
6. Root key: offline only — password manager plus one offline copy; never CI.

Second merge with the activation branch (04bb02c): the floor vector

• Exit-code collision. metadata-rollback keeps 47 (it landed first in the stack); origin-refused moved to 48. src/update/errors.ts is the only place numbers live — prose no longer states any — and tests/update-errors.test.ts reads the table as source text and fails on a duplicate code name, a duplicate exit status, or a retired or reserved number (verified to fail on the original collision).
• Publisher vs the vector — tests/update-publish-floors.test.ts. One Machine keeps its base through add-release A → add-release B → promote → timestamp refresh → snapshot refresh → targets renewal → rotation of root and targets keys → add-release C and never sees metadata-rollback. Every re-signing is a new version; snapshot.meta always lists targets.json and never lowers it; a snapshot refresh leaves the targets reference identical; targets metadata keeps every earlier artifact, identity and notes entry. At every step the vector the Machine recorded from the network equals the one computed from the publisher's tree. An older generation of the same repository (every byte genuine), and a branch reset and re-signed at already-seen versions (equivocation), ARE refused by the real client as metadata-rollback, with its vector unchanged. Nothing in the publisher had to change.
• The gate. release-publish status --against <published> holds the tree about to be deployed against the published one with the client's own violationOf (src/publish/monotonic.ts only turns a tree into facts; no rule is restated); exit 4; the workflows run it before every push. "Published" is the checked-out gh-pages commit (update-tree.sh baseline), not what the origin serves at that moment.
• Other conflicts: check.ts keeps both the signed custom.url validation and the vector's capture flow; the fixture keeps building through the publisher's builders and gains the vector's adversarial options; one deviation list, 1–25.

First merge with the activation branch (35cb0ab)

Merged, not rebased; nothing force-pushed. Conflicts and resolutions:

• src/update/config.ts (add/add): unified as described above.
• src/update/trust.ts: the activation branch's seeding rule taken whole; this branch's separate embeddedRoot input removed — the compiled-in root enters as the supplied root. verifiedRoot is exported as the build's gate for release/root.json.
• src/update/cli.ts: both command sets kept; one resolveRepository for install, update, update --check.
• docs/update.md: revised contract text kept; one merged list of concrete choices and one deviation list (1–24, no duplicates); State on disk and Surfaces now name the config's members, lazurio install and launchpad --base. The activation branch's deviation 16 ("config holds service and Folder, not only the channel") is resolved in the contract text and dropped.
• trust-missing with no supplied root and no trust/ directory is now answered before anything is created (previously the base, lock and an observation were written).

Final error-code table (stable, unique; 23, 26 and 31 are retired and never reused)

exit	code	retryable
2	invalid-request	no
20	network-unavailable	yes
21	metadata-expired	yes
22	metadata-invalid	yes
24	channel-invalid	yes
25	trust-missing	no
27	trust-invalid	no
28	target-unsupported	yes
29	busy	yes
30	storage-unavailable	yes
32	response-too-large	yes
33	lock-unsupported	no
34	not-installed	no
35	disk-full	yes
36	artifact-invalid	yes
37	identity-invalid	yes
38	schema-incompatible	yes
39	self-check-failed	yes
40	activation-failed	yes
41	activation-interrupted	yes
42	rollback-unavailable	no
43	already-installed	no
44	unverified-executable	no
45	unit-conflict	no
46	service-failed	yes
47	metadata-rollback	yes
48	origin-refused	no
70	internal	no

Commits that touch workflow files were pushed over SSH, because the HTTPS credential of this session lacks the workflow scope; per the coordinator this route is covered by the Principal's standing rule that agents may push to PR branches. All other commits went through the plain HTTPS push. Nothing was force-pushed.

What is NOT done

• Nothing has run against GitHub: no key, secret, environment, Pages site, tag or release was created, and neither workflow has ever executed.
• No key ceremony; release/root.json does not exist; every build today embeds no root.
• Release notes are published and signed, but no client surface reads them yet.
• Whether the refresh job's own gh-pages commits keep GitHub from disabling the scheduled workflow after 60 days of inactivity is unverified.
• Targets metadata keeps every artifact ever released; pruning is not built.
• The DNS record, domain verification and Pages custom domain for releases.lazurio.io do not exist yet.
• Launchpad poller/pill, installer, launchd and native evidence remain as listed in docs/update.md.

Verification

• bun run lint, bun run typecheck, bun run check:public: pass.
• bun run check on head dbdf120: pass — bun test 519 pass, 3 skip, 0 fail. One earlier full run had a single failure in the existing tests/update-journey.test.ts (artifact-invalid after a 100 % download); it did not reproduce in a second full run nor in three runs under parallel load.
• New: tests/publish-repository.test.ts (11 tests, including the explicit minimum version, the forged-tree refusal and the append-only branch plumbing against a local bare repository) and tests/update-publish-journey.test.ts (4 tests; lazurio install proves itself against the publisher-made repository with the compiled-in root, touching only metadata, the channel document and its own identity): the tree the publisher wrote is served as static files on loopback and the real client checks and downloads release A, sees B behind a signed URL on a second origin that redirects to a third, is refused at once with origin-refused when that third origin is unlisted, sees B on stable only after promotion, resolves a complete older repository from a cached older timestamp, and follows a rotated root + targets key; a real compiled CLI without release/root.json answers trust-missing, one with it needs no bootstrap root.
• scripts/build-candidate.ts <dir> --version 9.9.9-rc.1 was run for real: the executable reports the tag version and, with no release/root.json, answers trust-missing.
• All keys in tests are ephemeral and live in temporary directories or memory.

Deviations from docs/update.md are listed there as items 1–25 (17–25 from this slice).

🤖 Generated with Claude Code

[macroscopeapp]

🟠 High scripts/update-tree.sh:31

GH_TOKEN is exposed in the git process command line as reversible base64, so another process under the job user can read /proc/<pid>/cmdline or ps and use the token to modify the repository. Pass the credential through an askpass helper or a tightly permissioned temporary credential/config file instead, with cleanup.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @scripts/update-tree.sh around line 31:

`GH_TOKEN` is exposed in the `git` process command line as reversible base64, so another process under the job user can read `/proc/<pid>/cmdline` or `ps` and use the token to modify the repository. Pass the credential through an askpass helper or a tightly permissioned temporary credential/config file instead, with cleanup.

[macroscopeapp]

🟠 High docs/release-keys.md:201

The root-loss recovery procedure does not migrate existing installations to the newly embedded root, so those installations retain the old chain and lose update capability when it expires. readSeed prefers the syntactically valid durable trust/root.json over the embedded root, and the lost old key prevents publishing a successor; the procedure must explicitly require users to discard that durable trust state and perform a fresh installation.

-  root expires, publish a final release under the old chain that embeds a
-  **new** root created by a new ceremony, and tell users to update before the
-  date. Machines that miss it need a fresh installation. This is why the root
-  key has two verified copies.
+  root expires, publish a final release under the old chain that embeds a
+  **new** root created by a new ceremony. This does not migrate existing
+  installations because `readSeed` prefers their durable `trust/root.json`.
+  Tell users to discard that durable trust state and perform a fresh
+  installation before the old chain expires. This is why the root key has two
+  verified copies.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @docs/release-keys.md around lines 201-204:

The root-loss recovery procedure does not migrate existing installations to the newly embedded root, so those installations retain the old chain and lose update capability when it expires. `readSeed` prefers the syntactically valid durable `trust/root.json` over the embedded root, and the lost old key prevents publishing a successor; the procedure must explicitly require users to discard that durable trust state and perform a fresh installation.

[macroscopeapp]

🟡 Medium publish/repository.ts:463

Tree-hosted artifacts can be published with incorrect target lengths: artifact.length is only checked as a positive integer and is never compared with the source artifact.file. Since applyPlan verifies only the SHA-256 before copying, the generated metadata can disagree with the immutable file, causing clients to reject the download and referencedObjects to report it as unreachable. Validate the source file length before planning, or enforce the declared length during applyPlan.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @src/publish/repository.ts around line 463:

Tree-hosted artifacts can be published with incorrect target lengths: `artifact.length` is only checked as a positive integer and is never compared with the source `artifact.file`. Since `applyPlan` verifies only the SHA-256 before copying, the generated metadata can disagree with the immutable file, causing clients to reject the download and `referencedObjects` to report it as unreachable. Validate the source file length before planning, or enforce the declared length during `applyPlan`.

[macroscopeapp]

🟠 High publish/tree.ts:114

A checked-out tree containing a symlink at metadata or an intermediate targets/... component makes applyPlan write planned files outside directory, and the timestamp replacement can overwrite the symlink target. safePath only checks the path string, while mkdir, writeFile, copyFile, and writeDurableFile follow existing symlinks; reject symlinks in every existing path component and avoid following them during writes.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @src/publish/tree.ts around line 114:

A checked-out tree containing a symlink at `metadata` or an intermediate `targets/...` component makes `applyPlan` write planned files outside `directory`, and the timestamp replacement can overwrite the symlink target. `safePath` only checks the path string, while `mkdir`, `writeFile`, `copyFile`, and `writeDurableFile` follow existing symlinks; reject symlinks in every existing path component and avoid following them during writes.

[macroscopeapp]

🟠 High docs/release-keys.md:112

Pushing a release tag does not build or publish anything because this tree contains no release.yml or update-metadata-refresh.yml workflow—only .github/workflows/check.yml. The documented release and metadata-refresh procedures therefore leave clients without published releases or renewed metadata; include those workflows or mark these operations as unavailable.

Also found in 1 other location(s)

docs/update.md:488

The new workflow documentation says release.yml and update-metadata-refresh.yml implement publishing/refresh, but neither file exists in the reviewed tree (only .github/workflows/check.yml exists). As a result, following this documented release process cannot publish releases or renew metadata; this is also acknowledged in the PR context. Either include the workflow files or mark this behavior as not yet available rather than documenting it as implemented.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @docs/release-keys.md around line 112:

Pushing a release tag does not build or publish anything because this tree contains no `release.yml` or `update-metadata-refresh.yml` workflow—only `.github/workflows/check.yml`. The documented release and metadata-refresh procedures therefore leave clients without published releases or renewed metadata; include those workflows or mark these operations as unavailable.

Also found in 1 other location(s):
- docs/update.md:488 -- The new workflow documentation says `release.yml` and `update-metadata-refresh.yml` implement publishing/refresh, but neither file exists in the reviewed tree (only `.github/workflows/check.yml` exists). As a result, following this documented release process cannot publish releases or renew metadata; this is also acknowledged in the PR context. Either include the workflow files or mark this behavior as not yet available rather than documenting it as implemented.

[macroscopeapp]

🟡 Medium scripts/release-keys.ts:57

generate accepts output paths inside .git directories and bare repositories, so private keys can be written alongside repository or backup data despite the custody guarantee. insideRepository treats a successful --is-inside-work-tree result of false as safe; check --is-inside-git-dir and --is-bare-repository as well.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @scripts/release-keys.ts around line 57:

`generate` accepts output paths inside `.git` directories and bare repositories, so private keys can be written alongside repository or backup data despite the custody guarantee. `insideRepository` treats a successful `--is-inside-work-tree` result of `false` as safe; check `--is-inside-git-dir` and `--is-bare-repository` as well.

[macroscopeapp]

🟠 High publish/repository.ts:355

A replayed older timestamp.json causes the next publish to reuse a version below the one clients have already seen, so TUF rollback protection rejects the new release for those clients. loadRepository accepts the older timestamp when it references the current snapshot, and line 355 derives the replacement from that replayed version; reject such replays or otherwise enforce a monotonic timestamp version before incrementing it.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @src/publish/repository.ts around line 355:

A replayed older `timestamp.json` causes the next publish to reuse a version below the one clients have already seen, so TUF rollback protection rejects the new release for those clients. `loadRepository` accepts the older timestamp when it references the current snapshot, and line 355 derives the replacement from that replayed version; reject such replays or otherwise enforce a monotonic timestamp version before incrementing it.

[macroscopeapp]

🟡 Medium update/config.ts:72

Concurrent changeUpdateConfig calls lose each other's changes: a later write based on a stale config can overwrite a newly recorded service/folder or selected channel, causing subsequent updates to stop managing the service or use the wrong channel. Serialize the read-modify-write with the update/config lock, or use an atomic merge-and-retry scheme.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @src/update/config.ts around line 72:

Concurrent `changeUpdateConfig` calls lose each other's changes: a later write based on a stale config can overwrite a newly recorded `service`/`folder` or selected `channel`, causing subsequent updates to stop managing the service or use the wrong channel. Serialize the read-modify-write with the update/config lock, or use an atomic merge-and-retry scheme.

[macroscopeapp]

🟡 Medium update/check.ts:264

An inaccessible trustDirectory is reported as trust-missing, so existing installations with permission or I/O errors are sent down the bootstrap-recovery path instead of returning storage-unavailable with the underlying errno. The probe currently catches every lstat rejection; only ENOENT should map to absence, while other errors should use the existing storage-error handling.

Suggested change

	if (
	input.bootstrapRoot === undefined &&
	!(await lstat(trustDirectory).then(
	() => true,
	() => false,
	))
	)
	return fail("trust-missing");
	let trustPresent: boolean;
	try {
	await lstat(trustDirectory);
	trustPresent = true;
	} catch (error) {
	if (
	!(error &&
	typeof error === "object" &&
	"code" in error &&
	error.code === "ENOENT")
	)
	return fail(...storageOrInternal(error, "prepare"));
	trustPresent = false;
	}
	if (input.bootstrapRoot === undefined && !trustPresent)
	return fail("trust-missing");

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @src/update/check.ts around lines 264-271:

An inaccessible `trustDirectory` is reported as `trust-missing`, so existing installations with permission or I/O errors are sent down the bootstrap-recovery path instead of returning `storage-unavailable` with the underlying errno. The probe currently catches every `lstat` rejection; only `ENOENT` should map to absence, while other errors should use the existing storage-error handling.

[macroscopeapp]

🟠 High publish/tree.ts:122

A source artifact changed after hashFile(write.file) succeeds is copied with its new bytes, so the published digest path contains bytes that do not match the digest recorded in targets metadata; because timestamp.json is then published, clients download the artifact and fail verification. Copy from a stable opened source, or verify the bytes actually copied before publishing the timestamp.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @src/publish/tree.ts around line 122:

A source artifact changed after `hashFile(write.file)` succeeds is copied with its new bytes, so the published digest path contains bytes that do not match the digest recorded in targets metadata; because `timestamp.json` is then published, clients download the artifact and fail verification. Copy from a stable opened source, or verify the bytes actually copied before publishing the timestamp.

[macroscopeapp]

🟡 Medium publish/repository.ts:544

A direct addRelease to stable can publish a minimumVersion above the release version or below the existing stable floor, leaving the stable channel with an invalid floor. Unlike promote, this path performs no product-version or comparison checks before signing the channel document. Apply the same bounds and monotonicity checks used by promote, or reject direct stable publishing.

 const sequence = (current?.sequence ?? 0) + 1;
+  const minimumVersion =
+    input.minimumVersion ?? current?.minimumVersion ?? "0.0.1";
+  if (
+    input.channel === "stable" &&
+    (!isProductVersion(minimumVersion) ||
+      compareVersions(minimumVersion, input.version) > 0 ||
+      (current && compareVersions(minimumVersion, current.minimumVersion) < 0))
+  )
+    throw new PublishError("invalid-input", "minimum-version");
   const document = channelDocumentBytes({
     channel: input.channel,
     sequence,
     version: input.version,
-    minimumVersion: input.minimumVersion ?? current?.minimumVersion ?? "0.0.1",
+    minimumVersion,
     targets: documentTargets,
   });

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @src/publish/repository.ts around lines 544-550:

A direct `addRelease` to `stable` can publish a `minimumVersion` above the release version or below the existing stable floor, leaving the stable channel with an invalid floor. Unlike `promote`, this path performs no product-version or comparison checks before signing the channel document. Apply the same bounds and monotonicity checks used by `promote`, or reject direct stable publishing.

[macroscopeapp]

🟡 Medium publish/repository.ts:503

When two execution targets share the same artifact digest, the second identity write throws immutable-conflict because both identities use identityTargetPath(path), even though each identity has a different required identity.target. This makes valid multi-target releases with byte-identical artifacts impossible; derive the identity path from both the artifact path and execution target.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @src/publish/repository.ts around line 503:

When two execution targets share the same artifact digest, the second identity write throws `immutable-conflict` because both identities use `identityTargetPath(path)`, even though each identity has a different required `identity.target`. This makes valid multi-target releases with byte-identical artifacts impossible; derive the identity path from both the artifact path and execution target.

[macroscopeapp]

Macroscope skipped reviewing this pull request. Per-review cost limit exceeded (workspace setting).

This review would cost an estimated $10.00, which exceeds your per-review limit of $10.00.

The top 3 files driving up this estimate:

File	Diff Size	Estimate
src/publish/repository.ts	28.32KB	$1.42
docs/update.md	22.05KB	$1.10
scripts/release-publish.ts	19.55KB	$0.98

Tip

To get this pull request reviewed, you can:

1. Comment @macroscope-app on this PR to request a manual review (monthly spend limits still apply).
2. Exclude the file(s) above from review by adding a pattern to your .macroscope/ignore.md — note that creating this file replaces Macroscope's built-in default ignores rather than extending them.
3. Raise your cost limit in your workspace billing settings.

^{Turn off this reminder going forward}

[immakermatty]

Superseded by #11, which implements the simplified contract merged in #10 (decision F13: GitHub Releases + Sigstore attestation, one activation path). The TUF-based stack in this PR is not continued; nothing from it should be ported except what #11 already carries.