FOG Runtime

Flood is a runtime architecture for evidence-gated parallel exploration. FOG is its coordination substrate.

Flood provides the momentum. FOG shapes the flow.

Workers compete through hypotheses. Flood converges through evidence.

FOG is not a shared database, shared memory, blackboard, or Task World Model. It is a versioned executable projection that turns admitted local evidence into scoped changes in future execution. Workers encounter those changes only when their declared path footprint intersects the changed frontier and they reach a safe checkpoint.

Prediction
  -> Flood Release
  -> Worker Parallel Exploration
  -> Evidence
  -> Harness Verification and Admission
  -> FOG Mutation
  -> Selective Patch Projection
  -> Checkpoint Rebase
  -> Continued Exploration

Repository Boundary

This is an independent Python 3.12 reference runtime. It does not import, modify, execute, or symlink flood-harness. A future adapter will translate frozen wire values without sharing Python class identity.

The Evidence Ledger records what happened. FOG determines where that evidence should change future execution. FOG owns no fact and can be reconstructed from ordered admitted deltas, immutable evidence references, and the reducer version.

Persistent Map Identity Contracts

fog_runtime.world_map freezes deterministic logical identities, immutable partition revisions, map manifests, stable entity references, and selective Episode view references. These are syntax-level identity and citation values; they do not establish truth or supply joint evidence.

This module is explicitly not storage, the Experience Graph, Terrain Compiler, Map Intelligence, Exploration Allocator, a Flood adapter, or joint evidence.

Persistent semantic lifecycle contracts

fog_runtime.world_map.semantics defines provenance- and admission-bearing experience, hypothesis, and executed-future record contracts plus deterministic per-record lifecycle reduction and replay. It is a contract-and-pure-reducer reference layer above persistent map identity. Experiences and executed-future trajectories require Ledger evidence. Hypotheses may be registered without evidence and remain speculative.

It does not implement the Evidence Ledger, graph storage, terrain compilation, Map Intelligence, Exploration Allocation, Coordination Kernel effects, a Flood adapter, or joint Flood–FOG evidence. Identifiers remain opaque canonical syntax: the absence claim is structural—there are no dedicated private reasoning, payload, storage, time, or kernel fields—and does not semantically classify arbitrary identifier text.

Deterministic reminder projection

fog_runtime.world_map.reminders compiles an admitted semantic record, its complete lifecycle event history, and the replayed final state into a metadata-only versioned reminder entry:

semantic source
  -> deterministic reminder projection
  -> bounded exact cue activation
  -> exact semantic record and Ledger evidence pointers

Reminder cues are structured relation triples, not generated summaries or a bag of keywords. Source histories are replayed before compilation; contradiction, revocation, supersession, freshness, support, and trajectory changes therefore propagate mechanically into a new immutable projection. Queries require every declared cue, explicitly select allowed lifecycle classes, and return a bounded selection of at most 256 metadata-only entries. no_hit means only that this exact query found no entry in this projection version.

The existing activate_reminders() API remains the same conjunctive, reminder-ID-sorted exact activation operation. It does not use the new ranking path implicitly and does not become a fallback when explicit retrieval returns no_hit or fails.

Explicit Reminder Retrieval Runtime

fog_runtime.world_map.reminders.retrieval is a separate opt-in runtime surface. The caller supplies one immutable snapshot containing an exact ReminderProjection, registered ReminderMechanismManifest, and matching CueGraphIndex. The runtime then:

canonical query
  -> runtime-owned hard eligibility
  -> deterministic Cue Graph ranking
  -> universal authority and budget validation
  -> mechanism-specific deterministic verification
  -> metadata-only ReminderRetrievalResult

Hard cues and activation classes decide which entries are eligible. Retrieval seeds rank only those eligible identities. The runtime rehydrates selected metadata from the bound projection and re-enforces both result-count and byte budgets; the mechanism cannot supply evidence payloads or alter eligibility. An empty eligible corpus is the only short-circuit path and the only result without a mechanism-result digest.

Budget ownership has three layers: the query is the authority, the mechanism uses copied limits during execution, and the runtime independently enforces the original limits over rehydrated metadata before publication.

