t81-foundation

CanonFS Interchange Example

This is the smallest golden RFC-00D1 example in the repo.

It shows a real host directory import into CanonFS, a real export back out to a host directory, and the built-in policy-profile surface that currently ships as the narrow v1 candidate contract.

If you want the single frozen v1 contract fixture set, start in:

• examples/storage-and-canonfs/canonfs-interchange/v1/

For the current build-against boundary, pair this example with:

• spec/rfcs/RFC-00D1-canonfs-foreign-filesystem-interchange.md
• examples/storage-and-canonfs/canonfs-interchange/v1/README.md

Current Build-Against Boundary

The current RFC-00D1 v1 candidate surface is intentionally narrow.

Treat the following as stable enough to build against today:

• canonfs import
• canonfs export
• t81.canonfs-import.v1
• t81.canonfs-export.v1
• t81.canonfs-import-provenance.v1
• t81.canonfs-export-provenance.v1
• t81.canonfs-interchange-manifest.v1
• source/target kinds host-file and host-directory
• result linkage fields provenance_schema and manifest_schema
• stable structured error fields kind, message, code, reason
• built-in policy profiles permissive, import-only, export-only, deny-all

Still explicitly deferred from full v1 promotion:

• symlink posture
• archive/bundle export
• text output as a co-equal contract
• schema-catalog relocation beyond the RFC-local schema artifacts

Files

• input/alpha.txt
• input/nested/beta.txt
• policy-allow-alpha-only.apl
• policy-deny-all.apl
• policy-allow-example-inputs.apl

Run

From the repo root:

tmp_root="$(mktemp -d)"
canon_root="$tmp_root/.t81_canonfs"
export_root="$tmp_root/exported"

build/t81 canonfs import \
  examples/storage-and-canonfs/canonfs-interchange/input \
  --canonfs-root "$canon_root" \
  --json

Expected shape:

• schema: t81.canonfs-import.v1
• source kind: host-directory
• status: ok
• policy result: allowed
• policy profile: permissive
• provenance schema: t81.canonfs-import-provenance.v1
• manifest schema: t81.canonfs-interchange-manifest.v1
• manifest_ref populated

Export the returned manifest_ref back to a host directory:

manifest_ref="<manifest_ref from previous step>"

build/t81 canonfs export \
  "$manifest_ref" \
  --canonfs-root "$canon_root" \
  --out "$export_root" \
  --json

Expected shape:

• schema: t81.canonfs-export.v1
• target kind: host-directory
• status: ok
• policy result: allowed
• policy profile: permissive
• provenance schema: t81.canonfs-export-provenance.v1
• manifest schema: t81.canonfs-interchange-manifest.v1
• materialized_paths includes alpha.txt and nested/beta.txt

You can verify the exported payloads directly:

cat "$export_root/alpha.txt"
cat "$export_root/nested/beta.txt"

Negative Path

This lane also supports explicit policy-profile denial without needing an extra policy file:

build/t81 canonfs import \
  examples/storage-and-canonfs/canonfs-interchange/input \
  --canonfs-root "$canon_root" \
  --policy-profile export-only \
  --json

Expected shape:

• status: error
• policy result: denied
• policy profile: export-only
• error kind: policy-failure
• error message explains the denied operation
• error code: canonfs-policy-denied
• error reason: policy_denied

Built-In Policy Profiles

The current built-in profiles are intentionally narrow and deterministic:

• permissive allow import and export unless an explicit policy document/evaluator denies the request
• import-only allow canonfs import and deny canonfs export before host materialization
• export-only allow canonfs export and deny canonfs import before CanonFS storage writes
• deny-all deny both canonfs import and canonfs export

The current profile surface is about pre-side-effect admission control, not rich content policy. In other words:

• profile denial happens before CanonFS import writes or export materialization
• JSON result documents still record policy_result, policy_profile, and a structured error with kind, code, reason, and message
• in the current v1 candidate surface, each error object is emitted in stable field order as kind, message, code, reason
• richer policy semantics can still be added later through policy documents without widening the built-in profile names

Built-in profiles and explicit policy files are conjunctive:

• the built-in profile decides whether canonfs import or canonfs export is allowed at all
• an explicit policy file can further narrow which CanonFS objects are admitted within that allowed operation
• the result can therefore be ok, error, or partial without adding new profile names

Policy Document Examples

