AFS behavior is always instance-shaped. The same CLI binary against two daemons, two ARC data directories, or two mount tables will not produce the same paths.
Verified with arc 2.0.0-beta.28 against a local daemon unless noted.
Mounts
| Fact | Detail |
|---|---|
| Mount binds a path prefix to a provider URI | Example shape: /modules/project -> fs:///absolute/path |
| List mounts | arc afs mount list / arc afs explain mount |
| Validate config shape | arc afs mount validate → Configuration is valid on the verification host |
| Secrets | URIs may embed credentials (tokens, vault paths). Redact before sharing |
mount add is not automatically an acceptance path
On beta.28, the following sequence was observed:
arc afs mount add /modules/… fs:///tmp/…printedMounted ….arc afs mount listshowed the new row.arc afs explain <path>reportedTYPE unknown.lsreturned empty or connection errors;readreturned not found.arc afs mount remove <path>cleared the list entry.
Do not document a recipe that assumes add-then-immediately-write succeeds on every host. Prefer:
- inspecting mounts that are already serving data, or
- an isolation procedure your team has verified end-to-end (separate data dir / service instance), then re-check with
stat/lsbefore mutation.
Permissions and access
| Layer | What it constrains |
|---|---|
Provider accessMode | readonly / create / append / readwrite |
visibility | full vs meta (meta denies search content) |
| Action severity / policy | Which exec actions may run |
| Caller / network gates | Auth and network-read rules on some mounts |
A root that lists write among root actions still does not make every child mount writable.
Instance state
| Kind of state | Examples | Doc implication |
|---|---|---|
| Process | Running daemon PID/port under the host's AFS data dir | CLI often talks to this daemon |
| Mount table | Configured provider URIs | Environment-specific |
| Provider data | Files under an fs:// path, vault contents, remote resources | Mutation changes real data |
| Blocklet / space data | Under local DID Space trees | Different board; do not treat as disposable |
Do not treat an arbitrary long-lived daemon as disposable test infrastructure. Commands that register mounts or write provider data need a deliberate isolation story.
Local validation vs formal publish
| Surface | What it proves | What it does not prove |
|---|---|---|
Local arc afs … against your daemon | This instance's path/ops/mount behavior | Global product defaults, multi-tenant deploy |
| Local blocklet service / browser (site docs) | Site rendering of documentation | Remote DID Space hosting of your app |
arc deploy / DID Space publish | Publish integration when that is the task | Local AFS contract correctness by itself |
| Provider conformance tests in ARC monorepo | Provider interface discipline at a commit | That your host's mounts match that provider |
For this AFS board, local inspection and recipes are the primary evidence. Formal publish is a separate checklist—use it only when the task is deployment.
Practical checklist
- Record
arc --version. - Prefer read-only commands until mounts and capabilities are known.
- Read
<mount>/.meta/.capabilitieswhen present. - Mutate only on mounts you own; clean up disposable paths.
- Redact secrets from any shared output.
- When a command fails, preserve the exact error—do not invent success output.