DL4: a custom function's preparation runs before the server reports it usable

[trissim]

DL4 · draft · guards 3/3 new (5/5 in the file) · production −21 +107 · tests −0 +423

Gap 5 of the Cellpose/N2V2 receipt (#1230): a custom function's declared preparation ran in the first compile after readiness, and workers loaded the resource again on later runs. Receipt: docs/refactor/consolidation-20261009/DL4-custom-function-preparation.md.

What changed

• A process that prepared its catalogue for serving prepares a custom source when it loads it, through the same CallablePreparation.prepare_for_serving catalogued functions use (CallablePreparation.prepare_published, called from project_declaration in the custom-function manager). Authoring processes load without preparing.
• At server start the persisted sources are therefore prepared before readiness and before the workers fork. A source stored while the server is ready is prepared when the server loads it: by the registration request, or by the catalogue-preparation request, during which the server reports pending.
• A preparation that raises is a CustomFunctionLoadFailure of that source alone (file, line, error); a registration that fails publishes nothing.
• After the server prepares something late it forks its idle workers again and replaces leased ones on return (PreparedForkWorkerLaneRunner.replace_with_current_forks), so fork workers inherit the loaded resource.

Measured (Cellpose nuclei, CPU, 4 BBBC039 fields, 2 workers, cold weights)

	main, fork	branch, fork	main, spawn	branch, spawn
Weight download + model load	first compile, 4.86 s	preparation, 6.35 s	first compile, 3.23 s	preparation, 5.63 s
First compile / second compile	5.46 s / 0.09 s	0.21 s / 0.09 s	3.58 s / 0.07 s	0.14 s / 0.11 s
Model loads per worker, run 1 / run 2	1 / 1	0 / 0	1 / 1	1 / 1

Not done (details in the receipt)

1. Spawn workers (the default start method, and every GPU step) still start per execution and load per run.
2. Preparation that depends on a parameter (which model): proposal and owner decision in the receipt, not implemented.
3. The GUI editor does not tell a running server about a new source, so that path still prepares in the first compile that imports it.
4. No GPU run.

Gates

• guardrails_local.sh: base a51f4eab135b8b56f55f048391497fa62015b41d head b182fefef392a6006c9352d8ae1306e78401183f guardrails rc=0
• smoke_local.sh: smoke pytest exit 0 (335 s): 7 passed, 2 warnings in 322.33s (0:05:22), smoke gui exit 0 (51 s), smoke rc=0
• Guard file tests/integration/test_no_jit_after_readiness.py: 5 passed in 205.22s (0:03:25)
• Touched unit tests: 180 passed, 3 warnings in 22.07s
• verify_branch.sh (full suite) and official30 parity: queued, not yet reported; results will be added to the receipt.

🤖 Generated with Claude Code