Chapter 5 · Part II: Knowledge Native Architecture

Programming with Knowledge Capsules

Knowledge Native programs need a practical way to package knowledge together with the semantics that determine when and how it should participate in computation. A Knowledge Capsule provides that boundary. It declares relevant knowledge, scope, applicability, requirements, computational expertise, expected results, authority, and provenance, while leaving the underlying expert implementation free to be an LLM, rule engine, predictor, planner, solver, simulator, verifier, ordinary program, external service, or human.

5.1 From Knowledge Objects to Programmable Knowledge

Chapter 2 introduced knowledge objects as semantic units. Chapter 3 distinguished knowledge from computational expertise. Chapter 4 introduced the Knowledge Runtime and the A4 cycle:

ACTIVATE
    ↓
APPLY
    ↓
ABSORB
    ↓
AUTHORIZE

A running system now needs a practical abstraction that connects these ideas.

A knowledge object by itself answers:

What is known?

A computational expert answers:

What specialized computation can be performed with relevant knowledge?

A Knowledge Capsule connects the two:

Under what conditions should this knowledge and expertise participate, what does the expertise require, what does its result mean, and what authority may follow?

Definition 5.1 (Knowledge Capsule). A Knowledge Capsule is a portable declarative unit that packages knowledge together with the scope, applicability, requirements, computational-expertise binding, result semantics, authority conditions, and provenance needed for that knowledge to participate in the Knowledge Runtime.

Knowledge
    +
Applicability
    +
Requirements
    +
Computational Expertise
    +
Result Semantics
    +
Authority
    =
Knowledge Capsule

A capsule is not the expert itself.
It is the programmable boundary through which knowledge and expertise become available to the runtime.

5.2 Why the Capsule Exists

Consider three very different computational capabilities.

Clinical knowledge.

Knowledge:
    rib retractions are an
    escalation-relevant sign

Expertise:
    clinical pathway evaluator

Trajectory prediction.

Knowledge:
    trajectory history
    vessel context
    learned motion patterns

Expertise:
    trajectory predictor

Formal verification.

Knowledge:
    system specification
    invariants
    candidate plan

Expertise:
    formal verifier

The internal computations are entirely different.

Yet the Knowledge Runtime needs to ask common questions:

When does this capability apply?
What knowledge does it require?
Are those requirements currently satisfied?
How is the computation invoked?
What kind of result will it produce?
How should that result alter understanding?
What authority may that result carry?

The capsule provides a common declaration of these semantics without forcing every expert to share one internal implementation.

5.3 The Capsule Is an Abstraction Boundary

                  Knowledge Capsule
        ┌──────────────────────────────────┐
        │ identity                         │
        │ knowledge                        │
        │ scope                            │
        │ applicability                    │
        │ requirements                     │
        │ expertise binding                │
        │ result semantics                 │
        │ authority                        │
        │ provenance                       │
        └──────────────────────────────────┘
                       │
                       ↓
                Knowledge Runtime
                       │
                 ACTIVATE / APPLY
                       │
                       ↓
               Computational Expert
                       │
           ┌───────────┼───────────┐
           ↓           ↓           ↓
          LLM       Predictor    Planner
           ↓           ↓           ↓
        Solver      Simulator    Verifier
                       │
                       ↓
                    Result
                       │
                       ↓
                    ABSORB
                       │
                       ↓
                  AUTHORIZE

The capsule hides unnecessary implementation detail while exposing what the runtime needs to know.

A trajectory capsule need not contain a trained transformer's weights. It may reference a model endpoint or Python implementation.

A planning capsule need not implement search. It may provide planning knowledge and bind to an existing planner.

A verification capsule may reference a formal specification and bind to an external model checker.

The capsule packages computational semantics, not necessarily computational machinery.

5.4 Knowledge, Capsule, Expert, and Result

These four concepts should remain distinct.

Concept	Purpose
Knowledge Object	Represents something known, observed, predicted, proposed, assumed, required, or established.
Knowledge Capsule	Declares how a body of knowledge and associated expertise may participate in runtime computation.
Computational Expert	Performs the specialized computation.
Expert Result	Represents what that computation produced and claims to establish.

For example:

Knowledge Objects:
    recent vessel positions
    timestamps
    vessel class

Knowledge Capsule:
    trajectory_prediction

Computational Expert:
    trajectory-transformer-v7

Expert Result:
    predicted future track

