# mzero reference runtime

The GGUF provides the neural decision core. The reference runtime combines it with persistent event state and learning. This guide describes the included implementation.

## Four kinds of state

| State | Storage | Purpose |
|---|---|---|
| Neural parameters | `mzero-2b-Q4_K_M.gguf` | Evaluate described questions over evidence and earlier answers |
| Observed events | SQLite event and link tables | Preserve source observations, causal connections, and corrections |
| Decision records | SQLite decision table | Preserve evidence selection, question sequence, answers, parent links, and model revision |
| Learned relationships | SQLite memory table | Connect confirmed outcome patterns with observed question answers |

Events and decisions are persisted separately. Inherited model answers carry provisional status and a source reference. Field readers obtain active observed values from event records.

## Event contract

`POST /v1/events` accepts:

| Field | Meaning |
|---|---|
| `namespace` | Application or tenant context |
| `stream` | Operation, session, device, or another event sequence |
| `pack` / `version` | Assessment goal and published question definition |
| `id` | Stable source event ID |
| `occurred_at` | Unix occurrence timestamp |
| `data` | Observed JSON fields |
| `caused_by` | Source event IDs in this stream |
| `supersedes` | Earlier records corrected by this event |

The server records when the event became available. Event IDs are immutable within their namespace and stream. Replaying identical evidence returns the existing job. An event and its queued job are committed before acknowledgement.

Jobs are processed in persisted order by one decision worker. A completed job references the decision record. The decision, notification record, and job acknowledgement are committed together.

## Question packs

A pack defines a stable goal, a versioned question catalog, and processing budgets. Publishing a changed definition creates the next pack version. A different goal uses a different pack ID.

`entity_field` binds state to an observed entity. `state_fields` names the fields whose current values are carried forward with source event IDs. A field binding can answer a question through an explicit boolean or an exact comparison with two declared scalar values.

For example:

```json
{
  "fact_bindings": {
    "operation_completed": {"type": "boolean", "field": "completed"},
    "authorization_granted": {
      "type": "equals",
      "field": "authorization",
      "yes_value": "granted",
      "no_value": "denied"
    }
  }
}
```

Questions without fact bindings are evaluated by mzero GGUF. Each answer records its backend, so consumers can distinguish a source-field reading from a semantic model score.

## Selection and inheritance

Evidence selection uses occurrence and availability cutoffs, a recent candidate window, inherited source references, causal links, and correction links. Connected chains are evaluated for relevance to the pack's goal.

The most recent eligible decision in the same namespace, stream, and pack becomes the parent. An explicit parent ID creates a chosen continuation; an explicit null parent starts a new root. Inherited judgments include their previous focus event and stale status. The earlier decision remains available for inspection.

Question fingerprints include meaning and reader configuration. Relation memory therefore refers to a particular question contract. Adding a pack version preserves the historical definitions of earlier decisions.

## Feedback and learning

`POST /v1/feedback` links a completed decision to an independently confirmed outcome:

```json
{
  "namespace": "demo-app",
  "stream": "synthetic-operation-001",
  "decision_id": "DECISION_ID_RETURNED_BY_THE_API",
  "confirmed": true,
  "outcome_id": "synthetic-audit-001",
  "source_ref": "synthetic:independent-audit",
  "pattern": "anomaly",
  "answers": {
    "authorization_granted": "no",
    "operation_completed": "yes"
  }
}
```

Decision and source-outcome identities make learning idempotent. The confirmation updates the namespace-and-pack relation memory and increments its revision. Verified semantic targets can also be retained as neural training samples. Explicit typed facts retain their source contract; a source correction is submitted as a new event with `supersedes`.

The relationship weight for pattern `p` and question `q` is:

```text
w(p, q) = signed_observation_total(p, q) / support_accumulator(p, q)
```

On a confirmed update of pattern `p`, its existing accumulators are multiplied by the retention factor. New informative observations then add their signed value and one support unit. Pattern compatibility averages agreement over the observed questions shared with the pattern.

Question selection compares learned relationships among leading candidates. A separation mode prefers a question that divides candidate patterns; a confirmation mode uses the leading pattern's distinguishing relationships. The sequence worker also allocates a bounded exploration slot to incomplete question coverage.

`POST /v1/growth` exposes confirmed pattern counts, learned question IDs, memory revision, and confirmed parent-to-child pattern transitions.

## Notifications

An application selects the outcome labels that should generate an anomaly notification. The default label is `anomaly`. Notifications include the source event IDs, decision and parent IDs, question answers, answer backends, final pattern, and memory revision.

The outbox stores delivery state and retry attempts. Delivery uses either a webhook URL or an SNS topic configured by the application. Receivers deduplicate using the notification ID; webhook deliveries also carry it as `Idempotency-Key`.

The included example sends only synthetic notifications to a local test receiver. Production destination configuration belongs to the consuming application.

## API routes

| Route | Purpose |
|---|---|
| `GET /health` | Model/runtime readiness and model hash |
| `POST /v1/packs` | Register an immutable pack version |
| `POST /v1/events` | Persist source evidence and queue an assessment |
| `GET /v1/jobs/<id>` | Read job state and its completed decision |
| `POST /v1/feedback` | Confirm an outcome and update scoped learning |
| `POST /v1/growth` | Inspect learned relationships and recorded transitions |
| `GET /v1/alerts` | Inspect persisted notifications and delivery state |
| `GET /v1/metrics?namespace=...&pack=...` | Compare decisions with confirmed outcomes |
| `POST /v1/retry` | Requeue a failed job or notification |

Protected routes use the application-supplied bearer token. Example scripts read the token from the environment; no token is bundled.

## Model protocol

Prompt version 2 supplies system instructions, JSON evidence, ordered prior decisions, the current question, and described answer labels. The tokenizer verifies that each letter label occupies one token at the answer boundary.

The bundled runtime pins llama.cpp revision `08ffba21e5c2f1728b6b405c05ff3913f65706d4`. A small patch applies grammar before sampling when requesting post-sampling probabilities. The reference client checks that the returned probabilities cover the constrained answer space.

The training adapter is already merged into the GGUF. The Docker image reads the local model and verifies its SHA-256 against the release manifest.

## Running the archive

Extract `mzero-runtime.zip` into the directory containing the downloaded model and manifest. It supplies the runtime source, Dockerfile, Compose configuration, synthetic examples, and protocol tests.

```bash
python3 -m zipfile -e mzero-runtime.zip .
export MZERO_API_TOKEN="$(openssl rand -hex 32)"
docker compose up --build -d
```

The CPU image includes the local GGUF and exposes the API on localhost. A Docker volume persists SQLite state. `docker compose down` stops the service while retaining that volume.

The same service composition can be hosted as a container: local GGUF, authenticated API, persistent data volume, and an application-configured notification destination. AWS integrations use the SNS adapter with an ECS task role. NVIDIA execution uses a CUDA build of the pinned llama.cpp runtime. Application credentials and endpoint configuration are supplied at deployment time.

All bundled test fixtures and examples are synthetic. The archive contains no application database, private event history, environment file, cloud credential, or research attachment.