Chapter 5 · Part II: Knowledge Native Architecture

Programming with Knowledge Capsules

During execution, a Knowledge Native system receives observations, retrieves applicable knowledge, generates hypotheses, identifies gaps, validates evidence, revises earlier conclusions, and explains its reasoning. The programmable units that participate in this evolving process are knowledge capsules.

5.1 From Knowledge Objects to Active Computational Units

Chapter 2 introduced the knowledge object as a semantic unit. Chapter 4 showed how information from observations, documents, databases, foundation models, simulations, and people becomes computational knowledge. A running program now requires a concrete unit through which that knowledge can be instantiated, activated, combined, revised, and traced.

Definition 5.1 (Knowledge Capsule). A knowledge capsule is a programmable computational unit that realizes one or more knowledge objects together with the operational state, interfaces, dependencies, lifecycle, activation logic, and permissions through which that knowledge can participate in constructing and revising an understanding.

knowledge object
    semantic identity and meaning

knowledge capsule
    runtime realization and participation

understanding state
    organized result of interacting capsules

A knowledge object answers, What knowledge is represented? A knowledge capsule answers, How can this knowledge enter, influence, revise, and explain a computation?

Programming Principle. A capsule is not merely a record containing knowledge. It is a computational participant whose provenance, scope, status, and capabilities govern how it may shape understanding.

5.2 Why an Ordinary Object Is Not Enough

A capsule may be implemented using a class, record, actor, graph node, message, or database entity. The abstraction is not reducible to any one of these mechanisms.

class Claim:
    def __init__(self, subject, relation, object):
        self.subject = subject
        self.relation = relation
        self.object = object

This object stores a proposition, but it does not tell the program where the proposition came from, whether it is observed or predicted, when it applies, what it depends upon, which operations it may perform, or how it should affect the current understanding.

Fields alone are insufficient. The program must enforce their meaning. An expired capsule should not impose an authoritative constraint. A provisional capsule may support a hypothesis without settling it. A derived capsule must preserve dependencies. A superseded capsule must remain traceable without remaining influential.

A capsule is not an object plus metadata. Its knowledge-level properties determine what the system is permitted to do with it.

5.3 The Capsule Boundary

                  Knowledge Capsule
        ┌─────────────────────────────────┐
        │ semantic payload                │
        │ provenance                      │
        │ scope                           │
        │ epistemic state                 │
        │ lifecycle state                 │
        │ activation conditions           │
        │ dependencies                    │
        │ understanding contribution      │
        │ capabilities                    │
        │ trace events                    │
        └─────────────────────────────────┘
                 ↑               ↓
             inspection       operations

A guideline capsule may contain a structured clinical rule. A prediction capsule may contain a probability distribution. A mapping capsule may contain an ontology link. A procedure capsule may reference a tool. A question capsule may encode a missing piece of information and the reason it matters.

Despite these differences, the runtime can interact with them through common interfaces:

capsule.identity()
capsule.kind()
capsule.scope()
capsule.status()
capsule.provenance()
capsule.dependencies()
capsule.applies_to(context)
capsule.capabilities()
capsule.contribution()
capsule.trace()

5.4 Understanding Contribution

Definition 5.2 (Understanding Contribution). An understanding contribution describes the role through which a capsule may alter the current understanding state.

observe
support
challenge
constrain
qualify
derive
revise
request_information
explain
retire

Caregiver assistance.

ObservationCapsule:
    fever = 39.2°C
    contributes: observe

HypothesisCapsule:
    possible influenza
    contributes: support, challenge, explain

GuidelineCapsule:
    breathing difficulty requires escalation
    contributes: constrain, revise

QuestionCapsule:
    respiratory rate unknown
    contributes: request_information

RecommendationCapsule:
    urgent evaluation advised
    contributes: project, explain

Operational intelligence.

AISObservationCapsule:
    repeated low-speed movement
    contributes: observe

BehaviorHypothesisCapsule:
    possible rendezvous
    contributes: support, challenge