The result can then become new knowledge through ABSORB.

5.5 General Knowledge and Runtime Binding

A Knowledge Capsule should normally declare general knowledge independently of any particular runtime subject.

For example, this is poor design:

id: respiratory-rule-child-17

if:
    child-17 has rib retractions

then:
    child-17 has respiratory distress

The domain knowledge has been incorrectly fused with one runtime instance.

Instead:

id: respiratory-retractions

knowledge:
    if:
        subject has intercostal retractions

    then:
        respiratory distress concern supported

At runtime:

$subject = child-17

The same capsule may later apply to:

$subject = child-31
$subject = child-82
...

General knowledge is declared once.
The Knowledge Runtime binds it to the current entities and situation when ACTIVATE determines that it applies.

5.6 Anatomy of a Knowledge Capsule

A capsule should remain small enough to understand and general enough to represent very different forms of knowledge computation.

Identity

Every capsule needs stable identity for registration, lookup, versioning, dependency tracking, and traceability.

id: pediatric-respiratory-assessment
version: 1.2

Knowledge

The capsule identifies the knowledge it embodies, references, or expects to use.

Knowledge may include:

rules;
constraints;
guidelines;
planning models;
formal specifications;
equations;
feature definitions;
model identity;
historical or contextual knowledge requirements;
or references to external knowledge resources.

Scope

Scope declares where the capsule is intended to apply.

scope:
    domain: pediatric_care
    age:
        min: 0
        max: 17

For a specialized model:

scope:
    domain: maritime_trajectory
    observation_interval:
        max_seconds: 300
    vessel_classes:
        - cargo
        - tanker
        - fishing

Applicability

Applicability determines when the capsule becomes relevant to the current understanding.

applicable_when:
    respiratory_concern == true

Or:

applicable_when:
    future_motion_required == true
    and trajectory_history_available == true

Requirements

Applicability and readiness are different.

A capsule may be relevant but lack inputs required for APPLY.

requires:
    - respiratory_status

Or:

requires:
    - trajectory_window
    - timestamps
    - vessel_context

Missing requirements become explicit knowledge gaps rather than silent defaults.

Expertise Binding

The capsule identifies how the computation should be performed.

expertise:
    kind: python
    binding:
        knaitai_examples.respiratory.evaluate

Or:

expertise:
    kind: model
    binding:
        trajectory-transformer-v7

Or:

expertise:
    kind: external
    binding:
        formal-verification-service

The binding is deliberately abstract enough that execution infrastructure may change without rewriting domain knowledge.

Result Semantics

The capsule declares what kind of result the expert produces.

result:
    type: clinical_assessment
    establishes:
        respiratory_distress_status

Or:

result:
    type: prediction
    establishes:
        future_trajectory

This allows ABSORB to interpret results correctly.

Authority

A capsule may also declare how its result may influence the system.

authority:
    role: constraining

Or:

authority:
    role: advisory

Or:

authority:
    role: verifying
    required_for:
        execute_maneuver

Provenance

Provenance records where the capsule's knowledge and semantics came from.

This may include:

source document;
guideline edition;
model version;
training or validation information;
author or institution;
software version;
or human approver.

5.7 A Minimal Declarative Representation

A capsule should be declarable independently of application code wherever practical.

For example:

id: pediatric-respiratory-assessment
version: "1.0"

title: Pediatric respiratory assessment

scope:
  domain: pediatric_care
  age_max: 17

applicable_when:
  respiratory_concern: true

requires:
  - work_of_breathing

knowledge:
  guideline:
    rib_retractions:
      supports: respiratory_distress

expertise:
  kind: python
  binding: caretrace.respiratory.evaluate

result:
  type: clinical_assessment

authority:
  role: constraining

provenance:
  source: pediatric-triage-guidance

This declaration contains no patient-specific identifier.

At runtime:

case:
    subject = child-17

understanding:
    respiratory_concern = true
    work_of_breathing = intercostal_retractions

The runtime binds the general capsule to the current case.

5.8 A Minimal Python Representation

The same abstraction can be represented as validated Python data.

from pydantic import BaseModel
from typing import Any


class KnowledgeCapsule(BaseModel):

    id: str
    version: str

    title: str

    scope: dict[str, Any] = {}

    applicability: dict[str, Any] = {}

    requirements: list[str] = []

    knowledge: dict[str, Any] = {}

    expertise: dict[str, Any]

    result_semantics: dict[str, Any]

    authority: dict[str, Any] = {}

    provenance: dict[str, Any] = {}

