Skip to content

fix(docs): correct security claims in the new activation/capabilities prose - #29

Merged
mikehasa merged 1 commit into
mainfrom
fix/contributor-doc-accuracy
Jul 30, 2026
Merged

fix(docs): correct security claims in the new activation/capabilities prose#29
mikehasa merged 1 commit into
mainfrom
fix/contributor-doc-accuracy

Conversation

@mikehasa

Copy link
Copy Markdown
Owner

Follow-up to #27 and #28. Both are sound refactors — the manifest output is byte-identical, the permission constants are unchanged, and no test assertion was lost. But a few of the docstrings they added assert safety properties the code does not provide, and one of those claims justified dropping a real defense.

One behavior fix

  • Restore the per-acquisition chmod on the lock file. os.open's mode argument applies only when it creates the file, so a lock left group/world-readable by an older run stayed that way. main re-tightened it on every _locked() entry; the helper extraction dropped that, and an inline comment ("mode is applied at creation, so no separate chmod is needed") stated the reason it was safe to drop. It wasn't. Adds a regression test that fails without the chmod (verified by reverting it).

Docstring corrections

  • _write_json_atomically documented the durability order backwards: the parent-directory fsync happens after the rename — that is precisely what makes the rename durable. Matters because the surrounding comment advertises this helper for reuse in a shared store-IO module.
  • _try_chmod claimed failing silently is always safe. It isn't at the spawn log, which Path.open("ab") creates at 0o666 & ~umask — there this chmod is the only thing keeping child stdout/stderr (store paths, argv, tracebacks) private.
  • capabilities: the validator checks the shape of an evidence claim (ISO date parses, refs are non-empty and non-traversing) — it never opens the referenced document, so it cannot tell a real citation from a plausible-looking one. Replaced "the published matrix cannot overclaim" with what is actually enforced.
  • capabilities: experimental was defined as "only tested with synthetic data", but codex.model_attribution and cursor.mcp_semantics ship with verification level none — no evidence at all. Widened the definition to match the data.

Verification

Full suite: 2904 passed, 1 skipped. The new lock-permission test was negative-tested (removing the chmod makes it fail).

… prose

Follow-up to #27 and #28. Those PRs are sound refactors, but a few of the
docstrings they added assert safety properties the code does not provide, and
one of those claims justified dropping a real defense.

- activation: restore the per-acquisition chmod on the lock file. `os.open`
  applies its mode ONLY on creation, so a lock left group/world-readable by an
  older run stayed that way; `main` re-tightened it on every `_locked()` entry.
  Adds a regression test that fails without the chmod.
- activation: `_write_json_atomically` documented the durability order
  backwards. The parent-directory fsync happens AFTER the rename -- that is
  what makes the rename durable -- and the helper is advertised for reuse.
- activation: `_try_chmod` claimed failing silently is always safe. It is not
  at the spawn log, which `Path.open("ab")` creates at 0o666 & ~umask, where
  this chmod is the only thing keeping child stdout/stderr private.
- capabilities: the validator checks the SHAPE of an evidence claim, not its
  truth -- it never opens the referenced document. Say so instead of promising
  the matrix "cannot overclaim".
- capabilities: `experimental` was defined as "only tested with synthetic
  data", but codex.model_attribution and cursor.mcp_semantics carry no
  evidence at all. Widen the definition to match the data.
@mikehasa
mikehasa merged commit c77a638 into main Jul 30, 2026
3 checks passed
@mikehasa
mikehasa deleted the fix/contributor-doc-accuracy branch July 30, 2026 09:08
@mikehasa mikehasa mentioned this pull request Jul 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant