What ACE is

Most AI systems treat state as a side effect: a chat log, a vector index, a cache. ACE treats it as the product. The reasoning is the part you can replay.

• One install, one repository. ace-core ships Core and Intelligence together. There is no second service to run to get the reasoning model.
• Core owns governance. Authority, temporal and immutable state, reasoning receipts, decisions, and outcomes. Nothing durable is written except through Core.
• Intelligence owns the invariant machinery. The entity → observation → shift → signal → brief → decision-feedback pipeline is domain-neutral and does not change when your domain does.
• Domain Packs supply the domain. Ontology, source mappings, shift definitions, personas, synthesis templates, and policy ship as independently versioned, inert declarative data — compiled and content-addressed, never imported or executed.

Adding a vertical should mean writing config and connectors. In ACE it does: a new domain is a new pack plus a registered source connector. The kernel does not change.

The canonical flow

flowchart LR
    SRC[("authorized<br/>source")] -->|acquisition receipt| OBS[Observation]
    OBS --> ENT["Entity Snapshot<br/>(entity graph)"]
    ENT -->|detector rule| SHIFT[Shift]
    SHIFT -->|routing rule| SIG[Signal]
    SIG -->|persona + template| BRIEF[Brief]
    BRIEF --> DEC[Decision]
    DEC --> OUT[Outcome]
    OUT -.->|decision feedback| ENT

    subgraph CORE["Core governs the whole line"]
        direction LR
        AUTH["authority · immutable records<br/>governed-state heads · receipts"]
    end
    CORE -.->|"every write is committed here"| OBS
    CORE -.-> SHIFT
    CORE -.-> BRIEF
    CORE -.-> DEC

Each arrow is a typed contract, not a convention. Each hop carries lineage back to the exact resource it was derived from, with a content digest and an availability timestamp — so a Brief can always be walked back to the bytes of the source snapshot that produced it.

The pipeline runs in two clearly separated modes:

Interpretation functions are mode-typed and refuse to cross: detect_numeric_shift accepts only PREPARED snapshots, detect_live_numeric_shift only LIVE ones. No pure Intelligence function grants LIVE authority — the application bridge must independently prove a committed activation and authorize persistence through Core.

The architecture is the feature

ACE wraps a lean coordinating Core around specialized reasoning and Intelligence capabilities; the octopus is useful inspiration for that shape, not a literal ratio of code or intelligence. The existing cognitive runtime remains visible inside this architecture: Human ↔ ACE ↔ LLM, A nine-layer cognitive pipeline, and Dynamic composition describe how ACE assembles and governs reasoning. Core + Intelligence + Domain Packs describe how the same machinery becomes a reusable intelligence engine without putting domain nouns or executable behavior in the kernel.

ACE provides graph-grounded, calibrated foresight. It projects conditional consequences of decisions, exposes the mechanisms and uncertainty behind them, observes what actually happens, and uses resolved forecasts to improve later reasoning.

Architecture: one install, two bounded contexts

flowchart TB
    subgraph PKG["ace-core — one install"]
        direction TB
        subgraph APP["ace.application — governed services"]
            A1["LIVE source ingress"]
            A2["LIVE Intelligence bridge"]
            A3["Brief / case-brief synthesis"]
            A4["decision feedback · supersession impact"]
        end
        subgraph INT["ace.intelligence — invariant machinery"]
            I1["pack compiler + conformance"]
            I2["detection · routing · synthesis"]
            I3["epistemic status · derivation families"]
            I4["monitors · personas · subscriptions"]
        end
        subgraph CORE["ace.core — governed cognition"]
            C1["authority + activation"]
            C2["immutable records · append-only transactions"]
            C3["governed-state heads · preconditions"]
            C4["reasoning receipts · decisions · outcomes"]
        end
    end

    PACK[["Domain Pack<br/>independently versioned<br/>inert JSON"]] -.->|compiled + digested| INT
    CONN[["source connector<br/>registered by the host"]] -.->|bounded registry| APP
    APP --> INT
    APP --> CORE
    INT --> CORE
    HOST["host adapter<br/>(private: core.engine)"] --> APP

The dependency direction is enforced, not just described: ace.application depends on ace.core and ace.intelligence; ace.intelligence depends on ace.core; nothing under ace/ imports the host. Architecture gates in the test suite assert this.

What each layer owns

Domain Packs: add a vertical without touching the kernel

A Domain Pack is a manifest plus JSON module resources. The compiler (ace.intelligence.packs.compiler.compile_pack_document) is a pure, deterministic function: it performs no discovery, import, I/O, clock read, model call, secret lookup, registry mutation, or persistence operation.

