coilyco-flight-deck/umbra

Watch

Inventory every silently-degrading platform variant, and remove the silence from each #302

New issue

Closed

opened 2026-08-17 01:56:29 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-08-17 01:56:29 +00:00

Member

Filed by Darren (director seat), 2026-08-16, from Kai's directive in a triage consult round. The sweep half of #262, per her "flock now, sweep the rest separately".

The directive

remove any and every feature that needs fiddle cross platform variance

pkg/flock was the case in front of us and #301 carries it. This issue is the rest, and it exists because #262 surfaced a pattern rather than one bug: a security or coordination primitive that quietly does less on some platforms while its return value says it did the job.

The shape to hunt for

Not "code with a build tag". Build tags are ordinary and fine. The defect is narrower and it is worth stating precisely so the sweep does not turn into a refactor:

A primitive whose degraded path is indistinguishable, to its caller, from its working path.

pkg/flock is the reference instance: Exclusive returns nil on non-Unix, which is the same value a real lock returns. A caller cannot branch on it, a test cannot assert it, and an operator reading a log cannot see it.

The one other known instance

#261 already records it, in its own words:

Linux sandbox setup may degrade to unsandboxed execution, non-Linux execution is not jailed, and read-only capture operations are outside the jail.

That is the same shape and it is worse, because the thing degrading is isolation. #261's scope already includes "Make fallback to unsandboxed execution visible to callers and audit logs", so that half is owned there rather than here. This issue should record it and not duplicate the work.

Scope

Inventory. Every _other.go, _windows.go, _linux.go, !linux, !unix and equivalent in the tree, plus any runtime capability check that falls back rather than failing. Write the list down in the issue, with what each one does on its degraded path and what the caller sees.
Classify each. Three outcomes, and the classification is the deliverable rather than the fixes:
- Honest already - the degraded path errors or is otherwise visible. No change.
- Silent - the degraded path returns success. Gets the #301 treatment: fail loudly, or report the degradation to the caller and the audit log.
- Not worth carrying - the variance exists for a platform nothing runs. Delete the variant rather than fixing it, per the directive.
Decide each, and record the decision on the issue rather than in a commit message.

What this is not

Not a mandate to drop non-Unix support wholesale. umbra-shroud ships Windows and macOS binaries on Scoop and Homebrew today, and #295 keeps doing so. The question here is per-primitive truthfulness, not platform coverage.

Acceptance

A written inventory of every platform-conditional path in the tree, with its degraded behaviour and what the caller observes.
Every entry classified honest, silent, or delete.
Every silent entry either fixed or carrying its own issue.
No primitive in pkg/ returns a success value for work it did not do.
docs/ states which platforms each affected primitive actually supports.

#262 - the declined Windows lock implementation, and Kai's directive.
#301 - the flock instance, filed ahead of this sweep.
#261 - owns the sandbox instance already; this issue records it and does not duplicate it.

**Filed by Darren (director seat), 2026-08-16, from Kai's directive in a triage consult round. The sweep half of #262, per her "flock now, sweep the rest separately".** ## The directive > remove any and every feature that needs fiddle cross platform variance `pkg/flock` was the case in front of us and #301 carries it. This issue is the rest, and it exists because #262 surfaced a **pattern** rather than one bug: a security or coordination primitive that quietly does less on some platforms while its return value says it did the job. ## The shape to hunt for Not "code with a build tag". Build tags are ordinary and fine. The defect is narrower and it is worth stating precisely so the sweep does not turn into a refactor: **A primitive whose degraded path is indistinguishable, to its caller, from its working path.** `pkg/flock` is the reference instance: `Exclusive` returns `nil` on non-Unix, which is the same value a real lock returns. A caller cannot branch on it, a test cannot assert it, and an operator reading a log cannot see it. ## The one other known instance `#261` already records it, in its own words: > Linux sandbox setup may degrade to unsandboxed execution, non-Linux execution is not jailed, and read-only capture operations are outside the jail. That is the same shape and it is worse, because the thing degrading is isolation. #261's scope already includes "Make fallback to unsandboxed execution visible to callers and audit logs", so that half is owned there rather than here. This issue should record it and not duplicate the work. ## Scope 1. **Inventory.** Every `_other.go`, `_windows.go`, `_linux.go`, `!linux`, `!unix` and equivalent in the tree, plus any runtime capability check that falls back rather than failing. Write the list down in the issue, with what each one does on its degraded path and what the caller sees. 2. **Classify each.** Three outcomes, and the classification is the deliverable rather than the fixes: * **Honest already** - the degraded path errors or is otherwise visible. No change. * **Silent** - the degraded path returns success. Gets the #301 treatment: fail loudly, or report the degradation to the caller and the audit log. * **Not worth carrying** - the variance exists for a platform nothing runs. Delete the variant rather than fixing it, per the directive. 3. **Decide each**, and record the decision on the issue rather than in a commit message. ## What this is not Not a mandate to drop non-Unix support wholesale. `umbra-shroud` ships Windows and macOS binaries on Scoop and Homebrew today, and #295 keeps doing so. The question here is per-primitive truthfulness, not platform coverage. ## Acceptance * A written inventory of every platform-conditional path in the tree, with its degraded behaviour and what the caller observes. * Every entry classified honest, silent, or delete. * Every `silent` entry either fixed or carrying its own issue. * No primitive in `pkg/` returns a success value for work it did not do. * `docs/` states which platforms each affected primitive actually supports. ## Related * #262 - the declined Windows lock implementation, and Kai's directive. * #301 - the flock instance, filed ahead of this sweep. * #261 - owns the sandbox instance already; this issue records it and does not duplicate it.

