Architecture comparison: evidence record

Revisions examined

The other pages pin the rewrite at 9be7804 (Sep 24). Seven source commits since then change behavior discussed here: cecc6d1 (game decisions gain indeterminate; explain reports unknown truth), de62694 (calculated effect times), 6d6a9a9 (circular story-time questions stop as EXHAUSTED), 2e0c386 (candidate fluents scoped to each requested time), 33cd9a9 (strict game checks), c736a1b (circular timeline sources) and 828c0fe (timeline preparation shares request limits). They touch api/affordance.py, engine.py, errors.py, solve/context.py, temporal/calculus.py and temporal/timeline.py; the reader, bindings, program, solver, tabling, built-ins and analysis are unchanged since 9be7804.

Method

• Code. Source was read at the pinned commits with git show <commit>:<path>. Line numbers below are at those commits. Each engine's own architecture notes and migration map were used as starting points and checked against the code; drift found is listed below.
• Isolation. Each engine's src/ was exported with git archive <commit> src into a scratch folder, and probes imported only the export. Runs used CPython 3.12.10 on Windows 11 with PYTHONDONTWRITEBYTECODE=1 and python -B; nothing was installed. PyYAML 6.0.3 came from the interpreter's site-packages. Afterwards git status --porcelain was empty in both repositories and no file in either checkout was newer than the probe inputs.
• Determinism. Every matched probe ran under PYTHONHASHSEED 0, 1 and 2. The seed changes the iteration order of sets of strings, so a result that depended on that order would differ between seeds. Answers, decisions, statuses, notes, errors, standard output and trace sizes were identical across the three seeds for both engines.
• Call paths. A read-only recorder registered a Python 3.12 sys.monitoring callback for function entry (not generator resumption) and recorded the first-entry order, call counts and nearest in-package caller. Two read-only hooks read arguments and in-progress sets on entry to the story-time evaluators. No engine code was edited or monkey-patched.
• Test suites. Each engine's suite was run on an isolated export (git archive of src, tests and the files its tests read), never in the repository, because the earlier suite's configuration writes test_logs/ and .pytest_cache/ where it runs. Results are under measurements.
• Timings. The matched-probe timings are single runs and support no claim. The one timing the page uses, the change-cost measurement, was taken separately on September 29 as medians of 25 runs, repeated under three hash seeds. Function-entry counts from traces describe one engine's path and are not compared across engines, because the code bases divide work into functions differently.
• Earlier-stage probes. Some claims come from single-engine probes run the same day with the same isolation; they are listed separately.
• Revision-stage probes. Reviewer counterexamples were re-run on September 29 on fresh exports with the same isolation; they are listed separately. Their scripts and raw output are in the JSON under revision_stage_2026_09_29.
• Review-round-2 probes. The second accuracy review's counterexamples were re-run the same day on new exports, under three hash seeds; they are listed separately, with script and output in the JSON under review_round_2_2026_09_29.
• Review-round-3 probes. Two claims from the third accuracy review were re-run the same day on a new export of the rewrite, under three hash seeds; they are listed separately, with scripts and output in the JSON under review_round_3_2026_09_29.

Detail behind each page section

The Architecture page was cut twice on September 29, 2026: first to a shorter read, after which the second review round returned some qualifications to it in short form, then, aiming at a five-minute read, to a page of at most 1,300 words of visible prose, with each comparison reduced to a table row (what is shared, what differs, one symbol per engine) and one or two sentences of consequence (review record). Review round 3 then corrected that cut within the same word limits. The fuller detail is kept here, one heading per page section, in page order, each linking back to its section, with pointers to the probe tables and source map below. Nothing here is new evidence: the markings are the page's own (In the code, read in source at the pinned commits; Observed, from the probes in this record; What it means, interpretation).

Scope and layering

Page section: Who does each job.

• Shared. The same core jobs, one per row of Figure 1.
• In the code. Besides the kernel, the earlier src/kb/ holds a command-line game and a rooms game, gameplay modules, an ontology validator, metrics, structured logging and a legacy facade (core.py, the original CyclopsStormKB API). "Legacy" is the engine's own word, for that API and for its original rule evaluator, the Legacy evaluator. The rewrite's package is the kernel plus a host boundary (api/); its tests, including a differential suite that runs the earlier engine for comparison, live outside the package. Its modules import only downward, and tests/architecture/test_boundaries.py enforces the order: terms at the bottom, then the reader and bindings, clause storage, analysis and the per-request context, the solver and timeline, story time, and the facade on top. The solver never imports story time. It reaches holds_at through the built-in table the facade assembles, and holds_at calls the solver back; that runtime recursion is Figure 1's dashed arrow, and the earlier engine has the same two-way calls between its Legacy evaluator and its temporal package. No layering test was found in the earlier engine.
• Observed. The legacy facade answers queries from stored facts only and has its own story-time check (core.py:323), with immediate rather than delayed effects: a rule-based question the main engine answered yes got no answer there. The probe is in single-engine probes.
• What it means, in full. The earlier scope is real, but its applications don't exercise its main reasoner; a game adopting the rewrite builds those layers itself.
• Paths and line numbers: source map, row "Scope". What was kept, changed and omitted: Migration.

The traced request

Page section: One question, asked of both.

