Skip to main content

​
Current behavior

The install pipeline splits into plan (pure routing) and commit (resolution, integrity, materialization, writes). facet add, facet remove, and facet install converge on the same commit phase — they differ only in the they produce.
The Install Pipeline page has the full normative flow with diagrams and detailed integrity chain documentation.

​
The pipeline

1

Plan

Build the delta. No network, no lockfile, no cache.
2

Parse sources

Registry (name@1.*), GitHub (github:owner/repo#ref), git URLs, local paths. Caret/tilde/comparator ranges are rejected.
3

Resolve versions

Additions always re-resolve non-exact specifiers. Reproductions trust the lockfile when satisfying; re-resolve only absent or stale entries.
4

Cache + integrity

Cache keyed by <name>@<version>. Hits are re-hashed against the . Tampered content is evicted. Lockfile pins are string-compared; new entries require .
5

Materialize

Assets written to every selected adapter. Skip-if-identical. Inverse ops journaled for rollback.
6

Drift removal

The drives cleanup. No cache or network needed.
7

Tri-write

facets.json + facets.lock + receipt written together on success. Failure rolls back everything.
The manifest is never written ahead of the install. A failed facet add leaves the project exactly as it was.

​
Lockfile shape

Per facet: {source, version, integrity, assets}. The source is tagged:
KindFieldsNotes
registryregistryVersion in the entry’s version field
giturl, commitRef stays in facets.json
localpathResolved local path
Adapter-agnostic — the same asset set is applied to every selected adapter.

​
Frozen lockfile

--frozen-lockfile makes the lockfile authoritative.
Additions or removals are rejected immediately. Only facet install can run frozen.
The system checks bidirectional consistency before touching anything: every manifest facet must have a satisfying lockfile entry, the lockfile must not pin anything the manifest dropped, and git/local sources must match their locked provenance.
BehaviorFrozen mode
Version resolutionForbidden
Archive downloadAllowed (reproduction)
Integrity verificationRequired for every facet, including local
Drift removal + receiptRuns
Lockfile / manifest writeNever

​
Open-beta target (future)

Not yet implemented. The sections below describe planned behavior.

​
Server resolution

Two resolution paths will be added:
Query the registry for the latest version at or above the floor constraint. Download, verify, compute API surface hash.
Resolve the OCI image tag to a digest. Pin the digest. Compute API surface hash. If the reference is already a digest, use it as-is.
Servers are terminal — no transitive dependencies.

​
Upgrade

facet upgrade will check for newer versions, surface text diffs and API surface changes, and let the consumer choose which updates to apply.

​
Remove

facet remove deletes a facet’s assets via the delta-based pipeline. Assets are removed using the install receipt — no cache or network needed. Manifest, lockfile, and receipt are written together on success.

​
Not in the install flow

  • Text asset resolution — text is in the archive. No install-time fetching.
  • Transitive server resolution — servers are terminal.
  • Disk layout — determined by adapters, not the specification.