WeatherCapsule:
    severe current conditions
    contributes: qualify, challenge

AnalystJudgmentCapsule:
    historical association is significant
    contributes: support, revise

AlertCapsule:
    analyst review recommended
    contributes: project, explain

5.5 The Anatomy of a Knowledge Capsule

Semantic Payload

The payload contains the knowledge object or objects realized by the capsule. It may be symbolic, numerical, textual, procedural, or hybrid.

Identity

Every capsule requires a stable runtime identity for lookup, comparison, revision, serialization, dependency tracking, and trace construction.

source item:
    caregiver-dialogue-42:turn-7

knowledge object:
    observation:possible-respiratory-distress

capsule instance:
    capsule:respiratory-distress:r2

Provenance

Provenance may include source identifiers, constructor versions, model versions, prompt templates, source spans, human contributors, timestamps, and derivation inputs.

Scope

Scope specifies when, where, for whom, and for which task the capsule may be interpreted and used.

Epistemic State

observed
reported
asserted
inferred
predicted
assumed
provisional
disputed
validated
invalidated

Lifecycle State

constructed
grounded
validated
available
active
influential
suspended
superseded
retired
archived

Epistemic and lifecycle states are distinct. A predicted capsule may be active. A validated capsule may be archived. A disputed capsule may remain active for the purpose of challenging another interpretation.

Activation Logic

Activation logic specifies the conditions under which the capsule may enter a task's active knowledge set.

Capabilities

Capabilities specify which operations the capsule may perform. They may depend on kind, provenance, epistemic state, lifecycle state, and task.

Dependencies and Trace

Dependencies record what the capsule relies upon. Trace state records construction, grounding, validation, activation, influence, revision, supersession, and retirement events.

5.6 A Minimal Capsule Representation

from dataclasses import dataclass, field
from typing import Any, FrozenSet, Tuple

@dataclass(frozen=True)
class KnowledgeCapsule:
    capsule_id: str
    kind: str
    payload: Any
    provenance: dict
    scope: dict
    epistemic_state: dict
    lifecycle_state: str
    activation_conditions: Tuple[Any, ...]
    capabilities: FrozenSet[str]
    contribution_roles: FrozenSet[str]
    dependencies: FrozenSet[str] = field(
        default_factory=frozenset
    )

The capsule exposes the contract. A runtime, rule engine, graph service, model, or tool may perform the actual operation.

runtime.activate(capsule, task)
runtime.contribute(capsule, understanding)
runtime.request_information(capsule)
runtime.revise(capsule, revision)
runtime.retire(capsule)
runtime.trace(capsule)

5.7 Capsule Kinds

KnowledgeCapsule
    ObservationCapsule
    ClaimCapsule
    HypothesisCapsule
    RuleCapsule
    GuidelineCapsule
    ConstraintCapsule
    PredictionCapsule
    MappingCapsule
    ProcedureCapsule
    QuestionCapsule
    UncertaintyCapsule
    HumanJudgmentCapsule
    ExplanationCapsule
    DerivedCapsule

Observation Capsule

Represents information observed or reported about an entity, event, or situation.

Hypothesis Capsule

Represents a candidate interpretation that may be supported, challenged, refined, or rejected.

Guideline and Constraint Capsules

Guideline capsules represent conditional domain knowledge. Constraint capsules restrict permissible conclusions or actions.

Prediction Capsule

Represents a computational estimate while preserving the model, calibration, time, and scope that produced it.

Mapping Capsule

Connects expressions, identifiers, entities, or concepts.

MappingCapsule:
    "breathing much faster"
    maps_to
    possible tachypnea

Procedure Capsule

Represents knowledge of how to perform a controlled operation, such as querying a terminology service, retrieving vessel history, or calculating a threshold.

Question Capsule

Definition 5.3 (Question Capsule). A question capsule represents a knowledge gap as an actionable request for observation, retrieval, computation, or human input.

Current understanding
        ↓
missing respiratory rate
        ↓
QuestionCapsule
        ↓