This model is intentionally compact.

The purpose of the base abstraction is not to encode every possible domain concept. It is to define the common contract required by the Knowledge Runtime.

Implementation Principle.
Prefer one small general capsule abstraction over a large hierarchy of domain-specific capsule classes.

5.9 Do Not Turn Every Runtime Object into a Capsule

The earlier formulation of Knowledge Capsules can tempt an implementation toward classes such as:

ObservationCapsule
HypothesisCapsule
PredictionCapsule
QuestionCapsule
UncertaintyCapsule
RecommendationCapsule
ExplanationCapsule
...

That is usually unnecessary.

An observation, hypothesis, prediction, plan, question, or verification result is better understood primarily as a knowledge object or runtime result.

A capsule is useful when there is something reusable to declare about how knowledge and expertise participate.

For example:

Thing	Preferred abstraction
“Child has a fever”	Knowledge object / observation
“Possible respiratory distress”	Knowledge object / hypothesis or assessment
Predicted vessel path	Knowledge object / prediction
General pediatric respiratory assessment logic	Knowledge Capsule
Trajectory predictor and its applicability semantics	Knowledge Capsule
Planning domain + planner binding	Knowledge Capsule
Formal specification + verifier binding	Knowledge Capsule

Capsules package reusable computational expertise.
They need not become wrappers around every piece of runtime state.

5.10 Capsules and Computational Experts

A capsule describes expertise. A computational expert performs it.

A simple expert interface might be:

class ComputationalExpert:

    def apply(
        self,
        context
    ) -> ExpertResult:
        ...

The implementation may be local:

class PythonExpert(ComputationalExpert):

    def __init__(self, fn):
        self.fn = fn

    def apply(self, context):
        return self.fn(context)

Or remote:

class ExternalExpert(ComputationalExpert):

    def apply(self, context):
        return call_external_service(
            context
        )

Or neural:

class LLMExpert(ComputationalExpert):

    def apply(self, context):
        return call_foundation_model(
            context
        )

KnaiTai should not require all experts to inherit literally from one Python class. Protocols, adapters, service contracts, or existing orchestration systems may implement the same abstraction.

5.11 Capsules Through A4

The cleanest way to understand a capsule is through the four runtime operations.

ACTIVATE

ACTIVATE evaluates whether the capsule's knowledge and expertise matter in the current understanding.

activation = runtime.activate(
    capsule,
    understanding
)

Possible outcomes might include:

ACTIVE
INACTIVE
NOT_READY
OUT_OF_SCOPE

If applicable but missing requirements:

NOT_READY

missing:
    work_of_breathing

The missing requirement becomes part of the runtime understanding.

APPLY

If activated and ready, APPLY invokes the expertise bound by the capsule.

result = runtime.apply(
    capsule,
    understanding
)

The underlying expert may be a rule evaluator, predictor, planner, LLM, solver, simulator, or external service.

ABSORB

ABSORB interprets the expert result according to the capsule's declared result semantics.

understanding = runtime.absorb(
    understanding,
    result
)

A prediction remains a prediction.

A proposed plan remains a proposed plan.

A successful formal verification may establish a verified property.

A failed constraint may invalidate an action.

AUTHORIZE

AUTHORIZE evaluates whether the updated understanding satisfies a decision or action boundary.

authority = runtime.authorize(
    target="home_monitoring",
    understanding=understanding
)

The capsule may contribute to that authority without itself owning the final decision.

5.12 Result Semantics Matter

Different experts may return structurally similar values that mean very different things.

Consider:

{
    "safe": true
}

That result might mean:

an LLM believes an action is safe;
a statistical classifier predicts safety with probability 0.94;
a deterministic checker found no configured violation;
or a formal verifier established a property under stated assumptions.

The surface value is identical. The epistemic meaning is not.

Expert results must carry semantics, not merely values.

A minimal result might therefore contain:

ExpertResult

    expert_id
    result_type
    payload
    epistemic_status
    provenance
    assumptions
    dependencies
    validity_scope

ABSORB uses this information to determine what the result can legitimately change.

5.13 Authority Belongs in the Contract

A major purpose of the capsule abstraction is to prevent all computational expertise from being treated as equally authoritative.

A useful initial authority vocabulary might include:

