executive: deliberation, state-query, roll-up, peer-alarm faculties + foundation

CHANGELOG.md

@@ -84,6 +84,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added (v0.3.0 candidate)
 
+- **Executive faculties** (`substrate.executive`) — the decision/reasoning layer on
+  the band foundation:
+  - **Temporal authority** — `SustainedLoadTracker` Protocol + `EwmaLoadTracker`
+    (EWMA + consecutive-breach): the sole SPIKE-vs-SUSTAINED authority, so the
+    pivot and damage/debt fire by *duration* (a transient peak is absorbed).
+  - **Scale** — `ExecutiveScale` / `ScaleAxis` + `axis_of` / `physical_parent` /
+    `entity_parent`: the entity / physical (cell→rack→zone→region) / grouping
+    roll-up axes.
+  - **Deliberation + perspective-taking** (`deliberate`) — roll out N candidate
+    actions, score each affected entity's impact *from its own frame*
+    (care-weight × φ-proportioned trajectory), disqualify floor-harm and
+    net-negative-long-cycle extraction, surface trade-offs, pick the arg-max
+    long-horizon net-potential-gain action.
+  - **State query** (`integrate_state`) — integrate a load history into energy /
+    effort (slacking = avoidance) / trajectory over time + a human-readable
+    summary.
+  - **Scale roll-up** (`roll_up`) — aggregate member loads up a parent scale →
+    distribution, worst member, over-load/idle failure-tell fractions.
+  - **Peer awareness + alarm propagation** (`correlate_anomalies` / `assess_alarm`)
+    — herd-panic correlation (N peers weird together ⇒ the enclosing scale has a
+    problem) + trust × independent-corroboration alarm weighting with the
+    panic-injection guard.
+  - **Observed-graph extraction detection** (`detect_extraction`) — the substrate
+    calculus over an observed relationship graph; flags predators vs supporters.
+  91 conformance tests; pyright clean; pylint 10.00.
+
 - **Executive band package** (`substrate.executive`) — the resistance band made
   operational as a decision engine. Two named lenses on one utilization value —
   `LoadZone` (the load lens: IDLE/RECREATION/WORK/PEAKING/WARNING/DANGER on the

python/src/substrate/executive/__init__.py

@@ -2,13 +2,16 @@
 
 The resistance band, made operational as the substrate's executive function: the
 corrected symmetric ladder (geometric levels, temporal consequences), the
-quantity/scale discipline that keeps "what percentage is this and what does it
-mean" precise, and the order metric that reads emergence from a distribution.
+quantity/scale discipline, the temporal sustained-vs-spike authority, and the
+faculties built on top — deliberation (scenario rollout + perspective-taking), the
+state query, the scale roll-up, peer awareness + alarm propagation, the order
+metric, and observed-graph extraction detection.
 
 Curated exports — import the names, not deep module paths.
 """
 from __future__ import annotations
 
+from substrate.executive._trajectory import TrajectoryClass
 from substrate.executive.band import (
     BAND_TOLERANCE,
     DEFAULT_BAND_PROFILE,
@@ -22,6 +25,17 @@
     validate_band_profile,
     zone_to_legacy,
 )
+from substrate.executive.deliberation import (
+    ActionDelta,
+    CandidateAction,
+    CandidateEvaluation,
+    DeliberationOutcome,
+    DeliberationResult,
+    EntityFrame,
+    PerspectiveImpact,
+    deliberate,
+    perspective_impact,
+)
 from substrate.executive.negentropy import (
     NegentropyDirection,
     NegentropyReport,
@@ -34,36 +48,112 @@
     NpgEdge,
     detect_extraction,
 )
+from substrate.executive.peer_alarm import (
+    AlarmAssessment,
+    AlarmDisposition,
+    HerdVerdict,
+    PeerAlarm,
+    PeerAnomaly,
+    assess_alarm,
+    correlate_anomalies,
+    heeded_alarms,
+)
 from substrate.executive.quantities import (
     Cycle,
     GrowthNotADecisionBand,
     Quantity,
     ResourceKind,
     setpoint_for,
 )
+from substrate.executive.roll_up import (
+    MemberLoad,
+    RollUpError,
+    ScaleAggregate,
+    roll_up,
+)
+from substrate.executive.scale import (
+    ExecutiveScale,
+    ScaleAxis,
+    axis_of,
+    entity_parent,
+    physical_parent,
+)
+from substrate.executive.state_query import (
+    EffortState,
+    EnergyState,
+    EntityStateReport,
+    StateObservation,
+    TrajectoryDirection,
+    integrate_state,
+)
+from substrate.executive.temporal import (
+    DEFAULT_EWMA_ALPHA,
+    DEFAULT_SUSTAIN_COUNT,
+    EwmaLoadTracker,
+    LoadTrend,
+    SustainedLoadTracker,
+)
 
 __all__ = [
     "BAND_TOLERANCE",
     "DEFAULT_BAND_PROFILE",
+    "DEFAULT_EWMA_ALPHA",
+    "DEFAULT_SUSTAIN_COUNT",
     "TWO_THIRDS",
+    "ActionDelta",
+    "AlarmAssessment",
+    "AlarmDisposition",
     "BandProfile",
     "BandProfileInvalid",
+    "CandidateAction",
+    "CandidateEvaluation",
     "Cycle",
     "CyclePhase",
+    "DeliberationOutcome",
+    "DeliberationResult",
+    "EffortState",
+    "EnergyState",
+    "EntityFrame",
     "EntityRollup",
+    "EntityStateReport",
+    "EwmaLoadTracker",
+    "ExecutiveScale",
     "ExtractionReport",
     "GrowthNotADecisionBand",
+    "HerdVerdict",
+    "LoadTrend",
     "LoadZone",
+    "MemberLoad",
     "NegentropyDirection",
     "NegentropyReport",
     "NpgEdge",
+    "PeerAlarm",
+    "PeerAnomaly",
+    "PerspectiveImpact",
     "Quantity",
     "ResourceKind",
+    "RollUpError",
+    "ScaleAggregate",
+    "ScaleAxis",
+    "StateObservation",
+    "SustainedLoadTracker",
+    "TrajectoryClass",
+    "TrajectoryDirection",
+    "assess_alarm",
+    "axis_of",
     "classify_cycle_phase",
     "classify_load_zone",
+    "correlate_anomalies",
+    "deliberate",
     "detect_extraction",
+    "entity_parent",
+    "heeded_alarms",
+    "integrate_state",
     "negentropy",
     "order_index",
+    "perspective_impact",
+    "physical_parent",
+    "roll_up",
     "setpoint_for",
     "validate_band_profile",
     "zone_to_legacy",

python/src/substrate/executive/_trajectory.py

@@ -0,0 +1,23 @@
+"""Potential-trajectory class — the perspective-taking input.
+
+An entity's potential-trajectory determines how the same raw impact reweights on
+the long horizon (a benefit to a high-future-potential DEVELOPING entity compounds;
+a harm to an accumulated-and-at-risk VULNERABLE one bites harder). A minimal,
+self-contained enum for the deliberation engine.
+"""
+from __future__ import annotations
+
+from enum import Enum
+
+
+class TrajectoryClass(str, Enum):
+    """The potential-trajectory class of an entity."""
+
+    DEVELOPING = "developing"      # high future potential (a child / seed)
+    ESTABLISHED = "established"    # at capacity
+    VULNERABLE = "vulnerable"      # accumulated + at risk (an elder / dependent)
+    STATIC = "static"             # spent / low remaining potential
+    UNKNOWN = "unknown"
+
+
+__all__ = ["TrajectoryClass"]