v0.6.347: versions record every save before publishing it (#922); NFD folders reachable after take-over (#934) #952

Merged
Cordy merged 28 commits from fix-922 into main 2026-10-17 02:10:37 +00:00
Owner

What

#922: record, then publish

  • Every save now keeps its own content as a version record first, then publishes it.
  • A short in-process commit step (versions.PathSerializer) checks that the content being replaced has a record, and records it if it has none.
  • Keys are YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ_<12 random digits>[a|u]_<author>.v, ordered by time.
  • Identity per backend:
    • posix: hard link, or copy mode found by a boot probe;
    • s3: x-amz-meta-cairn-record, with a boot probe that chooses copy, put or none mode.
  • The current content's record is hidden from the Versions list.
  • A one-hour prune grace protects saves still in flight, and a remake after 30 minutes covers the cross-instance window.
  • A version's age now counts from when it was replaced.
  • The key drain keeps a file and its record as one identity and yields to client saves.

#934

  • Both drivers resolve each path segment in either Unicode form.
  • A take-over creates the space under the NFC name and keeps the NFD folder.
  • The empty NFC twin is removed at boot.

Faults on main (Task 1 probes, all failing on 8a20c218)

  • TestFault922Reproduces: live345 olga-2-IMPORTANT lost on 4/4 variants; 12-in-a-second lists w4 w3 w2; stress loses 47–112 of 161, plus "no free version key" refusals.
  • TestFault922TwinReproduces: the same across two stacks.
  • TestFault934Reproduces: take-over 201 with the NFD name, then 404s.
  • TestFault934S3TwinPrefix: a new file in an NFD folder hides the old files.

All four pass on the branch.

Rulings (spec docs/superpowers/specs/2026-10-16-fix-922-design.md §3.2)

  • R1: unique random-token keys, ordered by time.
  • R2: every Cairn write records, new files included.
  • R3: if only the write's own record fails, the write publishes unrecorded (WARN + counter).
  • R4: a refusal after the body keeps the body as a u version, which feeds the WOPI rescue.
  • R5: an identical save leaves the file untouched.
  • R6: the author is the person who saved that content.
  • R7: coalescing removes only the person's own replaced autosave.
  • R8: S3 identity via object metadata plus a boot probe.
  • R9: posix identity is open+fstat, with link or copy mode.
  • R10: prune exempts the current record and the write's own record.
  • R11: a copy records into the destination's chain.
  • R12: rename holds both paths.
  • R13: no fallback; start refused without Recorder.
  • R14: serializer interface for #742.
  • R15: current record hidden.
  • R16: legacy keys kept; the metric cause other is gone.
  • R17: the drain keeps identity.
  • R18: size counts a hard link once.
  • R19: per-segment Unicode resolution.
  • R20: NFC names, SameName.
  • R21: backups keep hard links.
  • R22: ADR amended for hard links.

Review-round rulings (all in the SDD ledger):

  • the 1 h grace;
  • remake under a fresh key, timed from naming;
  • age from replacement, with legacy and u rules;
  • drain yields to saves (serializer + identity check + head tee);
  • a failed rename keeps the destination snapshot;
  • a held path keeps the refusal key;
  • the mark takes the path lock again.

Changed pre-existing tests (each with its reason in the task reports)

  • Named in spec §8:
    • TestKeySearchStatError replaced by TestRecordOfStatError
    • TestNameTooLong (87-byte key)
    • versions902:434 (token)
    • finalize908:140
    • TestKeyRoundTrip
    • mintcopy908 (asserts a link on posix)
    • TestMergeMarkedSeqTaken and TestMergeNameClash (fresh token)
    • TestCoalesceSkips and TestCoalesceOnlyAfterAutosaveMint (R7/R3)
  • Seed written unrecorded, so the pre-image refusal path is still exercised (R3 would otherwise publish):
    • versionbell908, versions908, wopi908
    • stacktest_test (RigFault*, RigLog)
    • failclosed908: FailClosedWrite, NothingToKeep, SameContentWriteMintFailureRefused, WarnRateLimited*, MintVanishedAtOpen
    • api/failclosed908, which now pins the exact WARN lines
    • dav/matrix908
    • tus/finalize908
  • Wrap returns an error (R13): onrefusedwire908 and the stacktest order parser; ocm/grant908 embeds *posix.Driver.
  • Hidden current record:
    • TestRigRoundTrip and TestRigReopen (2 raw entries)
    • TestDeleteDropsChainHeldKeeps
    • TestMergeListErrorKeepsChain
  • Record grace:
    • atcap908 seeds at the cap
    • TestSameContentWriteAtCapKeepsChain and TestPruneCountCap set the grace to 1 ns
  • R7 moved the autosave mark: versions902:298.
  • Weakened, accepted under ruling D4: overwrite908 TestFailedRenameLeavesNoMint allows one extra listed version on s3.
  • Goldens are unchanged.

Garage

  • Probe P8 was not run by hand. Cairn's own boot probe makes the same check (PUT + HEAD + CopyObject COPY/REPLACE) at every start and logs the mode.
  • files-bao's boot line after the bump is the result. If it is none, I stop and report before going further.

Checks

  • Tests:
    • go test ./... passes (62 packages).
    • -race passes on Race922/Twin/Drain/Age.
    • vet is clean.
    • windows/darwin builds pass.
  • Local live check (scratch/b7e/live347/report.md):
    • v0.6.346 faults reproduced: t_5x 3/3 lost; 12 saves lose w5..w11; the #934 404s.
    • Branch: every check passes:
      • t_5x 3/3;
      • same-content ETag and Last-Modified unchanged;
      • WOPI refusal plus rescue;
      • restore;
      • all #934 rows;
      • two instances on one data root: t_5x 3/3, stress 480 writes, 0 lost, 0 refused, identical lists.

Follow-up issues filed during this work

#939 #940 #941 #942 #943 #944 #945 #946 #947 #948 #949 #950 #951

Closes #922, closes #934 (after the dogfood checks).

## What **#922: record, then publish** - Every save now keeps its own content as a version record first, then publishes it. - A short in-process commit step (`versions.PathSerializer`) checks that the content being replaced has a record, and records it if it has none. - Keys are `YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ_<12 random digits>[a|u]_<author>.v`, ordered by time. - Identity per backend: - posix: hard link, or copy mode found by a boot probe; - s3: `x-amz-meta-cairn-record`, with a boot probe that chooses copy, put or none mode. - The current content's record is hidden from the Versions list. - A one-hour prune grace protects saves still in flight, and a remake after 30 minutes covers the cross-instance window. - A version's age now counts from when it was replaced. - The key drain keeps a file and its record as one identity and yields to client saves. **#934** - Both drivers resolve each path segment in either Unicode form. - A take-over creates the space under the NFC name and keeps the NFD folder. - The empty NFC twin is removed at boot. ## Faults on main (Task 1 probes, all failing on 8a20c218) - `TestFault922Reproduces`: live345 `olga-2-IMPORTANT` lost on 4/4 variants; 12-in-a-second lists w4 w3 w2; stress loses 47–112 of 161, plus "no free version key" refusals. - `TestFault922TwinReproduces`: the same across two stacks. - `TestFault934Reproduces`: take-over 201 with the NFD name, then 404s. - `TestFault934S3TwinPrefix`: a new file in an NFD folder hides the old files. All four pass on the branch. ## Rulings (spec `docs/superpowers/specs/2026-10-16-fix-922-design.md` §3.2) - **R1:** unique random-token keys, ordered by time. - **R2:** every Cairn write records, new files included. - **R3:** if only the write's own record fails, the write publishes unrecorded (WARN + counter). - **R4:** a refusal after the body keeps the body as a `u` version, which feeds the WOPI rescue. - **R5:** an identical save leaves the file untouched. - **R6:** the author is the person who saved that content. - **R7:** coalescing removes only the person's own replaced autosave. - **R8:** S3 identity via object metadata plus a boot probe. - **R9:** posix identity is open+fstat, with link or copy mode. - **R10:** prune exempts the current record and the write's own record. - **R11:** a copy records into the destination's chain. - **R12:** rename holds both paths. - **R13:** no fallback; start refused without `Recorder`. - **R14:** serializer interface for #742. - **R15:** current record hidden. - **R16:** legacy keys kept; the metric cause `other` is gone. - **R17:** the drain keeps identity. - **R18:** size counts a hard link once. - **R19:** per-segment Unicode resolution. - **R20:** NFC names, `SameName`. - **R21:** backups keep hard links. - **R22:** ADR amended for hard links. Review-round rulings (all in the SDD ledger): - the 1 h grace; - remake under a fresh key, timed from naming; - age from replacement, with legacy and `u` rules; - drain yields to saves (serializer + identity check + head tee); - a failed rename keeps the destination snapshot; - a held path keeps the refusal key; - the mark takes the path lock again. ## Changed pre-existing tests (each with its reason in the task reports) - **Named in spec §8:** - `TestKeySearchStatError` replaced by `TestRecordOfStatError` - `TestNameTooLong` (87-byte key) - `versions902:434` (token) - `finalize908:140` - `TestKeyRoundTrip` - `mintcopy908` (asserts a link on posix) - `TestMergeMarkedSeqTaken` and `TestMergeNameClash` (fresh token) - `TestCoalesceSkips` and `TestCoalesceOnlyAfterAutosaveMint` (R7/R3) - **Seed written unrecorded, so the pre-image refusal path is still exercised (R3 would otherwise publish):** - versionbell908, versions908, wopi908 - stacktest_test (RigFault*, RigLog) - failclosed908: FailClosedWrite, NothingToKeep, SameContentWriteMintFailureRefused, WarnRateLimited*, MintVanishedAtOpen - api/failclosed908, which now pins the exact WARN lines - dav/matrix908 - tus/finalize908 - **`Wrap` returns an error (R13):** onrefusedwire908 and the stacktest order parser; ocm/grant908 embeds `*posix.Driver`. - **Hidden current record:** - `TestRigRoundTrip` and `TestRigReopen` (2 raw entries) - `TestDeleteDropsChainHeldKeeps` - `TestMergeListErrorKeepsChain` - **Record grace:** - atcap908 seeds at the cap - `TestSameContentWriteAtCapKeepsChain` and `TestPruneCountCap` set the grace to 1 ns - **R7 moved the autosave mark:** versions902:298. - **Weakened, accepted under ruling D4:** overwrite908 `TestFailedRenameLeavesNoMint` allows one extra listed version on s3. - Goldens are unchanged. ## Garage - Probe P8 was not run by hand. Cairn's own boot probe makes the same check (PUT + HEAD + CopyObject COPY/REPLACE) at every start and logs the mode. - files-bao's boot line after the bump is the result. If it is `none`, I stop and report before going further. ## Checks - **Tests:** - `go test ./...` passes (62 packages). - `-race` passes on Race922/Twin/Drain/Age. - vet is clean. - windows/darwin builds pass. - **Local live check** (`scratch/b7e/live347/report.md`): - **v0.6.346 faults reproduced:** t_5x 3/3 lost; 12 saves lose w5..w11; the #934 404s. - **Branch:** every check passes: - t_5x 3/3; - same-content ETag and Last-Modified unchanged; - WOPI refusal plus rescue; - restore; - all #934 rows; - two instances on one data root: t_5x 3/3, stress 480 writes, 0 lost, 0 refused, identical lists. ## Follow-up issues filed during this work #939 #940 #941 #942 #943 #944 #945 #946 #947 #948 #949 #950 #951 Closes #922, closes #934 (after the dogfood checks).
Task 6 fix round 1 (C1, I1, I2, I3, M1 to M5, D1):
- prune: the count cap spares records within RecordGrace (1h) of the
  pruning write's own record; in-flight records (pending, newer than own)
  take no slot of the cap.
- commit: a save whose record is older than RecordGrace/2 checks it under
  the lock and makes it again before the publish (RecordPlan.Again; posix
  link or copy of the temp, s3 PUT from the spool or CopyObject from the
  copy's source); failing that, R3 with cause record-lost.
- the pending mark is set when the record is named, before it is made.
- rename records an unrecorded source first, so the chain carries it.
- R5 also after a step-1 snapshot when the file's identity names it
  (posix); versions marks the write unchanged and ownermeta keeps the
  manifest, so Last-Modified and ETag stay.
- posix copy mode: RecordOf answers the newest matching record.
- s3: a record gone at the publish is recorded again once; never 404.
A remake held after its record is made again, before its publish, on one fake engine clock shared by three instances (straddle and slow record step, all 9 rows); the remake age is taken from Engine.now (time.Now, monotonic, when Now is unset). The rig gains BaseHook.AgainHook. An s3 copy onto a file whose source vanished answers not-found and reports no write published without its record (R3).
The drain rewrites a recorded file with its record under the same name (WriteRecorded, Replace; Renew when the s3 publish finds the record gone) and skips that record in its walk. main opens the base driver through openBase (posix logs its record mode, s3 probes the store and a failed probe refuses the start) and builds the chain below versions through storageChain; versions.Wrap also requires the base driver (Raw) to record writes, since reserved and encrypt always have the methods. OnUnrecorded feeds cairn_versions_unrecorded_writes_total{cause}.
Task 7 fix round 1. The drain commits under the versions engine's
serializer (main shares one object) and publishes only while the file
has the identity taken before its read; a skipped file is not counted
as moved. Every file goes through WriteRecorded, writeDirect through
the base driver's. A record is taken for the file's only when both
begin with the same bytes. A failed s3 record probe logs its own line
and runs under a 30 s deadline. Spec 5.11: the cross-instance window.
The record that keeps the body of a write refused at its commit step (R4, Unpublished) is renamed after the lock to its key with the mark u in place of the autosave mark, so keys stay within 87 bytes. ageCut skips u entries as the next newer entry and ages them from their own key time; Unpublished names the marked key. A failed rename keeps the first key, with the WARN 'versions: unpublished version not marked'. mergeKey keeps any mark and checks all three mark forms. Tests: TestAgeIgnoresRefusedRecord, TestRefusedMarkFails, TestAgeCurrentRecordNotNewest, TestAgeNewestVersionKept, TestUnpubKeyGrammar; stacktest Fault.RenameHook.
Cordy merged commit 760d7c1da1 into main 2026-10-17 02:10:37 +00:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: Cordy/Cairn#952
No description provided.