ffractal — ff

One command that finds the cheapest way to answer an intent — or says plainly why it can't.

ffractal is the dispatch of dispatchers. You ask for work (build this, run that, what can do X?); it lowers the request to one provider it is willing to admit, materializes anything missing exactly once, runs it, and publishes the answer to its occupant store so the next identical request is a hit.

Published as @a0n/ff, installed as a single zero-dependency npm package with two commands (ff and ffractal). No workspace, no .bin shims, no monorepo:

npx @a0n/ff --help      # try it right now
npm i -g @a0n/ff        # or install it
ff list

Why this exists (ELI5)

Picture a workshop. The honest old way is a morning routine: every day you rebuild every bench, rewire every machine, and file every tool — whether or not you were going to touch them. That is what an eager bootstrap does. It is safe and it is wasteful, and worse, when it half-fails you cannot tell.

ffractal flips it to a tool crib:

1. You type what you actually want.
2. It looks in the crib first — tools that are already built and already admitted. Hit → hand it over. Nothing is rebuilt.
3. Miss → it builds the cheapest thing that can do the job, once.
4. It writes a receipt. The next identical request is a hit.

The one thing that stays eager is the crib-keeper itself. Bootstrap the dispatcher; admit everything else on demand.

The claim: the toolchain is a cache whose fill path is a build.

Try it in 30 seconds

# What can this do right now?
npx @a0n/ff list

# Ask a question without running anything.
npx @a0n/ff resolve rip

# Would this work, and in what order?
npx @a0n/ff plan build the tensor tools

# What is broken or missing?
npx @a0n/ff doctor

Real output from a checkout where only the core tools exist:

$ npx @a0n/ff list
ID                        KIND   ORIGIN    CAPS            INSTALLED
a0                        bin    core      fs,net,exec     yes
gnit                      bin    core      fs,exec         yes
gnode                     bin    core      fs,exec         yes
monster                   bin    core      fs,exec         yes
monster-guard             bin    core      fs,exec         yes
moonshine                 bin    core      fs,net,exec     yes

$ npx @a0n/ff resolve rip
MISS rip [provider-not-found]

$ npx @a0n/ff doctor
ffractal doctor: findings (6 providers)
  registry open-source/.moonshine: MISSING
  registry open-source/.moonbeam: MISSING

Run it from an empty directory and it still works — the same core list, each provider INSTALLED no, because the resolver is honest about what is not there rather than guessing.

Run a file (the onramp)

ff lazily materializes the engine it needs. On a machine with nothing but Node, the first ff run fetches the monster binary from the public NOSYS network (repository forkjoin-ai/ff-engine) and caches it at .bin/monster — no workspace, no Rust, no setup step:

ff run ./hello.ts -- --export app                     # -> hello from typescript
ff run ./hello.rs -- --export main --input-json 21    # -> 42

Provider arguments follow a bare --, the same contract as ff <tool> [-- args]. A .ts/.rs/.js/.gg path passed to ff run is shorthand for running that file with monster. Use ff doctor to see what is materialized, and FFRACTAL_NOSYS_ORIGIN to point at a different network.

How it decides

Every request takes the same fork / race / fold path:

intent + context (cwd, argv, profile, caps)
  → canonicalize         what is actually being asked
  → resolve occupancy    is an admitted occupant already here?
        hit  → replay                        (0 residual provider calls)
  → miss
  → fork                 every provider that could satisfy it
  → race                 admission + cost (local build | summon | remote | agent)
  → fold                 the minimum admissible provider
  → admit                caps + lease + party identity
  → materialize          restore-and-verify, or residual fill
  → execute once
  → publish the occupant → the next identical intent is a hit

Two rules fall out of that, and they are the whole surface:

1. The admitted path never fills. A hit performs zero residual calls.
2. The residual path never pretends. A miss is a value with a reason; it is never converted into a success by a fallback.

Verdicts and exit codes

ffractal keeps three different questions in three different labels. They are never collapsed:

| Layer | Values | Meaning | |---|---|---| | Dispatch | RESOLVED · MISS · MALFORMED | Did we find a provider? | | Occupancy | GREEN · RED · CORRUPT | Are the bytes here and trustworthy? |