No Retrieval Hit is deliberately narrow. It means either that hard eligibility was empty, or that the selected mechanism abstained over a nonempty eligible corpus. It is not Known Unknown, Known False, negative evidence, or permission to run exact activation implicitly.

Concurrency follows immutable snapshot publication semantics. A host builds and validates a complete new projection/manifest/index tuple away from the published tuple, then replaces one host-owned reference. In-flight calls keep their captured old tuple; later calls receive the new tuple. This package adds no mutable global registry, background refresh, incremental graph mutation, or publication lock.

The runtime does not parse natural language, load Evidence Ledger payloads, infer epistemic state, call a model, implement Region storage, assemble Working Context, notify Workers, rebase checkpoints, or integrate Flood. Its Cue Graph identity reproduces a selected artificial development mechanism; that does not establish real-Episode or Flood evidence, retrieval quality, context reduction, or scale benefit.

Reminder Retrieval Development Benchmark

experiments/reminder_retrieval is a separate, offline mechanism-selection benchmark over an artificial public development fixture. It compares the existing runtime exact behavior, a filtered-exact semantic control, cascade, exact cue-cooccurrence graph retrieval, and an isolated local embedding path. The 9-case calibration partition fixes candidate thresholds; the 36-case evaluation partition supplies the reported quality vectors.

The frozen scored run produced:

Result	Value
Query-semantics outcome	gain
Mechanism outcome	selected:cue-graph-v1
Experiment manifest	sha256:99e5f4bf668237c7bf9829de29834aeaaae3dc100fa7c315e446fbffcfffa841
Semantic results	sha256:c12a38bd9753527b70ad02de10e0474ea4cd201c21c47f2ce3c3ce8c5289d9d0
Comparison report	sha256:94c6b55a1f00f1206cf0bb004677af360722cab26ba2c3cfde66a0d023f146d4
Completion manifest	sha256:2c105e7c7c8d35b8feea3e99ab55bded909d9826f2ecdc41cc5ea2ea949484d0

All five paths passed the frozen safety gate. A fresh second execution produced the same ordered semantic results, non-timing quality vectors, paired rows, outcomes, and bounded claim text. Timing receipts differed and support only diagnostics on the recorded machine.

Under the frozen lexicographic rule, cue graph was selected by its primary recall (1/1); its primary precision was 25/196. The selection therefore does not assert general superiority outside this rule and fixture.

This frozen evidence authorized the later FOG design review; by itself it did not change the runtime package. The explicit runtime above is a separate, subsequently verified implementation. Neither the benchmark nor the runtime establishes a result for real Episodes, Flood integration, context reduction, or scale. The canonical report and digest-bound receipts are under experiments/reminder_retrieval/artifacts/v1/.

Blank-Slate Emergent Constraint Terrain Study

experiments/emergent_terrain is a separate FOG-only deterministic synthetic development study. Its Workers began with an empty FOG and no prewritten reminders, constraints, gold paths, or terrain. Public attempt receipts could form generalized warnings only through the frozen evidence-admission and checkpoint-rebase path.

The frozen 144-run matrix produced:

Result	Value
Study outcome	not_supported
Execution source revision	e949a857080bad0bbd4e8fafd442114edff499b5
Experiment manifest	sha256:5b551de9f40e199225f65ad176f2add1186ca0302eb315d84a85e44d7845925f
Study report	sha256:d372101cfd4cebba417c7f532e580ded9392d7543fbad78592aeaf5d93a04ad6
Completion manifest	sha256:d01930b29453db0b5c67267032a8d7b7010b9a9f9ee71593c91714fb845e70b8
Runs / action receipts	144 / 7,317

The induced arm reduced aggregate post-discovery repeated failures at every reported width: 15 versus exact-share 42 at width 4, 45 versus 131 at width 8, and 125 versus 300 at width 16. Those observations do not satisfy the frozen claim, because the induced arm's false-warning-opportunity rates were 16/135, 30/269, and 13/200; all exceed the precommitted maximum of 1/20. The report therefore preserves not_supported even though safety, identity, replay, terrain formation at widths 8 and 16, repeated-failure reduction, completion, and diversity gates passed.

The seed summaries are frozen-instance aggregates, not population estimates. Completion and attempt-count changes are downstream diagnostics rather than independent evidence of terrain quality. Two full source-bound replays produced identical ordered semantic results and report/completion digests. The immutable snapshot is under experiments/emergent_terrain/artifacts/v0/result/.

