[binaryaaron]

Branch binaryaaron/graph-sdk/refactor/sync-core, five commits on the graph SDK line (PR #319). Branched at e0d8b317; it merges cleanly onto the current line head dddd02fa, which is one docs commit ahead.

Summary

The synchronous facade (run(), preview(), evaluate()) no longer starts a thread per invocation. Each invocation runs its graph on a private event loop on the caller's own thread, and every body runs inline on that thread. Ctrl-C therefore lands where 0.4.0 put it: inside DataDesigner's wait on the caller's thread.

Three steps make that possible, one commit each, plus one commit of tests and one of docs:

1. Substitute's map runs opaque. It now uses DataDesigner's own transport, retries and scheduling on every route, as it already did when its model skipped the health check, and as 0.4.0 does. The graph accounts it like Redact, Annotate, Hash and Rewrite: one invocation with unknown physical requests. The per-request bridge, its physical transport and the development-only qualified detection profile (its other consumer, not reachable from the facade) are deleted.
2. Bookkeeping is synchronous. Bodies and DataDesigner's per-row hooks no longer call back into the graph's event loop and wait for it. Their bookkeeping never suspends, so it runs on the calling thread under one lock; drive() raises if it ever suspends. Rewrite's repair loop needs the scheduler to start the next iteration between two bookkeeping calls, so a synchronous call that changed the ledger applies one scheduler step that starts subgraphs and closes blocked work but launches nothing. Owners with physical children (the SDK's worker path) keep their event-loop gate.
3. Private loop on the caller's thread. new_event_loop() + run_until_complete, with no asyncio.Runner and so no SIGINT handler. A caller already inside a running loop (Jupyter, asyncio.run) is blocked by the synchronous call anyway. Its running-loop marker is set aside for the private loop and restored around each body. On Python 3.14, which tracks the executing task per thread, the caller's current task is swapped with the marker. The host thread, the caller-thread queue, handoff and the interrupt settle/drain code are gone.
4. Tests. One subprocess Ctrl-C test with three cases replaces seven interrupt tests. The same file passes unchanged against 0.4.0 (main).
5. Docs. The graph SDK notes describe where graph bookkeeping now runs, and the deleted qualified detection profile is dropped from them.

Behaviour

Area	Before (graph SDK line)	After	0.4.0
Threads per run()	one anonymizer-graph-host per invocation (two or three with a delegating detector)	none from Anonymizer; only DataDesigner's engine threads	DataDesigner's only
Where caller code, bodies, DataDesigner calls and graph bookkeeping	the thread that triggers it: the caller's thread for bodies, DataDesigner's threads for its per-row hooks (under the runtime lock), except bookkeeping on the host thread	caller's thread	caller's thread
Ctrl-C during run()/preview()	caught in the host-queue server, then settled and drained	raised inside DataDesigner's wait; DataDesigner cancels its requests; the run raises KeyboardInterrupt	same as after
Ctrl-C inside asyncio.run	needs a second Ctrl-C	needs a second Ctrl-C	needs a second Ctrl-C
Jupyter (running loop in every cell)	works through the host thread	works through the marker swap; Kernel → Interrupt stops the run and the kernel stays healthy	works
Substitute map with a health-checked model	per-request graph accounting through a bridged transport	DataDesigner's own transport; the graph records no physical requests	DataDesigner's own transport
Caller detector **kwargs	received request_bridge=None	no request_bridge keyword	no request_bridge keyword

Rows, failed records, retries and dtypes show no differences against 0.4.0 beyond the line head's 102 accepted (allowlisted) rows: the parity corpus (166 cases, pandas 2 and 3) reports 0 blocking differences at every commit, with the same allowlisted rows as the line head.

Context variables: copy-in holds as before (values set before the call are visible inside); copy-out still differs from 0.4.0, where a value set inside caller code was visible after run() returned. That is the accepted delta recorded in the PR #319 status block, unchanged by this PR.

Not a compatibility contract

Until the graph SDK is published (REQ 13), nothing about anonymizer.graph or the engine modules behind it is a compatibility contract: names, export order, signatures, defaults, exception constructors, class pickles, thread names, the graph's request inventory and import cost may change. Tests that pin them are refactor safety nets, re-recorded with the change that moves them. What users can rely on is the shipped Anonymizer/config API, its result columns and errors, and Ctrl-C behaviour; this PR keeps those as the parity corpus and the subprocess Ctrl-C test show. anonymizer.graph.__all__ (228 names) and every public signature are byte-identical to the base.