ask caregiver
        ↓
ObservationCapsule
        ↓
revised understanding

Uncertainty Capsule

An uncertainty capsule represents unresolved uncertainty explicitly rather than hiding it inside a confidence score.

UncertaintyCapsule:
    fever duration unknown
    affects = severity assessment
    resolution = ask caregiver
    urgency = medium

Human Judgment Capsule

Preserves human observation or judgment together with role, authority, time, and intended use.

Explanation Capsule

Represents an audience-specific explanation projected from a knowledge trace. It is distinct from the trace itself.

5.8 Capsules and Foundation Models

Foundation models both consume and produce capsules.

A model may produce an observation capsule from conversation, a hypothesis capsule from multimodal evidence, a mapping capsule from ambiguous terminology, a question capsule from a knowledge gap, or an explanation capsule from a trace.

A model may consume active observations, competing hypotheses, applicable guidelines, constraints, unresolved questions, and the current understanding state.

Active Capsules
      ↓
Foundation Model
      ↓
Question Capsule
      ↓
User or Tool
      ↓
Observation Capsule
      ↓
Revised Understanding

This makes model participation inspectable. The model is not merely sent a prompt and asked to reason invisibly.

5.9 Capsule Lifecycle

Definition 5.4 (Capsule Lifecycle). The capsule lifecycle is the sequence of operational states through which a capsule passes as it is constructed, grounded, validated, activated, allowed to influence understanding, revised, and retired.

constructed
    ↓
grounded
    ↓
validated
    ↓
available
    ↓
active
    ↓
influential
    ↓
revised or superseded
    ↓
retired
    ↓
archived

Important Distinction. An active capsule is eligible to participate. An influential capsule has actually changed the understanding state or a downstream projection.

5.10 Capsule State, Runtime State, and Understanding State

State	What it records
Capsule state	The status, scope, capabilities, and dependencies of one capsule
Runtime state	Registration, activation, events, coordination, and operation dispatch across capsules
Understanding state	The organized interpretation currently held about the subject of reasoning

Separation of Concerns. The capsule owns its knowledge-level identity and contract. The runtime coordinates capsule behavior. The understanding state represents what the system currently believes.

5.11 Activation and Influence

activation = runtime.evaluate_activation(
    capsule=capsule,
    task=task,
    context=context,
    understanding=understanding
)

ActivationResult =
    Activate(capabilities, basis)
  | DoNotActivate(reason)
  | ActivateWithQualification(
        capabilities,
        basis,
        qualification
    )
  | CannotDetermine(missing_knowledge)

After activation, the runtime applies the capsule's understanding contribution:

ContributionResult =
    Supported(target, strength)
  | Challenged(target, reason)
  | Constrained(alternatives_removed)
  | Revised(understanding_delta)
  | RequestedInformation(question_capsule)
  | NoMaterialChange(reason)

5.12 Operations Over Capsules

Operations may be expressed as methods, functions, or runtime-mediated requests.

runtime.apply(
    operation="support",
    source=observation,
    target=hypothesis
)

Runtime mediation provides a strong default because the runtime can enforce capabilities, record dependencies, update traces, and reject invalid operations consistently.

Support

fever_observation
    supports
acute_infection_hypothesis

Challenge

severe_current_weather
    challenges
loitering_hypothesis

Constraint

respiratory_distress_guideline
    constrains
{home_monitoring,
 routine_visit,
 urgent_evaluation}

result:
{urgent_evaluation}

Inquiry

uncertain_respiratory_status
    ↓ request_information
QuestionCapsule:
    "Is the child struggling to breathe?"

Inquiry is not a fallback outside reasoning. It is a knowledge operation that determines the next computation.

5.13 Derived Capsules

Definition 5.5 (Derived Capsule). A derived capsule is a capsule whose payload is produced through one or more operations over existing capsules and whose provenance records those operations and dependencies.

Caregiver assistance.

Fever Observation Capsule
        +
Respiratory-Distress Observation Capsule
        +
Escalation Guideline Capsule
        ↓
