loop-apidoc Technical Tour — For New Engineering Teammates

The non-negotiable core invariant

Supplier sources are the sole authority for what the provider documents.

Anything a source does not state is left as null and recorded in missing — never inferred, never filled in with REST/OAuth conventions.

When validation hits something missing, it fails loudly rather than using guesses to make the docs "look complete." Every design decision in this project exists to hold this line.

Nor does a supplementary source weaken it. A hand-written excerpt of supplier correspondence may fill missing, but it is not a formal document: the formal document wins any disagreement, the excerpt never reaches explicit_support, and every claim resting only on it is named individually (ADR 0010).

Passive Implementation Observations do not weaken this rule. They report empirical behavior only inside an exact Applicability Envelope and use a separate confirms / contradicts / inconclusive / out_of_scope axis; none of those outcomes becomes supplier-source support.

The converse also has to be evidenced: "the source does not state it" is a claim that must be earned. source_facts/ mechanically scans Markdown sources for parameter tables and example blocks, and blocks the run when a source plainly documents them but the extraction came back empty; placeholder answers such as "requires further extraction" are blocked the same way. To claim a field genuinely is not in the source, name it in missing — so this gate only ever forces a named gap, never a fabrication.

Be clear about its limits, though: the scan only recognises well-structured Markdown (headings, GFM tables, fenced blocks). If a source is flattened into long single lines it yields zero facts and the gate does nothing. A clean gate exit does not mean the extraction is complete — it catches omissions that can be mechanically proven; everything else still needs human review.

Better to flag "missing" than to fabricate content

Loop Engineering

Four closed loops: source, quality, version, handoff

loop-apidoc's engineering focus is to make source, quality, version, and handoff all machine-reproducible, human-verifiable, and pickup-ready for downstream users — not just to produce a document.

Source-grounded loop

sources → extraction → provenance

Every output must trace back to a source citation; information a source doesn't state is left as missing, not filled in by convention.

Quality loop

preparation · validate · score

preparation flags governance items that need attention before generation, validation blocks errors, and score turns the finished product into a comparable quality signal.

Version loop

run-dir → diff/report

Two runs can be classified into breaking/additive/changed/source_only, giving version updates a downstream-impact reading.

Handoff loop

integration-contract · examples · handoff/

OpenAPI and the always-written integration contract are the machine contracts; the latter preserves typed transport, amount-direction, idempotency, line-currency, and cross-endpoint operational rules, while the derived Postman collection, SDK hints, task list, and examples help the next engineer pick it up.

A fifth loop · Separate authority

Feedback can improve an exact-scope operational view without rewriting provider documentation

The feedback command group assesses passive normalized observations, proposes and persists review cases, requires independent human approval for expiring amendments, and resolves an exact-scope Effective Contract. Assessment and preview perform no network I/O and write outside .foundry; only explicit submit/review/approve steps mutate governed state.

Normative Contract

supplier-source authority

The immutable approved account of what the provider documents. Global Foundry current always points to this axis.

Implementation Observation

empirical · exact envelope

Sanitized, digest-bound behavior evidence with producer, runner, replay, attempts, time, environment, region, identity, and configuration scope.

Compatibility Amendment

reviewed · expiring · scoped

A reproducible safe difference may be proposed, but an independent human approves it. Its proposal binds the complete Normative release digest: contract, documentary fragments, and support relationships.

Effective Contract

deterministic composition

One normative release plus applicable active amendments for one exact target. Composition rechecks the full release digest; each value retains normative or observed-override authority and lineage.

Provider Erratum: a formal provider correction is supplemental supplier source material, so it re-enters source-risk → source-quality → extraction → verification → assembly → review → Foundry approval. It is not a Compatibility Amendment shortcut.

Bounded assurance: “fully verified” means for this exact Applicability Envelope, as of this time, with this suite version and declared material-claim coverage. No finite suite proves universal or permanent 100% truth.

Key architecture

Two stages: agent extraction ‖ deterministic CLI back half

This is the mental model you most need to build first. The whole pipeline is split in two, with two JSON files as the only boundary in between; each side can be tested and swapped independently.

Two-stage architecture — The uncertainty is concentrated in the extraction front half; the deterministic back half only reads the seam JSON and produces re-runnable artifacts.

