Hiro development journal

Selecting domains for Hiro's first internet-observation probation

2026.08.06 at 00:00:31 America/Los_Angeles Validated and published Machine-readable JSON

Executive summary

Recommended a three-host initial allowlist for Hiro's first controlled internet-observation probation: www.iana.org, docs.python.org, and pypi.org.

The proposed set deliberately spans stable control HTML, authoritative technical documentation, and changing software metadata while remaining public, unauthenticated, query-free, and compatible with the implemented HTML and JSON sanitization lane.

Recommended exact path restrictions in addition to exact-host restrictions, beginning with one IANA control page, the Python 3 documentation tree, and a short named list of PyPI Simple Index project pages.

Recommended deferring api.github.com and api.weather.gov to a second phase because they introduce additional rate-limit, untrusted-content, media-type, and application-identification requirements. No Hiro observation request was made and the observation policy remains disabled.

Work completed

Phase 1 exact hosts

Recommended

Use www.iana.org only for the exact path /domains/reserved as a stable control page with predictable authoritative HTML.
Use docs.python.org only beneath /3/ for official Python language, library, and version documentation relevant to Hiro's Python implementation and candidate reasoning.
Use pypi.org only for a small approved set of query-free Simple Index pages such as /simple/httpx/, /simple/pydantic/, and /simple/pytest/, providing bounded changing dependency metadata without downloading distributions.
Limit the first session to one request per host, three total requests, no redirects beyond the existing strict budget, and the current one-megabyte cumulative download ceiling.

Phase 2 candidates

Deferred

api.github.com is valuable for public release metadata and can be accessed without authentication for public resources, but unauthenticated requests are limited to 60 per hour and release text is user-controlled evidence.
api.weather.gov provides free public forecast and alert data, but it requires an identifying User-Agent and commonly returns GeoJSON or JSON-LD media types not yet present in probation version 1's content allowlist.
Both hosts should be added only after Phase 1 proves redirect handling, snapshot completeness, sanitization, review workflow, and stop controls under real network conditions.
General search engines, social networks, news aggregators, arbitrary user-content hosts, login surfaces, large JavaScript applications, and undocumented sports APIs should remain excluded from the first probation.

Decisions and reasoning

Start with three exact hosts rather than a broad topical allowlist.
Add path-level restrictions before launch so host approval does not authorize every endpoint on that host.
Use IANA as a control source, Python documentation as authoritative technical evidence, and PyPI Simple Index pages as bounded changing metadata.
Do not download package files or follow PyPI file-host links during observation.
Defer GitHub API observation until rate-limit headers and user-generated release content have explicit handling.
Defer NWS API observation until the client has an approved identifying User-Agent and explicit GeoJSON/JSON-LD support.
Keep policy enabled false, the allowlist empty, the observation DISABLED sentinel present, and Stage 6 disabled until a separate launch action.

Validation and evidence

Check	Status	Result
Official source review	passed	Reviewed official IANA reserved-domain information, current Python documentation, PyPI JSON and Index API documentation and policies, GitHub REST unauthenticated rate limits, and National Weather Service API authentication and format guidance.
Compatibility with probation version 1	passed	The recommended Phase 1 endpoints are public, query-free, GET-compatible HTML pages and require no login or credential. PyPI scope excludes distribution downloads.
Hiro journal generation and frontend build	passed	The timestamped-entry test and production frontend build completed successfully before publication.

Current state

The preferred Phase 1 domain set is defined but not configured.
The current policy still has enabled false and an empty approved-domain list.
The internet-observation DISABLED sentinel and Stage 6 DISABLED sentinel remain present.
No Hiro observation snapshot has been created.

Next steps

Confirm the three recommended Phase 1 hosts and path scopes.
Implement and adversarially test exact path-prefix enforcement.
Configure one request per host and three total requests for the first shadow session.
Make a separate launch decision that enables only the observation lane while retaining Stage 6 DISABLED and zero promotion authority.
Review all three frozen snapshots before considering GitHub or National Weather Service sources.