P4-7: Files-on-demand gate — THIS is the v1.0 release #50

New issue

Open

opened 2026-09-10 18:10:49 +00:00 by Cordy · 1 comment

Cordy commented

2026-09-10 18:10:49 +00:00

Owner

Depends on P4-6. Closes phase 4 and ships the product.

This is the release. v1.0 means "it ships", and nothing ships until this gate passes. There
is no v1.0-then-v1.1 split — files-on-demand is part of the product, not a follow-up.

The bar

Same as #40's, and not lowered because this is "just" a storage optimisation. From a user's
point of view, a file that will not open is indistinguishable from a file that is gone.

72 hours of continuous real-world use across Windows, macOS and Linux with zero data loss,
zero mass hydration, and zero hung mounts.

Adversarial checklist

Mass-hydration hunt. Against a fully dehydrated 10,000-file tree, assert nothing
hydrates during: a full sync pass · antivirus scan · Windows Search / Spotlight indexing ·
a backup tool · grep -r · opening the folder and scrolling. Any one of these
downloading everything makes the feature worse than useless, and each is a real thing
that happens on a real machine.
Go offline, open a placeholder → clear message, no zero-byte file, no crash.
Start a 4 GB hydration, cancel halfway → no partial file, folder still usable.
Kill the process mid-hydration → restart recovers, no truncated file.
Fill the local disk during hydration → clear error, no corruption.
Edit a hydrated file offline, then reconnect → uploads normally, is not evicted first.
Run eviction with a file that has unsynced changes → that file survives.
Pin a folder, run "free up space" → pinned content stays.
Linux: kill the process, confirm no hung FUSE mount; ls in the folder still works.
Uninstall on each platform → no orphaned placeholders, no orphaned File Provider domain,
no hung mount.
Rename a folder containing placeholders → MOVE, no mass hydration.

