A folder is a database with no schema.

A configuration repository may contain hundreds of individually valid YAML files and still be broken as a project. A workflow can refer to an action in another file that was deleted, a required document can be missing, or a file can sit somewhere no consumer expects it. The folder has rules even if nobody has written them down together.

The filesystem design proposes one Layout that declares allowed paths, formats, per-file schemas, and identities. A pure core would validate supplied path-to-text documents, while a thin host adapter would read and write actual files. The aim is one interpretation of a project for CI, editors, and agents.

Use this page to evaluate the proposed architecture. For a working product today, try Schematics; for a small custom checker, pair your own file routing and decoding with algebra. There is no filesystem install command to run yet.

1. Today: describe the repository's rules

   List the documents that may exist, which are required, their parsing formats, and their Effect schemas. Use the proposed Layout example as a design sketch; it is not an installable API.

2. Today: identify cross-file meaning

   Name entity types and the fields that define or reference them. Algebra can already validate decoded values provided by your own loader; the planned filesystem layer would add routing and source positions.

3. Planned: make checking the shared boundary

   A future implementation would load a text snapshot and produce project diagnostics before changes reach a deployment or agent workspace. Parsing, validation, planning, and writing would remain distinct stages.

const Project = Layout.make({
  files: {
    "project.yaml": Layout.file(Format.yaml, ProjectSchema, { required: true }),
    "actions/:action.json": Layout.file(Format.json, ActionSchema, {
      identity: { type: "Action", capture: "action" },
    }),
    "workflows/**/*.yaml": Layout.file(Format.yaml, WorkflowSchema),
  },
  unmatched: "error",
})

hr-config/
├── project.yaml                  ✓
├── actions/
│   ├── send-welcome-email.json   ✓
│   └── order-laptop.json         ✓
├── workflows/
│   └── onboarding.yaml           × 4:5 unresolved Action "notify-manger"
└── notes.txt                     × unmatched-file

The layout and output illustrate the specification. They do not execute a filesystem implementation.

A config review can eventually explain what a deletion breaks.

A project contains actions/*.json and workflows/*.yaml. A workflow references notify-manager, but the action file is absent. Each remaining file is syntactically valid.

1. Route — planned

   The layout would identify each document's format and schema from its path and captures.

2. Link — planned

   After decoding, a combined graph would resolve references against definitions across the project's files.

3. Report — planned

   The unresolved reference would become a diagnostic at the workflow's source range. Format-preserving repair is a later phase.

Each library owns one kind of meaning. Combine the ones your application needs, with an explicit boundary between their jobs.

• filesystem + algebra ↗

  This is the proposed relationship engine underneath cross-file checks. The design needs a shared graph across routed documents; algebra's existing relation annotations describe the domain meaning.

• filesystem + predicates ↗

  A later phase proposes project constraints over decoded documents. Conditions could describe rules across the project, but constraint execution and serializable layouts are not implemented.

• filesystem + logic ↗

  Action definitions could be stored as schema-checked documents. A layout would validate the files; a separate permitted executor would run actions. The filesystem design does not execute code discovered in files.

• filesystem + workflow ↗

  Workflow definitions could live beside their referenced action and event definitions. Their long-running instance checkpoints would still need the workflow host's own persistence protocol.

• filesystem + core ↗

  Portable contracts could help other tools inspect stored program definitions. The initial proposed layout uses native Effect schemas; carrying a complete layout as JSON is a further design question.

These are application composition patterns, not a promise of automatic adapters. Align Effect peers and artifact formats before combining runtimes; source prototypes can differ from published releases.

All libraries are pre-1.0. Pin exact versions and plan for changes to APIs and artifact formats.