Over-the-air updates of a Zinc app, on every platform

Research report, 2026-10-18. No code changed. Three labels are used throughout: EXISTS (in the repo today), PROVEN (done by other products, with a source), PROPOSED (new, to build). Web claims marked (fetched) were read on 2026-10-18; the others are from the author’s knowledge of the tools and should be re-read before a decision depends on them.

1. What exists in Zinc today (EXISTS)

Open backlog items touching this: ZN-729.04 (Review), ZN-347 (plugin update commands), ZN-714 / docs/reports/zinc-windows-port.md:220 (“update-app for Windows”), ZN-392 (prebuilt player runtime per target), ZN-391 (file type registration). later.md lines from ZN-729.04: engine update stops at “downloaded and verified”; deploy --key; trial window on a Pi 3.

Gaps that matter for this goal: (1) no signed update works for a fused or exported app without a zinc binary; (2) no delta, no progress, no staged rollout, no expiry/freeze protection in the app manifest (the TUF client exists but is not wired to apps); (3) no native runtime update; (4) no ESP32 OTA slot; (5) nothing for Android/iOS/webOS beyond the first install; (6) no key-generation/publication owner step done (release key empty).

2. State of the art (PROVEN) and what fits

3. Payload update versus runtime update

A Zinc app is program.zbc + resources.bin + assets/ + (native plugin libraries). The runtime is the engine (interpreter, host, plugins’ native code).