coilyco-ops added the

labels

2026-08-17 01:56:59 +00:00

coilyco-ops referenced this issue

2026-08-17 02:26:46 +00:00

Make broker authorization fail closed and add reusable provenance primitives #261

coilyco-ops referenced this issue

2026-08-17 02:46:45 +00:00

pkg/flock returns success without locking on non-Unix, so a caller cannot tell a held lock from a no-op #301

coilyco-ops referenced this issue from a commit

2026-08-17 02:50:09 +00:00

fix(specgen): stop the Windows cache lock reporting a lock it never took

coilyco-ops commented

2026-08-17 02:50:36 +00:00

Author

Member

Sweep done. The inventory is below, every entry classified, and both silent entries are fixed rather than deferred.

Method, so the negative result is checkable

Four passes over the tree, because one modality proves nothing about the others:

grep -rln "^//go:build" for every explicit constraint.
find for implicit GOOS-suffixed filenames (*_windows.go, *_linux.go, *_darwin.go, *_plan9.go, *_js.go).
grep -rn "runtime.GOOS\|runtime.GOARCH" for runtime capability branching.
grep -rn -i "best-effort\|degrade\|no-op\|fallback\|not supported\|unsupported" for a fallback that carries no build tag at all.

Pass 2 returned nothing. There are no implicitly-constrained files in this repo, so the whole platform surface is the four files in pass 1.

The inventory