ADVISORY
SUPPORTING
VERIFYING
CONSTRAINING
AUTHORIZING

These labels need not imply one universal policy engine. They communicate how a result may participate.

Trajectory predictor.

authority:
    ADVISORY

The prediction changes understanding but does not independently authorize a maneuver.

Clinical safety requirement.

authority:
    CONSTRAINING

Failure of the requirement can prevent a home-monitoring recommendation.

Formal safety verifier.

authority:
    VERIFYING

required_for:
    execute_plan

The verified result may satisfy one mandatory condition for execution authority.

5.14 Capsules Can Describe Neural Expertise Too

Knowledge Capsules should not become synonymous with symbolic knowledge.

An LLM can participate through the same abstraction.

id: general-clinical-reasoner

scope:
    domain: caregiver_assistance

expertise:
    kind: llm
    binding: frontier-medical-model

requires:
    - current_conversation
    - understanding_state

result:
    type: clinical_interpretation

authority:
    role: advisory

In another application, the same model may have greater authority.

The capsule abstraction therefore does not encode a neural-versus-symbolic hierarchy.

The LLM is one computational expert.
Use it aggressively wherever its expertise is sufficient.

5.15 Capsules Can Describe Specialized Computation

The same abstraction becomes especially useful for computation that should not be reduced to general language reasoning.

Trajectory Prediction

id: vessel-trajectory-predictor

scope:
    domain: maritime_motion

applicable_when:
    future_motion_required: true

requires:
    - trajectory_window
    - timestamps
    - vessel_context

expertise:
    kind: python
    binding: maritime.predictor.predict

result:
    type: trajectory_prediction

authority:
    role: advisory

Planning

id: operational-planner

applicable_when:
    goal_requires_multistep_action: true

requires:
    - current_state
    - goal
    - action_model

knowledge:
    - actions
    - preconditions
    - effects

expertise:
    kind: external
    binding: planner-service

result:
    type: candidate_plan

authority:
    role: advisory

Formal Verification

id: maneuver-safety-verifier

applicable_when:
    candidate_plan_available: true

requires:
    - candidate_plan
    - safety_specification

expertise:
    kind: external
    binding: verifier-service

result:
    type: verification_result

authority:
    role: verifying
    required_for:
        execute_maneuver

5.16 A Capsule Registry

The runtime needs a way to discover available capsules.

A minimal registry might support:

registry.register(capsule)

registry.get(capsule_id)

registry.list()

registry.candidates(
    understanding
)

The registry is not the activation engine.

It makes expertise discoverable. ACTIVATE determines what actually matters.

Capsule Registry
      ↓
candidate capsules
      ↓
ACTIVATE
      ↓
relevant / applicable /
required expertise

5.17 Declarative and Programmatic Expertise Share One Runtime

Knowledge Native programming should support both declarative and programmatic definitions without creating two disconnected architectures.

YAML / JSON
    ↓
KnowledgeCapsule
    ↓
Registry
    ↓
A4 Runtime

And:

Python function / model / service
    ↓
ComputationalExpert binding
    ↓
KnowledgeCapsule
    ↓
Registry
    ↓
A4 Runtime

For example:

def predict_trajectory(context):

    history = context.require(
        "trajectory_window"
    )

    return ExpertResult(
        result_type="trajectory_prediction",
        payload=predict(history),
        epistemic_status="predicted"
    )

The capsule declares when and why this function participates.

The Python function implements the actual specialized expertise.

5.18 Capsules and Existing Orchestration

A capsule does not need to tell KnaiTai how to manage queues, retries, network calls, parallel execution, agent messaging, or distributed scheduling.

The runtime might determine:

maneuver-safety-verifier

    REQUIRED NOW

An orchestration layer may then determine:

service location
authentication
retry policy
timeout
parallel execution
resource allocation

The result returns to the Knowledge Runtime for ABSORB.

Capsules declare computational meaning.
Existing orchestration infrastructure can handle computational mechanics.

5.19 Versioning and Revision

Knowledge Capsules themselves may evolve.

A clinical guideline changes. A predictor is retrained. A model's validated scope changes. A safety specification is revised.

Capsule versions should therefore be explicit:

trajectory-predictor:1.4
        ↓ superseded_by
trajectory-predictor:1.5

Historical traces should retain which capsule and expert version actually participated in a computation.

Recommended Default.
Treat semantic capsule revisions as versioned declarations rather than silently mutating the definition used by earlier computations.