• In the code. In both engines decide is built from ordinary queries, so game hooks sit on the query API: is the action offered at this site (once(affords(...))), what are its guards (guard/4, all answers), then once(Condition) for each guard in order until one fails. That is three queries for the lab door and four for the tunnel's two guards. Figure 2 traces the condition asked directly, can_enter(lab), on a fresh engine. Earlier: KBEngine.query → QueryExecutionPipeline → HandlerRegistry → Reasoner.evaluate_derived → RoutingFSM.decide → LegacyDerivedEvaluator → FluentEvaluator.holds_at. Rewrite: KnowledgeBase.ask → _refresh → solve → built-in table → holds_at → _explain. Every function entered, with line numbers, is under request path.
• Observed. Under the delayed-effect reading the door is open at t1 and closed from t2. Each clock value went into a fresh engine, because the earlier KBEngine has no retract method, so no mutation happened between requests. All eight goals and both decisions are under ordinary success; they include when the lab is locked (t2 and t3 in both).
• Difference case. The page's one difference case keeps the lab story with now(t0) and adds a second guard, reachable(corridor, lab), over a tunnel of n passage/2 segments (probe inputs). It was built to cross the earlier engine's depth cap of 50, not to be typical. Earlier decide: allow at 10 segments; allow at 50, with one warning on standard output (a search past the lab hit the cap); deny, "You cannot find a way to the laboratory.", from 51 to 60, with two warnings each. Rewrite: allow, complete, at every length; at 60 segments, a 200-step budget gives indeterminate with status exhausted, and a cancel gives indeterminate with status cancelled. Tables: when evaluation can't finish; what it shows: limits, statuses and cancellation.

Terms and clause storage

Page section: Terms and storage.

• Shared. Immutable terms, numbered variables, a trail (a log of bindings to undo when backtracking), and facts and rules that answer together.
• In the code. The earlier engine converts between two term formats (reader output in core_types.py, engine terms in kb_core/model.py) and has two unifiers (unify/unifier.py, backtracking.py). It files facts by predicate name in FactStore, story facts in side indexes keyed by event text, and rules in a separate RuleCompiler. The rewrite has five term types (terms.py), one binding store (bindings.py) and one clause list per predicate (program.py).
• Observed. The variable-effect and rule-effect probes, and the code that explains them, are under input-design check; the rule form also works in the rewrite (round-2 probes).
• What it means, in full. In the earlier engine, how an effect is written decides which store handles it; in the rewrite a story fact is an ordinary clause, found by unification (binding variables so two terms match). The rewrite's cost is speed, not measured here: with no story indexes, story-time lookups try each earlier time point.

Routing, built-ins and recursion

Page section: Running a query.

• Shared. SLD resolution with backtracking, cut and negation as failure, similar built-ins, automatic tabling of recursion, and unknown predicates that quietly fail.
• In the code. The earlier pipeline picks a handler by predicate name (engine/query/registry.py), so a built-in's handler also captures user predicates of that name. The router (RoutingFSM.decide in routing.py) then sends derived goals to the depth-first (DFS) engine or to the Legacy evaluator, using a process-wide allowlist of names (child, person, sibling). The engine records the route it took in last_route. The rewrite has one generator, solve (solve/machine.py), for typed queries and rule bodies alike; after any change it analyzes the whole program, tables every recursive group and checks cuts and negation through recursion (solve/analysis.py).
• What it means, in full. The rewrite's answers depend only on the program, its Options (occurs check, tie-break policy, exclusive fluents, unknown predicates, automatic tabling) and the request's limits, apart from the generated names of unbound variables (see state held between requests).
• Observed. Under the head human/1, a rule body over 12,000 facts went to the Legacy evaluator: 10 answers. Renamed to the allowlisted person/1, it went to the DFS engine, whose iteration budget ran out silently: none. holds_at(in(player, corridor), T) answered when typed, but not inside a one-line rule, which reaches a different holds_at that needs a bound time. These name-dependence and entry-path probes, and the name-capture probes, are under single-engine probes.
• What it means, for the earlier engine. Its answers can also depend on names, entry path and process-wide state, though it records the route taken (last_route).

Mutable state and caches

Page section: Mutable state.

• Shared. Clauses live on the engine object for its whole life, and both engines build a per-query object, confusingly both named QueryContext.
• In the code. The earlier QueryContext holds only pipeline bookkeeping. Evaluation state lives on engine-lifetime objects: answer tables and a derived-result cache, cleared when the next query starts, and caches of holds_at answers and whole results, invalidated when facts are added (the result cache also expires after 300 seconds). The routing allowlist and loggers are process-wide. The rewrite's QueryContext (solve/context.py) holds all evaluation state and is dropped after the call. Between requests the knowledge base keeps its clauses and revision counter (Program), a first-argument index per predicate, and the analysis and timeline for that revision (DerivedState); the last three are rebuilt after a change. A request also touches process-wide state: it raises Python's recursion limit for the call, numbers variables from a global counter, and interns any atom it creates in a module-level table (terms.py:165) that every knowledge base in the process shares and nothing empties. Atom names therefore outlive the request, though they don't change answers (round-3 probes).
• Observed. The rewrite left no QueryContext alive and returned a new frozen result each time. The earlier engine's cache returned the list it had stored, so a caller that appended to it changed the next answer. That is a missing copy rather than a cost of caching: a deep-copying repeat was still fast in an earlier measurement. Object-level detail is under state held between requests; timings under change-cost measurement.
• What it means, in full. With its cache, the earlier engine's repeats were about 6 times faster than the rewrite's on the lab story (0.011 against 0.07 ms), and about 100 times faster on an earlier measurement's query. Caching speeds the earlier engine's repeats, but correctness depends on every invalidation agreeing, and engines in one process aren't independent: two instances shared one routing registry. The rewrite carries no answers between requests (Figure 2), but any change, even advancing now/1, costs a whole-program reanalysis, which the request's budget doesn't meter, and a timeline rebuild; both grow with the program. Neither engine is designed for concurrent use: the earlier one made a partial start, with thread-local query state and some locks; the rewrite has neither, and each call raises Python's process-wide recursion limit until it returns.

Story time and the timeline

Page section: Story time.

