This is the complete event reference for the plugin system, akin to API endpoints — it lists the firing time and payload parameters of every hook.

Event Dispatch Mechanism¶

• Registration: engine.register_hook(event, handler)
• Emission: engine.emit_hook(event, **kwargs) iterates over all handlers for the event and invokes each in turn via handler(**kwargs)
• Exception isolation: an exception raised by a single handler is only logged and does not affect the scan
• Handler signature: write the event parameter names you need and you're compatible (excess kwargs are not passed)

Event Table¶

on_scan_started¶

Firing time: engine.start(), after setting the running state and creating the timestamped output directory for this run.

on_scan_completed¶

Firing time: when the concurrent breeding loop finishes and the state is completed, before the finally: stop() exports the report.

on_scan_stopped¶

Firing time: stop() (normal end / Ctrl+C / abnormal cleanup all reach here); the event is emitted first, then the checkpoint is saved and output exported.

on_asset_scanned¶

Firing time: in _process_asset(), after the breeder finishes executing and the discovery loop runs; fires whether or not new assets were produced.

on_asset_discovered¶

Firing time: inside the discovery loop of _process_asset(), emitted once per new asset when asset_graph.add_asset(new_asset) returns True (first-time entry into the store). Only listen to it if you care about "new discoveries".

on_asset_excluded¶

Firing time: any of the following 5 branches is hit (comments give their location in _process_asset):

1. Exceeds max_depth
2. Asset type disabled by asset_types.<type>.enabled = false
3. Exceeds resource limits (resource_limits counters or type depth_limit)
4. Matches an exclusions exclusion rule
5. No corresponding breeder

on_asset_eliminated¶

Firing time: after the breeder runs, the asset state is marked as eliminated (the breeder judged that the asset has no value).

on_asset_failed¶

Firing time: the exception branch of _process_asset(), when processing an asset raises an exception; also increments metrics["errors"] += 1.

Lifecycle Sequence Diagram¶

flowchart TB
    start["Scan starts"] --> hook1["on_scan_started(engine)"]
    hook1 --> loop{"Process each asset concurrently"}

    loop --> excl{"Excluded?"}
    excl -->|yes| he["on_asset_excluded"]
    excl -->|no| breed["Breed"]
    breed --> nd["New asset loop"]
    nd --> hd["on_asset_discovered"]
    breed --> hsc["Complete"]
    hsc --> hscn["on_asset_scanned"]
    breed --> nelim{"No value?"}
    nelim -->|yes| he2["on_asset_eliminated"]
    breed --> herr{"Exception?"}
    herr -->|yes| hf["on_asset_failed"]

    hd --> loop
    hscn --> loop
    he --> loop
    he2 --> loop
    hf --> loop

    loop -->|all done| done["Scan complete"]
    done --> hc["on_scan_completed(engine)"]
    hc --> hstop["Stop / cleanup"]
    hstop --> hs["on_scan_stopped(engine, finalize=True)"]

Writing Notes¶

• on_asset_* is invoked from concurrent threads — lock any shared state in your handlers
• on_scan_started / on_scan_completed / on_scan_stopped are invoked at relatively well-defined points
• Handlers must not raise (exceptions are swallowed and logged); if you need to report an error, log it yourself

References¶

• Event emission source: main.py emit_hook() (around line 178)
• Hook scanning: main.py _scan_hook_names(): module-level on_* callable objects
• Full plugin development guide: Plugin Development