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

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

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

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 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.

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, 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.

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