• Shared. The Event Calculus vocabulary (initially, happens, initiates, terminates, holds_at), the delayed-effect reading, time ordered by before/2 links, effect rules written as ordinary rules, exclusive fluents declared with exclusive_fluent/1, a tie-break option for a fluent started and stopped at the same moment, and runtime calls in both directions between story-time evaluation and the solver.
• In the code. The earlier engine files story facts into temporal stores as they load and has several holds_at implementations, chosen by entry path. It works event-first: find the events before the queried time, then ask what they affect (FluentEvaluator). Seven fluent names are always exclusive (exclusivity.py); the rewrite makes those seven opt-in. The rewrite has one holds_at (temporal/calculus.py). Its facade builds the timeline once per revision by running time/1, before/2 and happens/2 through the solver and closing the order transitively (KnowledgeBase._build_timeline); when effect rules compute their own times, holds_at builds an enlarged copy for that request only. It works rule-first: at each earlier time point, solve the effect rules, then check that the event happened.
• Observed. In the self-referential probe the earlier engine never needed the rule, because stored effect facts settle each question first; had it needed the rule, its re-entry guard would have answered "false" without reporting a cycle. A paradoxical variant without the ordinary lock, where no answer is consistent, shows the guard at work: the earlier engine answered yes at t1, t2 and t3, printing nothing, and the rewrite reported exhausted. Given before/2 or happens/2 defined by rules, the earlier timeline ignored them (the door stayed open and was never locked) and the rewrite answered correctly. Both probes are under round-2 probes. With the time written in the rule's head, terminates(auto_lock(lab), door_open(lab), t1) :- …, the rewrite answers t1, while t2 and t3 stay open. Tables, traces and the rewrite's note are under when evaluation can't finish.
• What it means, in full. The rewrite's timeline, read through the solver, honors rules that define before/2 or happens/2, but is rebuilt after every change, and some answerable circular questions stay open, depending on how an effect is written (the three-argument form above answers t1). The earlier timeline updates cheaply while loading, but only from facts: given such rules, it never locked the door.

Limits, statuses and cancellation

Page section: Can't finish.