Runtime state is different. Activation status, current bindings, execution attempts, and task-local bookkeeping may change freely without creating a new semantic capsule version.

5.20 Dependencies Belong to Results and Understanding

Earlier capsule designs can overburden the capsule itself with every downstream dependency.

A cleaner model separates:

the reusable capsule declaration;
the expert invocation;
the expert result;
and the dependencies created when that result is absorbed.

For example:

trajectory observations
        ↓
APPLY trajectory capsule
        ↓
prediction result
        ↓
ABSORB
        ↓
collision hypothesis

dependency:
    collision hypothesis
    depends_on prediction result

The general trajectory capsule itself does not suddenly become dependent on one particular vessel observation.

Keep reusable expertise separate from case-specific dependency state.

5.21 Running Example I: Caregiver Assistance

Consider a small CareTrace-style application.

The frontier model handles the natural dialogue and broad clinical reasoning.

One selected piece of clinical knowledge receives explicit computational authority.

Capsule Declaration

id: home-monitoring-readiness

scope:
  domain: pediatric_caregiver

applicable_when:
  requested_disposition: home_monitoring

requires:
  - responsiveness
  - hydration_status
  - respiratory_status

expertise:
  kind: python
  binding: caretrace.disposition.evaluate

result:
  type: disposition_readiness

authority:
  role: constraining

Current Runtime State

subject:
    child-17

responsiveness:
    adequate

hydration_status:
    adequate

respiratory_status:
    UNKNOWN

ACTIVATE

The caregiver asks:

Can I monitor her at home tonight?

The home-monitoring capsule becomes applicable.

Requirements Check

responsiveness      ✓
hydration_status    ✓
respiratory_status  ?

The capsule is applicable but not ready for APPLY.

The runtime exposes:

knowledge_gap:
    respiratory_status

Dialogue

The conversational expert asks about breathing.

The caregiver eventually reports:

I can see the skin pulling in a little between her ribs.

ABSORB Observation

intercostal_retractions = true

This makes a respiratory-assessment capsule applicable.

APPLY Respiratory Expertise

result:
    respiratory_distress_concern

authority:
    constraining

ABSORB + AUTHORIZE

home_monitoring:
    BLOCKED

prompt_evaluation:
    RECOMMENDABLE

The LLM might independently reach exactly the same conclusion.
The value of the capsule is that this application chose not to leave this particular authority boundary entirely to model discretion.

5.22 Running Example II: Trajectory Prediction

Now consider a case in which specialized expertise performs the substantive computation.

Capsule

id: trajectory-prediction

scope:
  domain: maritime

applicable_when:
  future_motion_required: true

requires:
  - trajectory_window
  - timestamps

expertise:
  kind: python
  binding: maritime.predict

result:
  type: trajectory_prediction

authority:
  role: advisory

Runtime

ACTIVATE
    trajectory-prediction

APPLY
    maritime.predict(...)

RESULT
    future_track

ABSORB
    future_track as prediction

ACTIVATE
    collision-assessment

The capsule does not contain the prediction algorithm.

It tells the runtime when trajectory expertise matters, what it requires, how it is bound, and how to interpret its result.

5.23 Running Example III: Planning and Verification

Capsules also allow different expertise to participate sequentially without turning KnaiTai into a workflow engine.

Planning Capsule
    ↓
ACTIVATE
    ↓
APPLY planner
    ↓
candidate plan
    ↓
ABSORB
    ↓
Verification Capsule
    becomes applicable
    ↓
APPLY verifier
    ↓
verified / failed
    ↓
ABSORB
    ↓
AUTHORIZE execution

The execution framework may physically call the planner and verifier.

KnaiTai preserves why each computation became required and what its result established.

5.24 A Minimal Public Python API

From an application developer's perspective, the package should remain simple.

from knaitai import Runtime
from knaitai.experts import PythonExpert


runtime = Runtime()

runtime.load_capsules(
    "knowledge/"
)


runtime.register_expert(
    "trajectory_predictor",
    PythonExpert(
        predict_trajectory
    )
)


case = runtime.new_case(
    subject="vessel-204"
)


case.observe(
    trajectory_window=history
)


state = case.update()

The developer should not need to manage internal registries, dependency graphs, trace stores, or execution bookkeeping directly.

The runtime should expose them when inspection is needed, but hide them during ordinary use.

