# Package identity

Source: https://tapid.dev/docs/concepts/package-identity

How names, versions, registries, and artifact digests fit together.

A package request is not an identity. `acme-widget@^2.4` describes a name and a version range, but it does not identify the code that a project will install.

## Follow one request to one artifact

A useful package decision binds the request to all of these values:

| Term              | What it answers                        | Example                 |
| ----------------- | -------------------------------------- | ----------------------- |
| Package name      | Which package did the request name?    | `acme-widget`           |
| Version range     | Which releases are acceptable?         | `^2.4`                  |
| Resolved release  | Which exact version was selected?      | `2.7.1`                 |
| Registry identity | Which registry object supplied it?     | `npmjs.org/acme-widget` |
| Artifact digest   | Which exact bytes will be used?        | `sha512-...`            |
| Lockfile entry    | What must a later operation reproduce? | `tapid.lock` record     |

The range is a constraint. The resolved release is a selection. The artifact digest identifies the bytes. The registry identity prevents the same name and version from silently referring to different registry objects.

## Why the lockfile matters

A later offline or frozen operation should not resolve the request again. It should validate the lockfile's manifest digest, package identities, tree digests, and verified store content before activating managed `node_modules`.

That behavior is implemented for populated projects. A registry-backed install and replay print:

```text
Installed 1 package(s)
Replayed lockfile: 1 package(s)
```

The lockfile schema records the registry-qualified package identity, exact version, artifact integrity, integrity provenance, verified tree digest, dependency edges, and root selections needed for replay.

## What is implemented and what is planned

The current CLI resolves and installs a bounded npm-compatible subset, writes schema-7 ordinary locks, schema-8 imported locks and schema-9 derived locks, and reads supported older registry-only locks, and supports deterministic replay from verified store trees. Explicit scoped private routing and npm aliases are implemented. Alias import names stay separate from actual registry identity; workspace sources stay separate from verified registry artifacts. Registry-wide publisher provenance, complete npm compatibility and a package-evidence policy engine remain planned or incomplete. Read [Compatibility](https://tapid.dev/docs-markdown/compatibility/content.md).

Read [Evidence and policy](https://tapid.dev/docs-markdown/concepts/evidence-and-policy/content.md) to see how an exact identity would feed a decision, then return to [Getting started](https://tapid.dev/docs-markdown/getting-started/content.md) for the supported replay command and current status.