This result does not establish real-Episode induction, learned-terrain retrieval, Flood integration, production effectiveness, or asymptotic or nonlinear scale benefit.

Deterministic Example

The example admits one receipt-supported obstacle, reduces FOG from version 0 to 1, projects the change to a matching path, and requires checkpoint replan:

from pathlib import Path
from tempfile import TemporaryDirectory

from fog_runtime import (
    AdmissionVerdict,
    ApplicabilityPredicate,
    EffectKind,
    EffectSpec,
    ElementKind,
    EvidenceAdmission,
    EvidenceRef,
    FogDeltaProposal,
    FogRuntime,
    FrontierAddress,
    InMemoryEvidenceLedger,
    MutationState,
    RebaseOutcome,
    SupportClass,
    WorkerPathFootprint,
)

evidence = EvidenceRef(
    evidence_id="evidence-1",
    digest=f"sha256:{'a' * 64}",
    media_type="application/json",
    producer="harness",
)
target = FrontierAddress(
    topology_ref="topology-1",
    element_id="edge-obstacle",
    element_kind=ElementKind.EDGE,
)
scope = ApplicabilityPredicate(
    environment_fingerprint="env-1",
    checkpoint_lineage=("cp-root",),
)
effect = EffectSpec(EffectKind.BLOCK_ROUTE)
proposal = FogDeltaProposal(
    proposal_id="proposal-1",
    worker_id="worker-a",
    episode_id="episode-1",
    base_fog_version=0,
    target_addresses=(target,),
    proposed_effect=effect,
    applicability=scope,
    predicted_consequence="The scoped route is unavailable.",
    evidence_refs=(evidence,),
    dependency_effect_ids=(),
    summary="Observed a scoped obstacle.",
)
admission = EvidenceAdmission(
    admission_id="admission-1",
    proposal_id=proposal.proposal_id,
    verdict=AdmissionVerdict.ADMITTED,
    support_class=SupportClass.RECEIPT_SUPPORTED,
    authorized_effect=effect,
    authorized_scope=scope,
    evidence_refs=(evidence,),
    admission_sequence=1,
    authority="harness",
)
worker = WorkerPathFootprint(
    worker_id="worker-b",
    episode_id="episode-1",
    known_fog_version=0,
    topology_ref="topology-1",
    checkpoint_id="cp-root",
    checkpoint_lineage=("cp-root",),
    planned_addresses=(target,),
    hypothesis_dependencies=(),
    effect_dependencies=(),
    environment_fingerprint="env-1",
    context_labels=(),
    mutation_state=MutationState.AT_CHECKPOINT,
)

with TemporaryDirectory() as directory:
    runtime = FogRuntime.create(
        episode_id="episode-1",
        topology_ref="topology-1",
        ledger=InMemoryEvidenceLedger([evidence]),
        journal_path=Path(directory) / "events.jsonl",
        authorities={"harness"},
    )
    state = runtime.submit(proposal, admission)
    patch = runtime.project(worker)
    result = runtime.rebase(worker, patch)

assert state.version == 1
assert result.outcome is RebaseOutcome.REPLAN_REQUIRED

Verification

uv sync --python 3.12
uv run pytest -q
uv run ruff check .
uv run ruff format --check .

The fixed cascade fixture uses 64 logical workers to verify selective propagation: matching workers still at checkpoints replan, unrelated workers receive empty patches, and already-mutating workers defer rebase. It proves routing semantics, not asymptotic performance.

Public Release Notes

This repository is a sanitized single-commit export of the private development repository. Internal planning notes and review logs are not included; the frozen experiment designs are in docs/superpowers/specs/.

• Licensing: see LICENSE.md (CC BY 4.0 for the paper and data, MIT for code).
• Six Reminder Retrieval provenance tests (tests/test_reminder_retrieval_parity.py and one test in tests/retrieval_benchmark/test_scored_run.py) re-derive the frozen benchmark identity from source commit 34b6f5d6, which exists only in the private history. They fail in this export by design; every other test passes.
• Sealed Reminder Retrieval receipts record the absolute interpreter and artifact paths of the original run. They are left unmodified because their bytes are bound by SHA-256 digests.