Urgent Evaluation Recommendation Capsule

Operational intelligence.

AIS Observation Capsules
        +
Satellite Detection Capsule
        +
Weather Capsule
        +
Behavior Knowledge Capsule
        ↓
Possible Rendezvous Assessment Capsule

A derived capsule preserves its inputs, operations, time of derivation, and the understanding state in which it was created.

5.14 Dependencies and Revision

Definition 5.6 (Capsule Dependency). A capsule dependency is a recorded relation indicating that the content, status, activation, confidence, or influence of one capsule relies on another.

derived_from
supported_by
challenged_by
activated_by
constrained_by
grounded_by
validated_by
supersedes
answers

Different dependency types produce different revision behavior.

if dependency.type == "grounded_by"
and source.invalidated:
    suspend(dependent)

if dependency.type == "supported_by"
and source.invalidated:
    revise_confidence(dependent)

if dependency.type == "constrained_by"
and source.superseded:
    reconsider_alternatives(dependent)

Caregiver assistance. If “no breathing difficulty” is corrected to “labored breathing,” the respiratory observation is revised, the earlier low-risk recommendation is superseded, and escalation knowledge becomes influential.

Operational intelligence. If new weather data explains low-speed movement, the loitering capsule loses support, the alert capsule is revised, and the analyst-facing explanation changes.

5.15 Immutable Capsule Revisions

capsule-r1
    ↓ superseded_by
capsule-r2

Silent mutation destroys historical reconstruction. A stronger default is to create a new semantic capsule version while preserving the previous version for trace, replay, audit, and comparison.

Recommended Default. Treat semantic capsule revisions as immutable versions. Keep task-specific activation and runtime bookkeeping as separate operational state.

5.16 Capsule Composition

Definition 5.7 (Capsule Composition). Capsule composition constructs a higher-level capsule from component capsules while preserving their identities, roles, dependencies, and provenance.

CaregiverAssessmentCapsule
    observations
    supported hypotheses
    challenged hypotheses
    active guidelines
    constraints
    unanswered questions
    recommendation
    explanation trace

Composition preserves structure. It is not equivalent to concatenating capsule contents into a single block of text.

5.17 The Knowledge Capsule Runtime

Definition 5.8 (Knowledge Capsule Runtime). A knowledge capsule runtime is the program infrastructure that manages capsule creation, registration, activation, operation dispatch, dependency tracking, composition, revision, persistence, and tracing.

Capsule Runtime

register
retrieve
activate
deactivate
contribute
compose
derive
merge
split
revise
retire
persist
trace

The runtime acts as an operating environment for knowledge. It need not begin as a large platform. A small implementation may use ordinary Python classes, dictionaries, and adjacency lists.

5.18 Capsule Algebra: A First Glimpse

C₁ supports C₂
        ↓
revised C₂

C₃ challenges C₂
        ↓
qualified C₂

C₄ constrains alternatives
        ↓
reduced action set

C₁ + C₂ + C₄
        ↓ derive
C₅

Once capsules become first-class units, operations over them begin to resemble an algebra. Later chapters can develop how capsules compose, conflict, specialize, revise, and produce higher-level understanding while preserving computational meaning.

5.19 A Complete Programming Example: Caregiver Assistance

fever = factory.create(
    kind="ObservationCapsule",
    payload={
        "concept": "fever",
        "value_celsius": 39.2,
        "subject": "child-17"
    },
    provenance={
        "source": "caregiver-thermometer"
    },
    contribution_roles={
        "observe"
    }
)

breathing = factory.create(
    kind="ObservationCapsule",
    payload={
        "concept": "possible_respiratory_distress",
        "subject": "child-17"
    },
    provenance={
        "source": "caregiver-dialogue-42",
        "constructor": "conversation-constructor-v3",
        "method": "llm-assisted"
    },
    epistemic_state={
        "status": "reported",
        "confidence": 0.82
    },
    contribution_roles={
        "observe",
        "revise"
    }
)