Documentation (extends #43)

What files-on-demand is, in one paragraph, for a non-technical reader.
The offline caveat, stated prominently rather than buried. This is the support ticket
you will get most, and the fix is "pin it before you travel".
Pinning and freeing up space, per platform.
The macOS Finder-sidebar difference (#46).
Linux: the FUSE requirement, or the honest statement that the feature is unavailable there
if #47 chose option B.
Admin guide: the disk-budget policy keys.

Exit criteria — all must hold

72 continuous hours, three platforms, zero data loss, zero mass hydration.
Every adversarial case above behaves as designed.
No open issue labelled data-integrity.
Full phase-1 and phase-2 suites still green — the engine must be unchanged.
#40's entire gate re-run and passing against the phase-4 build. Most users will run
classic sync; adding placeholders must not cost them anything.
Documentation updated and published.

Then — ship it

Tag v1.0.0. First public release of the desktop client.
Publish the "Clients" page on swisscairn.ch — classic sync and files-on-demand, with
the platform caveats stated plainly rather than in a footnote.
Publish the user guide, admin deployment guide and troubleshooting docs (#43).
Update the handbook with the §8.3 network-behaviour statement: the server never phones
home; the client does exactly two optional things, both switchable off.
Close the phase-4-virtual-files milestone.

If the gate is not met

Do not ship. Extend the beta, or cut files-on-demand on the platform that is failing and
ship the other two — but do not ship a client that loses files. A file that will not open is a
lost file as far as the user is concerned, and this product's entire argument is that your data
stays intact and legible.

Depends on P4-6. Closes phase 4 and ships the product. **This is the release.** v1.0 means "it ships", and nothing ships until this gate passes. There is no v1.0-then-v1.1 split — files-on-demand is part of the product, not a follow-up. ## The bar Same as #40's, and **not lowered** because this is "just" a storage optimisation. From a user's point of view, a file that will not open is indistinguishable from a file that is gone. > **72 hours of continuous real-world use across Windows, macOS and Linux with zero data loss, > zero mass hydration, and zero hung mounts.** ## Adversarial checklist - [ ] **Mass-hydration hunt.** Against a fully dehydrated 10,000-file tree, assert nothing hydrates during: a full sync pass · antivirus scan · Windows Search / Spotlight indexing · a backup tool · `grep -r` · opening the folder and scrolling. **Any one of these downloading everything makes the feature worse than useless**, and each is a real thing that happens on a real machine. - [ ] Go offline, open a placeholder → clear message, no zero-byte file, no crash. - [ ] Start a 4 GB hydration, cancel halfway → no partial file, folder still usable. - [ ] Kill the process mid-hydration → restart recovers, no truncated file. - [ ] Fill the local disk during hydration → clear error, no corruption. - [ ] Edit a hydrated file offline, then reconnect → uploads normally, is not evicted first. - [ ] Run eviction with a file that has unsynced changes → **that file survives**. - [ ] Pin a folder, run "free up space" → pinned content stays. - [ ] Linux: kill the process, confirm no hung FUSE mount; `ls` in the folder still works. - [ ] Uninstall on each platform → no orphaned placeholders, no orphaned File Provider domain, no hung mount. - [ ] Rename a folder containing placeholders → MOVE, no mass hydration. ## Documentation (extends #43) - [ ] What files-on-demand is, in one paragraph, for a non-technical reader. - [ ] **The offline caveat, stated prominently rather than buried.** This is the support ticket you will get most, and the fix is "pin it before you travel". - [ ] Pinning and freeing up space, per platform. - [ ] The macOS Finder-sidebar difference (#46). - [ ] Linux: the FUSE requirement, or the honest statement that the feature is unavailable there if #47 chose option B. - [ ] Admin guide: the disk-budget policy keys. ## Exit criteria — all must hold - [ ] 72 continuous hours, three platforms, zero data loss, zero mass hydration. - [ ] Every adversarial case above behaves as designed. - [ ] No open issue labelled `data-integrity`. - [ ] Full phase-1 and phase-2 suites still green — the engine must be unchanged. - [ ] **#40's entire gate re-run and passing against the phase-4 build.** Most users will run classic sync; adding placeholders must not cost them anything. - [ ] Documentation updated and published. ## Then — ship it - [ ] Tag **`v1.0.0`**. First public release of the desktop client. - [ ] Publish the "Clients" page on swisscairn.ch — classic sync **and** files-on-demand, with the platform caveats stated plainly rather than in a footnote. - [ ] Publish the user guide, admin deployment guide and troubleshooting docs (#43). - [ ] Update the handbook with the §8.3 network-behaviour statement: the server never phones home; the client does exactly two optional things, both switchable off. - [ ] Close the `phase-4-virtual-files` milestone. ## If the gate is not met **Do not ship.** Extend the beta, or cut files-on-demand on the platform that is failing and ship the other two — but do not ship a client that loses files. A file that will not open is a lost file as far as the user is concerned, and this product's entire argument is that your data stays intact and legible.

Cordy added this to the phase-4-virtual-files milestone

2026-09-10 18:10:49 +00:00

Cordy added the

data-integrity

label

2026-09-10 18:10:49 +00:00

Cordy referenced this issue

2026-09-10 18:23:52 +00:00

P3-11: Private beta — internal gate, NOT the release #40

Cordy commented

2026-09-10 18:24:01 +00:00

Author

Owner

Amendment — 2026-09-10: this is the release

Decision: v1.0 means "it ships", and nothing ships until this milestone passes. The
open question about whether files-on-demand lands in v1.0 or v1.1 is closed — it is v1.0.
Everything is dogfooded until it is deemed ready, and readiness means done.

Replaces the "Then" section

Tag v1.0.0. This is the first public release of the desktop client.
Publish the "Clients" page on swisscairn.ch — describing classic sync and
files-on-demand, with the platform caveats stated plainly rather than in a footnote
(macOS Finder-sidebar placement; Linux FUSE requirement or its absence).
Update the handbook with the §8.3 network-behaviour statement.
Publish the user guide, admin deployment guide and troubleshooting docs (#43, extended
here with the files-on-demand sections).

The bar for shipping

Both gates must be green: #40's and this one. Phase 3's gate proves the sync engine; this
one proves placeholders on top of it. A regression in either blocks the release — a phase-1
property test going red is as much a shipping blocker as a hung FUSE mount.

Add to the exit criteria:

Phase 3's gate (#40) still passes against the phase-4 build. Adding placeholders must not
have broken classic sync for users who never enable files-on-demand.

That last one matters more than it looks: most users will run classic sync, and phase 4 must not
cost them anything.

## Amendment — 2026-09-10: this is the release **Decision: v1.0 means "it ships", and nothing ships until this milestone passes.** The open question about whether files-on-demand lands in v1.0 or v1.1 is closed — it is v1.0. Everything is dogfooded until it is deemed ready, and readiness means done. ### Replaces the "Then" section - [ ] Tag **`v1.0.0`**. This is the first public release of the desktop client. - [ ] Publish the "Clients" page on swisscairn.ch — describing classic sync **and** files-on-demand, with the platform caveats stated plainly rather than in a footnote (macOS Finder-sidebar placement; Linux FUSE requirement or its absence). - [ ] Update the handbook with the §8.3 network-behaviour statement. - [ ] Publish the user guide, admin deployment guide and troubleshooting docs (#43, extended here with the files-on-demand sections). ### The bar for shipping **Both gates must be green: #40's and this one.** Phase 3's gate proves the sync engine; this one proves placeholders on top of it. A regression in either blocks the release — a phase-1 property test going red is as much a shipping blocker as a hung FUSE mount. Add to the exit criteria: - [ ] Phase 3's gate (#40) still passes against the phase-4 build. Adding placeholders must not have broken classic sync for users who never enable files-on-demand. That last one matters more than it looks: most users will run classic sync, and phase 4 must not cost them anything.

Cordy referenced this issue

2026-09-10 18:29:51 +00:00

P3-11: Private beta — internal gate, NOT the release #40

Cordy changed title from ~~P4-7: Files-on-demand beta gate and documentation~~ to P4-7: Files-on-demand gate — THIS is the v1.0 release

2026-09-10 18:30:05 +00:00