SDS-024: Thermodynamic Substrate Service

Status: Draft
Version: 1.0
Date: 2025-12-30
Satisfies: PRD-005, ADR-025
Bounded-Context: shared

0. Isomorphism Declaration

Spec Section SEA-DSL Target Cardinality Verification
3.1 Energy Vector Value Object schema 1:1 Field names + types match
4.1 Cost Dimensions Entity schema 1:1 Formula expressions match
6.1 Substrate State Entity schema 1:1 Field names + types match
6.2 Consumption Record Entity schema 1:1 Field names + types match
7. Heat Death Levels Policy nodes 1:1 Threshold expressions match
8. API Contract Flow @command/@query 1:1 Input/output schema identical

0.1 Domain Glossary

Term Definition Type Canonical?
Substrate The finite resource pool (compute, capital, attention) consumed by work Entity ✓
Energy Vector Three-component vector [u_compute, u_capital, u_attention] Value Object ✓
Work Function Mapping from artifact to resource cost W(a) Algorithm ✓
Feasibility Check Pre-flight validation that substrate can afford the artifact cost Algorithm ✓
Capacity Alert Threshold-triggered warning when resources are low Entity ✓
Heat Death System state where substrate is depleted (0% capacity) State ✓
Replenishment Inflow of resources (revenue, rest, budget reset) Event ✓

1. System Overview

The Thermodynamic Substrate Service is the Body of the Cognitive Architecture. It manages the Finite Resources that the system consumes to perform work.

It serves as:

2. Core Principle

The system cannot perform work without consuming the Substrate.

1

U_{t+1} = U_t - Σ W(a_i) + R_inflow

Where:

3. Substrate Components

3.1 Energy Vector

The Substrate is modeled as a vector of resources:

1

U_t = [u_compute, u_capital, u_attention]^T
Component Description Unit Replenishment
u_compute Silicon processing power Tokens / GPU-hours API budget
u_capital Financial energy Currency Revenue
u_attention Human cognitive capacity Focus-hours Rest/Recovery

3.2 Feasibility Condition

An artifact can only be reified if the Substrate can afford it:

1
2
3
4

def is_feasible(artifact: Artifact, substrate: Substrate) -> bool:
    """F(a, U_t) = 1 if W(a) ≤ U_t, else 0"""
    cost = calculate_cost(artifact)
    return all(cost[i] <= substrate.capacity[i] for i in range(len(cost)))

4. Work Function

The Work Function W(a) maps an artifact to its resource cost.

4.1 Cost Dimensions

1
2
3
4
5
6
7
8
9
10
11
12

work_function:
  compute_cost:
    formula: 'token_count × model_cost_per_token'
    example: '5000 tokens × $0.002 = $10'

  capital_cost:
    formula: 'infrastructure_time × hourly_rate + external_services'
    example: '2 hours × $50 + $20 = $120'

  attention_cost:
    formula: 'review_time + decision_points × decision_cost'
    example: '1 hour + 3 decisions × 0.25 hours = 1.75 focus-hours'

4.2 Cost Estimation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

@dataclass
class ArtifactCost:
    compute: float  # Tokens
    capital: float  # Currency
    attention: float  # Focus-hours

def estimate_cost(intention: Intention, spec: Spec) -> ArtifactCost:
    """Estimate resource consumption before execution."""
    complexity = analyze_complexity(intention, spec)

    return ArtifactCost(
        compute=complexity.token_estimate,
        capital=complexity.infra_cost + complexity.services_cost,
        attention=complexity.review_time + (complexity.decision_points * 0.25)
    )

5. Consumption Protocol

5.1 Pre-flight Check

Before any artifact is reified, the Compiler MUST check feasibility:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

def pre_flight_check(artifact: Artifact, substrate: Substrate) -> Result:
    cost = estimate_cost(artifact)

    if not is_feasible(cost, substrate):
        return Result.REJECTED(
            reason="HEAT_DEATH_PREVENTION",
            deficit={
                "compute": max(0, cost.compute - substrate.compute),
                "capital": max(0, cost.capital - substrate.capital),
                "attention": max(0, cost.attention - substrate.attention)
            }
        )

    return Result.APPROVED(cost=cost)

5.2 Consumption

On successful reification, consume the substrate:

1
2
3
4
5
6

def consume(substrate: Substrate, cost: ArtifactCost) -> Substrate:
    return Substrate(
        compute=substrate.compute - cost.compute,
        capital=substrate.capital - cost.capital,
        attention=substrate.attention - cost.attention
    )

5.3 Replenishment

The substrate is replenished over time:

1
2
3
4
5
6

