# How Maka Audits Model Capabilities and Recovers Client Capabilities

> Learn how Maka audits model capabilities with an immutable log and recovers client capabilities using a coordinator. Restore user permissions seamlessly.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-08-31

---

**Maka uses an immutable audit log to track every model-provided capability and a client capability coordinator to restore user permissions after crashes or interruptions.**

The Apache Maka runtime treats capability tracking and recovery as foundational concerns. Every interaction with model capabilities—whether text generation, image creation, or tool invocation—leaves a tamper-evident trace in SQLite. When sessions resume, the system reconstructs client-side capabilities from this audit trail, eliminating redundant user prompts and preserving security boundaries. This article explains both mechanisms using actual source paths and runnable patterns from the `apache/maka` repository.

---

## What Are Model Capabilities in Maka?

Model capabilities represent functions exposed by AI providers or local models. Each capability carries a `capabilitySource` indicating its origin: provider API, static catalog, user override, or unknown. The **Model Catalog** ([`packages/core/src/model-catalog.ts`](https://github.com/apache/maka/blob/main/packages/core/src/model-catalog.ts)) serves as the authoritative registry, returning `ModelCapability` objects that the runtime instruments for auditing.

---

## How Maka Audits Model Capabilities

Maka's audit system is **best-effort** and **non-blocking**: failed writes log warnings but never halt execution. This preserves turn continuity while maximizing observability.

### Capability Retrieval and Source Tracking

When code requests a capability, the catalog embeds provenance metadata:

```typescript
// Retrieve a model capability and inspect its source
import { modelCatalog } from '@maka/core';

const cap = await modelCatalog.getCapability('text-completion');
console.log(cap.capabilitySource); // 'provider-api' | 'static-catalog' | 'user-override' | 'unknown'

```

The `capabilitySource` field in [[`packages/core/src/model-catalog.ts`](https://github.com/apache/maka/blob/main/packages/core/src/model-catalog.ts)](https://github.com/apache/maka/blob/main/packages/core/src/model-catalog.ts) enables downstream policy decisions—some deployments may reject capabilities from unknown sources.

### Automatic Audit Attachment in Tool Runtime

The **Tool Runtime** ([`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts)) intercepts every tool call and generates an audit record containing:

- **capabilityId**: Unique identifier from the catalog
- **request/response payload**: Full input and output data
- **deterministic auditId**: Reproducible identifier for verification

```typescript
// The runtime automatically creates audit facts on every call
import { enqueueRunStore } from '@maka/runtime';

const result = await cap.call({ prompt: 'Explain audit logs' });

// Manual audit append for custom instrumentation
await enqueueRunStore('append run status audit', {
  kind: 'audit',
  capabilityId: cap.id,
  payload: result,
});

```

### Persistent Storage and Read Model

Audit facts land in `runtime.sqlite` within the workspace directory. The **Runtime Event Read Model** (`packages/runtime/src/runtime-event-read-model.ts) exposes a read-only projection for UIs and compliance tools:

| Feature | Implementation |
|--------|----------------|
| Storage format | SQLite per-workspace |
| Write semantics | Append-only, best-effort |
| Query interface | Read model with materialized views |
| Failure handling | Log and continue |

The **Session Manager** ([`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts)) links audit facts to active sessions, ensuring temporal correlation between capability use and session state.

---

## How Maka Recovers Client Capabilities

Client capabilities—file system access, sandboxed execution, secret retrieval—require explicit user consent. Maka preserves these grants across crashes through **audit-driven reconstruction**.

### The Client Capability Coordinator

The **Client Capability Coordinator** ([`packages/runtime-host/src/server/client-capability-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/client-capability-coordinator.ts)) monitors the Runtime Host for capability-binding events. On session resume, it:

1. Queries the audit log for previously-issued capability IDs
2. Re-instantiates corresponding **Capability Objects**
3. Validates that grants remain valid per policy

### Invocation Brokering and Validation

The **Client Capability Invocation Broker** (`packages/runtime-host/src/server/client-capability-invocation-broker.ts) mediates actual calls:

```typescript
// Recover client capabilities after a crash
import { HostClientCapabilityCoordinator } from '@maka/runtime-host';

const coordinator = new HostClientCapabilityCoordinator({
  workspacePath: '/path/to/workspace',
  recoveryMode: 'outcome_unknown', // reuse prior outcome if possible
});

// Handle an incoming tool call with audit-backed validation
coordinator.handleInvocation({
  kind: 'client.capability.call',
  capabilityId: 'file-read-123',
  args: { path: '/etc/hosts' },
}).then(reply => {
  // Reply contains either original audited result or fresh execution
  console.log('Recovered result:', reply);
});

```

The broker emits `client.capability.accepted` for valid, open capabilities and `client.capability.result` with error codes for closed or malformed requests.

### Recovery Modes for Deterministic Replay

The `recoveryMode` parameter controls behavior when replaying interrupted turns:

| Mode | Behavior |
|------|----------|
| `outcome_unknown` | Re-run operation, preserving audit trail |
| `outcome_success` | Return cached result from audit log |
| `outcome_failure` | Re-run with failure awareness |

This mechanism in [[`packages/runtime-host/src/server/root-turn-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/root-turn-coordinator.ts)](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/root-turn-coordinator.ts) guarantees deterministic resumption without user re-authentication.

---

## Key Source Files and Responsibilities

| Component | File Path | Responsibility |
|-----------|-----------|----------------|
| Model capability registry | [`packages/core/src/model-catalog.ts`](https://github.com/apache/maka/blob/main/packages/core/src/model-catalog.ts) | Define capabilities, track `capabilitySource` |
| Tool runtime instrumentation | [`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts) | Attach audit records to tool calls |
| Audit read projection | [`packages/runtime/src/runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-read-model.ts) | Materialize audit facts for UI/compliance |
| Session-audit binding | [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) | Correlate capabilities with session lifecycle |
| Client capability recovery | [`packages/runtime-host/src/server/client-capability-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/client-capability-coordinator.ts) | Reconstruct capabilities from audit log |
| Invocation validation | [`packages/runtime-host/src/server/client-capability-invocation-broker.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/client-capability-invocation-broker.ts) | Validate and route recovered capability calls |
| Turn coordination | [`packages/runtime-host/src/server/root-turn-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/root-turn-coordinator.ts) | Orchestrate recovery mode and replay |

---

## Summary

- **Model capability auditing** captures provider, payload, and provenance in an append-only SQLite log via the Tool Runtime and Model Catalog.
- **Client capability recovery** restores user-granted permissions without re-prompting, using the Client Capability Coordinator and Invocation Broker to validate and replay audited grants.
- **Best-effort writes** ensure auditing never blocks execution; failures are logged for post-hoc analysis.
- **Deterministic replay modes** (`outcome_unknown`, `outcome_success`) let deployments choose between faithful reconstruction and fresh execution.

---

## Frequently Asked Questions

### What happens if the audit log write fails during a tool call?

The system logs the failure and continues execution. Maka's audit system is intentionally best-effort to prevent capability unavailability due to storage issues. The turn completes normally, though the specific call lacks audit coverage.

### Can client capabilities be recovered on a different machine?

Yes, provided the workspace directory containing `runtime.sqlite` is available. The Client Capability Coordinator reads the audit log from the specified `workspacePath` and reconstructs capabilities identically. Cryptographic validation of capability grants prevents unauthorized replay.

### How does Maka distinguish model capabilities from client capabilities?

Model capabilities originate from AI providers and flow through the Model Catalog; they require no user consent. Client capabilities involve system resources (files, secrets, sandbox) and require explicit user grants tracked in the audit log. The runtime treats these as separate trust domains with different recovery semantics.

### Is the audit log tamper-evident?

The SQLite database uses append-only semantics with deterministic `auditId` generation, making detection of deletions or modifications straightforward through ID sequence analysis. Full cryptographic verification would require additional infrastructure not present in the core runtime.