5.25 A Minimal v0.1 Architecture

A first implementation does not need dozens of capsule kinds or a large expert ecosystem.

A useful v0.1 can contain:

knaitai/

    capsule.py
        KnowledgeCapsule

    knowledge.py
        KnowledgeObject

    experts.py
        ComputationalExpert
        PythonExpert

    registry.py
        CapsuleRegistry
        ExpertRegistry

    understanding.py
        UnderstandingState

    runtime.py
        ACTIVATE
        APPLY
        ABSORB
        AUTHORIZE

    trace.py
        execution and dependency trace

    loaders.py
        YAML / JSON capsule loading

The minimal proof should demonstrate:

one declarative knowledge capsule;
one Python-backed specialized expert;
runtime applicability and requirements;
structured expert results;
ABSORB changing understanding;
AUTHORIZE granting or withholding authority;
and a trace showing what actually happened.

5.26 What Not to Build Into the Capsule

A capsule should not become a miniature application framework.

Avoid placing inside the abstraction:

workflow scheduling;
network retries;
agent messaging;
model-routing strategy;
database implementation;
UI behavior;
arbitrary business logic;
or the entire internal implementation of specialized experts.

These concerns may be referenced or adapted, but they belong beneath or outside the capsule abstraction.

A capsule should say what expertise means to the Knowledge Runtime, not how the entire surrounding software system works.

5.27 Common Design Mistakes

Making Everything a Capsule

Observations, predictions, hypotheses, questions, and plans are frequently better represented as knowledge objects or expert results. Capsules should package reusable knowledge computation.

Making Capsules Domain-Specific Classes

A hierarchy containing dozens of capsule subclasses quickly hard-codes domain semantics into the infrastructure.

Prefer a small general schema with domain-specific declarations.

Putting the Expert Inside the Capsule

A capsule may reference or bind to an implementation, but the abstraction should not require a model, planner, solver, or service to live physically inside it.

Confusing Applicability with Readiness

An expert may be relevant while required inputs remain missing.

Confusing Result with Truth

A predictor returns a prediction. An LLM may return a hypothesis. A planner returns a candidate plan. The runtime must preserve these distinctions.

Giving Every Expert Equal Authority

Expertise should participate according to its declared computational role and the application's authority requirements.

Hard-Coding Runtime Subjects into General Knowledge

A rule about rib retractions should be general. The runtime binds that rule to child-17 when appropriate.

Rebuilding Existing Orchestration

KnaiTai should determine why expertise is required and what its result means. Existing infrastructure can execute the underlying work.

Reintroducing an Operator Zoo

The capsule should fit cleanly into the stable A4 abstraction:

ACTIVATE
APPLY
ABSORB
AUTHORIZE

Prediction, planning, verification, support, challenge, constraint checking, and similar capabilities belong under APPLY or in result semantics.

5.28 The Capsule as a Core Programming Abstraction

The full relationship can now be summarized as:

INFORMATION
      ↓
knowledge construction
      ↓
KNOWLEDGE OBJECTS
      ↓
current understanding
      ↓

KNOWLEDGE CAPSULES
declare:
    what knowledge matters
    when it applies
    what expertise uses it
    what results mean
    what authority may follow

      ↓

KNOWLEDGE RUNTIME

    ACTIVATE
       ↓
     APPLY
       ↓
     ABSORB
       ↓
   AUTHORIZE

      ↓

COMPUTATIONAL EXPERTISE

LLM
predictor
planner
solver
simulator
verifier
algorithm
human

Central Thesis.
A Knowledge Capsule is the programmable declaration through which knowledge is connected to computational expertise and given runtime meaning.

The capsule does not replace the knowledge object, the expert, the runtime, or the orchestration system.

Its value comes precisely from connecting them while keeping their responsibilities separate.

Knowledge Native Thinking

When considering whether something should become a Knowledge Capsule, ask:

What reusable knowledge does this capsule represent or reference?
Under what conditions should it matter?
What runtime knowledge does it require?
What computational expertise can put that knowledge to work?
Where is that expertise implemented?
What kind of result will it return?
What does that result establish?
What authority should it have?
What provenance and version must be preserved?

Programming Shift.
Move from hard-wiring specialized computation into application workflows to declaring the knowledge semantics through which that expertise participates at runtime.

Chapter Summary

