Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Fingers Are The Primitive Gestures

Hands are how agents act. Fingers are the smallest gestures a hand can make. In Mirage, fingers are ops: read, readdir, stat, write, mkdir, unlink, rename. Each one is a single primitive action, and each one maps cleanly to exactly one kind of backend call (S3 GetObject, list_objects_v2, HEAD, PutObject, and so on). They are the atoms of filesystem behavior. A higher-level command like cat, grep, or cp is not itself a finger. It is a phrase of fingers the Hand strings together.

​
The Finger Set

FingerGestureTypical backend call
readpull bytes from a pathGetObject, file read
readdirlist children of a directorylist_objects_v2, scandir
statfeel for shape (size, type, mtime)HEAD, stat
writeput bytes at a pathPutObject, file write
mkdirmake a directorymkdir, prefix marker
unlinkremove a fileDeleteObject, unlink
renamemove a pathCopyObject + DeleteObject
createlay down an empty filezero-byte PutObject, touch
truncatecut a file to zero bytesPutObject empty, truncate
appendadd bytes at the endmultipart append, file append
Each finger’s contract is narrow on purpose: a single path, a well-defined input, a well-defined output. Narrow contracts are what let any finger move against any Eye without special casing.

​
Fingers Are Fundamental Infrastructure

The Fingers layer has two pieces:
  • Ops, the primitive gestures themselves, dispatched through the mount table to the right resource.
  • FUSE, a way to expose those same gestures to any process on the host through POSIX. Any shell, editor, or subprocess becomes a legitimate user of fingers, not just Mirage’s own dispatcher.
Both are fundamental in the literal sense: everything above them, every Gesture, every pipeline, every agent plan, is built on top. Backends only need to implement fingers to become part of Mirage. FUSE then takes those fingers and makes them usable by anything POSIX understands.

​
Why This Foundation Matters

A small set of fingers supports an unbounded set of gestures above it. Add a backend: implement the finger contract and every existing Gesture in the catalog, cat, grep, cp, jq, works against it automatically. Add a gesture: it runs against every existing backend for free. The catalog grows without churning the resources, and the resources grow without changing the catalog. This is the concrete mechanism behind Mirage’s N + M promise. Fingers are the small M-side interface every backend speaks. Gestures are the N-side catalog agents draw from. They never multiply into N × M adapters because they don’t talk to each other; they both talk to fingers.
  • Ops, how fingers are dispatched through the mount table to resources.
  • FUSE, how fingers get exposed to external processes via POSIX.
  • Gestures, what Mirage builds on top of fingers.
  • Hands, the higher-level metaphor fingers belong to.