How HeadlessProfile data is wired together.

This page is the public source-of-truth map for the directory. It explains what hns.bio is, how our headlessprofile fork extends it, where the directory's data actually comes from, and which fields look like DNS TXT records but are not.

/01Two things named "hns.bio"

It helps to keep these separate, because conflating them leads to wrong conclusions.

Whenever this page says hns.bio, it means the standard / website. Whenever it says hns_bio, it means the column.

/02The 3-bucket TXT prefix map

Every prefix the directory parses falls into one of three buckets. The first two are real DNS TXT records. The third is not.

Bucket A — Inherited from the hns.bio standard

Same prefix, same meaning, same parser as upstream H4ckB4s3/hns-bio. We did not change them.

Layout / branding

Communication

Web

Social & media

Wallets (56 addresses)

Bucket B — Added by the headlessprofile fork

The fork's fetch.js parses all of the prefixes below, but they fall into three sub-categories based on whether anything actually writes them to DNS. Several are also drafted in a proposal back to upstream hns.bio.

B1 — Published by sync_bio_to_dns (in known_keys)

B2 — Published by a separate writer

B3 — Parser-only (no writer publishes them)

The fork also fixes a parser bug: fetch.js now accepts both key:value and key=value (line 515), since some DNS panels rewrite : to =.

Bucket C — API-only / synthesized (NOT in DNS)

mpp_enabled and tempo_address are the strangest of the five — the fork's fetch.js has parser cases for them, so it could read real TXT records if any existed. But sync_bio_to_dns:known_keys does not include them, so nothing in headlessdomains-com ever publishes them. Practically API-only.

/03End-to-end data flow

Five hns_bio writers, four DNS-write paths, one cache fan-in. The "legitimate" path is JSON → DNS → DoH, but it is not the only path that touches DNS. Three additional writers (inject_manifest_dns_records, routes/arp.py, bmos_sync) bypass sync_bio_to_dns and write TXT records directly to SkyInclude. The shortcut read path is the lookup API, which the directory also reads and stuffs into the same raw_txt list as the real DNS records. That is where the duplication starts.

/04Field provenance — what shows on the directory came from where

Reading it. A DUP row means the same value enters raw_txt twice — once synthesized from the API, once from real DNS. A FAKE row means the value is only a synthesized string; the real data lives in a database column and never touched DNS.

/05Known duplicates & drift

Duplicate №1 — Same data, three copies

hns_bio JSON in HD → DNS TXT via SkyInclude → directory Profile row + raw_txt. Every profile field exists in three places. There is no reconciliation. Last writer wins, and SkyInclude failures are silent.

Duplicate №2 — API + DoH, merged with weak dedupe

directory/utils.py:fetch_txt_records calls the lookup API and two DoH resolvers, then merges. Dedupe is by exact string match (if rec not in txts). So name:Alice and "name:Alice" (DoH quoting) slip through. : vs = separator slips through.

Duplicate №3 — Five fields pretending to be TXT

mpp_enabled, tempo_address, flag_status, for_sale_usd, for_sale_gems were never published to DNS. The directory synthesizes TXT-shaped strings for them and stores them next to real DNS records. Anyone reading raw_txt cannot tell which is which.

Bonus — Multiple writers for agent-manifest:, skill-md:, arp:

Three TXT keys are written by more than one path:

• agent-manifest: and skill-md: are published by both sync_bio_to_dns (when syncing from hns_bio) and inject_manifest_dns_records in utils/skyinclude.py:307. Either path can land first; the other will see the record on its next read and either no-op or rewrite.
• arp: is published by both sync_bio_to_dns (apex, when _arp.state == 'arp_bound') and routes/arp.py directly (apex + _principal subdomain). routes/arp.py deletes-then-adds, so it dedupes itself, but races with sync_bio_to_dns are still possible.

The directory's API path also reconstructs bmos:<feed_url> from commerce_catalog in the lookup response, so the same feed URL can land in raw_txt twice — once from the API as a fake-TXT and once from real DoH. Note this is a directory-side duplicate, not a DNS-side one — there is only one DNS writer for bmos:.

Bonus — Dead IPFS code path

The directory looks for data.domain.ipfs and data.profile.ipfs on every fetch. Neither key is ever returned by the lookup endpoint or written into hns_bio. IPFS only flows from real TXT records via DoH. The branch runs forever and does nothing.

/06What it would take to fix

1. Stop the directory from impersonating DNS. Drop the lookup API path from fetch_txt_records, or keep it but route its data into clearly named columns — never inject synthesized key:value strings into raw_txt again.
2. Decide what is DNS-resident vs DB-only. Either publish mpp_enabled, tempo_address, flag_status, and for_sale_* to TXT records, or label them as off-DNS metadata fetched through a clearly-named API.
3. One writer for hns_bio. Funnel PowerLobster, BMOS, the dashboard form, and the API through one path that always re-syncs DNS atomically.
4. Clean up the directory's existing data. Either re-index every profile from DoH only, or run a one-shot script to strip the fake strings from raw_txt.
5. Consolidate the multi-writer keys. Three TXT keys (agent-manifest:, skill-md:, arp:) are written by more than one path. Either route them all through sync_bio_to_dns or all through their dedicated writers — not both. Stop the races.
6. Submit the prepared upstream PR to H4ckB4s3/hns-bio so name, bio, category, agent-manifest, skill-md, agent-capabilities, and the = separator fix become part of the universal hns.bio standard.

/07File references

Upstream — H4ckB4s3/hns-bio

• README.md — canonical prefix list (Layout, Communication, Web, Social, Media, Wallet, TXT Chaining)
• fetch.js (~337 lines) — original parser

Fork — shadstoneofficial/headlessprofile

• README.md — extended prefix list (adds name, category, bio, custom, plus the AI-Agent extensions)
• fetch.js — extended parser (~1200 lines) with :/= separator handling
• temp-specs/hns-bio-proposal.md — prepared PR back to upstream

Directory — headlessprofile-directory

• app.py — routes and parse_and_save_profile
• utils.py — fetch_txt_records: API + DoH + DoH merge logic; synthesis of fake-TXT strings (Bucket C); parse_txt_record separator handling
• models.py — Profile model with raw_txt JSON column

HeadlessDomains — headlessdomains-com

• models.py — Domain model with hns_bio JSON column, for_sale_price_*, flag_status
• routes/lookup.py — /api/v1/lookup/<domain>, returns hns_bio as profile
• routes/dashboard.py — sync_bio_to_dns, the known_keys allow-list, dashboard update_bio handler
• routes/api_v1.py — update_domain_bio, bmos_sync, for-sale and sold endpoints
• routes/manifests.py — /manifests/<name>.json
• utils/webhooks.py — notify_directory_index (HD → directory webhook)
• utils/skyinclude.py — DNS provider client