ADR-0016: Core-only VC specification and implementation

• Status: Accepted
• Date: 2026-09-08
• Updated: 2026-09-18
• Owners: VC maintainers
• Supersedes: product, protocol, and multi-package architecture decisions archived in Git history

Context

The repository grew from generic VC/VP primitives into credential families, applications, exchange protocols, status infrastructure, deployment code, and runtime integrations. Those experiments were useful but obscured the public API and coupled unrelated release and security lifecycles.

The repository now needs one responsibility: specify and implement reusable Midnight VC/VP semantics without selecting a product, transport, DID method, wallet, or deployment.

Decision

This repository owns:

• the normative, protocol-independent VC/VP specification under spec/;
• canonical credential and presentation data structures;
• a bounded TypeScript model and validation API;
• generic Compact VC/VP primitives and curated generated bindings;
• positive and negative conformance vectors; and
• the build, test, and release tooling for those surfaces.

The original supported public release graph contained:

• @midnight-ntwrk/credential-model;
• @midnight-ntwrk/credential-compact.

ADR-0017 adds the flat, protocol-independent @midnight-ntwrk/credential-did-midnight extension while preserving the exclusions below.

The core defines reusable data structures and cryptographic composition primitives. Complete issuer, holder, and verifier ceremonies belong to the credential-family or application repository that selects their policy and protocol. The core conformance manifest lists implemented, vectored operations; it is not a backlog of unsupported future protocols.

The repository does not own:

• concrete credential families, schemas, applications, or business contracts;
• OID4VC, DIDComm, HTTP, QR, DApp Connector, or wallet integrations;
• general DID-adapter frameworks, trust registries, or status services;
• deployment assembly, runtime discovery, or product proving artifacts; or
• rendering, localization, transliteration, and framework-specific UI.

Package-local tests, conformance vectors, and clean packed consumers provide the executable evidence. Runnable examples and use cases belong in consumer repositories.

Credential families and applications use published versions or immutable package artifacts. Cross-repository source imports, workspace links, generated trees, and submodule dependencies are prohibited.

Normative behavior changes require matching conformance vectors. The current breaking reset is 0.2.0-rc1; historical prereleases may be deprecated but must not be unpublished.

Consequences

• Protocol and product repositories can evolve on independent release trains.
• The default gate needs no Docker, LFS hydration, wallet, or application scenario.
• Deleted experiments remain discoverable through Git history and issues, without continuing to define the active architecture.
• A new public package requires evidence of a genuinely independent lifecycle, consumers, ownership, and release need before this decision is revised.