def replenish(substrate: Substrate, inflow: SubstrateInflow) -> Substrate:
    return Substrate(
        compute=substrate.compute + inflow.compute_budget,
        capital=substrate.capital + inflow.revenue,
        attention=min(substrate.attention + inflow.rest_recovery, MAX_ATTENTION)
    )

6. Data Model

6.1 Substrate State

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

substrate_state:
  timestamp: '2025-12-22T10:00:00Z'
  capacity:
    compute:
      current: 50000 # tokens
      max: 100000
      unit: 'tokens'
    capital:
      current: 5000.00 # USD
      max: 10000.00
      unit: 'USD'
    attention:
      current: 30.0 # focus-hours
      max: 40.0
      unit: 'focus-hours'

  replenishment_schedule:
    compute: 'weekly'
    capital: 'monthly'
    attention: 'daily'

6.2 Consumption Record

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

consumption_record:
  id: 'consumption-uuid'
  artifact_id: 'artifact-uuid'
  timestamp: '2025-12-22T10:00:00Z'
  cost:
    compute: 1500
    capital: 50.00
    attention: 0.5
  substrate_before:
    compute: 50000
    capital: 5000.00
    attention: 30.0
  substrate_after:
    compute: 48500
    capital: 4950.00
    attention: 29.5

6.3 Capacity Alert

1
2
3
4
5
6
7
8

capacity_alert:
  id: 'alert-uuid'
  timestamp: '2025-12-22T10:00:00Z'
  severity: 'WARNING' # INFO | WARNING | CRITICAL
  component: 'attention'
  current: 5.0
  threshold: 10.0
  recommendation: 'Reduce scope or defer low-priority work'

7. Heat Death Prevention

7.1 Threshold Alerts

Level Threshold Action
Green > 50% capacity Normal operations
Yellow 25-50% capacity Route only Tier 1 (Existential) work
Red < 25% capacity Emergency mode: Defer all non-critical
Black 0% capacity System pause: No reification allowed

7.2 Emergency Protocols

When substrate reaches critical levels:

  1. Defer Queue: Move Tier 2/3 work to deferred queue
  2. Lean Mutation: Trigger Evolutionary Kernel to propose low-cost Spec mutations
  3. Resource Advocacy: Notify Sovereign of capacity crisis

8. API Contract

8.1 Get Substrate Status

1

GET /substrate/status

Response:

1
2
3
4
5
6
7
8
9
10

{
  "timestamp": "2025-12-22T10:00:00Z",
  "capacity": {
    "compute": { "current": 48500, "max": 100000, "percent": 48.5 },
    "capital": { "current": 4950.0, "max": 10000.0, "percent": 49.5 },
    "attention": { "current": 29.5, "max": 40.0, "percent": 73.75 }
  },
  "health": "GREEN",
  "alerts": []
}

8.2 Check Feasibility

1

POST /substrate/feasibility

Request:

1
2
3
4
5
6
7

{
  "estimated_cost": {
    "compute": 1500,
    "capital": 200.0,
    "attention": 2.0
  }
}

Response:

1
2
3
4
5
6
7
8
9

{
  "feasible": true,
  "remaining_after": {
    "compute": 47000,
    "capital": 4750.0,
    "attention": 27.5
  },
  "warnings": []
}

8.3 Record Consumption

1

POST /substrate/consume

Request:

1
2
3
4
5
6
7
8

{
  "artifact_id": "uuid",
  "actual_cost": {
    "compute": 1450,
    "capital": 180.0,
    "attention": 1.75
  }
}

Response:

1
2
3
4
5
6
7
8

{
  "consumption_id": "uuid",
  "new_capacity": {
    "compute": 47050,
    "capital": 4770.0,
    "attention": 27.75
  }
}

8.4 Record Replenishment

1

POST /substrate/replenish

Request:

1
2
3
4
5
6
7
8

{
  "source": "monthly_budget_reset",
  "inflow": {
    "compute": 50000,
    "capital": 5000.0,
    "attention": 0
  }
}

9. Integration with Evolutionary Kernel

When the substrate is under pressure, the Kernel is notified:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

async def on_substrate_critical(substrate: Substrate, kernel: EvolutionaryKernel):
    """Trigger Lean Mutation when resources are low."""
    trauma = TraumaSignal(
        category="THERMODYNAMIC_CRISIS",
        magnitude=calculate_depletion_rate(substrate)
    )

    # Request mutations that reduce Entropy (cost) while maintaining Value
    mutations = await kernel.generate_lean_mutations(trauma)

    # Auto-apply minor mutations; escalate major ones to Sovereign
    for mutation in mutations:
        if mutation.is_minor:
            await kernel.apply_mutation(mutation)
        else:
            await notify_sovereign(mutation)

ADRs

PRDs

Other SDS

References