Engine - Filesystems - Catalogue

[ollieread]

Engine - Filesystems - Catalogue

The component itself: the Flysystem dependency, an immutable catalogue of named filesystems, and the
three the engine is given.

Parent: Engine - Filesystems.

Shape

FilesystemCatalogue is constructed from an array<string, FilesystemOperator> and resolves by name. It
is the catalogue half of the pattern used throughout, with no registry half, because nothing registers: a
filesystem is either given at construction or it does not exist.

That is the same state the container's catalogues are in today, built directly from arrays, so this
introduces no new shape.

Given filesystems

Name	Adapter	Holds
config	local	config.toml, config.d/, module config
data	local	Engine and module data
cache	local	Cached content, not includable output

data and cache have no consumer yet. They are included because they are directories the engine
already names in Paths, and adding them later would mean revisiting every construction site.

The public type

get() returns League\Flysystem\FilesystemOperator, not an engine-owned interface. Module authors work
with filesystems directly, so the familiar type is the right one, and wrapping would cost twenty-one
delegating methods to maintain in step with a library that already has them.

Flysystem's own guarantees carry through unchanged: PathTraversalDetected and CorruptedPathDetected
from the path normaliser, and FilesystemException as a marker interface extending Throwable, which is
the convention ContainerException and ConfigException already follow.

Construction

There is no composition root, so the tests construct the catalogue. This is the same position Paths is
in: it exists, only tests build it, and its docblock describes a bootstrap that has not been written. The
wiring lands with bootstrap; nothing here should try to invent one.

Lifetime

Process lifetime. A local adapter holds no connection and is safe for the life of the worker. Whatever
adds the first remote adapter inherits #63's lifetime question and the trap ConnectionFactory fell
into, so it is recorded rather than solved here.

Boundaries

• No config-declared filesystems, no adapter factory, no [filesystems] section.
• No remote adapters.
• No MountManager, no module scoping, no path prefixing.
• No TomlLoader changes. That is the migration card.

Tasks

• Add league/flysystem to require, and league/flysystem-memory to require-dev
• Implement FilesystemCatalogue over array<string, FilesystemOperator>, resolving by name
• Throw a named exception, in the component's own exception set, on an unknown name
• Define construction of the three given filesystems, wired by tests
• Tests: the catalogue resolves each given name
• Tests: an unknown name throws
• Tests: the catalogue is constructible with every filesystem backed by the memory adapter
• Tests: a returned operator reads and writes through its adapter