Do not use list, query, and search as names for the same feature. They solve different problems and make different promises.
Evidence: packages/core/src/capabilities/collection-query.ts, docs/guides/collection-query.md, AFSModule.search / query in type.ts, and CLI runs on arc 2.0.0-beta.28.
Three contracts
| Operation | Use it for | Do not assume |
|---|---|---|
list | Enumerating paths or entries under a path | A relevance-ranked result set, or a provider-independent data query language |
query | A typed collection specification at the standard /.actions/query action | Client-side fallback when a provider has not declared the capability |
search | Provider-defined free-text retrieval returned in a shared result envelope | Universal full-text coverage, semantic retrieval, a shared index, or one ranking algorithm |
list — best-effort enumeration
list is the filesystem-style directory walk. Unsupported options may be ignored or marked (for example order-by ignored metadata). It is the right tool for "what children exist here?"
arc afs ls /modules/projectsearch — provider-defined free text
arc afs search <path> <query>Verified sample on a local fs:// mount (arc 2.0.0-beta.28):
arc afs search /modules/project RELEASING/modules/project/CLAUDE.md
/modules/project/README.md
/modules/project/RELEASING.md
…| Rule | Detail |
|---|---|
| Ownership | The provider owns what it searches, how it indexes, and how it ranks |
| Envelope | ARC returns matches in AFSSearchResult and can merge searchable providers under the requested path |
| No global promise | Merging results is not a global FTS index or semantic search product |
| Visibility | On visibility: "meta" mounts, search is denied |
Document search expectations in the provider's docs, not by copying behavior observed on a different provider.
query — optional and strict
Collection query is the typed action at /.actions/query (entries mode and aggregate mode). Philosophy is declare ⇒ execute the whole spec. Malformed specs and unsupported blocks are AFS_VALIDATION_ERROR (or equivalent). There is no silent client-side degradation to "sort of query via list".
Probe before relying on it: read <mount>/.meta/.capabilities (or root capabilities) and look for the standard action with name === "query" and pathTemplate === "/.actions/query". Provider-local dialects (for example table-scoped query paths) are not this contract.
Verified on beta.28 against an fs:// project mount that does not offer collection query on this surface:
arc afs exec /.actions/query --args '{"path":"/modules/project","limit":2}'ERROR: Collection query is not available on this surfaceExit code observed: 5. That failure is the correct signal—not a partial list of files.
When a provider does declare query, a consumer issues a typed spec (fields such as path, doc, where, orderBy, limit/offset or cursor, count, groupBy, optional aggregate ops). Full field vocabulary and provider implementation checklist live in ARC's internal guide docs/guides/collection-query.md and packages/core/src/capabilities/collection-query.ts.
Choosing among the three
| Goal | Prefer |
|---|---|
| Browse a tree | list |
| Find free-text matches the provider knows how to find | search (after checking capability) |
| Server-side typed filter / order / count / aggregate over a record collection | query (only if declared) |
| "Search everything on the machine like a desktop FTS product" | Out of contract for AFS as a whole |
Product narrative caution
A future document library or NAS-oriented product may still layer catalogs, selected full-text collections, and richer indexes as separate product choices. Those choices are not automatic consequences of using AFS paths.