feat: US-001 - Add shared FS conformance test suite to core

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[railway-app]

🚅 Deployed to the rivet-pr-4525 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
frontend-inspector	❌ Build Failed (View Logs)	Web	Mar 29, 2026 at 11:04 pm
frontend-cloud	❌ Build Failed (View Logs)	Web	Mar 29, 2026 at 11:04 pm
website	❌ Build Failed (View Logs)	Web	Mar 29, 2026 at 11:03 pm
mcp-hub	✅ Success (View Logs)	Web	Mar 29, 2026 at 11:03 pm
ladle	❌ Build Failed (View Logs)	Web	Mar 29, 2026 at 11:02 pm
kitchen-sink	❌ Build Failed (View Logs)	Web	Mar 29, 2026 at 11:02 pm

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat: US-001 - Add shared FS conformance test suite to core #4525 👈 (View in Graphite)
• chore: RivetKit perf fixes #4523 : 2 other dependent PRs (#4535 , #4537 )
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: Add shared FS conformance test suite to core

This PR refactors the agent-os filesystem backends by extracting S3 into a new package, adding Postgres/SQLite/sandbox backends, and a shared conformance test suite. The architecture is solid, but there are several correctness, test quality, and design issues worth addressing.

Bugs and Correctness:

1. removeFile on S3 now throws ENOENT - behavioral change that breaks idempotency: packages/fs-s3/src/index.ts - The new code adds a HeadObjectCommand check before DeleteObjectCommand, making deletions of nonexistent keys throw ENOENT. The old implementation silently succeeded. Any caller relying on idempotent deletes will now break.

2. Non-atomic S3 rename - delete can race after copy succeeds: packages/fs-s3/src/index.ts - If CopyObjectCommand succeeds but DeleteObjectCommand fails, the file exists at both locations. Add a comment noting the non-atomicity.

3. Symlink size stored as character count, not byte count: packages/fs-postgres/src/index.ts, packages/fs-sqlite/src/index.ts - size: target.length uses UTF-16 code units. Use Buffer.byteLength(target).

4. link() copies content at insert time - hard link semantics broken: Both backends insert a new row with copied content. Subsequent writes to the original do not update the link. Document clearly.

5. readDir on nonexistent path silently returns empty array: Should throw ENOENT instead.

6. TOCTOU race in Postgres mkdir: packages/fs-postgres/src/index.ts - A getRow check followed by INSERT ... ON CONFLICT DO NOTHING is not atomic. Wrap in a transaction.

Test Quality:

7. Several failure-case tests have no assertions on the success path: If no error is thrown, the test passes with zero assertions. Add expect.fail in the non-throwing branch.

8. expect(true).toBe(true) antipattern: Replace with meaningful assertions or remove.

9. Module-level conformanceTmpDir shared across parallel test runs: packages/core/tests/host-dir-backend.test.ts - Scope the variable inside the closure.

Architecture and Design:

10. Test helpers exported from core package.json exports: ./test/file-system and ./test/docker are exported as public API. Consider a separate @rivet-dev/agent-os-test-utils package or mark as internal/unstable.

11. sandbox-agent is a devDependency but used in a publicly exported module: docker.ts imports sandbox-agent as a devDependency. Consumers will get a runtime failure. Move to peerDependencies or add a clear error message.

12. Postgres test schema uses Date.now() for uniqueness: Schema names can collide in rapid test runs. Use crypto.randomUUID().

13. vitest.config.ts testTimeout may expire before Docker container is healthy: testTimeout: 30000 does not cover the beforeAll hook. Set hookTimeout explicitly.

Minor:

• S3BackendOptions re-export: add a deprecation JSDoc comment.
• fs-sandbox pread: add a comment about the memory limitation.

Overall this is a well-structured refactor. The highest-priority items before merge are the S3 removeFile behavioral change, missing conformance test assertions, and the devDependency/public-export mismatch.