0036: Windows semantics for POSIX-shaped contracts
- Status: accepted
- Date: 2026-10-07
Context
The first full make check-windows runs (ADR 0024; tickets
01M3D7GD45SEZD7Y0RXWPAC6KF, 01M4BKSMKJ6DTQA5RE39H9AKG1,
01M4BKSMGQ15147H58RJ4XH8XZ, 01M4AGQDC4D2QPBXWV2SQTGSV9) found tests whose
assertions were written in POSIX terms and whose production code assumed
POSIX error semantics. Each needed a ruling on what the contract means
on Windows before a test could pin it; the rulings that change or
sharpen a contract are recorded here, the purely test-side fixes only on
their tickets.
Decisions
-
A private key file. "Mode 0600" is the unix statement of a contract: only the current user can read or write the file, from the moment it exists. On Windows the POSIX bits Go applies are advisory (0600 only decides the read-only attribute) and a new file inherits its directory's DACL, which outside the user's profile commonly lets Users or Everyone read. A private file on Windows is therefore one created with an explicit security descriptor, passed at creation (never applied afterwards), whose DACL is protected against inheritance and holds exactly two allow entries: full access for the current user (the process token's user SID) and for SYSTEM. This is the rule the daemon's named pipe already follows (
transport.PipeSDDL). Administrators get no entry: they can take ownership anyway, and an explicit grant would let any elevated process read key material without that step. Seam:cli.createPrivateFile, first used bydev key new --out;inject --outandentry edit's temporary file have the same gap and should follow. -
A path below a regular file is never "missing". On Windows a path whose parent is a regular file fails with
ERROR_PATH_NOT_FOUND, which Go maps tofs.ErrNotExist, where unix reportsENOTDIR. Code that reads not-exist as "nothing here yet" (an empty blob store, an output that does not exist yet, no.gitattributesyet) therefore accepts a file in a directory's place on Windows. The contract on every OS: a missing path is acceptable only when its nearest existing ancestor is a directory; otherwise it is refused as not a directory (backup.ErrUnexpectedFilefor the blob store, a plain refusal that is not not-exist for a backup output or data directory and forvault.Init'sOptions.Dir), and nothing is written first. A missingOptions.Diris now refused byvault.Init's pre-check too (an error wrappingfs.ErrNotExist, before any key file is written), where it used to fail only at the later.gitattributeswrite; every caller creates the directory first. -
A directory entry's cached info is not a stat. On Windows
os.ReadDirfills eachDirEntryfrom the listing (FindFirstFile), soDirEntry.Infosucceeds for a file removed after listing; on unix it is a lazylstatthat fails. Code that must notice a vanished entry (the backup's blob-store visitor) callsos.Lstaton the path itself. -
?in file names. The SQLite DSN builder (cloud/internal/sqlitedsn) percent-encodes every URI delimiter in a path (?,#,%, space) on every OS; that is pinned by a pure test. Only unix can hold a?in a file name, so the filesystem round-trip tests use names without it on Windows and keep the rest. -
A protocol violation is audited before its answer is readable. add-agent-daemon design.md "Group 5 decisions" 18 promises that a request's audit record exists before the peer can read the answer (the final-byte hook). Violations
agentproto.ServerConn.ReadRequestanswers itself (unknown-verb, no-session, malformed, hello-required, frame-too-large) were audited after the answer was on the wire, which the named-pipe transport exposed on every run and a loaded linux host intermittently. The ordering is extended to violations rather than the test relaxed:ServerConn.SetViolationHookruns the daemon's hook before any byte of the violation's answer is written, and the daemon writes the violation's audit record there, under the connection's write lock (as its final-byte hook already does for served requests). -
Reading a pipe's DACL must tolerate a daemon between accepts.
GetNamedSecurityInfoopens the pipe as a client and fails withERROR_PIPE_BUSYwhenever no instance is in the listening state, which with go-winio is the case betweenListenand the firstAcceptand between a client's connect and the nextAccept.transport.CheckEndpoint(doctor's endpoint check) waits for a listening instance (WaitNamedPipe, bounded) and retries, asDialdoes; a pipe nobody accepts on is reported as busy (wrappingERROR_PIPE_BUSY), never as insecure or missing. Tests read a pipe's DACL from the server side of an accepted connection (GetSecurityInfoon its handle), which does not race. -
Replacing a file that another handle holds open. Windows refuses
MoveFileExover a file any handle has open withoutFILE_SHARE_DELETE(ERROR_ACCESS_DENIEDorERROR_SHARING_VIOLATION): a concurrent save's own rename, an editor, a backup agent or an antivirus scan does so for milliseconds. The atomic publish inprofile(renameFile) treats those as transient and retries for a bounded time; a save never fails on the first refusal. -
The
runstartup budget is native only. The cli spec's "under 50 ms before exec" is the unix figure and stays the native budget (50 ms). TestRunStartupBudget is skipped on Windows pending ticket 01M4C7WA60TM2TT0NG49CRFFVZ: a warmruncommand starts two git processes there, and on the only Windows host this project tests on, an emulated ARM64 VM, process creation alone (git --versiontakes over 100 ms) puts it far above any figure that would still catch a doubled path. No Windows budget is set until that ticket profiles the path and removes or justifies the git processes. -
A missing program is
fs.ErrNotExiston every OS.runner.Run's documented contract. On Windowsos/execresolves a path-qualified program without an extension through%PATHEXT%and reportsexec.ErrNotFound("executable file not found in %PATH%"), which does not wrapfs.ErrNotExist; the runner maps that case (a program named by path that does not exist in any form) tofs.ErrNotExist. -
A small write never waits for the reader. A unix socket's kernel buffer absorbs a small frame whether or not the peer is reading; a named pipe created with go-winio's zero buffer sizes completes a write only once the other end reads it. The daemon writes a secret answer while holding respMu's read side, so on Windows a client that stopped reading held a screen lock off for a whole WriteTimeout behind a 70-byte answer (
TestQueuedSecretAnswerHoldsNoLock, 2 of 5 and 4 of 8 isolated runs on the VM; diagnosed from a goroutine dump). On every OS a write of up to 4 KiB on a daemon connection, in either direction, completes without the peer reading (transport.TestSmallWriteDoesNotWaitForReader); on Windows that is the listener's pipe buffer sizes.
Consequences
cmd/vaultfold/internal/cli.createPrivateFile,core/agentproto.(*ServerConn).SetViolationHook,cmd/vaultfold/internal/procinfo.ReadUTF16CommandLine(the native host's seam, mirrored for procinfo; ticket 01M49T3SQWPY3FAA8DYXZFXQEM) andcli.aceBounds(ticket 01M3EXT3G7HAA7BTMR4KCV883W) are the seams these rulings add; their tests are red until implemented.- Tests that pin a Windows-only behaviour live in
_windows_test.gofiles and run only undermake check-windows; where a ruling applies to every OS the test is sharpened so it also fails on unix until the production code follows (the blob store below a file, the violation hook, the private file seam). - The real cross-user pipe refusal (
TestPipeRefusesOtherUser) runs only where the VM'svftestharness exists and passes today; it is the first test of the pipe DACL against another Windows account.