autonomic

The foundational, implementation-independent BEAM/OTP control plane for the Autonomic Kernel architecture.

What is this package?

autonomic provides the core runtime, authority governor, effect broker, homeostatic regulator, episode lifecycle supervisor, and normative contracts for running untrusted coding workers inside disposable execution domains while keeping durable authority in a trusted control plane.

When should I install it?

Install autonomic if you are:

• Building an autonomous coding workflow with BEAM/OTP.
• Implementing a custom execution domain backend (extending Autonomic.ExecutionDomain).
• Implementing a custom authority or persistence store (extending Autonomic.Store).
• Implementing custom semantic sensor banks (extending Autonomic.SemanticSensor).
• Authoring custom effect adapters (extending Autonomic.EffectAdapter).

If you need a turnkey execution stack on Ubuntu/Linux with PostgreSQL and TypeSafe sensors, combine autonomic with:

• autonomic_linux — Linux cgroup v2, namespace, and seccomp isolation domain.
• autonomic_postgres — PostgreSQL durable authority store and ledger.
• autonomic_typesafe — TypeSafe/Jev semantic sensor bank.

What does it depend on?

autonomic has zero dependencies on Linux, PostgreSQL, Ecto, or TypeSafeSDK. It depends strictly on standard BEAM utilities:

• finch (~> 0.23)
• jason (~> 1.4)
• gen_stage (~> 1.3)
• telemetry (~> 1.3)

Installation

Add autonomic to your mix.exs:

def deps do
  [
    {:autonomic, "~> 0.1.0"}
  ]
end

For the full official stack, the application opts into all three adapters explicitly:

def deps do
  [
    {:autonomic, "~> 0.1.0"},
    {:autonomic_linux, "~> 0.1.0"},
    {:autonomic_postgres, "~> 0.1.0"},
    {:autonomic_typesafe, "~> 0.1.0"}
  ]
end

This does not make the adapters dependencies of autonomic. The dependency direction is the reverse: each adapter depends on core, and applications choose which adapters to install.

How do I configure it?

Configure the runtime implementations and effect adapters in your config/config.exs:

config :autonomic,
  store: Autonomic.Store.Postgres,
  domain_backend: Autonomic.Linux.Backend,
  sensor: Autonomic.Typesafe.Sensor,
  state_dir: "/var/lib/autonomic/kernel",
  effect_concurrency: 8,
  sensor_queue: 64,
  speculation_ms: 15_000,
  max_repairs: 3

TypeSafe-centered reference runtime

The core package is adapter-neutral, but the repository's reference semantic path is TypeSafe-centered. With sensor: Autonomic.Typesafe.Sensor, observable worker/effect state is evaluated by a fixed prepared TypeSafe bank and returned as typed Autonomic.SemanticObservation values.

Those observations are not decorative telemetry:

TypeSafe semantic bank
  |
  +--> Homeostat -> temporal drift/uncertainty/authority/destructive pressure
  |                 -> continue / yield / narrow / preempt
  |
  `--> EffectBroker -> semantic decision for an exact effect revision
                      -> allow / deny as one required decision class

The adapter preserves Noul/Score/Choice distributions, confidence, ranking/margins, actual/requested model, request ID, TypeSafeSDK version, bank version, Prepared fingerprint, usage, retries, and latency. Core policy then interprets that evidence conservatively; it does not treat the semantic model as authority.

See TypeSafe Control Loop for the exact core consumption path and current policy limitations.

What public modules and concepts does it own?

• Core & Lifecycle: Autonomic.Application, Autonomic.EpisodeSupervisor, Autonomic.EpisodeController, Autonomic.EpisodeSpec, Autonomic.Runtime, Autonomic.SystemRegulator.
• Authority & Policy: Autonomic.AuthorityGovernor, Autonomic.Policy, Autonomic.Capability, Autonomic.CapabilityLease, Autonomic.HumanApproval, Autonomic.VersionVector.
• Effect Broker & Adapters: Autonomic.EffectBroker, Autonomic.EffectSocket, Autonomic.EffectState, Autonomic.EffectAdapter, Autonomic.Adapters.Git, Autonomic.Adapters.GitRemote, Autonomic.Adapters.HTTP, Autonomic.Adapters.Artifact.
• Homeostasis & Sensors: Autonomic.Homeostat, Autonomic.HomeostaticState, Autonomic.SensorArray, Autonomic.SemanticSensor, Autonomic.Trajectory.
• Verification & Repair: Autonomic.Verifier, Autonomic.VerificationRunner, Autonomic.RepairManager, Autonomic.SnapshotManager.
• Contracts: Autonomic.Contracts, Autonomic.Canonical, Autonomic.Payloads.
• Extension Behaviours: Autonomic.Store, Autonomic.ExecutionDomain, Autonomic.SemanticSensor, Autonomic.EffectAdapter.

How does it fit into Autonomic?

autonomic is the central hub of the dependency graph:

       autonomic_linux   autonomic_postgres   autonomic_typesafe
              │                  │                   │
              └──────────────────┼───────────────────┘
                                 ▼
                      ┌─────────────────────┐
                      │      autonomic      │
                      │                     │
                      │ kernel semantics    │
                      │ EffectBroker        │
                      │ episode lifecycle   │
                      │ policy/capability   │
                      │ Store behaviour     │
                      │ Exec behaviour      │
                      │ Sensor behaviour    │
                      └─────────────────────┘

The arrows above are Mix dependency arrows: adapter → core. Runtime calls flow through core behaviours into the configured implementation, but package ownership remains one-way.

Where are the full system docs?

See the repository root at GitHub, HexDocs, and the repository package-composition guide.