---

This section details on the original issue you should resolve

<issue_title>query provenance</issue_title>
<issue_description>

Add provenance + performance tracing to QueryResult in py3plex so every result can report how it was computed (AST, params, seeds, backend path, timings, cache hits), without breaking existing APIs.

Hard constraints

Preserve backward compatibility: existing code using QueryResult must keep working.

No new required parameters in user-facing APIs.

Store provenance in QueryResult.meta (or a compatible nested structure) with stable keys.

❌ Do NOT create new markdown files.

✅ Update AGENTS.md in place to reflect the new QueryResult.meta["provenance"] structure.

---

1. Define a provenance schema (internal, stable)

Add an internal dataclass/TypedDict (e.g., ProvenanceRecord) with fields:

engine: "dsl_v2_executor" | "dsl_legacy" | "graph_ops" | "pipeline_step" | ...

py3plex_version

timestamp_utc (ISO8601)

network_fingerprint: lightweight (node_count, edge_count, layer_count, optional hash if available)

network_version: mutation counter if available; else None

query:

target: nodes/edges/communities/paths

ast_hash: stable hash of AST (or compiled plan)

ast_summary: short human-readable summary (no huge dumps)

params: normalized params (gamma, ci, n_samples, etc.)

randomness:

seed: base seed if any

child_seeds: optional list or seed-derivation descriptor (avoid huge arrays)

backend:

graph_backend: "networkx" (future-proof)

algo_backend: module/function identifiers used

fast_path: bool + reason

performance:

timings_ms: dict per stage (parse/compile/filter/compute/group/aggregate/format)

cache: hits/misses + keys used (redact large)

warnings: list of strings (e.g., “approximation used”, “fallback to serial”)

1. Instrument DSL v2 execution pipeline

In DSL v2 executor:

start a timer at execute() entry

time stages: compile→filter→compute→group/agg→materialize

attach provenance into QueryResult.meta["provenance"]

Ensure zero/low overhead when tracing is minimal (simple time.monotonic calls only).

1. Instrument legacy DSL execution

Add provenance fields:

engine="dsl_legacy"

query.raw_string

parse_time_ms, exec_time_ms

Same meta["provenance"] shape as v2 where possible.

1. Instrument graph_ops + pipelines (best-effort)

graph_ops:

when materializing (to_pandas, to_subgraph), attach provenance if a QueryResult exists or create a minimal provenance meta object.

pipelines:

when steps produce a QueryResult-like artifact, propagate/merge provenance (append step info).

1. Stable AST hash + summary

Implement ast_fingerprint(ast):

stable across process runs (avoid object ids)

include node types + normalized params only

Implement ast_summary(ast):

short: target, layer selection, predicates, computes, grouping/agg, limits

1. Network fingerprint + optional mutation counter

If network already has versioning, use it.

Otherwise implement lightweight fingerprint:

counts + layer names (optional)

optionally a cheap hash of sorted layers and a sample of edges (avoid O(E log E) on huge graphs)

1. Cache reporting hooks (if caches exist)

When metric/result caches are used:

record cache.hit, cache.miss, cache_keys (truncate)

1. Tests (required)

Ensure QueryResult still serializes/behaves as before.

Add tests that:

meta["provenance"] exists after DSL v2 execute

keys are present and types are correct

timings are non-negative

AST hash is stable across identical queries

legacy DSL also populates provenance

1. Documentation (AGENTS.md only)

Update AGENTS.md in place:

document QueryResult.meta["provenance"] keys and example payload

clarify it’s additive, backward compatible

❌ No new markdown files

Definition of done

Every query execution returns a QueryResult with meta["provenance"] populated (v2 + legacy).

Provenance is stable, lightweight, and does not break existing code.

Tests cover presence, stability, and basic correctness.</issue_description>

Comments on the Issue (you are @copilot in this section)