The agentic network · a Gord Holdings companyRoadmap
← All packages
The record · v0.2.0 · Apache-2.0

@flashyos/directory

One record per real thing, merged across an estate

The estate directory — one record per real thing, emitted as fragments by each repository and merged into a single world model every property renders a view over.

npm install @flashyos/directorynpm ↗source ↗

Why it exists

Each repository emits a fragment describing the things it actually knows about. This merges them into a single world model that every property renders a view over — so an organisation, a person or a product has one record, not nine pages that quietly disagree.

What it refuses to do
The merge reports contradictions rather than picking a winner. Two doors that disagree are a finding, not something to average.

How it works

Every repository emits a fragment — the nodes and edges it is the authority for — and the fragments merge into one graph every property renders a view over. Nothing is copied between repositories, so nothing can drift. Ids are `prefix/slug`, permanent, and never reissued, across thirteen node kinds and fourteen edge types.

The merge is where estate-wide rules are enforced: it reports contradictions rather than picking a winner, so two doors that disagree are a finding, not something to average. `declareEmitters` records which machine an org operates to sign its edges, so provenance is a citation to something declared rather than to nothing.

Authority is federated because a repository knows what it owns and nothing else reliably does — a central seed script works on one laptop and fails on every runner.

Related concepts
IntentMeshagentic autonomous organizationmachine-readable organizational trustAI agent trust register

Use it

Merge an estate and see what disagrees
npx @flashyos/directory merge flashyos.com gda.group flashy.gold

Installing it puts this command on your path — read from the package’s own manifest, so this list cannot drift from what you actually get.

flashyos-directory

In practice

Give an entity one record
An organisation described across nine properties emits a single fragment for itself; the merge renders one record every property views, so nine pages can no longer quietly disagree about what the org is.
Find where an estate contradicts itself
`npx @flashyos/directory merge` across several domains surfaces contested authority and dangling references as findings, rather than hiding them by choosing a winner.

How it stays honest

The estate-wide merge catches contested authority and dangling references, but it runs elsewhere and cannot say which repository caused them — so the Directory workflow validates each repository’s fragment at the point it is made, failing a bad fragment where it is written. The estate graph is separately assembled over the network from published URLs, not from local checkouts, so it proves the estate publishes what it claims. Verify a fragment yourself with `npx @flashyos/directory` against your own file.

.github/workflows/directory.yml ↗the workflow that keeps this current — read it, it hides nothing

Questions

What is a federated directory fragment?
A fragment is the set of nodes and edges a single repository is the authority for. Fragments merge into one graph and nothing is copied between them, so a record cannot drift out of sync across properties.
How does the directory merge handle conflicts?
It reports contradictions rather than picking a winner. Two properties that disagree about the same fact surface as a finding, because averaging or silently choosing would hide exactly the disagreement worth seeing.
What is an emitter id and why declare it?
An emitter id names the machine an organisation operates to sign its edges. Declaring it with declareEmitters makes provenance a citation to something the fragment defines, rather than a signature by an identity nothing declares.
Are directory ids ever reused?
No. An id is prefix/slug, permanent, and never reissued — not even after a property is retired and its domain lapses — so a reference always points at the same real thing.

The licence

Apache-2.0, read from the package’s own manifest. Embed it in anything, including closed software — that is what makes a spec adoptable and a verifier worth running. FlashyOS’s server side is AGPL-3.0-only instead, and a test in the monorepo asserts the direction between them: AGPL code may consume this, this may never consume AGPL code.

Keep reading

The network directory
Also in the record
@flashyos/canon@flashyos/backlog@flashyos/shiplog@flashyos/checkpoint@flashyos/assetmesh@flashyos/delivery@flashyos/playbook@flashyos/mesh@flashyos/holding@flashyos/mail@flashyos/frontdoor