test(workspace): run one contract table on the git engine and a change-id fake

[andybons]

Problem

No test states what an Engine must do, so a second engine has nothing to prove itself against. A snapshotting engine could also add an operation on every read. This is VCS step 6, PR 4 of vcs-engine-plan.md section 5, with the nine rows of its section 7. It is based on #619.

Design

Spec: docs/architecture.md Internal packages (the internal/workspace/workspacetest row) and workspace (ChangesWith).

workspacetest.Run(t, Factory) holds the nine engine-neutral rows: a read after an edit reports the edit; two reads with no edit add no operation; an untracked file is reported; a deleted file is reported; a rename is reported as a rename or as a delete and an add; a directory outside any repository is not_a_repo; an unborn head gives no head_rev and no error; a missing base is no_base; reads never write. Fake is an engine over a plain directory: its revisions are change:<n>, it has no .git, and its operation counter rises only when the digest of the files changes. ChangesWith takes the engine list, and Changes passes the real list to it, so a row runs one engine through the real Changes path. GitEngine is exported for the git fixture. The table runs from workspace_test.go, which testdata/test-exceptions.txt already lists, and no Options seam is added.

The git fixture checks that a read never writes: the row runs with and without a planted .git/index.lock, so a write to the real index would fail, and it compares the real index, HEAD, the config, the packed references, and every file of refs and of the real object directory before and after both scopes. The no-operation row repeats each scope. The Fake models an engine that snapshots the working copy on read: the first read after an edit records an operation in its own state file, which no user sees, and a read of unchanged files records nothing. The spec read rule says the same.

Semantic change

None for clients. Changes calls ChangesWith with the engine list.

Verification

The table ran first on a fake that adds an operation on every read. The rows failed for the named reason: operations after another read = 4, want 2 and the uncommitted read wrote to the repository: 3 want 2. They pass with the fix, and the git engine passes all nine rows. golangci-lint run ./... reports 0 issues, HARNESS_E2E_RUNTIME=1 go test -race ./e2e/ passes, and go build ./... && go vet ./... && go test -race ./... && test -z "$(gofmt -l .)" passes. One CLI e2e row (TestContractCLIRunPrintsEachOutputOfATaskChild...) failed once under the load of the full local run and passes alone with -count=3; it does not touch this change.

Known flake, not fixed here: TestChanges/a_dirty_submodule_is_not_walked can pass the 28 s budget under heavy load and fail with too_many_changes.

CI job times

Job	main (s)	PR (s)
Browser	115	96
Contract	93	78
Gates	41	33
Node wasm	84	51
Runtime contract	57	50
Static	49	44
Unit	71	65
WebAssembly	30	22

No job grew by more than 5 s. The 18 rows add about 2 s to the workspace package, which runs in parallel inside Unit.

[Copilot]

🟡 Changes recommended

The fake writes during reads contrary to the binding specification, and two contract behaviors remain incorrectly covered.

3 open findings

• Contract misses repeated uncommitted-read writes · New
• Head write violates read-only workspace specification · New
• Nested .fake-workspace.json files are incorrectly excluded · New

What changed in this PR

Adds a reusable workspace engine contract suite and runs it against Git and a change-ID fake.

Changes:

• Adds nine engine contract scenarios and fixtures.
• Introduces ChangesWith for engine injection.
• Updates architecture documentation and structure gates.

File	Description
internal/​workspace/​workspacetest/​fake.go	Implements the fake engine.
internal/​workspace/​workspacetest/​contract.go	Defines the contract table.
internal/​workspace/​workspace.go	Adds engine injection.
internal/​workspace/​workspace_test.go	Runs both engine fixtures.
internal/​workspace/​gitengine.go	Exports GitEngine.
internal/​gates/​structure.go	Updates engine-list ownership.
internal/​gates/​structure_test.go	Updates the structure fixture.
docs/​architecture.md	Documents the new contract design.

🧠 Review effort: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.