Decision: payload-first. The cheap and strong path for makers is a signed .zapp update with the runtime pinned by a runtime range in the manifest (“works with engine >= 0.9 < 1.0”); when the range is not satisfied the app offers the runtime update of its platform (table 3). Every change in plugins/*/native or the engine ABI makes a release of kind runtime (see manifest).

4. Per platform (comparison)

Columns: what is replaced, signature, rollback, user prompt, limits, effort. Effort S/M/L is for new work on top of what EXISTS.

5. Recommended single design (PROPOSED)

5.1 Principles

1. Payload first, runtime second; both use the same manifest, signature and rollback code.
2. Keep the existing Ed25519 manifest as the maker default. Add TUF only for the engine and official channels (client exists).
3. No server needed: a channel is a directory of static files (GitHub Releases, S3, any web server, file://, the agent on the LAN).
4. Every update is checked, staged, trialled and reversible; the app says healthy().

5.2 Manifest (extends the EXISTING key=value text, sig= last)

Keep the format tc::signManifest already signs; add keys, ignored by old clients (they still verify the whole text):

app=dev.zinc.music
channel=stable
version=1.4.0
seq=57                         # monotonic; client refuses seq < installed (rollback and replay protection)
expires=2027-01-18T00:00:00Z   # client refuses a stale manifest (freeze protection); republish to renew
kind=payload                   # payload | runtime
runtime=>=0.9 <1.0             # engine range the payload needs
min_version=1.2.0              # below this, a full download is required (no delta chain)
url=music-1.4.0.zapp           # relative to the manifest (EXISTS)
sha256=...                     # EXISTS
size=2410000
patch.from=1.3.2               # optional delta (see 5.4)
patch.url=music-1.3.2-1.4.0.zpatch
patch.sha256=...
rollout=25                     # percent; client takes the update if hash(deviceId+app+seq) % 100 < rollout
notes=Spotify login fixed
runtime.macos-arm64=music-mac-1.4.0.zip       # only for kind=runtime or when a binary is also published
runtime.windows-x64.sha256=...
runtime.android-armv7.url=...
sig=<128 hex>                  # Ed25519 over the text without this line (EXISTS)

zinc publish writes it. For the official engine and plugin index, the same signed targets are carried in TUF metadata (tuf.cpp), so key rotation and compromise recovery exist where it matters.

5.3 Signing and keys

• Per app Ed25519 key (zinc update-keygen, EXISTS), public half in zinc.json; a manifest may carry a successor key, signed by the old one (the agent already allows “an update may carry a new key”, zinc-next-agent.md:193). Add a second backup key listed in zinc.json so a lost seed does not strand installs (Tauri’s warning, fetched above).
• OS-level signatures stay separate and are the owner’s (Developer ID, Authenticode, APK keystore, Apple team).
• Anti-rollback: seq + expires in every manifest, plus a per-device stored high-water mark.

5.4 Delta

Default: no delta for .zapp (a ZBC payload with assets is small; most weight is assets). For assets-heavy apps: file-level delta, using the .zapp’s per-file SHA-256 (EXISTS in manifest.json): send only members whose hash changed, as zinc dev --device already does (D115: “each save sends the members whose SHA-256 changed”). For runtimes: zstd --patch-from (needs window >= file, memory about the file size: fine on desktops, not on the Nexus 7 with 1 GB or an ESP32) or bsdiff; no delta on small boards. Always fall back to the full download when the base hash does not match (Sparkle does the same, fetched above).

5.5 Channels and rollout

stable, beta, any name: <channel>.manifest (EXISTS). Staged rollout by the rollout percent above; halting = republish with seq+1 pointing at the previous version (a “rollback release”), so clients that already updated can go back since seq still rises. The app picks its channel from zinc.json or a runtime setting.

5.6 Hosting

5.7 App API (zinc:update, PROPOSED; today it is zinc:system/update, same names kept)

import * as update from 'zinc:update';

export interface UpdateInfo {
  available: boolean; version: string; notes: string;
  kind: 'payload' | 'runtime'; size: number; delta: boolean; mandatory: boolean;
}
export type Progress = { phase: 'download' | 'verify' | 'stage'; done: number; total: number };

update.check(opts?: { channel?: string; url?: string }): Promise<UpdateInfo>; // non-blocking; throws UpdateError('signature'|'expired'|'network'|'older')
update.download(onProgress?: (p: Progress) => void): Promise<string>;         // verifies sha256, stages; resumable (HTTP Range)
update.apply(opts?: { when?: 'now' | 'idle' | 'next-start' }): Promise<void>;  // payload: restart on trial; runtime: hands over to the platform installer
update.healthy(): void;                  // keeps the version on trial (EXISTS)
update.rollback(): Promise<void>;        // back to the previous version (engine.prev / previous.zapp exist)
update.current(): { version: string; channel: string; onTrial: boolean };
update.on('available' | 'progress' | 'applied' | 'rolled-back', cb): void;

check/download must not block a frame (the museum app had to start a process for that: ZN-650.11 notes). Make them async host operations. A UI helper (<UpdateBanner/> in lib/std/kit) gives makers a ready button.

5.8 What it reuses

tc::signManifest, fetchManifest, downloadUpdate, verifyBytes (tc.h), chooseAppVersion and trial logic (ZN-324.02), plugins/system/update.ts and its permission update, the agent’s ota.cpp and its previous/trial scheme, src/tc/tuf.cpp, tools/index-repo, zinc.json update.*, zinc publish, zinc export/tools/package/tools/sign-macos, mDNS.

6. Ordered work items

7. Irreversible or outward-facing steps (owner steps)

• Generating and storing the release signing key for the engine (update.pub is empty) and each official app’s seed; losing a seed strands installs (Tauri doc, fetched).
• Creating the TUF root keys and their offline backups for the index (threshold choice).
• Publishing: zinc publish, GitHub releases, uploading to S3/itch.io, pushing to the git remote, App Store / TestFlight / Play uploads.
• Buying a Windows code-signing certificate or Azure Artifact Signing (zinc-windows-port.md:87), Apple Developer ID and notarization, an Android upload key.
• ESP32 eFuse anti-rollback and secure boot: burning eFuses cannot be undone.
• Deciding whether to ship ZBC logic hot updates in an App Store build (policy risk, 2.5.2).
• The real launchd load of the agent (ZN-729.04 criterion 1) on the development Mac.

8. Open questions worth a check before building

• Apple Developer Program License 3.3.2 wording on interpreted code (not re-read).
• Exact USER_ACTION_NOT_REQUIRED conditions and Android 14+ restrictions (the fetched page was truncated).
• Whether zstd --patch-from decompression fits in the memory of the Nexus 7 and the TouchPad for a runtime-sized file.
• Whether the Nexus 7 app (NativeActivity APK, docs/reports/zinc-next-android.md) can load a .zapp from app-private storage without a recompile (depends on AOT versus interpreter in that build).

Edit this page on GitHub ↗