Data and AFS | ArcBlock

For a Blocklet, AFS is the public data boundary: paths, operations, and declared capabilities. A provider may use files, SQLite, object storage, or a remote service internally. That choice is not the application contract.

This page covers Blocklet-side integration. Core AFS operations and provider authoring live on the AFS board.

How a Blocklet meets AFS

Mechanism	Where declared	Role
Package files as readonly tree	Built into `dist/.afs/manifest.json`	Static package assets addressable as a tree
`mounts`	`blocklet.yaml`	Attach providers at absolute targets (`/ash`, custom modules, …)
`seed/`	Package directory + optional `instance.seed`	First-run material for instance data
`replicated`	`blocklet.yaml`	Collection ownership/copy contracts
`sites.bindings`	`blocklet.yaml`	Map HTTP paths to AFS paths + AUP pages
`networkRead`	`blocklet.yaml`	Allow network-origin reads of selected `/instance/**`
`index`	`blocklet.yaml`	Index domains for search over declared paths

Package tree vs `/instance`

Path family	Meaning
Package root / `/packages` projection	Immutable (for a version) application assets
`/instance`	Instance-scoped data space when the package needs one
`/user` / caller overlays	User-scoped data when `scope` and session model require them

arc blocklet build reports the instance posture:

# basic recipe
instance: stateless

# minimal-app recipe
instance: requires /instance DID Space

Rules:

If the package needs /instance and no real DID Space is bound, stateful features must fail closed — do not pretend seed files are a live instance space.
seed/ is initialization input, not a substitute for a bound instance DID Space after first run.
Local HTTP 200 on a static or shell page does not prove /instance writes succeeded.

Mounts

Declare only providers the package uses:

mounts:
  - uri: "ash://"
    target: /ash
    required: true

Or a local module:

mounts:
  - module: "./providers/my-provider"
    target: /my
    required: true

Optional fields include ops (whitelist), aup (recipe scan path anchored at $PROGRAM_DIR or $DATA_DIR), seed (copy package files into a cold mount), and shared.

Inspect what the convention scanner sees:

arc blocklet dev ./demo-min
# Mount: agents/app-agent → /agents/app-agent
# Mount: pages → /pages

Seed and settings

Complete-app recipes generate seed/settings/… JSON and AUP shells. Treat them as package defaults for instance initialization. Changing seed changes the package; changing live instance settings changes instance data.

Replicated collections (reference pattern)

Discuss Kit declares collections under replicated: (posts, comments, anon) with canonical, copy, minRole, readRole, and delete rules. That pattern is a reference implementation of replicated discussion data — not a claim that every historical product surface is platformized.

Read Discuss Kit lineage for scope and limits. Study the live manifest in the ARC tree at blocklets/discuss-kit/blocklet.yaml (read-only reference).

Bindings: URL → AFS → page

Example shape (Discuss Kit):

sites:
  - name: discuss-kit
    domains:
      - discuss-kit.localhost
    bindings:
      - id: posts-list
        path: "/posts"
        afs: "/instance/app/content/posts"
        page: index
      - id: post-detail
        path: "/posts/{slug}"
        afs: "/instance/app/content/posts/{slug}"
        page: detail

Use bindings when the product URL is a first-class map onto instance content. For pure Web Device static sites, prefer .route/web + pages/ as in Build a first site.

What to read next on the AFS board

Need	AFS page
Operations and capability boundary	Core contract
List vs query vs search	Search and query
Provider authoring	Author a provider / Providers
Local inspection commands	Local inspection

Hard boundaries

Do	Do not
Address data via AFS paths	Promise a specific SQL schema as the public API
Declare mounts the package needs	Mount host-global paths without understanding scope
Mark `/instance`-dependent features clearly	Claim seed files alone prove multi-user instance data
Link AFS board for op catalogs	Duplicate the full AFS op reference here