guideline = factory.create(
    kind="GuidelineCapsule",
    payload={
        "if": "respiratory distress is present",
        "then": "urgent evaluation is indicated"
    },
    provenance={
        "source": "pediatric-triage-guideline"
    },
    capabilities={
        "constrain",
        "revise",
        "explain"
    }
)

respiratory_rate_question = runtime.derive(
    kind="QuestionCapsule",
    payload={
        "question":
            "How many breaths per minute is she taking?",
        "knowledge_gap":
            "respiratory rate is unknown",
        "reason":
            "needed to assess respiratory distress"
    },
    inputs=[
        breathing,
        guideline
    ]
)

understanding = runtime.contribute(
    fever,
    understanding
)

understanding = runtime.contribute(
    breathing,
    understanding
)

understanding = runtime.contribute(
    guideline,
    understanding
)

recommendation = runtime.derive(
    kind="RecommendationCapsule",
    payload={
        "recommendation":
            "seek urgent clinical evaluation",
        "qualification":
            "especially if breathing difficulty is confirmed"
    },
    inputs=[
        fever,
        breathing,
        guideline
    ]
)

The system has not merely generated an answer. It has orchestrated capsules representing observations, uncertainty, applicable guidance, inquiry, recommendation, and explanation.

5.20 The Same Pattern in Operational Intelligence

AISObservationCapsule
SatelliteDetectionCapsule
WeatherCapsule
BehaviorHypothesisCapsule
AnalystJudgmentCapsule
MissionRuleCapsule
QuestionCapsule
AlertCapsule

A foundation model may propose a rendezvous hypothesis. Weather may challenge it. Historical association may support it. A mission rule may constrain whether an alert can be issued. A question capsule may request additional evidence. The runtime composes these contributions into a current operational understanding.

5.21 Testing Knowledge Capsules

Construction: Is the correct kind created, with complete provenance and preserved model assistance?
Lifecycle: Are invalid transitions rejected and revision chains preserved?
Activation: Does the capsule activate only in its intended scope?
Capability: Is a prediction prevented from behaving as an authoritative guideline?
Influence: Can each change in understanding be traced to the capsules that caused it?
Revision: Does invalidation propagate according to dependency type while unaffected capsules remain stable?

5.22 Common Design Mistakes

Making Capsules Large Unstructured Dictionaries

Without types, lifecycle rules, capabilities, and invariants, a capsule becomes another loosely structured data object.

Putting All Reasoning Inside Capsule Methods

Capsules expose knowledge behavior. Coordination, permission enforcement, dependency propagation, and tracing usually belong in the runtime.

Conflating Active with Influential

An active capsule is eligible to participate. An influential capsule actually changed understanding.

Treating LLM Output as Authoritative

Model-produced capsules should preserve model provenance and normally begin as provisional unless independently validated.

Representing Questions Only as Prompt Text

A question should arise from an explicit gap and remain linked to the decision or hypothesis it is intended to resolve.

Hiding Uncertainty Inside Confidence Scores

Some uncertainty deserves its own capsule because it changes what the system must do next.

Overwriting Capsules During Revision

Prefer immutable versions and explicit supersession links.

Flattening Composite Capsules

A higher-level capsule should preserve component identities and contribution roles.

5.23 A Minimal Student Implementation

capsule.py
    capsule types and invariants

factory.py
    capsule creation

registry.py
    storage and lookup

runtime.py
    activation and operation dispatch

understanding.py
    understanding-state updates

trace.py
    dependency and lifecycle records

capsule = factory.create(...)
registry.add(capsule)

activation = runtime.evaluate_activation(
    capsule,
    task,
    understanding
)

runtime.activate(capsule, activation)

understanding = runtime.contribute(
    capsule,
    understanding
)

derived = runtime.derive(
    operation,
    inputs
)

trace = runtime.trace(
    derived.capsule_id
)

Implementation Guidance. Start with a small number of capsule kinds and operations. Preserve identity, provenance, activation, understanding contribution, dependencies, revision, and trace correctly before adding sophisticated reasoning.

