feat(agent)!: build into a caller-owned graph config instead of the internal registry

[SkyeAv]

tablassert agent now requires --configuration-file/-f pointing at a caller-owned Graph YAML: the
agent reads its fullmap/name/version/rig: from that graph, audits each article with a one-table
copy of it, and appends successful absolute table-config paths back to that same file — replacing the
synthesized <state-dir>/graph.yaml registry.

CLI surface

• Required target: --configuration-file/-f replaces --fullmap; validated by
  graph_target.prepare_graph before any model, secret, or fetch work. PMC ids stay positional.
• Removed: the rebuild-agent-graph command and --fullmap parsing — tests/test_cover_cli.py
  locks both rejections.

Target graph mechanics (src/tablassert/graph_target.py)

• prepare_graph: resolves the YAML to an absolute path, validates the Graph, and resolves
  fullmap + rig.artifact_base_path against the graph's directory — in memory only; the file and all
  existing table YAMLs are never rewritten.
• append_successful_config: rereads the target under an exclusive <graph>.lock flock, drops the
  entry matching the config's basename stem, appends the new absolute path, re-validates, and persists
  via tmp + os.replace. Malformed targets raise without quarantine or overwrite.
• Success gate: only MAPPED / BUILT_UNMEASURED append; a failed rerun leaves the prior entry and
  best config untouched.

Supervisor semantics

• Forced reruns: the terminal-resume skip is deleted — requested PMCs are processed again on every
  invocation while state.json keeps attempts and coverage history. Only successful results atomically
  rewrite configs/<pmc_id>.yaml and update the target graph.
• Normalization: normalize_agent_table_config makes every generated source.local absolute
  (bases: cwd, state_dir, artifact root, graph dir); user-authored table YAMLs are never rewritten.
• Metadata inheritance: run_supervisor / make_tools / build_and_audit accept the prepared
  Graph; one-table audits deep-copy it, keep name/version/fullmap/full rig:, redirect only
  rig.artifact_base_path into builds/<pmc>/artifacts/, and pass audit_sources=False so a one-table
  audit never trips the full-table-set RIG cross-check.
• Legacy scalars preserved: fullmap/name/version kwargs remain for direct callers; the CLI
  path never uses them.

In-process build core

• Extracts build_graph_pipeline(graph, ...) from build_pipeline (src/tablassert/cli.py) so agent
  audits reuse the production stages without loading every table already in the target graph; build-kg
  behavior is unchanged.

Design

• Why caller-owned: the old registry synthesized agent_0.0.1 metadata and enforced a first-wins
  fullmap rule that could disagree with the graph users actually build. The supplied graph is now the
  single source of build identity and the single aggregation point.
• Accepted caveat — absolute paths: generated tables entries and source.local values are absolute
  by design (buildable from any CWD); the workspace is not relocatable without rerunning or fixing
  paths. Documented in docs/agent.md.
• Accepted caveat — state.json: the checkpoint read-modify-write stays per-workspace and unlocked;
  concurrent agents sharing one target graph must use separate --state-dirs or disjoint PMC sets. The
  graph file itself is flock-safe.
• src/tablassert/graph_registry.py (−215) and tests/test_graph_registry.py (−313) are deleted
  outright — no compatibility shim.

Docs & examples

• docs/agent.md — rewrites the workspace layout, checkpoint/rerun, and concurrency narrative around the
  caller-owned graph; docs/cli.md — updates the agent flag table and drops the rebuild-agent-graph
  section.
• examples/agent/ — README commands now use --configuration-file; the QC scripts glob
  <name>_<version>.* artifacts instead of hardcoded agent_0.0.1 names.

Testing

• uv run --extra qc --extra agent pytest -q → 929 passed, 13 skipped (94% coverage).
• uv run ruff check . + uv run ruff format --check . → clean.
• uv run --extra qc --extra agent pyright → 0 errors, 0 warnings.
• cargo test --manifest-path rust/Cargo.toml → 69 + 10 passed (1 ignored); cargo clippy --manifest-path rust/Cargo.toml --all-targets -- -D warnings → clean.
• New tests/test_graph_target.py: prepare-without-rewrite, metadata-preserving replace, malformed-target
  rejection, and an 8-process concurrent-append test that loses no entries.
• New supervisor coverage: target metadata drives artifact names (TARGET_KG_9.0.0.nodes.ndjson, no
  agent_0.0.1), failed reruns preserve the prior entry/config, successful reruns keep exactly one entry
  per PMC, and terminal + BUILT_UNMEASURED records are reprocessed on later invocations.

[coderabbitai]

Important

Review available on request

• 🔍 Trigger review

Reviews should be triggered manually for repositories with fewer than 10 stars. Select Trigger review above or comment @coderabbitai review to review the latest changes. For a full review, comment @coderabbitai full review.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 6025baf9-c744-4437-b098-b494f942592a

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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