What that buys you:

• Content addressing. Every resource is digest-checked; every module is canonicalized and hashed; the pack gets a pack_digest. Semantically identical packs with different key order or indentation compile to byte-identical IR. One changed attribute changes the digest.
• No executable surface. The compiler rejects any key named regex, template, expression, predicate, handler, script, eval, exec, jsonpath, and friends — and rejects mappings that try to select or override host-owned envelope fields such as source_digest, activation_id, or product_id. A pack cannot smuggle in behavior.
• Fail-closed diagnostics. Errors arrive as stable (severity, code, path, message) records: unknown_target_entity_type, missing_required_outputs, module_cycle, digest_mismatch.
• Independent versioning. Packs carry their own pack_id and semantic version, and declare the compiler and runtime contracts they target. They ship on their own schedule.
• Independent verification. A pack that declares no epistemic-status module for a template simply does not get status-aware synthesis — it does not silently get a permissive default.

A generic pack, end to end

Domain Packs are JSON (media_type is fixed to application/json); the compiler parses with a strict reader that rejects duplicate object keys, non-finite numbers, and lone surrogates. Nothing below is vertical-specific — swap watched_subject for vessel, competitor, service, or counterparty and the kernel is unchanged.

modules/ontology.json — what exists in your world:

{
  "contract": "ace.intelligence.ontology/v1alpha1",
  "module_id": "domain_ontology",
  "entity_types": [
    {
      "entity_type_id": "watched_subject",
      "display_name": "Watched Subject",
      "attributes": [
        { "attribute_id": "name", "value_type": "string", "required": true },
        { "attribute_id": "tracked_value", "value_type": "number" },
        { "attribute_id": "status", "value_type": "string" }
      ]
    }
  ],
  "relation_types": []
}

modules/detection.json — what counts as a material change:

{
  "contract": "ace.intelligence.detection/v1alpha2",
  "module_id": "domain_detection",
  "numeric_delta_rules": [
    {
      "detector_id": "tracked_value_moved",
      "entity_type_id": "watched_subject",
      "attribute_id": "tracked_value",
      "metric": "percent_change",
      "threshold": 10.0,
      "direction": "any",
      "shift_type": "tracked_value_shift",
      "signal_type": "tracked_value_signal"
    }
  ],
  "categorical_transition_rules": [
    {
      "detector_id": "status_changed",
      "entity_type_id": "watched_subject",
      "attribute_id": "status",
      "transitions": [{ "from_value": "nominal", "to_value": "degraded" }],
      "shift_type": "status_shift",
      "signal_type": "status_signal"
    }
  ]
}

pack.json — the manifest that binds them, with declared capabilities, authority requests, and operator-tunable overlay slots:

{
  "contract": "ace.intelligence.domain-pack-manifest/v1alpha1",
  "metadata": {
    "pack_id": "example_domain",
    "version": "0.1.0",
    "display_name": "Example Domain",
    "description": "A domain-neutral illustration of the pack contract."
  },
  "resources": [
    { "resource_id": "ontology",  "path": "modules/ontology.json",  "digest": "sha256:<64 hex>" },
    { "resource_id": "detection", "path": "modules/detection.json", "digest": "sha256:<64 hex>" }
  ],
  "modules": [
    {
      "module_id": "domain_ontology",
      "contract": "ace.intelligence.ontology/v1alpha1",
      "resource_id": "ontology"
    },
    {
      "module_id": "domain_detection",
      "contract": "ace.intelligence.detection/v1alpha2",
      "resource_id": "detection",
      "depends_on": ["domain_ontology"]
    }
  ],
  "capability_requirements": [
    {
      "requirement_id": "public_snapshot",
      "capability": "source_snapshot",
      "contract": "ace.source.snapshot/v1alpha1"
    }
  ],
  "authority_requests": [
    { "request_id": "read_public_source", "authority": "source_read" }
  ],
  "overlay_slots": [
    { "slot_id": "watched_subjects", "value_kind": "string_list", "required": true }
  ]
}

Additional module contracts a pack may declare, all compiled by the same function: ace.intelligence.source-mapping/v1alpha1 (source field → ontology attribute, with bounded transforms only), ace.intelligence.personas/v1alpha1 (personas plus signal-routing rules), ace.intelligence.synthesis/v1alpha1 and /v1alpha2 (brief templates), ace.intelligence.epistemic-status/v1alpha1 and /v1alpha2, and ace.intelligence.decision-outcomes/v1alpha1 (feedback policy).

What 0.4.0 adds

0.4.0 is the Governed Cognition release. It closes the gap between "ACE can analyze material you hand it" and "ACE can go get material under authority and stay governed the whole way."