pkg/flock/flock_other.go - exclusive, unlock - silent → FIXED (#301, 7b22f1d). Returned nil, the same value a real lock returns. Now ErrUnsupported wrapped with the GOOS, matched by errors.Is.

http/specgen/exec_other.go - lockFile, unlockFile - silent → FIXED (df51976). This is the instance the sweep was for. A second, independent copy of the flock primitive, with the identical defect: func lockFile(*os.File) error { return nil } on Windows, guarding materialize+build against a cache dir. Its comment argued the case honestly - "concurrent run of the same cache dir is rare and the build is idempotent" - but the return value said "locked" regardless.

Fixed by deduplicating onto pkg/flock rather than repairing the copy, so there is now one advisory-lock primitive in the tree. It reports the degradation and continues:

specgen: no cache lock on windows, building <dir> unserialised (a concurrent run may race)

Continuing rather than refusing, and this is where it departs from #301. specgen ships Windows binaries on Scoop and #295 keeps doing so, so refusing would drop platform support to fix a message. Per this issue's own "not a mandate to drop non-Unix support wholesale", the defect was the silence, not the continuing.

http/specgen/exec_other.go - execBinary - honest. No change. Windows has no syscall.Exec, so it spawns a child, mirrors stdio, and exits with the child's code. From the caller's side both variants terminate the process with the same status; it does a different thing rather than pretending to do the same thing.

http/specgen/exec_unix.go - execBinary - honest. No change. It also lost its lock functions, and its tag tightens from !windows to unix by construction. Worth noting the old tag was wrong: it claimed !windows while calling syscall.Flock, which no plan9 or wasm build could have compiled.

executablePathForOS / resolveBuildDestForOS (runtime.GOOS) - honest. No change. Pure naming, appending .exe on Windows. Nothing degrades.

Nothing classified not worth carrying. The only two variants are execBinary, which is load-bearing for a shipped platform, and locking, which is now truthful.

One correction to this issue's premise

#261 already records it (...) "Linux sandbox setup may degrade to unsandboxed execution"
That is the same shape and it is worse (...) #261's scope already includes making it visible, so that half is owned there.

Not a sandbox. (...) wrapper is audit + gate, not isolation. Sandboxing belongs in (...)

#261 inherited that line from an older description of the codebase and this issue inherited it from #261. Discharged on #261 as a documentation deliverable: docs/provenance.md now states outright that umbra performs no execution isolation. So this sweep found its second instance somewhere else entirely, which is the argument for having run all four passes rather than trusting the one known lead.

Acceptance

Written inventory of every platform-conditional path, with degraded behaviour and what the caller observes. Above.
Every entry classified honest / silent / delete. Two silent, three honest, zero delete.
Every silent entry fixed or carrying its own issue. Both fixed.
No primitive in pkg/ returns a success value for work it did not do. pkg/flock was the only one, and http/specgen is now covered by the same rule.
docs/ states which platforms each affected primitive supports. docs/ward-helpers.md for flock, and a new "The cache lock, and where it does not exist" section in docs/specgen-materialization.md.

Angie, engineer seat

**Sweep done. The inventory is below, every entry classified, and both `silent` entries are fixed rather than deferred.** ## Method, so the negative result is checkable Four passes over the tree, because one modality proves nothing about the others: 1. `grep -rln "^//go:build"` for every explicit constraint. 2. `find` for implicit GOOS-suffixed filenames (`*_windows.go`, `*_linux.go`, `*_darwin.go`, `*_plan9.go`, `*_js.go`). 3. `grep -rn "runtime.GOOS\|runtime.GOARCH"` for runtime capability branching. 4. `grep -rn -i "best-effort\|degrade\|no-op\|fallback\|not supported\|unsupported"` for a fallback that carries no build tag at all. **Pass 2 returned nothing.** There are no implicitly-constrained files in this repo, so the whole platform surface is the four files in pass 1. ## The inventory **`pkg/flock/flock_other.go`** - `exclusive`, `unlock` - **silent → FIXED** (#301, `7b22f1d`). Returned `nil`, the same value a real lock returns. Now `ErrUnsupported` wrapped with the GOOS, matched by `errors.Is`. **`http/specgen/exec_other.go`** - `lockFile`, `unlockFile` - **silent → FIXED** (`df51976`). *This is the instance the sweep was for.* A second, independent copy of the flock primitive, with the identical defect: `func lockFile(*os.File) error { return nil }` on Windows, guarding materialize+build against a cache dir. Its comment argued the case honestly - *"concurrent run of the same cache dir is rare and the build is idempotent"* - but the return value said "locked" regardless. Fixed by deduplicating onto `pkg/flock` rather than repairing the copy, so there is now one advisory-lock primitive in the tree. It reports the degradation and continues: ``` specgen: no cache lock on windows, building <dir> unserialised (a concurrent run may race) ``` **Continuing rather than refusing, and this is where it departs from #301.** specgen ships Windows binaries on Scoop and #295 keeps doing so, so refusing would drop platform support to fix a message. Per this issue's own "not a mandate to drop non-Unix support wholesale", the defect was the silence, not the continuing. **`http/specgen/exec_other.go`** - `execBinary` - **honest**. No change. Windows has no `syscall.Exec`, so it spawns a child, mirrors stdio, and exits with the child's code. From the caller's side both variants terminate the process with the same status; it does a different thing rather than pretending to do the same thing. **`http/specgen/exec_unix.go`** - `execBinary` - **honest**. No change. It also lost its lock functions, and its tag tightens from `!windows` to `unix` by construction. Worth noting the old tag was wrong: it claimed `!windows` while calling `syscall.Flock`, which no plan9 or wasm build could have compiled. **`executablePathForOS` / `resolveBuildDestForOS`** (`runtime.GOOS`) - **honest**. No change. Pure naming, appending `.exe` on Windows. Nothing degrades. **Nothing classified `not worth carrying`.** The only two variants are `execBinary`, which is load-bearing for a shipped platform, and locking, which is now truthful. ## One correction to this issue's premise > `#261` already records it (...) "Linux sandbox setup may degrade to unsandboxed execution" > That is the same shape and it is worse (...) #261's scope already includes making it visible, so that half is owned there. **There is no sandbox in this repository, so there is no such instance to own.** A search for `sandbox|landlock|seccomp|unshare|bwrap|nsjail|chroot|jail` across the Go tree returns three hits, all comments in `examples/treebuilders` saying umbra is explicitly *not* one: > Not a sandbox. (...) wrapper is audit + gate, not isolation. Sandboxing belongs in (...) #261 inherited that line from an older description of the codebase and this issue inherited it from #261. Discharged on #261 as a documentation deliverable: `docs/provenance.md` now states outright that umbra performs no execution isolation. So this sweep found its second instance somewhere else entirely, which is the argument for having run all four passes rather than trusting the one known lead. ## Acceptance * Written inventory of every platform-conditional path, with degraded behaviour and what the caller observes. Above. * Every entry classified honest / silent / delete. Two silent, three honest, zero delete. * Every `silent` entry fixed or carrying its own issue. Both fixed. * No primitive in `pkg/` returns a success value for work it did not do. `pkg/flock` was the only one, and `http/specgen` is now covered by the same rule. * `docs/` states which platforms each affected primitive supports. `docs/ward-helpers.md` for flock, and a new "The cache lock, and where it does not exist" section in `docs/specgen-materialization.md`.  Angie, engineer seat

coilyco-ops closed this issue

2026-08-17 02:50:41 +00:00

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

coilyco-flight-deck/umbra#302

No description provided.

Rows
Columns