# What Is the Managed Dependency Storage Authority in Apache Maka?

> Understand the managed dependency storage authority in Apache Maka. Learn how it securely owns, protects, and serves Node.js module caches for safe concurrent access.

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

---

**The managed dependency storage authority in Apache Maka is a runtime component that exclusively owns, protects, and serves persistent caches of hermetic Node.js module environments, ensuring safe concurrent access through file-based locking and SQLite-backed receipt bookkeeping.**

Apache Maka utilizes a sophisticated storage layer to maintain reproducible builds of dependency environments. The managed dependency storage authority, implemented in the `@maka/storage` package, functions as the durable cache layer for hermetic Node.js module builds. This component guarantees that only one process writes to a given storage root while providing deterministic identity hashing and automatic garbage collection.

## Core Responsibilities

The authority manages the complete lifecycle of cached dependency environments through six primary responsibilities defined in [`packages/storage/src/managed-dependency-environment.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/managed-dependency-environment.ts).

### Exclusive Ownership and File Locking

The authority guarantees single-process write access to any given storage root using a file-based lock mechanism. Upon initialization, it creates a `dependency-environment-authority-v1.lock` file that prevents concurrent mutation of the cache directory. According to lines 7019-7044 of the source, this lock ensures that even if multiple Maka processes target the same storage root, only one can perform write operations such as importing new environments or running garbage collection.

### Receipt Bookkeeping with SQLite

Every cached environment receives a cryptographic receipt stored in an SQLite database named `dependency-environment-authority-v1.sqlite`. As implemented in lines 4040-4066, this database maintains the canonical record of what environments exist, their hashes, and their last access times. The receipt system enables the authority to validate cache integrity and detect tampering or corruption without re-reading the entire environment contents.

### Cache Quota and Garbage Collection

The authority enforces configurable byte quotas to prevent unbounded disk usage. Lines 12376-12429 implement the garbage collection algorithm that evicts the least-recently-used environments when the cache exceeds its quota. The GC only removes environments that are not actively leased, ensuring that running builds never lose their dependencies mid-execution.

### Lease Lifecycle Management

Access to cached environments occurs through lease objects. When code requests a dependency environment, the authority returns a `ManagedDependencyEnvironmentLease` (lines 6050-6074) containing the path to the `node_modules` directory. Releasing the lease signals that the consumer no longer needs the environment, potentially triggering garbage collection if quota pressure exists. This reference-counting pattern prevents the deletion of actively used dependencies.

### Crash Recovery and Consistency

On startup, the authority performs validation routines to ensure storage consistency. Lines 8555-8575 handle the cleanup of orphaned staging directories and removal of partially published artifacts from interrupted writes. By verifying receipts against actual directory contents, the authority maintains atomicity guarantees even after process crashes or power failures.

### Deterministic Environment Identity

Each environment receives a unique `environmentId` computed from SHA-256 hashes of the manifest, lockfile, toolchain metadata, and producer configuration (lines 4048-4082). This deterministic identity ensures that identical dependency trees always map to the same cache entry, enabling reproducible builds across different machines and CI runs.

## Implementation Architecture

The authority is instantiated through the `createManagedDependencyEnvironmentAuthority` factory function exported by `@maka/storage`. This function accepts a `storageRoot` path and a producer configuration object that defines how to construct dependency environments when cache misses occur.

The primary implementation resides in [`packages/storage/src/managed-dependency-environment.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/managed-dependency-environment.ts), which defines the `ManagedDependencyEnvironmentAuthority` class. This module coordinates with [`packages/storage/src/root-authority.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/root-authority.ts) for generic storage-root abstractions used across Maka's storage subsystems.

## Working with the Authority

The following examples demonstrate creating an authority, acquiring a lease for a specific environment, and proper cleanup patterns.

### Creating the Authority

Initialize the authority once per storage root with a producer configuration:

```typescript
import { createManagedDependencyEnvironmentAuthority } from '@maka/storage';
import { mkdir } from 'fs/promises';
import { join } from 'path';

const dummyProducer = {
  capability: createManagedDependencyEnvironmentProducerCapability(
    'sha256:deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef',
  ),
  packageManagerName: 'npm',
  packageManagerVersion: '9.8.0',
  nodeRuntime: {
    version: '18.17.0',
    abi: 'node',
    platform: process.platform,
    arch: process.arch,
  },
  async provision(input) {
    await mkdir(join(input.outputRoot, 'node_modules'), { recursive: true });
  },
};

const storageRoot = '/tmp/maka-managed-deps';
const authority = await createManagedDependencyEnvironmentAuthority({
  storageRoot,
  producer: dummyProducer,
});

```

### Acquiring an Environment Lease

Compute the environment identity and acquire a lease to access the cached dependencies:

```typescript
import { computeManagedDependencyEnvironmentIdentity } from '@maka/storage';

const manifestBytes = Buffer.from('{ "name": "example", "version": "1.0.0" }');
const lockfileBytes = Buffer.from('{}');

const identity = computeManagedDependencyEnvironmentIdentity({
  manifestPath: 'package.json',
  manifestBytes,
  lockfilePath: 'package-lock.json',
  lockfileBytes,
  packageManagerName: 'npm',
  packageManagerVersion: '9.8.0',
  nodeVersion: process.version,
  nodeAbi: 'node',
  platform: process.platform,
  arch: process.arch,
  producerRuntimeIdentitySha256:
    'sha256:deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef',
  producerPolicyIdentitySha256:
    'sha256:feedfacefeedfacefeedfacefeedfacefeedfacefeedfacefeedfacefeedface',
  policyVersion: 'managed_dependency_environment_v1',
});

const lease = await authority.acquire(identity, {
  manifestBytes,
  lockfileBytes,
});

console.log('Dependency root:', lease.dependencyRoot);

```

### Releasing Resources

Always release leases when finished and close the authority during shutdown:

```typescript
await lease.release();
await authority.close();

```

## Key Source Files

The managed dependency storage authority implementation spans several critical files in the Apache Maka repository:

- **[`packages/storage/src/managed-dependency-environment.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/managed-dependency-environment.ts)** — Core implementation containing the authority class, receipt handling, lease logic, garbage collection, and crash recovery routines.

