Skip to main content

AFS

Author a provider

Start a provider from the current JSON provider and its conformance suite, then declare only enforceable capabilities.

Start from a provider covered by current tests, not from an old planning document. In the ARC source tree:

ArtifactRole
providers/core/json/src/index.tsCompact implementation baseline (AFSJSON extends AFSBaseProvider)
providers/core/json/test/conformance.test.tsConformance fixture via runProviderTests
packages/testing (@aigne/afs-testing)Shared suite runner and contract-gated fixtures
docs/guides/provider-authoring.mdAuthoring discipline (ops vs semantic actions, ifMatch, query)

Minimal public contract

PieceWhat to implement
Module identityname, optional description, uri / load params
Path ownershipStable path layout; no reserved virtual prefix abuse (.actions, .meta, .as, …)
OperationsOnly methods you can enforce: list / read / write / delete / stat / search / exec / explain / rename / optional query / optional batch
Capability declarationOperationsDeclaration (+ features). Declare ⇒ execute; never advertise ifMatch/query without enforcement
ErrorsUse shared AFS*Error codes (AFS_NOT_FOUND, AFS_VALIDATION_ERROR, AFS_CONFLICT, …)
Conformancetest/conformance.test.ts calling runProviderTests

Typical baseline pattern (JSON provider):

  1. Extend AFSBaseProvider.
  2. Provide static manifest() / load() for registry/URI loading.
  3. Decorate handlers with @List, @Read, @Write, @Delete, @Search, @Stat, @Explain, …
  4. Override getOperationsDeclaration() when you need features such as ifMatch.
  5. Expose /.meta/.capabilities for runtime discovery.

Run the JSON baseline conformance

From a current ARC monorepo checkout (package @aigne/afs-json):

bash
pnpm --filter @aigne/afs-json test -- test/conformance.test.ts

Verified on ARC source 44fbd616f (2026-08-10):

text
372 pass
6 skip
0 fail
Ran 378 tests across 1 file.

Treat that result as evidence for this baseline and this commit, not for every provider or every release. Skipped suites (for example subscribe when not declared) are expected when fixtures omit optional capabilities.

Suggested implementation order

  1. Sketch the FS layout (directories vs leaves vs action paths).
  2. Implement inspection first: list + read (+ stat/explain). Anything stored should be enumerable—do not hide data only behind custom actions.
  3. Add path mutation (write/delete/rename) only where the store can enforce it.
  4. Add semantic @Actions only for operations that need provider-specific meaning beyond path CRUD.
  5. Wire runProviderTests with a structure fixture matching real data.
  6. If you declare query, ship a collectionQuery fixture (declare ⇒ test).
  7. If you declare write.features.ifMatch, ship ifMatch and peerProvider against the same backing store.
  8. Document data, auth, search, and failure boundaries separately from the generic AFS contract.

Do not claim query because you can list, or a particular search quality because you expose search.

Keep an acceptance record

Use this record before presenting a provider as a public catalog candidate. It is a checklist, not a claim that every provider has already passed it.

RecordWhat to capture
ContractOwned paths, operations, declared capabilities; do not infer one from another
Data and access boundaryBacking system, credentials or caller boundary, data read/changed, observable failures
Conformance evidenceExact test command, ARC/source version, pass/skip/fail counts
Local acceptanceIsolated local exercise: ARC version, commands, non-secret env choices, observed result. Do not substitute DID Space deploy for local evidence
CompatibilityARC/runtime version and provider backend versions the observation depends on
Support ownershipMaintainer, lifecycle state, documentation location users should rely on

If any row is unknown, keep the provider out of the public catalog. A package in the source tree is implementation evidence, not a support promise. See Provider catalog.