abstraction-cas 0.1.0__tar.gz

abstraction_cas-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 the openabstractions contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

abstraction_cas-0.1.0/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: abstraction-cas
+Version: 0.1.0
+Summary: Compare-and-set over a file. The floor under every service that keeps state in a file.
+License-Expression: Apache-2.0
+Project-URL: Source, https://github.com/openabstractions/abstraction-cas
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# abstraction-cas
+
+**In development.** Tagged `go/v0.1.0`, but this page predates that tag: no
+capability claim, no contract page, no conformance scenario of its own.
+
+A file is replaced whole or not at all, and every change is applied to the value
+the previous change left — across processes and across languages sharing one
+kernel.
+
+## The problem
+
+Every service that keeps state in a file rewrites it, and two writers on one
+file lose each other's updates unless they agree on a lock and a rename. Each
+service of ours hand-rolled its own writer. This is the floor under all of them:
+one lock, one rename, one implementation per language we ship. Not a
+layer — no contract page, no capability claim. A stranger implementing `job`
+needs its page, not this.
+
+## Words
+
+| word | meaning |
+|---|---|
+| **read** | the whole file, or nothing when there is none |
+| **write** | replace the file only if it still holds `base`; else `Moved` |
+| **change** | read, edit and write under the lock, so an edit always sees the truth and never needs a retry |
+| **base** | the value a writer read; `nil` means *only if the file does not exist* |
+| **lock** | byte 0 of `<path>.lock`, exclusive, blocking, released by the kernel when the holder dies |
+
+No rule on this page carries a tag. The invariants below each carry a test, and
+*What a fourth implementation must do* is cited by
+[the job page](https://github.com/openabstractions/abstraction-job).
+
+## Obtain
+
+- **Go.** `go get github.com/openabstractions/abstraction-cas/go`. No tag yet;
+  `go get` resolves a pseudo-version of `main`.
+- **Python.** Not on any index. `python/abstraction_cas.py` is one module with
+  no imports of ours; `python/pyproject.toml` builds a wheel
+  (`pip wheel python/`).
+- **C++.** One header and one source, C++17, standard library only, and no build
+  file: name them. `g++ -std=c++17 -I cpp/include cpp/test/test_cas.cpp
+  cpp/src/cas.cpp -o test_cas` compiles and passes this layer's own test; MSVC
+  19.51 takes the same two files under `/std:c++17` and `/I`. Measured
+  2026-09-09. There
+  is no tagged release and no package.
+
+## Example
+
+```go
+import cas "github.com/openabstractions/abstraction-cas/go"
+
+err := cas.Change(path, func(cur []byte) ([]byte, error) {
+    var f file
+    if cur != nil {
+        json.Unmarshal(cur, &f)
+    }
+    f.Apps = append(f.Apps, app)
+    return json.Marshal(f)
+})
+```
+
+`Read` returns the whole file, or `nil` when there is none. `Write(path, base,
+data)` replaces the file only if it still holds `base` (`nil`: only if it does
+not exist), else `ErrMoved`. `Change` reads, edits and writes under the lock, so
+an edit always sees the truth and never needs a retry.
+
+The same three calls in `python/abstraction_cas.py` (`read`, `write`, `change`,
+`None` for missing, `Moved`) and `cpp/include/abstraction/cas.h` (`std::nullopt`
+for missing, `Moved` thrown, an edit refuses by throwing). All three share one
+lock and one rename, so writers in different languages on one file do not lose
+each other's updates; `mixed.py` proves it and `scripts/check.sh` runs it.
+
+## Invariants, each with a test in `go/cas_test.go`, `python/test_abstraction_cas.py`, `cpp/test/test_cas.cpp`
+
+- **Whole or nothing.** A reader at any moment, from any process, sees a value
+  some writer wrote in full. Never a partial file, never a mixture.
+- **No lost update.** Every successful `Change` was applied to the value left
+  by the previous successful one, across goroutines and across processes.
+- **A stale base is refused** and leaves the file untouched.
+- **An ended record stays ended.** An edit that refuses on what it reads is
+  refusing on the truth, so nothing can be walked backwards by a writer that
+  read earlier.
+- **Nothing left behind.** Contention and refusal leave no temporary files.
+
+## How
+
+The data is staged in a temporary file beside the target, fsynced, and renamed
+over it, under the lock the contract below names, which the kernel releases
+when the holder dies — no lock is ever broken by a timeout. On Windows every
+read opens with `FILE_SHARE_DELETE` and the rename is `FileRenameInfoEx` with
+POSIX semantics, so a reader of ours never blocks a replace; Go gets both from
+`os.Root`, Python and C++ call them. A Samba share answers `FileRenameInfoEx`
+with `ERROR_INVALID_PARAMETER`, flag or no flag, so there the fallback runs on
+every write — `MoveFileEx` in Python and C++, `FileRenameInformation` in Go —
+and a reader does block a replace; see below.
+
+**The lock is one machine's.** A byte-range lock taken over SMB and a `flock`
+taken on the server's own volume never meet: writers on the PC and on the NAS
+on one file lost or refused 147–149 of 2150 updates in three runs of three,
+every PC writer dying within its first few changes
+(`feedback/2026-09-06-shareloc.md`, harness `research/locks/twohost.py`). Six
+writers in three languages on the PC alone, over the same share, lost nothing
+in 1800. Two hosts on one record need a protocol this file does not have.
+
+## What a fourth implementation must do
+
+Two implementations on one file agree on the bytes they write and on the way
+they keep each other out. Every single-language test proves the first only: a
+writer with another lock passes all of them and loses updates against ours.
+
+- **The lock is byte 0 of `<path>.lock`, exclusive, blocking, no timeout.**
+  The lock file sits beside the data file, is opened read-write and created
+  `0600` when missing, and is never written, truncated or deleted: a deleted
+  lock file is a new inode, and holders of two inodes exclude nobody. Windows
+  is `LockFileEx(LOCKFILE_EXCLUSIVE_LOCK)` at offset 0, length 1. POSIX is
+  `flock(LOCK_EX)`. Not `fcntl`, `lockf` or an OFD lock: on Linux those are a
+  separate lock table, invisible to `flock`. Not `msvcrt.locking`: it retries
+  once a second and fails after ten.
+- **`Write` and `Change` hold it from before the read to after the rename.
+  `Read` never takes it.**
+- **Missing and empty are different values**, and a `Change` between them
+  writes.
+- **The replacement is a fresh temporary file in the same directory, fsynced,
+  renamed over `<path>`.** The name is unique to the writer — `CreateTemp`,
+  `mkstemp`, `CREATE_NEW` — so two languages staging at once never open each
+  other's file. Windows is `FileRenameInfoEx` with `REPLACE_IF_EXISTS |
+  POSIX_SEMANTICS`, falling back to `MoveFileEx(REPLACE_EXISTING)` where the
+  volume refuses the flags; `ERROR_SHARING_VIOLATION` and `ERROR_ACCESS_DENIED`
+  are retried a bounded number of times, then returned with the temporary
+  removed. POSIX is `rename(2)`.
+- **`Read` opens with every share mode on Windows** and holds the handle for
+  the read only.
+
+Prove it by being the seventh process in `mixed.py`: a program that, given
+`CAS_PATH`, `CAS_ROLE` and `CAS_N`, applies `CAS_N` increments of the `"n n"`
+counter as a `writer` or reads until it sees `CAS_N` as a `reader`, aborting on
+a torn read. Add its command to `commands()`; the run counts its updates with
+ours. A fourth implementation whose lock ours cannot see loses a third of its
+updates on the first run — measured with a Python writer on byte 1 on Windows
+and on `lockf` on Linux, in `feedback/2026-09-06-mixedgate.md`. `mixed.py`
+takes a directory as its second argument; a UNC path runs the six on a share.
+
+## Today
+
+Go, Python and C++, each the three calls. Consumed by `job`'s file store,
+`config`, `rights` and `asks`.
+
+What may break:
+
+- A handle on the data file without delete sharing — an editor, `type`,
+  Python's `open()` — makes a Windows replace fail with `ERROR_SHARING_VIOLATION`
+  for as long as it is held. The writer retries 1000 times — 160 to 470 ms on
+  local NTFS, process start included, the same in all three languages — then
+  returns the error with nothing left behind; the lock was held throughout, so
+  no other writer's update is lost, and the file still holds the previous
+  value. A handle opened with `FILE_SHARE_DELETE` keeps reading the bytes it
+  opened while the rename succeeds under it, 2 ms measured.
+- Over SMB every open handle on the data file blocks the replace, ours
+  included, share-delete or not, from the same client or another process on
+  it: the fallback rename fails with `ERROR_ACCESS_DENIED`, 11 to 126 ms a
+  try, so the 1000 tries last 25 s in Python and 31 s in C++ under a held
+  handle, and Go's `os.Root` rename does not return at all — killed at 90 s,
+  its temporary left behind. A reader that polls keeps the tries failing for as
+  long as it polls: six writers and three readers of ours on one share stalled
+  at 85 and 50 of 600, C++ and Python returned the error, Go never returned. A
+  process on the server holding the file open blocks nothing,
+  and the server's own rename is never blocked. `Read` over SMB can itself
+  fail with `ERROR_ACCESS_DENIED` on open while the server renames underneath
+  it, rather than returning either value.
+- Every write is an fsync: about 6 ms on this machine. Right for a policy file
+  written at human rate; wrong for a lease renewed every millisecond.
+- **Python flushes the directory after the rename; Go and C++ do not yet.**
+  Without that flush a power cut can lose the rename: the previous value
+  survives, the acknowledged one may not. Python opens the directory and
+  flushes it — `fsync` on POSIX, `FlushFileBuffers` on a
+  `FILE_FLAG_BACKUP_SEMANTICS` handle on Windows — and raises anything it does
+  not recognise. Where the volume answers `ERROR_INVALID_FUNCTION`,
+  `ERROR_NOT_SUPPORTED` or `ERROR_ACCESS_DENIED` — Samba over SMB is the one we
+  have met — the write is acknowledged without that guarantee. The flush costs
+  0.1 ms on NTFS, 1.7 ms on ext4 and 33 ms on the NAS's btrfs. What it buys is
+  the rename reaching the disk, not that the file system would have lost it
+  without it: whether NTFS, ext4, btrfs or APFS keep the rename anyway is a
+  power-cut test nobody has run.
+- A writer killed between staging and renaming — power cut, `TerminateProcess`,
+  `SIGKILL` — leaves one `<name>.<unique>.tmp` beside the file. The data file
+  is untouched and still holds its previous value, and nothing removes the
+  temporary on the write path: finding it means reading the directory, which
+  would cost every write the directory's size. The name is the sweeper's
+  handle — anything matching `<name>.*.tmp` beside the file is dead, because a
+  live writer stages under the lock. Python's `sweep(path)` takes that lock and
+  removes them, and returns how many; Go and C++ have no such call yet.
+- A reader that polls is a tax on every writer of the file on Windows: 4.4 ms
+  per update alone, 6 to 16 ms with one reader spinning, from open-close
+  contention on the name and not from the rename retry.
+- The names we derive are longer than the one you gave us — `<path>.lock` and
+  `<path>.XXXXXXXX.tmp` — so on Windows with `LongPathsEnabled = 0` a path a
+  bare `open()` accepts can be one `cas` cannot. **Python prefixes `\\?\` once
+  the staged name would pass `MAX_PATH`, and Go's own `os` package does the
+  same for it, so both take every path a bare `open()` takes and some it does
+  not; C++ refuses from 246 characters up, where `open()` still works.**
+- An edit that calls `write`, `change` or `sweep` on the file it is editing
+  cannot be served: the lock is held and a second handle on it is another
+  holder, so the call would wait for itself. **Python raises `Reentrant`; Go
+  and C++ block forever with no message.** Nesting on a different file is fine
+  and is how a record and its index are written together.
+- An edit that returns no value where the file holds one is refused —
+  `NoValue` in Python, `ErrNoValue` in Go — and the file is left as it was. It
+  is not a way to empty a file (write an empty value) or to delete one (there
+  is no delete). An edit that returns what it was given changes nothing, and on
+  a missing file that means the file stays missing. C++ cannot express it: its
+  `Edit` returns `std::string`.
+- The lock file stays. Delete the data file and `<path>.lock` together.
+
+## Conformance
+
+[`mixed.py`](mixed.py): two Go, two C++ and two Python writers making 100
+changes each to one file whose name is the last line of
+[`names.list`](names.list) — an emoji, a CJK pair, a macron and a combining
+acute, because until 2026-09-09 no test in any language used a file name longer
+than one ASCII letter and the Windows rename in Python had been counting code
+points where the kernel counts UTF-16 units — a reader per language spinning
+through every rename —
+[`CAS-MIXED1.txt`](https://github.com/openabstractions/abstractions/blob/main/docs/results/CAS-MIXED1.txt).
+Windows; macOS `UNPROVEN`. Each language's own tests are named above.
+
+## Where it sits
+
+Below: nothing of ours. Above:
+[abstraction-job](https://github.com/openabstractions/abstraction-job) writes
+every record through it, and
+[abstraction-config](https://github.com/openabstractions/abstraction-config),
+[abstraction-asks](https://github.com/openabstractions/abstraction-asks) and
+[abstraction-rights](https://github.com/openabstractions/abstraction-rights)
+keep their files with it.
+
+One layer of [openabstractions](https://github.com/openabstractions/abstractions).
+Every layer names one thing local tools rebuild on their own; the name means the
+same in each language that implements it, and the conformance scenarios are what
+hold an implementation to it.
+
+## Requirements
+
+Go 1.25 or newer, standard library only. Python 3.9 or newer, standard library
+only. C++17.
+
+## Licence
+
+Apache-2.0. See [LICENSE](https://github.com/openabstractions/abstraction-cas/blob/main/LICENSE).

abstraction_cas-0.1.0/README.md

@@ -0,0 +1,248 @@
+# abstraction-cas
+
+**In development.** Tagged `go/v0.1.0`, but this page predates that tag: no
+capability claim, no contract page, no conformance scenario of its own.
+
+A file is replaced whole or not at all, and every change is applied to the value
+the previous change left — across processes and across languages sharing one
+kernel.
+
+## The problem
+
+Every service that keeps state in a file rewrites it, and two writers on one
+file lose each other's updates unless they agree on a lock and a rename. Each
+service of ours hand-rolled its own writer. This is the floor under all of them:
+one lock, one rename, one implementation per language we ship. Not a
+layer — no contract page, no capability claim. A stranger implementing `job`
+needs its page, not this.
+
+## Words
+
+| word | meaning |
+|---|---|
+| **read** | the whole file, or nothing when there is none |
+| **write** | replace the file only if it still holds `base`; else `Moved` |
+| **change** | read, edit and write under the lock, so an edit always sees the truth and never needs a retry |
+| **base** | the value a writer read; `nil` means *only if the file does not exist* |
+| **lock** | byte 0 of `<path>.lock`, exclusive, blocking, released by the kernel when the holder dies |
+
+No rule on this page carries a tag. The invariants below each carry a test, and
+*What a fourth implementation must do* is cited by
+[the job page](https://github.com/openabstractions/abstraction-job).
+
+## Obtain
+
+- **Go.** `go get github.com/openabstractions/abstraction-cas/go`. No tag yet;
+  `go get` resolves a pseudo-version of `main`.
+- **Python.** Not on any index. `python/abstraction_cas.py` is one module with
+  no imports of ours; `python/pyproject.toml` builds a wheel
+  (`pip wheel python/`).
+- **C++.** One header and one source, C++17, standard library only, and no build
+  file: name them. `g++ -std=c++17 -I cpp/include cpp/test/test_cas.cpp
+  cpp/src/cas.cpp -o test_cas` compiles and passes this layer's own test; MSVC
+  19.51 takes the same two files under `/std:c++17` and `/I`. Measured
+  2026-09-09. There
+  is no tagged release and no package.
+
+## Example
+
+```go
+import cas "github.com/openabstractions/abstraction-cas/go"
+
+err := cas.Change(path, func(cur []byte) ([]byte, error) {
+    var f file
+    if cur != nil {
+        json.Unmarshal(cur, &f)
+    }
+    f.Apps = append(f.Apps, app)
+    return json.Marshal(f)
+})
+```
+
+`Read` returns the whole file, or `nil` when there is none. `Write(path, base,
+data)` replaces the file only if it still holds `base` (`nil`: only if it does
+not exist), else `ErrMoved`. `Change` reads, edits and writes under the lock, so
+an edit always sees the truth and never needs a retry.
+
+The same three calls in `python/abstraction_cas.py` (`read`, `write`, `change`,
+`None` for missing, `Moved`) and `cpp/include/abstraction/cas.h` (`std::nullopt`
+for missing, `Moved` thrown, an edit refuses by throwing). All three share one
+lock and one rename, so writers in different languages on one file do not lose
+each other's updates; `mixed.py` proves it and `scripts/check.sh` runs it.
+
+## Invariants, each with a test in `go/cas_test.go`, `python/test_abstraction_cas.py`, `cpp/test/test_cas.cpp`
+
+- **Whole or nothing.** A reader at any moment, from any process, sees a value
+  some writer wrote in full. Never a partial file, never a mixture.
+- **No lost update.** Every successful `Change` was applied to the value left
+  by the previous successful one, across goroutines and across processes.
+- **A stale base is refused** and leaves the file untouched.
+- **An ended record stays ended.** An edit that refuses on what it reads is
+  refusing on the truth, so nothing can be walked backwards by a writer that
+  read earlier.
+- **Nothing left behind.** Contention and refusal leave no temporary files.
+
+## How
+
+The data is staged in a temporary file beside the target, fsynced, and renamed
+over it, under the lock the contract below names, which the kernel releases
+when the holder dies — no lock is ever broken by a timeout. On Windows every
+read opens with `FILE_SHARE_DELETE` and the rename is `FileRenameInfoEx` with
+POSIX semantics, so a reader of ours never blocks a replace; Go gets both from
+`os.Root`, Python and C++ call them. A Samba share answers `FileRenameInfoEx`
+with `ERROR_INVALID_PARAMETER`, flag or no flag, so there the fallback runs on
+every write — `MoveFileEx` in Python and C++, `FileRenameInformation` in Go —
+and a reader does block a replace; see below.
+
+**The lock is one machine's.** A byte-range lock taken over SMB and a `flock`
+taken on the server's own volume never meet: writers on the PC and on the NAS
+on one file lost or refused 147–149 of 2150 updates in three runs of three,
+every PC writer dying within its first few changes
+(`feedback/2026-09-06-shareloc.md`, harness `research/locks/twohost.py`). Six
+writers in three languages on the PC alone, over the same share, lost nothing
+in 1800. Two hosts on one record need a protocol this file does not have.
+
+## What a fourth implementation must do
+
+Two implementations on one file agree on the bytes they write and on the way
+they keep each other out. Every single-language test proves the first only: a
+writer with another lock passes all of them and loses updates against ours.
+
+- **The lock is byte 0 of `<path>.lock`, exclusive, blocking, no timeout.**
+  The lock file sits beside the data file, is opened read-write and created
+  `0600` when missing, and is never written, truncated or deleted: a deleted
+  lock file is a new inode, and holders of two inodes exclude nobody. Windows
+  is `LockFileEx(LOCKFILE_EXCLUSIVE_LOCK)` at offset 0, length 1. POSIX is
+  `flock(LOCK_EX)`. Not `fcntl`, `lockf` or an OFD lock: on Linux those are a
+  separate lock table, invisible to `flock`. Not `msvcrt.locking`: it retries
+  once a second and fails after ten.
+- **`Write` and `Change` hold it from before the read to after the rename.
+  `Read` never takes it.**
+- **Missing and empty are different values**, and a `Change` between them
+  writes.
+- **The replacement is a fresh temporary file in the same directory, fsynced,
+  renamed over `<path>`.** The name is unique to the writer — `CreateTemp`,
+  `mkstemp`, `CREATE_NEW` — so two languages staging at once never open each
+  other's file. Windows is `FileRenameInfoEx` with `REPLACE_IF_EXISTS |
+  POSIX_SEMANTICS`, falling back to `MoveFileEx(REPLACE_EXISTING)` where the
+  volume refuses the flags; `ERROR_SHARING_VIOLATION` and `ERROR_ACCESS_DENIED`
+  are retried a bounded number of times, then returned with the temporary
+  removed. POSIX is `rename(2)`.
+- **`Read` opens with every share mode on Windows** and holds the handle for
+  the read only.
+
+Prove it by being the seventh process in `mixed.py`: a program that, given
+`CAS_PATH`, `CAS_ROLE` and `CAS_N`, applies `CAS_N` increments of the `"n n"`
+counter as a `writer` or reads until it sees `CAS_N` as a `reader`, aborting on
+a torn read. Add its command to `commands()`; the run counts its updates with
+ours. A fourth implementation whose lock ours cannot see loses a third of its
+updates on the first run — measured with a Python writer on byte 1 on Windows
+and on `lockf` on Linux, in `feedback/2026-09-06-mixedgate.md`. `mixed.py`
+takes a directory as its second argument; a UNC path runs the six on a share.
+
+## Today
+
+Go, Python and C++, each the three calls. Consumed by `job`'s file store,
+`config`, `rights` and `asks`.
+
+What may break:
+
+- A handle on the data file without delete sharing — an editor, `type`,
+  Python's `open()` — makes a Windows replace fail with `ERROR_SHARING_VIOLATION`
+  for as long as it is held. The writer retries 1000 times — 160 to 470 ms on
+  local NTFS, process start included, the same in all three languages — then
+  returns the error with nothing left behind; the lock was held throughout, so
+  no other writer's update is lost, and the file still holds the previous
+  value. A handle opened with `FILE_SHARE_DELETE` keeps reading the bytes it
+  opened while the rename succeeds under it, 2 ms measured.
+- Over SMB every open handle on the data file blocks the replace, ours
+  included, share-delete or not, from the same client or another process on
+  it: the fallback rename fails with `ERROR_ACCESS_DENIED`, 11 to 126 ms a
+  try, so the 1000 tries last 25 s in Python and 31 s in C++ under a held
+  handle, and Go's `os.Root` rename does not return at all — killed at 90 s,
+  its temporary left behind. A reader that polls keeps the tries failing for as
+  long as it polls: six writers and three readers of ours on one share stalled
+  at 85 and 50 of 600, C++ and Python returned the error, Go never returned. A
+  process on the server holding the file open blocks nothing,
+  and the server's own rename is never blocked. `Read` over SMB can itself
+  fail with `ERROR_ACCESS_DENIED` on open while the server renames underneath
+  it, rather than returning either value.
+- Every write is an fsync: about 6 ms on this machine. Right for a policy file
+  written at human rate; wrong for a lease renewed every millisecond.
+- **Python flushes the directory after the rename; Go and C++ do not yet.**
+  Without that flush a power cut can lose the rename: the previous value
+  survives, the acknowledged one may not. Python opens the directory and
+  flushes it — `fsync` on POSIX, `FlushFileBuffers` on a
+  `FILE_FLAG_BACKUP_SEMANTICS` handle on Windows — and raises anything it does
+  not recognise. Where the volume answers `ERROR_INVALID_FUNCTION`,
+  `ERROR_NOT_SUPPORTED` or `ERROR_ACCESS_DENIED` — Samba over SMB is the one we
+  have met — the write is acknowledged without that guarantee. The flush costs
+  0.1 ms on NTFS, 1.7 ms on ext4 and 33 ms on the NAS's btrfs. What it buys is
+  the rename reaching the disk, not that the file system would have lost it
+  without it: whether NTFS, ext4, btrfs or APFS keep the rename anyway is a
+  power-cut test nobody has run.
+- A writer killed between staging and renaming — power cut, `TerminateProcess`,
+  `SIGKILL` — leaves one `<name>.<unique>.tmp` beside the file. The data file
+  is untouched and still holds its previous value, and nothing removes the
+  temporary on the write path: finding it means reading the directory, which
+  would cost every write the directory's size. The name is the sweeper's
+  handle — anything matching `<name>.*.tmp` beside the file is dead, because a
+  live writer stages under the lock. Python's `sweep(path)` takes that lock and
+  removes them, and returns how many; Go and C++ have no such call yet.
+- A reader that polls is a tax on every writer of the file on Windows: 4.4 ms
+  per update alone, 6 to 16 ms with one reader spinning, from open-close
+  contention on the name and not from the rename retry.
+- The names we derive are longer than the one you gave us — `<path>.lock` and
+  `<path>.XXXXXXXX.tmp` — so on Windows with `LongPathsEnabled = 0` a path a
+  bare `open()` accepts can be one `cas` cannot. **Python prefixes `\\?\` once
+  the staged name would pass `MAX_PATH`, and Go's own `os` package does the
+  same for it, so both take every path a bare `open()` takes and some it does
+  not; C++ refuses from 246 characters up, where `open()` still works.**
+- An edit that calls `write`, `change` or `sweep` on the file it is editing
+  cannot be served: the lock is held and a second handle on it is another
+  holder, so the call would wait for itself. **Python raises `Reentrant`; Go
+  and C++ block forever with no message.** Nesting on a different file is fine
+  and is how a record and its index are written together.
+- An edit that returns no value where the file holds one is refused —
+  `NoValue` in Python, `ErrNoValue` in Go — and the file is left as it was. It
+  is not a way to empty a file (write an empty value) or to delete one (there
+  is no delete). An edit that returns what it was given changes nothing, and on
+  a missing file that means the file stays missing. C++ cannot express it: its
+  `Edit` returns `std::string`.
+- The lock file stays. Delete the data file and `<path>.lock` together.
+
+## Conformance
+
+[`mixed.py`](mixed.py): two Go, two C++ and two Python writers making 100
+changes each to one file whose name is the last line of
+[`names.list`](names.list) — an emoji, a CJK pair, a macron and a combining
+acute, because until 2026-09-09 no test in any language used a file name longer
+than one ASCII letter and the Windows rename in Python had been counting code
+points where the kernel counts UTF-16 units — a reader per language spinning
+through every rename —
+[`CAS-MIXED1.txt`](https://github.com/openabstractions/abstractions/blob/main/docs/results/CAS-MIXED1.txt).
+Windows; macOS `UNPROVEN`. Each language's own tests are named above.
+
+## Where it sits
+
+Below: nothing of ours. Above:
+[abstraction-job](https://github.com/openabstractions/abstraction-job) writes
+every record through it, and
+[abstraction-config](https://github.com/openabstractions/abstraction-config),
+[abstraction-asks](https://github.com/openabstractions/abstraction-asks) and
+[abstraction-rights](https://github.com/openabstractions/abstraction-rights)
+keep their files with it.
+
+One layer of [openabstractions](https://github.com/openabstractions/abstractions).
+Every layer names one thing local tools rebuild on their own; the name means the
+same in each language that implements it, and the conformance scenarios are what
+hold an implementation to it.
+
+## Requirements
+
+Go 1.25 or newer, standard library only. Python 3.9 or newer, standard library
+only. C++17.
+
+## Licence
+
+Apache-2.0. See [LICENSE](https://github.com/openabstractions/abstraction-cas/blob/main/LICENSE).

abstraction_cas-0.1.0/abstraction_cas.egg-info/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: abstraction-cas
+Version: 0.1.0
+Summary: Compare-and-set over a file. The floor under every service that keeps state in a file.
+License-Expression: Apache-2.0
+Project-URL: Source, https://github.com/openabstractions/abstraction-cas
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# abstraction-cas
+
+**In development.** Tagged `go/v0.1.0`, but this page predates that tag: no
+capability claim, no contract page, no conformance scenario of its own.
+
+A file is replaced whole or not at all, and every change is applied to the value
+the previous change left — across processes and across languages sharing one
+kernel.
+
+## The problem
+
+Every service that keeps state in a file rewrites it, and two writers on one
+file lose each other's updates unless they agree on a lock and a rename. Each
+service of ours hand-rolled its own writer. This is the floor under all of them:
+one lock, one rename, one implementation per language we ship. Not a
+layer — no contract page, no capability claim. A stranger implementing `job`
+needs its page, not this.
+
+## Words
+
+| word | meaning |
+|---|---|
+| **read** | the whole file, or nothing when there is none |
+| **write** | replace the file only if it still holds `base`; else `Moved` |
+| **change** | read, edit and write under the lock, so an edit always sees the truth and never needs a retry |
+| **base** | the value a writer read; `nil` means *only if the file does not exist* |
+| **lock** | byte 0 of `<path>.lock`, exclusive, blocking, released by the kernel when the holder dies |
+
+No rule on this page carries a tag. The invariants below each carry a test, and
+*What a fourth implementation must do* is cited by
+[the job page](https://github.com/openabstractions/abstraction-job).
+
+## Obtain
+
+- **Go.** `go get github.com/openabstractions/abstraction-cas/go`. No tag yet;
+  `go get` resolves a pseudo-version of `main`.
+- **Python.** Not on any index. `python/abstraction_cas.py` is one module with
+  no imports of ours; `python/pyproject.toml` builds a wheel
+  (`pip wheel python/`).
+- **C++.** One header and one source, C++17, standard library only, and no build
+  file: name them. `g++ -std=c++17 -I cpp/include cpp/test/test_cas.cpp
+  cpp/src/cas.cpp -o test_cas` compiles and passes this layer's own test; MSVC
+  19.51 takes the same two files under `/std:c++17` and `/I`. Measured
+  2026-09-09. There
+  is no tagged release and no package.
+
+## Example
+
+```go
+import cas "github.com/openabstractions/abstraction-cas/go"
+
+err := cas.Change(path, func(cur []byte) ([]byte, error) {
+    var f file
+    if cur != nil {
+        json.Unmarshal(cur, &f)
+    }
+    f.Apps = append(f.Apps, app)
+    return json.Marshal(f)
+})
+```
+
+`Read` returns the whole file, or `nil` when there is none. `Write(path, base,
+data)` replaces the file only if it still holds `base` (`nil`: only if it does
+not exist), else `ErrMoved`. `Change` reads, edits and writes under the lock, so
+an edit always sees the truth and never needs a retry.
+
+The same three calls in `python/abstraction_cas.py` (`read`, `write`, `change`,
+`None` for missing, `Moved`) and `cpp/include/abstraction/cas.h` (`std::nullopt`
+for missing, `Moved` thrown, an edit refuses by throwing). All three share one
+lock and one rename, so writers in different languages on one file do not lose
+each other's updates; `mixed.py` proves it and `scripts/check.sh` runs it.
+
+## Invariants, each with a test in `go/cas_test.go`, `python/test_abstraction_cas.py`, `cpp/test/test_cas.cpp`
+
+- **Whole or nothing.** A reader at any moment, from any process, sees a value
+  some writer wrote in full. Never a partial file, never a mixture.
+- **No lost update.** Every successful `Change` was applied to the value left
+  by the previous successful one, across goroutines and across processes.
+- **A stale base is refused** and leaves the file untouched.
+- **An ended record stays ended.** An edit that refuses on what it reads is
+  refusing on the truth, so nothing can be walked backwards by a writer that
+  read earlier.
+- **Nothing left behind.** Contention and refusal leave no temporary files.
+
+## How
+
+The data is staged in a temporary file beside the target, fsynced, and renamed
+over it, under the lock the contract below names, which the kernel releases
+when the holder dies — no lock is ever broken by a timeout. On Windows every
+read opens with `FILE_SHARE_DELETE` and the rename is `FileRenameInfoEx` with
+POSIX semantics, so a reader of ours never blocks a replace; Go gets both from
+`os.Root`, Python and C++ call them. A Samba share answers `FileRenameInfoEx`
+with `ERROR_INVALID_PARAMETER`, flag or no flag, so there the fallback runs on
+every write — `MoveFileEx` in Python and C++, `FileRenameInformation` in Go —
+and a reader does block a replace; see below.
+
+**The lock is one machine's.** A byte-range lock taken over SMB and a `flock`
+taken on the server's own volume never meet: writers on the PC and on the NAS
+on one file lost or refused 147–149 of 2150 updates in three runs of three,
+every PC writer dying within its first few changes
+(`feedback/2026-09-06-shareloc.md`, harness `research/locks/twohost.py`). Six
+writers in three languages on the PC alone, over the same share, lost nothing
+in 1800. Two hosts on one record need a protocol this file does not have.
+
+## What a fourth implementation must do
+
+Two implementations on one file agree on the bytes they write and on the way
+they keep each other out. Every single-language test proves the first only: a
+writer with another lock passes all of them and loses updates against ours.
+
+- **The lock is byte 0 of `<path>.lock`, exclusive, blocking, no timeout.**
+  The lock file sits beside the data file, is opened read-write and created
+  `0600` when missing, and is never written, truncated or deleted: a deleted
+  lock file is a new inode, and holders of two inodes exclude nobody. Windows
+  is `LockFileEx(LOCKFILE_EXCLUSIVE_LOCK)` at offset 0, length 1. POSIX is
+  `flock(LOCK_EX)`. Not `fcntl`, `lockf` or an OFD lock: on Linux those are a
+  separate lock table, invisible to `flock`. Not `msvcrt.locking`: it retries
+  once a second and fails after ten.
+- **`Write` and `Change` hold it from before the read to after the rename.
+  `Read` never takes it.**
+- **Missing and empty are different values**, and a `Change` between them
+  writes.
+- **The replacement is a fresh temporary file in the same directory, fsynced,
+  renamed over `<path>`.** The name is unique to the writer — `CreateTemp`,
+  `mkstemp`, `CREATE_NEW` — so two languages staging at once never open each
+  other's file. Windows is `FileRenameInfoEx` with `REPLACE_IF_EXISTS |
+  POSIX_SEMANTICS`, falling back to `MoveFileEx(REPLACE_EXISTING)` where the
+  volume refuses the flags; `ERROR_SHARING_VIOLATION` and `ERROR_ACCESS_DENIED`
+  are retried a bounded number of times, then returned with the temporary
+  removed. POSIX is `rename(2)`.
+- **`Read` opens with every share mode on Windows** and holds the handle for
+  the read only.
+
+Prove it by being the seventh process in `mixed.py`: a program that, given
+`CAS_PATH`, `CAS_ROLE` and `CAS_N`, applies `CAS_N` increments of the `"n n"`
+counter as a `writer` or reads until it sees `CAS_N` as a `reader`, aborting on
+a torn read. Add its command to `commands()`; the run counts its updates with
+ours. A fourth implementation whose lock ours cannot see loses a third of its
+updates on the first run — measured with a Python writer on byte 1 on Windows
+and on `lockf` on Linux, in `feedback/2026-09-06-mixedgate.md`. `mixed.py`
+takes a directory as its second argument; a UNC path runs the six on a share.
+
+## Today
+
+Go, Python and C++, each the three calls. Consumed by `job`'s file store,
+`config`, `rights` and `asks`.
+
+What may break:
+
+- A handle on the data file without delete sharing — an editor, `type`,
+  Python's `open()` — makes a Windows replace fail with `ERROR_SHARING_VIOLATION`
+  for as long as it is held. The writer retries 1000 times — 160 to 470 ms on
+  local NTFS, process start included, the same in all three languages — then
+  returns the error with nothing left behind; the lock was held throughout, so
+  no other writer's update is lost, and the file still holds the previous
+  value. A handle opened with `FILE_SHARE_DELETE` keeps reading the bytes it
+  opened while the rename succeeds under it, 2 ms measured.
+- Over SMB every open handle on the data file blocks the replace, ours
+  included, share-delete or not, from the same client or another process on
+  it: the fallback rename fails with `ERROR_ACCESS_DENIED`, 11 to 126 ms a
+  try, so the 1000 tries last 25 s in Python and 31 s in C++ under a held
+  handle, and Go's `os.Root` rename does not return at all — killed at 90 s,
+  its temporary left behind. A reader that polls keeps the tries failing for as
+  long as it polls: six writers and three readers of ours on one share stalled
+  at 85 and 50 of 600, C++ and Python returned the error, Go never returned. A
+  process on the server holding the file open blocks nothing,
+  and the server's own rename is never blocked. `Read` over SMB can itself
+  fail with `ERROR_ACCESS_DENIED` on open while the server renames underneath
+  it, rather than returning either value.
+- Every write is an fsync: about 6 ms on this machine. Right for a policy file
+  written at human rate; wrong for a lease renewed every millisecond.
+- **Python flushes the directory after the rename; Go and C++ do not yet.**
+  Without that flush a power cut can lose the rename: the previous value
+  survives, the acknowledged one may not. Python opens the directory and
+  flushes it — `fsync` on POSIX, `FlushFileBuffers` on a
+  `FILE_FLAG_BACKUP_SEMANTICS` handle on Windows — and raises anything it does
+  not recognise. Where the volume answers `ERROR_INVALID_FUNCTION`,
+  `ERROR_NOT_SUPPORTED` or `ERROR_ACCESS_DENIED` — Samba over SMB is the one we
+  have met — the write is acknowledged without that guarantee. The flush costs
+  0.1 ms on NTFS, 1.7 ms on ext4 and 33 ms on the NAS's btrfs. What it buys is
+  the rename reaching the disk, not that the file system would have lost it
+  without it: whether NTFS, ext4, btrfs or APFS keep the rename anyway is a
+  power-cut test nobody has run.
+- A writer killed between staging and renaming — power cut, `TerminateProcess`,
+  `SIGKILL` — leaves one `<name>.<unique>.tmp` beside the file. The data file
+  is untouched and still holds its previous value, and nothing removes the
+  temporary on the write path: finding it means reading the directory, which
+  would cost every write the directory's size. The name is the sweeper's
+  handle — anything matching `<name>.*.tmp` beside the file is dead, because a
+  live writer stages under the lock. Python's `sweep(path)` takes that lock and
+  removes them, and returns how many; Go and C++ have no such call yet.
+- A reader that polls is a tax on every writer of the file on Windows: 4.4 ms
+  per update alone, 6 to 16 ms with one reader spinning, from open-close
+  contention on the name and not from the rename retry.
+- The names we derive are longer than the one you gave us — `<path>.lock` and
+  `<path>.XXXXXXXX.tmp` — so on Windows with `LongPathsEnabled = 0` a path a
+  bare `open()` accepts can be one `cas` cannot. **Python prefixes `\\?\` once
+  the staged name would pass `MAX_PATH`, and Go's own `os` package does the
+  same for it, so both take every path a bare `open()` takes and some it does
+  not; C++ refuses from 246 characters up, where `open()` still works.**
+- An edit that calls `write`, `change` or `sweep` on the file it is editing
+  cannot be served: the lock is held and a second handle on it is another
+  holder, so the call would wait for itself. **Python raises `Reentrant`; Go
+  and C++ block forever with no message.** Nesting on a different file is fine
+  and is how a record and its index are written together.
+- An edit that returns no value where the file holds one is refused —
+  `NoValue` in Python, `ErrNoValue` in Go — and the file is left as it was. It
+  is not a way to empty a file (write an empty value) or to delete one (there
+  is no delete). An edit that returns what it was given changes nothing, and on
+  a missing file that means the file stays missing. C++ cannot express it: its
+  `Edit` returns `std::string`.
+- The lock file stays. Delete the data file and `<path>.lock` together.
+
+## Conformance
+
+[`mixed.py`](mixed.py): two Go, two C++ and two Python writers making 100
+changes each to one file whose name is the last line of
+[`names.list`](names.list) — an emoji, a CJK pair, a macron and a combining
+acute, because until 2026-09-09 no test in any language used a file name longer
+than one ASCII letter and the Windows rename in Python had been counting code
+points where the kernel counts UTF-16 units — a reader per language spinning
+through every rename —
+[`CAS-MIXED1.txt`](https://github.com/openabstractions/abstractions/blob/main/docs/results/CAS-MIXED1.txt).
+Windows; macOS `UNPROVEN`. Each language's own tests are named above.
+
+## Where it sits
+
+Below: nothing of ours. Above:
+[abstraction-job](https://github.com/openabstractions/abstraction-job) writes
+every record through it, and
+[abstraction-config](https://github.com/openabstractions/abstraction-config),
+[abstraction-asks](https://github.com/openabstractions/abstraction-asks) and
+[abstraction-rights](https://github.com/openabstractions/abstraction-rights)
+keep their files with it.
+
+One layer of [openabstractions](https://github.com/openabstractions/abstractions).
+Every layer names one thing local tools rebuild on their own; the name means the
+same in each language that implements it, and the conformance scenarios are what
+hold an implementation to it.
+
+## Requirements
+
+Go 1.25 or newer, standard library only. Python 3.9 or newer, standard library
+only. C++17.
+
+## Licence
+
+Apache-2.0. See [LICENSE](https://github.com/openabstractions/abstraction-cas/blob/main/LICENSE).

abstraction_cas-0.1.0/abstraction_cas.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+LICENSE
+README.md
+abstraction_cas.py
+pyproject.toml
+abstraction_cas.egg-info/PKG-INFO
+abstraction_cas.egg-info/SOURCES.txt
+abstraction_cas.egg-info/dependency_links.txt
+abstraction_cas.egg-info/top_level.txt

abstraction_cas-0.1.0/abstraction_cas.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

abstraction_cas-0.1.0/abstraction_cas.egg-info/top_level.txt

@@ -0,0 +1 @@
+abstraction_cas

abstraction_cas-0.1.0/abstraction_cas.py

@@ -0,0 +1,227 @@
+"""Compare-and-set over a file. Semantics in cas/README.md."""
+
+import contextlib
+import glob
+import os
+import sys
+import tempfile
+import threading
+
+
+class Moved(Exception):
+    """The file changed since it was read."""
+
+
+class NoValue(Exception):
+    """An edit returned no value where the file holds one."""
+
+
+class Reentrant(Exception):
+    """A write or change ran inside an edit on the same file."""
+
+
+def read(path):
+    try:
+        return _read(_native(path))
+    except FileNotFoundError:
+        return None
+
+
+def write(path, base, data):
+    with _locked(path):
+        _replace(path, base, data)
+
+
+def change(path, edit):
+    with _locked(path):
+        cur = read(path)
+        nxt = edit(cur)
+        if nxt != cur:
+            _replace(path, cur, nxt)
+
+
+def sweep(path):
+    """Remove the temporaries a killed writer left beside path; return how many.
+
+    Not on the write path, where it would cost every write the size of the
+    directory. Holding the lock is what makes it safe: a live writer stages
+    under the lock, so every temporary beside the file is a dead one.
+    """
+    with _locked(path):
+        native = _native(path)
+        gone = 0
+        for orphan in glob.glob(glob.escape(native) + ".*.tmp"):
+            with contextlib.suppress(OSError):
+                os.unlink(orphan)
+                gone += 1
+        return gone
+
+
+_held = threading.local()
+
+
+@contextlib.contextmanager
+def _locked(path):
+    native = _native(path)
+    holding = getattr(_held, "paths", None)
+    if holding is None:
+        holding = _held.paths = set()
+    if native in holding:
+        raise Reentrant(os.fspath(path))
+    os.makedirs(os.path.dirname(native), exist_ok=True)
+    fd = os.open(native + ".lock", os.O_CREAT | os.O_RDWR, 0o600)
+    holding.add(native)
+    try:
+        _flock(fd)
+        yield
+    finally:
+        holding.discard(native)
+        os.close(fd)
+
+
+def _replace(path, base, data):
+    if data is None:
+        raise NoValue(os.fspath(path))
+    if read(path) != base:
+        raise Moved(os.fspath(path))
+    native = _native(path)
+    directory = os.path.dirname(native)
+    fd, tmp = tempfile.mkstemp(prefix=os.path.basename(native) + ".", suffix=".tmp", dir=directory)
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+            f.flush()
+            os.fsync(f.fileno())
+        _rename_over(tmp, native)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        raise
+    _fsync_dir(directory)
+
+
+def _rename_over(tmp, native):
+    for _ in range(999):
+        try:
+            return _rename(tmp, native)
+        except _TRANSIENT:
+            pass
+    _rename(tmp, native)
+
+
+_MAX_PATH = 260
+_DERIVED = len(".XXXXXXXX.tmp")
+
+if sys.platform == "win32":
+    import ctypes
+    import msvcrt
+    from ctypes import wintypes
+
+    _k32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    _k32.CreateFileW.argtypes = [wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD, wintypes.LPVOID,
+                                 wintypes.DWORD, wintypes.DWORD, wintypes.HANDLE]
+    _k32.CreateFileW.restype = wintypes.HANDLE
+    _k32.CloseHandle.argtypes = [wintypes.HANDLE]
+    _k32.FlushFileBuffers.argtypes = [wintypes.HANDLE]
+    _k32.LockFileEx.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.DWORD, wintypes.DWORD,
+                                wintypes.DWORD, wintypes.LPVOID]
+    _k32.SetFileInformationByHandle.argtypes = [wintypes.HANDLE, ctypes.c_int, wintypes.LPVOID, wintypes.DWORD]
+
+    _GENERIC_READ, _GENERIC_WRITE, _DELETE = 0x80000000, 0x40000000, 0x00010000
+    _SHARE_ALL, _OPEN_EXISTING, _BACKUP_SEMANTICS = 0x7, 3, 0x02000000
+    _INVALID_HANDLE = wintypes.HANDLE(-1).value
+    _EXCLUSIVE_LOCK = 2
+    _FILE_RENAME_INFO_EX = 22
+    _REPLACE_IF_EXISTS, _POSIX_SEMANTICS = 1, 2
+    _ERROR_INVALID_FUNCTION, _ERROR_ACCESS_DENIED = 1, 5
+    _ERROR_NOT_SUPPORTED, _ERROR_INVALID_PARAMETER = 50, 87
+    _NO_DIRECTORY_FLUSH = (_ERROR_INVALID_FUNCTION, _ERROR_ACCESS_DENIED, _ERROR_NOT_SUPPORTED)
+    _TRANSIENT = PermissionError
+
+    def _native(path):
+        p = os.path.abspath(os.fspath(path))
+        if len(p) + _DERIVED < _MAX_PATH or p.startswith("\\\\?\\"):
+            return p
+        return "\\\\?\\UNC" + p[1:] if p.startswith("\\\\") else "\\\\?\\" + p
+
+    def _open_shared(path, access, flags=0):
+        h = _k32.CreateFileW(path, access, _SHARE_ALL, None, _OPEN_EXISTING, flags, None)
+        if h == _INVALID_HANDLE:
+            raise ctypes.WinError(ctypes.get_last_error())
+        return h
+
+    def _read(path):
+        fd = msvcrt.open_osfhandle(_open_shared(path, _GENERIC_READ), os.O_RDONLY)
+        with os.fdopen(fd, "rb") as f:
+            return f.read()
+
+    def _flock(fd):
+        overlapped = ctypes.create_string_buffer(32)
+        if not _k32.LockFileEx(msvcrt.get_osfhandle(fd), _EXCLUSIVE_LOCK, 0, 1, 0, overlapped):
+            raise ctypes.WinError(ctypes.get_last_error())
+
+    def _fsync_dir(directory):
+        try:
+            h = _open_shared(directory, _GENERIC_WRITE, _BACKUP_SEMANTICS)
+        except OSError as e:
+            if e.winerror in _NO_DIRECTORY_FLUSH:
+                return
+            raise
+        try:
+            if not _k32.FlushFileBuffers(h):
+                err = ctypes.get_last_error()
+                if err not in _NO_DIRECTORY_FLUSH:
+                    raise ctypes.WinError(err)
+        finally:
+            _k32.CloseHandle(h)
+
+    def _rename_info(target):
+        units = len(target.encode("utf-16-le")) // 2
+
+        class Info(ctypes.Structure):
+            _fields_ = [("Flags", wintypes.DWORD), ("RootDirectory", wintypes.HANDLE),
+                        ("FileNameLength", wintypes.DWORD), ("FileName", wintypes.WCHAR * (units + 1))]
+        return Info(_REPLACE_IF_EXISTS | _POSIX_SEMANTICS, None, units * 2, target)
+
+    def _rename(tmp, native):
+        h = _open_shared(tmp, _DELETE)
+        try:
+            info = _rename_info(native)
+            err = 0 if _k32.SetFileInformationByHandle(h, _FILE_RENAME_INFO_EX, ctypes.byref(info),
+                                                         ctypes.sizeof(info)) else ctypes.get_last_error()
+        finally:
+            _k32.CloseHandle(h)
+        if err in (_ERROR_NOT_SUPPORTED, _ERROR_INVALID_PARAMETER):
+            os.replace(tmp, native)
+        elif err:
+            raise ctypes.WinError(err)
+
+else:
+    import errno
+    import fcntl
+
+    _TRANSIENT = ()
+    _NO_DIRECTORY_FLUSH = (errno.EINVAL, errno.ENOTSUP)
+
+    def _native(path):
+        return os.path.abspath(os.fspath(path))
+
+    def _read(path):
+        with open(path, "rb") as f:
+            return f.read()
+
+    def _flock(fd):
+        fcntl.flock(fd, fcntl.LOCK_EX)
+
+    def _fsync_dir(directory):
+        fd = os.open(directory, os.O_RDONLY)
+        try:
+            os.fsync(fd)
+        except OSError as e:
+            if e.errno not in _NO_DIRECTORY_FLUSH:
+                raise
+        finally:
+            os.close(fd)
+
+    def _rename(tmp, native):
+        os.replace(tmp, native)

abstraction_cas-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "abstraction-cas"
+version = "0.1.0"
+description = "Compare-and-set over a file. The floor under every service that keeps state in a file."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+dependencies = []
+
+[project.urls]
+Source = "https://github.com/openabstractions/abstraction-cas"
+
+[tool.setuptools]
+py-modules = ["abstraction_cas"]

abstraction_cas-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+