feat(sdk): scope-compiler + mount-registry for workspace: auth (partial #308)

[kjgbot]

Partial towards #308. Ships the compiler foundation:

• packages/sdk/src/scope-compiler.ts — compiles workspace: / tools: declarations into path-scoped descriptors
• packages/sdk/src/mount-registry.ts — mount name → path map
• packages/sdk/tests/scope-compiler.test.ts — unit tests

Follow-up (separate PR)

• Preflight mount reachability probe
• Worker-session scope threading (thread compiled scope into AgentWorker start)
• Refusal codes mount_unknown / scope_syntax_invalid / scope_ungrantable end-to-end

Written by codex agent spec-H-auth on finn-mini; final commit at head of feat/spec-H-auth-scope. Committed + pushed from lead machine.

Test plan

• linux-x64-artifact green
• packed-consumer green

🤖 Generated with Claude Code

---

Note

Medium Risk
Introduces permission parsing and mount validation logic that will gate filesystem access; behavior is tested but not yet integrated into runtime enforcement paths.

Overview
Adds the first slice of workspace/filesystem scope auth for relay flows: a pure compiler plus a local mount manifest reader, with Vitest coverage. This is foundation only (partial #308); preflight probes and worker threading are explicitly deferred.

compileScopes turns workspace / tools.fs (and per-step overrides) into structured mount/path: readonly|readwrite|append descriptors. It rejects malformed or traversing paths, optionally checks grants against a MountRegistry, and returns structured refusals (scope_syntax_invalid, mount_unknown, scope_ungrantable) while still listing parsed declarations. Inputs are snapshotJsonValue-snapshotted so getters cannot run during compilation.

readMountRegistry walks upward from a start directory to load the nearest relayfile.mounts.json (version 1); missing file yields {}, invalid JSON/schema throws (fail closed). Child manifests replace outer ones—they are not merged.

^{Reviewed by Cursor Bugbot for commit 300fadc. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 8ed339e7-ce3e-4108-a413-0ae3ff3aa9bc

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[kjgbot]

maintainability lens — FAIL

Maintainability review — PR #329

I've read AGENTS.md, the RFC gate-8 references, and confirmed both new modules have zero in-tree consumers.

Blocker

• Mode matching is exact set membership, not subsumption. scope-compiler.ts:78-84 requires available.modes.includes(scope.mode). A mount declared with modes: ['readwrite'] will refuse a readonly grant — surprising to any filesystem-shaped mental model. The tests at scope-compiler.test.ts:39-42 and :8 implicitly assume manifests enumerate every mode the mount supports, but nothing in code, tests, or the RFC states that authoring convention. In six months a maintainer will either "fix" this by adding subsumption (breaking security assumptions) or file a bug against a rejected grant that looks obviously safe. Either declare the invariant in a comment on MountRegistry/SCOPE_MODES, or implement subsumption explicitly.

Concerns

• No in-tree caller for compileScopes or readMountRegistry. scope-compiler.ts:55 / mount-registry.ts:11. grep finds zero imports. AGENTS.md §7 forbids speculative abstraction; the RFC only sketches gate-8. A stranger reading this has no anchor for the contract beyond the tests. Land the consumer in the same PR, or add a top-of-file line naming the intended consumer and the gate it serves.
• compileScopes(input) with mounts undefined silently skips fact-checking (scope-compiler.ts:74). Two very different modes hide behind the same signature: "no facts loaded" vs "loaded, empty registry" ({}) reject-all. A caller that forgets the second arg gets an all-green result and thinks it enforced. Make mounts required; pass {} when the caller explicitly wants pre-validation only.
• readMountRegistry propagates JSON.parse and non-ENOENT fs errors raw (mount-registry.ts:17-22, :24). Shape errors carry the manifest path; parse/permission errors do not. The doc comment says "fails closed," which is true, but the failure trail is disorienting — wrap the parse and rethrown fs errors with the path.

Notes

• readMountRegistry walks to filesystem root with no repo boundary (mount-registry.ts:12-24, :19-22). Consistent with common "nearest config" patterns; flagging for reviewers wondering about scope creep.
• append vs readwrite split has no rationale in code or RFC. If future modes (execute, delete) are planned, one sentence on SCOPE_MODES would age well.
• Duplicate grants across workspace and step levels are not deduplicated (scope-compiler.ts:96-102). Fine if callers own dedup, but the contract is unstated.
• grant as string cast at scope-compiler.ts:76 is dynamically safe (parseScopeGrant rejects non-strings) but unmarked; a one-line comment would spare a future reader the trace.
• Test at scope-compiler.test.ts:47-51 asserts "does not read an accessor" but the guarantee is enforced by snapshotJsonValue, not this file. The test will silently start passing for the wrong reason if json-value.ts ever softens; consider a comment or a direct check.

REVIEW_FAILED

[kjgbot]

history lens — PASS

Blockers: none. PR #329 passes the HISTORY lens as an explicitly scoped compiler foundation.

• History: I found no reintroduction of a deliberately removed pattern. DRIVE-LOG records the nearest-config boundary: a child configuration shadows its parent without merging permissions. mount-registry.ts, lines 14–38 follows that pattern, propagates non-ENOENT read errors, and rejects malformed manifests. scope-compiler.test.ts, lines 70–90 adds corresponding assertions; I did not execute them.

• Settled RFC decisions: No new contradiction found. scope-compiler.ts, lines 7–18 and 61–104 introduces inert SDK descriptors and compilation logic, consistent with decision drive: WP-13: Fix SDK test failures from sandbox environment gaps #13’s placement of auth-by-declaration in the surface. It adds no kernel vocabulary, provider adapter, or gate modification.

• Commit honesty: The message accurately identifies the three added files and explicitly defers runtime integration. It claims no passing tests or completed enforcement. Command:

  gh pr view 329 --repo AgentWorkforce/flows --json commits --jq '.commits[].messageBody'

  Captured message body:

  …al) (#308)
  
  Initial slice: mount-registry + scope-compiler + tests. Compiles workspace:
  declarations into path-scoped descriptors. Preflight mount reachability
  and worker-session scope threading remain as follow-ups; opening PR to
  land the compiler foundation.
  

Concerns: scope-compiler.ts, lines 82–95 permits compilation without mount facts. The documented follow-up must supply trusted capabilities and enforce refusals before worker execution. That remaining integration work is not a regression in this diff.

Notes: AGENTS.md, RFC-0001, NEXT, DIRECTIVES, and relevant DRIVE-LOG history informed this review. The RFC-linked legacy charter was unavailable locally. No test or CI pass is asserted.

REVIEW_PASSED

[kjgbot]

structure lens — MISSING

[kjgbot]

🎯 review-swarm: FAILED (M:fail H:pass S:missing)

Lens transcripts posted as sibling comments above.