• Governed LIVE source ingress as a packaged public application service. One exact resolved source definition is captured through an activation-bound, authority-checked adapter and admitted atomically as five durable records — acquisition receipt, canonical source snapshot, Observation, Entity Snapshot, admission receipt — under four rechecked governed-state heads.
• The governed LIVE Intelligence bridge and LIVE Brief synthesis. Admitted snapshots derive Shift → Signal → attention dispositions, and route-triggered Briefs run through Core governed reasoning, with exact idempotent replay and restart reopening of every admission.
• Bounded connector composition. LIVE cognition is composed into the host exclusively through a private adapter. Connectors register in a constructor-supplied registry keyed by exact artifact identity: no dynamic entry-point loading, no embedded code in domain packs, and no persistence path outside Core's immutable-record port.
• Fail-closed acquisition. Source acquisition fails closed on scope, URI, redirect, DNS/IP rebinding, payload size, digest, replay, timing, and authority violations. Authority-use receipts are single-use and non-reusable across admissions.
• Packaged conformance seams (ace.testing) so an external package can exercise the public service contracts — including restart and replay — without importing the host.
• Unchanged public surface. Exactly eleven MCP tools. Extension-disabled (naked-kernel) startup still works and composes no LIVE service. Schema head stays at v175, with additive, append-only governed-state and immutable-record migrations.

The 0.4.0 milestone also carries a teaching-experience track (propose → inspect → approve → use → measure → revise or retire). The governed-LIVE slice above is what shipped; see the roadmap for the rest.

Full detail: CHANGELOG.

Quickstart

Fastest verified path — no database, no provider, no keys

The Core and Intelligence contracts are pure. You can compile a pack and exercise the full derivation machinery on a laptop in seconds:

git clone https://github.com/augmented-cognition-engine/core ace
cd ace
uv sync
uv run pytest tests/intelligence -q

That runs the Domain Pack compiler, detection, routing, synthesis, epistemic status, source mapping, ledger, activation, and governed-reasoning suites against no external service.

Full self-hosted runtime

Running the reasoning service adds a database and a model provider.

Prerequisites: macOS or Linux · Git · Python 3.12 · uv · Docker Engine with Compose v2 · credentials for one supported provider.

uv run ace setup

ace setup asks which model route to use, generates local credentials, writes .env with mode 0600 without replacing existing secrets, starts SurrealDB through Docker Compose, applies every migration, starts the ACE API as a local background process, and logs in the CLI and thin MCP client. It is safe to rerun; if it is interrupted, run the same command again.

uv run ace doctor          # configuration, database, schema, auth, provider routing, API, MCP
uv run ace service status
uv run ace service logs --lines 80
uv run ace service stop    # preserves the SurrealDB volume

ace doctor verifies operational readiness only. It does not certify the correctness of data already in the graph, and by default it spends no model tokens — add --live-provider for one explicitly requested minimal call.

Manual control, for CI or development:

cp .env.example .env
docker compose -f infra/docker-compose.yml up -d surrealdb
uv run python scripts/schema_apply.py
uv run uvicorn core.engine.api.main:app --host 127.0.0.1 --port 3000
uv run ace login --api-key '<the API_KEY from .env>'

Package-only install

The distribution is ace-core; it provides the ace import package, the ace CLI, and the ace-mcp-client command.

python -m pip install ace-core
python -c "import ace; print(ace.__version__)"
ace --help

The self-hosted runtime path above uses the source checkout because it carries the pinned Compose stack and the release-maintained local service scripts.

Test gates

make test-fast          # the fast suite (pytest -m "not e2e")
make test-naked-kernel  # the kernel with NO extensions loaded, plus the boundary guard
make lint               # ruff check + format --check

The public Python surface

Everything below uses only public ace.* APIs and runs with no database, no network, and no model provider.

Compile a Domain Pack

import hashlib
import json

from ace.intelligence.packs.compiler import compile_pack_document


def resource(payload: dict) -> bytes:
    return json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")


def digest(payload: bytes) -> str:
    return "sha256:" + hashlib.sha256(payload).hexdigest()


ontology = resource(
    {
        "contract": "ace.intelligence.ontology/v1alpha1",
        "module_id": "domain_ontology",
        "entity_types": [
            {
                "entity_type_id": "watched_subject",
                "attributes": [
                    {"attribute_id": "name", "value_type": "string", "required": True},
                    {"attribute_id": "tracked_value", "value_type": "number"},
                ],
            }
        ],
    }
)

