autonomic_typesafe

TypeSafe/Jev semantic sensor bank backend for the Autonomic Kernel.

What is this package?

autonomic_typesafe implements Autonomic.SemanticSensor on the TypeSafeSDK 0.4.0 semantic API. It evaluates a fixed, prepared bank for scope drift, authority escalation, evidence sufficiency, effect irreversibility and trajectory regime while keeping semantic evidence outside Autonomic's root of trust.

This is a greenfield integration. There is no TypeSafeSDK 0.2/0.3 compatibility path, legacy shim or alternate semantic HTTP client.

Runtime design

The adapter deliberately delegates reusable mechanics to TypeSafeSDK 0.4:

• TypeSafeSDK.Prepared.fingerprint/1 is the semantic-contract identity;
• response_contract: enforces exact allowed-model policy and rejects unexpected answer IDs;
• max_request_bytes: enforces the exact serialized request budget before egress;
• TypeSafeSDK.Response.metadata/1 supplies bounded stable response provenance and TypeSafeSDK.Error.metadata/1 supplies privacy-safe status diagnostics;
• TypeSafeSDK.OTP.Server keeps the bank responsive while evaluations run under the package-owned Autonomic.Typesafe.Tasks supervisor with an explicit max_in_flight bound; and
• TypeSafe's per-answer telemetry is emitted after semantic validation.

Autonomic still owns the concerns that are kernel-specific: observable-window construction, secret redaction, evidence budgeting, fail-closed treatment of an unknown answer type for a required sensor, semantic health and authority policy.

TypeSafeSDK continues to own its Pristine runtime. autonomic_typesafe does not implement retries, HTTP transport, a second queue, or transport cancellation.

Dependencies

• autonomic (~> 0.1.0 when published)
• typesafe_sdk (~> 0.4.0)

TypeSafeSDK 0.4.0 in turn requires Pristine 0.4.0. The supplied Pristine Finch transport advertises verified unary cancellation and cancellation cleanup; this adapter always requires those capabilities because the TypeSafe OTP server uses scoped cancellation for bounded in-flight work.

Installation

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

autonomic_typesafe remains a separate package so the core contract stays reusable, but the repository's full reference composition installs it and configures Autonomic.Typesafe.Sensor. Its Mix dependency is autonomic_typesafe → autonomic; the core never depends back on the adapter.

Configuration

config :autonomic,
  sensor: Autonomic.Typesafe.Sensor

config :autonomic_typesafe,
  api_key: System.get_env("TYPESAFE_API_KEY"),
  model: "jev-latest",
  allowed_models: [],
  timeout_ms: 3_000,
  slow_timeout_ms: 10_000,
  max_in_flight: 8,
  evidence_limit: 32_768,
  request_limit: 65_536,
  required_capabilities: [] # optional additional requirements; cancellation base is mandatory

allowed_models: [] means that no concrete model allow-set is enforced. required_capabilities adds deployment-specific requirements on top of the adapter’s non-removable :unary_cancellation and :cancellation_cleanup base. For a calibrated deployment, set a non-empty list of exact model IDs. request_limit is the TypeSafeSDK full serialized-request limit; evidence_limit is the separate Autonomic observable-state budget and remains necessary.

When no API key is configured, the package application starts without a bank and Autonomic.Typesafe.Sensor.observe/2 returns {:error, :typesafe_not_configured}. Tests disable autostart and inject real TypeSafeSDK.Test clients directly into a supervised bank; production has no client hot-swap API.

Public modules

• Autonomic.Typesafe.Sensor — Autonomic.SemanticSensor implementation.
• Autonomic.Typesafe.SensorBank — declarative question bank and Prepared contract.
• Autonomic.Typesafe.Bank — bounded OTP execution and response normalization.
• Autonomic.Typesafe.Evidence — observable-state sanitization and redaction.
• Autonomic.Typesafe.Application — dedicated semantic task supervision plus optional bank supervision.

What TypeSafe actually does in the reference system

The production bank is a prepared five-query contract, not a single safe? prompt:

One successful evaluation produces five Autonomic.SemanticObservation values with shared model/request/fingerprint/usage/timing provenance. Core then uses them in two real control paths:

1. Autonomic.Homeostat smooths semantic risk over time and can continue, yield, narrow authority, or preempt.
2. Autonomic.EffectBroker evaluates required semantic evidence for the exact proposed effect revision and persists a semantic allow/deny decision.

The TypeSafe-facing layer deliberately preserves more structure than current core policy consumes. In particular, EffectBroker currently reduces selected observations to explicit thresholds rather than performing probabilistic fusion across every returned distribution.

Read the guides in order:

1. Semantic Sensors
2. TypeSafeSDK Integration
3. Evidence Budgeting, Privacy & Failure Semantics
4. End-to-End TypeSafe Semantic Control Loop

Testing

Deterministic component tests use the real TypeSafeSDK serialization, validation, response-contract, request-budget and transport seam through TypeSafeSDK.Test. The separate :live gate uses an authorized real endpoint and records only non-secret structural provenance.

See the package guides and repository-level docs/TYPESAFE_SENSORS.md for the full integration contract.

For the repository-wide adapter/core dependency model and full-stack installation recipe, see docs/PACKAGE_COMPOSITION.md.