Consolidate daemon read-side vocabulary (…View / Endo* / EndoGitTree) and the tree/filesystemAt surface

[0xpatrickbot]

Problem

The daemon carries three parallel vocabularies for "the read side of a file or directory," under three different naming idioms, with overlapping or identical shapes. On top of that, the Git capability exposes two historical-read methods with distinct result contracts. This blurs the convention that #643 established (a bare name is the portable @endo/platform shape; an Endo prefix marks the daemon's authority-bearing specialization) and forces callers to learn more than one historical-read surface.

Symptoms

All references are in packages/daemon/src/types.d.ts (plus the Git surface in @endo/exo-git):

• ReadableBlobView and EndoReadable have identical members (streamBase64, text, json, getInfo, fetch, help). Two names, one shape.
• ReadableTreeView is EndoReadableTree minus the content-address identity (sha256). EndoGitTree is a third has / list / lookup read-tree. Three read-tree types share one structural core.
• Within a single type the idioms mix: EndoMountFile.readOnly() returns a ReadableBlobView, while EndoMountFile.snapshot() returns an EndoReadable. Two read faces of the same file, two vocabularies.
• The ...View suffix collides with the platform names it says it mirrors, and it fits neither the bare-name axis nor the Endo axis.
• Git.tree(ref): Promise<ReadableTree> and Git.filesystemAt(ref): Promise<Filesystem> are both live implementations. filesystemAt is the richer and preferred surface, and it already has a cross-package consumer in agent-tools.

Findings on the historical-read entry point

filesystemAt(ref) should be the canonical entry point for new caller and agent-facing work. It returns the same Filesystem vocabulary used for the live worktree, supports the richer directory/file operations, range reads, BlobRef snapshots, and composition, and gives a new caller one durable mental model.

Removing tree(ref) still fits the eventual small-surface goal, but it is not a documentation-only or mechanical migration:

• Both methods are implemented and covered by tests. The premise that they are Phase-1 stubs is stale.
• filesystemAt(ref).root() returns an @endo/platform Directory; that interface has no readOnly() method. The proposed filesystemAt(ref).root().readOnly() replacement is therefore not type-correct.
• ReadableTree and Directory have different contracts. A removal needs each current tree use to be rewritten to the operation it actually needs, or needs a deliberately designed adapter. A compatibility adapter would preserve a second public concept, so it should not be introduced merely to make the migration appear cheap.

The DX/AX decision is consequently: recommend filesystemAt now, retain tree only as the existing compatibility surface, and make removal a focused implementation change once its call-site rewrites are demonstrated. That change should delete tree, migrate the existing tests, and avoid adding a new public bridge unless a concrete consumer requires one.

Proposed solution

Collapse onto one Endo read hierarchy, retire the ...View idiom, and use one canonical historical-read entry point.

Read types:

• EndoReadable: read side of a blob or file (streamBase64, text, json, getInfo, fetch, help). EndoMountFile.readOnly() returns this. Delete ReadableBlobView.
• EndoReadableTree: base read-tree (has, list, lookup, help). EndoMount.readOnly() returns this. Delete ReadableTreeView.
• EndoSnapshotTree extends EndoReadableTree, adding sha256 and getInfo (the content-addressed tree).
• EndoGitTree extends EndoReadableTree, adding the git-archive methods (the historical view).

Surface:

• filesystemAt(ref) is the canonical historical-read entry point.
• tree(ref) is a compatibility surface, not a projection claim. A focused implementation follow-up may deprecate and remove it after it replaces each caller with a type-correct Filesystem operation and verifies no public bridge is needed.

Retire the ...View idiom entirely, folding makeReadableTreeView and makeReadableBlobView into the Endo readables.

Result

One daemon read hierarchy (EndoReadable, EndoReadableTree, plus the snapshot and git specializations) that mirrors the platform ReadableBlob / ReadableTree / SnapshotTree shapes, with no bare ...View names. New historical-read consumers use filesystemAt(ref); the implementation follow-up decides whether the remaining compatibility method can be removed without adding a kitchen-sink bridge.

Out of scope

• The @endo/platform and mount path-type consolidation in refactor(fs): consolidate mount and Git capability contracts #643 (landing separately).
• The four remaining Git remote and ref unknown declarations in @endo/exo-git (ensureCredentialUsable material, updatedRefs, head, branch), which are a separate builder change.

References

• refactor(exo-git): own public git capability types #633 and refactor(fs): consolidate mount and Git capability contracts #643 established the bare-name versus Endo-prefix convention.
• feat(daemon): Git.filesystemAt(ref) — endo-fs Filesystem over a git tree #374 merged filesystemAt, which makes the tree / filesystemAt reconciliation ripe.
• designs/daemon-git-next-steps.md section 5 ("Reconcile TreeRef and FilesystemAtRef into one canonical vocabulary").

[0xpatrickbot]

Three updates from the code-mode workspace work that bear on this issue. None of them invalidate the proposal; they sharpen its assumptions.

1. The proposal has an implicit dependency worth making explicit. The "one Endo read hierarchy that mirrors the platform shapes" framing presumes the daemon mount surface remains permanently parallel to the platform Filesystem, with from-mount.js as the bridge. There is an open direction question in the other direction: whether EndoMount is eventually subsumed by the extended platform Filesystem (the fs/extended ROADMAP and the #326 lineage point that way). The consolidation here is worth doing under either answer, since collapsing three read vocabularies onto one eases both outcomes, but the issue should state which assumption it makes. If the subsume direction wins, the consolidated Endo read hierarchy is transitional rather than durable, which affects how much specialization (for example EndoSnapshotTree) is worth investing in versus converging directly on the platform ReadableBlob / ReadableTree names.

2. Fresh support for filesystemAt as the canonical historical-read entry point. The agent-tools workspace configuration story now fixes read-only historical views as one of the four standard ways a host backs the code-mode workspace global: Git.filesystemAt(ref) (or a readOnly() attenuation) handed to the guest pre-attenuated, with the backend invisible to the guest. That is a concrete new consumer class standardizing on exactly the entry point this issue recommends, and it postdates the issue's findings.

3. The out-of-scope exo-git unknowns may partially resolve without a builder change. #902 now generalizes the shared code-mode type extractor to follow import() type references from any @endo/* package transitively, instead of collapsing everything outside @endo/platform/ to unknown. If any of the four listed unknown declarations (ensureCredentialUsable material, updatedRefs, head, branch) were boundary collapses rather than authored unknowns, the regenerated git-remote declarations will pick up the real shapes when that lands. Worth a re-check against the regenerated output before scoping the "separate builder change."

One non-issue checked deliberately: this proposal edits packages/daemon/src/types.d.ts, and the current type-source policy (authored TypeScript as the substrate for generated declaration surfaces, no new hand-authored .d.ts) grandfathers the daemon's existing types.d.ts, so there is no conflict to reconcile here.