100%

§07 platform domain python estate

Goal

The AI-OS platform’s Python estate (875K lines under scripts/) becomes a first-class graph domain: tree-sitter-python ingestion under CodeGraphScope ori-platform, GDS enrichment, and the 5 interim AST detectors migrate to graph queries.

Implementation Sketch

  • languages.yaml python entry mirrors the typescript entry shape (grammar_version pinned, expected_error_rate measured); decls/calls/imports .scm authored per parser_adapter conventions; _resolve_target_py is language-agnostic (deep-read fact) so python CALLS resolve for free at heuristic tier.
  • CodeGraphScope(‘ori-platform’, include=(‘scripts/’,), code_extensions=(‘.py’,), with_overlay=False) per the sync_code_graph INV-3a generalization; explicit bootstrap_repo (build-code-graph.sh gate-skips repos without :Repo — deep-read fact).
  • GDS: enrich_repo(driver,‘ori-platform’) in the sync tail; crate-rank/layering maps degrade gracefully (no crate concept).
  • Detector migration keeps the AST path until per-detector parity is measured (honest-degradation preserved).

Spec References

  • intel_repo/neo4j/sync_code_graph.py (CodeGraphScope INV-3a); intel_repo/languages.yaml; intel_repo/neo4j/gds_enrich.py (enrich_repo parameterization); scripts/impl_hygiene_review_runtime/python_detectors.py (the interim path this supersedes)

Work Items

  • languages.yaml python entry (tree-sitter-python) + decls/calls/imports .scm query families + validate-parsers.py coverage; CAPTURE_TO_KIND additions
  • Python call-resolution calibration: extend shared call-shape and import evidence for Python free, imported, qualified, and attribute calls; measure resolved and unresolved precision/recall against positive and false-bind fixtures instead of assuming the Rust-shaped _derive_call_shape resolver path applies for free
  • CodeGraphScope ori-platform (include scripts/, code_extensions .py, with_overlay False) + bootstrap_repo + sync driver + lefthook post-commit routing between ORI_SCOPE and the platform scope
  • Parameterize the canonical graph manifest and checkpointed relationship/full-sync coordinator for registered CodeGraphScope repos; preserve deterministic sorted batches, durable spools, source snapshots, code-fingerprint invalidation, progress envelopes, resume from the last committed batch, and repo-qualified writes without a parallel platform lifecycle path
  • GDS enrichment wired for ori-platform (enrich_repo parameterized call in the sync tail); platform staleness facet; domain-aware degradation for crate-shaped derived metrics (no crate concept in scripts/)
  • Register and ingest the repo-keyed Python hygiene fact substrate required by all five detectors: exception handler type and swallow-body shape, ordered terminator and following-statement facts, numeric literal occurrences, and mutable default-argument shape, with graph-contract identity, replacement scope, confidence, freshness, bidirectional query directions, and schema indexes
  • Migrate the 5 python AST filesystem detectors to graph-native queries over the platform domain (keep AST fallback until measured parity); platform query presets (—repo ori-platform rows in intelligence.md)
  • Tests: ingestion pins against real scripts/ fixtures, resolution sanity for python calls/imports, platform-domain fitness probe green
  • Deterministic platform acceptance gates: interrupt and resume full ingestion from the last committed checkpoint; prove every node, relationship, delete/replace transaction, GDS projection, freshness stamp, and query is isolated to repo ori-platform with ori as an unchanged negative control; register each detector query in the graph-contract query inventory and require live EXPLAIN to use the declared index with bounded Expand and no node, label, relationship, or variable-length scan; measure stable fixture-corpus latency, batch/progress output, detector parity, and platform fitness in deterministic machine-readable envelopes

Fresh intel (regenerated)

The section belongs in this plan and should remain one section, but its work-item shape must change before implementation.

  1. Add the Python AST facts required by the five detectors before migrating detector queries. Symbol, call, and import records cannot represent broad exception handlers, swallowed bodies, dead statements, mutable defaults, or literal occurrence counts.
  2. Reuse and parameterize the existing checkpointed relationship rebuild instead of creating a platform-only resume path. Its architecture already provides deterministic batches, durable spools, source snapshots, fingerprint invalidation, and restart/resume behavior, but it currently rejects every repo except ori.
  3. Register every platform detector query with the graph-contract query inventory and run the existing live EXPLAIN gate. The gate rejects node/relationship scans and unbounded variable expansion and requires index seeks plus bounded expansion.
  4. Preserve repo isolation on every node, relationship, projection, freshness stamp, query, and delete/replace transaction. ori-platform must never share an unqualified mutation or lookup with ori.
  5. Correct the implementation assumption that Python CALLS resolve entirely “for free.” The common resolver is reusable, but call-shape classification is explicitly Rust-shaped; Python attribute calls currently fall through with no method-shape guard and require measured Python-specific resolution calibration.

[JOIN] The detector-substrate gap and the performance-contract gap have one architectural cure: treat ori-platform as another registered repo-scoped producer under the existing graph contract, relationship rebuild, query-plan verifier, and fitness machinery. A parallel platform pipeline would violate SSOT; a declarations-only pipeline would fail the section goal.

VERDICT: Structurally expand the section with a detector-fact substrate item and a checkpointed/indexed performance-gate item. Keep the existing detector migration as the parity-and-cutover consumer of that substrate.

[]

DIG DEEPER

scripts/intel-query.sh status
scripts/intel-query.sh plan-status intel-graph-deepening
scripts/intel-query.sh dag-ascii intel-graph-deepening
scripts/intel-query.sh cypher "MATCH (r:Repo {name:'ori-platform'}) RETURN r.name, toString(r.last_platform_at)"

(full dossier: platform-domain-python-estate—s-b9cacd0d.intel.md)