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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fpf-thinking-map
-Version: 1.9.2
+Version: 1.9.4
 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>
@@ -49,7 +49,7 @@ context. The model can inspect the map and choose; the runtime decides whether
 the move is valid.
 
 [![PyPI](https://img.shields.io/pypi/v/fpf-thinking-map?style=flat-square&label=PyPI&color=3775A9)](https://pypi.org/project/fpf-thinking-map/)
-[![Downloads (honest)](https://img.shields.io/badge/downloads%20%28honest%29-3.8k-1f6feb?style=flat-square)](https://pypistats.org/packages/fpf-thinking-map)
+[![Downloads (honest)](https://img.shields.io/badge/downloads%20%28honest%29-4k-1f6feb?style=flat-square)](https://pypistats.org/packages/fpf-thinking-map)
 [![Python](https://img.shields.io/pypi/pyversions/fpf-thinking-map?style=flat-square&label=Python&color=f0b429)](https://github.com/igareosh/fpf-agentic-thinking-map/blob/main/pyproject.toml)
 [![License](https://img.shields.io/pypi/l/fpf-thinking-map?style=flat-square&label=license&color=57c7bd)](https://github.com/igareosh/fpf-agentic-thinking-map/blob/main/LICENSE)
 [![Zero dependencies](https://img.shields.io/badge/dependencies-0-ff9f43?style=flat-square)](https://github.com/igareosh/fpf-agentic-thinking-map/blob/main/pyproject.toml)

{fpf_thinking_map-1.9.2 → fpf_thinking_map-1.9.4}/README.md

@@ -13,7 +13,7 @@ context. The model can inspect the map and choose; the runtime decides whether
 the move is valid.
 
 [![PyPI](https://img.shields.io/pypi/v/fpf-thinking-map?style=flat-square&label=PyPI&color=3775A9)](https://pypi.org/project/fpf-thinking-map/)
-[![Downloads (honest)](https://img.shields.io/badge/downloads%20%28honest%29-3.8k-1f6feb?style=flat-square)](https://pypistats.org/packages/fpf-thinking-map)
+[![Downloads (honest)](https://img.shields.io/badge/downloads%20%28honest%29-4k-1f6feb?style=flat-square)](https://pypistats.org/packages/fpf-thinking-map)
 [![Python](https://img.shields.io/pypi/pyversions/fpf-thinking-map?style=flat-square&label=Python&color=f0b429)](https://github.com/igareosh/fpf-agentic-thinking-map/blob/main/pyproject.toml)
 [![License](https://img.shields.io/pypi/l/fpf-thinking-map?style=flat-square&label=license&color=57c7bd)](https://github.com/igareosh/fpf-agentic-thinking-map/blob/main/LICENSE)
 [![Zero dependencies](https://img.shields.io/badge/dependencies-0-ff9f43?style=flat-square)](https://github.com/igareosh/fpf-agentic-thinking-map/blob/main/pyproject.toml)

{fpf_thinking_map-1.9.2 → fpf_thinking_map-1.9.4}/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.2 → fpf_thinking_map-1.9.4}/fpf_thinking_map/primitives.py

@@ -438,6 +438,35 @@ class TransitionPrimitive:
     does — the engine only makes the
     option visible, it never picks one. Whether an alternative actually
     satisfies the goal is a domain judgment outside this library's scope.
+
+    guard_expression: names a DecisionRule (fpf_thinking_map.logic) that
+    must currently recommend *this* transition_id for the fire to
+    proceed unopposed — the routing-policy counterpart to
+    required_gate_id/required_evidence. Checked in
+    ThinkingMapTraversal.attempt_transition(), not by the guard engine
+    despite the name (guards.py stays pure ActiveState predicates; a
+    LogicLayer reference only ThinkingMapTraversal can resolve doesn't
+    belong there).
+
+    Deliberately not an ESCALATE: a routing-policy mismatch is not
+    "needs a human," it's "the map disagrees with the proposed move and
+    knows what it would prefer instead" — the same shape as
+    COLLECT_EVIDENCE, not requires_human_authorization. Fires
+    REVISE_PLAN (declared in OutcomeKind since the traversal engine's
+    outcome space was first drawn up, never previously returned by any
+    code path) with the rule's actual current recommendation in
+    Outcome.alternatives, so an agentic caller can retry the recommended
+    transition_id in the same turn — solution-seeking stays inside the
+    map's own vocabulary, no external tool, no waiting on a person.
+
+    Silent no-op, matching required_gate_id's existing convention for a
+    dangling reference, when: no logic_layer is bound on the traversal,
+    the named rule doesn't exist in it, or the rule currently has no
+    active recommendation at all (condition false with no
+    action_if_false, or a HINT/WARN rule's vacuous-implication
+    suppression) — "the policy has no opinion right now" defaults to
+    allow, same as not setting guard_expression at all. Only an active
+    recommendation for a *different* transition_id blocks.
     """
     transition_id: str
     label: str

fpf_thinking_map-1.9.4/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.4}/fpf_thinking_map/traversal.py

@@ -451,6 +451,33 @@ class ThinkingMapTraversal:
                         missing_evidence=gate.missing_evidence(state.available_evidence_ids),
                     )
 
+        if t.guard_expression and self.logic_layer:
+            rule = next(
+                (r for r in self.logic_layer.rules if r.name == t.guard_expression),
+                None,
+            )
+            # dangling rule name: same silent no-op as an unresolved
+            # required_gate_id above — a missing reference doesn't block.
+            if rule:
+                _, recommended = rule.evaluate(state)
+                # no active recommendation right now ("" from a false
+                # condition with no action_if_false, or vacuous HINT/WARN
+                # suppression) means the policy has no opinion — allow,
+                # same as guard_expression being unset. Only a *different*
+                # active recommendation blocks.
+                if recommended and recommended != transition_id:
+                    reason = (
+                        f"Transition '{transition_id}' does not match routing policy "
+                        f"'{rule.name}' — policy currently recommends '{recommended}'"
+                    )
+                    if rule.explanation:
+                        reason += f": {rule.explanation}"
+                    return Outcome(
+                        kind=OutcomeKind.REVISE_PLAN,
+                        reason=reason,
+                        alternatives=[recommended],
+                    )
+
         allowed, guard_results = self.guard_engine.is_action_allowed(state, transition_id)
         if not allowed:
             denials = [r.reason for r in guard_results if r.verdict == GuardVerdict.DENY]

{fpf_thinking_map-1.9.2 → fpf_thinking_map-1.9.4}/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,154 @@ 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 check_route_gated_transition():
+    """guard_expression -> DecisionRule: routing-policy legality, agentic
+
+    not human-facing. A transition naming a DecisionRule via
+    guard_expression only fires when that rule's current recommendation
+    matches the attempted transition_id — mismatches return REVISE_PLAN
+    (never ESCALATE: no human is asked, nothing is added to
+    pending_authorizations) with the rule's actual recommendation in
+    alternatives, so an agentic caller retries in the same turn, inside
+    the map's own vocabulary."""
+    sm = SemanticMap()
+    sm.register_context(ContextPrimitive("cis", "Compound Intelligence Stack"))
+    sm.register_transition(TransitionPrimitive(
+        "route_local", "route to local/open tier", "cis",
+        "control_plane", "local_open", guard_expression="escalation_policy",
+    ))
+    sm.register_transition(TransitionPrimitive(
+        "route_frontier", "escalate to frontier oracle", "cis",
+        "control_plane", "frontier", guard_expression="escalation_policy",
+    ))
+
+    logic = LogicLayer()
+    logic.add_rule(DecisionRule(
+        name="escalation_policy", condition=RiskAbove("high"),
+        action_if_true="route_frontier", action_if_false="route_local",
+        explanation="routine load stays local; frontier is the rare escalation",
+        kind=RuleKind.ROUTE,
+    ))
+    engine = ThinkingMapTraversal(sm, logic_layer=logic)
+
+    # normal risk: policy recommends route_local. Attempting the
+    # mismatched transition does not fire it, and — the whole point —
+    # does not touch pending_authorizations the way an ESCALATE would.
+    s_normal = engine.build_active_state(
+        RuntimeBinding(active_context_id="cis", risk_level="normal"),
+        current_state="control_plane",
+    )
+    o_mismatch = engine.attempt_transition(s_normal, "route_frontier")
+    assert o_mismatch.kind == OutcomeKind.REVISE_PLAN, o_mismatch.kind
+    assert o_mismatch.kind != OutcomeKind.ESCALATE, (
+        "a routing-policy mismatch must never read as 'needs a human'"
+    )
+    assert o_mismatch.alternatives == ["route_local"], o_mismatch.alternatives
+    assert "escalation_policy" in o_mismatch.reason
+    assert s_normal.current_state == "control_plane", "mismatch must not move state"
+    assert s_normal.pending_authorizations == set(), (
+        "REVISE_PLAN is not an authorization ask — nothing pending for a human"
+    )
+
+    # the matching transition at the same state fires normally
+    o_match = engine.attempt_transition(s_normal, "route_local")
+    assert o_match.kind == OutcomeKind.CONTINUE, o_match.kind
+    assert s_normal.current_state == "local_open"
+
+    # high risk: policy now recommends route_frontier instead. Attempting
+    # the now-wrong default gets REVISE_PLAN naming the correct one —
+    # and the caller can retry it immediately, autonomously, same turn.
+    s_high = engine.build_active_state(
+        RuntimeBinding(active_context_id="cis", risk_level="high"),
+        current_state="control_plane",
+    )
+    o_wrong_tier = engine.attempt_transition(s_high, "route_local")
+    assert o_wrong_tier.kind == OutcomeKind.REVISE_PLAN, o_wrong_tier.kind
+    assert o_wrong_tier.alternatives == ["route_frontier"], o_wrong_tier.alternatives
+    assert s_high.current_state == "control_plane"
+
+    o_retry = engine.attempt_transition(s_high, o_wrong_tier.alternatives[0])
+    assert o_retry.kind == OutcomeKind.CONTINUE, (
+        "the model's own retry, using exactly what REVISE_PLAN handed back, "
+        f"must succeed — got {o_retry.kind}"
+    )
+    assert s_high.current_state == "frontier"
+
+    # dangling reference / no logic_layer bound: same silent no-op as an
+    # unresolved required_gate_id — backward compatible with maps that
+    # never opted into routing policy at all
+    sm2 = SemanticMap()
+    sm2.register_context(ContextPrimitive("cis2", "Test"))
+    sm2.register_transition(TransitionPrimitive(
+        "t_a", "A", "cis2", "start", "mid", guard_expression="no_such_rule",
+    ))
+    engine_no_logic = ThinkingMapTraversal(sm2)  # no logic_layer at all
+    s2 = engine_no_logic.build_active_state(
+        RuntimeBinding(active_context_id="cis2"), current_state="start",
+    )
+    o2 = engine_no_logic.attempt_transition(s2, "t_a")
+    assert o2.kind == OutcomeKind.CONTINUE, (
+        f"a dangling guard_expression with no bound logic_layer must not "
+        f"block — got {o2.kind}"
+    )
+
+
 def main():
     print("FPF Thinking Map — Self-verification (horizontal)")
     print("=" * 55)
@@ -1711,6 +1861,8 @@ 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),
+        ("route-gated transition (guard_expression -> DecisionRule, REVISE_PLAN not ESCALATE)", check_route_gated_transition),
     ]
 
     passed = sum(check(name, fn) for name, fn in checks)

{fpf_thinking_map-1.9.2 → fpf_thinking_map-1.9.4/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.4
 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>
@@ -49,7 +49,7 @@ context. The model can inspect the map and choose; the runtime decides whether
 the move is valid.
 
 [![PyPI](https://img.shields.io/pypi/v/fpf-thinking-map?style=flat-square&label=PyPI&color=3775A9)](https://pypi.org/project/fpf-thinking-map/)
-[![Downloads (honest)](https://img.shields.io/badge/downloads%20%28honest%29-3.8k-1f6feb?style=flat-square)](https://pypistats.org/packages/fpf-thinking-map)
+[![Downloads (honest)](https://img.shields.io/badge/downloads%20%28honest%29-4k-1f6feb?style=flat-square)](https://pypistats.org/packages/fpf-thinking-map)
 [![Python](https://img.shields.io/pypi/pyversions/fpf-thinking-map?style=flat-square&label=Python&color=f0b429)](https://github.com/igareosh/fpf-agentic-thinking-map/blob/main/pyproject.toml)
 [![License](https://img.shields.io/pypi/l/fpf-thinking-map?style=flat-square&label=license&color=57c7bd)](https://github.com/igareosh/fpf-agentic-thinking-map/blob/main/LICENSE)
 [![Zero dependencies](https://img.shields.io/badge/dependencies-0-ff9f43?style=flat-square)](https://github.com/igareosh/fpf-agentic-thinking-map/blob/main/pyproject.toml)

{fpf_thinking_map-1.9.2 → fpf_thinking_map-1.9.4}/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.4}/pyproject.toml

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