phenotypic.sdk_.resolve_run_state

phenotypic.sdk_.resolve_run_state(output_dir: Path, *, depth: Literal['shallow', 'deep'] = 'deep') → RunState

Resolve one run’s completion state (spec §4.3, §9).

Verdict precedence is total and ordered (OPEN-QUESTIONS Q2): complete > active > failed > incomplete. First match wins. contradictory does not exist.

complete outranks active because a run proof covers the current inventory: a live worker at that point is either fenced by restart_epoch or belongs to a new invocation that has already changed the inventory, in which case rule 1 does not fire and this is not the case being decided. active outranks failed so that a failure from a previous attempt cannot mask an attempt currently retrying it.

depth="shallow" re-stats the verification cache’s recorded tuples – tier 1 in process, tier 2 from .phenotypic/verification_cache.json when tier 1 is cold (U-11) – and falls through to a deep pass for any image that is absent from the cache, moved, minted under a different identity, or unreadable. It never yields a positive verdict from a cache entry alone (INV-VERDICT): a cached entry can only ever license skipping a re-verification the caller already performed, and the run-level proofs are re-verified on every call regardless. A pass that deep-verified anything rewrites tier 2; a fully warm one writes nothing.

Parameters:

• output_dir (Path) – Run output root. May be any directory, including one this package has never written to.

• depth (Literal['shallow', 'deep']) – "deep" re-verifies every declared artifact’s content and repopulates the cache. "shallow" re-stats instead. See spec §9’s caller/depth table.

Returns:

A RunState. Never raises for an unreadable or absent tree – every parse failure degrades toward incomplete (INV-VERDICT’s degrade half). RunState.depth reports the depth actually performed, which for a cold "shallow" call is "deep".

Return type:

RunState