manifest = resource(
    {
        "contract": "ace.intelligence.domain-pack-manifest/v1alpha1",
        "metadata": {
            "pack_id": "example_domain",
            "version": "0.1.0",
            "display_name": "Example Domain",
        },
        "resources": [
            {
                "resource_id": "ontology",
                "path": "modules/ontology.json",
                "digest": digest(ontology),
            }
        ],
        "modules": [
            {
                "module_id": "domain_ontology",
                "contract": "ace.intelligence.ontology/v1alpha1",
                "resource_id": "ontology",
            }
        ],
    }
)

pack = compile_pack_document(manifest, {"modules/ontology.json": ontology})

print(pack.metadata.pack_id)          # example_domain
print(pack.pack_digest)               # sha256:...  stable across key order and whitespace
print([m.module_id for m in pack.modules])

Compilation is fail-closed. Tamper with a byte and you get a PackCompilationError carrying a digest_mismatch diagnostic with the exact path — not a silently different pack.

Append immutable records and replay them

import asyncio
from datetime import UTC, datetime

from ace.core import AppendOnlyTransactionRequestV1, ImmutableRecordV1
from ace.testing import InMemoryImmutableRecordStore

observed_at = datetime(2026, 8, 7, 12, 0, tzinfo=UTC)

record = ImmutableRecordV1(
    product_id="product:demo",
    record_space="live",
    record_kind="observation",
    record_key="watched_subject:acme@2026-08-07",
    payload_contract="ace.intelligence.observation/v1alpha1",
    payload={"tracked_value": 42.0},
    as_of=observed_at,
    available_at=observed_at,
    processing_order=0,
)

request = AppendOnlyTransactionRequestV1(
    product_id="product:demo",
    record_space="live",
    transaction_key="admit:watched_subject:acme@2026-08-07",
    records=(record,),
    submitted_at=observed_at,
)


async def main() -> None:
    store = InMemoryImmutableRecordStore()
    receipt = await store.append(request)
    replayed = await store.append(request)      # exact replay, not a second write
    assert receipt == replayed

    print(record.storage_id)                    # immutable_record:<stable digest>
    print(record.material_hash)                 # sha256:<canonical material>


asyncio.run(main())

Storage identity and material hash are derived, never supplied. Passing a storage_id that does not match the record's scope and key is a validation error, so a caller cannot forge identity or retroactively edit material behind a stable ID. InMemoryImmutableRecordStore is a reference port for conformance and fault tests — production hosts supply Core's database-backed adapter.

Other public entry points

Public contracts are v1alpha1 / v1alpha2. They are versioned in the name so a change is visible, but they are alpha and may change on a preview minor release.

MCP: still exactly eleven tools

The thin, pure-HTTP MCP client exposes the same eleven tools it did in 0.2 and 0.3. 0.4.0 adds none.

To connect a client, register the command uv run ace-mcp-client with its working directory set to the clone. It reuses the token written by ace login. Call ace_start first, then ace_load(...) before domain work.

ace_task uses a durable asynchronous receipt contract: it returns within a bounded submission window with either a completed result or a pending/running task ID, and long reasoning continues after the MCP call ends. Retrieve it with ace_status(filter="task:…"). completed, failed, and degraded are distinct terminal states — a polling timeout is not a task failure.

Setup and provider details: docs/providers.md · docs/capability-maturity.md · docs/governed-cognition-operations.md

Security and governance invariants

These are enforced by contract validation and architecture tests, not by convention.

Authority

• Every LIVE effect requires a resolved authority grant and a committed domain activation. Prepared analysis grants no authority under any circumstance.
• Authority-use receipts are single-use and cannot be reused across admissions.
• Capability use is bound to exact artifact identity, so a capability granted for one artifact does not carry to another.
• Models may propose. Models cannot approve, activate, roll back, expire, supersede, retire, or grant execution authority.

State

• All durable writes go through Core's immutable-record port as atomic append-only transactions. There is no persistence path around it.
• Governed-state heads carry preconditions that are rechecked inside the commit; a stale head fails the transaction rather than racing it.
• Identity and material hashes are derived from canonical JSON. Supplying a mismatched storage_id, material_hash, or request_hash is a validation error.
• Replay is exact: the same transaction key with the same material returns the same receipt; the same key with different material raises a replay conflict.

Acquisition

• Source acquisition fails closed on scope, URI, redirect, DNS/IP-rebinding, payload-size, digest, replay, timing, and authority violations. HTTPS URIs are validated exactly and IP literals are checked against non-public ranges.
• ACE does not browse. There is no automatic or arbitrary web access. A connector may fetch only one exact resolved source definition, and only through the bounded registry the host constructed.

Packs and connectors

