[Wave 4] Low/info — Docs: docs/design/library_api.md #721

Wave 4 · 6 finding(s) in 6 fix package(s). One pass over this document; keep the Turkish mirror in sync.

Findings

• DOC-BLEGAL-174 (docs, Low) — docs/design/library_api.md: stale — | forgelm.__version__ | PEP 396 / 8 string. |
  severity Low
  Where. docs/design/library_api.md:79 · type: stale
  The document says. | forgelm.__version__ | PEP 396 / 8 string. |
  What the code does. PEP 396 'Module Version Numbers' is Withdrawn: it was formally rejected on 2021-04-14, reclassified as withdrawn on 2024-10-21, and points to the PyPA guides. PEP 440 (Final) is the normative version-string specification. PEP 8 mentions version only for the placement of dunders. The importlib.metadata pattern ForgeLM uses is the one in the PyPA 'Single-sourcing the Project Version' guide.
  Proposed correction. '| forgelm.__version__ | PEP 440 version string (single-sourced via importlib.metadata per the PyPA guide). |'

• DOC-D2B04-028 (docs, Low) — docs/design/library_api.md: wrong detail — prepare_dataset 'Returns a datasets.Dataset'. Public symbols returning heavy types use the TYPE_CHECKING + string-quoted pattern, e.g. get_model_and_tokeni… severity **Low** **Where.** [docs/design/library_api.md:94](https://github.com/HodeTech/ForgeLM/blob/cab2947/docs/design/library_api.md#L94), docs/design/library_api.md:152-166 · type: wrong detail **The document says.** prepare_dataset 'Returns a datasets.Dataset'. Public symbols returning heavy types use the TYPE_CHECKING + string-quoted pattern, e.g. get_model_and_tokenizer(config: ForgeConfig) -> "tuple[PreTrainedModel, PreTrainedTokenizerBase]". **What the code does.** prepare_dataset(config: Any, tokenizer: PreTrainedTokenizer) -> Dict[str, Any]returns a split dict.get_model_and_tokenizer(config: Any) -> Tuple[Any, Any] uses no forward reference; only data.py uses TYPE_CHECKING, and only for the tokenizer parameter. **Code references.** [forgelm/data.py:6-9](https://github.com/HodeTech/ForgeLM/blob/cab2947/forgelm/data.py#L6-L9), [forgelm/data.py:691](https://github.com/HodeTech/ForgeLM/blob/cab2947/forgelm/data.py#L691), [forgelm/model.py:545`](https://github.com/HodeTech/ForgeLM/blob/cab2947/forgelm/model.py#L545)
  Proposed correction. Write: 'prepare_dataset returns Dict[str, Any] (split -> Dataset)' and 'get_model_and_tokenizer is annotated -> Tuple[Any, Any] today; the forward-reference pattern is a target, not the current state.'

• DOC-D2B04-029 (docs, Low) — docs/design/library_api.md: stale — The reference lives at docs/reference/library_api.md (#experimental, #concurrency, plus a -tr mirror). notebooks/library_api_example.ipynb exists. README has a 'Li…
  severity Low
  Where. docs/design/library_api.md:97, docs/design/library_api.md:376-382, docs/design/library_api.md:414, docs/design/library_api.md:439, docs/design/library_api.md:526 · type: stale
  The document says. The reference lives at docs/reference/library_api.md (#experimental, #concurrency, plus a -tr mirror). notebooks/library_api_example.ipynb exists. README has a 'Library API' section. The guide has a #config-from-dict anchor.
  What the code does. The reference is docs/reference/library_api_reference.md ('### Experimental' at L23, '## Concurrency' at L248), and docs/reference/library_api.md does not exist. No library_api_example.ipynb exists. README has a single 'Stable Python API' bullet (README.md:161), not a section. The guide heading is 'Construct a config from a dict (no YAML)'.
  Code references. docs/reference/library_api_reference.md:23, docs/reference/library_api_reference.md:248, README.md:161, notebooks/ (listing)
  Proposed correction. Replace docs/reference/library_api.md with docs/reference/library_api_reference.md throughout, mark the notebook row 'not shipped', and change the README row to 'one-line Stable Python API bullet'.

• DOC-D2B04-030 (docs, Low) — docs/design/library_api.md: stale — forgelm.safety is Internal and the run_safety_evaluation reach-in is undocumented. Phase 36 promotes it to Stable via re-export 'when the standalone subcommand shi…
  severity Low
  Where. docs/design/library_api.md:119 · type: stale
  The document says. forgelm.safety is Internal and the run_safety_evaluation reach-in is undocumented. Phase 36 promotes it to Stable via re-export 'when the standalone subcommand ships'.
  What the code does. The standalone forgelm safety-eval subcommand ships, yet forgelm.safety is still absent from all. The code's own docstring calls run_safety_evaluation 'a public Python API (importable as from forgelm.safety import run_safety_evaluation)'.
  Code references. forgelm/cli/subcommands/_safety_eval.py, forgelm/cli/__init__.py:234-237, forgelm/safety/_inputs.py:75-78, forgelm/__init__.py:77-119
  Proposed correction. Write: 'Internal. The safety-eval subcommand shipped without a re-export; promotion is deferred.' Alternatively, align the _inputs.py docstring.

• DOC-D2B04-031 (docs, Low) — docs/design/library_api.md: stale — forgelm/_version.py lines 32-39 hold __api_version__ = "1.0.0". Tiers are 'pinned in forgelm/init.py::all + _LAZY_SYMBOLS'. api_version is 'semver 1.…
  severity Low
  Where. docs/design/library_api.md:303-304, docs/design/library_api.md:521, docs/design/library_api.md:524 · type: stale
  The document says. forgelm/_version.py lines 32-39 hold __api_version__ = "1.0.0". Tiers are 'pinned in forgelm/init.py::all + _LAZY_SYMBOLS'. api_version is 'semver 1.0.0'.
  What the code does. api_version = "1.2.0" at _version.py:66, and the bump rules are at L31-34. Tiers are recorded in _STABILITY_TIERS; all and _LAZY_SYMBOLS carry membership only.
  Code references. forgelm/_version.py:31-34, forgelm/_version.py:66, forgelm/__init__.py:122-177
  Proposed correction. §12: 'api_version (semver, currently 1.2.0)'; 'tiers pinned in forgelm._STABILITY_TIERS'. §5.1: 'bump rules at forgelm/_version.py:31-34'.

• DOC-D2B04-032 (docs, Low) — docs/design/library_api.md: wrong detail — CLI dispatchers exit with codes 0/1/2/3/4. audit_dataset raises OptionalDependencyError for a missing extra. verify_audit_log raises OSError for unreadable…
  severity Low · already tracked: KNOWN-OPEN C31-EXIT-CODE-PROSE — docs/roadmap/phase-16-trust-surface-hardening.md:782-785
  Where. docs/design/library_api.md:418-425 · type: wrong detail
  The document says. CLI dispatchers exit with codes 0/1/2/3/4. audit_dataset raises OptionalDependencyError for a missing extra. verify_audit_log raises OSError for unreadable files. AuditLogger.log_event raises OSError on write failure.
  What the code does. Public exit codes are 0-6. audit_dataset raises plain ImportError (_pii_ml.py:98, _minhash.py:21), while OptionalDependencyError belongs to ingestion.py:63, so except OptionalDependencyError misses audit's errors. verify_audit_log returns valid=False for unreadable files and never raises. log_event can also raise ConfigError (genesis-manifest re-root refusal) and ValueError (truncated or non-UT…
  Code references. forgelm/cli/_exit_codes.py:10-39, forgelm/data_audit/_pii_ml.py:97-98, forgelm/data_audit/_minhash.py:21, forgelm/ingestion.py:63
  Proposed correction. Update the table: exit codes 0-6; audit_dataset -> ImportError (with install hint); verify_audit_log -> never raises (VerifyResult.valid=False); log_event -> OSError, ConfigError (re-root refused), ValueError (corrupt tail).

Done when

• Every finding above is fixed or closed with a reason (tick it here).
• Code fixes carry a test; doc fixes update the Turkish mirror in the same PR.

_{Found by the October 2026 ForgeLM code and documentation review against commit cab2947. Code links point at that commit; line numbers may have moved since. Finding IDs (CR-…, DOC-…, TECH-…) are stable references for this backlog.}