fpf-thinking-map 2.0.1__tar.gz → 2.0.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of fpf-thinking-map might be problematic. Click here for more details.

Files changed (29) hide show
  1. fpf_thinking_map-2.0.3/NOTICE +16 -0
  2. fpf_thinking_map-2.0.3/PKG-INFO +272 -0
  3. fpf_thinking_map-2.0.3/README.md +236 -0
  4. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map/__init__.py +10 -0
  5. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map/agentic_structure.py +2 -0
  6. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map/authorization.py +2 -0
  7. fpf_thinking_map-2.0.3/fpf_thinking_map/checkpoint.py +312 -0
  8. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map/examples.py +2 -0
  9. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map/guards.py +2 -0
  10. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map/logic.py +2 -0
  11. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map/move_intent.py +2 -0
  12. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map/pending_input.py +2 -0
  13. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map/primitives.py +2 -0
  14. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map/reachability.py +2 -0
  15. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map/state.py +35 -0
  16. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map/traversal.py +2 -0
  17. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map/verify.py +129 -0
  18. fpf_thinking_map-2.0.3/fpf_thinking_map.egg-info/PKG-INFO +272 -0
  19. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map.egg-info/SOURCES.txt +1 -0
  20. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/pyproject.toml +2 -2
  21. fpf_thinking_map-2.0.1/NOTICE +0 -36
  22. fpf_thinking_map-2.0.1/PKG-INFO +0 -439
  23. fpf_thinking_map-2.0.1/README.md +0 -403
  24. fpf_thinking_map-2.0.1/fpf_thinking_map.egg-info/PKG-INFO +0 -439
  25. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/LICENSE +0 -0
  26. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map/py.typed +0 -0
  27. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map.egg-info/dependency_links.txt +0 -0
  28. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/fpf_thinking_map.egg-info/top_level.txt +0 -0
  29. {fpf_thinking_map-2.0.1 → fpf_thinking_map-2.0.3}/setup.cfg +0 -0
