Core concepts
Facet
A named, versioned collection of text assets defined by a manifest. What the author creates, what gets published, and what gets installed.
Facet archive
The published, self-contained artifact stored in the registry. Contains the manifest and all text assets. The transport form between publish and install.
Adapter
An AI coding tool abstraction (OpenCode, Claude Code, Codex). The layer between facet assets and the tool’s storage and configuration conventions.
MCP server
A code asset providing tool capabilities via the Model Context Protocol. Published independently, versioned independently, resolved at install time.
Asset types
Skill
Text asset following the Agent Skills spec.
Agent
Text asset following the Agent Skills spec.
Command
Text asset following the Agent Skills spec.
Server
MCP server reference. Code, not text.
Asset management
| Term | Definition |
|---|---|
| Managed asset | Installed by a facet, tracked in the lockfile and . |
| Unmanaged asset | Exists in an adapter directory but not connected to any facet. User-created or kept from an uninstalled facet. |
Integrity
Hashes
Hashes
| Term | Definition |
|---|---|
| Canonical fingerprint | SHA-256 of the uncompressed inner tar (content_integrity). Recorded in the lockfile, cache sidecar, and build manifest. Trust anchor for verification. |
| Transport hash | SHA-256 of the uploaded .facet tarball (content_hash). Download-time transit check only. Never persisted to the lockfile. |
| API surface hash | SHA-256 of an MCP server’s tool declarations. Detects structural breaking changes. |
| OCI digest | Immutable content hash for a container image. Pins ref-mode servers in the lockfile. |
Verification
Verification
| Term | Definition |
|---|---|
| Cache sidecar | cache-integrity.json stored alongside cached content. Canonical fingerprint + per-asset hashes. |
| Cache self-audit | Re-verification of cached content against its sidecar on every materialization. Evicts on mismatch. |
| Integrity confirmation | Registry metadata request verifying content matches the published canonical fingerprint. Required when creating a lockfile entry. Fails offline. |
Install pipeline
| Term | Definition |
|---|---|
| Install delta | Additions (user’s specifier verbatim) + removals (bare names). facet install produces an empty delta. |
| Structural discriminator | Additions never trust the lockfile for version resolution; reproductions do. |
| Install receipt | Machine-local record under $FACET_DIR/receipts/ tracking materialized state per project. Drives offline drift removal. |
| Tri-write | Atomic commit: facets.json + facets.lock + receipt written together. Failure leaves all three unchanged. |
Execution modes
| Term | Definition |
|---|---|
| Source-mode | Server source code published to the facets registry, run via managed runtime. |
| Ref-mode | Server references an OCI container image in an external registry. |
Always hyphenate:
source-mode, ref-mode. Do not use OCI-mode or unhyphenated forms.Version constraints
| Term | Definition |
|---|---|
| Floor constraint | Minimum acceptable version for source-mode servers. CLI resolves to the latest at or above the floor. |
| Floor version | The specific minimum version value (e.g., "1.0.0"). |
Lifecycle
| Stage | What happens |
|---|---|
| Authoring | Author creates a manifest and text assets locally. |
| Publishing | Registry assembles the archive, computes hashes. Version is immutable once published. |
| Installing | Plan/commit pipeline: resolve, verify, materialize, tri-write. |
| Upgrading | Diffs surfaced to consumer. API surface changes flagged. (Future) |
| Uninstalling | Assets removed via delta pipeline. Receipt updated. |
| Running | Text in context. Servers running via MCP. |