- **[`packages/storage/src/root-authority.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/root-authority.ts)** — Provides the generic storage-root abstraction used by the managed dependency authority and other storage subsystems.

- **[`docs/architecture/managed-dependency-storage-authority-v1.zh-CN.md`](https://github.com/apache/maka/blob/main/docs/architecture/managed-dependency-storage-authority-v1.zh-CN.md)** — Architectural overview documenting design goals and invariants (Chinese language).

- **`scripts/release-cli-runtime-host-diagnostics.mjs`** — Production usage example demonstrating storage authority acquisition for runtime diagnostics.

- **`scripts/ci-workflow-policy.test.mjs`** — Test suite exercising crash-recovery paths and consistency validation.

## Summary

- The **managed dependency storage authority** is the exclusive owner of hermetic Node.js module caches in Apache Maka, preventing concurrent write conflicts through file-based locking.
- It maintains **cryptographic receipts** in an SQLite database to track environment integrity and access patterns.
- **Garbage collection** enforces configurable quotas by evicting least-recently-used environments that hold no active leases.
- **Lease lifecycle management** provides safe, reference-counted access to cached dependencies while preventing mid-build deletions.
- **Deterministic identity hashing** ensures reproducible cache keys based on manifest, lockfile, and toolchain configurations.
- **Crash recovery** validates receipts and cleans up orphaned staging directories on startup.

## Frequently Asked Questions

### How does the managed dependency storage authority prevent concurrent write conflicts?

The authority creates a `dependency-environment-authority-v1.lock` file in the storage root upon initialization. As implemented in lines 7019-7044 of [`managed-dependency-environment.ts`](https://github.com/apache/maka/blob/main/managed-dependency-environment.ts), this file lock guarantees that only one process can perform write operations—including environment imports and garbage collection—at any given time. Additional processes block or fail gracefully depending on the lock acquisition policy.

### What database format does the authority use for receipt bookkeeping?

The authority uses **SQLite** to store cryptographic receipts. Lines 4040-4066 define the schema and operations for the `dependency-environment-authority-v1.sqlite` database, which records each environment's hash, metadata, and last access timestamp. This approach provides atomic transactions and efficient querying for garbage collection and consistency checks.

### How does the authority handle crash recovery?

On startup, the authority executes validation routines defined in lines 8555-8575 to detect and repair inconsistent states. It verifies that receipt entries match actual directory contents, removes partially written staging directories from interrupted publications, and reclaims storage from orphaned files. These measures ensure the cache remains consistent even after sudden process termination or system failures.

### What identifies a unique managed dependency environment?

Each environment receives a deterministic `environmentId` generated from SHA-256 hashes of the package manifest, lockfile, Node.js runtime version, platform, architecture, and producer configuration (lines 4048-4082). This comprehensive hashing strategy guarantees that identical dependency trees and toolchains always resolve to the same cache entry, enabling reproducible builds across different machines.