@@ -0,0 +1,16 @@
1
+ FPF Thinking Map
2
+ ================
3
+
4
+ Copyright (c) 2026 CONSOLIDARE CONTINUUM S.R.L. <info@consolidare-continuum.com>
5
+ GitHub: @Consolidare-Continuum · https://consolidare-continuum.com
6
+
7
+ This runtime is a CONSOLIDARE CONTINUUM product: designed, owned, and published
8
+ for company and client delivery. It is not affiliated with any third-party
9
+ framework project.
10
+
11
+ Scope
12
+ -----
13
+
14
+ Independent traversal runtime with its own design boundaries, verification
15
+ suite, and release line. See docs/DECISIONS_REJECTIONS_ADOPTIONS.md for the
16
+ internal adoption record.
@@ -0,0 +1,272 @@
1
+ Metadata-Version: 2.4
2
+ Name: fpf-thinking-map
3
+ Version: 2.0.3
4
+ Summary: Deterministic Python runtime for lawful agent traversal with explicit state, evidence, authorization, waiting, and move identity.
5
+ Author-email: "CONSOLIDARE CONTINUUM S.R.L." <info@consolidare-continuum.com>
6
+ Maintainer-email: "CONSOLIDARE CONTINUUM S.R.L." <info@consolidare-continuum.com>
7
+ License-Expression: MIT
8
+ Project-URL: Homepage, https://consolidare-continuum.com/fpf-thinking-map/
9
+ Project-URL: Repository, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map
10
+ Project-URL: Documentation, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map#readme
11
+ Project-URL: Issues, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/issues
12
+ Project-URL: Architecture, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/ARCHITECTURE.md
13
+ Project-URL: Changelog, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/CHANGELOG.md
14
+ Project-URL: Contributing, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/CONTRIBUTING.md
15
+ Project-URL: Advisories, https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/blob/main/docs/deep/ADVISORIES.md
16
+ Project-URL: Website, https://consolidare-continuum.com
17
+ Project-URL: GitHub, https://github.com/Consolidare-Continuum
18
+ Project-URL: Telegram, https://t.me/igareosh
19
+ Project-URL: Demo, https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html
20
+ Keywords: agentic,thinking-map,llm,reasoning,propositional-logic,evidence-decay,ttl,guards,gates,semantic-map,fpf,human-in-the-loop,ignition-lock,hitl,safety,authorization,await,move-intent,workflow
21
+ Classifier: Development Status :: 4 - Beta
22
+ Classifier: Intended Audience :: Developers
23
+ Classifier: Intended Audience :: Science/Research
24
+ Classifier: Operating System :: OS Independent
25
+ Classifier: Programming Language :: Python :: 3
26
+ Classifier: Programming Language :: Python :: 3.12
27
+ Classifier: Programming Language :: Python :: 3.13
28
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
29
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
30
+ Classifier: Typing :: Typed
31
+ Requires-Python: >=3.12
32
+ Description-Content-Type: text/markdown
33
+ License-File: LICENSE
34
+ License-File: NOTICE
35
+ Dynamic: license-file
36
+
37
+ # fpf-thinking-map
38
+
39
+ A small Python library that tracks the state of a multi-step agent workflow
40
+ and answers one question: *is this next move allowed right now, and if not,
41
+ why?*
42
+
43
+ You describe a workflow as a graph (contexts, roles, evidence, gates,
44
+ transitions). Your agent harness feeds the library the current state and the
45
+ move the agent proposes. The library returns a legal/illegal outcome with the
46
+ reason and a trace. It does not call a model, run tools, poll, or schedule
47
+ anything.
48
+
49
+ **PyPI:** [`fpf-thinking-map`](https://pypi.org/project/fpf-thinking-map/) · **Current:** **2.0.3** · **License:** MIT
50
+
51
+ [![PyPI](https://img.shields.io/pypi/v/fpf-thinking-map?style=flat-square&label=PyPI)](https://pypi.org/project/fpf-thinking-map/)
52
+ [![Python](https://img.shields.io/pypi/pyversions/fpf-thinking-map?style=flat-square&label=Python)](pyproject.toml)
53
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
54
+
55
+ ## Install
56
+
57
+ Requires **Python ≥ 3.12**. No runtime dependencies.
58
+
59
+ ```bash
60
+ pip install "fpf-thinking-map==2.0.3"
61
+ python -m fpf_thinking_map.verify # the package's own self-tests, 40 checks
62
+ python -m fpf_thinking_map.examples
63
+ ```
64
+
65
+ Other releases on the index: [`2.0.1`](https://pypi.org/project/fpf-thinking-map/2.0.1/), [`2.0.0`](https://pypi.org/project/fpf-thinking-map/2.0.0/), [`1.9.6`](https://pypi.org/project/fpf-thinking-map/1.9.6/).
66
+
67
+ ## Minimal example
68
+
69
+ ```python
70
+ from fpf_thinking_map import (
71
+ SemanticMap,
72
+ ContextPrimitive,
73
+ RolePrimitive,
74
+ GatePrimitive,
75
+ GateCheck,
76
+ TransitionPrimitive,
77
+ RuntimeBinding,
78
+ ThinkingMapTraversal,
79
+ )
80
+
81
+ semantic_map = SemanticMap()
82
+ semantic_map.register_context(ContextPrimitive("deploy", "Deploy"))
83
+ semantic_map.register_role(RolePrimitive("owner", "Owner", "deploy"))
84
+ semantic_map.register_gate(
85
+ GatePrimitive(
86
+ "release_gate",
87
+ "Release gate",
88
+ "deploy",
89
+ checks=[
90
+ GateCheck(
91
+ "tests",
92
+ "Tests are green",
93
+ required_evidence=["test_results"],
94
+ )
95
+ ],
96
+ )
97
+ )
98
+ semantic_map.register_transition(
99
+ TransitionPrimitive(
100
+ "ship",
101
+ "Ship release",
102
+ "deploy",
103
+ "candidate",
104
+ "released",
105
+ required_gate_id="release_gate",
106
+ required_evidence=["test_results"],
107
+ )
108
+ )
109
+
110
+ traversal = ThinkingMapTraversal(semantic_map)
111
+ state = traversal.build_active_state(
112
+ RuntimeBinding(
113
+ task="release",
114
+ actor_role_ids=["owner"],
115
+ active_context_id="deploy",
116
+ current_evidence=["test_results"],
117
+ ),
118
+ current_state="candidate",
119
+ )
120
+
121
+ inspection = traversal.step(state)
122
+ result = traversal.attempt_transition(state, "ship")
123
+ print(inspection.kind, result.kind, state.current_state)
124
+ # OutcomeKind.CONTINUE OutcomeKind.CONTINUE released
125
+ ```
126
+
127
+ Replace the deploy vocabulary with your own contexts, roles, evidence and gates.
128
+
129
+ ## What it does
130
+
131
+ - Holds explicit traversal state: current context, state, and evidence.
132
+ - Checks evidence presence and freshness. Freshness decays over **traversal
133
+ steps**, not wall-clock time.
134
+ - Evaluates gates, guards and transitions and says which moves are legal.
135
+ - Supports cross-context bridges with validated writeback.
136
+ - Supports human authorization (`AuthorizationReceipt`): scoped, non-replayable.
137
+ - Distinguishes waiting on external input (`PendingInput` / `AWAIT`) from idle.
138
+ - Gives a proposed move a concrete identity (`MoveIntent`) that can be inspected.
139
+ - Can checkpoint and restore a paused traversal (`ActiveState.checkpoint()`,
140
+ `from_checkpoint()`); restore is all-or-nothing and never repairs.
141
+
142
+ Given the same map, state, evidence and receipts, it returns the same result.
143
+ The core modules call no clock, random source, network or model.
144
+
145
+ ## Division of work
146
+
147
+ | Agent / host | This library |
148
+ | --- | --- |
149
+ | Interprets the task | Holds explicit traversal state |
150
+ | Generates options | Computes which moves are legal |
151
+ | Collects evidence | Checks presence and freshness |
152
+ | Proposes a move | Inspects or attempts that move |
153
+ | Explains the result | Returns a bounded outcome and trace |
154
+ | Requests human input | Enforces the authorization boundary |
155
+ | Runs tools and jobs | Never executes, polls or schedules them |
156
+
157
+ ## Limits
158
+
159
+ - **It only constrains what is routed through it.** A harness or agent that
160
+ does not call the library is not constrained. There is no sandbox.
161
+ - **State lives in the host process.** The library keeps no storage of its
162
+ own; use `checkpoint()` to persist a paused traversal.
163
+ - **Several inputs are self-asserted.** For example `active_context_id`
164
+ (advisory ADV-03): the harness must own continuity.
165
+ - **Defaults are minimal.** Stale evidence warns but does not block unless a
166
+ gate requires it, and `requires_human_authorization` defaults off.
167
+ - **It is not a universal reasoner,** a vector store, a tool runner or
168
+ scheduler, or a certificate that an agent system is safe.
169
+
170
+ Full list of integrator boundaries: [ADVISORIES.md](docs/deep/ADVISORIES.md).
171
+
172
+ ## What the evidence shows
173
+
174
+ - **Self-tests.** `python -m fpf_thinking_map.verify` (40 checks) and
175
+ `dev_mcp/test_server.py` (45 checks) are written and run by the authors. They
176
+ check that the library does what it is specified to do. They have not been
177
+ audited by a third party.
178
+ - **Does it make agents safer?** One small benchmark exists
179
+ ([bench/RESULTS.md](bench/RESULTS.md)): two tasks, one frontier-model class,
180
+ 5 runs per condition, 20 runs total. The model made **no policy violations
181
+ with or without** the library, so there is **no measured compliance
182
+ improvement** for a cooperative model on a clearly stated task. With the
183
+ library the model made *more* tool calls (4.4 vs 1.0 and 2.0 vs 1.0), because
184
+ it used the inspection calls before acting. Weaker or adversarial models were
185
+ not tested.
186
+ - **ISO.** [docs/ISO_EVIDENCE_PACKET.md](docs/ISO_EVIDENCE_PACKET.md) maps
187
+ release 2.0.1 against ISO/IEC 25010, 27001 and 9001 as a self-assessed
188
+ checklist. It is **not** an audit and **not** a certification.
189
+
190
+ ## Shipped structures
191
+
192
+ | Concern | Structures | Effect |
193
+ | --- | --- | --- |
194
+ | Claim / assurance | `ContextSlice`, `ClaimScope`, `FormalityLevel`, `ReliabilityPath` | Typed scope; unknown stays unknown |
195
+ | Tool plans | `CallPlanPrimitive`, `BudgetEnvelope` | Incomplete plans → `REVISE_PLAN` |
196
+ | Autonomy | `AutonomyBudgetDecl`, `AutonomyLedgerEntry` | Opt-in budget; failure → `ESCALATE` |
197
+ | Work attribution | `WorkPrimitive.performed_under` | Wrong holder/context cannot complete |
198
+ | Gate join | `GateDecision`, `OutcomeCause` | `ABSTAIN` ≠ `BLOCK` (`cause=gate_block`) |
199
+ | Map integrity | `ThinkingMapTraversal.validate_map()` | Dangling refs / unknown IDs fail closed |
200
+ | Adjacency (2.0) | `AdjacencyClearanceRule`, `AdjacentlyCleared` | A confirmed-absent percept clears declared neighbours |
201
+ | Continuity (2.0.2) | `ActiveState.checkpoint()`, `from_checkpoint()` | Persist and restore a paused traversal |
202
+
203
+ ### Gate join
204
+
205
+ | Gate result | Meaning | Typical outcome |
206
+ | --- | --- | --- |
207
+ | `ABSTAIN` (`insufficient`) | Not enough basis to say yes | `COLLECT_EVIDENCE` when evidence is declared |
208
+ | `BLOCK` | Declared policy says no for this evaluation | Denied with `cause=GATE_BLOCK` |
209
+
210
+ `BLOCK` is hard for that evaluation; it is not automatically permanent. Checks
211
+ opt into `BLOCK` with `failure_decision=GateDecision.BLOCK`.
212
+
213
+ ## Demo
214
+
215
+ [Four interactive traces](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
216
+ (evidence recovery, `AWAIT`, `MoveIntent` with authorization, `ABSTAIN` vs
217
+ `BLOCK`). They follow behavior covered by the test suite as of v1.9.5; they are
218
+ not a recording of a live model run and do not show later features.
219
+
220
+ ## Releases
221
+
222
+ | Line | Change |
223
+ | --- | --- |
224
+ | v1.0–v1.5 | Primitives, TTL, bridges, stagnation, stable public boundary |
225
+ | v1.6–v1.8 | Human authorization, receipts, `AWAIT` |
226
+ | v1.9 / 1.9.5 | Move identity; A.21 gate join (`ABSTAIN` vs `BLOCK`) |
227
+ | v1.9.6 | Failed-run revert terminal (XOR + distance bound) |
228
+ | v2.0.0 | Adjacency clearance (`ADV-17`) |
229
+ | v2.0.1 | Docs and metadata only; runtime identical to 2.0.0 |
230
+ | v2.0.2 | Copyright and SPDX notices on every source file (license unchanged); includes traversal checkpoint and restore (`ADV-08`) |
231
+ | **v2.0.3** | Docs and metadata only; runtime identical to 2.0.2. Removes the upstream-intake advisory (`ADV-16`) and every named reference to the external specification this package was historically informed by; independence disclaimer reworded |
232
+
233
+ History: [VERSION_TRACKER.md](docs/VERSION_TRACKER.md) · [CHANGELOG.md](CHANGELOG.md) · [Releases](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/releases)
234
+
235
+ ## Integrator notes
236
+
237
+ | Priority | Advisory | One line |
238
+ | --- | --- | --- |
239
+ | Sharp | **ADV-03** | `active_context_id` is self-asserted: the harness must own continuity |
240
+ | Sharp | **ADV-07** | `RiskAbove` string match is case-sensitive and fails silently |
241
+ | Common | **ADV-01** | Stale evidence warns; it does not block unless gated |
242
+ | Common | **ADV-10** | `requires_human_authorization` defaults off |
243
+ | 2.0 | **ADV-17** | Adjacency clearance is only as sound as your declared biconditional |
244
+
245
+ MCP test harness: [`dev_mcp/`](dev_mcp/) (`run_scenario`, `get_advisories`, `run_verify`).
246
+
247
+ ## Repository
248
+
249
+ | Path | Purpose |
250
+ | --- | --- |
251
+ | [`fpf_thinking_map/`](fpf_thinking_map/) | The runtime (no dependencies) |
252
+ | [ARCHITECTURE.md](ARCHITECTURE.md) | Control flow |
253
+ | [docs/deep/ADVISORIES.md](docs/deep/ADVISORIES.md) | Integrator boundaries |
254
+ | [bench/](bench/) | The ablation benchmark and its raw results |
255
+ | [SHA256SUMS](SHA256SUMS) | Source file checksums |
256
+
257
+ ## License and ownership
258
+
259
+ MIT. Copyright (c) 2026 CONSOLIDARE CONTINUUM S.R.L.
260
+
261
+ Copyrighted build: release **2.0.2**, commit
262
+ [`f0a17a543a23cbc8a33071b170a02ccf41fd33b7`](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/commit/f0a17a543a23cbc8a33071b170a02ccf41fd33b7)
263
+ (signed tag `v2.0.2`). Every source file in that commit carries the copyright
264
+ and SPDX notice.
265
+
266
+ The MIT license requires
267
+ that the copyright notice and license text be kept in copies and substantial
268
+ portions of the software; see [LICENSE](LICENSE) and [NOTICE](NOTICE).
269
+
270
+ This is an independent implementation, out of scope of and not derived from
271
+ any third-party framework's document or ontology. It is not affiliated
272
+ with, sponsored by, or endorsed by any such project.
@@ -0,0 +1,236 @@
1
+ # fpf-thinking-map
2
+
3
+ A small Python library that tracks the state of a multi-step agent workflow
4
+ and answers one question: *is this next move allowed right now, and if not,
5
+ why?*
6
+
7
+ You describe a workflow as a graph (contexts, roles, evidence, gates,
8
+ transitions). Your agent harness feeds the library the current state and the
9
+ move the agent proposes. The library returns a legal/illegal outcome with the
10
+ reason and a trace. It does not call a model, run tools, poll, or schedule
11
+ anything.
12
+
13
+ **PyPI:** [`fpf-thinking-map`](https://pypi.org/project/fpf-thinking-map/) · **Current:** **2.0.3** · **License:** MIT
14
+
15
+ [![PyPI](https://img.shields.io/pypi/v/fpf-thinking-map?style=flat-square&label=PyPI)](https://pypi.org/project/fpf-thinking-map/)
16
+ [![Python](https://img.shields.io/pypi/pyversions/fpf-thinking-map?style=flat-square&label=Python)](pyproject.toml)
17
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
18
+
19
+ ## Install
20
+
21
+ Requires **Python ≥ 3.12**. No runtime dependencies.
22
+
23
+ ```bash
24
+ pip install "fpf-thinking-map==2.0.3"
25
+ python -m fpf_thinking_map.verify # the package's own self-tests, 40 checks
26
+ python -m fpf_thinking_map.examples
27
+ ```
28
+
29
+ Other releases on the index: [`2.0.1`](https://pypi.org/project/fpf-thinking-map/2.0.1/), [`2.0.0`](https://pypi.org/project/fpf-thinking-map/2.0.0/), [`1.9.6`](https://pypi.org/project/fpf-thinking-map/1.9.6/).
30
+
31
+ ## Minimal example
32
+
33
+ ```python
34
+ from fpf_thinking_map import (
35
+ SemanticMap,
36
+ ContextPrimitive,
37
+ RolePrimitive,
38
+ GatePrimitive,
39
+ GateCheck,
40
+ TransitionPrimitive,
41
+ RuntimeBinding,
42
+ ThinkingMapTraversal,
43
+ )
44
+
45
+ semantic_map = SemanticMap()
46
+ semantic_map.register_context(ContextPrimitive("deploy", "Deploy"))
47
+ semantic_map.register_role(RolePrimitive("owner", "Owner", "deploy"))
48
+ semantic_map.register_gate(
49
+ GatePrimitive(
50
+ "release_gate",
51
+ "Release gate",
52
+ "deploy",
53
+ checks=[
54
+ GateCheck(
55
+ "tests",
56
+ "Tests are green",
57
+ required_evidence=["test_results"],
58
+ )
59
+ ],
60
+ )
61
+ )
62
+ semantic_map.register_transition(
63
+ TransitionPrimitive(
64
+ "ship",
65
+ "Ship release",
66
+ "deploy",
67
+ "candidate",
68
+ "released",
69
+ required_gate_id="release_gate",
70
+ required_evidence=["test_results"],
71
+ )
72
+ )
73
+
74
+ traversal = ThinkingMapTraversal(semantic_map)
75
+ state = traversal.build_active_state(
76
+ RuntimeBinding(
77
+ task="release",
78
+ actor_role_ids=["owner"],
79
+ active_context_id="deploy",
80
+ current_evidence=["test_results"],
81
+ ),
82
+ current_state="candidate",
83
+ )
84
+
85
+ inspection = traversal.step(state)
86
+ result = traversal.attempt_transition(state, "ship")
87
+ print(inspection.kind, result.kind, state.current_state)
88
+ # OutcomeKind.CONTINUE OutcomeKind.CONTINUE released
89
+ ```
90
+
91
+ Replace the deploy vocabulary with your own contexts, roles, evidence and gates.
92
+
93
+ ## What it does
94
+
95
+ - Holds explicit traversal state: current context, state, and evidence.
96
+ - Checks evidence presence and freshness. Freshness decays over **traversal
97
+ steps**, not wall-clock time.
98
+ - Evaluates gates, guards and transitions and says which moves are legal.
99
+ - Supports cross-context bridges with validated writeback.
100
+ - Supports human authorization (`AuthorizationReceipt`): scoped, non-replayable.
101
+ - Distinguishes waiting on external input (`PendingInput` / `AWAIT`) from idle.
102
+ - Gives a proposed move a concrete identity (`MoveIntent`) that can be inspected.
103
+ - Can checkpoint and restore a paused traversal (`ActiveState.checkpoint()`,
104
+ `from_checkpoint()`); restore is all-or-nothing and never repairs.
105
+
106
+ Given the same map, state, evidence and receipts, it returns the same result.
107
+ The core modules call no clock, random source, network or model.
108
+
109
+ ## Division of work
110
+
111
+ | Agent / host | This library |
112
+ | --- | --- |
113
+ | Interprets the task | Holds explicit traversal state |
114
+ | Generates options | Computes which moves are legal |
115
+ | Collects evidence | Checks presence and freshness |
116
+ | Proposes a move | Inspects or attempts that move |
117
+ | Explains the result | Returns a bounded outcome and trace |
118
+ | Requests human input | Enforces the authorization boundary |
119
+ | Runs tools and jobs | Never executes, polls or schedules them |
120
+
121
+ ## Limits
122
+
123
+ - **It only constrains what is routed through it.** A harness or agent that
124
+ does not call the library is not constrained. There is no sandbox.
125
+ - **State lives in the host process.** The library keeps no storage of its
126
+ own; use `checkpoint()` to persist a paused traversal.
127
+ - **Several inputs are self-asserted.** For example `active_context_id`
128
+ (advisory ADV-03): the harness must own continuity.
129
+ - **Defaults are minimal.** Stale evidence warns but does not block unless a
130
+ gate requires it, and `requires_human_authorization` defaults off.
131
+ - **It is not a universal reasoner,** a vector store, a tool runner or
132
+ scheduler, or a certificate that an agent system is safe.
133
+
134
+ Full list of integrator boundaries: [ADVISORIES.md](docs/deep/ADVISORIES.md).
135
+
136
+ ## What the evidence shows
137
+
138
+ - **Self-tests.** `python -m fpf_thinking_map.verify` (40 checks) and
139
+ `dev_mcp/test_server.py` (45 checks) are written and run by the authors. They
140
+ check that the library does what it is specified to do. They have not been
141
+ audited by a third party.
142
+ - **Does it make agents safer?** One small benchmark exists
143
+ ([bench/RESULTS.md](bench/RESULTS.md)): two tasks, one frontier-model class,
144
+ 5 runs per condition, 20 runs total. The model made **no policy violations
145
+ with or without** the library, so there is **no measured compliance
146
+ improvement** for a cooperative model on a clearly stated task. With the
147
+ library the model made *more* tool calls (4.4 vs 1.0 and 2.0 vs 1.0), because
148
+ it used the inspection calls before acting. Weaker or adversarial models were
149
+ not tested.
150
+ - **ISO.** [docs/ISO_EVIDENCE_PACKET.md](docs/ISO_EVIDENCE_PACKET.md) maps
151
+ release 2.0.1 against ISO/IEC 25010, 27001 and 9001 as a self-assessed
152
+ checklist. It is **not** an audit and **not** a certification.
153
+
154
+ ## Shipped structures
155
+
156
+ | Concern | Structures | Effect |
157
+ | --- | --- | --- |
158
+ | Claim / assurance | `ContextSlice`, `ClaimScope`, `FormalityLevel`, `ReliabilityPath` | Typed scope; unknown stays unknown |
159
+ | Tool plans | `CallPlanPrimitive`, `BudgetEnvelope` | Incomplete plans → `REVISE_PLAN` |
160
+ | Autonomy | `AutonomyBudgetDecl`, `AutonomyLedgerEntry` | Opt-in budget; failure → `ESCALATE` |
161
+ | Work attribution | `WorkPrimitive.performed_under` | Wrong holder/context cannot complete |
162
+ | Gate join | `GateDecision`, `OutcomeCause` | `ABSTAIN` ≠ `BLOCK` (`cause=gate_block`) |
163
+ | Map integrity | `ThinkingMapTraversal.validate_map()` | Dangling refs / unknown IDs fail closed |
164
+ | Adjacency (2.0) | `AdjacencyClearanceRule`, `AdjacentlyCleared` | A confirmed-absent percept clears declared neighbours |
165
+ | Continuity (2.0.2) | `ActiveState.checkpoint()`, `from_checkpoint()` | Persist and restore a paused traversal |
166
+
167
+ ### Gate join
168
+
169
+ | Gate result | Meaning | Typical outcome |
170
+ | --- | --- | --- |
171
+ | `ABSTAIN` (`insufficient`) | Not enough basis to say yes | `COLLECT_EVIDENCE` when evidence is declared |
172
+ | `BLOCK` | Declared policy says no for this evaluation | Denied with `cause=GATE_BLOCK` |
173
+
174
+ `BLOCK` is hard for that evaluation; it is not automatically permanent. Checks
175
+ opt into `BLOCK` with `failure_decision=GateDecision.BLOCK`.
176
+
177
+ ## Demo
178
+
179
+ [Four interactive traces](https://consolidare-continuum.github.io/fpf-agentic-thinking-map/demos/three-runs.html)
180
+ (evidence recovery, `AWAIT`, `MoveIntent` with authorization, `ABSTAIN` vs
181
+ `BLOCK`). They follow behavior covered by the test suite as of v1.9.5; they are
182
+ not a recording of a live model run and do not show later features.
183
+
184
+ ## Releases
185
+
186
+ | Line | Change |
187
+ | --- | --- |
188
+ | v1.0–v1.5 | Primitives, TTL, bridges, stagnation, stable public boundary |
189
+ | v1.6–v1.8 | Human authorization, receipts, `AWAIT` |
190
+ | v1.9 / 1.9.5 | Move identity; A.21 gate join (`ABSTAIN` vs `BLOCK`) |
191
+ | v1.9.6 | Failed-run revert terminal (XOR + distance bound) |
192
+ | v2.0.0 | Adjacency clearance (`ADV-17`) |
193
+ | v2.0.1 | Docs and metadata only; runtime identical to 2.0.0 |
194
+ | v2.0.2 | Copyright and SPDX notices on every source file (license unchanged); includes traversal checkpoint and restore (`ADV-08`) |
195
+ | **v2.0.3** | Docs and metadata only; runtime identical to 2.0.2. Removes the upstream-intake advisory (`ADV-16`) and every named reference to the external specification this package was historically informed by; independence disclaimer reworded |
196
+
197
+ History: [VERSION_TRACKER.md](docs/VERSION_TRACKER.md) · [CHANGELOG.md](CHANGELOG.md) · [Releases](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/releases)
198
+
199
+ ## Integrator notes
200
+
201
+ | Priority | Advisory | One line |
202
+ | --- | --- | --- |
203
+ | Sharp | **ADV-03** | `active_context_id` is self-asserted: the harness must own continuity |
204
+ | Sharp | **ADV-07** | `RiskAbove` string match is case-sensitive and fails silently |
205
+ | Common | **ADV-01** | Stale evidence warns; it does not block unless gated |
206
+ | Common | **ADV-10** | `requires_human_authorization` defaults off |
207
+ | 2.0 | **ADV-17** | Adjacency clearance is only as sound as your declared biconditional |
208
+
209
+ MCP test harness: [`dev_mcp/`](dev_mcp/) (`run_scenario`, `get_advisories`, `run_verify`).
210
+
211
+ ## Repository
212
+
213
+ | Path | Purpose |
214
+ | --- | --- |
215
+ | [`fpf_thinking_map/`](fpf_thinking_map/) | The runtime (no dependencies) |
216
+ | [ARCHITECTURE.md](ARCHITECTURE.md) | Control flow |
217
+ | [docs/deep/ADVISORIES.md](docs/deep/ADVISORIES.md) | Integrator boundaries |
218
+ | [bench/](bench/) | The ablation benchmark and its raw results |
219
+ | [SHA256SUMS](SHA256SUMS) | Source file checksums |
220
+
221
+ ## License and ownership
222
+
223
+ MIT. Copyright (c) 2026 CONSOLIDARE CONTINUUM S.R.L.
224
+
225
+ Copyrighted build: release **2.0.2**, commit
226
+ [`f0a17a543a23cbc8a33071b170a02ccf41fd33b7`](https://github.com/Consolidare-Continuum/fpf-agentic-thinking-map/commit/f0a17a543a23cbc8a33071b170a02ccf41fd33b7)
227
+ (signed tag `v2.0.2`). Every source file in that commit carries the copyright
228
+ and SPDX notice.
229
+
230
+ The MIT license requires
231
+ that the copyright notice and license text be kept in copies and substantial
232
+ portions of the software; see [LICENSE](LICENSE) and [NOTICE](NOTICE).
233
+
234
+ This is an independent implementation, out of scope of and not derived from
235
+ any third-party framework's document or ontology. It is not affiliated
236
+ with, sponsored by, or endorsed by any such project.
@@ -1,3 +1,5 @@
1
+ # Copyright (c) 2026 CONSOLIDARE CONTINUUM S.R.L. <info@consolidare-continuum.com>
2
+ # SPDX-License-Identifier: MIT
1
3
  """FPF Thinking Map — compiled semantic substrate for agentic traversal.
2
4
 
3
5
  A structured board for LLM reasoning: the model navigates a pre-shaped
@@ -41,6 +43,14 @@ from fpf_thinking_map.authorization import (
41
43
  issue_authorization_receipt,
42
44
  )
43
45
 
46
+ # --- Checkpoint: supported round trip for a paused traversal (ADV-08) ---
47
+ from fpf_thinking_map.checkpoint import (
48
+ CheckpointError,
49
+ InvalidCheckpointState,
50
+ MapFingerprintMismatch,
51
+ UnsupportedCheckpointVersion,
52
+ )
53
+
44
54
  # --- Guards: deterministic hard constraints ---
45
55
  from fpf_thinking_map.guards import (
46
56
  Guard,
@@ -1,3 +1,5 @@
1
+ # Copyright (c) 2026 CONSOLIDARE CONTINUUM S.R.L. <info@consolidare-continuum.com>
2
+ # SPDX-License-Identifier: MIT
1
3
  """Agentic structures whose semantics must remain explicit at runtime.
2
4
 
3
5
  This module is deliberately smaller than the upstream patterns it responds to.
@@ -1,3 +1,5 @@
1
+ # Copyright (c) 2026 CONSOLIDARE CONTINUUM S.R.L. <info@consolidare-continuum.com>
2
+ # SPDX-License-Identifier: MIT
1
3
  """Authorization receipts — a human's yes, scoped to the exact state it was given for.
2
4
 
3
5
  `attempt_transition(state, "publish", authorized=True)` is an ambient boolean: