Skip to content
C.W.K.
Stream
Lesson 04 of 04 · published

The Engine Never Simulates

~13 min · delegation, boundaries, caching, closing

Level 0Raw Ore
0 XP0/36 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete
"The engine queues, records, reviews, and serves results. A session executes."

The last refusal

This quest opened on refusals — assays but never advises, four things the product deliberately is not. It closes on one more, and this one is about capability rather than posture.

Monte Carlo simulation and judgment-laden analysis do not run inside the engine. They are delegations: the engine queues a brief, records it, and holds the result behind a review round. The work itself is executed by a session on whichever machine took the brief.

Be precise about where that gate actually lives, because it is not where you would guess. The invariant is real and the CLI enforces it — the client refuses to land a delegation whose verification has not passed. The engine's own routes are more permissive: the archive routes serve any file committed under a delegation's directory without consulting its status, and the landing route checks for a duplicate landing and a non-empty summary rather than for a green verification. So the discipline is enforced at the tool everyone uses, not at the boundary. That is a common and defensible place to start — and it is worth knowing which one you have, because a gate in a client is a gate anyone can walk around by calling the route directly.

The architecture doc names its own mirror image: a sibling application that produces video holds the same line as the engine never renders. Same shape, different verb. In both cases the engine is a workshop rather than a factory — it holds the queue, the record and the gate, and the actual craft happens somewhere it can supervise but not perform.

Why not just run it in the engine

A Monte Carlo is only arithmetic, and a serving process can do arithmetic. The reason is the second half of the sentence: judgment-laden.

A valuation memo or a scenario model is not a computation with one right answer. It involves choosing assumptions, noticing that a chosen assumption is wrong, and revising. Full automation was judged insufficient for that class of work, and so was routing it through a chat interface — the queue is named as the load-bearing decision rather than an optimization.

And once the work happens elsewhere, the durability rules follow: briefs and results are stored, a crashed session re-takes its brief rather than losing it, and a report is material, not truth, until it has passed a review round. The engine cannot do the thinking, so it does the remembering and the gating instead — which is a genuinely useful division of labor rather than a limitation.

An engine that cannot perform the work can still guarantee the record. When work requires judgment, the valuable thing a system provides is not execution — it is that nothing gets lost, everything is attributable, and nothing unreviewed is served as a result. Those guarantees are stronger when the engine holds them and weaker when it is also trying to do the work.

One last mechanism: counting instead of guessing

A small thing that earns a place in the closing lesson, because it is the same idea in miniature.

The read model — percentiles, windows, medians over the whole append-only history — is expensive to rebuild. The obvious cache is time-based: rebuild every N seconds. The engine instead caches on its own write counter, and can do so because it is the single writer. Counting attempted writes is cheap and, crucially, never misses one. Look closely at the ordering though: the counter increments before the statement runs, so a statement that fails still advances it and still triggers a rebuild. That makes this conservative invalidation rather than an exact successful-write signal — it can rebuild when nothing changed, and it can never fail to rebuild when something did. For a cache that is exactly the right direction to be wrong in, and it is worth naming rather than claiming a precision the code does not have.

A timer would have been approximately right and occasionally embarrassing: press Refresh, watch nothing change, wonder if the button works. A signal that never misses was available for nothing, because an ownership decision made earlier had already established that there is only one place writes come from.

And the measurement that stopped an optimization. The natural instinct is to push this work into the database — one clever window-function query instead of computing in Python. It was tried and measured at roughly three times slower, because a median requires sorting every value and there is no index on the value column. The comment in the code says so, with both numbers, so the next person to have the same good idea gets the measurement instead of repeating the experiment.

Where this leaves you

One sentence has run through every track. A measurement that cannot state its own limits is not a measurement — it is a claim wearing a measurement's clothes.

It appeared as a date that did not say whose calendar it used. As a percentile that did not say how long its window was. As a roster that did not say it was incomplete. As a name borrowed from an index whose specification it did not meet. And finally as a number computed where nothing else could read it — the case where the limits could not be stated because there was nobody to state them to.

That is the whole discipline of an instrument that refuses to advise. It does not get to be persuasive, so it has to be checkable. A touchstone tells you what the metal is, shows you the reference needles it compared against, and stops talking.

Code

A reliable invalidation signal, available because of an ownership decision·python
# db.py -- the engine is the single writer, so counting never
# misses a write. Note the ORDER in execute() below.
_writes = 0
_write_lock = threading.Lock()


def write_version() -> int:
    with _write_lock:
        return _writes


def execute(sql: str, params=()):
    _bump()                     # every write goes through here
    return qdb.execute(sql, params)


# gauges.py -- the read model, cached on that counter.
def latest(gauge=None, market_code=None) -> list[dict[str, Any]]:
    """Cached on the engine's write counter -- exact, not a timer.
    The bands change when a refresh writes and at no other moment,
    so a manual Refresh is still instantly visible while a quiet
    dashboard stops rebuilding tens of thousands of rows on every
    load."""
    version = db.write_version()
    with _cache_lock:
        if _cache is None or _cache[0] != version:
            _cache = (version, _compute_latest())
        rows = _cache[1]
    return [...]

# Both docstrings above are quoted verbatim, and both say "exact".
# Read execute(): _bump() runs BEFORE the statement, so a failed
# write also advances the counter. The behaviour is conservative,
# not exact -- it can rebuild for nothing and can never miss a
# real change. Third time in this quest that a docstring claims
# more than its code delivers; the code is still right.

# And the optimization that was MEASURED and rejected: pushing this
# into one window-function query ran ~3x SLOWER, because a median
# needs a sort of every value and there is no index on `value`.

External links

Exercise

Take the whole quest's frame to something you own. Pick one number your systems publish and try to state its limits from the payload alone: which calendar its date belongs to, what reference set gives it meaning, how much history stands behind it, whether the set it summarizes was complete, whether it was measured or assumed, and whether anything besides the rendering surface can read it. Every question you cannot answer is a claim your product is currently making without evidence.
Hint
Do it for the number your organization quotes most often in meetings. That one has the widest reach, the most inherited assumptions, and — almost always — the fewest of these six questions answerable from the data itself.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.