build_tools.syllable_walk_web.services.profile_reaches_cache

IPC-backed cache for precomputed walker profile reaches.

This module provides a deterministic, run-directory-local cache for the profile reach tables computed during /api/walker/load-corpus.

Cache goals: - Avoid recomputing profile reaches when corpus + walker settings are unchanged. - Keep each run directory self-contained as the source of truth. - Use pipeworks-ipc hashes so cache validity is explicit and auditable.

Cache file location: <run_dir>/ipc/walker_profile_reaches.v1.json

Attributes

`CACHE_SCHEMA_VERSION`
`CACHE_KIND`
`CACHE_FILENAME`
`CACHE_SCHEMA_ID`
`MANIFEST_FILENAME`
`PROFILE_NAMES`

Classes

`CacheReadResult`	Result of attempting to read and validate a profile-reach cache.
`ManifestIPCInfo`	Canonical IPC fields extracted from one run's `manifest.json`.

Functions

`cache_path`(run_dir)	Return canonical cache path for one run directory.
`read_cached_profile_reach_hashes`(run_dir)	Return cache IPC hashes from disk, if present and valid.
`load_cached_profile_reaches`(*, run_dir, run_id, walker)	Read and validate cached profile reaches for a run.
`write_cached_profile_reaches`(*, run_dir, run_id, ...)	Write deterministic profile-reach cache for a run.

Module Contents

build_tools.syllable_walk_web.services.profile_reaches_cache.CACHE_SCHEMA_VERSION = 1

build_tools.syllable_walk_web.services.profile_reaches_cache.CACHE_KIND = 'walker_profile_reaches'

build_tools.syllable_walk_web.services.profile_reaches_cache.CACHE_FILENAME = 'walker_profile_reaches.v1.json'

build_tools.syllable_walk_web.services.profile_reaches_cache.CACHE_SCHEMA_ID = 'urn:pipeworks:schema:walker-profile-reaches-cache:v1'

build_tools.syllable_walk_web.services.profile_reaches_cache.MANIFEST_FILENAME = 'manifest.json'

build_tools.syllable_walk_web.services.profile_reaches_cache.PROFILE_NAMES = ('clerical', 'dialect', 'goblin', 'ritual')

class build_tools.syllable_walk_web.services.profile_reaches_cache.CacheReadResult[source]

Result of attempting to read and validate a profile-reach cache.

status: One of hit, miss, invalid, error, none. none means cache is ineligible because required manifest IPC metadata is missing.

profile_reaches: Populated only for status == "hit".

message: Optional short diagnostic used for debugging and tests.

status: str

profile_reaches: dict[str, build_tools.syllable_walk.reach.ReachResult] | None = None

message: str | None = None

ipc_input_hash: str | None = None

ipc_output_hash: str | None = None

class build_tools.syllable_walk_web.services.profile_reaches_cache.ManifestIPCInfo[source]

Canonical IPC fields extracted from one run’s manifest.json.

manifest_version: int

input_hash: str

output_hash: str

build_tools.syllable_walk_web.services.profile_reaches_cache.cache_path(run_dir)[source]

Return canonical cache path for one run directory.

build_tools.syllable_walk_web.services.profile_reaches_cache.read_cached_profile_reach_hashes(run_dir)[source]

Return cache IPC hashes from disk, if present and valid.

This helper is intentionally lightweight and tolerant: malformed or missing cache files simply return (None, None).

build_tools.syllable_walk_web.services.profile_reaches_cache.load_cached_profile_reaches(*, run_dir, run_id, walker)[source]

Read and validate cached profile reaches for a run.

Validation gates: - manifest IPC metadata is present (hash authority) - cache file exists and parses - cache input payload/hash matches current run + walker settings - cache output payload/hash is internally consistent

build_tools.syllable_walk_web.services.profile_reaches_cache.write_cached_profile_reaches(*, run_dir, run_id, walker, profile_reaches)[source]

Write deterministic profile-reach cache for a run.

Returns True when written successfully, else False.