5.24 The Capsule as a Core Programming Unit

information
    ↓ construction
knowledge object
    ↓ encapsulation
knowledge capsule
    ↓ activation
active capsule
    ↓ contribution
understanding revision
    ↓ composition
recommendation, dialogue,
prediction, alert, or explanation

Central Thesis. In conventional programming, the primary computational unit is often the object or function. In Knowledge Native programming, a primary computational unit is the knowledge capsule: a living unit of knowledge that participates in constructing, revising, and explaining computational understanding.

Programs no longer compute solely by transforming data structures or invoking models. They also compute by orchestrating populations of interacting knowledge capsules whose collective behavior gives rise to an evolving understanding of the world.

Knowledge Native Thinking

What knowledge object does this information represent?
What capsule should realize it?
How may it contribute to understanding?
Which capabilities should it possess?
Under what conditions may it activate?
What does it depend upon?
What question should it create when knowledge is missing?
How should it be revised or retired?
What trace must it preserve?

Programming Shift. Move from passing information between components to orchestrating computational units that know what they represent, where they came from, how they may influence understanding, and what must happen when they change.

Chapter Summary

A knowledge object is the semantic abstraction; a knowledge capsule is its runtime realization.
A capsule combines payload, provenance, scope, epistemic state, lifecycle, dependencies, capabilities, and understanding contribution.
Foundation models both consume and produce capsules.
Question capsules make knowledge gaps actionable.
Uncertainty capsules make unresolved knowledge computationally explicit.
Activation makes a capsule eligible to participate; influence records that it actually changed understanding.
Runtime-mediated operations enforce capabilities, record dependencies, and preserve traces.
Derived capsules preserve their inputs, operations, and understanding context.
Typed dependencies enable incremental revision.
Immutable semantic revisions preserve historical traceability.
Capsule composition creates higher-level understanding without flattening component roles.
The capsule runtime acts as an operating environment for knowledge.
Capsule operations suggest the beginnings of a knowledge algebra.

Discussion Questions

How is a knowledge capsule different from an ordinary object containing metadata?
Why should understanding contribution be explicit?
How does an active capsule differ from an influential capsule?
When should uncertainty become its own capsule?
Why should questions be represented as capsules rather than only as generated text?
What information must a derived capsule preserve?
Why are immutable revisions useful?
What operations might belong in a future capsule algebra?

Exercises

Exercise 5.1: From Knowledge Object to Capsule

Take one knowledge object from Chapter 2 and design its capsule realization, including payload, provenance, scope, lifecycle, capabilities, contribution roles, dependencies, and trace events.

Exercise 5.2: Implement the Base Capsule

Implement an immutable KnowledgeCapsule record with capability checking, dependency inspection, revision linking, and serialization.

Exercise 5.3: Define Capsule Kinds

Implement observation, hypothesis, guideline, question, uncertainty, and derived capsules. Specify default capabilities and contribution roles.

Exercise 5.4: Program the Lifecycle

Implement constructed, grounded, validated, available, active, influential, suspended, superseded, retired, and archived states.

Exercise 5.5: Build a Question Capsule

Represent one knowledge gap as a question capsule and link it to the hypothesis or decision it affects.

Exercise 5.6: Create an Uncertainty Capsule

Represent an uncertainty that cannot be captured adequately by a single confidence score.

Exercise 5.7: Create a Derived Capsule

Use observations and a guideline or behavior capsule to derive a recommendation or assessment capsule with complete provenance.

Exercise 5.8: Propagate a Revision

Create a capsule dependency graph and revise one source capsule. Determine which dependents require recomputation, suspension, confidence revision, retirement, or no change.

Exercise 5.9: Implement a Minimal Runtime

Build a runtime supporting registration, activation, contribution, derivation, revision, retirement, and trace retrieval.

Exercise 5.10: Compose an Understanding Capsule

Create a composite assessment capsule from observations, competing hypotheses, one constraint, one human judgment, one uncertainty, and one question capsule.