Front half · Uncertainty

agent extraction (Claude Code / Codex)

Pre-agent risk gate: after preprocessing and manifest creation, inspect-source-risk must pass before any agent reads source content.
Read-only subagent fan-out: the main agent dispatches multiple subagents, each of which only reads files / searches / fetches URLs and returns structured JSON, never writing files.
The main agent consolidates the returned JSON and writes it into the seam files.
Extraction is staged per SKILL.md (see the ten stages below), ensuring only what the sources actually state gets recorded.

The only seam inventory.json endpoints/*.json

Back half · Deterministic pure functions

assemble (deterministic CLI)

Does not extract; it only assembles the JSON the agent wrote.
Runs manifest → plan → preparation → generate → validate in order.
Reports ok / run_dir / report via --json, letting the agent drive corrections itself.

Why split it this way? Extraction — which requires semantic understanding and is inherently uncertain — is handed to the agent, while assembly, generation, and validation — which must be reproducible — are handed to deterministic code. There used to be a run-agent mode that extracted via the claude -p subprocess, and a NotebookLM backend; both were retired in 2026-06, and now agent-native is the only extraction path.

Core shadow seam. Opt in with assemble --architecture-mode shadow. After the legacy report is written, shadow/ maps the in-memory manifest and plan into Core evidence and claims, runs through Core validation only, and writes observational artifacts under <run-dir>/core/. It never approves, publishes, updates Foundry, or changes the legacy status or exit code. Use assemble --architecture-mode strict for the separate blocking candidate path: every legacy-supported material claim must re-verify against exact evidence before an unapproved Core release is written. Foundry independently validates the strict record before approval. Optional v1 evidence[] references re-materialize before a run exists and verify source identity, locator, digest, and claim path. Claim paths are bound to exact fragments by explicit_support, derived_support, contradicts, or insufficient. Prose without a parsed scalar can support only its one exact bound claim; OpenAPI structural derivations are versioned, allowlisted, and recomputed with every required context fragment. A whole-document legacy citation cannot become supported; inspect relationships.json and projections/provenance.json.

End-to-end data flow

What stages a full run passes through

Every stage has explicit inputs / outputs (artifacts). Raw PDF/Word must be converted into scannable text, and the manifest-bound source-risk gate must pass before agent extraction starts. The ones marked in grey are optional; preparation, score, diff, review, and handoff extend a run from mere "generation" into a reviewable, comparable, handoff-ready engineering asset.

End-to-end data flow — The main pipeline produces the run-dir; score, diff, and review extend the finished product into quality, version, and human-decision signals.

0preprocess / normalize Convert raw PDF/Word into supported text before inspection; built-in preprocess handles PDF/DOCX → Markdown and validates DOCX with a bounded fail-closed OOXML gate. scannable source directory

1manifest Inventory the exact text sources that the agent will later read. manifest.json

2inspect-source-risk Scan manifest-bound text in both directions — can it manipulate the agent, can it leak material to the agent — without rewriting it or echoing payloads; blocker or unscannable input rejects before agent access. source-risk-report.{json,zh-TW.md}

3assess-sources Verify the required risk-report binding, embed its audit, and assess traceable source-quality observations. source-quality-report · source-diff

4extraction Only now does the agent's read-only fan-out read the sources; the main agent writes out the seam JSON. inventory.json · endpoints/*.json

5plan Normalize the extraction results into a plan and perform source-match classification. plan/normalization-plan.json

6preparation Assess the readiness of the manifest, inventory, endpoint JSON, and plan before generation. preparation-report.{json,md}

7generate Generate OpenAPI, the Chinese guide, the manual review page, provenance, and handoff helper artifacts. openapi.yaml · api-guide.zh-TW.md · review.html · provenance.json · handoff/

8validate Run the four check categories — structure / completeness / consistency / no-speculation — and produce a report. validation/report.{json,md}

9score Grade the documentation quality of a completed run-dir, without changing validate's pass/fail semantics. optional → score/score.{json,md}

10diff Compare two completed run-dirs, classifying differences by downstream impact. optional → diff/report.{json,md}

11review Compare a candidate with current/baseline locally, save human conclusions, and explicitly approve when ready. optional → .foundry/api/.../review/decision.json

CLI interface

CLI commands, each with its own job

The CLI entry point is Typer (cli.py). Note: extraction is not in the CLI — that's the agent's job; the CLI handles the back half and tooling steps (source processing, URL evidence, source quality, run handling, asset governance, and local human review).

preprocess

PDF/DOCX → markdown; DOCX also gets deterministic source-hash provenance and unsafe OOXML is rejected before output.

manifest

Scan local sources + URLs and build manifest.json.

snapshot-openapi-url

Pin a single Swagger/OpenAPI JSON/YAML URL as an immutable local source and build a direct coverage ledger.

catalog-url

Download the entry page just once to build a sidebar navigation index (coverage universe); never auto-fetches child pages.

select-url

Select catalog nodes by explicit scope (branch/keyword) as reading starting points; downloads no URLs.

cache-url-pages

Cache all catalog pages and build local body/link/entity indexes (corpus.json); no model involved.

cache-url-entry

Directly cache a single entry page, for an empty catalog or a single-page document.

normalize-html-snapshot

Normalize a static HTML snapshot into supported Markdown, keeping a URL/SHA-256 provenance sidecar.

import-rendered-url

Import protected browser-rendered HTML/Markdown as immutable local evidence plus versioned provenance and fetched_rendered coverage. A verified match lets manifest/assemble skip that origin probe; mismatches fail closed.

import-supplementary-note

Import a hand-written excerpt of supplier correspondence as a supplementary source, with a provenance sidecar bound to its content (origin, receipt time, excerpter, SHA-256). It may fill missing but never supports explicit_support, and it stays out of the freshness fingerprint — the dividing line is re-obtainability. The excerpt is written by a person, so the sidecar buys accountability, not verifiability (ADR 0010).

related-url-pages

Output candidate page cards from body links and shared entities; the model reads candidate page bodies only when needed.

inspect-source-risk

Required before any agent reads sources. Scans manifest-bound Markdown, HTML, and OpenAPI JSON/YAML without rewriting sources or echoing matched payloads; raw PDF/Word are unscannable and must be converted first.

Exit codes: 0 pass · 1 reject · 2 invalid, stale, unsafe, or unreadable input.

assess-sources

Pre-extraction source quality gate: requires --source-risk, verifies its source/manifest binding, embeds the audit, and assesses traceable observations. A reject may return explicit, de-duplicated required_source_refs as a bounded next-capture list without crawling.

verify-extraction

Check whether the agent-produced extraction JSON conforms to the assemble input contract; writes nothing, creates no run-dir. Optional v1 evidence[] references re-materialize, verify their digest, and resolve their claim path. The contract includes the source-fact inventory: when a source section plainly lists a parameter table or example blocks and the extraction left them empty, that is a silent omission rather than "the source does not say" — to claim the latter, name the field in missing.

assemble

Assemble the JSON the agent wrote → plan → preparation → generate → validate, reporting via --json; optional --score and --url-coverage, with required --source-quality. Assemble rebuilds the manifest and revalidates the embedded source-risk binding before creating a run-dir, refusing unaudited runs without claiming to prove off-process source-read chronology.

Exit codes: 0 validation PASS · 1 validation FAIL · 2 extraction input file error (leaves no orphan directory).

validate

Re-run validation on an existing run-dir and produce a report (without regenerating).

score

Read an existing run-dir's OpenAPI, provenance, manifest, and validation report, and produce a quality score.

Exit codes: 0 pass · 1 needs_attention / fail · 2 run-dir input error.

evaluate

Compare two runtime replay JSON files for one case version and write immutable quality, cost, and latency deltas; it never assembles, imports, or approves a contract.

feedback

The implementation-conformance group: assess (0 closed, 1 reviewable/open, 2 error), propose (0 proposal, 1 none, 2 error), submit (immutable candidate case stage), review (one write-once non-approval decision and corrective route, with or without a proposal), approve (separate immutable approved Effective release; independent human, required expiry, exact-scope publication), compose (non-publishing preview), current (exact-target Effective lookup requiring timezone-aware --at), and provider-erratum (non-mutating handoff into the full normative source pipeline). Current lookup rejects not-yet-effective or expired assets, a non-current normative base, and stale pointer/artifact digests, while exposing validity, open/untested, stale-amendment, and unresolved-contradiction counters. Same-target conflicts fail closed unless explicit same-scope supersession is recorded. Global Foundry current remains normative.

governance-scan

Turn a freshness-watchlist batch result into a bounded human-work trigger: changed sources become review_required, while unreadable or inconclusive sources become attention_required. Optional --snapshot-dir retains only the same-scan changed raw bytes as an immutable, content-addressed evidence pack; it never re-extracts, generates, imports to Foundry, or approves a contract.

diff

Compare the version differences between two completed run-dirs.

Exit codes: 0 done · 2 input run-dir has a missing file or bad format (DiffInputError).

foundry

The project-local asset governance sub-group (init / import / approve / list / current): import a completed run as a candidate, approve it into a versioned asset, and maintain the current pointer.

review

A 127.0.0.1 workbench that auto-imports a candidate, compares current/baseline, and saves review/decision.json handoff. Only an explicit human approval updates current; it never calls a model or replaces validation.

Extraction stages

Extraction is split into ten stages

Why stage it? To avoid a single answer carrying all the content and losing fidelity. The agent extracts step by step across these ten stages, converging into inventory.json and per-endpoint endpoints/*.json.

01Source inventory

02API system overview and terminology

03Environments / base URL / version

04Authentication / authorization / signing

05Endpoint list

06Per-endpoint detail (method / path / parameters / req / resp / examples)

07Shared schemas / enums / data constraints

08Error codes and failure behavior

09operational limits, cross-endpoint business rules, field semantics, and formulas

10Source conflicts, gaps, and items that cannot be confirmed

Artifacts

One run delivers the contract, the evidence, and the handoff assets

The core artifacts provide the API contract and source grounding; the derived artifacts provide quality reading, version comparison, and downstream engineering handoff.

Standard spec

openapi.yaml

OpenAPI 3.1, ready for toolchains and engineers to consume directly without each interpreting the sources themselves.

Traditional Chinese integration guide

api-guide.zh-TW.md

A human-readable Traditional Chinese guide, so you don't have to slog through the original.

Source provenance

provenance.json

Every output states which source and which section it came from, so each can be cross-checked one by one.

Validation report

validation/report

Lists gaps and conflicts, including supported sources with zero citations and successful responses with no usable schema fields.

Quality score

score/score.{json,md}

Turns five quality categories into comparable scores and reports response fields, operations, and hollow operations.

Handoff pack

handoff/ · examples/

A task list, Postman collection, SDK hints, and request examples to help the integrating engineer take over.

Manual review page

review.html

A single-file HTML you can open offline, gathering scope, sources, API structure, and a specification-governance list onto one page for a quick human check. Gaps, source conflicts, and unverified facts remain trackable items; a document that omits a server URL, authentication details, or sandbox credentials does not by itself establish an integration risk.

Provenance ↔ validation alignment

No speculation, enforced by aligning targets one by one

This is the key mechanism by which "never guess" is machine-enforced: the target strings in provenance.json align one-to-one with OpenAPI locations.

one-to-one target alignment — The provenance target strings align one-to-one with OpenAPI locations, serving as the reference for the no-speculation check.

The no-speculation check cross-references exactly these targets: anything entering the output must trace back to a source-grounded plan item, or it counts as a violation. The aligned locations include paths.{path}.{method}, components.schemas.{name}, and components.securitySchemes.{name}.

Correction loop

Validation issues get classified, not blindly retried

There is no CLI built-in correction loop. assemble reports the classification result, and correction is driven by the agent itself: go back and re-read the sources, overwrite the corresponding JSON, and run again, for up to 3 rounds. Issues fall into two categories:

Fixable (FIXABLE)

OPENAPI_INVALID · OUTPUT_MISMATCH

The artifact itself is wrong → the agent corrects the JSON and regenerates.

REQUIRED_INFO_MISSING

Required information is missing → the agent goes back to re-read the affected source and fills in that piece.

Not fixable (fail-closed)

SOURCE_UNVERIFIED · SOURCE_CONFLICT · UNSUPPORTED_ASSERTION

The source can't be confirmed / sources conflict / an unsupported assertion → do not fill it in; report it faithfully as a gap or conflict. This is exactly where the core invariant is enforced.

Regression evidence architecture

The benchmark has four layers; SKIP is not PASS

New engineers can easily conflate "the fixture is committed," "the test discovered the case," and "the source-backed assertions ran." The harness deliberately separates four layers; see docs/BENCHMARK_VALIDATION_PLAN.md for the full contract and case-addition workflow.

1 · Committed inventory

fixture identity

A case contains both extraction/inventory.json and expected/validation.expect.json; there are currently 13 unique cases.

2 · Discovery guard

CI-safe

Even without local source snapshots, CI confirms that every fixture is discoverable and exactly matches the required inventory.

3 · Source-backed execution

original sources required

Assemble and artifact assertions run only when the original, dated sources/ snapshot exists; a missing source produces SKIP.

4 · Strict-local preflight

all sources · zero skips

Every required case must have non-empty sources, every source-backed check must execute, and the run must report zero skips.

Why are original sources excluded from Git? Some upstream documents have copyright, access, or redistribution restrictions, so benchmarks/<case>/sources/ contains operator-provided, gitignored snapshots. CI can prove committed inventory, discovery, and deterministic parity, but it cannot call a missing-source SKIP a pass. Never replace an unavailable historical snapshot with newer documentation, synthetic data, or an error page.

Supplemental sanitized-fixture lane: scripts/quality_gate.py --sanitized-fixtures replays reviewed, line-preserving exact-evidence fragments in CI. The current pilot is rsg-game-transfer-wallet. This lane sits outside the four layers and proves fixture-backed parity only for retained claims; it neither replaces original sources/ nor qualifies as source-backed or strict-local PASS.

Implementation-backed conformance lane: runtime observations are reported separately with their Applicability Envelope, time, suite version, and open discrepancies. They never count as documentary grounding or a source-backed strict-local PASS.

Version diff

On version change, classify by downstream impact into four buckets

diff compares the old and new completed run-dirs of the same API, looking at "will this revision break downstream integrations" rather than "which words in the source changed." Each difference is assigned to one of the four impacts below and sorted by severity from high to low, so you can see at a glance whether to block it and whom to notify.

Breaking breaking

Could break existing integrations outright; highest risk.

For example: removing an endpoint (operation removed), making an existing field/parameter required (became required), adding a required parameter, dropping a response or security scheme, or a schema structure change.

→ Block before release; proactively notify all integrators to adjust.

Additive additive

Purely adds things, usually backward-compatible.

For example: adding an endpoint (operation added), adding an optional parameter/field, adding a response or media type, or adding a schema / security scheme.

→ Safe to adopt; downstream decides for itself whether to use the new features.

Changed changed

Existing content changed, but not necessarily breaking compatibility.

For example: a parameter/field's description text changed (description changed), a servers address updated, info version metadata updated, or an unreferenced schema in components removed.

→ Read what changed and confirm there's no hidden impact on your side.

Source only source_only

The source or metadata moved, but the final API contract didn't change.

For example: the source file itself changed (manifest source changed), provenance tracing adjusted, or validation / preparation report contents changed, but the OpenAPI spec itself is unaffected.

→ Rest easy, the spec is unchanged; if you care, go back and see why the source moved.

Comparison scope: OpenAPI paths · methods · parameters · schemas · security · webhooks, integration-contract, provenance, the validation summary, and manifest (the first version does not compare the Markdown guide or examples). Output is written to diff/report.{json,md}; exit code 0 done, 2 means the input run-dir has a missing file or bad format (DiffInputError).

Package boundaries

How the code is split into packages

Principle: apart from a few I/O exits, all other modules are pure functions, which makes them easy to unit-test. When making changes, hold this boundary so every loop can be verified independently.

Package	Responsibility
`manifest/`	Scan local sources + build manifest.json; each source's `authority` (normative by default, or supplementary) is declared by its same-named `.source.json` sidecar, and the read side fails closed
`rendered_url.py`	Offline rendered-source import plus read-side provenance verification; writes immutable source/sidecar/coverage and prevents a matched protected-origin probe
`url_safety.py`	The egress gate: `safe_client()` validates the caller's URL and every redirect hop from an httpx `request` event hook, so a fetcher cannot forget to check and a 302 cannot jump into a private address. The criterion is HTTP(S) scheme, no userinfo, and every resolved address globally routable (every, not any — a name resolving to one public and one private address is the standard bypass); `trust_env=False` so a proxy environment variable cannot route around it either. The same module owns the write side: `RedactedUrl` is an annotated type whose serializer replaces credential values in a URL with `[REDACTED]` before it reaches disk (`corpus.json`, `coverage.json`, provenance sidecars, CLI stdout); in memory the URL stays whole, because a fetcher reads it off the model before issuing the request. Which field names count as credentials is `privacy.py`'s `is_credential_key` to decide, not this module's. `catalog.json` is the one exception and keeps whole URLs — `cache-url-pages` reads it back and fetches from it, so a URL there is an instruction, not evidence (ADR 0015).
`supplementary_note.py`	Imports a hand-written excerpt of supplier correspondence as a supplementary source; writes the immutable source plus a provenance sidecar bound to its content
`agentcli/`	assemble.py (assemble JSON → plan→preparation→generate→validate), input_schema.py (pydantic validation at the boundary), evidence.py (read-side v1 exact-evidence materialization/digest and claim-path verification), gate.py/verify.py (the extraction-contract check for `verify-extraction`, including the source-fact and deferral gates from `source_facts/`, writes nothing), extraction.py (inventory → plan answers), preprocess.py (typed PDF/DOCX→markdown orchestration)
`docx_*.py`	`docx_normalization.py` is the stable facade; package-wide fail-closed OOXML validation/rendering stays pure, while `docx_publish.py` owns staged provenance publication with rollback on reported write failures
`shadow/`	Opt-in legacy/Core bridge and in-memory runner; only `shadow/report.py` writes the observational `core/` artifact set or a safe error report.
`core/conformance.py` + `domain/conformance.py`	Pure ContractConformance assess/propose/compose boundary plus immutable authority, observation, amendment, and Effective Contract models.
`feedback/`	Normalized-JSON loading, full-Normative-release digest-bound assessment/proposal/composition, governed workflow adapters, timezone-aware exact-target lookup, and Provider Erratum handoff. Current lookup rejects not-yet-effective or expired assets and stale base/pointer/artifact bindings, and exposes bounded validity/discrepancy counters. Dry-run outputs stay outside `.foundry`; submit/review/approve persistence is delegated to Foundry and no command performs provider network I/O.
`extraction/`	Shared models + utilities (stages / questions / store / jsonblock)
`plan/`	Normalization plan + source-match classification
`preparation/`	Pre-generation readiness assessment + preparation-report (report.py writes files)
`generate/`	Generate OpenAPI / Markdown / review.html / provenance / examples / handoff (writes files)
`validate/`	Structure / completeness / consistency / no-speculation checks + report
`run/`	run-id generation, result/status models, writing the plan into the run-dir (writes files)
`score/`	Read a completed run-dir and produce score/score.{json,md} with five weighted categories (report.py writes files)
`diff/`	loader.py / compare.py / models.py / report.py (report.py writes files)
`freshness/`	A cheap scheduled freshness gate: record.py writes a baseline fingerprint from a completed run-dir (sha256 for local sources, one version signal per URL source, supplementary carriers always excluded — they cannot be re-obtained, so including one would only report fresh forever; a run with nothing re-obtainable is refused outright, and overwriting still needs `--force`), signals.py recomputes and classifies the current signal (network reads, writes nothing), check.py aggregates one docset, batch.py fans the gate across a watchlist (a per-item error is captured in that item's result rather than aborting the batch), report.py writes the reports. The exit codes are the contract: 0 unchanged, 1 changed, 2 inconclusive
`source_risk/`	Manifest-bound pre-agent text inspection and verified audit loading, covering both directions — whether a source can manipulate the agent and whether it leaks material to it. Among the leak rules only self-evidencing material (PEM private-key blocks, JWTs) blocks; a credential reference stays a warning, because a competent document documents its own Authorization header. reads exact source bytes and writes `source-risk-report.{json,zh-TW.md}` without rewriting or echoing source payloads
`source_quality/`	Pre-extraction source quality assessment and source version diff report; requires and embeds a verified source-risk audit; rejected reports may expose explicit bounded `required_source_refs` without crawling (writes files)
`focus/`	Requester-authored extraction focus directives: models.py (the strict contract; kind determines severity, intent determines anchor type, and there are only two outcomes, satisfied / not_found), loader.py (reads focus.json and focus-response.json — this package's only file-reading exit), gate.py/fields.py/codes.py (pure checks: one answer per directive, anchor resolution, and a not_found that must account for every readable source), report.py (writes `<run-dir>/focus/`, the only file-writing exit). A falsified assertion travels through the ValidationReport as `FOCUS_UNMET` rather than through the input gate — that is what keeps the artifacts available for a human to judge. A `collect_error_codes` answer reporting fewer codes than the documented floor computed from the source tables travels the same route, becoming a `FOCUS_INCOMPLETE` that names the omitted codes and where they are documented
`source_facts/`	Source-fact inventory: markdown.py mechanically scans Markdown sources for endpoint declarations, parameter tables and example blocks; collect.py reads the manifest-named sources (this package's only file-reading exit); gate.py compares them against the extraction JSON (resolving `schema_ref` into `inventory.schemas` transitively, so a shared body type is deduplication rather than an omission) and deferral.py rejects placeholder answers
`gitbook_llms.py` / `markdown_drafts/` / `extraction_scaffold/`	Deterministic GitBook acquisition fetches one `llms.txt`, safely caches every in-scope Markdown page plus provenance/coverage, then scans manifest-named Markdown into non-authoritative line-cited endpoint/table/example drafts and can project them into extraction-shaped scaffolds. A scaffold must be copied, reviewed, and completed in the work directory; it never replaces `source_facts/`, final extraction, or serves directly as `--extraction`.
`url_catalog.py` / `url_corpus.py`	Bounded URL navigation index, page caching, and related candidates, letting the agent read web docs from local evidence (writes files)
`foundry/`	Project-local asset governance: normative assets stay immutable, with supersession recorded on the new asset before pointers advance. Feedback inputs form the write-once candidate stage; bound decision/amendment records are append-only, and approval creates a separate immutable Effective release. Global `current` remains normative; Effective selection is exact-scope, time-aware, digest-verified, and rejected before approval/composition, after expiry, or after normative-base supersession.
`review/`	Local single-user workbench: auto-import a candidate, compare current/baseline, persist structured handoff, and update current through Foundry only after explicit human approval (writes files)

Do not read the wrong field. UrlSource.fetch_url is for issuing the request; its redacted form, citation_id, is for naming, comparing, and writing down. Reading the wrong one either puts a credential into plan.json or silently breaks a comparison/join — because a value read back from disk is redacted while its counterpart in memory is not. tests/test_citation_identity_contract.py fails on any read of fetch_url outside its ALLOWED list.

Marked rows contain file I/O exits: generate/, run/, agentcli/preprocess.py, shadow/report.py, feedback/report.py, preparation/report.py, score/report.py, diff/report.py, source_risk/report.py, source_quality/, freshness/, docx_publish.py, rendered URL import, supplementary_note.py, the URL corpus cache, foundry/, and review/workflow.py writing through Foundry. feedback/loader.py, docx_normalization.py, source_risk/inspect.py, and adapters/fragments.py are read-side I/O exits; Core and Domain remain pure.

Wrapping up

Glossary · What to read next

Glossary

seam: The only boundary between the two stages (inventory.json + endpoints/*.json), and also the cut point for testing.
manifest: The source inventory file, recording which sources and URLs were scanned.
normalization-plan: The plan after normalizing the extraction results; the shared input for generate and validate.
provenance: Source provenance; target aligns one-to-one with OpenAPI locations.
preparation: Pre-generation readiness assessment; in the quality loop, it flags blockers and things to watch first.
score: The quality score of a completed run-dir, used for back-half reading in the CI or review profile.
handoff: The engineering handoff pack derived from OpenAPI and the integration-contract; not a new contract source.
Normative / Effective Contract: The approved supplier-source release (contract + documentary fragments + support relationships) versus its deterministic, exact-scope composition with applicable approved amendments; they are distinct digest-bound artifacts and authority views.
Applicability Envelope: The complete provider, deployment, environment, identity, configuration, client, test-data, and time boundary for interpreting one observation or amendment.
fail-closed: When something can't be confirmed / conflicts, choose "don't output" rather than "guess one."
run-dir: The output directory of a single run, holding all of that run's artifacts.