• In the code. The earlier limits are module constants (engine/constants.py), such as recursion depth 50 in the Legacy evaluator. Hitting one returns the answers found so far as an ordinary list; a warning may be printed to standard output, but nothing reaches the caller, and KBEngine.query takes only the query text. The rewrite applies Limits per request (default 2,000,000 steps, depth 1,200) and polls the host's cancel callback every 512 steps (solve/context.py). Timeline preparation counts against the request's budget; whole-program analysis doesn't. A result is complete, exhausted (a budget ran out, or a circular question was stopped) or cancelled (result status); ask returns the answers found so far with the status; query raises IncompleteResult, where the earlier query returns the partial list; decide turns any status but complete into the decision indeterminate, not enabled (api/affordance.py); and spans_for returns a plain list without a status, so partial provenance looks complete. If a budget or cancel stops preparation, nothing is kept and the next request prepares again; a before/2 clause that raises is recorded instead, and story-time answers that depend on it are marked exhausted.
• In the code: analysis conflicts. A cut in any recursive predicate, or negation through recursion, makes every query on that knowledge base raise SemanticConflict, unrelated ones included, until the program changes (see How it works, known gaps). Loading succeeds; decide reports the conflict as indeterminate, with the error in its notes.
• Observed. The tunnel sweeps (10 segments, and every length from 44 to 60), the warnings printed, the budget and cancel calls, and the preparation and conflict probes are under when evaluation can't finish and revision-stage probes. The rewrite has limits too, and reports hitting them.
• Observed: unknown predicates. In both engines, by default, a guard built on an undefined or unsupported predicate (a typo, or catch/3, which the rewrite doesn't have) fails and refuses the player; the rewrite marks that decision complete. With unknown_fails=False the rewrite returns indeterminate, naming the predicate in its notes (round-2 probes; How it works, known gaps, first row).
• What it means, in full. On the earlier engine a game can't tell "no" from "gave up" or bound a request, and in the tunnel (built to cross the cap, not to be typical) the player got a false refusal. On the rewrite a game must handle partial answers and indeterminate. Budgets apply to each of decide's queries rather than to the whole decision, so a 200-step budget allows 200 steps for each of the four queries the tunnel's two guards need, and cancellation is cooperative, with no wall-clock deadline.

Explanations and provenance

Page section: Explanations.

• In the code. The earlier why/1, derivation/1 and evidence_chain/1 cover rule-derived facts as well as story time, but separate code builds them: derived explanations re-run the goal on the Legacy evaluator, bypassing the router (provenance_handlers.py). The rewrite's explain is the procedure that answers holds_at (_holds returns _explain(...).holds is True), so the two can't disagree, but it covers story time only. Both find source text through authored fact_id/2 and supports/2 facts; the earlier engine also has source/2.
• Observed. With now(t0), the earlier why(can_enter(lab)) returned the rule and its bindings, which the rewrite can't. With now(t2), the earlier why(can_enter(lab)) found no derivation and why(holds_at(door_open(lab), t2)) returned does_not_hold with no cause. Every request and answer is under explanations.
• What it means, in full. For "why can't I?", neither engine explains a failed rule, and only the rewrite names the event that ended the fluent. A game composes that reason from the decision's condition, its message and explain on the fluents inside the condition, not on the condition itself: explain treats any term as a fluent, so on a rule head such as can_enter(lab) it returns a misleading "never initiated", complete, even when the rule succeeds (explanations). For "why can I?", the earlier engine's answer is richer, but separate code builds it, so explanation and answer could disagree; the rewrite's can't.

Host integration and extension

Page section: Host and extension.

• Shared. In-process Python APIs, JSON, and the same game hooks: allow, deny, and abstain when an action isn't offered at a site.
• Results. Earlier: a list of dictionaries. Rewrite: a frozen Solutions with answers, status and notes; spans_for returns a plain list. Shapes are under state held between requests.
• Extension. Earlier: register a handler by name, edit the routing allowlist, or set environment flags; a registered handler answers a single goal typed at the top level, but not a rule body or a conjunction. A user fact such as length(rope, 5) is hidden by the built-in's handler. Rewrite: write clauses; built-ins are fixed, a clause for a built-in's name is refused at load, and there is no API for host-computed predicates.
• Changing facts. Earlier: add-only; snapshots cover the fact store only. Rewrite: assert_ and retract between queries; snapshots cover the whole program.
• Authoring feedback. Earlier: warnings for variables used only once, and syntax errors with a code and suggestions, on by default. Rewrite: syntax errors with a line and column; its documentation lists an authoring analyzer (singletons, unused predicates, arity) as deferred. It records some warnings on kb.diagnostics without printing them: an effect at a time nothing orders (engine.py:808), a time order derived from holds_at/2 (engine.py:741) and an ignored directive (program.py:447; round-2 probes).
• What it means, in full. In both engines, values the game computes must in practice be asserted as facts, because an earlier handler doesn't reach rule bodies and the rewrite has no API for host-computed predicates; in the rewrite each assert is a change that pays the reanalysis and timeline rebuild (mutable state).
• Observed. In the earlier engine, a handler registered for weight/2 answered weight(crate, W) but not weight(crate, W), W > 10 or a rule calling it, so a guard built on such a rule refused the player. The handler, name-capture, snapshot, built-in refusal and authoring probes are under single-engine probes and revision-stage probes.

Limits of the comparison

Page section: What this comparison can't tell you. Apart from the change-cost timing, timings are single runs on one machine and aren't used, and trace call counts aren't compared across engines (method). The earlier suite's 20 failures and errors all need the hypothesis package; the author's log recorded 6,660 passed by August 30 (measurements).

Probe inputs

The shared story, loaded as identical bytes into a fresh engine of each kind. The comment on its second line refers to the probe stage's working notes, which this page summarizes; SHA-256 hashes of every input are in the JSON.

% Shared story: may the player enter the laboratory after the door is locked?
% Identical input for both engines. Effect axioms are ground facts (see RESULTS.md).
time(t0). time(t1). time(t2). time(t3).
before(t0, t1). before(t1, t2). before(t2, t3).

initially(door_open(lab)).
happens(lock_door(lab), t1).
terminates(lock_door(lab), door_open(lab)).
initiates(lock_door(lab), locked(lab)).

can_enter(R) :- now(T), holds_at(door_open(R), T).

affords(enter_lab, corridor).
guard(enter_lab, 1, can_enter(lab), 'The laboratory door is locked.').
action_label(enter_lab, 'enter the laboratory').

Loaded after it, each as a separate text with the engine's ordinary load call (e.add(text) or kb.load(text)):

• Clock: now(t2). or now(t0)., each into a fresh engine. No mutation happened between requests, because the earlier KBEngine has no retract method.
• Tunnel of n segments: guard(enter_lab, 2, reachable(corridor, lab), 'You cannot find a way to the laboratory.')., the rules reachable(A, B) :- passage(A, B). and reachable(A, B) :- passage(A, C), reachable(C, B)., and n facts passage(corridor, tunnel1), …, passage(tunnelN-1, lab). Probed at n = 10, 60 and every value from 44 to 56 in the matched set, and every value from 50 to 60 in both engines during revision.
• Self-referential effect: happens(auto_lock(lab), t1). and terminates(auto_lock(lab), door_open(lab)) :- holds_at(door_open(lab), t3). During revision, also the three-argument spelling terminates(auto_lock(lab), door_open(lab), t1) :- holds_at(door_open(lab), t3). in the rewrite.
• Input-design check: the story with its two effect facts written as terminates(lock_door(R), door_open(R)). and initiates(lock_door(R), locked(R)).

Probe results

Ordinary success

Request path for the first can_enter(lab) after loading

Functions entered, in first-entry order, with the line where each is defined (from the traced code objects). Paths are relative to src/.

Earlier engine (route recorded as LEGACY / default):

1. KBEngine.query kb/engine/kb_engine.py:748 → QueryExecutionPipeline.execute kb/engine/query/pipeline/pipeline.py:70
2. Stages under kb/engine/query/pipeline/stages/: CacheLookupStage.process cache_lookup_stage.py:37 (miss in PerformanceManager.get_cached_result, kb/engine/performance.py:153); ValidationStage.process validation_stage.py:26; ParsingStage.process parsing_stage.py:38, which calls TableManager.clear kb/engine/tabling/table_manager.py:563; RoutingStage.process routing_stage.py:24 → HandlerRegistry.get_handler_or_default kb/engine/query/registry.py:108; ExecutionStage.process execution_stage.py:26 → GeneralPredicateHandler.handle kb/engine/query/query_handlers.py:938
3. Reasoner.evaluate_derived kb/engine/reasoning/reasoner.py:768 → QueryCache.get_derived_result kb/engine/query_cache.py:130 (miss) → QueryAnalyzer.analyze kb/routing.py:282 → RoutingFSM.decide kb/routing.py:453 → EngineRouter.eval_with_engine kb/engine/routing/engine_router.py:99 → LegacyDerivedEvaluator.evaluate_with_special_cases kb/engine/derived_evaluation/legacy_evaluator.py:416 → DerivedEvaluationTemplate.evaluate kb/engine/derived_evaluation/template.py:44 → _check_recursion legacy_evaluator.py:63 → BodyEvaluationCoordinator.evaluate_with_strategies kb/engine/evaluation/body_coordinator.py:57 → Reasoner._evaluate_literal reasoner.py:1225 (twice)
4. Reasoner._evaluate_holds_at_literal reasoner.py:1374 → Reasoner.holds_at reasoner.py:705 → FluentEvaluator.holds_at kb/engine/reasoning/temporal/fluent_evaluator.py:96 → _compute_holds_at :164 → PersistenceEvaluator._is_terminated_before persistence.py:243 → TemporalReasoner.lt_time temporal_reasoner.py:58 (7 calls; reachability built lazily by _compute_reachability :277)
5. QueryCache.cache_derived_result query_cache.py:158; ProjectionStage.process projection_stage.py:25 → PerformanceManager.cache_result performance.py:147; MetricsStage.process metrics_stage.py:30. The host receives [].

Rewrite:

1. KnowledgeBase.ask cyclops/engine.py:339 → _run :384 → _context :646 → QueryContext.__init__ cyclops/solve/context.py:92
2. KnowledgeBase._refresh engine.py:668 (revision changed): analyse cyclops/solve/analysis.py:114; a second, bootstrap QueryContext sharing the request's budget; KnowledgeBase._build_timeline engine.py:815 → build_timeline cyclops/temporal/timeline.py:120; DerivedState published
3. solve cyclops/solve/machine.py:42 → resolve_clauses machine.py:275 → built-in table (machine.py:123; table assembled at engine.py:60) → holds_at cyclops/temporal/calculus.py:671
4. prepare_effect_times timeline.py:306 → _holds calculus.py:487 → _explain calculus.py:548 → _starts_and_stops :404 → _effects :204 (4 calls, each back into solve) → _clipped :469 → Timeline.precedes timeline.py:92
5. _run maps exceptions and ctx.status to a status (engine.py:430-462) and returns Solutions(answers=(), status=COMPLETE). On a fresh knowledge base this first request reports 103 steps, depth 5, because timeline preparation is charged to it; the same query repeated reports 22 (re-measured during revision; the draft of this record paired the cold trace with the warm count). ask("once(can_enter(lab))"), the form decide sends, reports 104 when cold.

One decide sent three KBEngine.query calls in the earlier engine and three KnowledgeBase.ask calls in the rewrite, which built four QueryContext objects: one per call plus one bootstrap. The three are the action (once(affords(enter_lab, corridor))), its guards (guard/4, all answers) and one once(Condition) per guard until one fails, so the count grows with the guards: the tunnel's two-guard decide sent four (affordance.py:178-199).

State held between requests

Returned objects: in the earlier engine a second identical query("holds_at(locked(lab), T)") returned the same list object as the first, and that object was the value stored in the pipeline cache. That is a missing defensive copy, not a property of caching: the evidence overview measured a deep-copying repeat at 0.008 ms against 0.004 ms. In the rewrite each ask returned a new frozen Solutions whose answers are a tuple. Two separate KBEngine instances shared one routing registry and one structured logger. Process-wide state the rewrite touches per request: ask raises sys.setrecursionlimit for the call and restores it afterwards (engine.py:376-382; 1000 before and after in the probe), and variable numbers come from a module-level counter (terms.py:109), so non-ground answers get different variable names on each identical request (mk(X) gave f(_G22), then f(_G24)). Atoms are interned in a module-level dictionary (terms.py:165) that only grows: an atom first created by a request stays after it (round-3 probes).

Result shapes: the earlier query returns list of dict, with compound values as internal terms (Term('locked', (Term('lab', ()),))); its Decision.as_json has action, kind, enabled, condition, message. The rewrite's ask returns Solutions(goal, answers, status, notes, steps, depth) with values such as Struct('locked', (Atom('lab'),)); query() returns [{'F': locked('lab')}]; its Decision adds order, status and notes.

When evaluation can't finish

Public signatures, read with inspect.signature: earlier KBEngine.query(self, query_str: str) -> List[Dict[str, Any]], decide(engine, action, site=None), affordances(engine, site). Rewrite KnowledgeBase.ask(self, goal, *, limits=None, distinct=True, cancel=None), explain(self, fluent, when, *, limits=None, cancel=None); decide and affordances also take limits and cancel. Limits() defaults: 2,000,000 steps, depth 1,200, no answer limit.

Rewrite only, 60 segments, on a knowledge base warmed by one ask("true") (82 steps, nearly all timeline preparation; whole-program analysis is not metered, because analyse(program, *, auto_table) takes no step callback, and cancellation is checked only before and after it). The decide sub-queries took 3, 3, 8 and 729 steps at default limits.

Self-referential effect rule (now(t2)), each ask order (t3,t2,t1, t2,t3,t1, t1,t2,t3) on a fresh engine:

With the effect written in three-argument form, terminates(auto_lock(lab), door_open(lab), t1) :- holds_at(door_open(lab), t3). (no happens/2 needed), the rewrite answered t1 complete with one answer in both ask orders, left t2 and t3 exhausted, and decide stayed indeterminate. The difference: the two-argument rule's body runs before it is joined to happens/2, as the rewrite's docs/LIMITATIONS.md says.

The rewrite's note: "holds_at(door_open(lab), t3) is defined in terms of itself at the same time point; circular temporal evaluation stopped without assuming true or false." Traces: the earlier FluentEvaluator.holds_at was entered once per question and its rule-effect lookup (WeakReasonerMixin.evaluate_causal_rules) never, so the self-referential rule never ran. The rewrite's _explain was entered for (door_open, t1), then (door_open, t3), then (door_open, t3) again, which found its key in progress and raised TemporalCycle. The rewrite's docs/LIMITATIONS.md at 5d598de describes the case under "Time-scoped candidates do not reorder rule bodies". Why the earlier engine never ran the rule: PersistenceEvaluator._is_terminated_before (persistence.py:243) checks stored termination facts first and returns as soon as one precedes the queried time, which the lock_door fact does for t2 and t3; for t1 no event precedes it. Its own cycle guard (fluent_evaluator.py:133-137, which returns false) is code-verified but was not reached. The single consistent answer, which the earlier engine gives, is open at t1 and closed at t2 and t3: the ordinary lock closes the door whatever the rule does, so the rule's condition is false.

Explanations

At the boundary tick both engines say door_open(lab) holds at t1 because it held initially; for locked(lab) at t1 the earlier engine says does_not_hold and the rewrite never_initiated. Neither says the lock takes effect after t1.

Which code produced what: the earlier answer came from HoldsAtHandler.handle (query_handlers.py:172) → Reasoner.holds_at → FluentEvaluator.holds_at. Its temporal why came from WhyHandler (kb/engine/query/provenance_handlers.py:89) → _explain_temporal (:169), which calls Reasoner.holds_at for the verdict and builds a positive reason from a separate scan of stored facts whose time test (:205) also accepts an initiation at the queried time; no divergence was observed in this story. Its derived why (_explain_derived, :226) called LegacyDerivedEvaluator.evaluate_with_special_cases directly and did not enter the router. In the rewrite, ask and KnowledgeBase.explain (engine.py:505) both reach calculus._explain (:548); _holds (:487) is _explain(...).holds is True.

Input-design check: effect facts with variables

The earlier engine files effects under the event's text (FactStore.add_termination(event: str, fluent), kb/engine/storage.py:168) and finds an effect's time by looking that text up in event_time_map (get_event_time, :223; used in persistence.py:249-253). No happens/2 fact has the text lock_door(R), so the effect is skipped without an error. The rewrite solves effect goals with unification (_effects, calculus.py:204). The shared story therefore writes its effect facts ground.

Written as rules, terminates(lock_door(R), door_open(R)) :- room(R). and initiates(lock_door(R), locked(R)) :- room(R). with room(lab)., the same effects work in the earlier engine (revision stage): holds_at(door_open(lab), t2) → [], holds_at(locked(lab), T) → t2, t3. Its rule-effect path (WeakReasonerMixin.evaluate_causal_rules) unifies; only the fact path is keyed by text.

Single-engine probes cited on the page

Revision-stage probes

Run on September 29, 2026 on fresh git archive exports of both pinned commits, with PYTHONDONTWRITEBYTECODE=1, python -B and PYTHONHASHSEED=0; each answers a reviewer's counterexample or a reader's question. Scripts and raw output: the JSON, key revision_stage_2026_09_29.

Review-round-2 probes

Run on September 29, 2026 on new git archive exports of both pinned commits, with PYTHONDONTWRITEBYTECODE=1 and python -B, under PYTHONHASHSEED 0, 1 and 2; each engine's output was identical across the seeds. Each checks a counterexample from the second accuracy review. Script and raw output: the JSON, key review_round_2_2026_09_29.

Review-round-3 probes

Run on September 29, 2026 on a new git archive export of the rewrite at 5d598de, with PYTHONDONTWRITEBYTECODE=1 and python -B, under PYTHONHASHSEED 0, 1 and 2; the output was identical across the seeds. Each checks a claim from the third accuracy review. Scripts and raw output: the JSON, key review_round_3_2026_09_29.

Change-cost measurement

The lab story plus now(t0) and N unrelated facts item(1) … item(N), loaded into a fresh engine and queried once. Then, 25 times: add one unrelated fact seen(k) (kb.assert_ in the rewrite, KBEngine.add in the earlier engine) and ask can_enter(lab), timed together; then ask again, timed alone. Medians in milliseconds, CPython 3.12.10 on Windows 11, one machine, September 29, 2026; the three rows per cell are hash seeds 0, 1 and 2.

The rewrite's cost after a change grows with the program because _refresh re-analyzes all of it and rebuilds the timeline; the earlier engine clears its caches but rebuilds nothing. These are indicative only: small programs, facts only, one machine.

Source map

Paths are relative to src/kb/ for the earlier engine and src/cyclops/ for the rewrite unless shown in full; line numbers are at the pinned commits.

Measurements, current and historical

Current values were measured on September 28, 2026 with the method of measure-migration.py (physical lines from pinned Git snapshots). Historical values are as the other pages recorded them.

Line counts measure scope, not quality or simplicity. The earlier src/kb/ includes applications and instrumentation that the rewrite doesn't have.

Documentation checked against code

• Earlier engine. Its docs/KB_API_AND_DESIGN.md describes a clause index in IndexedFactStore that was removed (engine/indexed_store.py:1-22), says RuleCompiler checks stratification at compile time although the load path doesn't call it (p :- \+ q. q :- \+ p. loads and both goals answer []), gives the DFS allowlist as person, child (code: person, child, sibling), and lists explain_holds_at as public API although it returns an error string outside the test suite. Its README names files that don't exist. Its claim of identical answer order on every run holds for top-level handlers but not for time/1 inside a rule body, whose order changed across hash seeds 0 to 5.
• Rewrite. Its architecture diagrams show _refresh() before the QueryContext is built; the code builds the context first and prepares inside the status boundary. Its prose places the analysis and timeline caches on the program; the code keeps them on KnowledgeBase._derived, and the per-predicate first-argument index is a third revision-keyed structure it doesn't list. Its migration map calls candidate-fluent generation eliminated (now redesigned per requested time) and says self-referential fluents answer false with a note (since 6d6a9a9 they stop as EXHAUSTED). solve/context.py mentions a provenance recorder that doesn't exist. spans_for doesn't carry a status.
• This site. How it works says all long-lived state belongs to the program; at both 9be7804 and 5d598de the derived analysis and timeline live on the KnowledgeBase facade, keyed by the program's revision.

Review record

This is AI-simulated review, not testing with real users. Independent AI agents played readers and adversarial reviewers in three rounds: round 1 on the first, longer draft; round 2 on the page after it was cut to a shorter read; round 3 on the second cut. In every round the readers got the rendered page with no further explanation and answered five questions: what the projects share, the two most important architectural differences, where a request's mutable state lives, what happens when evaluation can't finish, and what would affect their choice. The reviewers were asked to find unsupported conclusions, unfair comparisons, omitted strengths of the earlier engine, misleading diagrams and counterexamples, and they ran their own isolated probes. Approval was not treated as evidence: each finding below was checked, then fixed or its uncertainty stated. Round 3 had one reader and one accuracy reviewer (below).

Second cut: toward a five-minute page

What changed. After round 2 the page was cut again on September 29, 2026, aiming at a five-minute read: at most 1,300 words of visible prose and 1,800 visible words in all (prose, tables, and figure questions and captions; the collapsed text equivalents and the code block aren't counted). Counted by a script over the rendered HTML, prose fell from 2,012 to 1,267 words, tables from 407 to 265, and figure questions and captions from 247 to 176, so the visible total fell from 2,666 to 1,708. The code block has 43 words and the collapsed text equivalents 706. Each comparison is now one table row (what is shared, what differs, and one symbol per engine to look up), followed by one or two sentences of consequence under its own heading. The traced example keeps the ordinary success and one difference case, the tunnel. Below 600 px the comparison table shows each row as a block of labelled lines instead of scrolling sideways.

Where earlier changes went. The Change and Now columns below describe the page after round 2. These left the page's visible text for the detail unless another place is named: the examples of Figure 1's legend (its text equivalent); the Options examples; decide's list of queries and the per-query budgets; the entry-path probe and last_route; the three-argument effect form (detail) and the two-argument cause of the open circular question (probe results, when evaluation can't finish); the tunnel's 50-segment row; explain on a rule head; which engine's snapshots cover what; the warnings the rewrite records on kb.diagnostics; that loading succeeds before a SemanticConflict; the legacy facade's immediate effects; what hash seeds change (method, added in round 3); and the concurrency note. Round 3 put some back on the page in short form: explain on a rule head, the per-query limits (in the table, with "a decide makes several"), the concurrency note, and the earlier engine's snapshot restore. The qualifications behind round 2's two major accuracy findings stay on the page: unknown predicates quietly fail in both engines, and the earlier engine's re-entry guard answers false without saying so.

Reviewed in round 3. One simulated reader and one accuracy reviewer read this cut; their findings and the corrections are below.

Round 3: the second cut

AI-simulated review, not testing with real users.

What was reviewed. The second cut above, before this round's corrections: 1,267 words of visible prose and 1,708 visible words in all. One AI-simulated reader got the rendered page with no further explanation and answered the five questions. A technical-accuracy reviewer compared the cut with the committed page and with the code at both pinned commits, rebuilt a copy of the site, checked links, anchors and the phone-width table, and ran new probes; both engine repositories stayed clean. There was no second or third reader, and no fairness or visual reviewer, in this round. The accuracy report first arrived cut off partway through its eleventh finding. The full report, recovered afterwards, has thirteen findings, two of them (6 and 13) older than the cut.

Answers. All five in substance as the page intends. Shared: in-process Python libraries for Prolog-style questions with Event Calculus story time, immutable terms and a binding trail, goal-by-goal search with automatic tabling, the same game hooks and JSON, fail-closed hooks, provenance from fact_id/2 and supports/2, and the same answers on the lab-door story under three hash seeds. Two differences: one path instead of many, with the human/1 and person/1 probe; and request-owned state, with its cost, a reanalysis and timeline rebuild after every change, even advancing the clock. Mutable state: each lifetime in both engines, from the rewrite's per-call QueryContext, revision-keyed DerivedState and clause index to the earlier engine's result cache (next add or 300 seconds), answer tables, derived-result and holds_at caches and process-wide routing. Can't finish: fixed limits that return a plain partial list, against budgets, cancellation and three statuses, with what ask, query, decide and spans_for each do; the tunnel's false refusal; SemanticConflict; the open circular question; and a complete "no" for an undefined predicate. Choice: the rewrite, for answers that don't depend on names or process-wide state, an honest "didn't finish", assert and retract, and isolation between instances; weighing indeterminate in game logic, the rebuild on every assert and clock tick (0.25 ms, about 3.4 ms with 10,000 more facts), no rule-level "why", slower repeats (0.07 against 0.011 ms), no authoring warnings and no bundled applications.

Where answers differed from the page's intent. The reader's list of the rewrite's process-wide state had no atom table, because the page left it out (accuracy finding 6). The reader also took SemanticConflict to break the knowledge base for good, because the cut had dropped "until the program changes" (finding 3).

Technical accuracy. The reviewer confirmed that the rebuilt copy matched the working tree, that the link check found no problems over 22 pages, and that all 16 links into this record, its 10 links back and the new glossary anchors resolve. It also confirmed the rewrite's first commit date, that the earlier games, CLI and app.py import only CyclopsStormKB, the layering test and that the solver never imports story time, every symbol in the comparison table, the difference case at 51, 55 and 60 segments, the timing figures, this record's word counts for the cut, and the phone-width table at 360, 390 and 599 px. Its findings, as received:

What changed since round 2.

• What was read. Round 2 read the page at about 2,700 visible words; round 3 read the second cut at 1,708.
• What came back. One reader's answers and confusions in full; the accuracy review first arrived cut off after its tenth finding and part of its eleventh; findings 12 and 13 were recovered from the full report afterwards.
• What the reader got right. All five questions; the misreadings traced to two omissions of the cut (findings 3 and 6).
• What the accuracy review found. As in round 2, compression had dropped qualifications, mostly ones that favor the earlier engine or name a cost of the rewrite. They are back in short form, some moved into the code-read table, and the page stays within its limits: 1,294 words of visible prose (limit 1,300) and 1,771 visible words in all (limit 1,800), of which tables 298 and figure questions and captions 179; the collapsed text equivalents have 827 words and the code block 43. At 200 to 240 words a minute, the prose takes about 5.5 to 6.5 minutes and everything visible about 7.5 to 9; the round-3 reader took 17 minutes, including the figures and their text equivalents.
• New evidence. Two round-3 probes. Figure 2's drawing gains the atom table, so its three SVG sizes grew by 16 or 17 px in height.

Round 2: the shortened page

What was reviewed. The page as cut on September 29, 2026, about 2,270 visible words (prose, tables and figure captions) against about 3,500 in the round-1 draft, and its evidence record. Received in full: all three readers' answers and confusions, and a technical-accuracy review that compared the cut page with the committed one and ran new probes. There was no fairness or visual reviewer in this round; the rendering checks after the rebuild were the reviser's own.

Answers. All three answered the five questions in substance as the page intends. Shared: in-process Python libraries with the same term model, goal-by-goal search with automatic tabling, Event Calculus story time with delayed effects, fail-closed game hooks, provenance from fact_id/2 and supports/2, and the same game hooks; the same answers on the lab-door story. Two differences: one path instead of many (with the human/1 and person/1 probe and the entry-path probe), and a request's state belonging to the request. Mutable state: each gave both engines' lifetimes accurately, from the rewrite's discarded QueryContext, revision-keyed DerivedState and clause index to the earlier engine's result cache (next add or 300 seconds), holds_at cache and process-wide routing. Can't finish: fixed limits and a silent partial list against per-request Limits, cancel and three statuses, with what ask, query, decide and spans_for each do, the tunnel's false refusal, SemanticConflict and the circular rule left open. Choice: all three leaned to the rewrite for honest statuses and answers that don't depend on names, weighing the rebuild after every change (including advancing now/1), slower repeats, no rule-level explanation, closed extension and handling indeterminate; the engineer would first measure the rebuild at their real program size and clock rate.

Where answers or readings differed from the page's intent. N read "so only the rewrite can say 'didn't finish'" as a consequence of Difference 2; it is a separate design choice. N and G first took Difference 2 to mean the rewrite has no process-wide state. N and G couldn't tell which engine snapshots. No reader said that a complete "no" can come from an undefined predicate, because the cut page no longer said so (accuracy finding 1 below).

Technical accuracy. The reviewer compared the cut page, both figures' captions, alt text, text equivalents and SVG text with the code at both commits, the committed page and this record, and ran new probes on fresh exports; both engine repositories stayed clean. It confirmed the revisions and dates, the seven intervening commits, the Limits defaults and the 512-step cancel poll, the three statuses, query raising and decide returning indeterminate, spans_for as the only result API without a status, both SemanticConflict triggers, what uses the legacy facade, the earlier engine being add-only apart from snapshots, the fail-closed _holds, the depth cap printing through print(), the re-entry guard, the change-cost figures, all eight goals matching under three seeds and a clean link check. Its findings, each re-probed where it made a behavioral claim (round-2 probes):

What changed since round 1.

• What was read. Round 1 read the first draft; round 2 read the page after the cut, which had moved many round-1 fixes into the detail.
• What came back. Round 1's reports arrived partly cut off (below); round 2's arrived whole, so this round records all three readers' confusions. Round 2 had no fairness or visual review.
• What the readers got right. Round-1 readers mostly asked for missing mechanisms and definitions. Round-2 readers answered all five questions as intended; their confusions came mostly from wording the cut had compressed.
• What the accuracy review found. The cut had dropped qualifications that round 1 had added. Round 2 put them back on the page in short form. The page grew from about 2,270 to about 2,700 visible words; the readers took 18 to 25 minutes.
• New evidence. Six round-2 probes. The glossary also gained an anchor per term.

Round 1: the first draft

What reached the revision. The reports came through an automated hand-off that cut part of them off. Received in full: the non-specialist reader, the technical review of the rewrite's claims, and the fairness review's summary and first four findings (the fifth in part). Received in part: the game developer's answers, without their list of confusions. Not received: the software-engineer reader and the visual review's written findings. The visual reviewer's scripts and screenshots were available, so its checks were re-run. Missing parts are recorded here as not received, not as clean.

Now says where each change stands after the cut and round 2: page; detail, only in this record; restored, dropped by the cut and back on the page in round 2; or revised, changed again in round 2.

Technically curious non-specialist (a Python programmer with no Prolog or Event Calculus; 18 minutes, including three linked pages). Answered all five questions correctly in substance: the shared jobs and execution model; both differences (one path, and engine-wide caches versus a discarded per-request object); where state lives in each engine; statuses, budgets, cancellation and the false refusal; and a reasoned choice, the rewrite if a false "no" is worse than an honest "don't know", budgeting for explanations and extension. Noted that choosing "the two most important" differences was their own judgment.

Game developer embedding an engine (Python, basic Prolog; read the page, both figures and five linked pages). Answered correctly: shared ground, both differences, state lifetimes including the aliasing evidence, can't-finish behavior including the indeterminate message. Would pick the rewrite for predictability, weighing slower repeats, the per-change rebuild ("could be the dominant cost, but it isn't measured"), no rule-level explanation, closed extension, a global SemanticConflict, and handling indeterminate in the UI. Their list of confusions wasn't received. From the answers, two things changed: the findings now label Difference 1 and Difference 2, because the reader said several findings could pass for the second difference; and the change cost is now measured. Both are on the page.

Software engineer maintaining or extending it. Not received.

Technical accuracy of the rewrite's claims (checked against 5d598de with the reviewer's own probes; working tree clean). It confirmed the line counts, the six changed source files, the solver's dispatch order, _holds, the default limits and cancel interval, query raising, decide's indeterminate results, no surviving QueryContext, SemanticConflict from analysis, the circular-rule and variable-effect results, and tunnel lengths 57 to 59.

Fairness to the earlier engine (checked against e62758c with the reviewer's own probes and a test run). The reviewer judged the page fair overall: real strengths named, size disclaimed, the tunnel input flagged as atypical.

Visual presentation. Written findings not received. The reviewer's checks were re-run in Edge at 360, 390, 899, 900, 960 and 1000 px:

Remaining uncertainty

Round 3's corrections have not been re-read by a fresh simulated reader or re-reviewed. Round 3 had one reader, not three, and its accuracy report arrived in two parts (13 findings). Neither round 2 nor round 3 had a fairness or visual reviewer. Round 1's maintainer reading and the visual reviewer's written findings were never received. The change-cost timing uses facts only, on one machine; rules and events would add to the rewrite's analysis and timeline work. Figure text widths were calibrated in Edge on Windows; other platforms' fonts were not checked. The second cut, as corrected in round 3, has 1,294 words of visible prose and 1,771 visible words in all: about 5.5 to 6.5 minutes for the prose alone at 200 to 240 words a minute. The one round-3 reader took 17 minutes over the uncorrected cut, including the figures and their text equivalents; five minutes would need about 260 words a minute over the prose alone.