12 APM Manifest Lockfile Model

Status

Accepted

Context

APM dependencies must be both human-readable in authored configuration and machine-reproducible in resolved state. Two file roles are needed:

• A human-authored manifest (apm.yml) that declares desired package dependencies using repository and tag references.
• A machine-resolved lockfile (apm.lock.yaml) that records the exact resolved state: tag, commit SHA, tree hashes, and per-file SHA-256 hashes.

Git tags are repository-level refs, not subdirectory-level refs. Because apm-registry stores many independently releasable primitives and packages within a single repository, a namespaced tag convention is required to allow independent versioning of sub-paths.

Using mutable branch refs (e.g. main) for production APM dependencies is not safe because the resolved commit can change without a corresponding lockfile update, breaking reproducibility guarantees.

Decision

APM dependencies use immutable Git tag refs as the declared dependency form in apm.yml. The lockfile apm.lock.yaml records the resolved commit SHA and per-file hashes for all installed files.

Tag namespace convention

Tags within apm-registry follow this namespacing:

refs/tags/catalog/v<semver>
refs/tags/packages/<package-name>/v<semver>
refs/tags/primitives/<primitive-type>/<primitive-name>/v<semver>

Manifest form (apm.yml)

dependencies:
  - id: calab.agent.github-pr-reviewer
    source:
      repo: calab-ai/apm-registry
      ref: refs/tags/primitives/agents/github-pr-reviewer/v1.2.0
      path: primitives/agents/github-pr-reviewer
    targets:
      - path: .github/copilot/agents/github-pr-reviewer

Lockfile form (apm.lock.yaml)

resolved:
  - id: calab.agent.github-pr-reviewer
    repo: calab-ai/apm-registry
    ref: refs/tags/primitives/agents/github-pr-reviewer/v1.2.0
    commit: 8f3c2a1...
    path: primitives/agents/github-pr-reviewer
    files:
      - source: agent.md
        target: .github/copilot/agents/github-pr-reviewer/agent.md
        sha256: 9b7f...

CI validation

gh calab apm validate --ci must fail on:

• branch refs in apm.yml (non-immutable)
• lockfile entries with no matching tag in apm.yml
• drift between lockfile hashes and files present on disk
• files not tracked in the lockfile that match managed path patterns

Consequences

• Reproducible installs are guaranteed at the per-file hash level.
• Dependency declarations in apm.yml remain readable and auditable by humans.
• Independent versioning of primitives and packages within apm-registry is supported through the namespaced tag convention.
• Production installs that use branch refs are rejected by CI validation.
• The lockfile must be committed alongside the manifest and generated files; omitting it should be treated as a CI failure.