Docs — `ProjectFiles` contract + fetch-then-build materialization

Document the ProjectFiles contract and the fetch-then-build materialization pattern for remote hosts, so plugin and adapter authors know the seam and how a hosted renderer feeds it.

claude/v0-27-0-planning-sgq68k View source

Criteria completion

Tracking started Jun 25 — check back for trends.

Relationships

ID:SPEC-113Status:accepted

ProjectFiles seam — virtual project filesystem for hosted and in-browser builds

ID:ADR-025Status:proposed

Incremental rebuild: dependency-tracked invalidation with the registry as firewall

Date:2026-06-25

ID:WORK-484Status:done

fileRoots + plan scan + loadContentFromTree plumbs; in-memory full-build test

Priority:highComplexity:moderateMilestone:v0.27.0

ID:v0.27.0Status:planning

v0.27.0 — External data & hosted content

claude/v0-27-0-planning-sgq68k current ready

changeset-release/main done claude/milestone-v0-27-0-yqiu8v done main done

Jun 25, 10:22 AM4eab338
Created (ready)by bjornolofandersson

Scope

Contract — the ProjectFiles interface (read/list/exists over normalized POSIX keys, containment as contract), the stock providers, and when a consumer should read through it.
Materialization — the fetch-then-build recipe (tarball-at-SHA → Map → ContentTree by key-prefix → memoryProjectFiles + loadContentFromTree), the one-map/tree-derived-from-it point, and the warm-instance / incremental-fetch tradeoff (atomic snapshot vs single-key patch).
Cross-link ADR-025 for the incremental-rebuild direction the recordable wrapper enables.

Acceptance Criteria

Plugin-authoring / adapter docs describe the ProjectFiles contract and the fetch-then-build materialization pattern for remote hosts.
The warm-instance / incremental-fetch tradeoff and the "one map, tree derived from it" model are documented.

Dependencies

WORK-484 — the contract is stable once the consumers + loadContentFromTree plumb land.

References

SPEC-113 §4 + Acceptance Criteria (docs) · ADR-025 · site/content/extend/plugin-authoring/.