What Is the Managed Dependency Storage Authority in Apache Maka?

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.

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, which defines the ManagedDependencyEnvironmentAuthority class. This module coordinates with 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:

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:

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:

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 — Core implementation containing the authority class, receipt handling, lease logic, garbage collection, and crash recovery routines.

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

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