fpf-thinking-map 1.9.2__tar.gz → 1.9.3__tar.gz

{fpf_thinking_map-1.9.2/fpf_thinking_map.egg-info → fpf_thinking_map-1.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fpf-thinking-map
-Version: 1.9.2
+Version: 1.9.3
 Summary: Deterministic Python runtime for lawful agent traversal with explicit state, evidence, authorization, waiting, and move identity.
 Author-email: "igareosh.com (@igareosh)" <igareosh@igareosh.com>
 Maintainer-email: "igareosh.com (@igareosh)" <igareosh@igareosh.com>

{fpf_thinking_map-1.9.2 → fpf_thinking_map-1.9.3}/fpf_thinking_map/__init__.py

@@ -15,6 +15,7 @@ Modules:
   pending_input — declared external dependencies distinguishing AWAIT from IDLE
   move_intent   — a concrete proposed move, distinct from its transition type
   examples      — deploy decision scenarios demonstrating the full system
+  reachability  — discrete reachability analysis over a map's transition graph
   verify        — self-verification harness
 """
 
@@ -95,3 +96,10 @@ from fpf_thinking_map.pending_input import PendingInput, PendingInputStatus
 
 # --- Move intent: concrete proposed move, distinct from transition type ---
 from fpf_thinking_map.move_intent import MoveIntent
+
+# --- Reachability: discrete reachability analysis over the transition graph ---
+from fpf_thinking_map.reachability import (
+    forward_reachable,
+    graph_roots,
+    unreachable_transitions,
+)

fpf_thinking_map-1.9.3/fpf_thinking_map/reachability.py

@@ -0,0 +1,109 @@
+"""Discrete reachability analysis over a SemanticMap's declared transition graph.
+
+A SemanticMap's transitions form exactly the object M. J. Kochenderfer, S. M.
+Katz, A. L. Corso, and R. J. Moss describe in *Algorithms for Validation*
+(MIT Press, 2026), ch. 10, "Reachability for Discrete Systems": a directed
+graph, one node per state, one edge per transition. Their algorithm 10.1
+(build the graph) and 10.3 (backward/forward reachable sets) are cheap at the
+scale a hand-authored domain map actually runs at -- tens of transitions, not
+thousands -- so there is no excuse for skipping them in favor of hand-picked
+test cases that only exercise the paths someone happened to think of.
+
+What this module answers: given the transitions a map declares, is every
+from_state either a named entry point or produced by some other transition's
+to_state? A from_state that is neither is either (a) the map's intentional
+starting point for a bounded context -- the caller sets current_state there
+directly, e.g. because real-world work upstream of this map already happened
+-- or (b) an orphaned typo nobody meant to leave unreachable. This module
+cannot tell those apart on its own, and does not try to: entry_states is a
+required argument, not inferred, because a map's real entry points are a
+domain fact, not something derivable from the graph.
+
+Origin story (see check_reachability in verify.py for the worked example):
+a downstream domain map gave a requires_human_authorization transition its
+own dedicated from_state, distinct from its non-destructive twin's. Read cold,
+that dedicated from_state looked unreachable -- nothing in the map produced
+it -- and the obvious "fix" (merge it onto the twin's shared from_state) broke
+four behavior tests, because ThinkingMapTraversal.step() called without an
+explicit transition_id aggregates missing_evidence across every transition
+sharing a from_state, not just the one the caller meant. The state genuinely
+was meant to be entered from outside the graph; the actual defect was that
+nothing recorded that on purpose. entry_states exists so that fact is written
+down once, in code, instead of being tribal knowledge someone has to
+rediscover by breaking tests.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from fpf_thinking_map.primitives import TransitionPrimitive
+from fpf_thinking_map.state import SemanticMap
+
+__all__ = ["graph_roots", "forward_reachable", "unreachable_transitions"]
+
+
+def graph_roots(transitions: Iterable[TransitionPrimitive]) -> set[str]:
+    """States that no declared transition's to_state ever produces.
+
+    Every state in the returned set is either an intentional entry point
+    or an orphaned from_state -- this function makes no claim about which.
+    Useful for auditing a map you didn't author: it's the candidate list
+    to sort into "yes, callers arrive here directly" and "nobody meant
+    this," by hand, once, rather than rediscovering it via a break like
+    the one described in this module's docstring.
+    """
+    transitions = list(transitions)
+    produced = {t.to_state for t in transitions}
+    consumed = {t.from_state for t in transitions}
+    return consumed - produced
+
+
+def forward_reachable(
+    transitions: Iterable[TransitionPrimitive],
+    entry_states: Iterable[str],
+) -> set[str]:
+    """States reachable from entry_states by following declared to_state edges.
+
+    Plain BFS over the (from_state -> to_state) graph -- algorithm 10.1's
+    graph formulation, forward direction. At domain-map scale (tens of
+    edges) this is microseconds; there is no reason to approximate it.
+    """
+    transitions = list(transitions)
+    edges: dict[str, list[str]] = {}
+    for t in transitions:
+        edges.setdefault(t.from_state, []).append(t.to_state)
+
+    seen = set(entry_states)
+    frontier = list(seen)
+    while frontier:
+        s = frontier.pop()
+        for nxt in edges.get(s, []):
+            if nxt not in seen:
+                seen.add(nxt)
+                frontier.append(nxt)
+    return seen
+
+
+def unreachable_transitions(
+    sm: SemanticMap,
+    entry_states: Iterable[str],
+) -> list[TransitionPrimitive]:
+    """Transitions whose from_state is unreachable given the declared entry points.
+
+    entry_states must be supplied explicitly. Omitting a state that a
+    caller genuinely does set current_state to directly is not a bug in
+    this function -- it is the intended failure mode, surfacing every
+    undeclared entry point by name instead of silently accepting it. See
+    check_reachability in verify.py for both directions demonstrated: the
+    library's own build_destructive_action_map() example map is clean when
+    "reviewed" is declared as an entry point, and loudly not clean when it
+    isn't.
+
+    Returns transitions in registration order (dict-ordered, matching
+    SemanticMap.transitions), not sorted -- callers building error messages
+    generally want map-declaration order, not alphabetical.
+    """
+    transitions = list(sm.transitions.values())
+    reachable = forward_reachable(transitions, entry_states)
+    return [t for t in transitions if t.from_state not in reachable]

{fpf_thinking_map-1.9.2 → fpf_thinking_map-1.9.3}/fpf_thinking_map/verify.py

@@ -15,12 +15,14 @@ import traceback
 from fpf_thinking_map.examples import (
     build_deploy_decision_map,
     build_deploy_rules,
+    build_destructive_action_map,
     run_logic_scenario,
     run_scenario_full_traversal,
     run_scenario_missing_evidence,
     run_scenario_role_conflict,
     run_truth_table_demo,
 )
+from fpf_thinking_map.reachability import unreachable_transitions
 from fpf_thinking_map.authorization import (
     AuthorizationReceipt,
     compute_state_fingerprint,
@@ -1680,6 +1682,62 @@ def check_move_intent():
     )
 
 
+def check_reachability():
+    """Discrete reachability over a map's declared transition graph (val.pdf ch.10).
+
+    Worked example, both directions, using the library's own canonical
+    destructive-move map (build_destructive_action_map): delete_records and
+    archive_records both declare from_state="reviewed", which is nobody's
+    to_state in this map — callers arrive at "reviewed" from outside (a
+    dry-run happened upstream), the same shape as the case that motivated
+    this module (see reachability.py's docstring for the full story: an
+    unreachable-looking from_state turned out to be an intentional external
+    entry point, and the "obvious" fix of merging it onto a shared from_state
+    broke four behavior tests by changing what missing_evidence aggregates
+    across).
+
+    entry_states is required, not inferred, precisely so that mistake isn't
+    repeatable: declaring "reviewed" as an entry point is a one-line,
+    reviewable statement of intent instead of something a reachability walk
+    has to guess at.
+    """
+    sm = build_destructive_action_map()
+
+    # declared correctly: "reviewed" is a named entry point, nothing is
+    # unreachable
+    dead = unreachable_transitions(sm, entry_states={"reviewed"})
+    assert not dead, f"unexpected unreachable transitions: {[t.transition_id for t in dead]}"
+
+    # omit the entry point on purpose: the check's whole job is to make an
+    # undeclared entry point loud, not to silently let it through. All three
+    # transitions rooted at "reviewed" must come back.
+    undeclared = unreachable_transitions(sm, entry_states=set())
+    undeclared_ids = {t.transition_id for t in undeclared}
+    assert undeclared_ids == {"delete_records", "archive_records", "log_status"}, undeclared_ids
+
+    # a genuinely orphaned transition — from_state nobody produces and
+    # nobody declared as an entry point — must still be caught even when a
+    # real entry point is declared correctly
+    sm2 = build_destructive_action_map()
+    sm2.register_transition(TransitionPrimitive(
+        transition_id="orphan_move",
+        label="Unreachable by construction — nothing produces 'nowhere'",
+        context_id="data_ops",
+        from_state="nowhere",
+        to_state="deleted",
+    ))
+    orphaned = unreachable_transitions(sm2, entry_states={"reviewed"})
+    assert [t.transition_id for t in orphaned] == ["orphan_move"], (
+        [t.transition_id for t in orphaned]
+    )
+    assert orphaned[0].requires_human_authorization is False, (
+        "orphan_move isn't gated — reachability catches dead transitions "
+        "regardless of whether they happen to be destructive; it is not a "
+        "substitute for requires_human_authorization, it is a separate check "
+        "on a separate property (can the graph get here at all)"
+    )
+
+
 def main():
     print("FPF Thinking Map — Self-verification (horizontal)")
     print("=" * 55)
@@ -1711,6 +1769,7 @@ def main():
         ("authorization receipt (scoped, non-replayable, TOCTOU-safe)", check_authorization_receipt),
         ("pending input / AWAIT (distinct from IDLE)", check_pending_input_await),
         ("move intent / inspect_move (concrete move identity)", check_move_intent),
+        ("reachability (discrete graph analysis, val.pdf ch.10)", check_reachability),
     ]
 
     passed = sum(check(name, fn) for name, fn in checks)

{fpf_thinking_map-1.9.2 → fpf_thinking_map-1.9.3/fpf_thinking_map.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fpf-thinking-map
-Version: 1.9.2
+Version: 1.9.3
 Summary: Deterministic Python runtime for lawful agent traversal with explicit state, evidence, authorization, waiting, and move identity.
 Author-email: "igareosh.com (@igareosh)" <igareosh@igareosh.com>
 Maintainer-email: "igareosh.com (@igareosh)" <igareosh@igareosh.com>

{fpf_thinking_map-1.9.2 → fpf_thinking_map-1.9.3}/fpf_thinking_map.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ fpf_thinking_map/move_intent.py
 fpf_thinking_map/pending_input.py
 fpf_thinking_map/primitives.py
 fpf_thinking_map/py.typed
+fpf_thinking_map/reachability.py
 fpf_thinking_map/state.py
 fpf_thinking_map/traversal.py
 fpf_thinking_map/verify.py

{fpf_thinking_map-1.9.2 → fpf_thinking_map-1.9.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fpf-thinking-map"
-version = "1.9.2"
+version = "1.9.3"
 description = "Deterministic Python runtime for lawful agent traversal with explicit state, evidence, authorization, waiting, and move identity."
 readme = "README.md"
 license = "MIT"