How Maka Audits Model Capabilities and Recovers Client Capabilities

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) 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:

// 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) 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) 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

// 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) 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) 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:

// 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) 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	Define capabilities, track capabilitySource
Tool runtime instrumentation	packages/runtime/src/tool-runtime.ts	Attach audit records to tool calls
Audit read projection	packages/runtime/src/runtime-event-read-model.ts	Materialize audit facts for UI/compliance
Session-audit binding	packages/runtime/src/session-manager.ts	Correlate capabilities with session lifecycle
Client capability recovery	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	Validate and route recovered capability calls
Turn coordination	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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}