Lineages and Worldviews

Lineages: Immutable Observation Histories

Stability: contract-backed concept

Authority: The normative rules for lineage branching and promotion live in spec/jacqos/v1/lineage.md. Worldview identity and committed state rules live in spec/jacqos/v1/semantic-state.md. Effect-authority rules live in spec/jacqos/v1/effects.md. This page stays conceptual.

A lineage is one immutable observation history. Every observation appended to a JacqOS application belongs to exactly one lineage. Lineages are the organizational boundary for the observation log — they answer the question “which stream of events are we talking about?”

Lineages matter for both sides of the containment architecture. At runtime, they provide agent isolation — different agents or sessions can operate in independent lineages without interfering with each other. During authoring, they provide safe experimentation — you can fork a lineage, test new rules or prompts against real observation history, and compare worldviews without affecting production.

In the simplest case, your app has one lineage. Observations arrive, atoms are extracted, facts are derived, intents fire, effects produce new observations — all within that single lineage.

Lineage: main
  obs-001  booking.request (Pat, slot-42)
  obs-002  slot.status (slot-42, available)
  obs-003  reserve.result (req-1, succeeded)
  obs-004  booking.confirmed (req-1, slot-42)

Why Lineages Matter

Lineages give you three things that a flat, global observation log cannot:

Isolation

Different lineages are independent observation streams. A test lineage does not interfere with a production lineage. A child lineage can diverge from a parent without affecting it.

Reproducibility

Because a lineage is an ordered, immutable sequence, replaying it from observation zero always produces the same derived state. This is the foundation of golden fixtures and jacqos verify.

Branching

You can fork a child lineage from a parent at any observation. The child inherits all observations up to the fork point, then diverges with its own observations.

Lineage: main
  obs-001  booking.request
  obs-002  slot.status
  obs-003  reserve.result
     │
     └── Lineage: prompt-v2-test (forked at obs-002)
           obs-002  slot.status (inherited)
           obs-003  llm.extraction (divergent — different prompt)
           obs-004  clinician.review

The exact fork inheritance, promotion, and no-merge-back rules live in the lineage authority above. Conceptually, a child lineage gives you a new place to continue from an existing prefix without mutating the parent history.

Worldviews: Derived Truth From a Specific Evaluator

A worldview is the set of facts derived from a specific evaluator over a specific lineage. Same observations, different evaluator — different worldview.

Lineage: main (observations obs-001 through obs-050)
  ├── Worldview A: evaluator v1.2 → 147 facts, 12 intents
  └── Worldview B: evaluator v1.3 → 152 facts, 14 intents

Worldviews are independent. They share the same observation log but derive facts through different ontology rules, mappers, or helpers. This is how you safely test evaluator changes against real observation histories.

What Defines a Worldview

A worldview is fully determined by two inputs:

1. The lineage — which observations to process
2. The evaluator digest — which rules, mappers, and helpers to apply

Two evaluators with the same evaluator digest produce identical worldviews from the same lineage. Two evaluators with different digests may produce different worldviews — that difference is the whole point of shadow evaluation.

Effect Authority

A critical runtime safety property: JacqOS distinguishes between the evaluator you trust to execute effects and the evaluators you run only for comparison. This prevents the dangerous situation where two evaluator configurations both try to execute the same intent — a class of bug that can cause double-bookings, duplicate payments, or conflicting API calls in multi-agent systems. The effect and semantic-state authorities above define the exact committed-activation and effect-authority rules. Conceptually, one evaluator executes effects for a lineage while other evaluators remain comparison-only shadow runs.

Lineage: main
  ├── Evaluator v1.2 (effect-authoritative) → intents execute as effects
  └── Evaluator v1.3 (shadow) → intents derived but not executed

This prevents the dangerous situation where two evaluator configurations both try to execute the same intent. Shadow builds stay useful because they still derive facts and intents for comparison without driving external actions.

Practical Uses

Side-by-Side Comparison

Run two evaluator versions against the same lineage and compare their worldviews via the Compare lens chip in Activity. Side-by-side dual-pane rendering ships in V1.1; in V1 the lens chip pins the comparison evaluator’s identity and the same fact-diff data is exported in every verification bundle:

• Which facts differ?
• Which intents would fire differently?
• Did the new rules fix the bug without introducing regressions?

Prompt A/B Testing

For LLM-assisted apps, fork a child lineage and run it with a different prompt:

1. Fork from the production lineage at the last observation before the LLM call
2. Update the prompt file
3. Run the child lineage with live LLM calls
4. Compare the child’s worldview against the parent’s

See LLM Agents — Child-Lineage Forking for the full workflow.

Fixture Replay

Every fixture replay creates an implicit lineage from the fixture’s observation sequence. The jacqos verify command replays each fixture and checks that the resulting worldview matches the expected state.

Where The Rules Live

• spec/jacqos/v1/lineage.md defines lineage immutability, fork inheritance, and the no-merge-back model.
• spec/jacqos/v1/semantic-state.md defines how evaluator identity and worldview state attach to a lineage.
• spec/jacqos/v1/effects.md defines which committed evaluator activation may execute effects.

Next Steps

• Observation-First Thinking — the append-only evidence model
• Atoms, Facts, and Intents — the derivation pipeline
• Evaluation Package — the evaluator digest and package identity
• Visual Provenance — comparing worldviews in Studio