AFS exposes path operations. The provider responsible for a path supplies the operation and its behavior. Do not model the API as one universal filesystem with mandatory support for every verb.
Evidence for this page: packages/core/src/type.ts (AFSModule, AFSRoot), packages/core/src/afs.ts, packages/core/src/capabilities/types.ts (OperationsDeclaration), packages/core/src/error.ts, checked against ARC source 44fbd616f and CLI arc 2.0.0-beta.28.
Operation families
| Operation | Module method (core) | Purpose | Capability boundary |
|---|---|---|---|
list | list? | Enumerate entries under a path | Options and listing semantics are provider-defined; unsupported list flags may be best-effort |
read / batch read | read?, optional batchRead? | Read one or more resources | Depends on provider and path; visibility: "meta" returns meta only |
write / batch write | write?, optional batchWrite? | Create or change content | Writable is not implied by path existence; write modes include replace/append/prepend/patch/create/update |
delete / batch delete | delete?, optional batchDelete? | Remove resources | Recursive and predicate options are provider/feature-specific |
rename | rename? | Move/rename within provider rules | Not every CLI surface exposes rename; check core/API and provider |
stat | stat? | Inspect metadata | Shared result envelope; fields inside are provider-defined |
search | search? | Free-text retrieval | Coverage and ranking are provider-defined; see Search and query |
exec | exec? | Invoke an action at a path | Requires explicit action path, args, and permission/severity policy |
explain | explain? | Report how a path resolves | Use for routing and ownership inspection |
query | query? (optional) | Typed collection query via /.actions/query | Optional and strict; declare fully or not at all |
Optional methods on AFSModule are real: a provider that omits a method does not implement that operation. Root AFSRoot requires the common ops at the dispatcher level and still routes through mount capabilities.
Capability declaration
Providers declare operations through OperationsDeclaration (boolean or { supported, features }):
| Field | Notes |
|---|---|
read, list, write, delete, search, exec, stat, explain | Core op flags |
query? | Mirrors the standard collection-query action for tooling |
batchWrite?, batchDelete? | Often derived; pushdown needs method presence + features.batchPushdown |
subscribe?, interact? | Optional event / human-elicitation capabilities |
Sub-capability features (examples):
| Feature | Meaning when declared |
|---|---|
write.features.ifMatch | Optimistic concurrency via opaque meta.version; must enforce or reject, not silent degrade |
list.features.orderBy | Server-side list ordering |
delete.features.where | Predicate delete |
Read live declarations when available:
arc afs read <mount>/.meta/.capabilitiesAccess mode and visibility
| Concept | Values | Effect |
|---|---|---|
accessMode | readonly · create · append · readwrite | Constrains which mutations are allowed at the module/mount |
visibility | full · meta | meta: read returns metadata only; search denied |
Do not assume readwrite from the fact that a path lists children.
Error codes (selected)
From packages/core/src/error.ts. Applications should branch on code, not English message text alone.
| Code | Class | Typical cause |
|---|---|---|
AFS_NOT_FOUND | AFSNotFoundError | Path does not exist |
AFS_UNSUPPORTED | AFSUnsupportedError | Operation not supported |
AFS_VALIDATION_ERROR | AFSValidationError | Bad args or strict query/spec failure |
AFS_READONLY | AFSReadonlyError | Mutation against readonly surface |
AFS_ACCESS_MODE | AFSAccessModeError | Violates mount access mode |
AFS_ACCESS_DENIED | AFSAccessDeniedError | Substrate access denied |
AFS_FORBIDDEN | AFSForbiddenError | Policy forbid |
AFS_AUTH_REQUIRED | AFSAuthRequiredError | Mutating action needs auth |
AFS_CONFLICT | AFSConflictError | ifMatch version mismatch |
AFS_ALREADY_EXISTS | AFSAlreadyExistsError | Create/collision |
AFS_MOUNT_FAILED | AFSMountError | Mount check failed |
AFS_ACTION_NOT_FOUND | AFSActionNotFoundError | Unknown action |
CLI observation on beta.28: missing path via arc afs read prints ERROR: Path not found: … and exits 5.
CLI vs core surface
| Surface | Ops commonly exposed |
|---|---|
arc afs (beta.28) | ls, read, write, delete, stat, exec, explain, search, mount |
Core AFSModule | Above plus rename, optional query, optional batch pushdown, subscribe, etc. |
If you need an operation that is in core types but missing from the CLI group, use the programmatic/RPC surface or check whether a root /.actions/* action covers it. See arc afs.
Provider authors
Implement an AFSModule (typically via AFSBaseProvider and operation decorators), expose only operations you can enforce, and run shared conformance tests. Continue with Author a provider.