{"slug": "language-agnostic-module-representation", "title": "Language Agnostic Module Representation", "summary": "A proposal for Language-Agnostic Module Representation (LAMP) introduces an intermediate artifact that captures software modularity before code generation, aiming to improve code structure from AI coding assistants. LAMP defines module boundaries, encapsulation, and contracts through a directory of Markdown files, enabling human review and constraining generation to honor modular intent.", "body_md": "A proposal for an intermediate representation that captures software modularity before code is generated.\n\n## 1. Overview\n\n### 1.1 Motivation\n\nAgentic coding assistants generate code that compiles and passes tests. Depending on the model and context size, the generated code often lacks coherent modular structure and code hygiene.\n\nThe artifacts that feed generation don't address modularity.\n\n- Requirements and tests describe behavior, not decomposition.\n- Design and tasks describe approach, not module contracts.\n\nLanguage-Agnostic Module rePresentation (LAMP) fills the gap with a reviewable artifact that commits to modular intent before code exists: what each module encapsulates and exposes, the capability contracts the agent must honor, and a modularity audit that gates generation rather than reviewing it afterward.\n\n### 1.2 What LAMP is\n\nLAMP sits between architectural component-level design and code. It captures a system's modular structure in a form reviewable before any implementation exists. The agent or human generating code is then constrained where it matters (module boundaries, encapsulation, observable contracts) and free where it doesn't (types, languages, data structures, concurrency). It also shrinks the context window, saving token costs.\n\nLAMP serves two goals:\n\n**Module Review:** a target for human review and modularity auditing before code changes.**Code Generation:** a contract the agent honors when producing code and tests.\n\nLAMP is part of a software development pipeline:\n\n```\nDESIGN\n   → decompose into modules around encapsulated decisions\nLAMP\n   → generate implementation honoring the contracts\nCODE\n```\n\nLAMP rests on four principles drawn from established modularity practice:\n\n**Information hiding.** Each module is organized around a design decision it encapsulates. Callers depend on the interface. The encapsulated decision can change without disturbing them.**Deep abstractions.** A module's value is proportional to how much implementation it hides behind how small an interface.**Decomposition by change axis.** Modules are drawn around what is likely to change, not around data structure or algorithm steps.**Stable contracts.** A module's interface is more stable than its implementation, and more stable than the requirements that motivated it.\n\n## 2. Document layout\n\nA LAMP artifact is a directory of Markdown files.\n\n```\nlamp/\n  capability.md        # capability registry\n  modules.md           # All module manifests\n```\n\n## A single file is the default because LAMP modules are small. When a system has many modules or capabilities and a single file grows unwieldy, split them across several files. Name a module file with a `module`\n\nprefix (e.g., `module-<family>.md`\n\n) to group related modules. Name a capability file with a `capability`\n\nprefix (e.g., `capability-<family>.md`\n\n).\n\n## 3. The module specification\n\nThe module manifest answers three questions: *what does this module hide, what does it offer, what does it need?* Each module is a top-level section in `modules.md`\n\n, with these subsections in order. All are required.\n\n```\n# Module: <name>\n\n## Encapsulates\nThe design decision or complexity this module hides. State it in\ncaller irrelevant terms.\n\n## Provider Capabilities\nMarkdown links into the capability registry in `capability.md`, one per\nline.\n\n  - [issue-session](capability.md#capability-issue-session)\n  - [resolve-session](capability.md#capability-resolve-session)\n  - [revoke-session](capability.md#capability-revoke-session)\n\n## Consuming Capabilities\nMarkdown links into the capability registry, one per line.\nDependencies are on capabilities, never on other modules directly.\n\n  - [monotonic-clock](capability.md#capability-monotonic-clock)\n  - [opaque-bytes-storage](capability.md#capability-opaque-bytes-storage)\n```\n\n### 3.1 Authoring rules\n\n**Encapsulation is named in caller-irrelevant terms.**\"How sessions are stored, expired, and revoked\" — good. \"Uses Redis with TTL\" — leaks.** Capability names don't leak implementation.**`flush_to_disk()`\n\nleaks;`commit()`\n\ndoesn't.`cache_evict()`\n\nleaks;`forget(handle)`\n\ndoesn't.**Dependencies are on capabilities, not modules.** Say*opaque-bytes-storage*, not*PostgresStore*.**No types, signatures, or language idioms.**`Promise<Result<Session, Error>>`\n\nis implementation.\n\n## 4. The capability specification\n\nCapabilities live in `capability.md`\n\n's registry. Each is declared once. The heading format is fixed. Module manifests link to capabilities by anchor, so the heading is part of the contract.\n\n```\n### capability: <verb-phrase-name>\n\nDescription: one sentence on what this accomplishes for a caller.\n\nInputs: Description of inputs.\n\nOutputs: Description of outputs.\n\nRequires: what must hold for the capability call to be valid.\n\nGuarantees: what is true on successful completion.\n\nFailure modes: caller meaningful error categories.\n\nProviders: List one or more providers who implement the capability. The capability registry and module manifests form a navigable graph in both directions.\n  - [<module-name>](modules.md#module-<module-name>)\n  - [<module-name>](modules.md#module-<module-name>)\n```\n\n### 4.1 Authoring rules for capabilities\n\n**Verb-phrased.**\"issue\", \"resolve\", \"find-by-prefix\" — verbs. Nouns like`session()`\n\nare smells; usually a leaked data structure.**Inputs and outputs by role, not type.**\"subject\" and \"handle\", not`string`\n\nand`UUID`\n\n.**Failure modes are caller-meaningful.**\"not-authorized\" tells a caller something. \"RedisTimeoutException\" leaks.\n\n## 5. A worked example\n\nFrom a user requirement:\n\nAs a service, I want to issue, validate, and revoke session handles so I can recognize returning callers without rechecking credentials on every call.\n\nAcceptance criteria:\n\n- Given a valid subject, when I issue a handle, resolving it returns the original subject.\n- Given a revoked handle, resolving it returns invalid.\n- Given an expired handle, resolving it returns invalid.\n- Two handles for the same subject are distinct and unguessable.\n\nLAMP excerpts:\n\n`capability.md`\n\ncapability registry:\n\n```\n### capability: issue-session\n\nDescription: produces an opaque handle representing an authenticated subject.\nInputs:\n  - subject: the principal the session represents\n  - claims: caller-supplied attributes\nOutputs:\n  - handle: opaque reference\nGuarantees:\n  - The handle is valid until revoked or expired.\n  - The handle is distinct from every previously-issued handle.\n  - The handle is not guessable from prior handles.\nFailure modes:\n  - capacity-exhausted\nProviders:\n  - [SessionStore](modules.md#module-sessionstore)\n\n### capability: revoke-session\n\nDescription: invalidates an issued handle.\nInputs:\n  - handle: an opaque reference previously returned by issue-session\nGuarantees:\n  - After this returns, resolve-session(handle) returns invalid.\n  - Subsequent revoke-session(handle) calls are accepted with no further effect.\nProviders:\n  - [SessionStore](modules.md#module-sessionstore)\n```\n\n`modules.md`\n\n(SessionStore section):\n\n```\n# Module: SessionStore\n\n## Encapsulates\nHow sessions are stored, expired, and revoked. Whether storage is\nin-memory, in a database, or encoded into the handle itself is hidden.\nWhether revocation is push-based or pull-based is hidden.\n\n## Provider Capabilities\n- [issue-session](capability.md#capability-issue-session)\n- [resolve-session](capability.md#capability-resolve-session)\n- [revoke-session](capability.md#capability-revoke-session)\n\n## Consuming Capabilities\n- [monotonic-clock](capability.md#capability-monotonic-clock)\n- [opaque-bytes-storage](capability.md#capability-opaque-bytes-storage)\n```\n\n", "url": "https://wpnews.pro/news/language-agnostic-module-representation", "canonical_source": "https://about.a3rn.com/blog/lamp-language-agnostic-module-representation/", "published_at": "2026-07-16 22:48:21+00:00", "updated_at": "2026-07-16 23:17:36.549565+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents"], "entities": ["LAMP"], "alternates": {"html": "https://wpnews.pro/news/language-agnostic-module-representation", "markdown": "https://wpnews.pro/news/language-agnostic-module-representation.md", "text": "https://wpnews.pro/news/language-agnostic-module-representation.txt", "jsonld": "https://wpnews.pro/news/language-agnostic-module-representation.jsonld"}}