# Apache Maka Artifact Storage Layout and Metadata Contract: A Complete Guide

> Discover the Apache Maka artifact storage layout and metadata contract. Learn how Maka enforces access policies and keeps filesystem paths hidden for secure model artifact management.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: architecture
- Published: 2026-09-02

---

**Apache Maka stores every model output as an artifact under a configurable root directory, using a strict TypeScript metadata contract defined in [`packages/core/src/artifacts.ts`](https://github.com/apache/maka/blob/main/packages/core/src/artifacts.ts) that enforces source-based access policies while keeping absolute filesystem paths hidden from renderers.**

In Apache Maka, every piece of data generated by tools, models, or user uploads is treated as an **artifact**. The Runtime host manages a dedicated artifact root on disk, but never exposes absolute paths to the renderer. Instead, components reference artifacts through a **relative path** stored in the metadata record, ensuring sandboxed security while enabling complex research workflows.

## The Artifact Metadata Contract

The core contract is defined in [`packages/core/src/artifacts.ts`](https://github.com/apache/maka/blob/main/packages/core/src/artifacts.ts) and consists of three primary TypeScript interfaces that govern how artifacts are described, stored, and secured.

### Core Types

The system distinguishes between immutable descriptions and physical storage records:

- **`ArtifactDescriptor`** – An immutable definition containing the artifact's canonical ID, session and turn associations, timestamps, name, kind, size, MIME type, source, and status.
- **`ArtifactRecord`** – Extends `ArtifactDescriptor` to add the `relativePath` field (the location under the artifact root) and an optional `deepResearchRole` for durable workspaces.
- **`ArtifactSourcePolicy`** – An internal type that governs user permissions including deletion rights, visibility, and cross-session readability.

### Key Metadata Fields

Every artifact record contains fields that enforce contract integrity:

- **`id`** – A globally unique identifier validated by `isCanonicalArtifactEntityId()`.
- **`sessionId`** – Groups artifacts belonging to the same user session into isolated directories.
- **`turnId`** – A bounded Runtime turn key (`isArtifactTurnKey`) that segments storage by conversation turn without being used directly as a filesystem path.
- **`relativePath`** – The path relative to the artifact root where binary data persists. The Runtime resolves this to an absolute path only during read operations.
- **`kind`** – Restricted to the `ARTIFACT_KINDS` enum: `'file' | 'diff' | 'html' | 'image' | 'pdf'`.
- **`source`** – One of the enumerated `ARTIFACT_SOURCES` (e.g., `tool_result`, `deep_research`, `user_upload`). This determines the policy applied via `ArtifactSourcePolicy`.
- **`status`** – Either `'live'` or `'deleted'`, enabling soft-delete semantics without immediate data removal.
- **`sizeBytes`** and **`mimeType`** – Used for admission control; for example, images exceeding 2 MiB are rejected by `resolveArtifactImagePreview()`.

## Physical Storage Layout on Disk

Apache Maka implements a hierarchical directory structure that mirrors the logical session and turn model while maintaining strict isolation between components.

### Artifact Root and Directory Hierarchy

The storage layout follows a four-level nested structure:

1. **Artifact Root** – A base directory configured by the Runtime host (commonly `~/.maka/artifacts/`).
2. **Session Sub-directory** – Each `sessionId` receives its own folder, ensuring data isolation between concurrent users.
3. **Turn-level Sub-directory** – Within each session, artifacts are organized by `turnId`, creating temporal boundaries for each conversation exchange.
4. **Artifact Files** – Individual artifacts are stored as plain files derived from their `id` and `name` properties.

Because the contract stores only `relativePath`, renderers can reference artifacts without learning the absolute filesystem location. All disk access flows through the core API functions `readArtifact()` and `saveArtifact()`, which validate policies before performing I/O operations.

## Source-Based Policy Enforcement

Access control in Apache Maka is determined by the artifact's `source` field rather than manual permission lists. The system enforces three primary policy dimensions through utility functions in [`packages/core/src/artifacts.ts`](https://github.com/apache/maka/blob/main/packages/core/src/artifacts.ts):

- **`canUserDeleteArtifact(record)`** – Returns `true` only when the source's `userDeletable` flag is set. Tool-generated results typically prohibit deletion while user uploads allow it.
- **`isArtifactUserVisible(record)`** – Determines UI visibility based on the `userVisible` policy flag.
- **`isArtifactSharedSessionReadable(record)`** – Controls whether other sessions can read the artifact when the source's `sharedReadable` flag is enabled.

These functions ensure that, for example, artifacts from `tool_result` sources remain visible to users but immutable, whereas `user_upload` sources grant both visibility and deletion rights.

## Working with Artifacts in Code

The following example demonstrates creating an artifact descriptor, validating preview eligibility, and persisting the record with policy enforcement:

```typescript
import {
  ARTIFACT_KINDS,
  ArtifactDescriptor,
  ArtifactRecord,
  resolveArtifactImagePreview,
  isArtifactUserVisible,
} from '@maka/core/artifacts';

// Define the artifact after tool execution
const descriptor: ArtifactDescriptor = {
  id: 'a1b2c3',
  sessionId: 'sess-123',
  turnId: 'turn-456',
  createdAt: Date.now(),
  name: 'screenshot.png',
  kind: 'image',
  sizeBytes: 1_800_000,
  mimeType: 'image/png',
  source: 'tool_result',
  status: 'live',
};

// Validate image preview eligibility (≤ 2 MiB limit)
const preview = resolveArtifactImagePreview({
  name: descriptor.name,
  kind: descriptor.kind,
  mimeType: descriptor.mimeType,
  sizeBytes: descriptor.sizeBytes,
});

if (preview.kind === 'image') {
  // Construct the relative path following the storage layout convention
  const relativePath = `sess-123/turn-456/${descriptor.id}-${descriptor.name}`;
  
  const record: ArtifactRecord = { 
    ...descriptor, 
    relativePath,
    deepResearchRole: 'evidence' // Optional for Deep Research workspaces
  };
  
  // Persist through the core API; Runtime resolves absolute path internally
  await core.saveArtifact(record, fileBuffer);
}

// Later, verify visibility before rendering
if (isArtifactUserVisible(record)) {
  // Safe to render thumbnail or download link
}

```

## Summary

- Apache Maka persists all data as **artifacts** under a configurable root directory with a strict hierarchical layout (root → session → turn → file).
- The **metadata contract** in [`packages/core/src/artifacts.ts`](https://github.com/apache/maka/blob/main/packages/core/src/artifacts.ts) defines `ArtifactDescriptor`, `ArtifactRecord`, and `ArtifactSourcePolicy` types.
- Security relies on **relative paths** (`relativePath`) rather than absolute filesystem exposure, with the Runtime host resolving paths only during controlled read operations.
- **Source-based policies** control deletion, visibility, and sharing through the `ARTIFACT_SOURCES` enumeration and functions like `canUserDeleteArtifact()`.
- Size and MIME type validation (e.g., the 2 MiB image limit) occurs through `resolveArtifactImagePreview()` before storage admission.

## Frequently Asked Questions

### How does Apache Maka prevent renderers from accessing arbitrary filesystem paths?

Apache Maka never transmits absolute paths to the renderer layer. Instead, the metadata contract stores only a **relative path** relative to the artifact root. When a read request occurs, the Runtime host validates the request against source policies and resolves the absolute path internally. This sandboxing ensures renderers can only access artifacts explicitly created through the `saveArtifact()` API.

### What is the `deepResearchRole` field in `ArtifactRecord`?

The optional `deepResearchRole` field extends `ArtifactRecord` for **Deep Research workspaces**, allowing artifacts to be tagged with specific roles within a durable research session. This enables the system to distinguish between evidence, drafts, and final outputs in long-running research workflows, as documented in [`docs/deep-research-durable-workspace.md`](https://github.com/apache/maka/blob/main/docs/deep-research-durable-workspace.md).

### Which artifact sources allow users to delete their own files?

Deletion rights depend entirely on the **source policy** defined in `ARTIFACT_SOURCES`. According to the implementation in [`packages/core/src/artifacts.ts`](https://github.com/apache/maka/blob/main/packages/core/src/artifacts.ts), sources like `user_upload` typically set `userDeletable: true`, while `tool_result` sources mark artifacts as immutable (`userDeletable: false`). The `canUserDeleteArtifact()` function checks this flag before permitting any deletion operation.

### Are there file size limits for artifact storage?

Yes. While the storage system itself accepts arbitrary sizes, the **preview system** enforces admission limits. For example, `resolveArtifactImagePreview()` rejects images larger than 2 MiB or with unknown MIME types, preventing the renderer from attempting to preview oversized files while still allowing storage of the raw artifact.