Skip to content

feat: add shared agent graph registry - #72

Merged
SkyeAv merged 1 commit into
mainfrom
wk-tablassert-global-graph-registry
Aug 10, 2026
Merged

feat: add shared agent graph registry#72
SkyeAv merged 1 commit into
mainfrom
wk-tablassert-global-graph-registry

Conversation

@SkyeAv

@SkyeAv SkyeAv commented Aug 10, 2026

Copy link
Copy Markdown
Owner

Adds a concurrency-safe shared <state-dir>/graph.yaml registry so parallel tablassert agent runs can upsert successful PMC configs and then build one aggregate graph with tablassert build-kg -f <state-dir>/graph.yaml.

Shared Registry

  • Registry module: Adds src/tablassert/graph_registry.py with register_build and rebuild_graph.
  • Concurrent writes: Serializes read-modify-write with a sidecar graph.yaml.lock flock, writes via tmp file + os.replace, and uses absolute table config paths so build-kg works from any CWD.
  • Recovery: Quarantines corrupt registries as graph.yaml.corrupt-<UTC timestamp> and rebuilds fresh instead of wedging unattended runs.
  • Fullmap policy: Keeps the first recorded fullmap value and logs a warning on mismatches.

Agent + CLI

  • Supervisor wiring: run_supervisor now registers MAPPED and BUILT_UNMEASURED builds, never SKIPPED; registry failures are logged/noted without flipping a successful status.
  • Repair command: Adds tablassert rebuild-agent-graph --state-dir ... --fullmap ... to reconstruct/prune the registry from state.json.

Docs + Tests

  • Docs: Documents parallel agent fanout, shared-state caveats, locking, registered statuses, and the rebuild command in docs/agent.md and docs/cli.md.
  • Coverage: Adds registry unit tests, a true multiprocessing contention test, supervisor integration tests, CLI parsing/reporting tests, and updates docs CLI guardrails.

Design

  • Accepted caveat: graph.yaml updates are cross-process safe, but state.json remains per-process read-modify state; users should fan out disjoint PMC sets when sharing --state-dir.
  • Deferred: Custom graph name/version/description flags are not added; the registry uses stable defaults.

Testing

  • uv run ruff check . → passed
  • uv run ruff format --check . → 69 files already formatted
  • uv run pyright → 0 errors, 0 warnings, 0 informations
  • uv run pytest → 801 passed, 2026 warnings
  • uv run pytest tests/test_docs_cli_coverage.py -q → 6 passed

@SkyeAv
feat: add a concurrency-safe shared graph.yaml registry for parallel …
2e0f459 
…agent runs

Several `tablassert agent` processes pointed at the same `--state-dir` can now run in
parallel (over DISJOINT pmc sets) and each successful build self-registers into ONE global
Graph config that `tablassert build-kg -f <state-dir>/graph.yaml` builds as a whole.

- New `tablassert.graph_registry`: `register_build` upserts the best config by pmc-id
  basename stem (re-runs replace) and `rebuild_graph` reconstructs `tables` from
  `state.json` (MAPPED / BUILT_UNMEASURED records with an existing best config, sorted by
  pmc id, pruning stale entries). Both serialize on an exclusive `fcntl.flock` on the
  `graph.yaml.lock` sidecar around the read-modify-write and persist atomically (tmp file
  + `os.replace`, the same pattern as `save_state`). A corrupt registry (YAML error, not
  a mapping, or failing `Graph.model_validate`) is quarantined to
  `graph.yaml.corrupt-<UTC timestamp>` and rebuilt fresh, so unattended parallel runs
  self-heal. Fullmap is first-wins (existing value kept + warned on mismatch); entries are
  absolute paths so `build-kg` works from any CWD. Stdlib only — no new dependencies.
- Supervisor wiring: MAPPED and BUILT_UNMEASURED builds register after the status decision;
  registration is wrapped so it can NEVER flip a successful status (log + note, keep the
  status). SKIPPED never registers; a re-run that skips an already-MAPPED pmc keeps its
  entry (resume skips terminal records). `best_config_path` is now persisted absolute so
  cross-CWD rebuilds never silently prune.
- New `tablassert rebuild-agent-graph` command (`--state-dir`/`-sd` default
  `.tablassert/agent`, required `--fullmap`/`-f`) that rebuilds the registry from the
  checkpoint and prints the path + entry count; it also tolerates a corrupt `state.json`.
- Docs: parallel-agents section + workspace rows in docs/agent.md, command reference in
  docs/cli.md, and the docs-coverage guardrail mapping updated.
- Tests: registry semantics, quarantine, fullmap first-wins, a true 10-process concurrency
  test, cross-CWD rebuild, supervisor wiring (register / not-register / failure-keeps-status),
  and CLI parsing + forwarding.
@coderabbitai

coderabbitai Bot commented Aug 10, 2026

Copy link
Copy Markdown

Warning

Review limit reached

@SkyeAv, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 33 seconds

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5db345e2-17d8-4613-b19c-4121cddc255b

📥 Commits

Reviewing files that changed from the base of the PR and between 6a54349 and 2e0f459.

📒 Files selected for processing (10)
  • docs/agent.md
  • docs/cli.md
  • src/tablassert/agent.py
  • src/tablassert/cli.py
  • src/tablassert/graph_registry.py
  • tests/test_agent_cli.py
  • tests/test_agent_storage.py
  • tests/test_agent_supervisor.py
  • tests/test_docs_cli_coverage.py
  • tests/test_graph_registry.py

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@SkyeAv
SkyeAv merged commit 6c021fd into main Aug 10, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@SkyeAv