Removed engine names and DataDesigner private hooks

Removed engine-level names (none re-exported by anonymizer.graph): harness.kernel.{acquire_native_transport, qualify_detection_redact, ensure_async_engine_loop, NATIVE_TRANSPORT_GATE_TIMEOUT_NS}; detection._graph_profile.{execute_detection_redact, ensure_async_engine_loop} and the run_detection_redact(limits=, opaque=) keywords; DetectionRedactInvocation.submit and its fields physical, slots, execution, semantic_loop, handoff; DetectionBinding.check_outcomes; ndd._graph_requests.{NddPhysicalTransport, NddRequestBridge, SingleAttemptTransportError, require_binding_capabilities, scheduler_salvage_rounds, skip_health_checks_env}; the native-map route in ndd._route; the module replace/_native_map_requests.py. A caller detector declared with **kwargs no longer receives request_bridge, which matches 0.4.0.

DataDesigner private dependencies removed: DataDesigner._create_resource_provider; ModelRegistry(model_facade_factory=) and ModelRegistry._model_facade_factory; ModelFacade.agenerate as a bridge hook; models.clients.retry.create_retry_transport; the _HTTP_CLIENT_FIELDS coupling; readiness._SKIP_MODEL_HEALTH_CHECKS_ENV; AsyncTaskScheduler(salvage_max_rounds=); the bridge's use of parsers.errors.ParserException (the judge's use remains, as on main).

Private hooks that remain: DataDesigner._create_dataset_builder, BatchStage, SDG_CONFIG_FILENAME and DatasetBuilder/ArtifactStorage internals (engine/ndd/_graph_requests.py:51-82), and the generator.agenerate patch in engine/ndd/_source_frame.py.

Size

Commit	src net
Opaque Substitute map, delete the native request path	-1,722
Synchronous bookkeeping	+35
Private loop on the caller's thread	-105
Tests	0
Total	-1,792 (+324 / -2,116)

Tests: +334 / -2,673. Docs: +12 / -32.

Testing

• Full suite on pandas 2.3.3 and 3.0.6 at every commit (5,538 passed on each at the tip). make format-check, make typecheck and mkdocs build --strict pass.
• Parity corpus against main at every commit: 0 blocking (pandas 2 and 3), plus the main+fix(interface): only pass entity_label_examples when the detector accepts it #311 reference cases.
• tests/interface/test_interrupt.py: three cases (plain; inside asyncio.run; second Ctrl-C), each passing on main, the line head and this branch with identical event sequences.
• tests/interface/test_thread_placement.py green. It now also rejects any anonymizer-graph* thread started during a run.
• Topology-relevant tests on Python 3.13 and 3.14.
• A real ipykernel ran every route and a Kernel → Interrupt.

Not verified

• Windows and macOS.
• The full suite on Python 3.12, 3.13 and 3.14 (3.13 and 3.14 ran the topology-relevant files only).
• Python 3.15.
• Live providers, including a health-checked Substitute model against a real endpoint.
• A browser-driven notebook, and nest_asyncio with the real library.
• Contention on the bookkeeping lock beyond the test suite.
• A graph whose body needs a newly launched operation mid-body. None exists on the facade today; such an operation would start after the body returns.
• graph_sdk/_foreign_transport.py stays. It has no Anonymizer consumer left, but removing it is a separate SDK-surface decision.

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge based on the reviewed changes.

Summary

The PR moves synchronous graph execution onto a private event loop on the caller’s thread.

• Synchronous graph calls now run on the caller’s thread.
• Graph bookkeeping now runs inline with synchronous bodies.
• Substitute maps now use DataDesigner’s own transport and retries.

Acknowledged by binaryaaron: internal engine APIs are not compatibility contracts; context-variable changes inside a call remain isolated; and the documented second-interrupt behavior is intentional.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A["Synchronous caller"] --> B["Private event loop on caller thread"]
  B --> C["Body runs inline"]
  C --> D["Graph bookkeeping under invocation lock"]
  C --> E["DataDesigner call and wait"]
  E --> F["DataDesigner engine threads"]
  F --> D
  B --> G["Close private loop and restore caller"]

Loading

_{Reviews (1) · Last reviewed commit: "docs: describe where graph bookkeeping r..." · Reviewed by Greptile}