| Exit code | Meaning | |---:|---| | 0 | Resolved / ran successfully | | 3 | MISS — nothing admissible satisfied the intent (a reason, never a stack trace) | | 4 | MALFORMED — input did not parse | | 5 | CORRUPT — evidence exists but its bytes no longer match, so execution is refused |

Corrupt ≠ RED. A corrupted occupant is refused, never silently rebuilt as if it were merely absent.

Commands

| Command | What it does | Executes? | |---|---|---| | ff list | List every indexed provider | no | | ff show <id> | One provider: caps, origin, install state | no | | ff resolve <intent...> | RESOLVED / MISS / MALFORMED + reason | no | | ff plan <intent...> | Ordered candidate providers (cost rank) | no | | ff identity <id> | NOSYS-shaped work identity for a provider | no | | ff occupancy <id> | GREEN / RED / CORRUPT for local bytes | no | | ff doctor | Broken shims, missing registries, stale admissions | no | | ff components status | What is filled vs residual | no | | ff components plan <id> | The residual fill plan for one provider | no | | ff run <intent...> | Resolve, materialize on MISS, then dispatch | yes | | ff exec <id> [-- args] | Re-entrant dispatch with caps applied | yes | | ff admit <id> | Fill the local occupant for a materialized provider | writes | | ff restore <id> | Fetch bytes from the network, hash-verify, then admit | writes | | ff explain <phrase> | Canonical command for a natural-language phrase | no | | ff anything | An unrecognized first token is resolved as an intent | maybe |

Everything except exec, run, admit, and restore is read-only.

Standalone vs. workspace

ffractal finds its workspace root by walking up for the nearest .moonshine, .moonbeam, .a0, nx.json, pnpm-workspace.yaml, or .git. If it finds none, it uses the current directory and reports an honest empty index. That is why npx @a0n/ff works on a laptop with nothing installed:

• Standalone (default for npx): the resolver index, the read-only verbs, and the intent table all work. Provider rows simply are not there yet.
• Workspace: inside a repo that carries .moonshine / .moonbeam registries, the same verbs see the full provider set, and exec / run / restore can materialize and dispatch.

Use --dir <path> to point at a specific workspace.

The stack underneath, layer by layer (ELI5)

ffractal is the dispatch seam across a much larger stack. Each layer gets a plain-language doc in docs/:

| # | Layer | ELI5 doc | |---|---|---| | 1 | Languages — what a person writes | docs/01-languages.md | | 2 | Formats & containers — how bytes are shaped | docs/02-formats.md | | 3 | Addressing & identity — what a name points at | docs/03-addressing.md | | 4 | Transport & networking — how bytes move | docs/04-transport.md | | 5 | Runtimes & substrates — where work runs | docs/05-runtimes.md | | 6 | Executables & toolchain — what you invoke | docs/06-executables-and-toolchain.md | | 7 | Trust model — why refusal is a feature | docs/07-trust-model.md |

Deeper sources (in the monorepo): the ffractal north star and the sovereign stack overview.

Programmatic use

The published bundle is self-contained and exports the resolver:

import { parseFfractalArgv, main } from '@a0n/ff';

// Run the CLI in-process:
const code = await main(['resolve', 'rip']);

// Or use the resolver directly:
import { buildFfractalProviderIndex, resolveFfractalIntent } from '@a0n/ff';

Develop / build

# from the monorepo root
a0 run @a0n/ff:build          # bundles src/ -> dist/ (self-contained)
a0 run @a0n/ff:typecheck
a0 run @a0n/ff:pack:verify    # npm pack --dry-run, no publish

The published tarball contains only bin/, dist/, README.md, and LICENSE — a bundled CLI with no runtime dependencies.

Honesty boundary

• ffractal may decline. It may run residual work. It may never dispatch a wrong provider and call it success.
• Different states never share a label: a tape is not a ticket, and CORRUPT is not MISS.
• This package is the public onramp. The resolver it bundles is the same code the monorepo CLI runs; where a mechanism exists but a production receipt is still owed, the north star says so.

License

MPL-2.0. See LICENSE.