Skip to content
Almathal Handbook

Manifest

Accepted

A Manifest is the JSON descriptor for an Adapter or Module. It is the contract between the Library and the Composer: everything the Composer needs to decide whether and how to use a building block lives in the Manifest.

Manifests are the data structures the platform reasons over. Without Manifests, the libraries would just be heaps of code; with Manifests, they become a queryable, machine-readable inventory of trusted building blocks.

What a Manifest Declares

Every Manifest declares the following sections (formal schema in Schemas → Adapter Manifest v1):

  1. Identity — slug, UUID, version, display name, language slice, upstream source
  2. Category and Capabilities — what kind of building block this is and what it provides
  3. Interface Contracts — what API surface it exposes for the Stitcher to generate against
  4. Compatibility — what other Adapters, Modules, scaffolders, and runtime versions it works with
  5. Dependencies — what it needs to install and run
  6. Provenance — license, source repository, security history, audit trail
  7. Integration Hints — imports, build-tool snippets, typical usage patterns, common pitfalls
  8. Lifecycle — status (active, deprecated, etc.), maintenance signals, successor reference

The Manifest schema is versioned. v1 is the current schema; future versions will add fields backward-compatibly or bump the major version with a migration tool.

The Two Identifier Model

Every Manifest carries both the human-readable slug and the immutable UUID:

{
  "manifest_version": "adapter-manifest/v1",
  "identity": {
    "id": "adapter:java/spring-data-jpa",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "version": "3.2.4",
    "display_name": "Spring Data JPA",
    "language": "java",
    "slice": "java-backend"
  }
}

See ID Scheme for the full treatment of why both exist.

Where Manifests Live

Manifests are stored in a central platform-owned registry, not in the upstream library’s repository. Reasons:

  • No upstream coordination required
  • Quality control stays with the platform team
  • Manifests cannot be accidentally corrupted by changes to generated codebases
  • The registry can be backed up, versioned, and audited as a single artifact

This is recorded in ADR-0016: Central Manifest Registry.

Future versions of Almathal may contribute Manifests upstream to library maintainers who want to own them, but for v1 and the immediate roadmap, the platform owns all Manifests.

Adapter Manifest vs Module Manifest

The two schemas share most fields but differ in some:

FieldAdapter ManifestModule Manifest
sourcePoints to Maven, npm, PyPI, Docker Hubnull for platform-composed; upstream project for curated
constituent_adaptersAbsentList of Adapters this Module composes
configuration_surfaceAdapter-level config keysModule-level config (database connection, secrets, etc.)
internal_seamsAbsentList of Seams filled during Module composition

Schemas are detailed at Schemas → Adapter Manifest v1 and Schemas → Module Manifest v1.

How Manifests Are Authored

Manifests follow the Manifest Authoring process:

  • Early stage (first ~30 Manifests per slice): LLM-drafted, human-directed. The platform team directs the LLM tightly to ensure quality and consistency.
  • Mature stage: LLM-drafted from research, human-reviewed before admission. Higher throughput, still trusted.
  • Future: For low-risk Manifest updates (minor version bumps of well-established Adapters), agent-ratified with post-hoc human sampling.

Provenance and security fields are always verified mechanically (license scan, CVE scan, signature verification) regardless of who drafted the Manifest.

How Manifests Are Used

The Composer reads Manifests during:

  • Spec Resolution — to know what each Slot’s default and alternatives are
  • Compatibility Validation — to check the declared compatibility matrix
  • Seam Validation — to confirm declared Capabilities cover Seam requirements
  • Stitcher handoff — to provide integration hints and concrete patterns the Stitcher generates against

The Stitcher reads Manifests for the Adapters declared in each Seam’s must_use_adapters, using the integration and interface_contracts sections to know what code to generate.

The Build Validator references Manifests during verification, particularly for any Adapter-specific lint rules or test patterns.

Manifest Versioning

A Manifest’s own version (the identity.version field) matches the underlying library’s version for Adapters, or follows platform-managed semver for Modules.

The schema of the Manifest format is separately versioned (manifest_version: "adapter-manifest/v1"). When the schema evolves:

  • Backward-compatible additions stay within v1
  • Breaking changes bump to v2 with a migration tool

Old Manifests continue to be readable; the registry stores all versions historically.

What Manifests Don’t Contain

Equally important. A Manifest does not contain:

  • The library’s source code (that’s at the upstream location)
  • Cached artifacts (those live in the optional verified artifact mirror)
  • User-specific data (Manifests are public to anyone with platform access)
  • Runtime state (Manifests are static descriptors)
  • Implementation details of how the Adapter would be assembled into a particular app (that’s in the Archetype Spec)

The Manifest is metadata. It is the small, structured layer that turns a library into a usable building block in the Almathal system.