Core38 Docstring Drift Audit

Scope

  • Package: engine/src/tangl/core38

  • Objective: correctness-first drift detection and docstring contract alignment

  • Non-goal: runtime behavior changes

Method

  1. Parsed module/class/function docstrings across core38 and compared against public callable surface.

  2. Mapped documentation claims to core38 tests in engine/tests/core38.

  3. Ran doctests and unit tests to validate documentation truthfulness.

  4. Applied targeted P0/P1 fixes and high-impact P2 method-level coverage in requested modules.

Severity-Ranked Findings

P0 (Correctness)

F-P0-001: RuntimeOp doctest example was not executable with safe_builtins

  • File/line: engine/src/tangl/core38/runtime_op.py:48

  • Drift type: wrong behavior in docs

  • Current contract (before fix): example used print(...) inside apply_all(...).

  • Intended contract: examples must run under safe_builtins; print is unavailable.

  • Legacy inspiration: examples in engine/src/tangl/core/entity.py prioritize runnable, assertion-oriented doctests.

  • Status: fixed in this pass.

P1 (Semantic Ambiguity / Stale Contracts)

F-P1-001: Dispatch module docstring referenced stale API names

  • File/line: engine/src/tangl/core38/dispatch.py:4

  • Drift type: stale name/path

  • Current contract (before fix): referred to generic on_task/do_task and Registry.add_item().

  • Intended contract: explicit hook pairs (on_init, do_init, etc.) and Registry.add/get/remove.

  • Legacy inspiration: explicit API sections in engine/src/tangl/core/behavior/behavior_registry.py.

  • Status: fixed in this pass.

F-P1-002: bases cross-reference pointed to removed legacy module

  • File/line: engine/src/tangl/core38/bases.py:80

  • Drift type: stale name/path

  • Current contract (before fix): core.requirement listed as current follow-on module.

  • Intended contract: reference vm38.provision.requirement for requirement/provisioning semantics and core38.* for core surfaces.

  • Legacy inspiration: module map discipline from engine/src/tangl/core/registry.py and engine/src/tangl/core/graph/graph.py.

  • Status: fixed in this pass.

F-P1-003: Behavior.sort_key prose did not match tuple order

  • File/line: engine/src/tangl/core38/behavior.py:258

  • Drift type: wrong behavior in docs

  • Current contract (before fix): claimed priority-first ordering.

  • Intended contract: dispatch_layer first, then priority, then wants_exact_kind, then seq.

  • Legacy inspiration: ordering contract clarity from enum docs in engine/src/tangl/core/behavior/behavior.py.

  • Status: fixed in this pass.

F-P1-004: merge_results inline comment contradicted actual merge policy

  • File/line: engine/src/tangl/core38/behavior.py:165

  • Drift type: semantic contradiction

  • Current contract (before fix): comment said early entries override late entries.

  • Intended contract: later dict results override earlier ones (ChainMap(*reversed(results))).

  • Legacy inspiration: reduction semantics and receipt prose in engine/src/tangl/core/behavior/call_receipt.py.

  • Status: fixed in this pass.

P2 (Coverage / Clarity)

F-P2-001: High-impact modules had missing public method docstrings

  • Drift type: missing API explanation

  • Modules prioritized by this pass: runtime_op, dispatch, behavior, record, template, singleton.

  • Status: fixed in this pass (public-callable gaps reduced to zero for these modules).

  • Legacy inspiration: class/API curation style in engine/src/tangl/core/behavior/behavior_registry.py and engine/src/tangl/core/registry.py.

F-P2-002: Remaining coverage hotspots outside requested target modules

  • Drift type: missing API explanation

  • Current hotspots (still open):

    • engine/src/tangl/core38/bases.py

    • engine/src/tangl/core38/graph.py

    • engine/src/tangl/core38/ctx.py

    • engine/src/tangl/core38/token.py

  • Status: open (deferred by scope to keep momentum on correctness-first items).

  • Legacy inspiration: detailed GraphItem/Graph surface docs in engine/src/tangl/core/graph/graph.py.

P3 (Polish)

F-P3-001: Protocol method-level explanation depth remains uneven

  • Drift type: polish

  • Affected area: RuntimeCtx method semantics in engine/src/tangl/core38/behavior.py.

  • Status: partially improved by module/class-level docs; method-level expansion deferred.

Inventory Snapshot

Pre-pass hotspot snapshot (captured)

  • runtime_op.py: 100% missing public-callable docstrings

  • singleton.py: 100%

  • template.py: 95.2%

  • dispatch.py: 92.9%

  • record.py: 87.5%

  • behavior.py: 85.7%

Post-pass snapshot

  • runtime_op.py: 0% missing

  • singleton.py: 0%

  • template.py: 0%

  • dispatch.py: 0%

  • record.py: 0%

  • behavior.py: 33.3% (residual primarily protocol/helper methods)

Rewrite Snippet Pack (P0/P1)

S-P0-001 (runtime_op.py doctest-safe example)

>>> RuntimeOp.apply_all("abc = abc + 1", "abc = abc * 2", ns={"abc": 123})
{'abc': 248}

S-P1-001 (dispatch.py module contract language)

Default global dispatch registry and explicit hook pairs for core38 lifecycle events.
...
- `on_create` / `do_create`
- `on_init` / `do_init`
- `on_add_item` / `do_add_item`
...

S-P1-002 (bases.py where-to-look references)

- `core38.selector` for matching.
- `vm38.provision.requirement` for satisfaction and provisioning contracts.
- `core38.registry` for registry ownership and grouping.

S-P1-003 (behavior.py sort-key semantics)

Sorts by:
  - layer: global -> local
  - priority: low -> high
  - wants_exact_kind: False then True
  - registration seq: earlier -> later

S-P1-004 (behavior.py dict-merge policy note)

return ChainMap(*reversed(results))  # later dict values override earlier ones

Optional P2 Snippet Set (Prioritized)

  1. engine/src/tangl/core38/graph.py: add concise docs for typed find helpers and GraphItem.graph alias.

  2. engine/src/tangl/core38/ctx.py: document get_ctx/using_ctx runtime contract explicitly.

  3. engine/src/tangl/core38/token.py: add method docs for reference_singleton, factory helpers, and wrapper semantics.

  4. engine/src/tangl/core38/bases.py: add concise docs to HasIdentity helper methods (get_identifiers, has_identifier, id_hash).

Reusable Rubric for vm38/story38/service38

  1. Executable examples: every doctest must run under real safety/runtime constraints.

  2. Name fidelity: doc names must match current callable/API names exactly.

  3. Ordering fidelity: prose ordering must match real tuple/sort behavior.

  4. Aggregation fidelity: reduction semantics must match actual fold functions.

  5. Context contract clarity: minimal required protocol methods are explicit.

  6. Boundary clarity: clearly separate mechanism (core/vm) vs policy (story/service).

  7. Layer references current: no stale module references from pre-refactor names.

  8. Public method coverage: non-trivial public methods have one-sentence contract docs.

  9. Cross-layer pointers: each module has actionable See Also links to current layer peers.

  10. Truthfulness gate: docs pass doctests and do not contradict package tests.

Validation

  • Doctests: poetry run pytest --doctest-modules engine/src/tangl/core38 -q

  • Core38 tests: poetry run pytest engine/tests/core38 -q

Both were run after this pass and are green.