feat(core): add the file contract parser and evaluator

[oratis]

Summary

PR 1 of docs/FLOATBOAT_ADOPTION_PLAN.md §2.A. Parse and decide only — nothing is wired into the dispatcher, so the diff that touches the permission path can be reviewed on its own (that's PR 2).

Zero runtime behaviour change: no caller invokes this yet.

The gap it closes

settings.json permission rules match on the tool. Bash(git diff:*) works; Read(.env*) matches nothing, because the only path-aware match is a prefix compare against primaryInput() and a real file_path is absolute. So "never read .env" is a sentence the permission layer cannot express.

The sandbox can express part of it via sandbox.filesystem.denyRead, but that's inert when unconfigured (resolveSandboxMode falls to danger-full-access), its hardcoded deny list covers home-directory credential stores rather than in-project .env, and it's a flat prefix list with no ask state.

This adds the missing axis: glob × {read, write, execute} × {allow, ask, deny}.

Design decisions worth reviewing

The verdict type is PermissionVerdict. Selfware's require_discussion maps exactly onto DeepCode's existing ask, so there's no new lattice and no new vocabulary — composition in PR 2 is a min over a lattice that already exists.

Pure evaluation, separate loader. file-contract.ts has no node:fs; file-contract-loader.ts does the I/O. That split is what makes the decision table exhaustively testable.

A malformed contract is invalid, never absent. Both obvious alternatives are wrong: falling back to "no contract" silently drops every deny the author wrote, and hard-failing turns a typo into a broken install. The parser is strict for the same reason — unknown keys, bad decision values, a rule with no glob, and a rule that decides nothing are all errors, because a silently-ignored line in this file is a permission quietly granted.

Hand-written glob + YAML subset. The repo carries neither dependency by policy (see skills/frontmatter.ts), and this file has exactly one shape.

Honest limitations, stated in the docs

docs/file-contract.md leads with a callout that this is policy, not a security boundary:

• Bash is out of scope. cat .env is a string; statically analysing shell would be guesswork that reads as a guarantee. Only the sandbox bounds Bash.
• No realpath. Path normalization is string math, so a symlink inside the workspace pointing out still looks inside.

Test plan

• pnpm test — 1224 passed, 16 skipped (+49 in this PR)
• pnpm typecheck · pnpm lint · pnpm format:check · pnpm build · node scripts/check-docs.mjs

Coverage includes the adversarial cases AGENTS.md requires for permission changes:

Area	Cases
Glob semantics	segment vs cross-segment, a/**/b matching a/b, braces, ?, regex metacharacters treated as literals (or **/.env* would match axenv)
Precedence	specificity beats file order; exact ties go to the later rule
Self-amendment	Exact-glob write: allow on the contract → still deny; broad ** write: allow → still deny; reading it stays allowed
Path traversal	../ escape → no verdict; src/../.env re-entry → rule still applies; /work/repo-evil/.env does not pass as inside /work/repo
Fail-closed parsing	11 malformed inputs each throw, with line numbers
Loader	absent / loaded / invalid ≠ absent; project wins over user without merging

Documentation

• New docs/file-contract.md — format, glob syntax, precedence, self-protection, failure behaviour, and the composition rule PR 2 will implement

Release notes label

• release-notes:internal — no user-visible behaviour until PR 2 wires it in

Checklist

• PR 标题是 conventional commits 格式
• 所有 commits 都是 conventional commits 格式
• 添加了对应测试
• CI 全绿（待 CI 运行）

Related

Plan §2.A. Research: docs/research/floatboat.md §4.4(1).

🤖 Generated with Claude Code