A knowledge object represents what is known; a Knowledge Capsule declares how reusable knowledge and computational expertise may participate in the runtime.
A computational expert performs the specialized computation; the capsule does not need to contain its implementation.
An expert result records what the computation produced and what it claims to establish.
Capsules package identity, knowledge, scope, applicability, requirements, expertise binding, result semantics, authority, and provenance.
General knowledge should remain independent of runtime subjects and be bound to concrete entities only when applicable.
Capsules can be declared in YAML, JSON, Python, or another suitable representation.
One general capsule abstraction is preferable to a large hierarchy of observation, question, hypothesis, prediction, and recommendation capsule classes.
Observations, hypotheses, predictions, plans, and verification outputs are usually knowledge objects or expert results rather than distinct capsule kinds.
Foundation models can participate as computational experts through the same abstraction as predictors, planners, solvers, simulators, and verifiers.
ACTIVATE determines whether capsule knowledge and expertise matter now.
APPLY invokes the appropriate computational expertise.
ABSORB interprets the result and changes the evolving understanding.
AUTHORIZE evaluates whether the resulting understanding permits a recommendation, decision, or action.
Applicability and execution readiness are distinct because required knowledge may still be missing.
Result semantics preserve distinctions among observations, hypotheses, predictions, plans, and verified properties.
Authority belongs in the capsule contract because different expertise should exert different computational influence.
Dependencies created by one particular computation belong primarily to runtime results and understanding, not to the reusable capsule definition.
Capsule definitions should be versioned so historical computations remain reconstructable.
Existing workflow and agent infrastructure can execute expert calls while KnaiTai preserves their knowledge semantics.
The capsule is a core programming abstraction for connecting knowledge to heterogeneous computational expertise.

Discussion Questions

Why should a Knowledge Capsule be distinct from both a knowledge object and a computational expert?
What information must a capsule expose for the Knowledge Runtime to use it correctly?
Why should general domain knowledge remain independent of runtime subjects?
When should a runtime result become a knowledge object rather than a new capsule?
Why is one general capsule abstraction preferable to many domain-specific capsule subclasses?
How should a capsule distinguish applicability from execution readiness?
Why are result semantics necessary even when an expert returns structured data?
How should authority differ among an LLM, predictor, planner, constraint checker, and formal verifier?
What should be declarative in a capsule and what should remain in executable code?
How can capsules reference external experts without becoming an orchestration framework?
When does a change require a new capsule version rather than only an update to runtime state?
Which aspects of an existing AI application could be expressed as capsules without rewriting the underlying models and workflows?

Exercises

Exercise 5.1: Separate the Four Concepts

For one application, identify:

three knowledge objects;
one Knowledge Capsule;
one computational expert;
and one expert result.

Explain why each belongs to that abstraction.

Exercise 5.2: Declare a General Capsule

Write a YAML capsule containing general domain knowledge, applicability, requirements, expertise binding, result semantics, authority, and provenance. Do not include any runtime subject identifier.

Exercise 5.3: Bind General Knowledge at Runtime

Create two runtime subjects and show how the same general capsule can become applicable to one, both, or neither depending on their current understanding states.

Exercise 5.4: Implement a Python Expert

Implement a small Python function that accepts structured runtime context and returns a typed ExpertResult. Register it as the expertise binding of a capsule.

Exercise 5.5: Preserve Result Semantics

Create three results containing superficially similar values but produced respectively by an LLM, a predictor, and a verifier. Specify the epistemic status and permitted authority of each.

Exercise 5.6: Model Missing Requirements

Create a capsule that is applicable but cannot yet run because one required input is unknown. Show how the runtime represents the missing knowledge and what becomes possible after the requirement is satisfied.

Exercise 5.7: Run an A4 Cycle

Using one capsule and one computational expert, trace:

ACTIVATE
    ↓
APPLY
    ↓
ABSORB
    ↓
AUTHORIZE

State exactly what changes at each stage.

Exercise 5.8: Add a Verifier

Create a second capsule whose expertise verifies the first expert's result. Require the verification result before AUTHORIZE grants a consequential action.

Exercise 5.9: Separate Runtime Dependencies

Show why a prediction result may depend on one case's observations while the reusable prediction capsule itself does not. Represent both dependency structures correctly.

Exercise 5.10: Replace an Expert Implementation

Replace the implementation binding of one capsule, such as changing a simple Python predictor to a trained model or remote service. Identify what parts of the Knowledge Native program should remain unchanged.