• Domain Packs are inert data. The compiler rejects executable-shaped fields and refuses mappings that touch host-owned envelope fields.
• Connectors register in a constructor-supplied registry keyed by exact artifact identity. There is no dynamic entry-point loading for LIVE source connectors.
• The naked kernel (ACE_DISABLE_EXTENSIONS=1) boots and composes no LIVE service. make test-naked-kernel is that boundary in CI form.

Report vulnerabilities per SECURITY.md.

Repository map

.
├── ace/                      ← the public package (this is the product surface)
│   ├── core/                 ← authority, immutable records, governed state, reasoning, decisions
│   ├── intelligence/
│   │   ├── contracts/        ← pack, resources, detection, synthesis, epistemic, ledger, monitors…
│   │   ├── packs/            ← compiler, runtime binding, activation, diagnostics
│   │   └── detection/        ← numeric delta, categorical transition
│   ├── application/          ← LIVE ingress, LIVE bridge, brief synthesis, decision feedback
│   └── testing/              ← packaged conformance seams for external packages
├── core/
│   ├── engine/               ← the host runtime (private): API, CLI, orchestration, adapters
│   ├── schema/               ← SurrealDB migrations (head: v175)
│   └── ui/canvas/            ← Atrium, an experimental React research canvas (repository beta)
├── ace_mcp_client/           ← thin pure-HTTP MCP client (the eleven tools)
├── extensions/reference/     ← the worked extension example the kernel actually loads
├── examples/                 ← independent example packages
├── docs/                     ← architecture, providers, maturity, operations, evidence
├── evaluations/              ← frozen fixtures and acceptance results
├── infra/                    ← docker-compose for SurrealDB + API
├── scripts/                  ← schema apply, journeys, verification, scaffolding
└── tests/                    ← including tests/intelligence, the no-service contract suite

ace/ is the public boundary. core/engine/ is the host and is private — public ace contracts stay host-free, and host adapters are the only core.engine edge into the public package.

Maturity and limitations

0.4.0 is a developer preview and a single-node governed-cognition release. Read this section before you build on it.

What is bounded:

• Single node. One ACE API/worker deployment and one SurrealDB/SurrealKV database. Distributed ordering, multi-writer consistency, multi-region failover, and exactly-once delivery across independent databases are not claimed.
• Trusted extensions only. In-process Python extensions must be explicitly trusted. There is no hostile-code isolation.
• Alpha contracts. The v1alpha1 / v1alpha2 public contracts may change on a preview minor release. Changes are visible in the contract string.
• Domain Packs and connectors are independently versioned and are not part of this release's compatibility promise. There is no domain-pack marketplace, registry, or distribution channel — packs are artifacts you build and supply.
• Python 3.12 only.

What ACE does not claim:

• No hosted SaaS. ACE is self-hosted; you run the database and bring your own model credentials.
• No supported graphical UI. Atrium is experimental repository-beta source, not part of the Python artifact, the supported runtime, or the golden path.
• No automatic or arbitrary web access.
• No real-world causal accuracy, calibrated forecasting, autonomous learning, general model of reality, or demonstrated beneficial impact outside the frozen, bounded evaluation scopes recorded in docs/evidence/.
• Security review to date is an independent AI review, not a human penetration test, professional audit, or certification. That limitation travels with the evidence.

Current supported/experimental/internal boundaries: docs/capability-maturity.md. Point-in-time acceptance receipts: docs/evidence/.

Roadmap and contributing

The north-star loop is:

understand → reason → decide → act with authority → observe outcomes → improve future reasoning

0.4.0 delivers the governed-cognition span of that loop. 0.5.0 (Reasoning into Action) carries an approved decision into bounded, attributable action; 0.6.0 (Measured Intelligence) promotes or retires reasoning revisions because of measured outcomes.

• Public roadmap — outcome state, sequencing, and declared boundaries
• Roadmap project board — live Now / Next / Later
• Architecture — as-built boundaries
• Contributing · Code of conduct · Security policy
• Issues — the best first contribution is a Domain Pack for a vertical we have not tried, plus the diagnostic it made you wish existed

Good contributions to start with: a new detector family, a synthesis template contract, a source connector against a public API, or a conformance seam that makes an external package easier to test.

License

Apache-2.0 — see LICENSE and NOTICE.

Existing ACE code is copyright Edwin Amirian; contributors retain copyright in their contributions and license them under Apache-2.0. QueryLabs LLC is the founding sponsor. Separately distributed extensions and Domain Packs state their own licenses. The default stack runs SurrealDB separately; the SurrealDB server is source-available under BSL 1.1 rather than OSI open source.