This example directory also includes two small Axion policy files that work with the current CanonFS interchange lane:

• policy-allow-alpha-only.apl allows only input/alpha.txt, which makes the checked-in directory import and export paths return partial instead of all-or-nothing
• policy-deny-all.apl denies CanonFS import/export through policy evaluation even when the built-in profile is still permissive
• policy-allow-example-inputs.apl allows only the two checked-in example input objects by hash

Validate them directly:

build/t81 policy validate \
  examples/storage-and-canonfs/canonfs-interchange/policy-allow-alpha-only.apl \
  --json

build/t81 policy validate \
  examples/storage-and-canonfs/canonfs-interchange/policy-deny-all.apl \
  --json

build/t81 policy validate \
  examples/storage-and-canonfs/canonfs-interchange/policy-allow-example-inputs.apl \
  --json

Partial import using the checked-in alpha-only policy:

build/t81 canonfs import \
  examples/storage-and-canonfs/canonfs-interchange/input \
  --canonfs-root "$canon_root" \
  --policy examples/storage-and-canonfs/canonfs-interchange/policy-allow-alpha-only.apl \
  --json

Expected shape:

• status: partial
• policy result: partial
• policy profile: permissive
• provenance schema: t81.canonfs-import-provenance.v1
• manifest schema: t81.canonfs-interchange-manifest.v1
• imported_paths includes alpha.txt
• errors[0].reason: policy_denied
• errors[0].message mentions nested/beta.txt

Policy denial through a checked-in file:

build/t81 canonfs import \
  examples/storage-and-canonfs/canonfs-interchange/input \
  --canonfs-root "$canon_root" \
  --policy examples/storage-and-canonfs/canonfs-interchange/policy-deny-all.apl \
  --json

Expected shape:

• status: error
• policy result: denied
• error reason: policy_denied

The same checked-in policy file can deny export under the default permissive profile once you already have a manifest or object ref:

build/t81 canonfs export \
  "$manifest_ref" \
  --canonfs-root "$canon_root" \
  --policy examples/storage-and-canonfs/canonfs-interchange/policy-deny-all.apl \
  --out "$export_root" \
  --json

Expected shape:

• status: error
• policy result: denied
• policy profile: permissive
• error kind: policy-failure
• error reason: policy_denied
• error message explains the denied export

Policy allowlist using the checked-in example input hashes:

build/t81 canonfs import \
  examples/storage-and-canonfs/canonfs-interchange/input \
  --canonfs-root "$canon_root" \
  --policy examples/storage-and-canonfs/canonfs-interchange/policy-allow-example-inputs.apl \
  --json

Expected shape:

• status: ok
• policy profile: permissive
• import/export stay allowed because the policy file admits the example hashes

You can also see the same narrowing effect on export by first importing the directory under the permissive default, then exporting the returned manifest_ref with the alpha-only policy:

build/t81 canonfs export \
  "$manifest_ref" \
  --canonfs-root "$canon_root" \
  --policy examples/storage-and-canonfs/canonfs-interchange/policy-allow-alpha-only.apl \
  --out "$export_root" \
  --json

Expected shape:

• status: partial
• policy result: partial
• policy profile: permissive
• provenance schema: t81.canonfs-export-provenance.v1
• manifest schema: t81.canonfs-interchange-manifest.v1
• materialized_paths includes alpha.txt
• materialized_paths does not include nested/beta.txt
• errors[0].reason: policy_denied
• errors[0].message mentions nested/beta.txt
• errors[0] is emitted in stable field order: kind, message, code, reason

Target-Side Export Failure

The current contract also distinguishes target-side export failures from source or policy failures. One small reproducible case is exporting a single-file CanonFS object to a path that already exists as a directory:

blocked_out="$tmp_root/already-a-directory"
mkdir -p "$blocked_out"

build/t81 canonfs export \
  "$hash" \
  --canonfs-root "$canon_root" \
  --out "$blocked_out" \
  --json

Expected shape:

• schema: t81.canonfs-export.v1
• status: error
• error kind: target-failure
• error message explains that the output file could not be opened
• error code: canonfs-export-target-open-failed
• error reason: target_open_failed

Notes

• This example is intentionally file-based and small.
• It is meant to match the current RFC-00D1 CLI seed and contract tests, not to demonstrate every future interchange feature.
• The round-trip for this directory is exercised directly by canonfs_interchange_test.

This site is open source. Improve this page.