Directory-as-ID: Scaling Module Discovery Without Configuration

Source: Dev.to

Introduction

In the previous volume, we explored the vision of an AI‑Perceivable world. Now, it’s time to go under the hood. The first technical pillar of the apcore protocol is a deceptively simple idea: Directory-as-ID.

In traditional microservices or modular architectures, a central registry, massive YAML configuration, or complex dependency‑injection container often becomes a bottleneck as the system grows from 10 modules to 1,000. Merge conflicts, naming collisions, and “Scaling Rot” are common pain points.

apcore solves this by making the file system the source of truth. In this tenth article, we’ll look at the algorithm behind Directory-as-ID and why it’s essential for scaling AI‑ready systems.

The Algorithm: From Path to Canonical ID

The principle is straightforward: the relative path of a module file is its unique identity.

If you have a module root directory (e.g., extensions/), apcore scans the files and applies a deterministic mapping:

1. Remove the Root

   extensions/executor/email/send.py → executor/email/send.py

2. Remove Extension

   executor/email/send.py → executor/email/send

3. Normalize Separators

   executor/email/send → executor.email.send   (The Canonical ID)

Why This Matters for AI

AI agents are highly sensitive to names. By using a hierarchical, directory‑based naming convention, you naturally create namespaces. An agent can quickly differentiate between executor.user.delete and admin.user.delete because the hierarchy provides context.

Case Study: Zero‑Config in apexe

apexe: AI‑fying the CLI Universe

apexe scans existing CLIs (e.g., git or docker) and wraps them into apcore modules. Running:

apexe scan git

generates a hierarchy of modules under ~/.apexe/modules/:

• git commit → cli.git.commit
• git push → cli.git.push

Because of Directory-as-ID, apexe doesn’t need to manage a database of IDs. It simply writes the files to the appropriate folders, and the apcore Registry “perceives” the entire CLI command tree instantly. This enables Dynamic Skill Discovery: installing a new CLI tool and scanning it makes the agent aware of it immediately, without any server restart.

Technical Rigor: Handling Multi‑Language Drift

A core challenge of a language‑agnostic standard is that different languages have different naming conventions (Python prefers snake_case, TypeScript prefers camelCase).

The apcore protocol defines strict ID Normalization Rules:

• Normalization: All IDs are converted to a canonical form (lowercase, snake_case) for the Registry.
• Language Mapping: Each SDK (Python, TypeScript, Rust) translates between the canonical ID and the local file name (e.g., SendEmail.ts maps to send_email).

This ensures that even in a polyglot enterprise, the AI agent sees a single, consistent address space.

Conclusion: Scale Is a Design Constraint

Directory-as-ID is more than a convenience; it’s a design constraint for the Agentic Era. It enables Zero‑Config Discovery, eliminates registry bottlenecks, and provides a natural namespace for AI perception.

In the next article, we’ll dive into the heart of the engine: The 11‑Step Execution Pipeline.

This is Article #10 of the apcore: Building the AI‑Perceivable World series.

GitHub: